qrunch.chemistry.integral_builders.tensor_hyper_contraction_integral_builder

Module for Tensor Hyper Contraction integral builders.

Functions

`cholesky_performance_optimized_estimate_memory_usage`(...)	Estimate memory usage (in GB) for performance optimized version to build the E matrix from RI tensor.
`generate_x`(weights, ao_value_mo, ...)	Generate the X matrix given grid weights and basis function values.
`memory_requirement_in_gb_for_full_eri`(nao)	Calculate the memory requirement in GB for doing THC with the full 4-index electron repulsion integrals (ERI).
`pivoted_cholesky`(matrix, max_rank[, tolerance])	Compute pivoted Cholesky decomposition of a symmetric positive semidefinite matrix.

Classes

`GridData`	Numerical Grid Data.
`GridLevel`	Defines grid resolution levels for numerical integration in PySCF.
`RestrictedTensorHyperContractionIntegralsBuilder`	Build integrals using Tensor Hyper Contraction (THC) approximation.
`TensorHyperContractionIntegralsBuilder`	Build integrals using Tensor Hyper Contraction (THC) approximation.
`UnrestrictedTensorHyperContractionIntegralsBuilder`	Build unrestricted two-body integrals using Tensor Hyper Contraction (THC) approximation.

class GridData

Bases: object

Numerical Grid Data.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

coords – The grid coordinate shape (N, 3)
weights – The grid weights shape (N)

__init__(coords: ndarray[Any, dtype[float64]], weights: ndarray[Any, dtype[float64]]) → None

Parameters:

coords (ndarray[Any, dtype[float64]])
weights (ndarray[Any, dtype[float64]])

Return type:

None

coords: ndarray[Any, dtype[float64]]

weights: ndarray[Any, dtype[float64]]

class GridLevel

Bases: Enum

Defines grid resolution levels for numerical integration in PySCF.

The value of the enum is used to select the number of radial grid shells and the number of angular (spherical) points per shell.

LEVEL0 through LEVEL9 goes from fast to accurate. LEVEL9 is the default.

LEVEL0 = (2, 14): 2 radial shells and 14 angular points per shell.

LEVEL1 = (4, 14): 4 radial shells and 14 angular points per shell.

LEVEL2 = (4, 26): 4 radial shells and 26 angular points per shell.

LEVEL3 = (6, 26): 6 radial shells and 26 angular points per shell.

LEVEL4 = (6, 38): 6 radial shells and 38 angular points per shell.

LEVEL5 = (8, 38): 8 radial shells and 38 angular points per shell.

LEVEL6 = (8, 50): 8 radial shells and 50 angular points per shell.

LEVEL7 = (10, 50): 10 radial shells and 50 angular points per shell.

LEVEL8 = (10, 74): 10 radial shells and 74 angular points per shell.

LEVEL9 = (12, 74): 12 radial shells and 74 angular points per shell.

class RestrictedTensorHyperContractionIntegralsBuilder

Bases: object

Build integrals using Tensor Hyper Contraction (THC) approximation.

__init__(*, use_ri: bool = True, use_grid_point_pruning: bool = True, pseudoinverse_tolerance: float = 1e-08, grid_level: GridLevel = GridLevel.LEVEL9, maximum_memory_in_gb: float = 10.0, aux_basis: BasisSet | None = None) → None

Initialize the Restricted Tensor Hyper Contraction (THC) integral builder.

Parameters:

use_ri (bool) – If True, use the 3 index RI tensor (via Cholesky decomposition) to compute THC matrices. Otherwise, use the conventional 4 index integrals.
use_grid_point_pruning (bool) – Use grid point pruning.
pseudoinverse_tolerance (float) – The tolerance acts as a cutoff threshold constructing the pseudoinverse.
grid_level (GridLevel) – The numerical grid level.
maximum_memory_in_gb (float) – The maximum memory in GB.
aux_basis (BasisSet | None) – The auxiliary density-fitting RI basis set. Defaults to the Weigend-Coulomb-fit basis.

Return type:

None

calculate_integrals(molecular_orbitals: RestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration) → RestrictedTensorHyperContractionIntegrals

Compute tensor hypercontraction (THC) integrals for a given molecule.

Parameters:

molecular_orbitals (RestrictedMolecularOrbitals)
molecular_configuration (MolecularConfiguration)

Return type:

RestrictedTensorHyperContractionIntegrals

class TensorHyperContractionIntegralsBuilder

Bases: TwoBodyElectronRepulsionIntegralBuilderProtocol

Build integrals using Tensor Hyper Contraction (THC) approximation.

__init__(*, use_ri: bool = True, use_grid_point_pruning: bool = True, pseudoinverse_tolerance: float = 1e-08, grid_level: GridLevel = GridLevel.LEVEL9, maximum_memory_in_gb: float = 10.0, aux_basis: BasisSet | None = None) → None

Initialize the Tensor Hyper Contraction (THC) integral builder.

Parameters:

use_ri (bool) – If True, use the 3 index RI tensor (via Cholesky decomposition) to compute THC matrices. Otherwise, use the conventional 4 index integrals.
use_grid_point_pruning (bool) – Use grid point pruning.
pseudoinverse_tolerance (float) – The tolerance acts as a cutoff threshold constructing the pseudoinverse.
grid_level (GridLevel) – The numerical grid level.
maximum_memory_in_gb (float) – The maximum memory in GB.
aux_basis (BasisSet | None) – The auxiliary density-fitting RI basis set. Defaults to the Weigend-Coulomb-fit basis.

Return type:

None

calculate_integrals(molecular_orbitals: UnrestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration) → UnrestrictedTensorHyperContractionIntegrals

calculate_integrals(molecular_orbitals: RestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration) → RestrictedTensorHyperContractionIntegrals

Compute tensor hyper-contraction (THC) integrals for a given molecule.

Parameters:

molecular_orbitals – The Molecular Orbitals.
molecular_configuration – The molecular configuration.

class UnrestrictedTensorHyperContractionIntegralsBuilder

Bases: object

Build unrestricted two-body integrals using Tensor Hyper Contraction (THC) approximation.

__init__(*, use_ri: bool = True, use_grid_point_pruning: bool = True, pseudoinverse_tolerance: float = 1e-08, grid_level: GridLevel = GridLevel.LEVEL9, maximum_memory_in_gb: float = 10.0, aux_basis: BasisSet | None = None) → None

Initialize the Unrestricted Tensor Hyper Contraction (THC) integral builder.

Parameters:

use_ri (bool) – If True, use the 3 index RI tensor (via Cholesky decomposition) to compute THC matrices. Otherwise, use the conventional 4 index integrals.
use_grid_point_pruning (bool) – Use grid point pruning.
pseudoinverse_tolerance (float) – The tolerance acts as a cutoff threshold constructing the pseudoinverse.
grid_level (GridLevel) – The numerical grid level.
maximum_memory_in_gb (float) – The maximum memory in GB.
aux_basis (BasisSet | None) – The auxiliary density-fitting RI basis set. Defaults to the Weigend-Coulomb-fit basis.

Return type:

None

calculate_integrals(molecular_orbitals: UnrestrictedMolecularOrbitals, molecular_configuration: MolecularConfiguration) → UnrestrictedTensorHyperContractionIntegrals

Compute tensor hypercontraction (THC) integrals for a given molecule.

Parameters:

molecular_orbitals (UnrestrictedMolecularOrbitals)
molecular_configuration (MolecularConfiguration)

Return type:

UnrestrictedTensorHyperContractionIntegrals

cholesky_performance_optimized_estimate_memory_usage(nao: int, naux: int, n_grids: int) → float

Estimate memory usage (in GB) for performance optimized version to build the E matrix from RI tensor.

Parameters:

nao (int) – Number of atomic orbitals.
naux (int) – Number of auxiliary functions.
n_grids (int) – Number of grid points.

Return type:

float

generate_x(weights: ndarray[Any, dtype[float64]], ao_value_mo: ndarray[Any, dtype[float64]], number_of_orbitals: int) → ndarray[Any, dtype[float64]]

Generate the X matrix given grid weights and basis function values.

This method creates a scaling factor from the grid weights and multiplies it with the basis (or MO) function values.

Parameters:

weights (ndarray[Any, dtype[float64]]) – The grid weights reshaped as a column vector.
ao_value_mo (ndarray[Any, dtype[float64]]) – The values of the basis (or MO) functions on the grid.
number_of_orbitals (int) – The number of atomic orbitals.

Return type:

ndarray[Any, dtype[float64]]

memory_requirement_in_gb_for_full_eri(nao: int) → float

Calculate the memory requirement in GB for doing THC with the full 4-index electron repulsion integrals (ERI).

Parameters:: nao (int) – Number of atomic orbitals.
Return type:: float

pivoted_cholesky(matrix: ndarray[Any, dtype[float64]], max_rank: int, tolerance: float = 1e-08) → list[int]

Compute pivoted Cholesky decomposition of a symmetric positive semidefinite matrix.

Print per-iteration residual trace and pivot value. At the end, print total trace error.

Parameters:

matrix (ndarray[Any, dtype[float64]]) – Symmetric positive semidefinite matrix to decompose.
max_rank (int) – max rank of the pivots
tolerance (float) – Threshold to terminate the decomposition.

Raises:

ValueError – If the input matrix is not square or not symmetric.

Return type:

list[int]