Package esys :: Package escript :: Module linearPDEs :: Class SolverOptions
[hide private]
[frames] | no frames]

Class SolverOptions

object --+
         |
        SolverOptions

this class defines the solver options for a linear or non-linear solver.

The option also supports the handling of diagnostic informations.

Typical usage is

opts=SolverOptions() print opts opts.resetDiagnostics() u=solver(opts) print "number of iteration steps: =",opts.getDiagnostics("num_iter")

Instance Methods [hide private]
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 
__str__(self)
str(x)
 
_getRestartForC(self)
 
_updateDiagnostics(self, name, value)
Updates diagnostic information
bool
acceptConvergenceFailure(self)
Returns True if a failure to meet the stopping criteria within the given number of iteration steps is not raising in exception.
bool
adaptInnerTolerance(self)
Returns True if the tolerance of the inner solver is selected automatically.
float
getAbsoluteTolerance(self)
Returns the absolute tolerance for the solver
in the list SolverOptions.DEFAULT, SolverOptions.YAIR_SHAPIRA_COARSENING, SolverOptions.RUGE_STUEBEN_COARSENING, SolverOptions.AGGREGATION_COARSENING
getCoarsening(self)
Returns the key of the coarsening algorithm to be applied AMG.
float
getCoarseningThreshold(self)
Returns the threshold for coarsening in the algebraic multi level solver or preconditioner
 
getDiagnostics(self, name)
Returns the diagnostic information C{name}
float
getDropStorage(self)
Returns the maximum allowed increase in storage for ILUT
float
getDropTolerance(self)
Returns the relative drop tolerance in ILUT
int
getInnerIterMax(self)
Returns maximum number of inner iteration steps
float
getInnerTolerance(self)
Returns the relative tolerance for an inner iteration scheme
int
getIterMax(self)
Returns maximum number of iteration steps
int
getLevelMax(self)
Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
int
getMinCoarseMatrixSize(self)
Returns the minumum size of the coarsest level matrix in AMG.
 
getName(self, key)
returns the name of a given key
int
getNumPostSweeps(self)
Returns he number of sweeps in the post-smoothing step of a multi level solver or preconditioner
int
getNumPreSweeps(self)
Returns he number of sweeps in the pre-smoothing step of a multi level solver or preconditioner
int
getNumSweeps(self)
Returns the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.
in the list SolverOptions.DEFAULT, SolverOptions.PASO, SolverOptions.SUPER_LU, SolverOptions.PASTIX, SolverOptions.MKL, SolverOptions.UMFPACK, SolverOptions.TRILINOS
getPackage(self)
Returns the solver package key
in the list SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI, SolverOptions.AMG, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU, SolverOptions.NO_PRECONDITIONER
getPreconditioner(self)
Returns key of the preconditioner to be used.
float
getRelaxationFactor(self)
Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.
in the list SolverOptions.NO_REORDERING, SolverOptions.NO_REORDERING, SolverOptions.NO_REORDERING, SolverOptions.DEFAULT_REORDERING
getReordering(self)
Returns the key of the reordering method to be applied if supported by the solver.
int or None
getRestart(self)
Returns the number of iterations steps after which GMRES is performing a restart.
in the list SolverOptions.DEFAULT, SolverOptions.DIRECT, SolverOptions.CHOLEVSKY, SolverOptions.PCG, SolverOptions.CR, SolverOptions.CGS, SolverOptions.BICGSTAB, SolverOptions.SSOR, SolverOptions.GMRES, SolverOptions.PRES20, SolverOptions.LUMPING, SolverOptions.ITERATIVE, SolverOptions.AMG, SolverOptions.NONLINEAR_GMRES, SolverOptions.TFQMR, SolverOptions.MINRES, SolverOptions.GAUSS_SEIDEL
getSolverMethod(self)
Returns key of the solver method to be used.
 
getSummary(self)
Returns a string reporting the current settings
float
getTolerance(self)
Returns the relative tolerance for the solver
int
getTruncation(self)
Returns the number of residuals in GMRES to be stored for orthogonalization
 
hasConverged(self)
Returns True if the last solver call has been finalized successfully.
bool
isSymmetric(self)
Checks if symmetry of the coefficient matrix is indicated.
bool
isVerbose(self)
Returns True if the solver is expected to be verbose.
 
resetDiagnostics(self, all=False)
resets the diagnostics
 
setAbsoluteTolerance(self, atol=0.0)
Sets the absolute tolerance for the solver
 
setAcceptanceConvergenceFailure(self, accept=False)
Sets a flag to indicate the acceptance of a failure of convergence.
 
setAcceptanceConvergenceFailureOff(self)
Switches the acceptance of a failure of convergence off.
 
setAcceptanceConvergenceFailureOn(self)
Switches the acceptance of a failure of convergence on
 
setCoarsening(self, method=0)
Sets the key of the coarsening method to be applied in AMG.
 
setCoarseningThreshold(self, theta=0.05)
Sets the threshold for coarsening in the algebraic multi level solver or preconditioner
 
setDropStorage(self, storage=2.0)
Sets the maximum allowed increase in storage for ILUT.
 
setDropTolerance(self, drop_tol=0.01)
Sets the relative drop tolerance in ILUT
 
setInnerIterMax(self, iter_max=10)
Sets the maximum number of iteration steps for the inner iteration.
 
setInnerTolerance(self, rtol=0.9)
Sets the relative tolerance for an inner iteration scheme for instance on the coarsest level in a multi-level scheme.
 
setInnerToleranceAdaption(self, adapt=True)
Sets a flag to indicate automatic selection of the inner tolerance.
 
setInnerToleranceAdaptionOff(self)
Switches the automatic selection of inner tolerance off.
 
setInnerToleranceAdaptionOn(self)
Switches the automatic selection of inner tolerance on
 
setIterMax(self, iter_max=100000)
Sets the maximum number of iteration steps
 
setLevelMax(self, level_max=10)
Sets the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
 
setMinCoarseMatrixSize(self, size=500)
Sets the minumum size of the coarsest level matrix in AMG.
 
setNumPostSweeps(self, sweeps=2)
Sets the number of sweeps in the post-smoothing step of a multi level solver or preconditioner
 
setNumPreSweeps(self, sweeps=2)
Sets the number of sweeps in the pre-smoothing step of a multi level solver or preconditioner
 
setNumSweeps(self, sweeps=2)
Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.
 
setPackage(self, package=0)
Sets the solver package to be used as a solver.
 
setPreconditioner(self, preconditioner=10)
Sets the preconditioner to be used.
 
setRelaxationFactor(self, factor=0.3)
Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.
 
setReordering(self, ordering=30)
Sets the key of the reordering method to be applied if supported by the solver.
 
setRestart(self, restart=None)
Sets the number of iterations steps after which GMRES is performing a restart.
 
setSolverMethod(self, method=0)
Sets the solver method to be used.
 
setSymmetry(self, flag=False)
Sets the symmetry flag for the coefficient matrix to flag.
 
setSymmetryOff(self)
Clears the symmetry flag for the coefficient matrix.
 
setSymmetryOn(self)
Sets the symmetry flag to indicate that the coefficient matrix is symmetric.
 
setTolerance(self, rtol=1e-08)
Sets the relative tolerance for the solver
 
setTruncation(self, truncation=20)
Sets the number of residuals in GMRES to be stored for orthogonalization.
 
setVerbosity(self, verbose=False)
Sets the verbosity flag for the solver to flag.
 
setVerbosityOff(self)
Switches the verbosity of the solver off.
 
setVerbosityOn(self)
Switches the verbosity of the solver on.

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__

Class Variables [hide private]
  AGGREGATION_COARSENING = 35
AMG coarsening using (symmetric) aggregation
  AMG = 22
Algebraic Multi Grid
  BICGSTAB = 6
The stabilized Bi-Conjugate Gradient method
  CGS = 5
The conjugate gradient square method
  CHOLEVSKY = 2
The direct solver based on LDLt factorization (can only be applied for symmetric PDEs)
  CR = 4
The conjugate residual method
  DEFAULT = 0
The default method used to solve the system of linear equations
  DEFAULT_REORDERING = 30
the reordering method recommended by the solver
  DIRECT = 1
The direct solver based on LDU factorization
  GAUSS_SEIDEL = 28
Gauss-Seidel solver
  GMRES = 11
The Gram-Schmidt minimum residual method
  ILU0 = 8
The incomplete LU factorization preconditioner with no fill-in
  ILUT = 9
The incomplete LU factorization preconditioner with fill-in
  ITERATIVE = 20
The default iterative solver
  JACOBI = 10
The Jacobi preconditioner
  LUMPING = 13
Matrix lumping
  MINIMUM_FILL_IN = 18
Reorder matrix to reduce fill-in during factorization
  MINRES = 27
Minimum residual method
  MIN_COARSE_MATRIX_SIZE = 37
minimum size of the coarsest level matrix to use direct solver.
  MKL = 15
Intel's MKL solver library
  NESTED_DISSECTION = 19
Reorder matrix to improve load balancing during factorization
  NONLINEAR_GMRES = 25
  NO_PRECONDITIONER = 36
no preconditioner is applied.
  NO_REORDERING = 17
No matrix reordering allowed
  PASO = 21
PASO solver package
  PASTIX = 32
the Pastix direct solver_package
  PCG = 3
The preconditioned conjugate gradient method (can only be applied for symmetric PDEs)
  PRES20 = 12
Special GMRES with restart after 20 steps and truncation after 5 residuals
  REC_ILU = 23
recursive ILU0
  RILU = 29
relaxed ILU0
  RUGE_STUEBEN_COARSENING = 34
AMG coarsening method by Ruge and Stueben
  SCSL
SGI SCSL solver library
  SSOR = 7
The symmetric over-relaxation method
  SUPER_LU = 31
the Super_LU solver package
  TFQMR = 26
Transport Free Quasi Minimal Residual method
  TRILINOS = 24
The TRILINOS parallel solver class library from Sandia National Labs
  UMFPACK = 16
The UMFPACK library
  YAIR_SHAPIRA_COARSENING = 33
AMG coarsening method by Yair-Shapira
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__
(inherited documentation)

__str__(self)
(Informal representation operator)

 

str(x)

Overrides: object.__str__
(inherited documentation)

_updateDiagnostics(self, name, value)

 

Updates diagnostic information

Parameters:
  • name (str in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "net_time", "residual_norm", "converged".) - name of diagnostic information
  • vale - new value of the diagnostic information

Note: this function is used by a solver to report diagnostics informations.

acceptConvergenceFailure(self)

 

Returns True if a failure to meet the stopping criteria within the given number of iteration steps is not raising in exception. This is useful if a solver is used in a non-linear context where the non-linear solver can continue even if the returned the solution does not necessarily meet the stopping criteria. One can use the hasConverged method to check if the last call to the solver was successful.

Returns: bool
True if a failure to achieve convergence is accepted.

adaptInnerTolerance(self)

 

Returns True if the tolerance of the inner solver is selected automatically. Otherwise the inner tolerance set by setInnerTolerance is used.

Returns: bool
True if inner tolerance adaption is chosen.

getDiagnostics(self, name)

 

Returns the diagnostic information C{name} 

@param name: name of diagnostic information where
- "num_iter": the number of iteration steps
- "cum_num_iter": the cumulative number of iteration steps
- "num_level": the number of level in multi level solver
- "num_inner_iter": the number of inner iteration steps
- "cum_num_inner_iter": the cumulative number of inner iteration steps
- "time": execution time 
- "cum_time": cumulative execution time
- "set_up_time": time to set up of the solver, typically this includes factorization and reordering
- "cum_set_up_time": cumulative time to set up of the solver
- "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner
- "cum_net_time": cumulative net execution time
- "residual_norm": norm of the final residual
- "converged": return self.__converged     
@type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "net_time", "residual_norm", "converged".
@return: requested value. C{None} is returned if the value is undefined.
@note: If the solver has thrown an exception diagnostic values have an undefined status.

getName(self, key)

 

returns the name of a given key

Parameters:
  • key - a valid key

getRestart(self)

 

Returns the number of iterations steps after which GMRES is performing a restart. If None is returned no restart is performed.

Returns: int or None

hasConverged(self)

 

Returns True if the last solver call has been finalized successfully.

Note: if an exception has been thrown by the solver the status of this flag is undefined.

isSymmetric(self)

 

Checks if symmetry of the coefficient matrix is indicated.

Returns: bool
True if a symmetric PDE is indicated, False otherwise

isVerbose(self)

 

Returns True if the solver is expected to be verbose.

Returns: bool
True if verbosity of switched on.

resetDiagnostics(self, all=False)

 

resets the diagnostics

Parameters:
  • all (bool) - if all is True all diagnostics including accumulative counters are reset.

setAbsoluteTolerance(self, atol=0.0)

 

Sets the absolute tolerance for the solver

Parameters:
  • atol (non-negative float) - absolute tolerance

setAcceptanceConvergenceFailure(self, accept=False)

 

Sets a flag to indicate the acceptance of a failure of convergence.

Parameters:
  • accept (bool) - If True, any failure to achieve convergence is accepted.

setCoarsening(self, method=0)

 

Sets the key of the coarsening method to be applied in AMG.

Parameters:

setCoarseningThreshold(self, theta=0.05)

 

Sets the threshold for coarsening in the algebraic multi level solver or preconditioner

Parameters:
  • theta (positive float) - threshold for coarsening

setDropStorage(self, storage=2.0)

 

Sets the maximum allowed increase in storage for ILUT. storage=2 would mean that a doubling of the storage needed for the coefficient matrix is allowed in the ILUT factorization.

Parameters:
  • storage (float) - allowed storage increase

setDropTolerance(self, drop_tol=0.01)

 

Sets the relative drop tolerance in ILUT

Parameters:
  • drop_tol (positive float) - drop tolerance

setInnerIterMax(self, iter_max=10)

 

Sets the maximum number of iteration steps for the inner iteration.

Parameters:
  • iter_max (int) - maximum number of inner iterations

setInnerTolerance(self, rtol=0.9)

 

 Sets the relative tolerance for an inner iteration scheme for instance
on the coarsest level in a multi-level scheme.

@param rtol: inner relative tolerance
@type rtol: positive C{float}

setInnerToleranceAdaption(self, adapt=True)

 

Sets a flag to indicate automatic selection of the inner tolerance.

Parameters:
  • adapt (bool) - If True, the inner tolerance is selected automatically.

setIterMax(self, iter_max=100000)

 

Sets the maximum number of iteration steps

Parameters:
  • iter_max (int) - maximum number of iteration steps

setLevelMax(self, level_max=10)

 

Sets the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner

Parameters:
  • level_max (int) - maximum number of levels

setMinCoarseMatrixSize(self, size=500)

 

Sets the minumum size of the coarsest level matrix in AMG.

Parameters:
  • size (positive int or None) - minumum size of the coarsest level matrix .

setNumPostSweeps(self, sweeps=2)

 

Sets the number of sweeps in the post-smoothing step of a multi level solver or preconditioner

Parameters:
  • sweeps - number of sweeps
  • theta (positive int)

setNumPreSweeps(self, sweeps=2)

 

Sets the number of sweeps in the pre-smoothing step of a multi level solver or preconditioner

Parameters:
  • sweeps - number of sweeps
  • theta (positive int)

setNumSweeps(self, sweeps=2)

 

Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.

Parameters:
  • sweeps - number of sweeps
  • theta (positive int)

setPackage(self, package=0)

 

Sets the solver package to be used as a solver.

Parameters:

Note: Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular is requested.

setPreconditioner(self, preconditioner=10)

 

Sets the preconditioner to be used.

Parameters:

Note: Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters an unknown preconditioner.

setRelaxationFactor(self, factor=0.3)

 

Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.

Parameters:
  • factor (float) - relaxation factor

Note: RILU with a relaxation factor 0 is identical to ILU0

setReordering(self, ordering=30)

 

Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering to optimize compute time and storage use during elimination.

Parameters:

setRestart(self, restart=None)

 

Sets the number of iterations steps after which GMRES is performing a restart.

Parameters:
  • restart (int or None) - number of iteration steps after which to perform a restart. If equal to None no restart is performed.

setSolverMethod(self, method=0)

 

Sets the solver method to be used. Use method=SolverOptions.DIRECT to indicate that a direct rather than an iterative solver should be used and Use method=SolverOptions.ITERATIVE to indicate that an iterative rather than a direct solver should be used.

Parameters:

Note: Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters an unknown solver method.

setSymmetry(self, flag=False)

 

Sets the symmetry flag for the coefficient matrix to flag.

Parameters:
  • flag (bool) - If True, the symmetry flag is set otherwise reset.

setTolerance(self, rtol=1e-08)

 

Sets the relative tolerance for the solver

Parameters:
  • rtol (non-negative float) - relative tolerance

setTruncation(self, truncation=20)

 

Sets the number of residuals in GMRES to be stored for orthogonalization. The more residuals are stored the faster GMRES converged but

Parameters:
  • truncation (int) - truncation

setVerbosity(self, verbose=False)

 

Sets the verbosity flag for the solver to flag.

Parameters:
  • flag (bool) - If True, the verbosity of the solver is switched on.