`solver_option`

direct and iterative solver options

# Description

This class implements a set of options for customizing a `solver`. An instance of this class can be supplied to the `solver` constructor.

# Main option

`iterative`

> This boolean flag controls the choice between an iterative or a direct method. Default is direct for matrix obtained from 1D or 2D PDE problems and iterative for 3D ones. The direct solver bases on the `mumps` library for a distributed environment and, otherwise, on the `suitesparse` or the `eigen` in a sequential one. The iterative solver bases on `cg` conjugate gradient algorithm for symmetric positive definite matrix and on the `gmres` algorithm otherwise.

# Option for direct solvers

`preferred_library`

> The direct solver bases on an external library: it could be either `mumps`, `suitesparse` or `eigen`. When all these libraries are available, then `mumps` is the default when is is well configured with either the `scoth` or the `metis` ordering library. When neither `mumps` nor `suitesparse` are available, the `eigen` choice is selected. This option allows one to impose an alternative choice e.g. `suitesparse`, by setting the string to `"suitesparse"`. This option can be provided as a list of choices, separated by a space or a coma, e.g. `preferred_library="suitesparse eigen mumps"`.

`default_preferred_library(a)`

> This method returns all the the available libraries in the decreasing preference order. The result depends upon the matrix `a`, especially if it is symmetric definite positive or not, and whether it requires memory communications or not.

used_library(a,sopt)

> This method returns the name of the available library that will be used by the `solver` when a direct solvers is selected. The result depends upon the properties of the `a` matrix and upon the solver option `sopt`, especially the `sopt.preferred_library`.

`compute_determinant`

> Compute also the determinant of the matrix. Requires `mumps` or `suitesparse`.

`n_refinement`

> Number of iterative refinement, when using a direct method (`suitesparse` only support it).

# Option for iterative solvers

`tol`

> This floating parameter control the tolerance for the stopping criterion. Default is the machine epsilon for the default `Float` type. Recall that the default `Float` type is defined at Rheolef Configuration time and is `double` by default, when no special Configuration option is used.

`max_iter`

> Maximum number of iteration when using an iterative method.

`absolute_stopping`

> Absolute or relative stopping criterion.
> With the absolute criterion, the algorithm stops when `norm(A*x-b) < tol`, otherwise it stops when `norm(A*x-b) < tol*norm(b)`. Default is to use an absolute stopping criterion.

`residue`

> On return, gives the obtained residue, optionally divided by the initial one when using a relative stopping. It is less or equal to `tol` when the iterative algorithm stops with succes.

`n_iter`

> On return, gives the number of iterations performed. It is always less or equal to `max_iter` when the iterative algorithm stops with succes.

`p_err`

> A pointer to the `diststream` where residues are printed during iterations. When this pointer is zero, no errors are printed. Default is to print to `derr` standard `diststream` error.

`label`

> When printing errors, each line is prefixed by `[label]`. When the label is empty, each iterative algorithm uses its default label, e.g. `"cg"` for the `cg` conjugate gradient. By default the label is empty and this option is used to customize the convergence trace.

`krylov_dimension`

> The dimension of the Krylov space used by the `gmres` algorithm. Default is `krylov_dimension=6`.

# Options for developers

`verbose_level`

> Can be set to 0, 1, 2 or 3. The default is 0.

`level_of_fill`

> Built an incomplete factorization with the prescribed level of fill [1:5].

`do_check`

> Performs extra checks for debug.

`force_seq`

> In distributed mode, restrict the linear system resolution to diagonal blocs per process. This option is only active when using the `mumps` direct solver.

`ooc`

> Out-of-core limit (Mo/percent depending on compilation options). In development.

`amalgamation`

> Level of amalgamation [10:70] for Kass. In development.

# Implementation

This documentation has been generated from file linalg/lib/solver_option.h

class solver_option {
public:
typedef std::size_t size_type;
static const long int decide = -1;
mutable long int iterative;
Float tol;
size_type max_iter;
bool absolute_stopping;
mutable Float residue;
mutable size_type n_iter;
odiststream* p_err;
mutable std::string label;
size_type krylov_dimension;
size_type n_refinement;
bool compute_determinant;
std::string preferred_library;
size_type verbose_level;
bool do_check;
bool force_seq;
size_type level_of_fill;
size_type amalgamation;
size_type ooc;
// allocator and default values:
solver_option()
: iterative (decide),
#if defined(_RHEOLEF_HAVE_FLOAT128)
tol (1e6*std::numeric_limits<Float>::epsilon()),
#else
tol (1e3*std::numeric_limits<Float>::epsilon()),
#endif
max_iter (100000),
absolute_stopping (true),
residue (0),
n_iter (0),
p_err (&derr),
label (),
krylov_dimension (6),
n_refinement (2),
compute_determinant(false),
preferred_library(),
verbose_level (0),
do_check (false),
force_seq (false),
level_of_fill (1),
amalgamation (10),
ooc (20000)
{
}
solver_option (const solver_option&);
solver_option& operator= (const solver_option&);
template <class T, class M>
static std::string default_preferred_library (const csr<T,M>& a);
template <class T, class M>
static std::string used_library (const csr<T,M>& a, const solver_option& sopt = solver_option());
size_type
field::size_type size_type
Definition: branch.cc:425
Float
see the Float page for the full documentation
rheolef::solver_option::level_of_fill
size_type level_of_fill
Definition: solver_option.h:174
rheolef::solver_option::force_seq
bool force_seq
Definition: solver_option.h:173
rheolef::solver_option::max_iter
size_type max_iter
Definition: solver_option.h:161
rheolef::solver_option::n_refinement
size_type n_refinement
Definition: solver_option.h:168
rheolef::solver_option::label
std::string label
Definition: solver_option.h:166
rheolef::solver_option::decide
static const long int decide
Definition: solver_option.h:158
rheolef::solver_option::default_preferred_library
static std::string default_preferred_library(const csr< T, M > &a)
Definition: solver_option.h:274
rheolef::solver_option::solver_option
solver_option()
Definition: solver_option.h:180
rheolef::solver_option::absolute_stopping
bool absolute_stopping
Definition: solver_option.h:162
rheolef::solver_option::amalgamation
size_type amalgamation
Definition: solver_option.h:175
rheolef::solver_option::ooc
size_type ooc
Definition: solver_option.h:176
rheolef::solver_option::krylov_dimension
size_type krylov_dimension
Definition: solver_option.h:167
rheolef::solver_option::p_err
odiststream * p_err
Definition: solver_option.h:165
rheolef::solver_option::n_iter
size_type n_iter
Definition: solver_option.h:164
rheolef::solver_option::size_type
std::size_t size_type
Definition: solver_option.h:157
rheolef::solver_option::compute_determinant
bool compute_determinant
Definition: solver_option.h:169
rheolef::solver_option::used_library
static std::string used_library(const csr< T, M > &a, const solver_option &sopt=solver_option())
Definition: solver_option.h:281
rheolef::solver_option::tol
Float tol
Definition: solver_option.h:160
rheolef::solver_option::do_check
bool do_check
Definition: solver_option.h:172
rheolef::solver_option::operator=
solver_option & operator=(const solver_option &)
Definition: solver_option.h:249
rheolef::solver_option::residue
Float residue
Definition: solver_option.h:163
rheolef::solver_option::preferred_library
std::string preferred_library
Definition: solver_option.h:170
rheolef::solver_option::verbose_level
size_type verbose_level
Definition: solver_option.h:171
rheolef::solver_option::iterative
long int iterative
Definition: solver_option.h:159
rheolef::derr
odiststream derr(cerr)
see the diststream page for the full documentation
Definition: diststream.h:436
a
Definition: diffusion_isotropic.h:25
epsilon
Float epsilon
Definition: transmission_error.cc:25
};