Skip to content

wave_function_solver#

Includes our wave function solvers.

Modules:

  • auto_select –

    Includes method to auto-select the best wave function solver.

  • cudss –

    Includes the cuDSS wave function solver.

  • mumps –

    Includes the MUMPS wave function solver.

  • pardiso –

    Includes the PARDISO wave function solver.

  • solver –

    Includes the abstract base class for wave function solvers.

  • superlu –

    Includes the SuperLU wave function solver.

  • thomas –

    Includes our Thomas algorithm based wave function solver.

Classes:

  • cuDSS –

    Wavefunction solver using NVIDIA's cuDSS library for sparse

  • MUMPS –

    Wave function solver using MUMPS for sparse matrix solving.

  • PARDISO –

    Wave function solver using PARDISO for sparse matrix solving.

  • WFSolver –

    Abstract base class for wave function solvers.

  • SuperLU –

    Wave function solver using LU decomposition for solving.

  • Thomas –

    Wave function solver using the block Thomas algorithm.

Functions:

cuDSS #

cuDSS(matrix_type: str | None = None, matrix_view: str | None = None)

Bases: WFSolver

Wavefunction solver using NVIDIA's cuDSS library for sparse direct solves on GPUs.

Parameters:

  • matrix_type (str, default: None ) –

    The type of the system matrix. This describes properties like symmetry and definiteness. If None, the solver will use a general matrix type.

  • matrix_view (str, default: None ) –

    The view of the system matrix sparsity. This solver supports 'full', 'upper', and 'lower' views. If None, the solver will use the 'full' view.

Methods:

  • solve –

    Solves the sparse linear system a @ x = b using cuDSS.

solve #

solve(a: csr_matrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False)

Solves the sparse linear system a @ x = b using cuDSS.

Parameters:

  • a (csr_matrix) –

    The sparse system matrix in CSR format.

  • b (NDArray) –

    The dense right-hand side array with shape (n, batchsize).

  • reuse_analysis (bool, default: False ) –

    Whether to reuse the symbolic factorization from a previous solve. Default is False. This is useful when solving multiple linear systems with the same sparsity pattern but different numerical values.

  • reuse_factorization (bool, default: False ) –

    Whether to reuse the numerical factorization from a previous solve. Default is False. This can only be True if reuse_analysis is also True. Note that this must only be True if the matrix values have not changed since the last factorization.

Returns:

  • x ( NDArray ) –

    The solution array with shape (n, batchsize).

MUMPS #

MUMPS(matrix_type: str = 'complex_nonsymmetric', matrix_view: str = 'full', ordering: str = 'metis', verbose: bool = False)

Bases: WFSolver

Wave function solver using MUMPS for sparse matrix solving.

This solver uses MUMPS to solve sparse linear systems on the CPU. It can reuse the analysis phase if configured to do so, which can speed up repeated solves with the same matrix structure.

Parameters:

  • matrix_type (str, default: 'complex_nonsymmetric' ) –

    The type of matrix to be solved. The only valid option is 'complex_nonsymmetric', which is the default. This is a placeholder for future support of other matrix types.

  • matrix_view (str, default: 'full' ) –

    The view of the matrix. The only valid option is 'full', which means the full matrix is used. Default is 'full'. This is a placeholder for future support of other matrix views.

  • ordering (str, default: 'metis' ) –

    The ordering method to use for the matrix factorization. Valid options are 'amd', 'amf', 'scotch', 'pord', 'metis', 'qamd', and 'auto'. The 'metis' and 'scotch' orderings are apparently usually pretty good. The 'auto' option will let MUMPS choose the "best" ordering. Default is 'metis'.

  • verbose (bool, default: False ) –

    If True, enable verbose output from MUMPS. Default is False.

Methods:

  • solve –

    Solves the sparse linear system a @ x = b using MUMPS.

solve #

solve(a: spmatrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False) -> NDArray

Solves the sparse linear system a @ x = b using MUMPS.

Parameters:

  • a (spmatrix) –

    The sparse system matrix.

  • b (NDArray) –

    The dense right-hand side vector.

  • reuse_analysis (bool, default: False ) –

    Whether to reuse the analysis phase from a previous solve, by by default False. This is useful when solving multiple linear systems with the same sparsity pattern but different numerical values.

  • reuse_factorization (bool, default: False ) –

    Whether to reuse the numerical factorization from a previous solve, by default False. This can only be True if reuse_analysis is also True. Note that this must only be True if the matrix values have not changed since the last factorization.

Returns:

  • x ( NDArray ) –

    The solution vector.

PARDISO #

PARDISO(matrix_type: str | None = None, matrix_view: str | None = None, verbose: bool = False)

Bases: WFSolver

Wave function solver using PARDISO for sparse matrix solving.

Parameters:

  • matrix_type (str, default: None ) –

    The type of the system matrix. Must be one of the valid PARDISO matrix types. Default is 'complex_nonsymmetric'.

  • matrix_view (str, default: None ) –

    The view of the matrix. Valid options are 'default' and 'up'. The 'up' view is a hint to the user to use the upper triangular part of the matrix, which is required for symmetric matrices. Default is 'default', meaning the full matrix is used.

  • verbose (bool, default: False ) –

    If True, enable verbose output from PARDISO. Default is False.

Methods:

  • solve –

    Solves the sparse linear system a @ x = b using PARDISO.

solve #

solve(a: spmatrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False) -> NDArray

Solves the sparse linear system a @ x = b using PARDISO.

Parameters:

  • a (spmatrix) –

    The sparse system matrix.

  • b (NDArray) –

    The right-hand side vector.

  • reuse_analysis (bool, default: False ) –

    Whether to reuse the symbolic factorization from a previous solve, by default False. This is useful when solving multiple linear systems with the same sparsity pattern but different numerical values.

  • reuse_factorization (bool, default: False ) –

    Whether to reuse the numerical factorization from a previous solve, by default False. This can only be True if reuse_analysis is also True. Note that this must only be True if the matrix values have not changed since the last factorization.

Returns:

  • x ( NDArray ) –

    The solution vector.

WFSolver #

WFSolver(matrix_type: str | None, matrix_view: str | None)

Bases: ABC

Abstract base class for wave function solvers.

Parameters:

  • matrix_type (str) –

    The type of the system matrix. This describes properties like symmetry and definiteness, which can be used by solvers to optimize the solution process. Can be None if the solver does not require this information or if it can be inferred from the matrix itself.

  • matrix_view (str) –

    The view of the system matrix sparsity. This is a hint to the solver about which part of the matrix to use, which can be relevant for symmetric matrices where only the upper or lower part is needed. Can be None if the solver does not require this information or if it can be inferred from the matrix itself.

Methods:

  • solve –

    Solves the sparse linear system a @ x = b.

solve abstractmethod #

solve(a: spmatrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False) -> NDArray

Solves the sparse linear system a @ x = b.

Parameters:

  • a (spmatrix) –

    The sparse system matrix.

  • b (NDArray) –

    The right-hand side vector.

  • reuse_analysis (bool, default: False ) –

    Whether to reuse the analysis phase from a previous solve, by default False. This typically includes symbolic factorization and ordering but can vary between solvers. This is useful when solving multiple linear systems with the same sparsity pattern but different numerical values.

  • reuse_factorization (bool, default: False ) –

    Whether to reuse the numerical factorization from a previous solve, by default False. This can only be True if reuse_analysis is also True. Note that this must only be True if the matrix values have not changed since the last factorization.

Returns:

  • x ( NDArray ) –

    The solution vector.

SuperLU #

SuperLU(matrix_type: str = 'complex_nonsymmetric', matrix_view: str = 'full')

Bases: WFSolver

Wave function solver using LU decomposition for solving.

This solver uses the SuperLU on the CPU for facorization. Depending on the chosen array module, the solution phase is computed on the CPU or GPU.

Parameters:

  • matrix_type (str, default: 'complex_nonsymmetric' ) –

    The type of matrix to be solved. The only valid option is 'complex_nonsymmetric', which is the default. This is a placeholder for future support of other matrix types.

  • matrix_view (str, default: 'full' ) –

    The view of the matrix. The only valid option is 'full', which means the full matrix is used. Default is 'full'. This is a placeholder for future support of other matrix views.

Methods:

  • solve –

    Solves the sparse system a @ x = b using LU decomposition.

solve #

solve(a: spmatrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False) -> NDArray

Solves the sparse system a @ x = b using LU decomposition.

Parameters:

  • a (spmatrix) –

    The sparse system matrix.

  • b (NDArray) –

    The right-hand side vector.

  • reuse_analysis (bool, default: False ) –

    Unused for this solver since it does not involve an analysis phase.

  • reuse_factorization (bool, default: False ) –

    Whether to reuse the numerical factorization from a previous solve, by default False. Note that this must only be True if the matrix values have not changed since the last factorization.

Returns:

  • x ( NDArray ) –

    The solution vector.

Thomas #

Thomas(matrix_type: str = 'complex_nonsymmetric', matrix_view: str = 'full')

Bases: WFSolver

Wave function solver using the block Thomas algorithm.

Parameters:

  • matrix_type (str, default: 'complex_nonsymmetric' ) –

    The type of the system matrix. Must be one of 'real_symmetric_indefinite', 'complex_hermitian_indefinite', or 'complex_nonsymmetric'. Default is 'complex_nonsymmetric'.

  • matrix_view (str, default: 'full' ) –

    The view of the system matrix. Must be one of 'full', 'upper', or 'lower'. 'upper' and 'lower' are only valid for symmetric or Hermitian matrices. Default is 'full'.

Methods:

  • solve –

    Solves the sparse system a @ x = b using the block Thomas algorithm.

solve #

solve(a: csr_matrix, b: NDArray, reuse_analysis: bool = False, reuse_factorization: bool = False, overwrite_b: bool = True) -> NDArray

Solves the sparse system a @ x = b using the block Thomas algorithm.

Since b is directly modified in-place, b is lost after this call.

Parameters:

  • a (csr_matrix) –

    The sparse system matrix.

  • b (NDArray) –

    The dense right-hand side vector.

  • reuse_analysis (bool, default: False ) –

    Whether to reuse the analysis phase from a previous solve, by by default False. This is useful when solving multiple linear systems with the same sparsity pattern but different numerical values.

  • reuse_factorization (bool, default: False ) –

    Not implemented for this solver.

  • overwrite_b (bool, default: True ) –

    Whether to overwrite the input b with the solution. Default is True. If False, a copy of b will be made before solving, and the original b will remain unchanged. This can be useful if the caller needs to keep the original right-hand side vector for later use.

Returns:

  • x ( NDArray ) –

    The solution vector.

auto_select_solver #

auto_select_solver(matrix_type: str, matrix_view: str) -> WFSolver

Auto-selects the solver based on the matrix type.

On GPU, cuDSS is the preferred solver if available. If cuDSS is not available, SuperLU is used as a fallback.

On CPU, PARDISO is the preferred solver if available. If PARDISO is not available, MUMPS is used as a fallback. If MUMPS is also not available, SuperLU is used as a final fallback.

If the matrix type is symmetric or Hermitian, only cuDSS on GPU and PARDISO on CPU are supported. If these solvers are not available, an error is raised.

Parameters:

  • matrix_type (str) –

    The type of the matrix.

  • matrix_view (str) –

    The view of the matrix.

Returns:

  • WFSolver –

    The selected wavefunction solver instance.