MATMUL

The following contains all relevant function for the matrix-free matrix-vector multiplication. Depending on the setup (MPI, openMP, or none) different implementations are utilized of the same functions.

For distributed memory with MPI, a different set of routines (blocking – which is the default – and non-blocking) are available. If MATMUL_NON_BLOCKING is defined via

#define MATMUL_NON_BLOCKING 1

the multiplication is done using non-blocking routines (MPI_ISend and MPI_IRecv) instead of MPI_Alltoallv.

Vector class

The Vector class can be used for computations executed by the ShellMatrix. In order to ensure the correct memory layout (particularly important for MPI), the Vector instances should be created with:

Vector<scalartype> danceq::internal::ShellMatrix::create_Vector(void) const

Creates a Vector class instance compatible with the ShellMatrix.

The function creates an instance of the Vector class that can be used with the computations. This is particularly important when MPI is enabled to ensure the correct memory layout. The Vector class has many additionally features for simple linear algebra routines.

Returns:

Vector

High-level functions

Matrix-free multiplication and the computation of the expectation value are performed using the following high-level functions that are wrapper for functions listed below.

int32_t danceq::internal::ShellMatrix::apply(const danceq::internal::Vector<scalartype> &input, danceq::internal::Vector<scalartype> &output, const bool reset_output_to_zero = true) const

High-level function to perform a matrix-free multiplication using the Vector class.

The function is a wrapper for the low-level function MATMUL_basic(…). In- and output are instances of the Vector class that should be created with create_Vector(). Before the multiplication is executed, the output data might by set to zero using the boolean reset_output_to_zero.

Parameters:

• input – Input Vector

• output – Output Vector

• reset_output_to_zero – Boolean to set output to zero before multiplication

Returns:

error_code

Vector<scalartype> danceq::internal::ShellMatrix::operator*(const Vector<scalartype> &v) const

High-level function to perform a matrix-free multiplication using the Vector class.

The function is a wrapper for the low-level function MATMUL_basic(…). Input is an instance of the Vector class that should be created with create_Vector().

The usage is straightforward:

w = H*v;

Parameters:

v – Input Vector

Returns:

Output vector

scalartype danceq::internal::ShellMatrix::get_expectation_value(const danceq::internal::Vector<scalartype> &lhs, const danceq::internal::Vector<scalartype> &rhs) const

High-level function to compute the expectation value using the Vector class.

The function is a wrapper for the low-level function EXPECTATION_VALUE_basic(…). lhs (rhs) refers to the left(right)-hand side. Both are instances of the Vector class that should be created with create_Vector(). The complex conjugate of the left-hand side is used when the scalars are complex.

Parameters:

• lhs – Left-hand side

• rhs – Reft-hand side

Returns:

Expectation value

scalartype danceq::internal::ShellMatrix::get_expectation_value(const danceq::internal::Vector<scalartype> &psi) const

High-level function to compute the expectation value using the Vector class.

The function is a wrapper for get_expectation_value(psi,psi) which calls the low-level function EXPECTATION_VALUE_basic(…). The input is an instance of the Vector class that should be created with create_Vector(). The complex conjugate is used for the left-hand side.

Parameters:

psi – Left- and right-hand side

Returns:

Expectation value

Low-level functions

We have two low-level function that are marked as private to compute the matrix-free matrix-vector multiplication and the expectation value of an Operator. They are called by higher-level, more user friendly, functions listed above.

int32_t danceq::internal::ShellMatrix::MATMUL_basic(const scalartype *input, scalartype *output, const bool reset_output_to_zero = true) const

Low-level function to preform the matrix-free matrix-vector multiplication.

This function is the core the ShellMatrix class which preforms the matrix-free multiplication. It takes an input and output pointing to the correctly assigned data. For example, they can point to the data of the Vector class or the data of the internal vector structure Vec of Petsc. Note, that if the data is distributed over different processes with MPI it only points to the local data. The input is marked by const and is, therefore, not modified. Before the multiplication is executed, the output data might by set to zero using the boolean reset_output_to_zero. Not setting the output to zero allows an efficient construction of the Krylov space methods where only two (instead of three) vectors are stored. The function has four different implementation (two times MPI, one time openMP, and no parallelization option) as discussed here.

Parameters:

• input – Pointer to the local input data

• output – Pointer to the local output data

• reset_output_to_zero – Boolean to set output to zero before multiplication

Returns:

error_code

scalartype danceq::internal::ShellMatrix::EXPECTATION_VALUE_basic(const scalartype *lhs, const scalartype *rhs) const

Low-level function to compute the expectation value using a matrix-free multiplication.

It takes two const inputs: lhs (left-hand side) and rhs (right-hand side). Both are pointers that have to be correctly assigned data, e.g., from Vector class. If complex scalar are used, the complex-conjugate of the lhs is used:

\[o = \sum_{ij} \texttt{conj}({\mathrm{lhs}}_i)\,\, O_{ij}\,\, \mathrm{rhs}_j \]

\(O\) refers to the Operator. The function has four different implementations (two times MPI, one time openMP, and no parallelization option) as discussed here.

Parameters:

• lhs – Left-hand side

• rhs – Reft-hand side

Returns:

Expectation value