Settings

The settings of a FESTIM simulation are defined with a festim.Settings object. This tutorial provides information for defining required and optional settings for users to customize their simulations.

Objectives:

• Defining tolerances and solver settings

• Setting up transient or steady-state simulations

Defining tolerances and solver settings

The required settings for any FESTIM simulation are the absolute and relative tolerances, while users can optionally specify the maximum number of iterations for the solver, degree order for finite element, and whether to use residual or incremental convergence criterion (for Newton solvers).

We can define the tolerances using atol (absolute) and rtol (relative):

import festim as F

settings = F.Settings(
    atol=1e10,
    rtol=1e-10
)

/home/docs/checkouts/readthedocs.org/user_builds/festim-workshop/conda/latest/lib/python3.12/site-packages/festim/coupled_heat_hydrogen_problem.py:1: TqdmExperimentalWarning: Using `tqdm.autonotebook.tqdm` in notebook mode. Use `tqdm.tqdm` instead to force console mode (e.g. in jupyter console)
  import tqdm.autonotebook

To specify the maximum number of iterations (which defaults to 30), we can use max_iterations:

settings = F.Settings(
    atol=1e10,
    rtol=1e-10,
    max_iterations=50
)

To specify the degree order of the finite element (which defaults to 1), we can use element_degree:

settings = F.Settings(
    atol=1e10,
    rtol=1e-10,
    element_degree=2
    )

To specify the convergence criterion, we can use convergence_criterion and strings for residual and incremental. For a residual-based convergence:

settings = F.Settings(
    atol=1e10,
    rtol=1e-10,
    convergence_criterion='residual'
)

Setting up transient or steady-state simulations

For transient simulations, we need to define final_time and stepsize, while for steady-state problems, we simply need to set transient to False.

For example, if we have an absolute and relative tolerance of 1e10 and 1e-10, respectively, we can define the steady-state settings as:

import festim as F

my_settings = F.Settings(
    atol=1e10,
    rtol=1e-10,
    transient=False,
)

For a transient simulation with a run-time of 10 seconds and stepsize of 2 seconds:

my_settings = F.Settings(
    atol=1e10,
    rtol=1e-10,
    final_time=10,
    stepsize=2
)

Note

FESTIM defaults the transient setting to True, while the stepsize and final time defaults to None.

Custom PETSC options

It is possible to parameterise the PETSC Newton solver by providing a dictionary to the petsc_options attribute of the problem class.

For example:

my_model = F.HydrogenTransportProblem()

my_model.petsc_options = { 
    "ksp_type": "preonly",
    "pc_type": "lu",
    "pc_factor_mat_solver_type": "mumps",
}

For available choices, see the PETSc SNES documentation.