ogstools.core.model module#

class ogstools.core.model.Model[source]#

Bases: StorageBase

A complete OGS model combining project file, meshes, and execution settings.

The Model class integrates all components needed to run an OGS simulation: - A project file (prj) defining the simulation setup - Meshes required by the simulation - Execution parameters (parallelization, logging, etc.)

Models can be created from individual components, loaded from disk, or initialized from existing folder structures following OGSTools conventions.

Initialize a Model object.

Parameters:

project (Project | Path | str) – Project object or path to a .prj file. If a path is given, the Project will be loaded from that file.
meshes (Meshes | Path | str | None) – Meshes object or path to a folder containing mesh files. If None, attempts to locate meshes in standard locations relative to the project file (same folder or ‘meshes’ subfolder).
execution (Execution | Path | str | None) – Execution object or path to an execution.yaml file. If None, creates a default Execution configuration.
id (str | None) – Optional unique identifier for this model.

Raises:

ValueError – If meshes cannot be found or located automatically.
FileNotFoundError – If specified paths do not exist.

__init__(project, meshes=None, execution=None, id=None)[source]#

Initialize a Model object.

Parameters:

project (Project | Path | str) – Project object or path to a .prj file. If a path is given, the Project will be loaded from that file.
meshes (Meshes | Path | str | None) – Meshes object or path to a folder containing mesh files. If None, attempts to locate meshes in standard locations relative to the project file (same folder or ‘meshes’ subfolder).
execution (Execution | Path | str | None) – Execution object or path to an execution.yaml file. If None, creates a default Execution configuration.
id (str | None) – Optional unique identifier for this model.

Raises:

ValueError – If meshes cannot be found or located automatically.
FileNotFoundError – If specified paths do not exist.

classmethod from_folder(folder)[source]#

Initialize a Model from a folder following OGSTools conventions.

Expects the folder structure created by Model.save(): - project/: Subfolder containing project.prj and associated files - meshes/: Subfolder containing mesh files - execution.yaml: Execution configuration

Parameters:: folder (Path | str) – Path to the folder containing the model files.
Return type:: ogstools.Model
Returns:: A ogstools.Model object initialized from the folder contents.
Raises:: FileNotFoundError – If required files are not found in the folder.

classmethod from_id(model_id)[source]#

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

Parameters:: model_id (str) – The unique ID of the ogstools.Model to load.
Return type:: ogstools.Model
Returns:: A ogstools.Model instance with Project and Meshes loaded from disk.

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

Save the Model to disk, including Project, Meshes, and Execution config.

Creates a folder structure containing: - project/: Subfolder with project.prj and associated files - meshes/: Subfolder with mesh files - execution.yaml: Execution configuration

By default, uses symlinks for efficiency. Use archive=True to create a standalone copy with all data materialized.

Parameters:

target (Path | str | None) – Path to the folder where the model should be saved. If None, uses a default location based on the model ID.
overwrite (bool | None) – If True, existing files are overwritten. If False, raises an error if files already exist.
dry_run (bool) – If True, simulates the save without writing files, but returns the list of files that would be created.
archive (bool) – If True, materializes all symlinks by copying referenced data (may be time and space intensive).
id (str | None) – Optional identifier. Mutually exclusive with target.

Return type:

list[Path]

Returns:

List of Paths to saved files (including meshes, project, and execution configuration).

run(target=None, overwrite=None, id=None)[source]#

Run a simulation to completion and wait for it to finish.

This is a convenience method that starts the simulation and blocks until it completes. For stepwise control, use start() instead.

Parameters:

target (Path | str | None) – Optional path for the resulting Simulation. If None, uses a default location.
overwrite (bool | None) – If True, overwrite existing output directory.
id (str | None) – Optional identifier for the resulting Simulation.

Return type:

ogstools.Simulation

Returns:

A ogstools.Simulation object containing the completed simulation results and metadata.

controller(sim_output=None, dry_run=False, overwrite=None)[source]#

Start a simulation and return a controller for execution management.

The type of controller returned depends on the execution configuration:

OGSInteractiveController: Allows stepwise control (execute_time_step, inspect intermediate results) when execution.interactive is True
OGSNativeController: Runs to completion when execution.interactive is False

Parameters:

sim_output (Path | str | None) – Optional path where simulation should be written. If None, uses a default location.
dry_run (bool) – If True, prints the command that would be executed but does not actually run the simulation.

Return type:

SimulationController

Returns:

A SimulationController for managing the simulation.

property cmd: str#: Get the full OGS command (without output path).

plot_constraints(**kwargs)[source]#

Plot the meshes with annotated boundary conditions and source terms.

keyword arguments: see contourf()

Return type:: Figure