Safe Haskell | None |
---|---|

Language | Haskell2010 |

This documentation is based on original Eigen page Solving Sparse Linear Systems

Eigen currently provides a limited set of built-in MPL2 compatible solvers. They are summarized in the following table:

Sparse solver Solver kind Matrix kind Notes ConjugateGradient Classic iterative CG SPD Recommended for large symmetric problems (e.g., 3D Poisson eq.) BiCGSTAB Iterative stabilized Square bi-conjugate gradient SparseLU LU factorization Square Optimized for small and large problems with irregular patterns SparseQR QR factorization Any, rectangular Recommended for least-square problems, has a basic rank-revealing feature

All these solvers follow the same general concept. Here is a typical and general example:

```
let
a :: SparseMatrixXd
a = ... -- fill a
b :: SparseMatrixXd
b = ... -- fill b
validate msg = info >>= (
````when`

fail msg) . (/= Success)
// solve Ax = b
runSolverT solver $ do
compute a
validate "decomposition failed"
x <- solve b
validate "solving failed"
// solve for another right hand side
x1 <- solve b1

In the case where multiple problems with the same sparsity pattern have to be solved, then the "compute" step can be decomposed as follow:

runSolverT solver $ do analyzePattern a1 factorize a1 x1 <- solve b1 x2 <- solve b2 factorize a2 x1 <- solve b1 x2 <- solve b2

Finally, each solver provides some specific features, such as determinant, access to the factors, controls of the iterations, and so on.

## Synopsis

- class Code s => Solver s
- class Solver s => DirectSolver s
- class Solver s => IterativeSolver s
- data OrderingMethod
- data Preconditioner
- data ConjugateGradient = ConjugateGradient Preconditioner
- data BiCGSTAB = BiCGSTAB Preconditioner
- data SparseLU = SparseLU OrderingMethod
- data SparseQR = SparseQR OrderingMethod
- data ComputationInfo
- type SolverT s a b m = ReaderT (s, ForeignPtr (CSolver a b)) m
- runSolverT :: (Solver s, MonadIO m, Elem a b) => s -> SolverT s a b m c -> m c
- analyzePattern :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m ()
- factorize :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m ()
- compute :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m ()
- solve :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m (SparseMatrix a b)
- info :: (Solver s, MonadIO m, Elem a b) => SolverT s a b m ComputationInfo
- tolerance :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Double
- setTolerance :: (IterativeSolver s, MonadIO m, Elem a b) => Double -> SolverT s a b m ()
- maxIterations :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Int
- setMaxIterations :: (IterativeSolver s, MonadIO m, Elem a b) => Int -> SolverT s a b m ()
- error :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Double
- iterations :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Int
- matrixR :: (MonadIO m, Elem a b) => SolverT SparseQR a b m (SparseMatrix a b)
- matrixQ :: (MonadIO m, Elem a b) => SolverT SparseQR a b m (SparseMatrix a b)
- rank :: (MonadIO m, Elem a b) => SolverT SparseQR a b m Int
- setPivotThreshold :: (MonadIO m, Elem a b) => Double -> SolverT SparseQR a b m ()
- setSymmetric :: (MonadIO m, Elem a b) => Bool -> SolverT SparseLU a b m ()
- matrixL :: (MonadIO m, Elem a b) => SolverT SparseLU a b m (SparseMatrix a b)
- matrixU :: (MonadIO m, Elem a b) => SolverT SparseLU a b m (SparseMatrix a b)
- determinant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a
- absDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a
- signDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a
- logAbsDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a

# Sparse Solvers

class Code s => Solver s Source #

## Instances

Solver SparseQR Source # | |

Defined in Data.Eigen.SparseLA | |

Solver SparseLU Source # | |

Defined in Data.Eigen.SparseLA | |

Solver BiCGSTAB Source # | |

Defined in Data.Eigen.SparseLA | |

Solver ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA |

class Solver s => DirectSolver s Source #

For direct methods, the solution is computed at the machine precision.

## Instances

DirectSolver SparseQR Source # | |

Defined in Data.Eigen.SparseLA | |

DirectSolver SparseLU Source # | |

Defined in Data.Eigen.SparseLA |

class Solver s => IterativeSolver s Source #

Sometimes, the solution need not be too accurate.
In this case, the iterative methods are more suitable and the desired accuracy can be set before the solve step using `setTolerance`

.

## Instances

IterativeSolver BiCGSTAB Source # | |

Defined in Data.Eigen.SparseLA | |

IterativeSolver ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA |

data OrderingMethod Source #

Ordering methods for sparse matrices. They are typically used to reduce the number of elements during the sparse matrix
decomposition (`LLT`

, `LU`

, `QR`

). Precisely, in a preprocessing step, a permutation matrix `P`

is computed using those ordering methods
and applied to the columns of the matrix. Using for instance the sparse Cholesky decomposition, it is expected that the nonzeros
elements in `LLT(A*P)`

will be much smaller than that in `LLT(A)`

.

COLAMDOrdering | The column approximate minimum degree ordering The matrix should be in column-major and compressed format |

NaturalOrdering | The natural ordering (identity) |

## Instances

Read OrderingMethod Source # | |

Defined in Data.Eigen.SparseLA readsPrec :: Int -> ReadS OrderingMethod # readList :: ReadS [OrderingMethod] # | |

Show OrderingMethod Source # | |

Defined in Data.Eigen.SparseLA showsPrec :: Int -> OrderingMethod -> ShowS # show :: OrderingMethod -> String # showList :: [OrderingMethod] -> ShowS # |

data Preconditioner Source #

DiagonalPreconditioner | A preconditioner based on the digonal entries It allows to approximately solve for A.x = b problems assuming A is a diagonal matrix.
In other words, this preconditioner neglects all off diagonal entries and, in Eigen's language, solves for:
A variant that has yet to be implemented would attempt to preserve the norm of each column. |

IdentityPreconditioner | A naive preconditioner which approximates any matrix as the identity matrix |

## Instances

Read Preconditioner Source # | |

Defined in Data.Eigen.SparseLA readsPrec :: Int -> ReadS Preconditioner # readList :: ReadS [Preconditioner] # | |

Show Preconditioner Source # | |

Defined in Data.Eigen.SparseLA showsPrec :: Int -> Preconditioner -> ShowS # show :: Preconditioner -> String # showList :: [Preconditioner] -> ShowS # |

data ConjugateGradient Source #

A conjugate gradient solver for sparse self-adjoint problems.

This class allows to solve for `A.x = b`

sparse linear problems using a conjugate gradient algorithm. The sparse matrix `A`

must be selfadjoint.

The maximal number of iterations and tolerance value can be controlled via the `setMaxIterations`

and `setTolerance`

methods.
The defaults are the size of the problem for the maximal number of iterations and `epsilon`

for the tolerance

## Instances

Read ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA | |

Show ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA showsPrec :: Int -> ConjugateGradient -> ShowS # show :: ConjugateGradient -> String # showList :: [ConjugateGradient] -> ShowS # | |

Code ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA code :: ConjugateGradient -> CInt Source # | |

IterativeSolver ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA | |

Solver ConjugateGradient Source # | |

Defined in Data.Eigen.SparseLA |

A bi conjugate gradient stabilized solver for sparse square problems.

This class allows to solve for `A.x = b`

sparse linear problems using a bi conjugate gradient stabilized algorithm.
The vectors `x`

and `b`

can be either dense or sparse.

The maximal number of iterations and tolerance value can be controlled via the `setMaxIterations`

and `setTolerance`

methods.
The defaults are the size of the problem for the maximal number of iterations and `epsilon`

for the tolerance

Sparse supernodal LU factorization for general matrices.

This class implements the supernodal LU factorization for general matrices. It uses the main techniques from the sequential SuperLU package. It handles transparently real and complex arithmetics with single and double precision, depending on the scalar type of your input matrix. The code has been optimized to provide BLAS-3 operations during supernode-panel updates. It benefits directly from the built-in high-performant Eigen BLAS routines. Moreover, when the size of a supernode is very small, the BLAS calls are avoided to enable a better optimization from the compiler. For best performance, you should compile it with NDEBUG flag to avoid the numerous bounds checking on vectors.

An important parameter of this class is the ordering method. It is used to reorder the columns (and eventually the rows) of the matrix to reduce the number of new elements that are created during numerical factorization. The cheapest method available is COLAMD. See OrderingMethods module for the list of built-in and external ordering methods.

Sparse left-looking rank-revealing QR factorization.

This class implements a left-looking rank-revealing QR decomposition of sparse matrices. When a column has a norm less than a given
tolerance it is implicitly permuted to the end. The QR factorization thus obtained is given by `A*P = Q*R`

where `R`

is upper triangular or trapezoidal.

`P`

is the column permutation which is the product of the fill-reducing and the rank-revealing permutations.

`Q`

is the orthogonal matrix represented as products of Householder reflectors.

`R`

is the sparse triangular or trapezoidal matrix. The later occurs when `A`

is rank-deficient.

data ComputationInfo Source #

Success | Computation was successful. |

NumericalIssue | The provided data did not satisfy the prerequisites. |

NoConvergence | Iterative procedure did not converge. |

InvalidInput | The inputs are invalid, or the algorithm has been improperly called. When assertions are enabled, such errors trigger an error. |

## Instances

Enum ComputationInfo Source # | |

Defined in Data.Eigen.SparseLA succ :: ComputationInfo -> ComputationInfo # pred :: ComputationInfo -> ComputationInfo # toEnum :: Int -> ComputationInfo # fromEnum :: ComputationInfo -> Int # enumFrom :: ComputationInfo -> [ComputationInfo] # enumFromThen :: ComputationInfo -> ComputationInfo -> [ComputationInfo] # enumFromTo :: ComputationInfo -> ComputationInfo -> [ComputationInfo] # enumFromThenTo :: ComputationInfo -> ComputationInfo -> ComputationInfo -> [ComputationInfo] # | |

Eq ComputationInfo Source # | |

Defined in Data.Eigen.SparseLA (==) :: ComputationInfo -> ComputationInfo -> Bool # (/=) :: ComputationInfo -> ComputationInfo -> Bool # | |

Read ComputationInfo Source # | |

Defined in Data.Eigen.SparseLA | |

Show ComputationInfo Source # | |

Defined in Data.Eigen.SparseLA showsPrec :: Int -> ComputationInfo -> ShowS # show :: ComputationInfo -> String # showList :: [ComputationInfo] -> ShowS # |

# The Compute step

In the `compute`

function, the matrix is generally factorized: LLT for self-adjoint matrices, LDLT for general hermitian matrices,
LU for non hermitian matrices and QR for rectangular matrices. These are the results of using direct solvers.
For this class of solvers precisely, the compute step is further subdivided into `analyzePattern`

and `factorize`

.

The goal of `analyzePattern`

is to reorder the nonzero elements of the matrix, such that the factorization step creates less fill-in.
This step exploits only the structure of the matrix. Hence, the results of this step can be used for other linear systems where the
matrix has the same structure.

In `factorize`

, the factors of the coefficient matrix are computed. This step should be called each time the values of the matrix change.
However, the structural pattern of the matrix should not change between multiple calls.

For iterative solvers, the `compute`

step is used to eventually setup a preconditioner.
Remember that, basically, the goal of the preconditioner is to speedup the convergence of an iterative method by solving a modified linear
system where the coefficient matrix has more clustered eigenvalues.
For real problems, an iterative solver should always be used with a preconditioner.

analyzePattern :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m () Source #

Initializes the iterative solver for the sparsity pattern of the matrix `A`

for further solving `Ax=b`

problems.

factorize :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m () Source #

Initializes the iterative solver with the numerical values of the matrix `A`

for further solving `Ax=b`

problems.

compute :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m () Source #

Initializes the iterative solver with the matrix `A`

for further solving `Ax=b`

problems.

The `compute`

method is equivalent to calling both `analyzePattern`

and `factorize`

.

# The Solve step

The `solve`

function computes the solution of the linear systems with one or many right hand sides.

x <- solve b

Here, `b`

can be a vector or a matrix where the columns form the different right hand sides.
The `solve`

function can be called several times as well, for instance when all the right hand sides are not available at once.

x1 <- solve b1 -- Get the second right hand side b2 x2 <- solve b2 -- ...

solve :: (Solver s, MonadIO m, Elem a b) => SparseMatrix a b -> SolverT s a b m (SparseMatrix a b) Source #

An expression of the solution `x`

of `Ax=b`

using the current decomposition of `A`

.

info :: (Solver s, MonadIO m, Elem a b) => SolverT s a b m ComputationInfo Source #

`Success`

if the iterations converged or computation was succesful`NumericalIssue`

if the factorization reports a numerical problem`NoConvergence`

if the iterations are not converged`InvalidInput`

if the input matrix is invalid

# Iterative Solvers

tolerance :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Double Source #

The tolerance threshold used by the stopping criteria.

setTolerance :: (IterativeSolver s, MonadIO m, Elem a b) => Double -> SolverT s a b m () Source #

Sets the tolerance threshold used by the stopping criteria.

This value is used as an upper bound to the relative residual error: `|Ax-b|/|b|`

. The default value is the machine precision given by `epsilon`

maxIterations :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Int Source #

The max number of iterations. It is either the value setted by setMaxIterations or, by default, twice the number of columns of the matrix.

setMaxIterations :: (IterativeSolver s, MonadIO m, Elem a b) => Int -> SolverT s a b m () Source #

Sets the max number of iterations. Default is twice the number of columns of the matrix.

error :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Double Source #

The tolerance error reached during the last solve. It is a close approximation of the true relative residual error `|Ax-b|/|b|`

.

iterations :: (IterativeSolver s, MonadIO m, Elem a b) => SolverT s a b m Int Source #

The number of iterations performed during the last solve

# SparseQR Solver

matrixR :: (MonadIO m, Elem a b) => SolverT SparseQR a b m (SparseMatrix a b) Source #

Returns the `b`

sparse upper triangular matrix `R`

of the QR factorization.

matrixQ :: (MonadIO m, Elem a b) => SolverT SparseQR a b m (SparseMatrix a b) Source #

Returns the matrix `Q`

as products of sparse Householder reflectors.

rank :: (MonadIO m, Elem a b) => SolverT SparseQR a b m Int Source #

Returns the number of non linearly dependent columns as determined by the pivoting threshold.

setPivotThreshold :: (MonadIO m, Elem a b) => Double -> SolverT SparseQR a b m () Source #

Sets the threshold that is used to determine linearly dependent columns during the factorization.

In practice, if during the factorization the norm of the column that has to be eliminated is below this threshold, then the entire column is treated as zero, and it is moved at the end.

# SparseLU Solver

setSymmetric :: (MonadIO m, Elem a b) => Bool -> SolverT SparseLU a b m () Source #

Indicate that the pattern of the input matrix is symmetric

matrixL :: (MonadIO m, Elem a b) => SolverT SparseLU a b m (SparseMatrix a b) Source #

Returns the matrix `L`

matrixU :: (MonadIO m, Elem a b) => SolverT SparseLU a b m (SparseMatrix a b) Source #

Returns the matrix `U`

determinant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a Source #

The determinant of the matrix.

absDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a Source #

The absolute value of the determinant of the matrix of which *this is the QR decomposition.

A determinant can be very big or small, so for matrices of large enough dimension, there is a risk of overflow/underflow.
One way to work around that is to use `logAbsDeterminant`

instead.

signDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a Source #

A number representing the sign of the determinant

logAbsDeterminant :: (MonadIO m, Elem a b) => SolverT SparseLU a b m a Source #

The natural log of the absolute value of the determinant of the matrix of which this is the QR decomposition

This method is useful to work around the risk of overflow/underflow that's inherent to the determinant computation.