DirectSolverBase (Artisynth API documentation)

java.lang.Object
- maspack.solvers.DirectSolverBase

All Implemented Interfaces:

DirectSolver

Direct Known Subclasses:

AccelerateSolver, MumpsSolver, PardisoSolver
```
public abstract class DirectSolverBase
extends java.lang.Object
implements DirectSolver
```
Base class for DirectSolver implementations which are implemented natively and which accept their matrices in compressed row storage (CRS) format with 1-based indices. It supplies the solver state machine, the buffers used to extract CRS data from Matrix objects, and the analyze, factor and solve methods which are common to such solvers, leaving subclasses to supply the native calls themselves through a small number of hook methods:
- createSolverHandle() and releaseSolverHandle(long), which create and destroy the native solver instance;
- setMatrixNative(double[], int[], int[], int, int, int), factorMatrixNative(double[]) and solveNative(double[], double[], int), which implement the three solution phases;
- errorMessage(int) and getSolverName(), which are used to describe failures.
Solver specific settings (reorder methods, pivot perturbation, etc.), and the static methods which load the native libraries and determine solver availability, are left entirely to the subclasses. Note in particular that the fields which record whether a native library has been loaded must be declared in the subclass, since static fields are not polymorphic and sharing them here would cause one solver's availability to be reported for another.

Nested Class Summary
- Nested classes/interfaces inherited from interface maspack.solvers.DirectSolver
  DirectSolver.IterativeMethod

Field Summary

Fields
Modifier and Type Field and Description

static int DEFAULT_GMRES_RESTART
Default restart length for GMRES iterative solves.
- Fields inherited from interface maspack.solvers.DirectSolver
  ANALYZED, DEFAULT_ITERATIVE_MAX_SOLVES, DEFAULT_ITERATIVE_TOLERANCE, FACTORED, UNSET

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_GMRES_RESTART` Default restart length for GMRES iterative solves.

Constructor Summary

Constructors
Constructor and Description

DirectSolverBase()

Constructors
Constructor and Description
`DirectSolverBase()`

Method Summary

All Methods Static Methods Instance Methods Concrete 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`.
`void`	`finalize()`
`static int`	`getDefaultNumThreads()` Returns the default number of threads which solvers are assigned when they are created.
`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.
`int`	`getGmresRestart()` Queries the GMRES restart length.
`int`	`getIterativeMaxSolves()` Queries the maximum number of preconditioner solves allowed for `DirectSolver.iterativeSolve(double[], double[], double[])`.
`DirectSolver.IterativeMethod`	`getIterativeMethod()` Queries the method used by `DirectSolver.iterativeSolve(double[], double[], double[])`.
`double`	`getIterativeTolerance()` Queries the tolerance for `DirectSolver.iterativeSolve(double[], double[], double[])`.
`double`	`getLastIterativeResidual()` Returns the relative residual `\|\|b - M x\|\|/\|\|b\|\|` obtained by the most recent call to `DirectSolver.iterativeSolve(double[], double[], double[])`, or -1 if this is not available.
`int`	`getLastIterativeSolves()` Returns the number of preconditioner solves performed by the most recent call to `DirectSolver.iterativeSolve(double[], double[], double[])`, or -1 if this is not available.
`int`	`getNumThreads()` Returns the number of threads that this solver is using.
`int`	`getPhysicalCoreCount()` Returns the number of physical CPU cores on this machine, as opposed to logical/hyperthreaded processors -- queried natively (see `getPhysicalCoreCountNative()`) since Java has no portable way to tell the two apart, and hyperthreads provide little to no benefit for compute-bound work like sparse factorization (see `maxThreadsNnz(int, int)`).
`int`	`getState()` Returns the current state of this solver, which is one of `UNSET`, `ANALYZED`, or `FACTORED`.
`static boolean`	`getUseCriticalArrayAccess()` Queries whether native solvers use JNI critical array access for their iterative solves.
`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`, where the values of `M` are given in compressed row storage (CRS) format.
`static void`	`setDefaultNumThreads(int num)` Sets the default number of threads which solvers are assigned when they are created.
`void`	`setGmresRestart(int restart)` Sets the restart length used when the iterative method is GMRES.
`void`	`setIterativeMaxSolves(int max)` Sets the maximum number of preconditioner solves allowed for `DirectSolver.iterativeSolve(double[], double[], double[])`, beyond which it fails.
`void`	`setIterativeMethod(DirectSolver.IterativeMethod method)` Sets the method used by `DirectSolver.iterativeSolve(double[], double[], double[])`.
`void`	`setIterativeTolerance(double tol)` Sets the tolerance for `DirectSolver.iterativeSolve(double[], double[], double[])`: the iteration succeeds when the relative residual `\|\|b - M x\|\|/\|\|b\|\|` is at most `tol`.
`void`	`setNumThreads(int num)` Sets the number of threads that this solver should use.
`static void`	`setUseCriticalArrayAccess(boolean enable)` Sets whether native solvers use JNI critical array access (`GetPrimitiveArrayCritical`) to transfer array data for the iterative (GMRES or CGS) solves performed by their native wrappers.
`void`	`solve(double[] x, double[] b)` Solves the system
`void`	`solve(double[] X, double[] B, int nrhs)` Solves the system
`void`	`solve(VectorNd x, VectorNd b)` Solves the system

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface maspack.solvers.DirectSolver
getMaxRefinementSteps, getNumNegEigenvalues, getNumNonZerosInFactors, getNumPerturbedPivots, getNumPosEigenvalues, hasIterativeSolves, hasMultipleRhsSolves, iterativeSolve, iterativeSolve, residual, setMaxRefinementSteps

- Field Detail
  - DEFAULT_GMRES_RESTART
```
public static final int DEFAULT_GMRES_RESTART
```
    Default restart length for GMRES iterative solves.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DirectSolverBase
```
public DirectSolverBase()
```
- Method Detail
  - getState
```
public int getState()
```
    Returns the current state of this solver, which is one of UNSET, ANALYZED, or FACTORED.
    
    Specified by:
    
    getState in interface DirectSolver
    
    Returns:
    
    state of this solver
  - getErrorMessage
```
public 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.
    
    Specified by:
    
    getErrorMessage in interface DirectSolver
    
    Returns:
    
    most recent error message, if any
  - setDefaultNumThreads
```
public static void setDefaultNumThreads(int num)
```
    Sets the default number of threads which solvers are assigned when they are created. The results are undefined if this number exceeds the maximum number of threads available on the system. Setting num to a value <= 0 will reset the number of threads to the default used by OpenMP, which is typically the value stored in the environment variable OMP_NUM_THREADS.
    Note: this setting is shared by all solvers derived from DirectSolverBase, since the thread pools which they use (OpenMP and the threaded BLAS) are properties of the process rather than of an individual solver.
    
    Parameters:
    
    num - default number of threads to use
    
    See Also:
    
    getDefaultNumThreads()
  - getDefaultNumThreads
```
public static int getDefaultNumThreads()
```
    Returns the default number of threads which solvers are assigned when they are created.
    
    Returns:
    
    default number of threads
    
    See Also:
    
    setDefaultNumThreads(int)
  - setNumThreads
```
public void setNumThreads(int num)
```
    Sets the number of threads that this solver should use. The results are undefined if this number exceeds the maximum number of threads available on the system. Setting num to a value <= 0 will reset the number of threads to myNominalNumThreads, i.e., whatever this solver would have been assigned when created: the thread pool's own natural default, overridden by getDefaultNumThreads() if positive, and capped by getPhysicalCoreCount().
    Note: the thread count is a property of the process rather than of an individual solver, so changing it here affects all solvers running in the same process. It should also not be changed in between the analyze, factor and solve phases.
    A positive value here is also recorded as the highest priority input to automatic thread throttling (see maxThreadsNnz(int, int)), taking precedence over everything else, including getPhysicalCoreCount().
    
    Parameters:
    
    num - number of threads to use
    
    See Also:
    
    getNumThreads()
  - getNumThreads
```
public int getNumThreads()
```
    Returns the number of threads that this solver is using. By default, this is myNominalNumThreads -- the thread pool's own natural default (typically OMP_NUM_THREADS), overridden by getDefaultNumThreads() if positive, and capped by getPhysicalCoreCount().
    
    Returns:
    
    number of threads being used
    
    See Also:
    
    setNumThreads(int)
  - getPhysicalCoreCount
```
public int getPhysicalCoreCount()
```
    Returns the number of physical CPU cores on this machine, as opposed to logical/hyperthreaded processors -- queried natively (see getPhysicalCoreCountNative()) since Java has no portable way to tell the two apart, and hyperthreads provide little to no benefit for compute-bound work like sparse factorization (see maxThreadsNnz(int, int)). Falls back to Runtime.availableProcessors() (logical count, with a printed warning) if native detection runs but fails, or returns -1 if this solver's native library predates getPhysicalCoreCountNative() entirely -- callers should treat that as "undetermined" and skip whatever they would otherwise have capped by it, rather than treating -1 as a literal core count.
    On Arm-based Macs with both performance and efficiency cores, the native code shared by the MUMPS and Accelerate solvers counts only the performance cores. This is tuned for MUMPS, whose use of Accelerate's BLAS (which runs on the chip's shared matrix units) gains little from extra threads and is slowed down by the efficiency cores. It is not true of solvers in general: Pardiso, under Rosetta, is fastest with all cores.
    Queried once and cached for the life of the process: this is not meticulously synchronized against concurrent first calls from different solver instances, but the query is cheap, side-effect-free and deterministic, so a benign race only risks redoing it once, never an inconsistent result.
    
    Returns:
    
    physical core count on this machine, or -1 if undetermined
  - setIterativeMethod
```
public void setIterativeMethod(DirectSolver.IterativeMethod method)
```
    Sets the method used by DirectSolver.iterativeSolve(double[], double[], double[]). The default is DirectSolver.IterativeMethod.GMRES. Has no effect if DirectSolver.hasIterativeSolves() returns false.
    
    Specified by:
    
    setIterativeMethod in interface DirectSolver
    
    Parameters:
    
    method - iterative method
  - getIterativeMethod
```
public DirectSolver.IterativeMethod getIterativeMethod()
```
    Queries the method used by DirectSolver.iterativeSolve(double[], double[], double[]).
    
    Specified by:
    
    getIterativeMethod in interface DirectSolver
    
    Returns:
    
    iterative method
  - setIterativeMaxSolves
```
public void setIterativeMaxSolves(int max)
```
    Sets the maximum number of preconditioner solves allowed for DirectSolver.iterativeSolve(double[], double[], double[]), beyond which it fails. The default is DirectSolver.DEFAULT_ITERATIVE_MAX_SOLVES. Has no effect if DirectSolver.hasIterativeSolves() returns false.
    
    Specified by:
    
    setIterativeMaxSolves in interface DirectSolver
    
    Parameters:
    
    max - maximum number of preconditioner solves
  - getIterativeMaxSolves
```
public int getIterativeMaxSolves()
```
    Queries the maximum number of preconditioner solves allowed for DirectSolver.iterativeSolve(double[], double[], double[]).
    
    Specified by:
    
    getIterativeMaxSolves in interface DirectSolver
    
    Returns:
    
    maximum number of preconditioner solves
  - setIterativeTolerance
```
public void setIterativeTolerance(double tol)
```
    Sets the tolerance for DirectSolver.iterativeSolve(double[], double[], double[]): the iteration succeeds when the relative residual ||b - M x||/||b|| is at most tol. The default is DirectSolver.DEFAULT_ITERATIVE_TOLERANCE. Has no effect if DirectSolver.hasIterativeSolves() returns false.
    
    Specified by:
    
    setIterativeTolerance in interface DirectSolver
    
    Parameters:
    
    tol - relative residual tolerance
  - getIterativeTolerance
```
public double getIterativeTolerance()
```
    Queries the tolerance for DirectSolver.iterativeSolve(double[], double[], double[]).
    
    Specified by:
    
    getIterativeTolerance in interface DirectSolver
    
    Returns:
    
    relative residual tolerance
  - setGmresRestart
```
public void setGmresRestart(int restart)
```
    Sets the restart length used when the iterative method is GMRES. The default is DEFAULT_GMRES_RESTART.
    
    Parameters:
    
    restart - GMRES restart length
  - getGmresRestart
```
public int getGmresRestart()
```
    Queries the GMRES restart length.
    
    Returns:
    
    GMRES restart length
  - getLastIterativeSolves
```
public int getLastIterativeSolves()
```
    Returns the number of preconditioner solves performed by the most recent call to DirectSolver.iterativeSolve(double[], double[], double[]), or -1 if this is not available.
    
    Specified by:
    
    getLastIterativeSolves in interface DirectSolver
    
    Returns:
    
    number of preconditioner solves
  - getLastIterativeResidual
```
public double getLastIterativeResidual()
```
    Returns the relative residual ||b - M x||/||b|| obtained by the most recent call to DirectSolver.iterativeSolve(double[], double[], double[]), or -1 if this is not available.
    
    Specified by:
    
    getLastIterativeResidual in interface DirectSolver
    
    Returns:
    
    relative residual of the most recent iterative solve
  - setUseCriticalArrayAccess
```
public static void setUseCriticalArrayAccess(boolean enable)
```
    Sets whether native solvers use JNI critical array access (GetPrimitiveArrayCritical) to transfer array data for the iterative (GMRES or CGS) solves performed by their native wrappers. The value, right-hand side and solution arrays are then copied directly between Java and native storage, avoiding extra copies and allocation of the value array. Critical access is held only while copying, never during the solve, since on JDK 21 and earlier it defers garbage collection for all threads. The default is true. Currently used by PardisoSolver and MumpsSolver.
    
    Parameters:
    
    enable - if true, use critical array access
  - getUseCriticalArrayAccess
```
public static boolean getUseCriticalArrayAccess()
```
    Queries whether native solvers use JNI critical array access for their iterative solves. See setUseCriticalArrayAccess(boolean).
    
    Returns:
    
    true if critical array access is used
  - analyze
```
public 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.
    
    Specified by:
    
    analyze in interface DirectSolver
    
    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
  - analyze
```
public 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.
    
    Specified by:
    
    analyze in interface DirectSolver
    
    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)
  - factor
```
public void factor()
```
    Factors a previously analyzed matrix.
    
    Specified by:
    
    factor in interface DirectSolver
  - factor
```
public 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().
    
    Specified by:
    
    factor in interface DirectSolver
    
    Parameters:
    
    vals - non-zero matrix element values
  - analyzeAndFactor
```
public void analyzeAndFactor(Matrix M)
```
    Factors a matrix. This is equivalent to the two calls
```
   analyze (M, M.rowSize(), 0)
   factor()
 
```
    Specified by:
    
    analyzeAndFactor in interface DirectSolver
    
    Parameters:
    
    M - matrix to factor
  - solve
```
public void solve(VectorNd x,
                  VectorNd b)
```
    Solves the system
```
  M x = b
 
```
    where M was specified using previous calls to analyze or factor.
    Specified by:
    
    solve in interface DirectSolver
    
    Parameters:
    
    x - vector in which result is returned
    
    b - right hand vector of matrix equation
  - solve
```
public void solve(double[] x,
                  double[] b)
```
    Solves the system
```
  M x = b
 
```
    where the solution and right hand side are supplied using double[] objects.
    Specified by:
    
    solve in interface DirectSolver
    
    Parameters:
    
    x - vector in which result is returned
    
    b - right hand vector of matrix equation
  - solve
```
public 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 DirectSolver.hasMultipleRhsSolves() returns true.
    Specified by:
    
    solve in interface DirectSolver
    
    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
  - residual
```
public 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, where the values of M are given in compressed row storage (CRS) format. This is a convenience wrapper for DirectSolver.residual(int[], int[], double[], int, double[], double[], boolean).
    
    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
  - dispose
```
public void dispose()
```
    Releases all internal resources allocated by this solver.
    
    Specified by:
    
    dispose in interface DirectSolver
  - finalize
```
public void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object

Class DirectSolverBase

Nested Class Summary

Nested classes/interfaces inherited from interface maspack.solvers.DirectSolver

Field Summary

Fields inherited from interface maspack.solvers.DirectSolver

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface maspack.solvers.DirectSolver

Field Detail

DEFAULT_GMRES_RESTART

Constructor Detail

DirectSolverBase

Method Detail

getState

getErrorMessage

setDefaultNumThreads

getDefaultNumThreads

setNumThreads

getNumThreads

getPhysicalCoreCount

setIterativeMethod

getIterativeMethod

setIterativeMaxSolves

getIterativeMaxSolves

setIterativeTolerance

getIterativeTolerance

setGmresRestart

getGmresRestart

getLastIterativeSolves

getLastIterativeResidual

setUseCriticalArrayAccess

getUseCriticalArrayAccess

analyze

analyze

factor

factor

analyzeAndFactor

solve

solve

solve

residual

dispose

finalize