Linear solver processes

Solving a linear problem

fem.solve(physicsList, numericSolver, solverOptions)
Description:	Executes a linear FEM simulation as a single operation.
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 linear solver accepts the following options: - assemblerDofMode: 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). It can be changed to help debugging with the aid of print options and might be necessary for transient solvers. - 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.
Returns:	Nothing.

Examples:

local solverOptions = {
  printOptions = {
    elementMatrices = true,  -- All element matrices will be printed
    elementVectors  = true,  -- All element vectors will be printed
    assembledMatrix = true,  -- The global assembled matrix will be printed
    assembledVector = true,  -- All global assembled vector will be printed
  }
}

fem.solve('physicsId', 'numericSolverId')

fem.solve({'physics1Id', physics2Id'}, 'numericSolverId', solverOptions)

Solving a non-linear problem by repeated linear iterations

Although the non-linear solver is the preferred method for solving non-linear problems, the 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. This pattern can be done with the linear solver by applying and improving on the following (naive) code fragment:

local solver = fem.initLinearSolver({'physics'}, 'numeric_solver', solverOptions)
local r   = 1.0
local tol = 1e-5
while r > tol do
  fem.linearStep(solver)
  r = fem.linearResidual(solver)
end

fem.initLinearSolver(physicsList, numericSolver, solverOptions)
Description:	Creates and initializes a linear FEM solver intended to be used on a loop as exemplified above. Returns a solver object that should be passed as parameter in calls to fem.linearStep() and fem.linearResidual().
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 linear solver accepts the following options: - assemblerDofMode: 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). It can be changed to help debugging with the aid of print options and might be necessary for transient solvers. - 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.
Returns:	The solver object.

fem.linearStep(solver)
Description:	Executes a new step of the linear solver created by the previous call to fem.initLinearSolver(). Should be called inside a loop until convergence is achieved.
Parameters:	solver - The solver object returned by fem.initLinearSolver().
Returns:	Nothing.

fem.linearResidual(solver, evalMax)
Description:	Calculates the residual error associated with the last linear step taken by a call to fem.linearStep(). 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.initLinearSolver().
	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.