occ::ints::ESPEvaluator< T > Class Template Reference

High-level ESP integral evaluator. More...

#include <esp.h>

Public Types
using	Mat3N = Eigen::Matrix<T, 3, Eigen::Dynamic>
using	MatRM = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>

Public Member Functions
	ESPEvaluator (const T *boys_table)
	Construct evaluator with Boys function table.
	~ESPEvaluator ()
	ESPEvaluator (const ESPEvaluator &)=delete
ESPEvaluator &	operator= (const ESPEvaluator &)=delete
	ESPEvaluator (ESPEvaluator &&) noexcept
ESPEvaluator &	operator= (ESPEvaluator &&) noexcept
size_t	add_shell_pair (int la, int lb, int na_prim, int nb_prim, const T *exponents_a, const T *exponents_b, const T *coeffs_a, const T *coeffs_b, const T *A, const T *B)
	Add a shell pair and precompute its E-matrices (Cartesian) Returns index for later evaluation.
size_t	add_shell_pair (int la, int lb, int na_prim, int nb_prim, const T *exponents_a, const T *exponents_b, const T *coeffs_a, const T *coeffs_b, const T *A, const T *B, bool spherical)
	Add a shell pair with option for spherical harmonics.
void	evaluate (size_t shell_idx, const Eigen::Ref< const Mat3N > &C, Eigen::Ref< MatRM > integrals, Eigen::Ref< MatRM > workspace, T omega=T(0))
	Evaluate ESP integrals for a precomputed shell pair (Eigen interface).
void	evaluate_soa (size_t shell_idx, const T *x, const T *y, const T *z, int npts, T *V, int ldv, T omega=T(0)) const
	Structure-of-arrays evaluation, vectorised over points.
void	evaluate_soa_contract (size_t shell_idx, const T *x, const T *y, const T *z, int npts, const T *F, T *G, int ld, int bf_p, int bf_q, bool both, T omega=T(0)) const
	The pair's integrals contracted as they are formed, for seminumerical exchange: with V as from evaluate_soa, G[(bf_q + b) * ld + i] -= sum_a F[(bf_p + a) * ld + i] V_ab(i) and, when both, G[(bf_p + a) * ld + i] -= sum_b F[(bf_q + b) * ld + i] V_ab(i) (a over the pair's first shell, b its second).
void	resize_derivative_pairs (size_t n)
	Shell pairs for centre derivatives (seminumerical exchange gradients), the same shells as add_shell_pair: resize_derivative_pairs(n) once, then set_shell_pair_derivative for each idx < n (distinct indices may be set concurrently).
void	set_shell_pair_derivative (size_t idx, int la, int lb, int na_prim, int nb_prim, const T *exponents_a, const T *exponents_b, const T *coeffs_a, const T *coeffs_b, const T *A, const T *B, bool spherical)
void	evaluate_soa_value_and_derivative_contraction (size_t idx, const T *x, const T *y, const T *z, int npts, T *A, int lda, const T *W, int ldw, int ncentres, T *out, T omega=T(0)) const
	One pass over a derivative pair giving both its integrals and their centre derivatives contracted with per-point weights: A[ab * lda + i] = (a b | 1/|r - x_i|) (nab rows, as evaluate_soa) out[c] += sum_i sum_ab W[ab * ldw + i] d/dc A_ab(x_i) c = A_x, A_y, A_z (and B_x, B_y, B_z when ncentres == 2).
void	resize_hessian_pairs (size_t n)
	Shell pairs for second derivatives (seminumerical exchange Hessians), set like the derivative pairs: resize_hessian_pairs(n) once, then set_shell_pair_hessian for each idx < n (distinct indices may be set concurrently).
void	set_shell_pair_hessian (size_t idx, int la, int lb, int na_prim, int nb_prim, const T *exponents_a, const T *exponents_b, const T *coeffs_a, const T *coeffs_b, const T *A, const T *B, bool spherical)
void	evaluate_soa_hessian (size_t idx, const T *x, const T *y, const T *z, int npts, T *V, int ldv, const T *W, int ldw, T *out, T omega=T(0)) const
	One pass over a Hessian pair, point-fastest like evaluate_soa: V[(k * nab + ab) * ldv + i], k = 0 the integrals (a b | 1/|r - x_i|), 1..3 their d/dA_{x,y,z}, 4..6 d/dB_{x,y,z}; and, unless W is null, second derivatives contracted with per-point weights, out[k] += sum_i sum_ab W[ab * ldw + i] d2/dc_k (a b | ...), 21 values: AA (xx, xy, xz, yy, yz, zz), AB (A_d B_e at 3 d + e), BB (as AA).
size_t	workspace_size (size_t shell_idx, int npts) const
	Get required workspace size for a shell pair.
void	evaluate_overlap (size_t shell_idx, T *integrals)
	Evaluate overlap integrals for a precomputed shell pair.
int	nab (size_t shell_idx) const
	Get number of basis function pairs for a shell pair.
int	nherm (size_t shell_idx) const
	Get number of Hermite Gaussians for a shell pair (workspace cols needed).
std::pair< int, int >	angular_momenta (size_t shell_idx) const
	Get angular momenta for a shell pair.
void	clear ()
	Clear all precomputed shell pairs.
size_t	num_shell_pairs () const
	Number of precomputed shell pairs.
bool	is_spherical (size_t shell_idx) const
	Check if a shell pair uses spherical harmonics.
std::array< T, 3 >	pair_center (size_t shell_idx) const
	Get the effective center of a shell pair (overlap region) Based on the most diffuse primitive combination.
T	pair_extent (size_t shell_idx) const
	Get the extent of a shell pair (radius where pair density < 1e-12) Based on the most diffuse primitive combination.
T	pair_estimate (size_t shell_idx) const
	Grid-point-independent upper bound on this pair's ESP integrals, sum_prim |2 pi / p * c_a * c_b * exp(-mu R_AB^2)|, i.e.
std::array< T, 2 >	pair_far_estimate (size_t shell_idx) const
	Far-field form of the same bound, {q1, spread}: at a point C with R = |C - pair_center| > spread the pair's ESP integrals are at most q1 / (R - spread) (each primitive's F_0(T) <= sqrt(pi/T)/2).

Static Public Attributes
static constexpr int	soa_padding = 32
	Point counts passed to evaluate_soa must be a multiple of this.

Detailed Description

template<typename T>
class occ::ints::ESPEvaluator< T >

High-level ESP integral evaluator.

This class manages precomputed shell pair data and workspace buffers for efficient evaluation of ESP integrals over many grid points.

Usage: ESPEvaluator<double> esp(boys_table); esp.add_shell_pair(la, lb, na_prim, nb_prim, ...); esp.evaluate(shell_idx, grid_points, integrals, workspace);

Member Typedef Documentation

Mat3N

template<typename T>

using occ::ints::ESPEvaluator< T >::Mat3N = Eigen::Matrix<T, 3, Eigen::Dynamic>

MatRM

template<typename T>

using occ::ints::ESPEvaluator< T >::MatRM = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>

Constructor & Destructor Documentation

ESPEvaluator() [1/3]

template<typename T>

occ::ints::ESPEvaluator< T >::ESPEvaluator ( const T * boys_table )

explicit

Construct evaluator with Boys function table.

~ESPEvaluator()

template<typename T>

occ::ints::ESPEvaluator< T >::~ESPEvaluator

(

)

ESPEvaluator() [2/3]

template<typename T>

occ::ints::ESPEvaluator< T >::ESPEvaluator ( const ESPEvaluator< T > & )

delete

ESPEvaluator() [3/3]

template<typename T>

occ::ints::ESPEvaluator< T >::ESPEvaluator ( ESPEvaluator< T > && )

noexcept

Member Function Documentation

add_shell_pair() [1/2]

template<typename T>

size_t occ::ints::ESPEvaluator< T >::add_shell_pair	(	int	la,
		int	lb,
		int	na_prim,
		int	nb_prim,
		const T *	exponents_a,
		const T *	exponents_b,
		const T *	coeffs_a,
		const T *	coeffs_b,
		const T *	A,
		const T *	B )

Add a shell pair and precompute its E-matrices (Cartesian) Returns index for later evaluation.

add_shell_pair() [2/2]

template<typename T>

size_t occ::ints::ESPEvaluator< T >::add_shell_pair	(	int	la,
		int	lb,
		int	na_prim,
		int	nb_prim,
		const T *	exponents_a,
		const T *	exponents_b,
		const T *	coeffs_a,
		const T *	coeffs_b,
		const T *	A,
		const T *	B,
		bool	spherical )

Add a shell pair with option for spherical harmonics.

Parameters

spherical

If true, output integrals in spherical basis

angular_momenta()

template<typename T>

std::pair< int, int > occ::ints::ESPEvaluator< T >::angular_momenta

(

size_t

shell_idx

)

const

Get angular momenta for a shell pair.

clear()

template<typename T>

void occ::ints::ESPEvaluator< T >::clear

(

)

Clear all precomputed shell pairs.

evaluate()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate	(	size_t	shell_idx,
		const Eigen::Ref< const Mat3N > &	C,
		Eigen::Ref< MatRM >	integrals,
		Eigen::Ref< MatRM >	workspace,
		T	omega = T(0) )

Evaluate ESP integrals for a precomputed shell pair (Eigen interface).

Parameters

shell_idx	Index returned by add_shell_pair
C	Grid point coordinates [3 x npts] column-major
integrals	Output buffer [npts x nab] row-major
workspace	External workspace buffer [npts x nherm] row-major
omega	Range-separation parameter: 0 = full Coulomb (1/r), omega > 0 = long-range erf(omega*r)/r operator

evaluate_overlap()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate_overlap	(	size_t	shell_idx,
		T *	integrals )

Evaluate overlap integrals for a precomputed shell pair.

Parameters

shell_idx	Index returned by add_shell_pair
integrals	Output buffer [nab]

evaluate_soa()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate_soa	(	size_t	shell_idx,
		const T *	x,
		const T *	y,
		const T *	z,
		int	npts,
		T *	V,
		int	ldv,
		T	omega = T(0) ) const

Structure-of-arrays evaluation, vectorised over points.

Parameters

x,y,z	Point coordinates; npts must be a multiple of soa_padding, with padding entries holding any finite coordinates (their outputs are computed and ignored)
V	Output [nab x ldv], V[ab * ldv + pt] (point fastest)
omega	As for evaluate()

evaluate_soa_contract()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate_soa_contract	(	size_t	shell_idx,
		const T *	x,
		const T *	y,
		const T *	z,
		int	npts,
		const T *	F,
		T *	G,
		int	ld,
		int	bf_p,
		int	bf_q,
		bool	both,
		T	omega = T(0) ) const

The pair's integrals contracted as they are formed, for seminumerical exchange: with V as from evaluate_soa, G[(bf_q + b) * ld + i] -= sum_a F[(bf_p + a) * ld + i] V_ab(i) and, when both, G[(bf_p + a) * ld + i] -= sum_b F[(bf_q + b) * ld + i] V_ab(i) (a over the pair's first shell, b its second).

V is never stored in full. npts as for evaluate_soa, ld >= npts.

evaluate_soa_hessian()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate_soa_hessian	(	size_t	idx,
		const T *	x,
		const T *	y,
		const T *	z,
		int	npts,
		T *	V,
		int	ldv,
		const T *	W,
		int	ldw,
		T *	out,
		T	omega = T(0) ) const

One pass over a Hessian pair, point-fastest like evaluate_soa: V[(k * nab + ab) * ldv + i], k = 0 the integrals (a b | 1/|r - x_i|), 1..3 their d/dA_{x,y,z}, 4..6 d/dB_{x,y,z}; and, unless W is null, second derivatives contracted with per-point weights, out[k] += sum_i sum_ab W[ab * ldw + i] d2/dc_k (a b | ...), 21 values: AA (xx, xy, xz, yy, yz, zz), AB (A_d B_e at 3 d + e), BB (as AA).

W must be zero on padding points.

evaluate_soa_value_and_derivative_contraction()

template<typename T>

void occ::ints::ESPEvaluator< T >::evaluate_soa_value_and_derivative_contraction	(	size_t	idx,
		const T *	x,
		const T *	y,
		const T *	z,
		int	npts,
		T *	A,
		int	lda,
		const T *	W,
		int	ldw,
		int	ncentres,
		T *	out,
		T	omega = T(0) ) const

One pass over a derivative pair giving both its integrals and their centre derivatives contracted with per-point weights: A[ab * lda + i] = (a b | 1/|r - x_i|) (nab rows, as evaluate_soa) out[c] += sum_i sum_ab W[ab * ldw + i] d/dc A_ab(x_i) c = A_x, A_y, A_z (and B_x, B_y, B_z when ncentres == 2).

The derivative integrals are never stored. W must be zero on padding points.

is_spherical()

template<typename T>

bool occ::ints::ESPEvaluator< T >::is_spherical

(

size_t

shell_idx

)

const

Check if a shell pair uses spherical harmonics.

nab()

template<typename T>

int occ::ints::ESPEvaluator< T >::nab

(

size_t

shell_idx

)

const

Get number of basis function pairs for a shell pair.

nherm()

template<typename T>

int occ::ints::ESPEvaluator< T >::nherm

(

size_t

shell_idx

)

const

Get number of Hermite Gaussians for a shell pair (workspace cols needed).

num_shell_pairs()

template<typename T>

size_t occ::ints::ESPEvaluator< T >::num_shell_pairs

(

)

const

Number of precomputed shell pairs.

operator=() [1/2]

template<typename T>

ESPEvaluator & occ::ints::ESPEvaluator< T >::operator= ( const ESPEvaluator< T > & )

delete

operator=() [2/2]

template<typename T>

ESPEvaluator & occ::ints::ESPEvaluator< T >::operator= ( ESPEvaluator< T > && )

noexcept

pair_center()

template<typename T>

std::array< T, 3 > occ::ints::ESPEvaluator< T >::pair_center

(

size_t

shell_idx

)

const

Get the effective center of a shell pair (overlap region) Based on the most diffuse primitive combination.

pair_estimate()

template<typename T>

T occ::ints::ESPEvaluator< T >::pair_estimate

(

size_t

shell_idx

)

const

Grid-point-independent upper bound on this pair's ESP integrals, sum_prim |2 pi / p * c_a * c_b * exp(-mu R_AB^2)|, i.e.

the integral prefactor with the Boys factor F_0 <= 1 bounded out. Because it drops the only distance-to-grid-point dependence, it bounds the pair everywhere and is the right magnitude to screen a 1/R kernel on. Cheaper and tighter than the overlap, which is this times sqrt(pi/p)/2 and so understates compact pairs badly.

pair_extent()

template<typename T>

T occ::ints::ESPEvaluator< T >::pair_extent

(

size_t

shell_idx

)

const

Get the extent of a shell pair (radius where pair density < 1e-12) Based on the most diffuse primitive combination.

pair_far_estimate()

template<typename T>

std::array< T, 2 > occ::ints::ESPEvaluator< T >::pair_far_estimate

(

size_t

shell_idx

)

const

Far-field form of the same bound, {q1, spread}: at a point C with R = |C - pair_center| > spread the pair's ESP integrals are at most q1 / (R - spread) (each primitive's F_0(T) <= sqrt(pi/T)/2).

The 1/R tail is kept: this only tightens the bound, it never cuts it off.

resize_derivative_pairs()

template<typename T>

void occ::ints::ESPEvaluator< T >::resize_derivative_pairs

(

size_t

n

)

Shell pairs for centre derivatives (seminumerical exchange gradients), the same shells as add_shell_pair: resize_derivative_pairs(n) once, then set_shell_pair_derivative for each idx < n (distinct indices may be set concurrently).

Angular momenta up to 5.

resize_hessian_pairs()

template<typename T>

void occ::ints::ESPEvaluator< T >::resize_hessian_pairs

(

size_t

n

)

Shell pairs for second derivatives (seminumerical exchange Hessians), set like the derivative pairs: resize_hessian_pairs(n) once, then set_shell_pair_hessian for each idx < n (distinct indices may be set concurrently).

Angular momenta up to 4.

set_shell_pair_derivative()

template<typename T>

void occ::ints::ESPEvaluator< T >::set_shell_pair_derivative	(	size_t	idx,
		int	la,
		int	lb,
		int	na_prim,
		int	nb_prim,
		const T *	exponents_a,
		const T *	exponents_b,
		const T *	coeffs_a,
		const T *	coeffs_b,
		const T *	A,
		const T *	B,
		bool	spherical )

set_shell_pair_hessian()

template<typename T>

void occ::ints::ESPEvaluator< T >::set_shell_pair_hessian	(	size_t	idx,
		int	la,
		int	lb,
		int	na_prim,
		int	nb_prim,
		const T *	exponents_a,
		const T *	exponents_b,
		const T *	coeffs_a,
		const T *	coeffs_b,
		const T *	A,
		const T *	B,
		bool	spherical )

workspace_size()

template<typename T>

size_t occ::ints::ESPEvaluator< T >::workspace_size	(	size_t	shell_idx,
		int	npts ) const

Get required workspace size for a shell pair.

Member Data Documentation

soa_padding

template<typename T>

int occ::ints::ESPEvaluator< T >::soa_padding = 32

staticconstexpr

Point counts passed to evaluate_soa must be a multiple of this.

---

The documentation for this class was generated from the following file:

• /home/runner/work/occ/occ/include/occ/ints/esp.h