public class ComplexSuperLU extends Object implements Serializable
ComplexSparseMatrix
by a column method and solves a sparse
linear system of equations \(Ax=b\).
Consider the sparse linear system of equations
$$ Ax=b.$$
Here, A is a general square, nonsingular, n by n sparse
matrix, and x and b are vectors of length n. All
entries in A, x and b are of type Complex
.
Gaussian elimination, applied to the system above, can be shortly described as follows:
Class ComplexSuperLU
handles step 1 above in the
solve
method if it is has not been computed prior to step 2.
More precisely, before \(Ax=b\) is solved
the following steps are performed:
Method solve
uses this information to perform the following
steps:
Some of the steps mentioned above are optional. Their settings can be
controlled by the set methods of class ComplexSuperLU
.
Class ComplexSuperLU
is based on the SuperLU code written
by Demmel, Gilbert, Li et al. For more detailed explanations of the
factorization and solve steps, see the SuperLU Users' Guide (1999).
Copyright (c) 2003, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from U.S. Dept. of Energy)
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
(1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
(2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
(3) Neither the name of Lawrence Berkeley National Laboratory, U.S. Dept. of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Modifier and Type | Field and Description |
---|---|
static int |
COLUMN_APPROXIMATE_MINIMUM_DEGREE
For column ordering, use column approximate minimum degree ordering.
|
static int |
COLUMN_SCALING
Indicates that input matrix A was column scaled before
factorization.
|
static int |
FILL_FACTOR
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
MAXIMUM_SUPERNODE_SIZE
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
MINIMUM_COLUMN_DIMENSION
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
MINIMUM_DEGREE_AT_A
For column ordering, use minimum degree ordering on the structure of
\(A^TA\).
|
static int |
MINIMUM_DEGREE_AT_PLUS_A
For column ordering, use minimum degree ordering on the structure of
\(A^T+A\).
|
static int |
MINIMUM_ROW_DIMENSION
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
NATURAL_ORDERING
For column ordering, use the natural ordering.
|
static int |
NO_SCALING
Indicates that input matrix A was not equilibrated before
factorization.
|
static int |
PANEL_SIZE
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
RELAXATION_PARAMETER
A performance tuning parameter which can be adjusted via method
setPerformanceTuningParameters . |
static int |
ROW_AND_COLUMN_SCALING
Indicates that input matrix A was row and column scaled before
factorization.
|
static int |
ROW_SCALING
Indicates that input matrix A was row scaled before
factorization.
|
Constructor and Description |
---|
ComplexSuperLU(ComplexSparseMatrix A)
Constructor for
ComplexSuperLU . |
Modifier and Type | Method and Description |
---|---|
int |
getColumnPermutationMethod()
Returns the method that will be used to permute the columns of the input matrix.
|
double |
getConditionNumber()
Returns the estimate of the reciprocal condition number of the matrix
A.
|
double |
getDiagonalPivotThreshold()
Returns the threshold used for a diagonal entry to be an acceptable pivot.
|
boolean |
getEquilibrate()
Returns the equilibration flag.
|
int |
getEquilibrationMethod()
Returns information on the type of equilibration used
before matrix factorization.
|
double |
getForwardErrorBound()
Returns the estimated forward error bound for each solution vector.
|
boolean |
getIterativeRefinement()
Returns a value specifying whether iterative refinement is to be performed or not.
|
int |
getPerformanceTuningParameters(int parameter)
Returns a performance tuning parameter value.
|
boolean |
getPivotGrowth()
Returns the reciprocal pivot growth factor flag.
|
double |
getReciprocalPivotGrowthFactor()
Returns the reciprocal pivot growth factor.
|
double |
getRelativeBackwardError()
Returns the componentwise relative backward error of the solution vector.
|
boolean |
getSymmetricMode()
Returns the symmetric mode flag.
|
void |
setColumnPermutationMethod(int colpermute)
Specifies how to permute the columns of the input matrix.
|
void |
setDiagonalPivotThreshold(double thresh)
Specifies the threshold used for a diagonal entry to be an
acceptable pivot.
|
void |
setEquilibrate(boolean equilibrate)
Specifies if input matrix A should be equilibrated
before factorization.
|
void |
setIterativeRefinement(boolean refine)
Specifies whether to perform iterative refinement.
|
void |
setPerformanceTuningParameters(int parameter,
int tunedValue)
Sets performance tuning parameters.
|
void |
setPivotGrowth(boolean growth)
Specifies whether to compute the reciprocal pivot growth factor.
|
void |
setSymmetricMode(boolean symmetric)
Specifies whether to use the symmetric mode.
|
Complex[] |
solve(Complex[] b)
Computation of the solution vector for the system
\( Ax = b\).
|
Complex[] |
solveConjugateTranspose(Complex[] b)
Computation of the solution vector for the system
\( A^Hx = b\).
|
Complex[] |
solveTranspose(Complex[] b)
Computation of the solution vector for the system
\( A^Tx = b\).
|
public static final int NATURAL_ORDERING
public static final int MINIMUM_DEGREE_AT_A
public static final int MINIMUM_DEGREE_AT_PLUS_A
public static final int COLUMN_APPROXIMATE_MINIMUM_DEGREE
public static final int PANEL_SIZE
setPerformanceTuningParameters
.public static final int RELAXATION_PARAMETER
setPerformanceTuningParameters
.public static final int MAXIMUM_SUPERNODE_SIZE
setPerformanceTuningParameters
.public static final int MINIMUM_ROW_DIMENSION
setPerformanceTuningParameters
.public static final int MINIMUM_COLUMN_DIMENSION
setPerformanceTuningParameters
.public static final int FILL_FACTOR
setPerformanceTuningParameters
.public static final int NO_SCALING
getEquilibrationMethod
.public static final int ROW_SCALING
getEquilibrationMethod
.public static final int COLUMN_SCALING
getEquilibrationMethod
.public static final int ROW_AND_COLUMN_SCALING
getEquilibrationMethod
.public ComplexSuperLU(ComplexSparseMatrix A)
ComplexSuperLU
.A
- a ComplexSparseMatrix
containing the sparse
quadratic input matrix.public Complex[] solve(Complex[] b) throws SingularMatrixException
b
- a Complex
vector of length n
,
n
the order of input matrix A
,
containing the right hand side.Complex
vector containing the solution to the
system \( Ax = b\). Optionally, the solution
is improved by iterative refinement, if
setIterativeRefinement
is set to true
.
Method solve
internally first factorizes matrix A
(step 1 of the introduction) if the factorization has not been
done before.SingularMatrixException
public Complex[] solveTranspose(Complex[] b) throws SingularMatrixException
b
- a Complex
vector of length n
, n
the order of input matrix A
, containing the right hand side.Complex
vector containing the solution to the
system \( A^Tx = b\). Optionally, the solution
is improved by iterative refinement, if
setIterativeRefinement
is set to true
. Method solveTranspose
internally first
factorizes matrix A (step 1 of the introduction) if the
factorization has not been done before.SingularMatrixException
public Complex[] solveConjugateTranspose(Complex[] b) throws SingularMatrixException
b
- a Complex
vector of length n
, n
the order of input matrix A
, containing the right hand side.Complex
vector containing the solution to the
system \( A^Hx = b\). Optionally, the solution
is improved by iterative refinement, if
setIterativeRefinement
is set to true
. Method solveConjugateTranspose
internally first
factorizes matrix A (step 1 of the introduction) if the factorization
has not been done before.SingularMatrixException
public int getEquilibrationMethod()
int
value specifying the equilibration
option used.
return value | option description | 1 = NO_SCALING |
No equilibration is performed. |
---|---|
2 = ROW_SCALING |
Equilibration is performed with row scaling. |
3 = COLUMN_SCALING |
Equilibration is performed with column scaling. |
4 = ROW_AND_COLUMN_SCALING |
Equilibration is performed with row and column scaling. |
public void setEquilibrate(boolean equilibrate)
equilibrate
- a boolean
determining
if matrix A should be equilibrated before
the factorization.
equilibrate |
action |
---|---|
false |
do not equilibrate |
true |
equilibrate |
equilibrate
= true
.
public void setColumnPermutationMethod(int colpermute)
colpermute
- an int
scalar specifying how to permute
the columns of the input matrix for sparsity preservation.
colpermute |
method |
---|---|
NATURAL_ORDERING |
natural ordering, that is \(P_c=I\), I the identity matrix |
MINIMUM_DEGREE_AT_PLUS_A |
minimum degree ordering on the structure of \(A^T+A\) |
MINIMUM_DEGREE_AT_A |
minimum degree ordering on the structure of \(A^TA\) |
COLUMN_APPROXIMATE_MINIMUM_DEGREE |
column approximate minimum degree ordering |
colpermute
=
SuperLU.COLUMN_APPROXIMATE_MINIMUM_DEGREE
.public int getColumnPermutationMethod()
int
scalar specifying how the columns
of the input matrix are to be permuted for sparsity preservation.
return value | method |
---|---|
0 = NATURAL_ORDERING |
natural ordering, that is \(P_c=I\), I the identity matrix |
1 = MINIMUM_DEGREE_AT_PLUS_A |
minimum degree ordering on the structure of \(A^T+A\) |
2 = MINIMUM_DEGREE_AT_A |
minimum degree ordering on the structure of \(A^TA\) |
3 = COLUMN_APPROXIMATE_MINIMUM_DEGREE
|
column approximate minimum degree ordering |
public void setSymmetricMode(boolean symmetric)
symmetric
- a boolean
indicating if symmetric mode
is to be used. This mode should be applied if the input matrix
A is diagonally dominant or nearly so. The user should
then define a small diagonal pivot threshold (e.g. 0.0 or 0.01)
by method setDiagonalPivotThreshold
and choose an
(\(A^T+A\))-based column permutation algorithm
(e.g. column permutation method
ComplexSuperLU.MINIMUM_DEGREE_AT_PLUS_A
).
symmetric | action |
---|---|
false |
symmetric mode is not used |
true |
symmetric mode is used |
symmetric=false
.public boolean getSymmetricMode()
boolean
scalar indicating if symmetric mode
is to be used. Returns
true if symmetric mode is to be used.public void setIterativeRefinement(boolean refine)
refine
- a boolean
scalar specifying whether to use
iterative refinement, refine = true
or
no iterative refinement, refine = false
.
refine = false
.public boolean getIterativeRefinement()
boolean
scalar specifying whether
iterative refinement is to be performed, true
, or
no iterative refinement is to be performed, false
.public void setDiagonalPivotThreshold(double thresh)
thresh
- a double
scalar specifying the threshold
used for a diagonal entry to be an acceptable pivot.
thresh=1.0
, i.e. classical partial
pivoting.IllegalArgumentException
- is thrown if thresh
is not in the interval \([0.0,1.0]\).public double getDiagonalPivotThreshold()
double
scalar specifying the threshold used for a
diagonal entry to be an acceptable pivot.public void setPivotGrowth(boolean growth)
growth
- a boolean
specifying whether to
compute the reciprocal pivot growth factor.
growth |
action |
---|---|
false |
don't compute growth factor |
true |
compute growth factor |
growth = false
.public boolean getPivotGrowth()
boolean
specifying whether to
compute the reciprocal pivot growth factor. Returns
true if the reciprocal pivot growth factor is to be computed.public double getReciprocalPivotGrowthFactor() throws SingularMatrixException
double
scalar representing the reciprocal growth factor
$$\max_{1 \le j \le n} \frac{\|\tilde{A}_j\|_\infty}{\|U_j\|_\infty}.$$
If the returned value is much less than 1, the stability of the
\(LU\) factorization could be poor.SingularMatrixException
public double getConditionNumber() throws SingularMatrixException
double
scalar containing the reciprocal condition
number of the matrix A after equilibration and permutation of
rows/columns (if done). If the reciprocal condition number is less
than machine precision, in particular if it is equal to 0, the matrix
is singular to working precision.SingularMatrixException
public double getForwardErrorBound()
double
containing the estimated forward error bound
for the solution vector. The estimate is as
reliable as the estimate for the reciprocal condition
number, and is almost always a slight overestimate of
the true error. If iterative refinement is not used,
the return value = 1.0.public double getRelativeBackwardError()
double
containing the componentwise relative
backward error of the solution vector x
.
If setIterativeRefinement
is not set to
true
, then
getRelativeBackwardError
returns 1.0.public boolean getEquilibrate()
boolean
specifying whether or not matrix
A
is equilibrated before factorization. If
getEquilibrate
returns true
the
system is equilibrated, if getEquilibrate
returns
false
, no equilibration is performed.public void setPerformanceTuningParameters(int parameter, int tunedValue)
parameter
- an int
scalar that specifies the
parameter to be tuned.tunedValue
- an int
scalar that specifies the
value to be used for the specified tuning parameter.
parameter |
Description | Default |
---|---|---|
PANEL_SIZE |
The panel size. | 10 |
RELAXATION_PARAMETER |
The relaxation parameter to control supernode amalgamation. | 5 |
MAXIMUM_SUPERNODE_SIZE |
The maximum allowable size for a supernode. | 100 |
MINIMUM_ROW_DIMENSION |
The minimum row dimension to be used for 2D blocking. | 200 |
MINIMUM_COLUMN_DIMENSION |
The minimum column dimension to be used for 2D blocking. | 40 |
FILL_FACTOR |
The estimated fill factor for L and U, compared with A. | 20 |
IllegalArgumentException
- is thrown when a) parameter
is not in the interval \([1,\ldots,6]\) or
b) tunedValue
is not greater than zero.public int getPerformanceTuningParameters(int parameter)
parameter
- an int
scalar that specifies the
parameter for which the value is to be returned.
parameter |
return value description |
---|---|
PANEL_SIZE |
The panel size. |
RELAXATION_PARAMETER |
The relaxation parameter to control supernode amalgamation. |
MAXIMUM_SUPERNODE_SIZE |
The maximum allowable size for a supernode. |
MINIMUM_ROW_DIMENSION |
The minimum row dimension to be used for 2D blocking. |
MINIMUM_COLUMN_DIMENSION |
The minimum column dimension to be used for 2D blocking. |
FILL_FACTOR |
The estimated fill factor for L and U, compared with A. |
int
specifying the current value used for the specified tuning parameter.Copyright © 2020 Rogue Wave Software. All rights reserved.