Solver Util

Table based solver creation. More...

Functions
function util solver	CondAbort (condition, message)
function util solver	CreateConvCheck (convCheckDesc, solverutil)
function util solver	CreateLinearSolver (solverDesc, solverutil)
function util solver	CreateLineSearch (lineSearchDesc)
function util solver	CreateMGStats (mgStatsDesc)
function util solver	CreateOrdering (orderingDesc, solverutil)
function util solver	CreatePreconditioner (precondDesc, solverutil)
function util solver	CreateSolver (solverDesc, solverutil)
function util solver	CreateTransfer (transferDesc, solverutil)
function util solver	PrepareSolverUtil (solverDesc, solverutil)
function util solver	PrepareStep (desc, nestedStep, timeStep)
function util solver	SetDebugWriter (obj, desc, defaults, solverutil)
function util solver	SolveLinearProblem (domainDisc, solverDesc, outFilePrefix, startValueCB)
function util solver	SolveLinearTimeProblem (domDisc, solverDesc, timeDesc, outDesc, startValueCB)
function util solver	SolveNonLinearTimeProblem (domDisc, solverDesc, timeDesc, outDesc, startValueCB)

Detailed Description

Table based solver creation.

Given a (possibly nested) solver description, e.g.,

solver = {
  type = "bicgstab",
  precond = "ilu",
  convCheck = "standard"
}

a call e.g. to util.solver.CreateSolver(solver) creates and returns the requested solver.

All components may either be specified through a string-id or through a descriptor. You only have to specify those components which deviate from the defaults (solver.util.defaults), the rest will be ammended.

To use a geometric multigrid preconditioner, you either have to specify an approxSpace entry in its descriptor or set 'util.solver.defaults.approxSpace' before calling any 'util.solver.Create...' method.

Examples

Several examples follow:

Example: Creating an exact solver

solver = util.solver.CreateSolver("lu")

Example: Creating a simple iterative jacobi solver

solverDesc = {
  type = "linear",
  precond = "jac"
}
 
solver = util.solver.CreateSolver(solverDesc)

Example: Creating a simple iterative jacobi solver with custom parameters

solverDesc = {
  type = "linear",
  precond = {
    type = "jac",
    damping = 0.5
  }
}
 
solver = util.solver.CreateSolver(solverDesc)

Example: Creation of a bicgstab solver with geometric multigrid preconditioner

here someApproxSpace points to a previously created approximation space

solverDesc = 
{
  type = "bicgstab",      -- linear solver type ["bicgstab", "cg", "linear"]
  precond = 
  { 
    type    = "gmg",  -- preconditioner ["gmg", "ilu", "ilut", "jac", "gs", "sgs"]
    smoother  = "gs", -- gmg-smoother ["ilu", "ilut", "jac", "gs", "sgs"]
    cycle   = "V",    -- gmg-cycle ["V", "F", "W"]
    preSmooth = 3,    -- number presmoothing steps
    postSmooth  = 3,    -- number postsmoothing steps
    rap   = false,  -- comutes RAP-product instead of assembling if true
    baseLevel = 0,    -- gmg - baselevel
    baseSolver  = {     -- better options are most likely "lu" or "superlu"
      type    = "bicgstab",
      precond   = "gs",
      convCheck = {
        type    = "standard",
        iterations  = 1000,
        absolute  = 1e-12,
        reduction = 1e-10,  -- higher values may suffice and may be much
                  -- more efficent (e.g. 1e-2, 1e-4, ...).
        verbose   = false
      }
    },
    approxSpace = someApproxSpace,
  },
 
  convCheck = "standard"
}
solver = util.solver.CreateSolver(solverDesc)

Example: Providing custom solver and preconditioner objects (advanced)

You may also provide instances of preconditioners instead of descriptor tables:

solverDesc =
{
  type = "linear",
  precond = ILU()   -- for each component one can optionally supply a custom instance
}
solver = util.solver.CreateSolver(solverDesc)

Example: Accessing the created solvers and preconditioners (advanced)

For conveniance, all the methods will add an 'instance' entry to their respective descriptor tables, assigning the created solver component. If you thus setup a solver, e.g.

solver = {
  type = "bicgstab",
  precond = {
    type = "ilu"
  }
}

you may later access 'solver.instance' and 'solver.precond.instance'. Note that this is only possible if you specified a component through a descriptor. If you use the short form, e.g.

solver = {
  type = "bicgstab",
  precond = "ilu"
}

you will still be able to access 'solver.instance', but you can't access 'solver.precond.instance'.

Non-Linear Solvers

The following listing gives an overview over available non-linear solvers and their default parameters. Pass the descriptor of a non-linear solver to

util.solver.CreateSolver(...)

to obtain the described solved.

linSolver can be any linear solver listed in the Linear Solvers section.

convCheck can be any convergence check listed in the Convergence Checks section.

lineSearch can be any line search method listed in the Line Search section.

Currently only the Newton method is available as non-linear solver.

Newton Method

{
  type    = "newton",
  convCheck = "standard",
  linSolver = "bicgstab",
  lineSearch  = nil
}

Linear Solvers

The following listing gives an overview over available linear-solvers and their default parameters. Pass the descriptor of a linear solver to

util.solver.CreateSolver(...)

to obtain the described solved.

precond can be any preconditioner listed in the Preconditioners section.

convCheck can be any convergence check listed in the Convergence Checks section.

Linear Solver

{
  type    = "linear",
  precond = "ilu",
  convCheck = "standard"
}

Conjugate Gradients

{
  type    = "cg",
  precond = "ilu",
  convCheck = "standard"
}

BiCGStab

{
  type    = "bicgstab",
  precond = "ilu",
  convCheck = "standard"
}

Preconditioners

The following listing gives an overview over available preconditioners and their default parameters.

Geometric Multigrid

{
  type              = "gmg",
  adaptive            = false,
  approxSpace             = nil,
  baseLevel             = 0,
  baseSolver            = "lu", -- any solver listed in the 'Solvers' section
  cycle               = "V",
  discretization          = nil,    -- only necessary if the underlying matrix is not of type AssembledLinearOperator
  gatheredBaseSolverIfAmbiguous       = false,
  preSmooth             = 3,
  postSmooth            = 3,
  rap               = false,
  rim               = false,
  emulateFullRefined          = false,
  smoother            = "gs", -- any preconditioner listed in the 'Preconditioners' section
  transfer            = "std",  -- any transfer listed in the 'Transfers' section
  debug               = false,
  mgStats           = nil   -- any mgStats listed in the 'MGStats' section
}

ILU

{
  type      = "ilu",
  beta      = 0,
  damping     = 1,
  sortEps     = 1.e-50,
  inversionEps    = 1.e-8
}

ILUT

{
  type    = "ilut",
  threshold   = 1e-6
}

Jacobi

{
  type  = "jac",
  damping = 0.66
}

Gauss Seidel

{
  type = "gs"
}

Block Gauss Seidel

{
  type = "bgs"
}

Symmetric Gauss Seidel

{
  type = "sgs"
}

Element Gauss Seidel

{
  type = "egs"
}

Schur

{
  type      = "schur",
  dirichletSolver = "lu",
  skeletonSolver    = "lu"
}

Convergence Checks

The following listing gives an overview over available convergence checks and their default parameters.

Standard convergence check

{
  type    = "standard",
  iterations  = 100,
  absolute  = 1e-12,
  reduction = 1e-6,
  verbose = true
}

Transfer Operators

The following listing gives an overview over available transfer operators and their default parameters.

Standard Transfer Operator

{
  type        = "std",
  restrictionDamp     = 1.0,
  prolongationDamp    = 1.0,
  enableP1LagrangeOptimization   = true,
  debug         = false
}

Line Search Methods

The following listing gives an overview over available line search methods and their default parameters.

Standard Line Search Method

{
  type      = "standard",
  maxSteps    = 10,
  lambdaStart   = 1,
  lambdaReduce    = 0.5,
  acceptBest    = true,
  checkAll    = false
}

MGStats

The following listing gives an overview over available MGStats objects. MGStats objects are used to record statistics on individual multigrid cycles. They add some overhead, so one should only use them for debugging.

MGStats

{
  type    = "standard",
  filenamePrefix  = "mgstats",
  exitOnError = false,
  writeErrVecs  = false,
  writeErrDiffs = false,
  activeStages  = nil
}

Function Documentation

CondAbort()

function util solver CondAbort	(	condition	,
		message
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :576-581

function util.solver.CondAbort(condition, message)
  if condition == true then
    print("ERROR in util.solver: " .. message)
    exit()
  end
end

CreateConvCheck()

function util solver CreateConvCheck	(	convCheckDesc	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :962-1011

CreateLinearSolver()

function util solver CreateLinearSolver	(	solverDesc	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :638-721

CreateLineSearch()

function util solver CreateLineSearch

(

lineSearchDesc

)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1013-1042

CreateMGStats()

function util solver CreateMGStats

(

mgStatsDesc

)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1045-1076

CreateOrdering()

function util solver CreateOrdering	(	orderingDesc	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :749-787

CreatePreconditioner()

function util solver CreatePreconditioner	(	precondDesc	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :791-959

CreateSolver()

function util solver CreateSolver	(	solverDesc	,
		solverutil
	)

Creates a solver.

Parameters

solverutil

You may OPTIONALLY pass a table solverutil in which solver related information will be stored. If solverDesc is a table, you may also acacess this information through solverDesc.solverutil (even if the parameter solverutil == nil).

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :601-636

CreateTransfer()

function util solver CreateTransfer	(	transferDesc	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :723-747

PrepareSolverUtil()

function util solver PrepareSolverUtil	(	solverDesc	,
		solverutil
	)

if solverDesc is a table, solverDesc.solverutil will be set to solverutil or initialized as an empty table. The method will then return solverDesc.solverutil. If solverDesc is not a table, the method returns solverutil or {}, if solverutil == nil.

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :587-594

function util.solver.PrepareSolverUtil(solverDesc, solverutil)
  if type(solverDesc) == "table" then
    solverDesc.solverutil = solverutil or solverDesc.solverutil or {}
    return solverDesc.solverutil
  else
    return solverutil or {}
  end
end

PrepareStep()

function util solver PrepareStep	(	desc	,
		nestedStep	,
		timeStep
	)

Prepares a solution step, e.g. during nested iterations.

Parameters

desc	a solver-desc which was used during solver-creation in one of the solver_util methods or a solverutil table, which is was also created in one of the solver_util methods or simply a table which holds a bunch of Convergence-Check descriptor tables.
nestedStep	(optional) the step of the nested iteration (default: 1)
timeStep	(optional) the current time step (default: 1)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1147-1172

SetDebugWriter()

function util solver SetDebugWriter	(	obj	,
		desc	,
		defaults	,
		solverutil
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1078-1135

SolveLinearProblem()

function util solver SolveLinearProblem	(	domainDisc	,
		solverDesc	,
		outFilePrefix	,
		startValueCB
	)

Solves a linear problem given as a domain discretization

Parameters

domDisc	the domain discretization object
solverDesc	a valid solver descriptor or solver object
outFilePrefix	(optional) .vtk and .vec files of the solution are stored.

Returns

A, u, b, where A is the system matrix, u is the solution and b is the right hand side

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1181-1209

SolveLinearTimeProblem()

function util solver SolveLinearTimeProblem	(	domDisc	,
		solverDesc	,
		timeDesc	,
		outDesc	,
		startValueCB
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1212-1249

SolveNonLinearTimeProblem()

function util solver SolveNonLinearTimeProblem	(	domDisc	,
		solverDesc	,
		timeDesc	,
		outDesc	,
		startValueCB
	)

location: /home/runner/work/docs/docs/ug4/ugcore/scripts/util / solver_util.lua :1252-1289