ogstools.core.interactive_simulation_controller module#

exception ogstools.core.interactive_simulation_controller.OGSSimulationInitializationError[source]#

Bases: Exception

Exception raised when OGSSimulation initialization fails.

This can occur when: - OGSSimulation returns None (initialization failed) - Multiple OGSSimulation instances are created in parallel (Issue #3589)

class ogstools.core.interactive_simulation_controller.OGSInteractiveController[source]#

Bases: SimulationController

Controller for interactive stepwise execution of OGS simulations.

Allows fine-grained control over simulation execution including: - Executing individual time steps - Inspecting intermediate mesh states - Querying current simulation time - Pausing and resuming execution

Requires OGS to be built with interactive mode support.

Initialize an interactive simulation controller.

Parameters:

model_ref (ogstools.Model) – The ogstools.Model to simulate.
sim_output (Path | str | None) – Optional path for simulation output directory.
overwrite (bool | None) – If True, overwrite existing output directory.

__init__(model_ref, sim_output=None, overwrite=None)[source]#

Initialize an interactive simulation controller.

Parameters:

model_ref (ogstools.Model) – The ogstools.Model to simulate.
sim_output (Path | str | None) – Optional path for simulation output directory.
overwrite (bool | None) – If True, overwrite existing output directory.

property status: SimulationStatus#: Get the current simulation status.

terminate()[source]#

Terminate the simulation immediately.

Closes the OGS simulator and stops log capture if active.

Return type:: bool
Returns:: True if termination was successful.

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

Run the simulation to completion.

Executes time steps until the simulation reaches end_time or encounters an error. After completion, closes the simulator and returns a Simulation object.

Parameters:

target (Path | str | None) – Optional path for the simulation output directory.
id (str | None) – Optional identifier for the resulting Simulation.

Return type:

ogstools.Simulation

Returns:

A ogstools.Simulation object containing the completed simulation.

property current_time: float#

Get the current model time.

Returns:: Current time value in s.

property end_time: float#

Get the configured model end time.

Returns:: End time value in s.

execute_time_step()[source]#

Execute a single time step of the simulation.

Advances the simulation by one time step and updates the status.

Return type:: SimulationStatus
Returns:: The updated SimulationStatus after executing the time step.

mesh(name, variables=None)[source]#

Retrieve the current mesh state during simulation.

Parameters:

name (str) – Name of the mesh to retrieve.
variables (Sequence[str] | None) – Optional list of variable names to include. If None, includes all variables.

Return type:

UnstructuredGrid

Returns:

UnstructuredGrid containing the mesh and data.

status_str()[source]#

Get a human-readable status description.

Return type:: str
Returns:: String describing the current simulation state and runtime.