lizzy

The LIZZY namespace exposes the LizzyModel class, which provides all the user-facing APIs to interact with Lizzy. It also exposes the SolverType enum, which contains the available solver types to choose from.

class lizzy.LizzyModel

The main class for defining simulations in Lizzy. This class wraps all subcomponents of the solver and exposes all user-facing APIs. Provides access to methods for reading a mesh, assigning properties, configuring the solver, saving results and more. A script typically begins with the instantiation of a LizzyModel.

Properties

property assigned_materials: Dict[str, PorousMaterial]: Dictionary of assigned materials in the model. (read-only)

property existing_materials: Dict[str, PorousMaterial]: Dictionary of existing materials in the model. A material can be existing (after being created with create_material()) but not assigned to any mesh region. (read-only)

property n_empty_cvs: int: Number of currently empty control volumes in the mesh (read-only).

property current_time: float: Current simulation time from the start of the infusion (read-only).

property latest_solution: Solution: The most recent solution from the model (read-only). This value is None if the model is run in lightweight mode.

Model setup methods

read_mesh_file(mesh_file_path: str | PathLike) → None

Reads a mesh file and initialises the mesh. Currently only .MSH format is supported (Version 4 ASCII).

Parameters:: mesh_file_path (str) – Path to the mesh file from the current working folder.

print_mesh_info() → None: Prints some information about the mesh.

set_simulation_parameters(*, output_interval: float = 10, fill_tolerance: float = 0.01, end_step_when_sensor_triggered: bool = False, lightweight: bool = False, in_memory_solve: bool = False, progress_bar: bool = False) → None

Set values to one or more simulation parameters using keyword arguments.

Parameters:

**kwargs –

Keyword arguments corresponding to parameter names and their new values. Valid keywords are:

output_interval (float, optional): interval of simulation time between solution write-outs [s]. A negative value will write-out every numerical time step (not recommended). Default: 10
fill_tolerance (float, optional): tolerance on the fill factor to consider a CV as filled. Default: 0.01
end_step_when_sensor_triggered (bool, optional): if True, ends current solution step and creates a write-out when a sensor changes state. Default: False
lightweight (bool, optional): if True, disables Solution packing after each solve, saving memory and computation time. save_results() cannot be used in lightweight mode. Default: False
in_memory_solve (bool, optional): if False (default), solution data is written incrementally to disk during the solve, reducing memory footprint for large simulations. If True, solution data is accumulated in memory and written at the end via save_results(). Default: False
progress_bar (bool, optional): if True, shows a progress bar during the solution. Default: False

Examples

>>> model.set_simulation_parameters(output_interval=50)

Raises:: AttributeError – If any key in kwargs does not correspond to a known attribute.

print_simulation_parameters() → None: Print the currently assigned simulation parameters.

create_resin(name: str, viscosity: float) → Resin

Create a new resin that can then be selected and used in the model.

Parameters:

name (str) – Unique name of the resin.
viscosity (float) – Dynamic viscosity of the resin [Pa.s]

Returns:

Reference to the created resin.

Return type:

Resin

assign_resin(resin_selector: Resin | str) → None

Assign an existing resin to the model.

Parameters:: resin_selector (Resin | str) – The resin object or name of the resin to assign. Must correspond to an existing resin created with create_resin().

Note

Resin is a global property and does not need to be assigned to specific mesh regions. Only one resin can be assigned to the model, and it will be used for the entire simulation domain.

create_material(name: str, k_vals: tuple[float, float, float], porosity: float, thickness: float) → PorousMaterial

Create a new material that can then be selected and used in the model.

Parameters:

name (str) – Unique name of the new material.
k_vals (tuple[float, float, float]) – Permeability values in the three principal directions (k1, k2, k3) [m²]. All values must be positive.
porosity (float) – Volumetric porosity of the material (porosity = 1 - fibre volume fraction). Must be between 0 and 1 (exclusive).
thickness (float) – Thickness of the material in the out-of-plane direction [m]. Must be positive.

Returns:

Reference to the created material.

Return type:

PorousMaterial

assign_material(material_selector: PorousMaterial | str, mesh_tag: str, rosette: Rosette = None) → None

Assign an existing material to a labeled mesh region.

Parameters:

material_selector (str) – Label of the material to assign. Must correspond to an existing material created with LizzyModel.create_material.
mesh_tag (str) – Label of the mesh region where to assign the material.
rosette (Rosette, optional) – Orientation rosette to apply to the material. If none provided, a default rosette with k1 aligned with the global X axis is assigned.

create_rosette(name: str, u: tuple[float, float, float]) → Rosette

Create a new orientation rosette that can then be used when assigning a material.

Parameters:

name (str) – Unique name of the new rosette.
u (tuple[float, float, float]) – Direction vector defining the first principal direction of the rosette (k1 direction), expressed in global (x, y, z) coordinates. Does not need to be normalised.

Returns:

Reference to the created rosette.

Return type:

Rosette

Mesh management methods

get_elements() → list[Triangle]

Returns the list of all mesh elements.

Returns:: List of all Triangle elements in the mesh.
Return type:: list of Triangle

get_element_by_idx(idx: int) → Triangle

Returns the mesh element at the given index.

Parameters:: idx (int) – Integer index of the element.
Returns:: The element at the given index.
Return type:: Triangle

get_nodes() → list[Node]

Returns the list of all mesh nodes.

Returns:: List of all Node objects in the mesh.
Return type:: list of Node

get_node_by_idx(idx: int) → Node

Returns the mesh node at the given index.

Parameters:: idx (int) – Integer index of the node.
Returns:: The node at the given index.
Return type:: Node

Inlet management methods

create_pressure_inlet(name: str, initial_pressure_value: float) → PressureInlet

Creates a new inlet where a pressure boundary condition is applied.

Parameters:

name (str) – Name of the inlet.
initial_pressure_value (float) – Initial pressure value at the inlet.

Returns:

The created inlet.

Return type:

PressureInlet

create_flowrate_inlet(name: str, initial_flowrate_value: float) → FlowRateInlet

Creates a new inlet where a volumetric flow rate boundary condition is applied.

Parameters:

name (str) – Name of the inlet.
initial_flowrate_value (float) – Initial volumetric flow rate value at the inlet.

Returns:

The created inlet.

Return type:

FlowRateInlet

assign_inlet(inlet_selector: Inlet | str, boundary_tag: str) → None

Selects an inlet from created ones and assigns it to the indicated mesh boundary.

Parameters:

inlet_selector (Inlet | str) – Either the inlet object to assign, or the name of an existing inlet.
boundary_tag (str) – An existing mesh boundary tag where to assign the inlet.

fetch_inlet_by_name(inlet_name: str) → Inlet

Fetches an inlet from existing ones in the model.

Parameters:: inlet_name (str) – The name of an existing inlet.
Returns:: The fetched inlet object.
Return type:: Inlet

change_inlet_pressure(inlet_selector: Inlet | str, pressure_value: float, mode: Literal['set', 'delta'] = 'set')

Changes the pressure value at the selected inlet to a new value, according to the selected mode.

Parameters:

inlet_selector (Inlet | str) – Either the inlet object to assign, or the name of an existing inlet.
pressure_value (float) – The new pressure value to set at the inlet.
mode ({'set', 'delta'}, optional) –
How to apply the new pressure value:
- set (default): directly set the new pressure value.
- delta: increment the existing pressure by the given value.

Raises:

ValueError – If the mode is not one of the allowed values.

open_inlet(inlet_selector: Inlet | str)

Sets the selected inlet state to open. When open, the inlet applies its p_value as a Dirichlet boundary condition. An inlet can be opened at any time during the simulation.

Parameters:: inlet_selector (Inlet | str) – Either the inlet object reference, or the name of an existing inlet.

close_inlet(inlet_selector: Inlet | str)

Sets the selected inlet state to closed. When closed, the inlet acts as a Neumann natural boundary condition (no flux). An inlet can be closed at any time during the simulation. The stored p_value is preserved when the inlet is closed.

Parameters:: inlet_selector (Inlet | str) – Either the inlet object reference, or the name of an existing inlet.

Vent management methods

create_vent(name: str, vacuum_pressure: float = 0.0) → Vent

Creates a new vent where a vacuum pressure boundary condition is applied.

Parameters:

name (str) – Name of the vent.
vacuum_pressure (float, optional) – Vacuum pressure value at the vent (default is 0.0).

Returns:

The created vent.

Return type:

Vent

assign_vent(vent_selector: Vent | str, boundary_tag: str) → None

Selects a vent from created ones and assigns it to the indicated mesh boundary.

Note

Currently only one vent can be assigned to the model. Attempting to assign a second vent will raise a ConfigurationError.

Parameters:

vent_selector (Vent | str) – Either the vent object to assign, or the name of an existing vent.
boundary_tag (str) – An existing mesh boundary tag where to assign the vent.

Sensor management methods

create_sensor(name: str, coords: tuple[float, float, float]) → None

Create a virtual sensor at the specified position and add it to the model.

Parameters:

name (str) – The name of the sensor
coords (tuple[float, float, float]) – The coordinates of the sensor

print_sensor_readings(): Prints to the console the current readings of each sensor: time, pressure, fill factor and velocity.

get_sensor_trigger_states() → list[bool]: Returns a list of sensor trigger states: True if the sensor has been triggered, False otherwise.

get_sensor_by_name(name: str) → Sensor

Fetches a sensor by its name.

Parameters:: name (str) – Name of the sensor to fetch.
Returns:: The fetched sensor object.
Return type:: Sensor

Solver methods

initialise_solver(solver_type: SolverType = SolverType.ITERATIVE_PETSC, solver_tol: float = 1e-08, solver_max_iter: int = 1000, solver_verbose: bool = False, **solver_kwargs)

Initialize the solver for the filling simulation.

Parameters:

solver_type (SolverType) – Type of linear solver (DIRECT_DENSE, DIRECT_SPARSE, ITERATIVE_PETSC). Default is ITERATIVE_PETSC and will revert to DIRECT_SPARSE is PETSc is not installed.
solver_tol (float) – Convergence tolerance for iterative solvers
solver_max_iter (int) – Maximum iterations for iterative solvers
solver_verbose (bool) – Print solver convergence information
**solver_kwargs – Additional solver-specific keyword arguments

Raises:

ConfigurationError – If required components (resin, materials, inlets, vents) are not properly assigned.

solve(time_interval: float = None) → Solution

Advance the filling simulation from the current time until the part is filled.

Returns:: solution – A Solution object storing the solution fields up to the time step reached. Returns None if in_memory_solve=False (streaming mode).
Return type:: Solution

solve_time_interval(time_interval: float) → Solution

Advance the filling simulation from the current time for the specified time interval.

Parameters:: time_interval (float) – The time period to advance the simulation for.
Returns:: solution – A Solution object storing the solution fields up to the time step reached. Returns None if in_memory_solve=False (streaming mode).
Return type:: Solution

initialise_new_solution(): Initialises a new solution, resetting all simulation variables. The part will be emptied and initial boundary conditions restored. This method can be called to reset a simulation and run a new one, without resetting the model.

save_results(result_name: str = None, solution: Solution = None, save_permeability: bool = False, **kwargs)

Save the results contained in the solution dictionary into an XDMF file.

Parameters:

solution (Solution, optional) – The solution that should be written to the XDMF file. If none passed, the latest solution present in the model will be used.
result_name (str, optional) – The name of the solution file that will be created. If none passed, the name of the mesh file with appended ‘_RES’ will be used.
save_permeability (bool, optional) – If True, include the full 3x3 permeability tensor as a cell field in the output. Default is False.

class lizzy.SolverType(*values)

Bases: Enum

Enum representing the available pressure solver types.

Parameters:

DIRECT_DENSE (SolverType) – Direct solver using dense matrix factorization.
DIRECT_SPARSE (SolverType) – Direct solver using sparse matrix factorization.
ITERATIVE_PETSC (SolverType) – Iterative solver using PETSc.

DIRECT_DENSE = 1

DIRECT_SPARSE = 2

ITERATIVE_PETSC = 3