DirectSolver (Artisynth API documentation)

All Known Implementing Classes:

AccelerateSolver, DirectSolverBase, MatlabSolver, MumpsSolver, PardisoSolver, UmfpackSolver
```
public interface DirectSolver
```

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`DirectSolver.IterativeMethod` Describes the methods available for `iterativeSolve(double[], double[], double[])`, each of which uses the most recent factorization as a preconditioner.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ANALYZED` Indicates that a matrix has been set and analyzed for this solver.
`static int`	`DEFAULT_ITERATIVE_MAX_SOLVES` Default maximum number of preconditioner solves for iterative solves.
`static double`	`DEFAULT_ITERATIVE_TOLERANCE` Default relative residual tolerance for iterative solves.
`static int`	`FACTORED` Indicates that a matrix has been set, analyzed, and numerically factored for this solver.
`static int`	`UNSET` Indicates that no matrix is currently set for this solver.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`analyze(double[] vals, int[] colIdxs, int[] rowOffs, int size, int type)` Performs prefactor analysis on a matrix whose structure and values are supplied in compressed row storage (CRS) format, using 1-based indices, as described in the documentation for `Matrix.setCRSValues`.
`void`	`analyze(Matrix M, int size, int type)` Performs prefactor analysis on a specified matrix.
`void`	`analyzeAndFactor(Matrix M)` Factors a matrix.
`void`	`dispose()` Releases all internal resources allocated by this solver.
`void`	`factor()` Factors a previously analyzed matrix.
`void`	`factor(double[] vals)` Factors a previously analyzed matrix, using the numeric values supplied by `vals`.
`java.lang.String`	`getErrorMessage()` Returns a message describing the reason for the failure of the most recent call to `analyze()` or `factor()`, or `null` if the method succeeded.
`default int`	`getIterativeMaxSolves()` Queries the maximum number of preconditioner solves allowed for `iterativeSolve(double[], double[], double[])`.
`default DirectSolver.IterativeMethod`	`getIterativeMethod()` Queries the method used by `iterativeSolve(double[], double[], double[])`.
`default double`	`getIterativeTolerance()` Queries the tolerance for `iterativeSolve(double[], double[], double[])`.
`default double`	`getLastIterativeResidual()` Returns the relative residual `\|\|b - M x\|\|/\|\|b\|\|` obtained by the most recent call to `iterativeSolve(double[], double[], double[])`, or -1 if this is not available.
`default int`	`getLastIterativeSolves()` Returns the number of preconditioner solves performed by the most recent call to `iterativeSolve(double[], double[], double[])`, or -1 if this is not available.
`default int`	`getMaxRefinementSteps()` Returns the maximum number of iterative refinement steps that this solver will perform after a solve, or 0 if iterative refinement is not supported.
`default int`	`getNumNegEigenvalues()` If possible, returns the number of negative eigenvalues detected during the most recent factorization of a symmetric indefinite matrix.
`long`	`getNumNonZerosInFactors()` If possible, returns the number of non-zero elements in the factorization.
`default int`	`getNumPerturbedPivots()` If possible, returns the number of pivot perturbations that were required during the most recent numeric factorization (i.e., during the last `factor()` call).
`default int`	`getNumPosEigenvalues()` If possible, returns the number of positive eigenvalues detected during the most recent factorization of a symmetric indefinite matrix.
`int`	`getState()` Returns the current state of this solver, which is one of `UNSET`, `ANALYZED`, or `FACTORED`.
`default boolean`	`hasIterativeSolves()` Returns true if this solver supports iterative solving, using a recent directly-factored matrix as a preconditioner.
`default boolean`	`hasMultipleRhsSolves()` Returns true if this solver can solve for multiple right hand sides, using `solve(X,B,nrhs)`.
`default int`	`iterativeSolve(double[] vals, double[] x, double[] b)` Solves the system
`default int`	`iterativeSolve(double[] vals, double[] x, double[] b, int tolExp)` Deprecated. use `setIterativeTolerance(double)` and `iterativeSolve(double[],double[],double[])` instead
`static double`	`residual(int[] rowOffs, int[] colIdxs, double[] vals, int size, double[] x, double[] b, boolean symmetric)` Computes the norm of the residual
`default void`	`setIterativeMaxSolves(int max)` Sets the maximum number of preconditioner solves allowed for `iterativeSolve(double[], double[], double[])`, beyond which it fails.
`default void`	`setIterativeMethod(DirectSolver.IterativeMethod method)` Sets the method used by `iterativeSolve(double[], double[], double[])`.
`default void`	`setIterativeTolerance(double tol)` Sets the tolerance for `iterativeSolve(double[], double[], double[])`: the iteration succeeds when the relative residual `\|\|b - M x\|\|/\|\|b\|\|` is at most `tol`.
`default void`	`setMaxRefinementSteps(int nsteps)` Sets the maximum number of iterative refinement steps that this solver should perform after a solve.
`void`	`solve(double[] x, double[] b)` Solves the system
`default void`	`solve(double[] X, double[] B, int nrhs)` Solves the system
`void`	`solve(VectorNd x, VectorNd b)` Solves the system

- Field Detail
  - UNSET
```
static final int UNSET
```
    Indicates that no matrix is currently set for this solver.
    
    See Also:
    
    Constant Field Values
  - ANALYZED
```
static final int ANALYZED
```
    Indicates that a matrix has been set and analyzed for this solver.
    
    See Also:
    
    Constant Field Values
  - FACTORED
```
static final int FACTORED
```
    Indicates that a matrix has been set, analyzed, and numerically factored for this solver.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ITERATIVE_TOLERANCE
```
static final double DEFAULT_ITERATIVE_TOLERANCE
```
    Default relative residual tolerance for iterative solves.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ITERATIVE_MAX_SOLVES
```
static final int DEFAULT_ITERATIVE_MAX_SOLVES
```
    Default maximum number of preconditioner solves for iterative solves.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getState
```
int getState()
```
    Returns the current state of this solver, which is one of UNSET, ANALYZED, or FACTORED.
    
    Returns:
    
    state of this solver
  - getErrorMessage
```
java.lang.String getErrorMessage()
```
    Returns a message describing the reason for the failure of the most recent call to analyze() or factor(), or null if the method succeeded.
    
    Returns:
    
    most recent error message, if any
  - getNumNonZerosInFactors
```
long getNumNonZerosInFactors()
```
    If possible, returns the number of non-zero elements in the factorization. If the factorization has not yet been performed, this may be the number estimated by the most recent call to analyze(). If the solver does not report this quantity, -1 is returned.
    
    Returns:
    
    number of non-zero elements in the factorization, or -1 if not supported
  - analyze
```
void analyze(Matrix M,
             int size,
             int type)
```
    Performs prefactor analysis on a specified matrix. The matrix reference is stored and used by later calls to factor(). If size is less than the actual matrix size, then the analysis is done on the principal submatrix of M defined by the first size rows and columns.
    
    Parameters:
    
    M - matrix to analyze
    
    size - size of the matrix to factor.
    
    type - or-ed flags giving information about the matrix type. Typical flags are SYMMETRIC or POSITIVE_DEFINITE
    
    Throws:
    
    java.lang.IllegalArgumentException - if the matrix is not square, or the matrix type is not supported by the solver.
    
    NumericalException - if the analysis failed for numeric reasons.
  - analyze
```
void analyze(double[] vals,
             int[] colIdxs,
             int[] rowOffs,
             int size,
             int type)
```
    Performs prefactor analysis on a matrix whose structure and values are supplied in compressed row storage (CRS) format, using 1-based indices, as described in the documentation for Matrix.setCRSValues. The number of non-zero values is given by rowOffs[size]-1. If the matrix type is symmetric, only the upper triangular portion should be supplied.
    Because no matrix object is supplied, factor() cannot be used after calling this method; use factor(vals) instead. The values supplied here may be used to assist the analysis but are not used for any numeric factorization.
    
    Parameters:
    
    vals - values of the non-zero matrix elements
    
    colIdxs - 1-based column indices of the non-zero matrix elements
    
    rowOffs - 1-based row start offsets into vals and colIdxs
    
    size - size of the matrix to be analyzed
    
    type - or-ed flags giving information about the matrix type, as described for analyze(M,size,type)
    
    Throws:
    
    java.lang.IllegalArgumentException - if the CRS data structures are inconsistent, or the matrix type is not supported by the solver
    
    NumericalException - if the analysis failed for numeric reasons
  - factor
```
void factor()
```
    Factors a previously analyzed matrix.
    
    Throws:
    
    java.lang.IllegalStateException - if no previous call to analyze has been made.
    
    NumericalException - if the factor failed for numeric reasons.
  - factor
```
void factor(double[] vals)
```
    Factors a previously analyzed matrix, using the numeric values supplied by vals. These must be ordered in the same way as those supplied to the most recent call to analyze().
    
    Parameters:
    
    vals - non-zero matrix element values
    
    Throws:
    
    java.lang.IllegalStateException - if no previous call to analyze has been made
    
    java.lang.IllegalArgumentException - if the number of supplied values is less than the number of non-zero elements in the analyzed matrix
    
    NumericalException - if the factor failed for numeric reasons.
  - analyzeAndFactor
```
void analyzeAndFactor(Matrix M)
```
    Factors a matrix. This is equivalent to the two calls
```
   analyze (M, M.rowSize(), 0)
   factor()
 
```
    Parameters:
    
    M - matrix to factor
    
    Throws:
    
    java.lang.IllegalArgumentException - if the matrix is not square, or general matrices are not supported by the solver.
    
    NumericalException - if the analysis or factoring failed for numeric reasons.
  - solve
```
void solve(VectorNd x,
           VectorNd b)
```
    Solves the system
```
  M x = b
 
```
    where M was specified using previous calls to analyze or factor.
    Parameters:
    
    x - vector in which result is returned
    
    b - right hand vector of matrix equation
    
    Throws:
    
    NumericalException - if the solve failed for numeric reasons.
    
    java.lang.IllegalStateException - if no previous call to analyze or factor has been made.
  - solve
```
void solve(double[] x,
           double[] b)
```
    Solves the system
```
  M x = b
 
```
    where the solution and right hand side are supplied using double[] objects.
    Parameters:
    
    x - vector in which result is returned
    
    b - right hand vector of matrix equation
    
    Throws:
    
    NumericalException - if the solve failed for numeric reasons.
    
    java.lang.IllegalStateException - if the matrix has not been factored
  - hasIterativeSolves
```
default boolean hasIterativeSolves()
```
    Returns true if this solver supports iterative solving, using a recent directly-factored matrix as a preconditioner. If it does, all the methods described by DirectSolver.IterativeMethod are available, as are the settings setIterativeMethod(maspack.solvers.DirectSolver.IterativeMethod), setIterativeMaxSolves(int) and setIterativeTolerance(double).
    
    Returns:
    
    true if iterative solving is available
  - setIterativeMethod
```
default void setIterativeMethod(DirectSolver.IterativeMethod method)
```
    Sets the method used by iterativeSolve(double[], double[], double[]). The default is DirectSolver.IterativeMethod.GMRES. Has no effect if hasIterativeSolves() returns false.
    
    Parameters:
    
    method - iterative method
  - getIterativeMethod
```
default DirectSolver.IterativeMethod getIterativeMethod()
```
    Queries the method used by iterativeSolve(double[], double[], double[]).
    
    Returns:
    
    iterative method
  - setIterativeMaxSolves
```
default void setIterativeMaxSolves(int max)
```
    Sets the maximum number of preconditioner solves allowed for iterativeSolve(double[], double[], double[]), beyond which it fails. The default is DEFAULT_ITERATIVE_MAX_SOLVES. Has no effect if hasIterativeSolves() returns false.
    
    Parameters:
    
    max - maximum number of preconditioner solves
  - getIterativeMaxSolves
```
default int getIterativeMaxSolves()
```
    Queries the maximum number of preconditioner solves allowed for iterativeSolve(double[], double[], double[]).
    
    Returns:
    
    maximum number of preconditioner solves
  - setIterativeTolerance
```
default void setIterativeTolerance(double tol)
```
    Sets the tolerance for iterativeSolve(double[], double[], double[]): the iteration succeeds when the relative residual ||b - M x||/||b|| is at most tol. The default is DEFAULT_ITERATIVE_TOLERANCE. Has no effect if hasIterativeSolves() returns false.
    
    Parameters:
    
    tol - relative residual tolerance
  - getIterativeTolerance
```
default double getIterativeTolerance()
```
    Queries the tolerance for iterativeSolve(double[], double[], double[]).
    
    Returns:
    
    relative residual tolerance
  - getLastIterativeSolves
```
default int getLastIterativeSolves()
```
    Returns the number of preconditioner solves performed by the most recent call to iterativeSolve(double[], double[], double[]), or -1 if this is not available.
    
    Returns:
    
    number of preconditioner solves
  - getLastIterativeResidual
```
default double getLastIterativeResidual()
```
    Returns the relative residual ||b - M x||/||b|| obtained by the most recent call to iterativeSolve(double[], double[], double[]), or -1 if this is not available.
    
    Returns:
    
    relative residual of the most recent iterative solve
  - iterativeSolve
```
default int iterativeSolve(double[] vals,
                           double[] x,
                           double[] b)
```
    Solves the system
```
  M x = b
 
```
    iteratively, using the most recent factorization as a preconditioner and the matrix values supplied by vals. If the current values are close to those associated with the factorization, this can be considerably faster than an explicit factor() and solve(). The method, maximum number of preconditioner solves and tolerance are set by setIterativeMethod(maspack.solvers.DirectSolver.IterativeMethod), setIterativeMaxSolves(int) and setIterativeTolerance(double).
    This method is only available if hasIterativeSolves() returns true; otherwise, it returns 0 and the caller should fall back on factoring and solving directly.
    Parameters:
    
    vals - current values of the non-zero matrix elements, in the same ordering as that supplied to analyze()
    
    x - vector in which the result is returned
    
    b - right hand vector of the matrix equation
    
    Returns:
    
    number of iterations performed, or a value <= 0 if the iterative solve was not performed or did not succeed
  - iterativeSolve
```
@Deprecated
default int iterativeSolve(double[] vals,
                                       double[] x,
                                       double[] b,
                                       int tolExp)
```
    Deprecated. use setIterativeTolerance(double) and iterativeSolve(double[],double[],double[]) instead
    
    Performs an iterative solve with a relative residual tolerance of 10^-tolExp, leaving the tolerance set by setIterativeTolerance(double) unchanged.
    
    Parameters:
    
    vals - current values of the non-zero matrix elements
    
    x - vector in which the result is returned
    
    b - right hand vector of the matrix equation
    
    tolExp - (negative) exponent of the desired relative residual
    
    Returns:
    
    number of iterations performed, or a value <= 0 if the iterative solve was not performed or did not succeed
  - hasMultipleRhsSolves
```
default boolean hasMultipleRhsSolves()
```
    Returns true if this solver can solve for multiple right hand sides, using solve(X,B,nrhs).
    
    Returns:
    
    true if multiple right hand sides are supported
  - solve
```
default void solve(double[] X,
                   double[] B,
                   int nrhs)
```
    Solves the system
```
  M X = B
 
```
    for a set of right hand sides B, where the number of right hand sides is given by nrhs. Both X and B should be stored in column major order. This method is only available if hasMultipleRhsSolves() returns true.
    Parameters:
    
    X - returns the solutions, in column major order
    
    B - supplies the right hand sides, in column major order
    
    nrhs - number of right hand sides
    
    Throws:
    
    java.lang.UnsupportedOperationException - if multiple right hand sides are not supported
    
    java.lang.IllegalStateException - if the matrix has not been factored
    
    NumericalException - if the solve failed for numeric reasons
  - getNumNegEigenvalues
```
default int getNumNegEigenvalues()
```
    If possible, returns the number of negative eigenvalues detected during the most recent factorization of a symmetric indefinite matrix. For matrices which are not symmetric indefinite, or for solvers which do not compute the inertia, -1 is returned.
    
    Returns:
    
    number of negative eigenvalues, or -1 if not available
  - getNumPosEigenvalues
```
default int getNumPosEigenvalues()
```
    If possible, returns the number of positive eigenvalues detected during the most recent factorization of a symmetric indefinite matrix. For matrices which are not symmetric indefinite, or for solvers which do not compute the inertia, -1 is returned.
    
    Returns:
    
    number of positive eigenvalues, or -1 if not available
  - getNumPerturbedPivots
```
default int getNumPerturbedPivots()
```
    If possible, returns the number of pivot perturbations that were required during the most recent numeric factorization (i.e., during the last factor() call). Pivot perturbation generally indicates a singular, or very nearly singular, matrix. If the solver does not report pivot perturbations, -1 is returned.
    
    Returns:
    
    number of perturbed pivots, or -1 if not supported
  - getMaxRefinementSteps
```
default int getMaxRefinementSteps()
```
    Returns the maximum number of iterative refinement steps that this solver will perform after a solve, or 0 if iterative refinement is not supported.
    
    Returns:
    
    maximum number of iterative refinement steps
    
    See Also:
    
    setMaxRefinementSteps(int)
  - setMaxRefinementSteps
```
default void setMaxRefinementSteps(int nsteps)
```
    Sets the maximum number of iterative refinement steps that this solver should perform after a solve. Setting this to 0 disables iterative refinement. Solvers which do not support iterative refinement ignore this setting.
    
    Parameters:
    
    nsteps - maximum number of iterative refinement steps
    
    See Also:
    
    getMaxRefinementSteps()
  - residual
```
static double residual(int[] rowOffs,
                       int[] colIdxs,
                       double[] vals,
                       int size,
                       double[] x,
                       double[] b,
                       boolean symmetric)
```
    Computes the norm of the residual
```
   M x - b
 
```
    for given values of M, x, and b, where the values of M are given in compressed row storage (CRS) format with 1-based indices.
    Parameters:
    
    rowOffs - matrix row offsets (CRS format)
    
    colIdxs - non-zero element column indices (CRS format)
    
    vals - non-zero element values (CRS format)
    
    size - size of the matrix
    
    x - supplies the solution value
    
    b - supplies the right-hand side
    
    symmetric - if true, assumes that the arguments define only the upper triangular portion of a symmetric matrix
    
    Returns:
    
    norm of the residual
    
    Throws:
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size.
  - dispose
```
void dispose()
```
    Releases all internal resources allocated by this solver.

Interface DirectSolver

Nested Class Summary

Field Summary

Method Summary

Field Detail

UNSET

ANALYZED

FACTORED

DEFAULT_ITERATIVE_TOLERANCE

DEFAULT_ITERATIVE_MAX_SOLVES

Method Detail

getState

getErrorMessage

getNumNonZerosInFactors

analyze

analyze

factor

factor

analyzeAndFactor

solve

solve

hasIterativeSolves

setIterativeMethod

getIterativeMethod

setIterativeMaxSolves

getIterativeMaxSolves

setIterativeTolerance

getIterativeTolerance

getLastIterativeSolves

getLastIterativeResidual

iterativeSolve

iterativeSolve

hasMultipleRhsSolves

solve

getNumNegEigenvalues

getNumPosEigenvalues

getNumPerturbedPivots

getMaxRefinementSteps

setMaxRefinementSteps

residual

dispose