Multipole#

cuest.bindings.cuestMultipoleComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspaceDescriptor: int,
multipoleOrder: collections.abc.Sequence[int],
origin: collections.abc.Sequence[float],
outMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required (in bytes) for multipole matrix calculation.

This function computes the workspace requirements for a requested multipole calculation. Fill the provided workspace descriptor with host and device buffer sizes required. The outMatrix pointer may be NULL.

The multipole order is specified in terms of integer exponents on x^l y^m z^n. This and the origin may not be NULL during the WorkspaceQuery.

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle). Must not be NULL.

parameters[in]cuestMultipoleComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspaceDescriptor[out]cuestWorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

multipoleOrder[in]List[int]

List of length 3 specifying exponents: x^l y^m z^n, on the CPU. Elements must be greater than or equal to zero. Must not be NULL.

origin[in]List[float]

List of length 3 specifying the cartesian coordinates of the origin, on the CPU. Must not be NULL.

outMatrixPointer

Optional buffer for computed multipole matrix

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestMultipoleCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspace: int,
multipoleOrder: collections.abc.Sequence[int],
origin: collections.abc.Sequence[float],
outMatrix: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Compute the atomic orbital multipole matrix using the provided OEIntPlan plan.

The output buffer must be preallocated and sized for (nao × nao) elements, where nao is the number of atomic orbitals in the basis. Temporary workspace must be allocated using size returned by cuestMultipoleComputeWorkspaceQuery().

With the default configuration of the cuEST handle, multipole moments with a total order of up to 30 are supported (assuming an orbital basis including g orbitals). Support for higher-order multipoles can be enabled by increasing CUEST_HANDLE_PARAMETERS_MAX_GAUSS_HERMITE. Exceeding this limit results in a CUEST_STATUS_EXCEPTION return code.

The multipole order is specified in terms of integer exponents on x^l y^m z^n.

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle). Must not be NULL.

parameters[in]cuestMultipoleComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffers for computation (preallocated). Must not be NULL.

multipoleOrder[in]List[int]

List of length 3 specifying exponents: x^l y^m z^n, on the CPU. Elements must be greater than or equal to zero. Must not be NULL.

origin[in]List[float]

List of length 3 specifying the cartesian coordinates of the origin, on the CPU. Must not be NULL.

outMatrix[out]Pointer

Output buffer for computed multipole matrix elements (size: nao × nao) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestMultipoleDerivativeComputeWorkspaceQuery(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspaceDescriptor: int,
multipoleOrder: collections.abc.Sequence[int],
origin: collections.abc.Sequence[float],
densityMatrix: cuest.bindings.cuest.Pointer,
outGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Query the temporary workspace required (in bytes) for multipole matrix gradient calculation.

This function computes the workspace requirements of a single gradient evaluation, based on the supplied plan and dimensions. The workspace descriptor is filled with host and device memory requirements. Output buffers may be NULL for the purposes of the query.

The multipole order is specified in terms of integer exponents on x^l y^m z^n. This and the origin may not be NULL during the WorkspaceQuery.

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle). Must not be NULL.

parameters[in]cuestMultipoleDerivativeComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspaceDescriptor[out]cuestWorkspaceDescriptor

Output descriptor for temporary workspace sizes. Must not be NULL.

multipoleOrder[in]List[int]

List of length 3 specifying exponents: x^l y^m z^n, on the CPU. Elements must be greater than or equal to zero. Must not be NULL.

origin[in]List[float]

List of length 3 specifying the cartesian coordinates of the origin, on the CPU. Must not be NULL.

densityMatrixPointer

Optional density matrix

outGradientPointer

Optional output gradient

Returns#

status[out]cuestStatus_t
cuest.bindings.cuestMultipoleDerivativeCompute(
*,
handle: cuest.bindings.cuest.cuestHandle,
plan: cuest.bindings.cuest.cuestOEIntPlanHandle,
parameters: cuest.bindings.cuest.Parameters,
temporaryWorkspace: int,
multipoleOrder: collections.abc.Sequence[int],
origin: collections.abc.Sequence[float],
densityMatrix: cuest.bindings.cuest.Pointer,
outGradient: cuest.bindings.cuest.Pointer,
) → cuest.bindings.cuest.CuestStatus#

Compute the electronic gradient (derivative) of the atomic orbital multipole matrix using the supplied integral plan and density matrix.

Both the input density matrix and the output gradient must be preallocated. The density matrix must be a nao x nao array and the output gradient must have space for (natom x 3) elements, where nao is the number of atomic orbitals and natom the number of atoms in the system. All required temporary workspace must be allocated by the user prior to calling this function.

With the default configuration of the cuEST handle, multipole moment derivatives with a total order of up to 29 are supported (assuming an orbital basis including g orbitals). Support for higher-order multipoles can be enabled by increasing CUEST_HANDLE_PARAMETERS_MAX_GAUSS_HERMITE. Exceeding this limit results in a CUEST_STATUS_EXCEPTION return code.

The multipole order is specified in terms of integer exponents on x^l y^m z^n.

Parameters#

handle[in]cuestHandle

cuEST handle. Must not be NULL.

plan[in]cuestOEIntPlanHandle

One-electron integral computation plan (opaque handle). Must not be NULL.

parameters[in]cuestMultipoleDerivativeComputeParameters_t

Parameters object. Must not be NULL.

temporaryWorkspace[in]Workspace

Temporary workspace buffers (preallocated for this operation). Must not be NULL.

multipoleOrder[in]List[int]

List of length 3 specifying exponents: x^l y^m z^n, on the CPU. Elements must be greater than or equal to zero. Must not be NULL.

origin[in]List[float]

List of length 3 specifying the cartesian coordinates of the origin, on the CPU. Must not be NULL.

densityMatrix[in]Pointer

Input density matrix (size: nao × nao) on the GPU. Must not be NULL.

outGradient[out]Pointer

Output gradient (size: natom × 3) on the GPU. Must not be NULL. Elements of this array are overwritten by the calculation results.

Returns#

statuscuestStatus_t