ogstools.core.simulation module#

class ogstools.core.simulation.Simulation[source]#

Bases: StorageBase

A completed or ongoing OGS simulation with associated model and results.

Combines a Model (project setup) with Results (output data) and provides convenient access to simulation outputs like mesh series and log files. Simulations can be saved, loaded, and analyzed after completion.

Initialize a Simulation object.

Parameters:

  • model (Model) – The ogstools.Model used for this simulation.

  • result (Result) – The Result object containing simulation output.

Status#

alias of SimulationStatus

classmethod from_id(simulation_id)[source]#

Load a Simulation from the user storage path using its ID.

Parameters:

simulation_id (str) – The unique identifier of the ogstools.Simulation to load.

Return type:

Self

Returns:

A ogstools.Simulation instance restored from disk.

Raises:

FileNotFoundError – If no simulation with the given ID exists.

classmethod from_folder(sim_folder)[source]#

Load a Simulation from a folder following OGSTools conventions.

Expects the folder structure created by Simulation.save(): - model/: Subfolder containing the Model - result/: Subfolder containing simulation results

Parameters:

sim_folder (Path | str) – Path to the folder containing the simulation.

Return type:

Self

Returns:

A ogstools.Simulation instance loaded from the folder.

Raises:

FileNotFoundError – If required components are not found.

__init__(model, result)[source]#

Initialize a Simulation object.

Parameters:

  • model (Model) – The ogstools.Model used for this simulation.

  • result (Result) – The Result object containing simulation output.

property status: SimulationStatus#

Get the current simulation status from the return code file.

Reads the returncode file written by the simulation controller to determine if the simulation completed successfully or with an error.

Returns:

SimulationStatus enum value (running, done, error, or unknown).

property status_str: str#

Get a human-readable status description of the simulation.

Includes information about completion status and result availability.

Returns:

String describing the simulation state.

property cmd: str#

Get the full command used to run the simulation.

property log_file: Path#

Get the absolute path to the log file.

property log: Log#

Access the parsed log file of this simulation.

Lazily loads and parses the log file on first access.

Returns:

A Log object for querying simulation log data.

property meshseries_file: Path#

Get the path to the mesh series output file.

Returns:

Path to the mesh series file (pvd, xdmf, etc.).

property meshseries: MeshSeries#

Access the mesh series of this simulation.

Lazily loads the mesh series on first access.

Returns:

A MeshSeries containing the simulation results.

save(target=None, overwrite=None, dry_run=False, archive=False, id=None)[source]#

Save the Simulation to disk, including Model and Result.

Creates a folder structure containing: - model/: The Model (project, meshes, execution config) - result/: The simulation results

Parameters:

  • target (Path | str | None) – Path to save the ogstools.Simulation. If None, uses a default location.

  • overwrite (bool | None) – If True, overwrite existing files. Defaults to False.

  • dry_run (bool) – If True, simulate save without writing files.

  • archive (bool) – If True, materialize all symlinks by copying data.

  • id (str | None) – Optional identifier. Mutually exclusive with target.

Return type:

list[Path]

Returns:

List of Paths to saved files.

restart(restart_suffix='_restart', zero_displacement=False, initialize_porosity_from_medium_property=False, *, t_initial=None, t_end=None, initial_dt=None, timevalues=None)[source]#

Prepares the PRJ file for a restart run.

Supports two mutually exclusive modes: - Time-range mode: use t_initial and t_end (optionally initial_dt). - Explicit-times mode: use timevalues only.

The method reads the last written time step from the PVD referenced in the PRJ and updates initial conditions, output prefix, and time control blocks accordingly. If zero_displacement is True, displacement initial conditions are set to zero. restart_suffix is appended to the output prefix.

t_initial/t_end and timevalues must not be used together. All time-scheme control arguments are keyword-only.

Parameters:

  • restart_suffix (str) – appended to the output prefix. Default: “_restart”

  • zero_displacement (bool) – set displacement initial conditions to zero. Default is False.

  • t_initial (float | None) – restart interval start time (time-range mode)

  • t_end (float | None) – restart interval end time (time-range mode)

  • initial_dt (float | None) – initial time step (time-range mode)

  • timevalues (list | None) – explicit list of restart times (explicit-times mode)

Return type:

Model

Returns:

None