SolverEngine

class psi4.driver.p4util.SolverEngine

Bases: ABC

Abstract Base Class defining the API for a matrix-vector product object required by solvers.

Engines implement the correct product functions for iterative solvers that do not require the target matrix be stored directly. Classes intended to be used as an engine for davidson_solver() or hamiltonian_solver() should inherit from this base class to ensure that the required methods are defined.

Note

The vector referred to here is intentionally vague, the solver does not care what it is and only holds individual or sets of them. In fact an individual vector could be split across two elements in a list, such as for different spin. Whatever data type is used and individual vector should be a single element in a list such that len(list) returns the number of vector-like objects.

Methods Summary

compute_products(X)	Compute a Matrix * trial vector products
new_vector()	Return a new vector object.
precondition(R_k, w_k)	Apply the preconditioner to a Residual vector
residue(X, so_prop_ints)	Compute residue
vector_axpy(X, Y)	Compute scaled vector addition operation a*X + Y
vector_copy()	Make a copy of a vector
vector_dot(X, Y)	Compute a dot product between two vectors
vector_scale(X)	Scale a vector by some factor

Methods Documentation

abstract compute_products(X)

Compute a Matrix * trial vector products

Parameters:

X (List[vector]) – Trial vectors.

Returns:

• Expected by davidson_solver()

• AX (List[vector]) – The product \(A x X_{i}\) for each X_{i} in X, in that order. Where A is the hermitian matrix to be diagonalized. len(AX) == len(X)

• n (int) – The number of products that were evaluated. If the object implements product caching this may be less than len(X)

• Expected by hamiltonian_solver()

• H1X (List[vector]) – The product \(H1 x X_{i}\) for each X_{i} in X, in that order. Where H1 is described in hamiltonian_solver(). len(H1X) == len(X)

• H2X (List[vector]) – The product \(H2 x X_{i}\) for each X_{i} in X, in that order. Where H2 is described in hamiltonian_solver(). len(H2X) == len(X)

abstract new_vector()

Return a new vector object.

The solver is oblivious to the data structure used for a vector this method provides the engine with a means to create vector like quantities.

The engine calls this method with no arguments. So any defined by the engine for its own use should be optional

Returns:

X – This should be a new vector object with the correct dimensions, assumed to be zeroed out

Return type:

singlet vector

abstract precondition(R_k, w_k)

Apply the preconditioner to a Residual vector

The preconditioner is usually defined as \((w_k - D_{i})^-1\) where D is an approximation of the diagonal of the matrix that is being diagonalized.

Parameters:

• R_k (single vector) – The residual vector

• w_k (float) – The eigenvalue associated with this vector

Returns:

new_X_k – The preconditioned residual vector, a correction vector that will be used to augment the guess space

Return type:

single vector

abstract residue(X, so_prop_ints)

Compute residue

Parameters:

• X – The single vector to use to compute the property.

• so_prop_ints – Property integrals in SO basis for the desired transition property.

• prefactor – Optional float scaling factor.

Returns:

residue – The transition property.

Return type:

Any

abstract vector_axpy(X, Y)

Compute scaled vector addition operation a*X + Y

Parameters:

• a (float) – The scale factor applied to X

• X (singlet vector) – The vector which will be scaled and added to Y

• Y (single vector) – The vector which the result of a*X is added to

Returns:

Y – The solver assumes that Y is updated, and returned. So it is safe to avoid a copy of Y if possible

Return type:

single vector

abstract vector_copy()

Make a copy of a vector

Parameters:

X (single vector) – The vector to copy

Returns:

X’ – A copy of X should be distinct object that can be modified independently of the passed object, Has the same data when returned.

Return type:

single vector

abstract static vector_dot(X, Y)

Compute a dot product between two vectors

Parameters:

• X (single vector)

• Y (single vector)

Returns:

a – The dot product (X x Y)

Return type:

float

abstract vector_scale(X)

Scale a vector by some factor

Parameters:

• a (float) – The scale facor

• X (single vector) – The vector that will be scaled

Returns:

X – The solver assumes that the passed vector is modifed. So it is save to avoid a copy of X if possible.

Return type:

single vector