Exports

class Export(field=None)

Bases: object

class XDMFExport(field, label=None, filename=None, mode=1, checkpoint=True, folder=None)

Bases: Export

Parameters:

• field (str) – the exported field (“solute”, “1”, “retention”, “T”…)

• label (str, optional) – label of the field in the written file. If None, an automatic label will be given. Defaults to None.

• filename (str, optional) – the file path, needs to end with ‘.xdmf’. If None, the label will be used. Defaults to None.

• mode (int, str, optional) – if “last” only the last timestep will be exported. Otherwise the number of iterations between each export can be provided as an integer. Defaults to 1.

• checkpoint (bool, optional) – If set to True, fenics.XDMFFile.write_checkpoint will be use, else fenics.XDMFFile.write. Defaults to True.

• folder (str, optional) – path of the export folder. Defaults to None.

define_xdmf_file()

Creates the file

is_export(t, final_time, nb_iterations)

Checks if export should be exported.

Parameters:

• t (float) – the current time

• final_time (float) – the final time of the simulation

• nb_iterations (int) – the current number of time steps

Returns:

True if export should be exported, else False

Return type:

bool

write(t)

Writes to file

Parameters:

t (float) – current time

class TXTExport(field, filename, times=None, filter=True, write_at_last=False, header_format='.2e')

Bases: Export

Parameters:

• field (str) – the exported field (“solute”, “1”, “retention”, “T”…)

• filename (str) – the filename (must end with .txt).

• times (list, optional) – if provided, the field will be exported at these timesteps. Otherwise exports at all timesteps. Defaults to None.

• filter (bool) – if True and the field is projected to a DG function space, the duplicated vertices in the output file array are filtered except those near interfaces. Defaults to True.

• write_at_last (bool) – if True, the data will be exported at the last export time. Otherwise, the data will be exported at each export time. Defaults to False.

• header_format (str, optional) – the format of column headers. Defautls to “.2e”.

Variables:

• data (np.array) – the data array of the exported field. The first column is the mesh vertices. Each next column is the field profile at the specific export time.

• header (str) – the header of the exported file.

• V (fenics.FunctionSpace) – the vector-function space for the exported field.

Note

The exported field is projected to DG if conservation of chemical potential is considered or traps_element_type is “DG”.

initialise(mesh, project_to_DG=False, materials=None)

Initialises TXTExport. Depending on the project_to_DG flag, defines a function space (DG1 or CG1) for projection of the exported field. After that, an unsorted array of mesh vertices is created for export. The array is then used to obtain indices of sorted elements for the data export.

Note

If DG1 is used and the filter flag is True, the duplicated vertices in the array are filtered except those near interfaces. The interfaces are defined by material.borders in the Materials list.

Parameters:

• mesh (fenics.Mesh) – the mesh.

• project_to_DG (bool) – if True, the exported field is projected to a DG1 function space. Defaults to False.

• materials (festim.Materials) – the materials. Defaults to None.

is_it_time_to_export(current_time)

Checks if the exported field should be written to a file or not based on the current time and the TXTExport.times

Parameters:

current_time (float) – the current simulation time

Returns:

True if the exported field should be written to a file, else False

Return type:

bool

is_last(current_time, final_time)

Checks if the current simulation step equals to the last export time. based on the final simulation time, TXTExport.times, and the current time

Parameters:

• current_time (float) – the current simulation time.

• final_time (float, None) – the final simulation time.

Returns:

True if simulation is steady (final_time is None), if TXTExport.times are not provided and the current time equals to the final time, or if TXTExport.times are provided and the current time equals to the last time in TXTExport.times, else False.

Return type:

bool

write(current_time, final_time)

Modifies the header and writes the data to a file depending on the current and the final times of a simulation.

Parameters:

• current_time (float) – the current simulation time.

• final_time (float, None) – the final simulation time.

class TrapDensityXDMF(trap, **kwargs)

Bases: XDMFExport

Parameters:

• trap (festim.Trap) – the trap to export density

• () (kwargs) – See XDMFExport

write(t, dx)

Writes to file

Parameters:

• t (float) – the time

• dx (fenics.Measure) – the measure for dx

class DerivedQuantity(field)

Bases: Export

Parent class of all derived quantities

Parameters:

field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (fenics.Function) – the solution function of the field

• dx (fenics.Measure) – the measure of the volume

• ds (fenics.Measure) – the measure of the surface

• n (fenics.Function) – the normal vector

• D (fenics.Function) – the diffusion coefficient

• S (fenics.Function) – the source term

• thermal_cond (fenics.Function) – the thermal conductivity

• Q (fenics.Function) – the heat source term

• data (list) – the data of the derived quantity

• t (list) – the time values of the data

• allowed_meshes (list) – the allowed meshes for the derived quantity

class DerivedQuantities(*args, filename: str = None, nb_iterations_between_compute: int = 1, nb_iterations_between_exports: int = None, show_units=True)

Bases: list

A list of festim.DerivedQuantity objects

Parameters:

• filename (str, optional) – the filename (must end with .csv). If None, the data will not be exported. Defaults to None.

• nb_iterations_between_compute (int, optional) – number of iterations between each derived quantities computation. Defaults to 1.

• nb_iterations_between_exports (int, optional) – number of iterations between each export. If None, the file will be exported at the last timestep. Defaults to None.

• show_units (bool, optional) – will show the units of each derived quantity in the title in export. Defaults to True.

Variables:

• filename (str) – the filename.

• nb_iterations_between_compute (int) – number of iterations between each derived quantities computation.

• nb_iterations_between_exports (int) – number of iterations between each export. If None, the file will be exported at the last timestep.

• show_units (bool) – will show the units of each derived quantity in the title in export

• data (list) – the data to be exported

• t (list) – the time steps

append(item)

Append object to the end of the list.

assign_properties_to_quantities(materials)

Assign properties attributes to all DerivedQuantity objects (D, S, thermal_cond and H) based on the properties stored in materials

Parameters:

materials (festim.Materials) – the materials

extend(other)

Extend list by appending elements from the iterable.

filter(surfaces: list | int = None, volumes: list | int = None, fields: list | str = None, instances: DerivedQuantity = None)

Finds DerivedQuantity objects that match surfaces, volumes, and instances.

Parameters:

• surfaces (Union[list, int], optional) – the surface ids to match. Defaults to None.

• volumes (Union[list, int], optional) – the volume ids to match. Defaults to None.

• fields (Union[list, str], optional) – the fields to match. Defaults to None.

• instances (DerivedQuantity, optional) – the DerivedQuantity instances to match. Defaults to None.

Returns:

if only one quantity matches returns this

quantity, else returs a list of DerivedQuantity

Return type:

list, DerivedQuantity

insert(index, item)

Insert object before index.

is_compute(nb_iterations)

Checks if the derived quantities should be computed or not based on the current number of iterations

Parameters:

nb_iterations (int) – the current number of time steps

Returns:

True if it’s time to compute, else False

Return type:

bool

is_export(t, final_time, nb_iterations)

Checks if the derived quantities should be exported or not based on the current time, the final time of simulation and the current number of iterations

Parameters:

• t (float) – the current time

• final_time (float) – the final time of the simulation

• nb_iterations (int) – the current number of time steps

Returns:

True if the derived quantities should be exported, else False

Return type:

bool

class PointValue(field: str | int, x: int | float | tuple | list)

Bases: DerivedQuantity

Computes the value of a field at a given point

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• x (int, float, tuple, list) – the point coordinates

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• x (int, float, tuple, list) – the point coordinates

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

compute()

Evaluates the value of a function at the given point

class AdsorbedHydrogen(surface)

Bases: SurfaceQuantity

Object to compute the value of the adsorbed H concentration, defined with the SurfaceKinetics boundary condition on a given surface.

Warning

The AdsorbedHydrogen export can be used only if the SurfaceKinetics condition is defined on the same surface!

Parameters:

surface (int) – the surface id

Variables:

• surface (int) – the surface id

• export_unit (str) – the unit of the derived quantity in the export file

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the hydrogen adsorbed field

class AverageSurface(field, surface)

Bases: SurfaceQuantity

Computes the average value of a field on a given surface int(f ds) / int (1 * ds)

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

class AverageVolume(field, volume: int)

Bases: VolumeQuantity

Computes the average value of a field in a given volume int(f dx) / int (1 * dx)

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

• r (ufl.indexed.Indexed) – the radius of the cylinder

Note

Units are in H/m3 for hydrogen concentration and K for temperature

class SurfaceFlux(field, surface)

Bases: SurfaceQuantity

Computes the surface flux of a field at a given surface in cartesian coordinates

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• export_unit (str) – the unit of the derived quantity in the export file

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

Note

Object to compute the flux J of a field u through a surface J = integral(+prop * grad(u) . n ds) where prop is the property of the field (D, thermal conductivity, etc) u is the field n is the normal vector of the surface ds is the surface measure. units are in H/m2/s in 1D, H/m/s in 2D and H/s in 3D domains for hydrogen concentration and W/m2 in 1D, W/m in 2D and W in 3D domains for temperature

class SurfaceFluxCylindrical(field, surface, azimuth_range=(0, 6.283185307179586))

Bases: SurfaceFlux

Object to compute the flux J of a field u through a surface J = integral(-prop * grad(u) . n ds) where prop is the property of the field (D, thermal conductivity, etc) u is the field n is the normal vector of the surface ds is the surface measure in cylindrical coordinates. ds = r dr dtheta or ds = r dz dtheta

Note

For particle fluxes J is given in H/s, for heat fluxes J is given in W

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• azimuth_range (tuple, optional) – Range of the azimuthal angle (theta) needs to be between 0 and 2 pi. Defaults to (0, 2 * np.pi).

class SurfaceFluxSpherical(field, surface, azimuth_range=(0, 3.141592653589793), polar_range=(-3.141592653589793, 3.141592653589793))

Bases: SurfaceFlux

Object to compute the flux J of a field u through a surface J = integral(-prop * grad(u) . n ds) where prop is the property of the field (D, thermal conductivity, etc) u is the field n is the normal vector of the surface ds is the surface measure in spherical coordinates. ds = r^2 sin(theta) dtheta dphi

Note

For particle fluxes J is given in H/s, for heat fluxes J is given in W

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• azimuth_range (tuple, optional) – Range of the azimuthal angle (phi) needs to be between 0 and pi. Defaults to (0, np.pi).

• polar_range (tuple, optional) – Range of the polar angle (theta) needs to be between - pi and pi. Defaults to (-np.pi, np.pi).

class HydrogenFlux(surface)

Bases: SurfaceFlux

Computes the surface flux of hydrogen at a given surface

Parameters:

surface (int) – the surface id

Variables:

• field (str) – the hydrogen solute field

• surface (int) – the surface id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the hydrogen solute field

Note

units are in H/m2/s in 1D, H/m/s in 2D and H/s in 3D domains

class ThermalFlux(surface)

Bases: SurfaceFlux

Computes the surface flux of heat at a given surface

Parameters:

surface (int) – the surface id

Variables:

• surface (int) – the surface id

• field (str) – the temperature field

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the temperature field

Note

units are in W/m2 in 1D, W/m in 2D and W in 3D domains

class MaximumSurface(field, surface)

Bases: SurfaceQuantity

Computes the maximum value of a field on a given surface

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

compute(surface_markers)

Maximum of f over subdomains facets marked with self.surface

class MinimumSurface(field, surface)

Bases: SurfaceQuantity

Computes the minimum value of a field on a given surface

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

compute(surface_markers)

Minimum of f over subdomains facets marked with self.surface

class MaximumVolume(field, volume)

Bases: VolumeQuantity

Computes the maximum value of a field in a given volume

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function for the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

compute(volume_markers)

Minimum of f over subdomains cells marked with self.volume

class MinimumVolume(field, volume)

Bases: VolumeQuantity

Computes the minimum value of a field in a given volume

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function for the field

Note

Units are in H/m3 for hydrogen concentration and K for temperature

compute(volume_markers)

Minimum of f over subdomains cells marked with self.volume

class TotalSurface(field, surface)

Bases: SurfaceQuantity

Computes the total value of a field on a given surface int(f ds)

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

• export_unit (str) – the unit of the derived quantity for exporting

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the hydrogen solute field

Note

units are in H/m2 in 1D, H/m in 2D and H in 3D domains for hydrogen concentration and K in 1D, K m in 2D and K m2 in 3D domains for temperature

class TotalVolume(field, volume)

Bases: VolumeQuantity

Computes the total value of a field in a given volume int(f dx)

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

Variables:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id

• export_unit (str) – the unit of the derived quantity for exporting

• title (str) – the title of the derived quantity

• show_units (bool) – show the units in the title in the derived quantities file

• function (dolfin.function.function.Function) – the solution function of the hydrogen solute field

Note

units are in H/m2 in 1D, H/m in 2D and H in 3D domains for hydrogen concentration and K m in 1D, K m2 in 2D and K m3 in 3D domains for temperature

class SurfaceQuantity(field: str, surface: int)

Bases: DerivedQuantity

DerivedQuantity relative to a surface

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• surface (int) – the surface id

class VolumeQuantity(field: str, volume: int)

Bases: DerivedQuantity

DerivedQuantity relative to a volume

Parameters:

• field (str, int) – the field (“solute”, 0, 1, “T”, “retention”)

• volume (int) – the volume id