qrunch.chemistry.integral_builders.lazy_standard_integrals

Lazy four-center two-body electron repulsion integrals that defer computation until needed.

Classes

LazyRestrictedTwoBodyElectronRepulsionIntegrals

Lazy wrapper around the standard four-center two-body integral builder.

LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

Lazy wrapper around the standard four-center two-body integral builder (unrestricted).
class LazyRestrictedTwoBodyElectronRepulsionIntegrals

Bases: RestrictedTwoBodyElectronRepulsionIntegralsProtocol, LazyIntegralsProtocol

Lazy wrapper around the standard four-center two-body integral builder.

This class stores the ingredients needed to compute two-body electron repulsion integrals (molecular orbitals, molecular configuration, and an integral builder) and only materializes the integrals when they are first accessed via force_computation() or active_space().

__init__(molecular_orbitals: RestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration, integral_builder: TwoBodyElectronRepulsionIntegralBuilder) → None

Initialize lazy integrals with the ingredients for deferred computation.

Parameters:
Return type:

None

active_space(active_orbitals: tuple[int, ...], reduction_tolerance: float = 1e-10) → RestrictedTwoBodyElectronRepulsionIntegralsProtocol

Return the active space integrals by computing only the needed subset.

Instead of materializing the full tensor and extracting a sub-block, this method computes integrals directly for the requested active orbitals.

Parameters:

  • active_orbitals (tuple[int, ...]) – Active orbital indices.

  • reduction_tolerance (float) – Relative threshold for pruning (unused for dense integrals).

Return type:

RestrictedTwoBodyElectronRepulsionIntegralsProtocol

property alpha_alpha: ndarray[tuple[Any, ...], dtype[float64]]

Return the alpha-alpha integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

property beta_alpha: ndarray[tuple[Any, ...], dtype[float64]]

Return the beta-alpha integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

property beta_beta: ndarray[tuple[Any, ...], dtype[float64]]

Return the beta-beta integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

classmethod decode(data: dict[str, Any]) → LazyRestrictedTwoBodyElectronRepulsionIntegrals

Decode a dictionary to an instance.

Parameters:

data (dict[str, Any]) – The dictionary representation.

Return type:

LazyRestrictedTwoBodyElectronRepulsionIntegrals

einsum(component: Literal['aa', 'bb', 'mixed'], einsum_str: str, *operands: ndarray[tuple[Any, ...], dtype[float64]], index_slices: tuple[slice, slice, slice, slice] | None = None, **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Perform einsum (not supported on the lazy wrapper).

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • einsum_str (str) – The einsum string.

  • *operands (ndarray[tuple[Any, ...], dtype[float64]]) – Additional ndarrays.

  • index_slices (tuple[slice, slice, slice, slice] | None) – Optional slices to apply to the 4-index tensor.

  • **kwargs (Any) – Passed through to np.einsum.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:

dict[str, Any]

force_computation() → RestrictedTwoBodyElectronRepulsionIntegralsProtocol

Force computation of the full integral tensor and return it.

Return type:

RestrictedTwoBodyElectronRepulsionIntegralsProtocol

internal_contracted_left(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two leftmost indices: \(g_{iipq} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_contracted_middle(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two middle indices: \(g_{piiq} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_contracted_right(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two rightmost indices: \(g_{pqii} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_trace_contracted_middle(component: Literal['aa', 'bb', 'mixed'], orbital_range: slice) → float

Compute \(\sum_{p,i} g_{piip}\) for the given orbital range.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • orbital_range (slice) – Slice selecting orbital indices for both the free and contracted pairs.

Return type:

float

internal_trace_contracted_right(component: Literal['aa', 'bb', 'mixed'], orbital_range: slice) → float

Compute \(\sum_{p,i} g_{ppii}\) for the given orbital range.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • orbital_range (slice) – Slice selecting orbital indices for both the free and contracted pairs.

Return type:

float

property is_restricted: Literal[True]

Return True since this is restricted.

property molecular_configuration: MolecularConfiguration

Return the stored molecular configuration.

property molecular_orbitals: RestrictedMolecularOrbitals

Return the stored molecular orbitals.

property number_of_orbitals: int

Return the number of orbitals.

rotate(rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) → LazyRestrictedTwoBodyElectronRepulsionIntegrals

Rotate the integrals lazily by composing the rotation into the stored MO coefficients.

Mathematically, rotating the materialised integrals by \(R\) is equivalent to replacing the MO coefficient matrix \(C\) with \(C R\), since the AO to MO transformation is linear in the MO coefficients. We therefore avoid materialising the full \(N^4\) tensor and simply return a new lazy instance whose stored MO coefficients have been multiplied by the rotation matrix on the right.

Parameters:

rotation_matrices (tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) – Tuple containing a single 2-dimensional square rotation matrix. Should match the structure given by the output of rotation_matrix_structure().

Return type:

LazyRestrictedTwoBodyElectronRepulsionIntegrals

rotation_matrix_structure() → list[RotationBlockDefinition]

Get information on which blocks should be non-zero in the rotation matrix.

Return type:

list[RotationBlockDefinition]

property shape: tuple[int, int, int, int]

Return the shape of the 4-index tensor.

two_body_energy(number_of_occupied_orbitals: int) → float

Compute the restricted two_electron Hartree-Fock energy.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

Parameters:

number_of_occupied_orbitals (int) – The number of occupied alpha orbitals.

Return type:

float

class LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

Bases: UnrestrictedTwoBodyElectronRepulsionIntegralsProtocol, LazyIntegralsProtocol

Lazy wrapper around the standard four-center two-body integral builder (unrestricted).

This class stores the ingredients needed to compute two-body electron repulsion integrals (molecular orbitals, molecular configuration, and an integral builder) and only materializes the integrals when they are first accessed via force_computation() or active_space().

__init__(molecular_orbitals: UnrestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration, integral_builder: TwoBodyElectronRepulsionIntegralBuilder) → None

Initialize lazy integrals with the ingredients for deferred computation.

Parameters:
Return type:

None

active_space(active_orbitals: tuple[int, ...], reduction_tolerance: float = 1e-10) → UnrestrictedTwoBodyElectronRepulsionIntegralsProtocol

Return the active space integrals by computing only the needed subset.

Parameters:

  • active_orbitals (tuple[int, ...]) – Active orbital indices.

  • reduction_tolerance (float) – Relative threshold for pruning (unused for dense integrals).

Return type:

UnrestrictedTwoBodyElectronRepulsionIntegralsProtocol

property alpha_alpha: ndarray[tuple[Any, ...], dtype[float64]]

Return the alpha-alpha integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

property beta_alpha: ndarray[tuple[Any, ...], dtype[float64]]

Return the beta-alpha integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

property beta_beta: ndarray[tuple[Any, ...], dtype[float64]]

Return the beta-beta integrals, materializing if needed.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

classmethod decode(data: dict[str, Any]) → LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

Decode a dictionary to an instance.

Parameters:

data (dict[str, Any]) – The dictionary representation.

Return type:

LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

einsum(component: Literal['aa', 'bb', 'mixed'], einsum_str: str, *operands: ndarray[tuple[Any, ...], dtype[float64]], index_slices: tuple[slice, slice, slice, slice] | None = None, **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Perform einsum (not supported on the lazy wrapper).

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • einsum_str (str) – The einsum string.

  • *operands (ndarray[tuple[Any, ...], dtype[float64]]) – Additional ndarrays.

  • index_slices (tuple[slice, slice, slice, slice] | None) – Optional slices to apply to the 4-index tensor.

  • **kwargs (Any) – Passed through to np.einsum.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:

dict[str, Any]

force_computation() → UnrestrictedTwoBodyElectronRepulsionIntegralsProtocol

Force computation of the full integral tensor and return it.

Return type:

UnrestrictedTwoBodyElectronRepulsionIntegralsProtocol

internal_contracted_left(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two leftmost indices: \(g_{iipq} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_contracted_middle(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two middle indices: \(g_{piiq} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_contracted_right(component: Literal['aa', 'bb', 'mixed'], active_range: slice, inactive_range: slice) → ndarray[tuple[Any, ...], dtype[float64]]

Contract over the two rightmost indices: \(g_{pqii} \to g_{pq}\).

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • active_range (slice) – Slice selecting active MO columns for the free pair (p, q).

  • inactive_range (slice) – Slice selecting inactive MO columns for the contracted pair (i).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

internal_trace_contracted_middle(component: Literal['aa', 'bb', 'mixed'], orbital_range: slice) → float

Compute \(\sum_{p,i} g_{piip}\) for the given orbital range and component.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • orbital_range (slice) – Slice selecting orbital indices for both the free and contracted pairs.

Return type:

float

internal_trace_contracted_right(component: Literal['aa', 'bb', 'mixed'], orbital_range: slice) → float

Compute \(\sum_{p,i} g_{ppii}\) for the given orbital range and component.

Parameters:

  • component (Literal['aa', 'bb', 'mixed']) – Which integral component to use “aa”, “bb”, or “mixed”.

  • orbital_range (slice) – Slice selecting orbital indices for both the free and contracted pairs.

Return type:

float

property is_restricted: Literal[False]

Return False since this is unrestricted.

property molecular_configuration: MolecularConfiguration

Return the stored molecular configuration.

property molecular_orbitals: UnrestrictedMolecularOrbitals

Return the stored molecular orbitals.

property number_of_orbitals: int

Return the number of orbitals.

rotate(rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) → LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

Rotate the integrals lazily by composing the rotations into the stored MO coefficients.

Mathematically, rotating the materialised integrals by \((R_\alpha, R_\beta)\) is equivalent to replacing the MO coefficient matrices \(C_\alpha\) and \(C_\beta\) with \(C_\alpha R_\alpha\) and \(C_\beta R_\beta\), since the AO to MO transformation is linear in the MO coefficients. We therefore avoid materialising the full \(N^4\) tensor and return a new lazy instance whose stored MO coefficients have been multiplied by the rotation matrices on the right.

Parameters:

rotation_matrices (tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) – Tuple containing two 2-dimensional square rotation matrices (R_alpha, R_beta). Should match the structure given by the output of rotation_matrix_structure().

Return type:

LazyUnrestrictedTwoBodyElectronRepulsionIntegrals

rotation_matrix_structure() → list[RotationBlockDefinition]

Get information on which blocks should be non-zero in the rotation matrix.

Return type:

list[RotationBlockDefinition]

property shape: tuple[int, int, int, int]

Return the shape of the 4-index tensor.

two_body_energy(number_of_occupied_alpha_orbitals: int, number_of_occupied_beta_orbitals: int) → float

Compute the unrestricted two-electron Hartree-Fock energy.

Not implemented on the lazy wrapper since it encourages inefficient access patterns.

Parameters:

  • number_of_occupied_alpha_orbitals (int) – The number of occupied alpha orbitals.

  • number_of_occupied_beta_orbitals (int) – The number of occupied beta orbitals.

Return type:

float