maspack.solvers
Class PardisoSolver

java.lang.Object
  extended by 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:

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
static class PardisoSolver.ReorderMethod
          Describes the reorder methods that can be used during the analyze phase to reduce factorization fill-in.
 
Field Summary
static int ANALYZED
          Indicates that a matrix has been set and analyzed for this solver.
static int FACTORED
          Indicates that a matrix has been set, analyzed, and numerically factored for this solver.
static boolean printThreadInfo
           
static int UNSET
          Indicates that no matrix is currently set for this solver.
 
Constructor Summary
PardisoSolver()
          Creates a new PardisoSolver object.
 
Method Summary
 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 tolExpinstead, 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.
 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.
 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 state 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, double[] x, double[] b)
          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.
 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.
 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(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

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 state 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

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 number <= 0 will set the number of threads to the valuse stored in the environment variable OMP_NUM_THREADS.

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 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.

residual

public double residual(int[] rowOffs,
                       int[] colIdxs,
                       double[] vals,
                       double[] x,
                       double[] b)
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)
x - supplies the solution value
b - supplies the right-hand-side
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.