|
| 1 | +.. index:: integrator |
| 2 | + |
| 3 | +Integrator object |
| 4 | +================= |
| 5 | + |
| 6 | +The :code:`PyQInt` class is the low-level numerical integrator used internally |
| 7 | +throughout the ``pyqint`` package. It provides efficient evaluation of |
| 8 | +Gaussian-type orbital (GTO) and contracted Gaussian function (CGF) integrals |
| 9 | +via a C++ backend with optional OpenMP parallelization. |
| 10 | + |
| 11 | +Most users do **not** interact with :code:`PyQInt` directly. Instead, higher- |
| 12 | +level routines construct and manage an integrator instance internally. Direct |
| 13 | +use of :code:`PyQInt` is intended for advanced users who need fine-grained |
| 14 | +control over integral evaluation or wish to experiment with custom workflows. |
| 15 | + |
| 16 | +Overview |
| 17 | +-------- |
| 18 | + |
| 19 | +The integrator implements core quantum-chemical building blocks, including: |
| 20 | + |
| 21 | +* Overlap integrals |
| 22 | +* Kinetic energy integrals |
| 23 | +* Nuclear attraction integrals |
| 24 | +* Two-electron (electron–repulsion) integrals |
| 25 | +* First derivatives with respect to nuclear coordinates |
| 26 | +* Grid-based evaluation of basis functions and molecular orbitals |
| 27 | + |
| 28 | +The implementation is optimized for repeated evaluation and makes use of |
| 29 | +internal caching where possible. |
| 30 | + |
| 31 | +Creating an Integrator |
| 32 | +---------------------- |
| 33 | + |
| 34 | +An integrator instance is created by specifying limits on angular momentum |
| 35 | +and the maximum order of the Boys function: |
| 36 | + |
| 37 | +.. code-block:: python |
| 38 | +
|
| 39 | + from pyqint import PyQInt |
| 40 | +
|
| 41 | + qint = PyQInt(lmax=4, nu_max=12) |
| 42 | +
|
| 43 | +The parameters control internal cache sizes and directly affect both memory |
| 44 | +usage and performance. Reusing a single integrator instance is recommended |
| 45 | +when evaluating many integrals. |
| 46 | + |
| 47 | +Typical Usage |
| 48 | +------------- |
| 49 | + |
| 50 | +Most integrals are evaluated using contracted Gaussian functions (CGFs): |
| 51 | + |
| 52 | +.. code-block:: python |
| 53 | +
|
| 54 | + S = qint.overlap(cgf1, cgf2) |
| 55 | + T = qint.kinetic(cgf1, cgf2) |
| 56 | + V = qint.nuclear(cgf1, cgf2, rc, zc) |
| 57 | +
|
| 58 | +Two-electron integrals can be computed either individually or in batches: |
| 59 | + |
| 60 | +.. code-block:: python |
| 61 | +
|
| 62 | + eri = qint.repulsion(cgf1, cgf2, cgf3, cgf4) |
| 63 | +
|
| 64 | +For performance-critical workflows, the integrator provides routines that |
| 65 | +build full matrices and tensors in a single call using OpenMP: |
| 66 | + |
| 67 | +.. code-block:: python |
| 68 | +
|
| 69 | + S, T, V, tei = qint.build_integrals_openmp(cgfs, nuclei) |
| 70 | +
|
| 71 | +Parallel Execution |
| 72 | +------------------ |
| 73 | + |
| 74 | +If OpenMP support was available at build time, the integrator will |
| 75 | +automatically parallelize suitable workloads. The number of threads is |
| 76 | +controlled via standard OpenMP environment variables such as ``OMP_NUM_THREADS``. |
| 77 | + |
| 78 | +The current thread count can be queried at runtime: |
| 79 | + |
| 80 | +.. code-block:: python |
| 81 | +
|
| 82 | + nthreads = qint.get_num_threads() |
| 83 | +
|
| 84 | +Build Information |
| 85 | +----------------- |
| 86 | + |
| 87 | +For diagnostic and reproducibility purposes, the integrator exposes |
| 88 | +build-time information: |
| 89 | + |
| 90 | +.. code-block:: python |
| 91 | +
|
| 92 | + info = qint.get_compile_info() |
| 93 | +
|
| 94 | +The returned dictionary includes compiler details, OpenMP availability, |
| 95 | +and compilation date and time. |
| 96 | + |
| 97 | +Grid-Based Evaluation |
| 98 | +--------------------- |
| 99 | + |
| 100 | +The integrator also supports evaluation of basis functions, molecular |
| 101 | +orbitals, and their gradients on three-dimensional grids: |
| 102 | + |
| 103 | +.. code-block:: python |
| 104 | +
|
| 105 | + grid = qint.build_rectgrid3d(-5.0, 5.0, 50) |
| 106 | + values = qint.plot_wavefunction(grid, coeff, cgfs) |
| 107 | +
|
| 108 | +These routines are primarily intended for visualization and analysis. |
| 109 | + |
| 110 | +Notes |
| 111 | +----- |
| 112 | + |
| 113 | +* The :code:`PyQInt` object is **not thread-safe** across Python threads. |
| 114 | +* Creating multiple integrators increases memory usage due to internal caches. |
| 115 | +* Most users should rely on higher-level interfaces provided by ``pyqint``. |
0 commit comments