Transient linear solver options

Solving a transient linear problem

Transient linear solvers can be orchestrated in GeMA by using code simillar to the following fragment:

local solver = fem.initTransientSolver('physicsId', 'numericSolverId', solverOptions)

local dt     = 0.05      -- The time step
local endt   = 5.0       -- Simulation duration
local nsteps = endt / dt -- Number of steps

-- Simulation time loop
for i=1, nsteps do
  -- Set the current time in the model
  setCurrentTime(i*dt)

  -- Solve one time step
  fem.transientStep(solver, dt)
end

fem.initTransientSolver(physicsList, numericSolver, solverOptions, nonlinear)
Description:	Creates and initializes a transient linear FEM solver intended to be used on a time loop as exemplified above. Returns a solver object that should be passed as parameter in calls to fem.transientStep(), fem.transientLinearStep() and fem.transientLinearResidual().
Parameters:	physicsList	A string with the id of the physics responsible for providing the FEM process with the equations to be solved. Can also be a table with multiple physics ids. All physics objects must be tied to the same mesh.
	numericSolver	A string with the id of the numeric solver that will be used to solve the final linear system.
	solverOptions	An optional Lua table with a set of flags defining options for the solver. The transient linear solver accepts the following options: - assemblerDofMode: A an optional string parameter that instructs the solver how fixed dofs should be treated. By default (assemblerDofMode empty or equal to "automatic"), the solver selects how to work. The option "add fixed dofs" tells the solver that global matrices should include lines for fixed dofs that will be removed prior to solving the system. The option "remove fixed dofs" tells the solver that the assembler should remove fixed dofs and don't include them on the assembled matrix at all. This is a superior option (and the default option for the linear solver) but at the moment can not be used when boundary condition application points change over the simulation time (it can be used though if bc values are changing, without changing the nodes / edges / faces to which they are applied). - numThreads: An option that defines the desired number of worker threads that will be used. If this option is missing, or is equal to -1, the project configured maximum number of concurrent threads, maxThreads from the simulation options, will be used. A value greater than maxThreads will revert to that maximum. A value of zero disables threading, meaning that tasks will be executed by the main thread. A value of 1, although weird, can be used for testing: all tasks are executed by a single thread, different from the main one. - numTasks: An option that defines the number of tasks that the assembler will use to process mesh elements. If this option is missing or is equal to 0, the default number of tasks, defNumTasks from the simulation options, will be used. A value greater than 0 specifies a fixed number of tasks while a value less than 0 specifies a multiple of the number of worker threads, so a value of 5 means exactly 5 tasks, while a value of -2 means that the number of tasks should be equal to twice the number of worker threads. - cellPartitionStrategy: An option that defines the default strategy that will be used to partition mesh cells into tasks. If this option is missing, the default strategy, defCellPartitionStrategy from the simulation options, will be used. Accepted values are "default" and "sequential". - printOptions: A table with a set of print options for the solver. This options can instruct the solver to print all of its internal matrices and are usefull when debugging new physics implementations or to fully understand the FEM process behavior.
	nonlinear	An optional flag that should be set to true when this solver is used for solving non-linear problems (see fem.transientLinearStep()). Default = false.
Returns:	The solver object.

fem.transientStep(solver, dt, updateDof)
Description:	Executes a new time step of the transient linear solver created by the previous call to fem.initTransientSolver(). Should be called inside a loop until reaching the end of the simulation.
Parameters:	solver	The solver object returned by fem.initTransientSolver().
	dt	The time step that should be used for advancing the simulation time. The value is expected to be given in the current time simulation unit defined in a call to setCurrentTimeUnit(), or in seconds if this function was not called.
	updateDof	An optional flag that when set to true, informs the solver that the contents of the simulation degrees of freedom where changed by the orchestration (the mesh has changed, for example) and that the solver should reload that information. Default = false.
Returns:	Nothing.

Solving a transient non-linear problem by repeated linear iterations

Although the non-linear solver is the preferred method for solving non-linear problems, the transient linear solver can also be used in simple cases to solve non-linear problems by repeatedly iterating over the linear solution until convergence is achieved in each time step. This pattern can be done with the transient linear solver by applying and improving on the following (naive) code fragment:

local solver = fem.initTransientSolver('physicsId', 'numericSolverId', solverOptions, true)

local dt     = 0.05      -- The time step
local endt   = 5.0       -- Simulation duration
local nsteps = endt / dt -- Number of steps
local tol    = 1e-5      -- The tolerance for the non-linear iteration

-- Simulation time loop
for i=1, nsteps do
  -- Set the current time in the model
  setCurrentTime(i*dt)

  -- Solve one time step
  local iter = 1
  local r    = 1.0

  while r > tol do
    fem.transientLinearStep(solver, dt, iter)
    r = fem.transientLinearResidual(solver, dt)

    iter = iter + 1
  end
end

fem.transientLinearStep(solver, dt, iter, updateDof)
Description:	Executes a new step of the transient linear solver created by the previous call to fem.initTransientSolver(). Should be called inside a loop until convergence is achieved for each time step.
Parameters:	solver	The solver object returned by fem.initTransientSolver().
	dt	The time step that should be used for advancing the simulation time. The value is expected to be given in the current time simulation unit defined in a call to setCurrentTimeUnit(), or in seconds if this function was not called. Should be the same value in every call during the non-linear loop.
	iter	The number of the non-linear iteration (1 for the first one).
	updateDof	An optional flag that when set to true, informs the solver that the contents of the simulation degrees of freedom where changed by the orchestration (the mesh has changed, for example) and that the solver should reload that information. Default = false.
Returns:	Nothing.

fem.transientLinearResidual(solver, dt, evalMax)
Description:	Calculates the residual error associated with the last linear step taken by a call to fem.transientLinearStep(). Should be called inside the non-linear loop to check if convergence has been achieved. This function returns the L2 norm of the residual vector given by \(r = K(x_i)x_i - f\). If the second parameter evalMax is true, it also returns the maximum and the average values among each of the values in the residual vector. The default is false since this option only makes sense if all degrees of freedom in the result space are comparable.
Parameters:	solver	The solver object returned by fem.initTransientSolver().
	dt	The time step taken when advancing the simulation on the call to fem.transientLinearStep().
	evalMax	Optional flag defining if the maximum and average values among the residual entries should be calculated. Default = false.
Returns:	The L2 norm + the maximum and the average value in the residual vector if evalMax is true.