Convergence criteria
Convergence criteria are an essential part of numerical tools. They should be chosen wisely in order to obtain a reasonably accurate solution without performing more iterations than needed. This documentation describes how the user can practically assemble a set of convergence criteria.
Types
Iteration limit
The type
convergence_criterion.iteration_limit
is satisfied if the number of coupling iterations equals or is larger than a predefined maximum.
The settings
dictionary contains one entry:
parameter | type | description |
---|---|---|
maximum |
int | Maximum number of iterations. |
Absolute norm
The type
convergence_criterion.absolute_norm
is satisfied if the p-norm of the residual in the last coupling iteration
is smaller than a predefined tolerance
.
More information on how the residual is calculated can be found in the coupled solvers documentation.
The p-norm of the residual r is defined as
where r_i is the i-th component of the residual.
The settings
are as follows:
parameter | type | description |
---|---|---|
order |
int | Order p of the norm. |
tolerance |
double | Limit value for convergence. |
Relative norm
The type
convergence_criterion.relative_norm
is completely analogous to the absolute norm. Instead of the norm of
the last residual being smaller than a set tolerance
, now the ratio norm of the residual of the last coupling iteration to the
norm of the residual of the first coupling iteration is compared to a tolerance
. Zero divisions are avoided internally by
comparing the norm of the residual of the first coupling iteration to the machine limit for floating points, i.e. the smallest number
different from zero. In case this initial norm is too small, an exception will be raised. Should this happen, it is advised to opt
for the absolute norm criterion instead of relative norm.
These are the same as for convergence_criterion.absolute_norm
.
Solver coupling convergence
The type
convergence_criterion.solver_coupling_convergence
is a convergence criterion that uses the convergence of a solver to determine the convergence of the coupling loop.
The criterion is considered fulfilled once the solver converges in its first solver iteration.
Not all solvers allow for this feature, see their respective documentation.
A detailed explanation of this criterion is found in Spenke and Delaissé et al. [1].
Typically, a solver_coupling_convergence
criterion is used for each solver, combined with an and
criterion (see Combining multiple convergence criteria).
This way, the coupling loop is considered converged when all solvers converge in their first solver iteration.
The settings
dictionary contains one entry:
parameter | type | description |
---|---|---|
solver_index |
int | Index of the solverwrapper in the solver_wrappers list of the coupled solver to which this convergence criterion belongs. |
Combining multiple convergence criteria
In most cases, it is wise to combine two criteria: one to ensure a high enough accuracy and an iteration limit in order
to break loops that are not converging fast enough. In that case, the criteria are combined via or
or and
statements.
In that case, the type
is set to convergence_criterion.or
(alternatively, convergence_criterion.and
) and the settings
contain a criteria_list
that contains single criteria in the same way as described above.
In the following example, the iteration_limit
and relative_norm
criteria are combined using an or
statement.
Note that the number of criteria is not limited to two.
Moreover, the or
and and
statements can be combined multiple times, if needed.
{
"type": "convergence_criteria.or",
"settings": {
"criteria_list": [
{
"type": "convergence_criteria.iteration_limit",
"settings": {
"maximum": 20
}
},
{
"type": "convergence_criteria.relative_norm",
"settings": {
"order": 2,
"tolerance": 1e-3
}
}
]
}
}
An example of the use of the and
criterion is with use of the solver_coupling_convergence
criterion.
{
"type": "convergence_criteria.and",
"settings": {
"criteria_list": [
{
"type": "convergence_criteria.solver_coupling_convergence",
"settings": {
"solver_index": 0
}
},
{
"type": "convergence_criteria.solver_coupling_convergence",
"settings": {
"solver_index": 1
}
}
]
}
}
Dummy convergence criterion
This dummy convergence criterion can be used in the explicit or one-way coupled solvers, which don't require a convergence criterion.
If the use of a dummy convergence criterion is allowed, the type
(convergence_criteria.dummy_convergence_criterion
) can be written explicitly or omitted. No settings
are required.
Note that the key convergence_criterion
is still required.
References
[1] Spenke T., Delaissé N., Degroote J. and Hosters, N., "On the number of subproblem iterations per coupling step in partitioned fluid-structure interaction simulations", International Journal for Numerical Methods in Engineering, vol. 125, no. 7, e7420, 2024.