PardisoSolver (Artisynth API documentation)

java.lang.Object
- maspack.solvers.PardisoSolver

All Implemented Interfaces:

DirectSolver
```
public class PardisoSolver
extends java.lang.Object
implements DirectSolver
```
JNI interface to the Pardiso sparse solver. Usage of Pardiso is usually dividing into three phases:
- An analyze phase that reorder the matrix to reduce fill-in and performs a symbolic factorization;
- A factor phase that numerically factors the matrix into a sutiable decomposition;
- A solve phase that uses the factorization to solve M x = b for some given right-hand side b.
Typical usage of this solver is exemplified by the following call sequence:
```
    Matrix M;                 // matrix to be solved
    VectorNd x, b;            // solution vector and right-hand side
    
    PardisoSolver solver = new PardisoSolver();
    solver.analyze (M, M.rowSize(), Matrix.SYMMETRIC); // symbolic factorization
    solver.factor();          // numeric factorization
    solver.solve (x, b);      // solution using factorization
    
    solver.dispose();         // release resources when we are done
 
```
It is very important to call dispose() when the solver is no longer required, in order to release internal native resources that have been allocated for the Pardiso native code. It is not necessary to call the analyze() and factor() methods every time a solution is required. analyze() needs to be called only when a matrix is first presented to the solver or when its sparsity structure changes. factor() needs to be called only when the numeric values of the matrix change. For a given set of numeric values, once factor() has been called, solve() can be called as many times as desired to generate solutions for different right-hand sides.
It is also possible to avoid using a Matrix object, and instead call analyze() and factor() with compressed row storage (CRS) data structures directly, as in
```
    solver.analyze (vals, colIdxs, rowOffs, size, matrixType);
    solver.factor (vals);
 
```
Here vals, colIdxs, and rowOffs descrive the sparse matrix structure using the CRS format as described in the documentation for Matrix.setCRSValues. Pardiso also supports iterative solving, using preconditioned CGS iteration. The preconditioner is supplied by the most recent matrix factorization. If the current matrix values are close to those associated with the factorization, then the resulting iterative solution time can be considerably faster than the alternative combination of a factor() and a solve(). There are several iterativeSolve() methods, which obtain the current matrix values either directly as an input argument, or from a Matrix object supplied through the analyze() methods. When an iterativeSolve() method is successful, it returns a positive number indicating the number of iterations performed. A possible call sequence is as follows:
```
 
    solver.analyze (M, M.rowSize(), Matrix.SYMMETRIC); // symbolic factorization
    solver.factor();          // numeric factorization
    while (computing) {
       ... update matrix values and right-hand side b ...;
       if (solver.iterativeSolve(x, b) <= 0) {
          // iterative solve failed; do explicit factor and solve
          solver.factor();
          solver.solve (x, b);
       }
    }
 
 
```
A more sophisticated version of the above code will also call factor() and solve() when the compute time associated with iterativeSolve() exceeds a certain threshold. After refactorization, the time required by iterativeSolve() should be reduced since the next set of matrix values will again (presumably) be close to those associated with the factorization. This functionality is provided by the autoFactorAndSolve() methods:
```
    solver.analyze (M, M.rowSize(), Matrix.SYMMETRIC); // symbolic factorization
    solver.factor();          // numeric factorization
    while (computing) {
       ... update matrix values and right-hand side b ...;
       // automatically choose between iterative and direct solving
       solver.autoFactorAndSolve (x, b);
    }
 
```

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`PardisoSolver.ReorderMethod` Describes the reorder methods that can be used during the analyze phase to reduce factorization fill-in.

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 boolean`	`DEFAULT_SHOW_PERTURBED_PIVOTS`
`static int`	`FACTORED` Indicates that a matrix has been set, analyzed, and numerically factored for this solver.
`static boolean`	`printThreadInfo`
`static boolean`	`supportsMultipleRhs`
`static int`	`UNSET` Indicates that no matrix is currently set for this solver.

Constructor Summary

Constructors
Constructor and Description

PardisoSolver()
Creates a new PardisoSolver object.

Constructors
Constructor and Description
`PardisoSolver()` Creates a new PardisoSolver object.

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)` Sets the matrix associated with this solver and performs symbolic analysis on it.
`void`	`analyze(Matrix M, int size, int type)` Sets the matrix associated with this solver and performs symbolic analysis on it.
`void`	`analyzeAndFactor(Matrix M)` Convenience method that sets the matrix associated with this solver, performs symbolic analysis on it, and factors it.
`void`	`autoFactorAndSolve(double[] x, double[] b, int tolExp)` Implementation of `autoFactorAndSolve(maspack.matrix.VectorNd,maspack.matrix.VectorNd,int)` that uses `double[]` objects to store to the result and right-hand side.
`void`	`autoFactorAndSolve(VectorNd x, VectorNd b, int tolExp)` Calls `factor()` and `solve(double[],double[])` together, or, if `tolExp` is positive, automatically determines when to call `iterativeSolve(maspack.matrix.VectorNd,maspack.matrix.VectorNd,int)` with the specific `tolExp`instead, depending on whether the matrix is factored and if it is estimated that `iterativeSolve` will save time.
`void`	`dispose()` Releases the native resources used by this solver.
`void`	`factor()` Performs a numeric factorization of the matrix associated with this solver, using the current numeric values contained within the matrix that was supplied by a previous call to `analyze(Matrix,int,int)` or `analyzeAndFactor(Matrix)`.
`void`	`factor(double[] vals)` Performs a numeric factorization of the most recently analyzed matrix solver using the supplied numeric values.
`void`	`finalize()`
`int`	`getAnalysisMemoryUsage()` Returns the amount of permanent memory (in kbytes) that was allocated during the most recent `analyze()` call.
`boolean`	`getApplyScaling()` Returns whether or not matrix scaling is enabled.
`boolean`	`getApplyWeightedMatchings()` Returns whether or not weighted matchings are enabled.
`static int`	`getDefaultNumThreads()` Returns the default number of threads that Pardiso is assigned when a `PardisoSolver` is created.
`java.lang.String`	`getErrorMessage()` Returns a message describing the reason for failure of the most recent call to any of the `analyze()`, `factor()`, or `iterativeSolve()` methods, or `null` if the method succeeded.
`int`	`getFactorSolveMemoryUsage()` Returns the total memory consumption (in kbytes) required for the `factor()` and `solve()` calls.
`static java.lang.String`	`getInitErrorMessage()` Returns a message describing an error that occurred during initialization, or `null` if no error occurred.
`boolean`	`getMatrixChecking()` Returns true if matrix checking is enabled.
`int`	`getMaxRefinementSteps()` Returns the maximum number of iterative refinement steps that Pardiso should perform after a solve.
`int`	`getMessageLevel()` Returns the message level for the Pardiso native code.
`int`	`getNumNegEigenvalues()` Returns the number of negative eigenvalues that were detected during the most recent numeric factorization of a symmetric indefinite matrix (i.e., during the last `factor()` call).
`int`	`getNumNonZerosInFactors()` Returns the number of non-zeros elements in the factorization.
`int`	`getNumPerturbedPivots()` Returns the number of pivot perturbations that were required during the last recent numeric factorization (i.e., during the last `factor()` call).
`int`	`getNumPosEigenvalues()` Returns the number of positive eigenvalues that were detected during the most recent numeric factorization of a symmetric indefinite matrix (i.e., during the last `factor()` call).
`int`	`getNumRefinementSteps()` Returns the number of iterative refinement steps that Pardiso actually performed during the most call to `solve()`.
`int`	`getNumThreads()` Returns the number of threads that Pardiso should use.
`int`	`getPeakAnalysisMemoryUsage()` Returns the peak amount of memory (in kbytes) that was used during the most recent `analyze()` call.
`int`	`getPivotPerturbation()` Returns the size of the perturbation that should be used to resolve zero-pivots, expressed as a negative power-of-ten exponent.
`PardisoSolver.ReorderMethod`	`getReorderMethod()` Gets the reorder method that is used during the analyze phase to reduced factorization fill-in.
`static boolean`	`getShowPerturbedPivots()` Queries whether the "num perturbed pivots" message is enabled.
`int`	`getSPDZeroPivot()` If the solver detects a zero or negative pivot for an SPD matrix, this method returns the row number where the first zero or negative pivot was detected.
`int`	`getState()` Returns the current stateface for this solver.
`boolean`	`getUse2x2Pivoting()` Returns whether or not 2 x 2 pivoting is enabled.
`boolean`	`hasAutoIterativeSolving()` Returns true if this solver supports automatic iterative solving using a recent directly-factored matrix as a preconditioner.
`static boolean`	`isAvailable()` Returns true if the Pardiso solver is available.
`int`	`iterativeSolve(double[] vals, double[] x, double[] b, int tolExp)` Attempts to use preconditioned CGS iteration to solve M x = b for a given right-hand side `b`.
`int`	`iterativeSolve(double[] x, double[] b, int tolExp)` Attempts to use preconditioned CGS iteration to solve M x = b for a given right-hand side `b`.
`int`	`iterativeSolve(VectorNd x, VectorNd b, int tolExp)` Implementation of `iterativeSolve(double[],double[],int)` that uses `VectorNd` objects to store to the result and right-hand side.
`static void`	`main(java.lang.String[] args)`
`double`	`residual(int[] rowOffs, int[] colIdxs, double[] vals, int size, double[] x, double[] b, boolean symmetric)` Computes the norm of the residual
`void`	`setApplyScaling(int enable)` Sets whether or not Pardiso should apply matrix scaling to its factorizations.
`void`	`setApplyWeightedMatchings(int enable)` Sets whether or not Pardiso should apply weighted matching to its factorizations.
`static void`	`setDefaultNumThreads(int num)` Sets the default number of threads that Pardiso is assigned when a `PardisoSolver` is created.
`void`	`setMatrixChecking(boolean enable)` Enables or disables checking of the integrity of the matrix data structures passed to Pardiso.
`void`	`setMaxRefinementSteps(int nsteps)` Sets the maximum number of iterative refinement steps that Pardiso should perform after a solve.
`void`	`setMessageLevel(int level)` Sets the message level for the Pardiso native code.
`void`	`setNumThreads(int num)` Sets the number of threads that Pardiso should use.
`void`	`setPivotPerturbation(int n)` Sets the size of the perturbation that should be used to resolve zero-pivots, expressed as a negative power-of-ten exponent.
`void`	`setReorderMethod(PardisoSolver.ReorderMethod method)` Sets the reorder method that should be used during the analyze phase to reduced factorization fill-in.
`static void`	`setShowPerturbedPivots(boolean enable)` Enables/disables the "num perturbed pivots" message (which usually indicates an ill-conditioned solve).
`void`	`setUse2x2Pivoting(int enable)` Sets whether or not Pardiso should use 2 x 2 Bunch and Kaufman pivoting (in addition to regular 1 x 1 pivoting) for symmetric indefinite matrices.
`void`	`solve(double[] x, double[] b)` Solves the matrix associated with this solver for x, given a specific right-hand side b.
`void`	`solve(double[] X, double[] B, int nrhs)` Solves the matrix associated with this solver for a set of vectors X, given a set of right-hand sides B.
`void`	`solve(VectorNd x, VectorNd b)` Solves the matrix associated with this solver for x, given a specific right-hand side b.
`void`	`systemExit(int code)` This method is a hook that gives us access to _exit(), which is is in turn needed to exit ArtiSynth on the MacBook Pro 8.2 version of Ubuntu, since otherwise the JVM exit process encounters a SEGV in XQueryExtension.

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

- Field Detail
  - printThreadInfo
```
public static boolean printThreadInfo
```
  - supportsMultipleRhs
```
public static boolean supportsMultipleRhs
```
  - DEFAULT_SHOW_PERTURBED_PIVOTS
```
public static boolean DEFAULT_SHOW_PERTURBED_PIVOTS
```
  - UNSET
```
public static final int UNSET
```
    Indicates that no matrix is currently set for this solver.
    
    See Also:
    
    Constant Field Values
  - ANALYZED
```
public static final int ANALYZED
```
    Indicates that a matrix has been set and analyzed for this solver.
    
    See Also:
    
    Constant Field Values
  - FACTORED
```
public static final int FACTORED
```
    Indicates that a matrix has been set, analyzed, and numerically factored for this solver.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PardisoSolver
```
public PardisoSolver()
```
    Creates a new PardisoSolver object.
- Method Detail
  - getState
```
public int getState()
```
    Returns the current stateface for this solver. Possible states are UNSET, ANALYZED, and FACTORED.
    
    Returns:
    
    state for this solver.
  - isAvailable
```
public static boolean isAvailable()
```
    Returns true if the Pardiso solver is available. A solver might not be available if the Pardiso native libraries cannot be loaded for some reason.
    
    Returns:
    
    true if Pardiso is available.
  - getInitErrorMessage
```
public static java.lang.String getInitErrorMessage()
```
    Returns a message describing an error that occurred during initialization, or null if no error occurred.
    
    Returns:
    
    initialization error message
  - analyze
```
public void analyze(Matrix M,
                    int size,
                    int type)
```
    Sets the matrix associated with this solver and performs symbolic analysis on it. The matrix is assumed to be square. After calling this method, the solver's state is set to ANALYZED.
    Normally the matrix is simply supplied by the argument M, unless the size arugment is less than M.rowSize(), in which case the matrix is taken to be the top-left diagonal sub-matrix of the indicated size. This solver retains a pointer to M until the next call to analyze() or analyzeAndFactor().
    The type of the matrix is given by type:
    
    Matrix.INDEFINITE
    
    will produce a general permuted L U decomposition;
    Matrix.SYMMETRIC
    
    will produce an L D L^T decomposition;
    Matrix.SPD
    
    will produce a Cholesky L L^T decomposition;
    
    Specified by:
    
    analyze in interface DirectSolver
    
    Parameters:
    
    M - supples the matrix to be analyzed
    
    size - size of the matrix to be analyzed
    
    type - type of the matrix to be analyzed
    
    Throws:
    
    java.lang.IllegalArgumentException - if the matrix is not square or if size is out of bounds
    
    NumericalException - if the matrix cannot be analyzed for numeric reasons.
  - factor
```
public void factor()
```
    Performs a numeric factorization of the matrix associated with this solver, using the current numeric values contained within the matrix that was supplied by a previous call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix). After calling this method, the solver's state is set to FACTORED.
    
    Specified by:
    
    factor in interface DirectSolver
    
    Throws:
    
    ImproperStateException - if not preceded by a call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix)
    
    NumericalException - if the matrix cannot be factored for numeric reasons.
  - factor
```
public void factor(double[] vals)
```
    Performs a numeric factorization of the most recently analyzed matrix solver using the supplied numeric values. After calling this method, the solver's state is set to FACTORED.
    
    Parameters:
    
    vals - non-zero matrix element values
    
    Throws:
    
    ImproperStateException - if this solver's state is UNSET or if the number of supplied values is less that the number of non-zero elements in the analyzed matrix.
    
    NumericalException - if the matrix cannot be factored for numeric reasons.
  - analyzeAndFactor
```
public void analyzeAndFactor(Matrix M)
```
    Convenience method that sets the matrix associated with this solver, performs symbolic analysis on it, and factors it. The matrix is assumed to be square and have a type of Matrix.INDEFINITE, meaning that Pardiso will produce an L U factorization. After calling this method, the solver's state is set to ANALYZED.
    
    Specified by:
    
    analyzeAndFactor in interface DirectSolver
    
    Parameters:
    
    M - matrix to factor
    
    Throws:
    
    NumericalException - if the matrix cannot be analyzed or factored for numeric reasons.
  - autoFactorAndSolve
```
public void autoFactorAndSolve(VectorNd x,
                               VectorNd b,
                               int tolExp)
```
    Calls factor() and solve(double[],double[]) together, or, if tolExp is positive, automatically determines when to call iterativeSolve(maspack.matrix.VectorNd,maspack.matrix.VectorNd,int) with the specific tolExpinstead, depending on whether the matrix is factored and if it is estimated that iterativeSolve will save time. It is assumed that a matrix was supplied to the solver using a previous call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix).
    
    Specified by:
    
    autoFactorAndSolve in interface DirectSolver
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    tolExp - if positive, enables iterative solving and provides the exponent of the stopping criterion
    
    Throws:
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size, or if topExp is negative.
    
    ImproperStateException - if not preceded by a call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix)
    
    NumericalException - if the matrix cannot be factored for numeric reasons
  - autoFactorAndSolve
```
public void autoFactorAndSolve(double[] x,
                               double[] b,
                               int tolExp)
```
    Implementation of autoFactorAndSolve(maspack.matrix.VectorNd,maspack.matrix.VectorNd,int) that uses double[] objects to store to the result and right-hand side.
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    tolExp - if positive, enables iterative solving and provides the exponent of the stopping criterion
    
    Throws:
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size, or if topExp is negative.
    
    ImproperStateException - if not preceded by a call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix)
    
    NumericalException - if the matrix cannot be factored for numeric reasons
  - setShowPerturbedPivots
```
public static void setShowPerturbedPivots(boolean enable)
```
    Enables/disables the "num perturbed pivots" message (which usually indicates an ill-conditioned solve).
    
    Parameters:
    
    enable - if true, enables the message
  - getShowPerturbedPivots
```
public static boolean getShowPerturbedPivots()
```
    Queries whether the "num perturbed pivots" message is enabled.
    
    Returns:
    
    true if the message is enabled
  - setDefaultNumThreads
```
public static void setDefaultNumThreads(int num)
```
    Sets the default number of threads that Pardiso is assigned when a PardisoSolver is 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.
    
    Parameters:
    
    num - default number of threads to use
    
    See Also:
    
    getDefaultNumThreads()
  - getDefaultNumThreads
```
public static int getDefaultNumThreads()
```
    Returns the default number of threads that Pardiso is assigned when a PardisoSolver is created.
    
    See Also:
    
    setDefaultNumThreads(int)
  - setNumThreads
```
public void setNumThreads(int num)
```
    Sets the number of threads that Pardiso 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 the default used by OpenMP, which is typically the value stored in the environment variable OMP_NUM_THREADS.
    Note: under the MKL version of Pardiso, changes to the thread number are applied globally to all instances of Pardiso running in the same process. Therefore, this method is of limited utility and does not allow different numbers of threads to be used by different PardisoSolver instances. Moreover, the thread number should not be changed in between the analyze, factor and solve phases.
    
    Parameters:
    
    num - number of threads to use
    
    See Also:
    
    getNumThreads()
  - getNumThreads
```
public int getNumThreads()
```
    Returns the number of threads that Pardiso should use. By default, this is the default number used by OpenMP, which is typically the value stored in the environment variable OMP_NUM_THREADS.
    
    Returns:
    
    number of threads Pardio should use
    
    See Also:
    
    setNumThreads(int)
  - setMaxRefinementSteps
```
public void setMaxRefinementSteps(int nsteps)
```
    Sets the maximum number of iterative refinement steps that Pardiso should perform after a solve. Setting this to 0 disables iterative refinement. Setting this to -1 will cause Pardiso to choose a default value appropriate to the matrix type. More iterative refinement steps will increase solution accuracy but slow down the solve.
    
    Parameters:
    
    nsteps - maximum number of iterative refinement steps
    
    See Also:
    
    getMaxRefinementSteps(), getNumRefinementSteps()
  - getMaxRefinementSteps
```
public int getMaxRefinementSteps()
```
    Returns the maximum number of iterative refinement steps that Pardiso should perform after a solve.
    
    Returns:
    
    maximum number of iterative refinement steps
    
    See Also:
    
    setMaxRefinementSteps(int), getNumRefinementSteps()
  - getNumRefinementSteps
```
public int getNumRefinementSteps()
```
    Returns the number of iterative refinement steps that Pardiso actually performed during the most call to solve().
    
    Returns:
    
    number of iterative refinement steps actually performed
    
    See Also:
    
    getMaxRefinementSteps(), setMaxRefinementSteps(int)
  - getReorderMethod
```
public PardisoSolver.ReorderMethod getReorderMethod()
```
    Gets the reorder method that is used during the analyze phase to reduced factorization fill-in.
    
    Returns:
    
    current reorder method
    
    See Also:
    
    setReorderMethod(maspack.solvers.PardisoSolver.ReorderMethod)
  - setReorderMethod
```
public void setReorderMethod(PardisoSolver.ReorderMethod method)
```
    Sets the reorder method that should be used during the analyze phase to reduced factorization fill-in. Setting the method to DEFAULT will cause Pardiso to choose its default value.
    
    Parameters:
    
    method - reorder method
    
    See Also:
    
    getReorderMethod()
  - setPivotPerturbation
```
public void setPivotPerturbation(int n)
```
    Sets the size of the perturbation that should be used to resolve zero-pivots, expressed as a negative power-of-ten exponent. The perturbation size is given by
```
  norm(M) 10^{-n}
 
```
    where n is the argument to this method and norm(M) is a norm of the matrix. Setting n this to -1 will cause Pardiso to choose a default value appropriate to the matrix type.
    Parameters:
    
    n - perturbation exponent
    
    See Also:
    
    getPivotPerturbation()
  - getPivotPerturbation
```
public int getPivotPerturbation()
```
    Returns the size of the perturbation that should be used to resolve zero-pivots, expressed as a negative power-of-ten exponent.
    
    Returns:
    
    perturbation exponent
    
    See Also:
    
    setPivotPerturbation(int)
  - setApplyScaling
```
public void setApplyScaling(int enable)
```
    Sets whether or not Pardiso should apply matrix scaling to its factorizations. Scaling can be applied to unsymmetric matrices, or to symmetric matrices if weighted matchings (see setApplyWeightedMatchings()) are also selected. Scaling is controlled by enable as follows: enable > 0 enables scaling, enable = 0 disables scaling, and enable < 0 causes the solver to choose a default value appropriate to the matrix type.
    
    Parameters:
    
    enable - enables/disables matrix scaling
    
    See Also:
    
    getApplyScaling()
  - getApplyScaling
```
public boolean getApplyScaling()
```
    Returns whether or not matrix scaling is enabled.
    
    Returns:
    
    true if matrix scaling is enabled
    
    See Also:
    
    setApplyScaling(int)
  - setApplyWeightedMatchings
```
public void setApplyWeightedMatchings(int enable)
```
    Sets whether or not Pardiso should apply weighted matching to its factorizations. This, along with scaling (see setApplyScaling()) is recommended for highly indefinite symmetric systems (such as saddle point problems) and is the default for symmetric matrices. Weighted matchings are controlled by enable as follows: enable > 0 enables them, enable = 0 disables them, and enable < 0 causes the solver to choose a default value appropriate to the matrix type.
    
    Parameters:
    
    enable - enables/disables weight matchings
    
    See Also:
    
    getApplyWeightedMatchings()
  - getApplyWeightedMatchings
```
public boolean getApplyWeightedMatchings()
```
    Returns whether or not weighted matchings are enabled.
    
    Returns:
    
    true if weighted matchings are enabled
    
    See Also:
    
    setApplyWeightedMatchings(int)
  - setUse2x2Pivoting
```
public void setUse2x2Pivoting(int enable)
```
    Sets whether or not Pardiso should use 2 x 2 Bunch and Kaufman pivoting (in addition to regular 1 x 1 pivoting) for symmetric indefinite matrices. 2 x 2 pivoting is controlled by enable as follows: enable > 0 enables it, enable = 0 disables it, and enable < 0 causes the solver to choose a default value.
    
    Parameters:
    
    enable - enables 2 x 2 pivoting
    
    See Also:
    
    getUse2x2Pivoting()
  - getUse2x2Pivoting
```
public boolean getUse2x2Pivoting()
```
    Returns whether or not 2 x 2 pivoting is enabled.
    
    Returns:
    
    true if 2 x 2 pivoting is enabled
    
    See Also:
    
    setUse2x2Pivoting(int)
  - setMatrixChecking
```
public void setMatrixChecking(boolean enable)
```
    Enables or disables checking of the integrity of the matrix data structures passed to Pardiso. By default this is disabled, but it may be a good idea to enable it if problems arise such as crashes within the Pardiso native code.
    
    Parameters:
    
    enable - enables/disables matrix checking
    
    See Also:
    
    getMatrixChecking()
  - getMatrixChecking
```
public boolean getMatrixChecking()
```
    Returns true if matrix checking is enabled.
    
    Returns:
    
    true if matrix checking is enabled
    
    See Also:
    
    setMatrixChecking(boolean)
  - setMessageLevel
```
public void setMessageLevel(int level)
```
    Sets the message level for the Pardiso native code. 0 disables messages, while 1 causes printing of various stats and information about the solve process. The message level should normally be set to 0.
    
    Parameters:
    
    level - native code message level
    
    See Also:
    
    getMessageLevel()
  - getMessageLevel
```
public int getMessageLevel()
```
    Returns the message level for the Pardiso native code.
    
    Returns:
    
    message level
    
    See Also:
    
    setMessageLevel(int)
  - getNumNonZerosInFactors
```
public int getNumNonZerosInFactors()
```
    Returns the number of non-zeros elements in the factorization. Pardiso determines this during the analyze phase, and so the number returned by this method reflects that determined during the most recent analyze() call.
    
    Returns:
    
    number non-zero elements in the factorization.
  - getNumNegEigenvalues
```
public int getNumNegEigenvalues()
```
    Returns the number of negative eigenvalues that were detected during the most recent numeric factorization of a symmetric indefinite matrix (i.e., during the last factor() call). For matrices that are not symmetric indefinite, -1 is returned.
    
    Returns:
    
    number of negative eigenvalues for symmetric indefinite matrices
  - getNumPosEigenvalues
```
public int getNumPosEigenvalues()
```
    Returns the number of positive eigenvalues that were detected during the most recent numeric factorization of a symmetric indefinite matrix (i.e., during the last factor() call). For matrices that are not symmetric indefinite, -1 is returned.
    
    Returns:
    
    number of positive eigenvalues for symmetric indefinite matrices
  - getNumPerturbedPivots
```
public int getNumPerturbedPivots()
```
    Returns the number of pivot perturbations that were required during the last recent numeric factorization (i.e., during the last factor() call). Pivot perturbation generally indicates a singular, or very nearly singular, matrix.
    
    Returns:
    
    number of pivot perturbations
  - getSPDZeroPivot
```
public int getSPDZeroPivot()
```
    If the solver detects a zero or negative pivot for an SPD matrix, this method returns the row number where the first zero or negative pivot was detected.
    
    Returns:
    
    location of first zero or negative pivot, if any
  - getPeakAnalysisMemoryUsage
```
public int getPeakAnalysisMemoryUsage()
```
    Returns the peak amount of memory (in kbytes) that was used during the most recent analyze() call.
    
    Returns:
    
    peak memory usage during analyze.
  - getAnalysisMemoryUsage
```
public int getAnalysisMemoryUsage()
```
    Returns the amount of permanent memory (in kbytes) that was allocated during the most recent analyze() call.
    
    Returns:
    
    permanent memory allocated during analyze.
  - getFactorSolveMemoryUsage
```
public int getFactorSolveMemoryUsage()
```
    Returns the total memory consumption (in kbytes) required for the factor() and solve() calls. This number is determined in the most recent factor() call.
    
    Returns:
    
    total memory usage during factor and solve steps.
  - analyze
```
public void analyze(double[] vals,
                    int[] colIdxs,
                    int[] rowOffs,
                    int size,
                    int type)
```
    Sets the matrix associated with this solver and performs symbolic analysis on it. The matrix is assumed to be square. After calling this method, the solver's state is set to ANALYZED.
    The matrix structure and its initial values are described using a compressed row storage (CRS) format. See Matrix.setCRSValues() for a detailed description of this format. The matrix type is the same as that supplied to analyze(Matrix,int,int). It is not possible to call factor() after calling this version of analyze because it does not supply a matrix that can be used to obtain values from.
    
    Parameters:
    
    vals - values of the non-zero matrix elements. These may be used to assist the symbolic factorization, but will not used in any actual numeric factorization.
    
    colIdxs - 1-based column indices of the non-zero matrix elements.
    
    rowOffs - 1-based row start offsets into vals and colIdxs, corresponding to CRS format.
    
    size - size of the matrix to be analyzed
    
    type - type of the matrix to be analyzed
    
    Throws:
    
    java.lang.IllegalArgumentException - if the CRS data structures are inconsistent.
    
    NumericalException - if the matrix cannot be analyzed for numeric reasons.
  - solve
```
public void solve(VectorNd x,
                  VectorNd b)
```
    Solves the matrix associated with this solver for x, given a specific right-hand side b. It is assumed that the matrix has been factored and that this solver's state is FACTORED.
    
    Specified by:
    
    solve in interface DirectSolver
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    Throws:
    
    java.lang.IllegalStateException - if this solver's state is not FACTORED
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size.
  - solve
```
public void solve(double[] x,
                  double[] b)
```
    Solves the matrix associated with this solver for x, given a specific right-hand side b. It is assumed that the matrix has been factored and that this solver's state is FACTORED.
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    Throws:
    
    java.lang.IllegalStateException - if this solver's state is not FACTORED
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size.
  - solve
```
public void solve(double[] X,
                  double[] B,
                  int nrhs)
```
    Solves the matrix associated with this solver for a set of vectors X, given a set of right-hand sides B. The number of right-hand sides is given by nrhs. Both X and B should be stored in the column major ordering used by FORTRAN. It is assumed that the matrix has been factored and that this solver's state is FACTORED.
    
    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 to solve for
    
    Throws:
    
    java.lang.IllegalStateException - if this solver's state is not FACTORED
    
    java.lang.IllegalArgumentException - if the dimensions of X or B are incompatible with the matrix size and rhs.
  - 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
 
```
    for a given values of M, x, and b. The values of M are given in compressed row storage (CRS) format.
    Parameters:
    
    rowOffs - matrix row offsets (CRS format)
    
    colIdxs - non-zero element column indices (CRS format)
    
    vals - non-zero element value (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.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size.
  - iterativeSolve
```
public int iterativeSolve(VectorNd x,
                          VectorNd b,
                          int tolExp)
```
    Implementation of iterativeSolve(double[],double[],int) that uses VectorNd objects to store to the result and right-hand side.
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    tolExp - exponent for the stopping criterion
    
    Returns:
    
    number of iterations performed, negated if unsuccessful
    
    Throws:
    
    ImproperStateException - if not preceded by a call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix), or if the matrix has not previously been factored.
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size, or if topExp is negative.
  - iterativeSolve
```
public int iterativeSolve(double[] x,
                          double[] b,
                          int tolExp)
```
    Attempts to use preconditioned CGS iteration to solve M x = b for a given right-hand side b. Current numeric values for M are obtained from the matrix that was supplied by a previous call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix). The most recent numeric factorization of this matrix will be used as a preconditioner for the CGS iteration, with a relative stopping criterion given by 10^-tolExp. It is assumed that the matrix has been previously factored with a call to factor().
    If the CGS iteration is successful, this method returns a positive value giving the number of iterations required. If unsuccessful, it returns a non-postive value giving the negative of the number of iterations that were actually performed, and getErrorMessage() can be used to determine the underlying error.
    
    Parameters:
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    tolExp - exponent for the stopping criterion
    
    Returns:
    
    number of iterations performed, negated if unsuccessful
    
    Throws:
    
    ImproperStateException - if not preceded by a call to analyze(Matrix,int,int) or analyzeAndFactor(Matrix), or if the matrix has not previously been factored.
    
    java.lang.IllegalArgumentException - if the dimensions of x or b are incompatible with the matrix size, or if topExp is negative.
  - iterativeSolve
```
public int iterativeSolve(double[] vals,
                          double[] x,
                          double[] b,
                          int tolExp)
```
    Attempts to use preconditioned CGS iteration to solve M x = b for a given right-hand side b. Current numeric values for M are supplied by the argument vals. Otherwise this method behaves identically to iterativeSolve(double[],double[],int).
    
    Parameters:
    
    vals - supplied the current matrix values
    
    x - returns the solution value
    
    b - supplies the right-hand side
    
    tolExp - exponent for the stopping criterion
    
    Returns:
    
    number of iterations performed, negated if unsuccessful
    
    Throws:
    
    ImproperStateException - if the matrix has not previously been factored.
    
    java.lang.IllegalArgumentException - if there are insufficient values specified by vals, the dimensions of x or b are incompatible with the matrix size, or if topExp is negative.
  - dispose
```
public void dispose()
```
    Releases the native resources used by this solver.
    
    Specified by:
    
    dispose in interface DirectSolver
  - finalize
```
public void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object
  - hasAutoIterativeSolving
```
public boolean hasAutoIterativeSolving()
```
    Returns true if this solver supports automatic iterative solving using a recent directly-factored matrix as a preconditioner. If this feature is available, it may be invoked using the autoFactorAndSolve method.
    
    Specified by:
    
    hasAutoIterativeSolving in interface DirectSolver
    
    Returns:
    
    true if auto-iterative solving is available
  - main
```
public static void main(java.lang.String[] args)
```
  - getErrorMessage
```
public java.lang.String getErrorMessage()
```
    Returns a message describing the reason for failure of the most recent call to any of the analyze(), factor(), or iterativeSolve() methods, or null if the method succeeded.
    
    Returns:
    
    most recent error message, if any
  - systemExit
```
public void systemExit(int code)
```
    This method is a hook that gives us access to _exit(), which is is in turn needed to exit ArtiSynth on the MacBook Pro 8.2 version of Ubuntu, since otherwise the JVM exit process encounters a SEGV in XQueryExtension. This method was put into PardisoSolver purely ; it has nothing to do with Pardiso per-se.

Class PardisoSolver

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

printThreadInfo

supportsMultipleRhs

DEFAULT_SHOW_PERTURBED_PIVOTS

UNSET

ANALYZED

FACTORED

Constructor Detail

PardisoSolver

Method Detail

getState

isAvailable

getInitErrorMessage

analyze

factor

factor

analyzeAndFactor

autoFactorAndSolve

autoFactorAndSolve

setShowPerturbedPivots

getShowPerturbedPivots

setDefaultNumThreads

getDefaultNumThreads

setNumThreads

getNumThreads

setMaxRefinementSteps

getMaxRefinementSteps

getNumRefinementSteps

getReorderMethod

setReorderMethod

setPivotPerturbation

getPivotPerturbation

setApplyScaling

getApplyScaling

setApplyWeightedMatchings

getApplyWeightedMatchings

setUse2x2Pivoting

getUse2x2Pivoting

setMatrixChecking

getMatrixChecking

setMessageLevel

getMessageLevel

getNumNonZerosInFactors

getNumNegEigenvalues

getNumPosEigenvalues

getNumPerturbedPivots

getSPDZeroPivot

getPeakAnalysisMemoryUsage

getAnalysisMemoryUsage

getFactorSolveMemoryUsage

analyze

solve

solve

solve

residual

iterativeSolve

iterativeSolve

iterativeSolve

dispose

finalize

hasAutoIterativeSolving

main

getErrorMessage

systemExit