API reference

API reference#

class DirichletBCBase(subdomain: SurfaceSubdomain, value: ndarray | Constant | int | float | Callable)[source]#

Bases: object

Dirichlet boundary condition class u = value

Parameters:

subdomain – The surface subdomain where the boundary condition is applied
value – The value of the boundary condition

Variables:

subdomain (festim.subdomain.surface_subdomain.SurfaceSubdomain) – The surface subdomain where the boundary condition is applied
value (numpy.ndarray | dolfinx.fem.function.Constant | int | float | collections.abc.Callable[[numpy.ndarray], numpy.ndarray] | collections.abc.Callable[[numpy.ndarray, float], numpy.ndarray] | collections.abc.Callable[[float], float]) – The value of the boundary condition
value_fenics (None | dolfinx.fem.function.Function | dolfinx.fem.function.Constant | numpy.ndarray | float) – The value of the boundary condition in fenics format
bc_expr (dolfinx.fem.function.Expression) – The expression of the boundary condition that is used to update the value_fenics

define_surface_subdomain_dofs(facet_meshtags: MeshTags, function_space: FunctionSpace | tuple[FunctionSpace, FunctionSpace]) → ndarray[Any, dtype[int32]] | tuple[ndarray[Any, dtype[int32]], ndarray[Any, dtype[int32]]][source]#

Defines the facets and the degrees of freedom of the boundary condition.

Given the input meshtags, find all facets matching the boundary condition subdomain ID, and locate all DOFs associated with the input function space(s).

Note

For sub-spaces, a tuple of sub-spaces are expected as input, and a tuple of arrays associated to each of the function spaces are returned.

Parameters:

facet_meshtags – MeshTags describing some facets in the domain
mesh
function_space – The function space or a tuple of function spaces: (sub, collapsed)

property time_dependent: bool#: Returns true if the value of the boundary condition is time dependent

update(t: float)[source]#

Updates the boundary condition value

Parameters:: t – the time

class FixedConcentrationBC(subdomain: SurfaceSubdomain, value: ndarray | Constant | int | float | Callable, species: Species)[source]#

Bases: DirichletBCBase

Parameters:

subdomain (festim.Subdomain) – the surface subdomain where the boundary condition is applied
value – The value of the boundary condition. It can be a function of space and/or time
species – The name of the species

Variables:

temperature_dependent (bool) – True if the value of the bc is temperature dependent

Examples

FixedConcentrationBC(subdomain=my_subdomain, value=1, species="H")
FixedConcentrationBC(subdomain=my_subdomain,
                     value=lambda x: 1 + x[0], species="H")
FixedConcentrationBC(subdomain=my_subdomain,
                     value=lambda t: 1 + t, species="H")
FixedConcentrationBC(subdomain=my_subdomain,
                     value=lambda T: 1 + T, species="H")
FixedConcentrationBC(subdomain=my_subdomain,
                     value=lambda x, t: 1 + x[0] + t, species="H")

create_value(function_space: FunctionSpace, temperature: float | Constant, t: float | Constant, K_S: Function = None)[source]#

Creates the value of the boundary condition as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a dolfinx.fem.Constant. If the value is a function of t, it is converted to dolfinx.fem.Constant. Otherwise, it is converted to a dolfinx.fem.Function.Function and the expression of the function is stored in bc_expr.

Parameters:

function_space – the function space
temperature – The temperature
t – the time
K_S – The solubility of the species. If provided, the value of the boundary condition is divided by K_S (change of variable method).

class FixedTemperatureBC(subdomain: SurfaceSubdomain, value: ndarray | Constant | int | float | Callable)[source]#

Bases: DirichletBCBase

create_value(function_space: FunctionSpace, t: Constant)[source]#

Creates the value of the boundary condition as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a dolfinx.fem.Constant. If the value is a function of t, it is converted to a dolfinx.fem.Constant. Otherwise, it is converted to a` dolfinx.fem.Function` and the expression of the function is stored in bc_expr.

Parameters:

function_space – the function space
t – the time

class FluxBCBase(subdomain: SurfaceSubdomain, value)[source]#

Bases: object

Flux boundary condition class

Ensuring the gradient of the solution u at a boundary:

\[-A \nabla u \cdot \mathbf{n} = f\]

where \(A\) is some material property (diffusivity for particle flux and thermal conductivity for heat flux), \(\mathbf{n}\) is the outwards normal vector of the boundary, \(f\) is a function of space and time.

Parameters:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the boundary condition is applied
value (float, fem.Constant, callable) – the value of the boundary condition

Variables:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the boundary condition is applied
value (float, fem.Constant, callable) – the value of the boundary condition
value_fenics (fem.Function or fem.Constant) – the value of the boundary condition in fenics format
bc_expr (fem.Expression) – the expression of the boundary condition that is used to update the value_fenics

create_value_fenics(mesh, temperature, t: Constant)[source]#

Creates the value of the boundary condition as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a fenics.Constant. If the value is a function of t, it is converted to a fenics.Constant. Otherwise, it is converted to a ufl Expression

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh
temperature (float) – the temperature
t (dolfinx.fem.Constant) – the time

update(t)[source]#

Updates the flux bc value

Parameters:: t (float) – the time

class HeatFluxBC(subdomain, value)[source]#

Bases: FluxBCBase

Heat flux boundary condition class Ensuring the gradient of the solution T at a boundary: -lambda * grad(T) * n = f where lambda is the thermal conductivity , n is the outwards normal vector of the boundary, f is a function of space and time.

Parameters:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the heat flux is applied
value (float, callable, fem.Constant) – the value of the heat flux

Variables:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the heat flux is applied
value (float, callable, fem.Constant) – the value of the heat flux
value_fenics (fem.Function or fem.Constant) – the value of the heat flux in fenics format
bc_expr (fem.Expression) – the expression of the heat flux that is used to update the value_fenics

Examples

HeatFluxBC(subdomain=my_subdomain, value=1)
HeatFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0])
HeatFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t)
HeatFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t)

class HenrysBC(subdomain, H_0, E_H, pressure, species)[source]#

Bases: FixedConcentrationBC

Henrys boundary condition class

c = H * pressure H = H_0 * exp(-E_H / k_B / T)

Parameters:

subdomain (festim.Subdomain) – the subdomain where the boundary condition is applied
species (str) – the name of the species
H_0 (float or fem.Constant) – the Henrys constant pre-exponential factor (H/m3/Pa)
E_H (float or fem.Constant) – the Henrys constant activation energy (eV)
pressure (float or callable) – the pressure at the boundary (Pa)

Variables:

subdomain (festim.Subdomain) – the subdomain where the boundary condition is applied
value (float or fem.Constant) – the value of the boundary condition
species (festim.Species or str) – the name of the species
H_0 (float or fem.Constant) – the Henrys constant pre-exponential factor (H/m3/Pa)
E_H (float or fem.Constant) – the Henrys constant activation energy (eV)
pressure (float or callable) – the pressure at the boundary (Pa)

Examples

HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=1e5, species="H")
HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x: 1e5 + x[0], species="H")
HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda t: 1e5 + t, species="H")
HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda T: 1e5 + T, species="H")
HenrysBC(subdomain=my_subdomain, H_0=1e-6, E_H=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")

create_new_value_function()[source]#

Creates a new value function based on the pressure attribute

Raises:: ValueError – if the pressure function is not supported
Returns:: the value function
Return type:: callable

class ParticleFluxBC(subdomain, value, species, species_dependent_value={})[source]#

Bases: FluxBCBase

Particle flux boundary condition class Ensuring the gradient of the solution c at a boundary: -D * grad(c) * n = f where D is the material diffusivity, n is the outwards normal vector of the boundary, f is a function of space and time.

Parameters:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the particle flux is applied
value (float, fem.Constant, callable) – the value of the particle flux
species (festim.Species) – the species to which the flux is applied
species_dependent_value (dict) – a dictionary containing the species that the value. Example: {“name”: species} where “name” is the variable name in the callable value and species is a festim.Species object.

Variables:

subdomain (festim.SurfaceSubdomain) – the surface subdomain where the particle flux is applied
value (float or fem.Constant) – the value of the particle flux
species (festim.Species) – the species to which the flux is applied
value_fenics (fem.Function or fem.Constant) – the value of the particle flux in fenics format
bc_expr (fem.Expression) – the expression of the particle flux that is used to update the value_fenics
species_dependent_value (dict) – a dictionary containing the species that the value. Example: {“name”: species} where “name” is the variable name in the callable value and species is a festim.Species object.

Examples

ParticleFluxBC(subdomain=my_subdomain, value=1, species="H")
ParticleFluxBC(subdomain=my_subdomain, value=lambda x: 1 + x[0], species="H")
ParticleFluxBC(subdomain=my_subdomain, value=lambda t: 1 + t, species="H")
ParticleFluxBC(subdomain=my_subdomain, value=lambda T: 1 + T, species="H")
ParticleFluxBC(subdomain=my_subdomain, value=lambda x, t: 1 + x[0] + t, species="H")
ParticleFluxBC(subdomain=my_subdomain, value=lambda c1: 2 * c1**2, species="H", species_dependent_value={"c1": species1})

create_value_fenics(mesh, temperature, t: Constant)[source]#

Creates the value of the boundary condition as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a fenics.Constant. If the value is a function of t, it is converted to a fenics.Constant. Otherwise, it is converted to a ufl Expression

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh
temperature (float) – the temperature
t (dolfinx.fem.Constant) – the time

class SievertsBC(subdomain, S_0, E_S, pressure, species)[source]#

Bases: FixedConcentrationBC

Sieverts boundary condition class

c = S * sqrt(pressure) S = S_0 * exp(-E_S / k_B / T)

Parameters:

subdomain (festim.Subdomain) – the subdomain where the boundary condition is applied
species (str) – the name of the species
S_0 (float or fem.Constant) – the Sieverts constant pre-exponential factor (H/m3/Pa0.5)
E_S (float or fem.Constant) – the Sieverts constant activation energy (eV)
pressure (float or callable) – the pressure at the boundary (Pa)

Variables:

subdomain (festim.Subdomain) – the subdomain where the boundary condition is applied
value (float or fem.Constant) – the value of the boundary condition
species (festim.Species or str) – the name of the species
S_0 (float or fem.Constant) – the Sieverts constant pre-exponential factor (H/m3/Pa0.5)
E_S (float or fem.Constant) – the Sieverts constant activation energy (eV)
pressure (float or callable) – the pressure at the boundary (Pa)

Examples

SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=1e5, species="H")
SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x: 1e5 + x[0], species="H")
SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda t: 1e5 + t, species="H")
SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda T: 1e5 + T, species="H")
SievertsBC(subdomain=my_subdomain, S_0=1e-6, E_S=0.2, pressure=lambda x, t: 1e5 + x[0] + t, species="H")

create_new_value_function()[source]#

Creates a new value function based on the pressure attribute

Raises:: ValueError – if the pressure function is not supported
Returns:: the value function
Return type:: callable

class SurfaceReactionBC(reactant, gas_pressure, k_r0, E_kr, k_d0, E_kd, subdomain)[source]#

Bases: object

Boundary condition representing a surface reaction A + B <-> C where A, B are the reactants and C is the product the forward reaction rate is K_r = k_r0 * exp(-E_kr / (k_B * T)) and the backward reaction rate is K_d = k_d0 * exp(-E_kd / (k_B * T)) The reaction rate is: K = K_r * C_A * C_B - K_d * P_C with C_A, C_B the concentration of species A and B, P_C the partial pressure of species C at the surface.

The flux of species A entering the surface is K. In the special case where A=B, then the flux of particle entering the surface is 2*K

Parameters:

reactant (list) – list of F.Species objects representing the reactants
gas_pressure (float, callable) – the partial pressure of the product species
k_r0 (float) – the pre-exponential factor of the forward reaction rate
E_kr (float) – the activation energy of the forward reaction rate (eV)
k_d0 (float) – the pre-exponential factor of the backward reaction rate
E_kd (float) – the activation energy of the backward reaction rate (eV)
subdomain (F.SurfaceSubdomain) – the surface subdomain where the reaction occurs

class SurfaceReactionBCpartial(reactant, gas_pressure, k_r0, E_kr, k_d0, E_kd, subdomain, species)[source]#

Bases: ParticleFluxBC

Boundary condition representing a surface reaction A + B <-> C where A, B are the reactants and C is the product the forward reaction rate is K_r = k_r0 * exp(-E_kr / (k_B * T)) and the backward reaction rate is K_d = k_d0 * exp(-E_kd / (k_B * T)) The reaction rate is: K = K_r * C_A * C_B - K_d * P_C with C_A, C_B the concentration of species A and B, P_C the partial pressure of species C at the surface.

This class is used to create the flux of a single species entering the surface Example: The flux of species A entering the surface is K.

Parameters:

reactant (list) – list of F.Species objects representing the reactants
gas_pressure (float, callable) – the partial pressure of the product species
k_r0 (float) – the pre-exponential factor of the forward reaction rate
E_kr (float) – the activation energy of the forward reaction rate (eV)
k_d0 (float) – the pre-exponential factor of the backward reaction rate
E_kd (float) – the activation energy of the backward reaction rate (eV)
subdomain (F.SurfaceSubdomain) – the surface subdomain where the reaction occurs
species (F.Species) – the species to which the flux is applied

create_value_fenics(mesh, temperature, t: Constant)[source]#

Creates the value of the boundary condition as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a fenics.Constant. If the value is a function of t, it is converted to a fenics.Constant. Otherwise, it is converted to a ufl Expression

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh
temperature (float) – the temperature
t (dolfinx.fem.Constant) – the time

class AverageSurface(field, surface, filename: str | None = None)[source]#

Bases: SurfaceQuantity

Computes the average value of a field on a given surface

Parameters:

field (festim.Species) – species for which the average surface is computed
surface (festim.SurfaceSubdomain) – surface subdomain
filename (str, optional) – name of the file to which the average surface is exported

Variables:

festim.SurfaceQuantity (see)

compute(ds)[source]#: Computes the average value of the field on the defined surface subdomain, and appends it to the data list

class AverageVolume(field, volume, filename: str = None)[source]#

Bases: VolumeQuantity

Computes the average value of a field in a given volume

Parameters:

field (festim.Species) – species for which the average volume is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str, optional) – name of the file to which the average volume is exported

Variables:

festim.VolumeQuantity (see)

compute(dx)[source]#: Computes the average value of solution function within the defined volume subdomain, and appends it to the data list

class MaximumSurface(field, surface, filename: str | None = None)[source]#

Bases: SurfaceQuantity

Computes the maximum value of a field on a given surface

Parameters:

field (festim.Species) – species for which the maximum surface is computed
surface (festim.SurfaceSubdomain) – surface subdomain
filename (str, optional) – name of the file to which the maximum surface is exported

Variables:

festim.SurfaceQuantity (see)

compute()[source]#: Computes the maximum value of the field on the defined surface subdomain, and appends it to the data list

class MaximumVolume(field, volume, filename: str = None)[source]#

Bases: VolumeQuantity

Computes the maximum value of a field in a given volume

Parameters:

field (festim.Species) – species for which the maximum volume is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str, optional) – name of the file to which the maximum volume is exported

Variables:

festim.VolumeQuantity (see)

compute()[source]#: Computes the maximum value of solution function within the defined volume subdomain, and appends it to the data list

class MinimumSurface(field, surface, filename: str | None = None)[source]#

Bases: SurfaceQuantity

Computes the minimum value of a field on a given surface

Parameters:

field (festim.Species) – species for which the minimum surface is computed
surface (festim.SurfaceSubdomain) – surface subdomain
filename (str, optional) – name of the file to which the minimum surface is exported

Variables:

festim.SurfaceQuantity (see)

compute()[source]#: Computes the minimum value of the field on the defined surface subdomain, and appends it to the data list

class MinimumVolume(field, volume, filename: str = None)[source]#

Bases: VolumeQuantity

Computes the minimum value of a field in a given volume

Parameters:

field (festim.Species) – species for which the minimum volume is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str, optional) – name of the file to which the minimum volume is exported

Variables:

festim.VolumeQuantity (see)

compute()[source]#: Computes the minimum value of solution function within the defined volume subdomain, and appends it to the data list

class SurfaceFlux(field, surface, filename: str | None = None)[source]#

Bases: SurfaceQuantity

Computes the flux of a field on a given surface

Parameters:

field (festim.Species) – species for which the surface flux is computed
surface (festim.SurfaceSubdomain1D) – surface subdomain
filename (str, optional) – name of the file to which the surface flux is exported

Variables:

festim.SurfaceQuantity (see)

compute(ds)[source]#

Computes the value of the flux at the surface

Parameters:: ds (ufl.Measure) – surface measure of the model

class SurfaceQuantity(field, surface, filename: str | None = None)[source]#

Bases: object

Export SurfaceQuantity

Parameters:

field (festim.Species) – species for which the surface flux is computed
surface (festim.SurfaceSubdomain1D) – surface subdomain
filename (str, optional) – name of the file to which the surface flux is exported

Variables:

field (festim.Species) – species for which the surface flux is computed
surface (festim.SurfaceSubdomain) – surface subdomain
filename (str) – name of the file to which the surface flux is exported
t (list) – list of time values
data (list) – list of values of the surface quantity

write(t)[source]#: If the filename doesnt exist yet, create it and write the header, then append the time and value to the file

class TotalSurface(field, surface, filename: str | None = None)[source]#

Bases: SurfaceQuantity

Computes the total value of a field on a given surface

Parameters:

field (festim.Species) – species for which the total volume is computed
surface (festim.SurfaceSubdomain) – surface subdomain
filename (str, optional) – name of the file to which the total volume is exported

Variables:

festim.SurfaceQuantity (see)

compute(ds: Measure)[source]#

Computes the total value of the field on the defined surface subdomain, and appends it to the data list

Parameters:: ds (ufl.Measure) – surface measure of the model

class TotalVolume(field, volume, filename: str = None)[source]#

Bases: VolumeQuantity

Computes the total value of a field in a given volume

Parameters:

field (festim.Species) – species for which the total volume is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str, optional) – name of the file to which the total volume is exported

Variables:

festim.VolumeQuantity (see)

compute(dx: Measure)[source]#

Computes the value of the total volume of the field in the volume subdomain and appends it to the data list

Parameters:: dx (ufl.Measure) – volume measure of the model

class VTXSpeciesExport(filename: str | Path, field: Species | list[Species], subdomain: VolumeSubdomain = None, checkpoint: bool = False)[source]#

Bases: ExportBaseClass

Export functions to VTX file

Parameters:

filename – The name of the output file
field – Set of species to export
subdomain – A field can be defined on multiple domains. This arguments specifies what subdomains we export on. If None we export on all domains.
checkpoint – If True, the export will be a checkpoint file using adios4dolfinx and won’t be readable by ParaView. Default is False.

get_functions() → list[Function][source]#: Returns list of species for a given subdomain. If using legacy mode, return the whole species.

class VolumeQuantity(field, volume, filename: str = None)[source]#

Bases: object

Export VolumeQuantity

Parameters:

field (festim.Species) – species for which the volume quantity is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str, optional) – name of the file to which the volume quantity is exported

Variables:

field (festim.Species) – species for which the volume quantity is computed
volume (festim.VolumeSubdomain) – volume subdomain
filename (str) – name of the file to which the volume quantity is exported
t (list) – list of time values
data (list) – list of values of the volume quantity

write(t)[source]#: If the filename doesnt exist yet, create it and write the header, then append the time and value to the file

class XDMFExport(filename: str | Path, field: list[Species] | Species)[source]#

Bases: ExportBaseClass

Export functions to XDMFfile

Parameters:

filename – The name of the output file
field – The field(s) to export

Variables:

_writer (dolfinx.io.XDMFFile) – the XDMF writer
_field (festim.Species, list of festim.Species) – the field index to export

define_writer(comm: Intracomm) → None[source]#

Define the writer

Parameters:: comm (mpi4py.MPI.Intracomm) – the MPI communicator

write(t: float)[source]#

Write functions to VTX file

Parameters:: t (float) – the time of export

class Mesh(mesh: Mesh | None = None)[source]#

Bases: object

Mesh class

Parameters:

None. (mesh The mesh. Defaults to)

Variables:

mesh (mesh The)
vdim – the dimension of the mesh cells
fdim – the dimension of the mesh facets
n – Symbolic representation of the vector normal to the facets of the mesh.

define_meshtags(surface_subdomains, volume_subdomains, interfaces=None)[source]#

Defines the facet and volume meshtags of the mesh

Parameters:

surface_subdomains (list of festim.SufaceSubdomains) – the surface subdomains of the model
volume_subdomains (list of festim.VolumeSubdomains) – the volume subdomains of the model
interfaces (dict, optional) – the interfaces between volume subdomains {int: [VolumeSubdomain, VolumeSubdomain]}. Defaults to None.

Returns:

the facet meshtags dolfinx.mesh.MeshTags: the volume meshtags

Return type:

dolfinx.mesh.MeshTags

class Mesh1D(vertices, **kwargs)[source]#

Bases: Mesh

1D Mesh

Parameters:: vertices (list or np.ndarray) – the mesh x-coordinates (m)
Variables:: vertices (np.ndarray) – the mesh x-coordinates (m)

check_borders(volume_subdomains)[source]#

Checks that the borders of the subdomain are within the domain

Parameters:: volume_subdomains (list of festim.VolumeSubdomain1D) – the volume subdomains
Raises:: Value error – if borders outside the domain

define_meshtags(surface_subdomains, volume_subdomains, interfaces=None)[source]#

Defines the facet and volume meshtags of the mesh

Parameters:

surface_subdomains (list of festim.SufaceSubdomains) – the surface subdomains of the model
volume_subdomains (list of festim.VolumeSubdomains) – the volume subdomains of the model
interfaces (dict, optional) – the interfaces between volume subdomains {int: [VolumeSubdomain, VolumeSubdomain]}. Defaults to None.

Returns:

the facet meshtags dolfinx.mesh.MeshTags: the volume meshtags

Return type:

dolfinx.mesh.MeshTags

generate_mesh()[source]#: Generates a 1D mesh

class MeshFromXDMF(volume_file, facet_file, mesh_name='Grid', surface_meshtags_name='Grid', volume_meshtags_name='Grid')[source]#

Bases: Mesh

Mesh read from the XDMF files

Parameters:

volume_file (str) – path to the volume file
facet_file (str) – path to the facet file
mesh_name (str, optional) – name of the mesh in the volume XDMF file. Defaults to “Grid”.
surface_meshtags_name (str, optional) – name of the surface meshtags in the facet XDMF file. Defaults to “Grid”.
volume_meshtags_name (str, optional) – name of the volume meshtags in the volume XDMF file. Defaults to “Grid”.

Variables:

volume_file (str) – path to the volume file
facet_file (str) – path to the facet file
mesh_name (str) – name of the mesh in the volume XDMF file.
surface_meshtags_name (str) – name of the surface meshtags in the facet XDMF file.
volume_meshtags_name (str) – name of the volume meshtags in the volume XDMF file
mesh (fenics.mesh.Mesh) – the fenics mesh

define_surface_meshtags()[source]#

Creates the facet meshtags

Returns:: the facet meshtags
Return type:: dolfinx.MeshTags

define_volume_meshtags()[source]#

Creates the volume meshtags

Returns:: the volume meshtags
Return type:: dolfinx.MeshTags

class SurfaceSubdomain(id)[source]#

Bases: object

Surface subdomain class

Parameters:: id (int) – the id of the surface subdomain

locate_boundary_facet_indices(mesh: Mesh) → ndarray[Any, dtype[int32]][source]#

Locates the dof of the surface subdomain within the function space and return the index of the dof

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh of the simulation

Returns:

the first value in the list of surface facet: indices of the subdomain

Return type:

index (np.array)

class SurfaceSubdomain1D(id: int, x: float)[source]#

Bases: SurfaceSubdomain

Surface subdomain class for 1D cases

Parameters:

id (int) – the id of the surface subdomain
x (float) – the x coordinate of the surface subdomain

Variables:

id (int) – the id of the surface subdomain
x (float) – the x coordinate of the surface subdomain

Examples

SurfaceSubdomain1D(id=1, x=1)

locate_boundary_facet_indices(mesh: Mesh)[source]#

Locates the dof of the surface subdomain within the function space and return the index of the dof

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh of the simulation

Returns:

the first value in the list of surface facet: indices of the subdomain

Return type:

index (np.array)

class VolumeSubdomain(id, material)[source]#

Bases: object

Volume subdomain class

Parameters:

id (int) – the id of the volume subdomain
material (festim.Material) – the material assigned to the subdomain

create_subdomain(mesh: Mesh, marker: MeshTags)[source]#

Creates the following attributes: .parent_mesh, .submesh, .submesh_to_mesh, .v_map, padded, and the entity map parent_to_submesh.

Only used in festim.HydrogenTransportProblemDiscontinuous

Parameters:

mesh (dolfinx.mesh.Mesh) – the parent mesh
marker (dolfinx.mesh.MeshTags) – the parent volume markers

locate_subdomain_entities(mesh: Mesh)[source]#

Locates all cells in subdomain borders within domain

Parameters:: mesh (dolfinx.mesh.Mesh) – the mesh of the model
Returns:: the entities of the subdomain
Return type:: entities (np.array)

locate_subdomain_entities_correct(cell_tags: MeshTags)[source]#

Locates all cells in subdomain borders within domain

Parameters:: cell_tags (dolfinx.mesh.MeshTags) – the mesh tags of the model
Returns:: the entities of the subdomain
Return type:: entities (np.array)

class VolumeSubdomain1D(id, borders, material)[source]#

Bases: VolumeSubdomain

Volume subdomain class for 1D cases

Parameters:

id (int) – the id of the volume subdomain
borders (list of float) – the borders of the volume subdomain
material (festim.Material) – the material of the volume subdomain

Variables:

id (int) – the id of the volume subdomain
borders (list of float) – the borders of the volume subdomain
material (festim.Material) – the material of the volume subdomain

Examples

VolumeSubdomain1D(id=1, borders=[0, 1], material=my_mat)

locate_subdomain_entities(mesh: Mesh) → ndarray[Any, dtype[int32]][source]#

Locates all cells in subdomain borders within domain

Parameters:: mesh (dolfinx.mesh.Mesh) – the mesh of the model
Returns:: the entities of the subdomain
Return type:: entities (np.array)

class AdvectionTerm(velocity: Function, subdomain: VolumeSubdomain, species: Species)[source]#

Bases: object

Advection term class

Parameters:

velocity – the velocity field or function
subdomain – the volume subdomain where the velocity is to be applied
species – the species to which the velocity field is acting on

Variables:

velocity (dolfinx.fem.function.Function) – the velocity field or function
subdomain (festim.subdomain.volume_subdomain.VolumeSubdomain) – the volume subdomain where the velocity is to be applied
species (festim.species.Species) – the species to which the velocity field is acting on

class VelocityField(input_value)[source]#

Bases: Value

A class to handle input values of velocity fields from users and convert them to a relevent fenics object

Parameters:

input_value – The value of the user input

Variables:

input_value (dolfinx.fem.function.Function | collections.abc.Callable) – The value of the user input
fenics_interpolation_expression (dolfinx.fem.function.Expression) – The expression of the user input that is used to update the fenics_object
fenics_object (dolfinx.fem.function.Function) – The value of the user input in fenics format
explicit_time_dependent (bool) – True if the user input value is explicitly time dependent
temperature_dependent (bool) – True if the user input value is temperature dependent
vector_function_space (dolfinx.fem.function.FunctionSpace) – the vector function space of the fenics object

convert_input_value(function_space: FunctionSpace, t: Constant | None = None)[source]#

Converts a user given value to a relevent fenics object

Parameters:

function_space – the function space of the fenics object
t – the time, optional

update(t: Constant)[source]#

Updates the velocity field

Parameters:: t – the time

class CoupledTransientHeatTransferHydrogenTransport(heat_problem: HeatTransferProblem, hydrogen_problem: HydrogenTransportProblem)[source]#

Bases: object

Coupled heat transfer and hydrogen transport transient problem

Parameters:

heat_problem – the heat transfer problem
hydrogen_problem – the hydrogen transport problem

Variables:

heat_problem (festim.heat_transfer_problem.HeatTransferProblem) – the heat transfer problem
hydrogen_problem (festim.hydrogen_transport_problem.HydrogenTransportProblem) – the hydrogen transport problem
non_matching_meshes (bool) – True if the meshes in the heat_problem and hydrogen_problem are not matching

Examples

import festim as F

my_heat_transfer_model = F.HeatTransferProblem(...)

my_h_transport_model = F.HydrogenTransportProblem(...)

coupled_problem = F.CoupledTransientHeatTransferHydrogenTransport(
    heat_problem=my_heat_transfer_model,
    hydrogen_problem=my_h_transport_model,
)

class HeatTransferProblem(mesh=None, subdomains=None, initial_condition=None, boundary_conditions=None, sources=None, exports=None, settings=None)[source]#

Bases: ProblemBase

create_dirichletbc_form(bc)[source]#

Creates a dirichlet boundary condition form

Parameters:

bc (festim.FixedTemperatureBC) – the boundary condition

Returns:

A representation of: the boundary condition for modifying linear systems.

Return type:

dolfinx.fem.bcs.DirichletBC

create_flux_values_fenics()[source]#: For each heat flux create the value_fenics

create_formulation()[source]#: Creates the formulation of the model

create_initial_conditions()[source]#: For each initial condition, create the value_fenics and assign it to the previous solution of the condition’s species

create_source_values_fenics()[source]#: For each source create the value_fenics

define_function_space()[source]#: Creates the function space of the model, creates a mixed element if model is multispecies. Creates the main solution and previous solution function u and u_n. Create global DG function spaces of degree 0 and 1 for the global diffusion coefficient

initialise_exports()[source]#: Defines the export writers of the model, if field is given as a string, find species object in self.species

post_processing()[source]#: Post processes the model

transfer_meshtags_to_submesh(mesh, entity_tag, submesh, sub_vertex_to_parent, sub_cell_to_parent)[source]#: Transfer a meshtag from a parent mesh to a sub-mesh.

class Value(input_value)[source]#

Bases: object

A class to handle input values from users and convert them to a relevent fenics object

Parameters:

input_value – The value of the user input

Variables:

input_value (float | int | dolfinx.fem.function.Constant | numpy.ndarray | dolfinx.fem.function.Expression | ufl.core.expr.Expr | dolfinx.fem.function.Function) – The value of the user input
fenics_interpolation_expression (dolfinx.fem.function.Expression) – The expression of the user input that is used to update the fenics_object
fenics_object (dolfinx.fem.function.Function | dolfinx.fem.function.Constant | ufl.core.expr.Expr) – The value of the user input in fenics format
explicit_time_dependent (bool) – True if the user input value is explicitly time dependent
temperature_dependent (bool) – True if the user input value is temperature dependent

Converts a user given value to a relevent fenics object depending on the type of the value provided

Parameters:

function_space – the function space of the fenics object, optional
t – the time, optional
temperature – the temperature, optional
up_to_ufl_expr – if True, the value is only mapped to a function if the input is callable, not interpolated or converted to a function, optional

property explicit_time_dependent: bool#: Returns true if the value given is time dependent

property temperature_dependent: bool#: Returns true if the value given is temperature dependent

update(t: float)[source]#

Updates the value

Parameters:: t – the time

as_fenics_constant(value: float | int | Constant, mesh: Mesh) → Constant[source]#

Converts a value to a dolfinx.Constant

Parameters:

value – the value to convert
mesh – the mesh of the domiain

Returns:

The converted value

Raises:

TypeError – if the value is not a float, an int or a dolfinx.Constant

as_fenics_interp_expr_and_function(value: Callable, function_space: FunctionSpace, t: Constant | None = None, temperature: Function | Constant | Expr | None = None) → tuple[Expression, Function][source]#

Takes a user given callable function, maps the function to the mesh, time or temperature within festim as needed. Then creates the fenics interpolation expression and function objects

Parameters:

value – the callable to convert
function_space – The function space to interpolate function over
t – the time, optional
temperature – the temperature, optional

Returns:

fenics interpolation expression, fenics function

Maps a user given callable function to the mesh, time or temperature within festim as needed

Parameters:

value – the callable to convert
function_space – the function space of the domain, optional
t – the time, optional
temperature – the temperature, optional

Returns:

The mapped function

nmm_interpolate(f_out: Function, f_in: Function)[source]#

Non Matching Mesh Interpolate: interpolate one function (f_in) from one mesh into another function (f_out) with a mismatching mesh

Parameters:

f_out – function to interpolate into
f_in – function to interpolate from

notes: https://fenicsproject.discourse.group/t/gjk-error-in-interpolation-between-non-matching-second-ordered-3d-meshes/16086/6

class HydrogenTransportProblem(mesh: Mesh | None = None, subdomains: list[VolumeSubdomain | SurfaceSubdomain] | None = None, species: list[Species] | None = None, reactions: list[Reaction] | None = None, temperature: float | int | Constant | Function | Callable[[ndarray[Any, dtype[float64]]], ndarray[Any, dtype[float64]]] | Callable[[ndarray[Any, dtype[float64]], Constant], ndarray[Any, dtype[float64]]] | None = None, sources=None, initial_conditions=None, boundary_conditions=None, settings=None, exports=None, traps=None, advection_terms=None, petsc_options=None)[source]#

Bases: ProblemBase

Hydrogen Transport Problem.

Parameters:

mesh – The mesh
subdomains – List containing the subdomains
species – List containing the species
reactions – List containing the reactions
temperature – The temperature or a function describing the temperature as a model of either space or space and time. Unit (K)
sources – The hydrogen sources
initial_conditions – The initial conditions
boundary_conditions – The boundary conditions
exports (list of festim.Export) – the exports of the model
traps (list of F.Trap) – the traps of the model
advection_terms – the advection terms of the model

Variables:

mesh (festim.mesh.mesh.Mesh) – The mesh
subdomains (list[festim.subdomain.volume_subdomain.VolumeSubdomain]) – The subdomains
species – The species
reactions – the reaction
temperature – The temperature in unit K
sources (list[festim.source.SourceBase]) – The hydrogen sources
initial_conditions – The initial conditions
boundary_conditions – List of Dirichlet boundary conditions
exports (list of festim.Export) – the export
traps (list of F.Trap) – the traps of the model
advection_terms – the advection terms of the model
dx (dolfinx.fem.dx) – the volume measure of the model
ds (dolfinx.fem.ds) – the surface measure of the model
function_space (dolfinx.fem.FunctionSpaceBase) – the function space of the model
facet_meshtags (dolfinx.mesh.MeshTags) – the facet meshtags of the model
volume_meshtags (dolfinx.mesh.MeshTags) – the volume meshtags of the model
formulation (ufl.form.Form) – the formulation of the model
solver (dolfinx.nls.newton.NewtonSolver) – the solver of the model
multispecies (bool) – True if the model has more than one species.
temperature_fenics (fem.Constant or fem.Function) – the temperature of the model as a fenics object (fem.Constant or fem.Function).
temperature_expr (fem.Expression) – the expression of the temperature that is used to update the temperature_fenics
temperature_time_dependent (bool) – True if the temperature is time dependent
V_DG_0 (dolfinx.fem.FunctionSpaceBase) – A DG function space of degree 0 over domain
V_DG_1 (dolfinx.fem.FunctionSpaceBase) – A DG function space of degree 1 over domain
volume_subdomains (list of festim.VolumeSubdomain) – the volume subdomains of the model
surface_subdomains (list of festim.SurfaceSubdomain) – the surface subdomains of the model

Examples

Can be used as either

import festim as F
my_model = F.HydrogenTransportProblem()
my_model.mesh = F.Mesh(...)
my_model.subdomains = [F.Subdomain(...)]
my_model.species = [F.Species(name="H"), F.Species(name="Trap")]
my_model.temperature = 500
my_model.sources = [F.ParticleSource(...)]
my_model.boundary_conditions = [F.BoundaryCondition(...)]
my_model.initialise()

or

my_model = F.HydrogenTransportProblem(
    mesh=F.Mesh(...),
    subdomains=[F.Subdomain(...)],
    species=[F.Species(name="H"), F.Species(name="Trap")],
)
my_model.initialise()

assign_functions_to_species()[source]#: Creates the solution, prev solution, test function and post-processing solution for each species, if model is multispecies, created a collapsed function space for each species

convert_advection_term_to_fenics_objects()[source]#: For each advection term convert the input value

convert_source_input_values_to_fenics_objects()[source]#: For each source create the value_fenics

create_dirichletbc_form(bc)[source]#

Creates a dirichlet boundary condition form

Parameters:

bc (festim.DirichletBC) – the boundary condition

Returns:

A representation of: the boundary condition for modifying linear systems.

Return type:

dolfinx.fem.bcs.DirichletBC

create_flux_values_fenics()[source]#: For each particle flux create the value_fenics

create_formulation()[source]#: Creates the formulation of the model

create_implicit_species_value_fenics()[source]#: For each implicit species, create the value_fenics

create_initial_conditions()[source]#: For each initial condition, create the value_fenics and assign it to the previous solution of the condition’s species

create_species_from_traps()[source]#: Generate a species and reaction per trap defined in self.traps

define_D_global(species)[source]#

Defines the global diffusion coefficient for a given species

Parameters:

species (F.Species) – the species

Returns:

the global diffusion: coefficient and the expression of the global diffusion coefficient for a given species

Return type:

dolfinx.fem.Function, dolfinx.fem.Expression

define_boundary_conditions()[source]#: Defines the dirichlet boundary conditions of the model

define_function_spaces()[source]#: Creates the function space of the model, creates a mixed element if model is multispecies. Creates the main solution and previous solution function u and u_n. Create global DG function spaces of degree 0 and 1 for the global diffusion coefficient

define_temperature()[source]#: Sets the value of temperature_fenics_value. The type depends on self.temperature. If self.temperature is a function on t only, create a fem.Constant. Else, create an dolfinx.fem.Expression (stored in self.temperature_expr) to be updated, a dolfinx.fem.Function object is created from the Expression (stored in self.temperature_fenics_value). Raise a ValueError if temperature is None.

initialise_exports()[source]#: Defines the export writers of the model, if field is given as a string, find species object in self.species

post_processing()[source]#: Post processes the model

class HydrogenTransportProblemDiscontinuous(mesh=None, subdomains=None, species=None, reactions=None, temperature=None, sources=None, initial_conditions=None, boundary_conditions=None, settings=None, exports=None, traps=None, interfaces: list[Interface] | None = None, surface_to_volume: dict | None = None, petsc_options: dict | None = None)[source]#

Bases: HydrogenTransportProblem

convert_advection_term_to_fenics_objects()[source]#: For each advection term convert the input value

convert_source_input_values_to_fenics_objects()[source]#: For each source create the value_fenics

create_dirichletbc_form(bc: FixedConcentrationBC)[source]#

Creates the value_fenics attribute for a given festim.FixedConcentrationBC and returns the appropriate dolfinx.fem.DirichletBC object.

Parameters:

bc (festim.FixedConcentrationBC) – the dirichlet BC

Returns:

the appropriate dolfinx representation: generated from dolfinx.fem.dirichletbc()

Return type:

dolfinx.fem.DirichletBC

create_flux_values_fenics()[source]#: For each particle flux create the value_fenics attribute

create_formulation()[source]#

Takes all the formulations for each subdomain and adds the interface conditions.

Finally compute the jacobian matrix and store it in the J attribute, adds the entity_maps to the forms and store them in the forms attribute

create_initial_conditions()[source]#: For each initial condition, create the value_fenics and assign it to the previous solution of the condition’s species

create_solver()[source]#: Creates the solver of the model

create_subdomain_formulation(subdomain: VolumeSubdomain)[source]#

Creates the variational formulation for each subdomain and stores it in subdomain.F

Parameters:: subdomain (F.VolumeSubdomain) – a subdomain of the geometry

define_function_spaces(subdomain: VolumeSubdomain)[source]#

Creates appropriate function space and functions for a given subdomain (submesh) based on the number of species existing in this subdomain. Then stores the functionspace, the current solution (u) and the previous solution (u_n) functions. It also populates the correspondance dicts attributes of the species (eg. species.subdomain_to_solution, species.subdomain_to_test_function, etc) for easy access to the right subfunctions, sub-testfunctions etc.

Parameters:: subdomain (F.VolumeSubdomain) – a subdomain of the geometry

initialise_exports()[source]#: Defines the export writers of the model, if field is given as a string, find species object in self.species

iterate()[source]#: Iterates the model for a given time step

post_processing()[source]#: Post processes the model

run()[source]#: Runs the model

class InitialCondition(value, species)[source]#

Bases: object

Initial condition class

Parameters:

value (float, int, fem.Constant, fem.Function, or callable) – the value of the initial condition. If a fem.Function is passed, the mesh of the function needs to match the mesh of the problem.
species (festim.Species) – the species to which the condition is applied

Variables:

value (float, int, fem.Constant, fem.Function, or callable) – the value of the initial condition
species (festim.Species) – the species to which the source is applied
expr_fenics (Callable | dolfinx.fem.function.Expression) – the value of the initial condition in fenics format

Examples

InitialCondition(value=1, species=my_species)
InitialCondition(value=lambda x: 1 + x[0], species=my_species)
InitialCondition(value=lambda T: 1 + T, species=my_species)
InitialCondition(value=lambda x, T: 1 + x[0] + T, species=my_species)

create_expr_fenics(mesh, temperature, function_space)[source]#

Creates the expr_fenics of the initial condition. If the value is a float or int, a function is created with an array with the shape of the mesh and all set to the value. Otherwise, it is converted to a fem.Expression.

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh
temperature (float) – the temperature
function_space (dolfinx.fem.FunctionSpaceBase) – the function space of the species

read_function_from_file(filename: str, name: str, timestamp: int | float, family='P', order: int = 1) → Function[source]#

Read a function from a file

note::: The function is read from a file using adios4dolfinx. For more information see the [adios4dolfinx documentation](https://jsdokken.com/adios4dolfinx/README.html).

Parameters:

filename – the filename
name – the name of the function
timestamp – the timestamp of the function
family – the family of the function space
order – the order of the function space

Returns:

the function

class Material(D_0, E_D, K_S_0=None, E_K_S=None, thermal_conductivity=None, density=None, heat_capacity=None, name=None, solubility_law=None)[source]#

Bases: object

Material class

Parameters:

D_0 (float or dict) – the pre-exponential factor of the diffusion coefficient (m2/s)
E_D (float or dict) – the activation energy of the diffusion coeficient (eV)
K_S_0 (float or dict) – the pre-exponential factor of the solubility coefficient (H/m3/Pa0.5)
E_K_S (float or dict) – the activation energy of the solubility coeficient (eV)
name (str) – the name of the material
thermal_conductivity (float, callable) – the thermal conductivity of the material (W/m/K)
density (float, callable) – the density of the material (kg/m3)
heat_capacity (float, callable) – the heat capacity of the material (J/kg/K)
solubility_law (str) – the solubility law of the material (“sievert” or “henry”)

Variables:

D_0 (float or dict) – the pre-exponential factor of the diffusion coefficient (m2/s)
E_D (float or dict) – the activation energy of the diffusion coeficient (eV)
K_S_0 (float or dict) – the pre-exponential factor of the solubility coefficient (H/m3/Pa0.5)
E_K_S (float or dict) – the activation energy of the solubility coeficient (eV)
name (str) – the name of the material
thermal_conductivity (float, callable) – the thermal conductivity of the material (W/m/K)
density (float, callable) – the density of the material (kg/m3)
heat_capacity (float, callable) – the heat capacity of the material (J/kg/K)

Examples

# if only one species:
Material(D_0=1.9e-7, E_D=0.2, name="my_mat")

# if several species:
Material(
    D_0={"Species_1": 1.9e-7, "Species_2": 2.0e-7},
    E_D={"Species_1": 0.2, "Species_2": 0.3},
    name="my_mat"
)

get_D_0(species=None)[source]#

Returns the pre-exponential factor of the diffusion coefficient

Parameters:: species (festim.Species or str, optional) – the species we want the pre-exponential factor of the diffusion coefficient of. Only needed if D_0 is a dict.
Returns:: the pre-exponential factor of the diffusion coefficient
Return type:: float

get_E_D(species=None)[source]#

Returns the activation energy of the diffusion coefficient

Parameters:: species (festim.Species or str, optional) – the species we want the activation energy of the diffusion coefficient of. Only needed if E_D is a dict.
Returns:: the activation energy of the diffusion coefficient
Return type:: float

get_E_K_S(species=None) → float[source]#

Returns the activation energy of the solubility coefficient

Parameters:: species – the species we want the activation energy of the solubility coefficient of. Only needed if E_K_S is a dict.
Returns:: the activation energy of the solubility coefficient

get_K_S_0(species=None) → float[source]#

Returns the pre-exponential factor of the solubility coefficient

Parameters:: species – the species we want the pre-exponential factor of the solubility coefficient of. Only needed if K_S_0 is a dict.
Returns:: the pre-exponential factor of the solubility coefficient

get_diffusion_coefficient(mesh, temperature, species=None)[source]#

Defines the diffusion coefficient

Parameters:

mesh (dolfinx.mesh.Mesh) – the domain mesh
temperature (dolfinx.fem.Constant) – the temperature
species (festim.Species, optional) – the species we want the diffusion coefficient of. Only needed if D_0 and E_D are dicts.

Returns:

the diffusion coefficient

Return type:

ufl.algebra.Product

get_solubility_coefficient(mesh, temperature, species=None)[source]#

Defines the solubility coefficient

Parameters:

mesh (dolfinx.mesh.Mesh) – the domain mesh
temperature (dolfinx.fem.Constant) – the temperature
species (festim.Species, optional) – the species we want the solubility coefficient of. Only needed if K_S_0 and E_K_S are dicts.

Returns:

the solubility coefficient

Return type:

ufl.algebra.Product

class ProblemBase(mesh: Mesh = None, sources=None, exports=None, subdomains=None, boundary_conditions=None, settings=None, petsc_options=None)[source]#

Bases: object

Base class for HeatTransferProblem and HydrogenTransportProblem.

Variables:

show_progress_bar (bool) – If True a progress bar is displayed during the simulation
progress_bar (None | tqdm.std.tqdm) – the progress bar

create_solver()[source]#: Creates the solver of the model

define_boundary_conditions()[source]#: Defines the dirichlet boundary conditions of the model

define_meshtags_and_measures()[source]#: Defines the facet and volume meshtags of the model which are used to define the measures fo the model, dx and ds

iterate()[source]#: Iterates the model for a given time step

run()[source]#: Runs the model

Bases: object

A reaction between two species, with a forward and backward rate.

Parameters:

reactant (Union[F.Species, F.ImplicitSpecies], List[Union[F.Species, F.ImplicitSpecies]]) – The reactant.
product (Optional[Union[F.Species, List[F.Species]]]) – The product.
k_0 (float) – The forward rate constant pre-exponential factor.
E_k (float) – The forward rate constant activation energy.
p_0 (float) – The backward rate constant pre-exponential factor.
E_p (float) – The backward rate constant activation energy.
volume (F.VolumeSubdomain1D) – The volume subdomain where the reaction takes place.

Variables:

reactant (Union[F.Species, F.ImplicitSpecies], List[Union[F.Species, F.ImplicitSpecies]]) – The reactant.
product (Optional[Union[F.Species, List[F.Species]]]) – The product.
k_0 (float) – The forward rate constant pre-exponential factor.
E_k (float) – The forward rate constant activation energy.
p_0 (float) – The backward rate constant pre-exponential factor.
E_p (float) – The backward rate constant activation energy.
volume (F.VolumeSubdomain1D) – The volume subdomain where the reaction takes place.

Examples

:: testsetup:: Reaction

from festim import Reaction, Species, ImplicitSpecies

:: testcode:: Reaction

# create a volume subdomain # create two species reactant = [F.Species(“A”), F.Species(“B”)]

# create a product species product = F.Species(“C”)

# create a reaction between the two species reaction = Reaction(reactant, product, k_0=1.0, E_k=0.2, p_0=0.1, E_p=0.3) print(reaction) # A + B <–> C

# compute the reaction term at a given temperature temperature = 300.0 reaction_term = reaction.reaction_term(temperature)

reaction_term(temperature, reactant_concentrations: List = None, product_concentrations: List = None) → Expr[source]#

Compute the reaction term at a given temperature.

Parameters:

temperature – The temperature at which the reaction term is computed.
reactant_concentrations – The concentrations of the reactants. Must be the same length as the reactants. If None, the concentration attribute of each reactant is used. If an element is None, the concentration attribute of the reactant is used.
product_concentrations – The concentrations of the products. Must be the same length as the products. If None, the concentration attribute of each product is used. If an element is None, the concentration attribute of the product is used.

Returns:

The reaction term to be used in a formulation.

class Settings(atol, rtol, max_iterations=30, transient=True, final_time=None, stepsize=None, convergence_criterion: Literal['residual', 'incremental'] = 'residual')[source]#

Bases: object

Settings for a festim simulation.

Parameters:

atol (float or callable) – Absolute tolerance for the solver.
rtol (float or callable) – Relative tolerance for the solver.
max_iterations (int, optional) – Maximum number of iterations for the solver. Defaults to 30.
transient (bool, optional) – Whether the simulation is transient or not.
final_time (float, optional) – Final time for a transient simulation. Defaults to None
stepsize (festim.Stepsize, optional) – stepsize for a transient simulation. Defaults to None
convergence_criterion – resiudal or incremental (for Newton solver)

Variables:

atol (float or callable) – Absolute tolerance for the solver.
rtol (float or callable) – Relative tolerance for the solver.
max_iterations (int) – Maximum number of iterations for the solver.
transient (bool) – Whether the simulation is transient or not.
final_time (float) – Final time for a transient simulation.
stepsize (festim.Stepsize) – stepsize for a transient simulation.
convergence_criterion – resiudal or incremental (for Newton solver)

class HeatSource(value, volume)[source]#

Bases: SourceBase

Heat source class

Parameters:

value – the value of the source
volume – the volume subdomains where the source is applied

Variables:

value (float | int | dolfinx.fem.function.Constant | numpy.ndarray | dolfinx.fem.function.Expression | ufl.core.expr.Expr | dolfinx.fem.function.Function) – the value of the source
volume (festim.subdomain.volume_subdomain.VolumeSubdomain) – the volume subdomains where the source is applied

Examples

from festim import HeatSource

HeatSource(volume=my_vol, value=1)
HeatSource(volume=my_vol, value=lambda x: 1 + x[0])
HeatSource(volume=my_vol, value=lambda t: 1 + t)
HeatSource(volume=my_vol, value=lambda x, t: 1 + x[0] + t)

class ParticleSource(value, volume, species: Species)[source]#

Bases: SourceBase

Particle source class

Parameters:

value – the value of the source
volume – the volume subdomains where the source is applied
species – the species to which the source is applied

Variables:

value (float | int | dolfinx.fem.function.Constant | numpy.ndarray | dolfinx.fem.function.Expression | ufl.core.expr.Expr | dolfinx.fem.function.Function) – the value of the source
volume (festim.subdomain.volume_subdomain.VolumeSubdomain) – the volume subdomains where the source is applied
species (festim.species.Species) – the species to which the source is applied

Examples

from festim import ParticleSource

ParticleSource(volume=my_vol, value=1, species="H")
ParticleSource(volume=my_vol, value=lambda x: 1 + x[0], species="H")
ParticleSource(volume=my_vol, value=lambda t: 1 + t, species="H")
ParticleSource(volume=my_vol, value=lambda T: 1 + T, species="H")
ParticleSource(volume=my_vol, value=lambda x, t: 1 + x[0] + t, species="H")

Bases: object

Source base class

Parameters:

value – the value of the source
volume – the volume subdomains where the source is applied

Variables:

value (float | int | dolfinx.fem.function.Constant | numpy.ndarray | dolfinx.fem.function.Expression | ufl.core.expr.Expr | dolfinx.fem.function.Function) – the value of the source
volume (festim.subdomain.volume_subdomain.VolumeSubdomain) – the volume subdomains where the source is applied

class ImplicitSpecies(n: float | callable, others: List[Species] = None, name: str = None)[source]#

Bases: object

Implicit species class for H transport simulation. c = n - others

Parameters:

n (Union[float, callable]) – the total concentration of the species
others (list[Species]) – the list of species from which the implicit species concentration is computed (c = n - others)
name (str, optional) – a name given to the species. Defaults to None.

Variables:

name (str) – a name given to the species.
n (float) – the total concentration of the species
others (list[Species]) – the list of species from which the implicit species concentration is computed (c = n - others)
concentration (form) – the concentration of the species
value_fenics – the total concentration as a fenics object

create_value_fenics(mesh, t: Constant)[source]#

Creates the value of the density as a fenics object and sets it to self.value_fenics. If the value is a constant, it is converted to a fenics.Constant. If the value is a function of t, it is converted to a fenics.Constant. Otherwise, it is converted to a ufl Expression

Parameters:

mesh (dolfinx.mesh.Mesh) – the mesh
t (dolfinx.fem.Constant) – the time

update_density(t)[source]#

Updates the density value (only if the density is a function of time only)

Parameters:: t (float) – the time

class Species(name: str = None, mobile=True, subdomains=None)[source]#

Bases: object

Hydrogen species class for H transport simulation.

Parameters:

name (str, optional) – a name given to the species. Defaults to None.
mobile (bool, optional) – whether the species is mobile or not. Defaults to True.
subdomain (F.VolumeSubdomain, optional) – the volume subdomain where the species is. Defaults to None.

Variables:

name (str) – a name given to the species.
mobile (bool) – whether the species is mobile or not.
solution (dolfinx.fem.Function) – the solution for the current timestep
prev_solution (dolfinx.fem.Function) – the solution for the previous timestep
test_function (ufl.Argument) – the testfunction associated with this species
sub_function_space (dolfinx.fem.function.FunctionSpaceBase) – the subspace of the function space
collapsed_function_space (dolfinx.fem.function.FunctionSpaceBase) – the collapsed function space for a species in the function space. In case single species case, this is None.
post_processing_solution (dolfinx.fem.Function) – the solution for post processing
concentration (dolfinx.fem.Function) – the concentration of the species
subdomains (F.VolumeSubdomain) – the volume subdomains where the species is
subdomain_to_solution (dict) – a dictionary mapping subdomains to solutions
subdomain_to_prev_solution (dict) – a dictionary mapping subdomains to previous solutions
subdomain_to_test_function (dict) – a dictionary mapping subdomains to test functions
subdomain_to_post_processing_solution (dict) – a dictionary mapping subdomains to post processing solutions
subdomain_to_collapsed_function_space (dict) – a dictionary mapping subdomains to collapsed function spaces
subdomain_to_function_space (dict) – a dictionary mapping subdomains to function spaces

Examples

:: testsetup:: Species

from festim import Species

:: testcode:: Species

Species(name=”H”) Species(name=”Trap”, mobile=False)

property legacy: bool#: Check if we are using FESTIM 1.0 implementation or FESTIM 2.0

find_species_from_name(name: str, species: list)[source]#

Returns the correct species object from a list of species based on a string

Parameters:

name (str) – the name of the species
species (list) – the list of species

Returns:

the species object with the correct name

Return type:

species (festim.Species)

Raises:

ValueError – if the species name is not found in the list of species

class Stepsize(initial_value, growth_factor=None, cutback_factor=None, target_nb_iterations=None, max_stepsize=None, milestones=None)[source]#

Bases: object

A class for evaluating the stepsize of transient simulations.

Parameters:

initial_value (float, int) – initial stepsize.
growth_factor (float, optional) – factor by which the stepsize is increased when adapting
cutback_factor (float, optional) – factor by which the stepsize is decreased when adapting
target_nb_iterations (int, optional) – number of Newton iterations over (resp. under) which the stepsize is increased (resp. decreased)
max_stepsize (float or callable, optional) – Maximum stepsize. If callable, has to be a function of t. Defaults to None.
milestones (list, optional) – list of times by which the simulation must pass. Defaults to None.

Variables:

initial_value (float, int) – initial stepsize.
growth_factor (float) – factor by which the stepsize is increased when adapting
cutback_factor (float) – factor by which the stepsize is decreased when adapting
target_nb_iterations (int) – number of Newton iterations over (resp. under) which the stepsize is increased (resp. decreased)
adaptive (bool) – True if the stepsize is adaptive, False otherwise.
max_stepsize (float, callable) – Maximum stepsize.
milestones (list) – list of times by which the simulation must pass.

get_max_stepsize(t)[source]#

Returns the maximum stepsize at time t.

Parameters:: t (float) – the current time
Returns:: the maximum stepsize at time t
Return type:: float or None

is_adapt(t)[source]#

Methods that defines if the stepsize should be adapted or not

Parameters:: t (float) – the current time
Returns:: True if needs to adapt, False otherwise.
Return type:: bool

next_milestone(current_time: float)[source]#

Returns the next milestone that the simulation must pass. Returns None if there are no more milestones.

Parameters:: current_time (float) – current time.
Returns:: next milestone.
Return type:: float

class Trap(name: str, mobile_species, k_0, E_k, p_0, E_p, n, volume)[source]#

Bases: Species

Trap species class for H transport simulation.

This class only works for 1 mobile species and 1 trapping level and is for convenience, for more details see notes.

Parameters:

name (str, optional) – a name given to the trap. Defaults to None.
mobile_species (_Species) – the mobile species to be trapped
k_0 (float) – the trapping rate constant pre-exponential factor (m3 s-1)
E_k (float) – the trapping rate constant activation energy (eV)
p_0 (float) – the detrapping rate constant pre-exponential factor (s-1)
E_p (float) – the detrapping rate constant activation energy (eV)
volume (F.VolumeSubdomain1D) – The volume subdomain where the trap is.

Variables:

name (str, optional) – a name given to the trap. Defaults to None.
mobile_species (_Species) – the mobile species to be trapped
k_0 (float) – the trapping rate constant pre-exponential factor (m3 s-1)
E_k (float) – the trapping rate constant activation energy (eV)
p_0 (float) – the detrapping rate constant pre-exponential factor (s-1)
E_p (float) – the detrapping rate constant activation energy (eV)
volume (F.VolumeSubdomain1D) – The volume subdomain where the trap is.
trapped_concentration (_Species) – The immobile trapped concentration
trap_reaction (_Reaction) – The reaction for trapping the mobile conc.
empty_trap_sites (F.ImplicitSpecies) – The implicit species for the empty trap sites

Examples

trap = Trap(name="Trap", mobile_species=H, k_0=1.0, E_k=0.2, p_0=0.1, E_p=0.3, n=100, volume=my_vol)

my_model = HydrogenTransportProblem()
my_model.traps = [trap]

Notes

This convenience class replaces the need to specify an implicit species and the associated reaction, thus:

cm = _Species("mobile")
my_trap = F.Trap(
    name="trapped",
    mobile_species=cm,
    k_0=1,
    E_k=1,
    p_0=1,
    E_p=1,
    n=1,
    volume=my_vol,
)
my_model.species = [cm]
my_model.traps = [my_trap]

is equivalent to:

cm = _Species("mobile")
ct = _Species("trapped")
trap_sites = F.ImplicitSpecies(n=1, others=[ct])
trap_reaction = _Reaction(
    reactant=[cm, trap_sites],
    product=ct,
    k_0=1,
    E_k=1,
    p_0=1,
    E_p=1,
    volume=my_vol,
)
my_model.species = [cm, ct]
my_model.reactions = [trap_reaction]

create_species_and_reaction()[source]#: create the immobile trapped species object and the reaction for trapping

API reference

Contents

API reference#