ogstools.core.simulation_controller module#

class ogstools.core.simulation_controller.SimulationStatus[source]#

Bases: Enum

Enumeration of possible simulation states.

Attributes:

not_started: Simulation has not been started yet. running: Simulation is currently executing. paused: Simulation is paused (interactive mode only). done: Simulation completed successfully. error: Simulation terminated with an error.

not_started = 0#
running = 1#
paused = 2#
done = 3#
error = 4#
unknown = 5#
class ogstools.core.simulation_controller.SimulationController[source]#

Bases: ABC

Abstract base class for controlling OGS simulation execution.

Provides a unified interface for running simulations, whether in interactive stepwise mode or batch mode. Handles signal interruption (SIGINT, SIGTERM) and manages simulation status.

Concrete implementations: - OGSInteractiveController: For stepwise execution control - OGSNativeController: For batch execution

Initialize a SimulationController.

Parameters:

  • model_ref (ogstools.Model) – The ogstools.Model to simulate.

  • sim_output (Path | str | None) – Optional path for simulation output directory. If None, uses a default location.

  • overwrite (bool | None) – If True, overwrite existing output directory.

Status#

alias of SimulationStatus

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

Initialize a SimulationController.

Parameters:

  • model_ref (ogstools.Model) – The ogstools.Model to simulate.

  • sim_output (Path | str | None) – Optional path for simulation output directory. If None, uses a default location.

  • overwrite (bool | None) – If True, overwrite existing output directory.

property is_interrupted: bool#

Check if an interrupt signal was received and reset the flag.

Returns:

True if SIGINT or SIGTERM was received, False otherwise.

abstractmethod terminate()[source]#

Terminate the simulation immediately.

Return type:

bool

Returns:

True if termination was successful, False otherwise.

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

Run the simulation to completion.

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.

abstract property status: SimulationStatus#

Get the current simulation status.

Returns:

Current SimulationStatus.

abstractmethod status_str()[source]#

Get a human-readable status string.

Return type:

str

Returns:

String describing the current simulation state.

property log_file: Path#

Get the path to the log file.

plot_log(log_data='step_start_time', time_y_axis_type='linear', time_window_length=0, iteration_window_length=0, update_interval=2.0, notebook=False)[source]#

Open the interactive Bokeh monitoring dashboard for this simulation.

By default this launches the same dashboard as the ogsmonitor command line tool, in a real browser tab, which renders reliably across notebook environments (plain Jupyter, JupyterLab, VS Code’s Jupyter extension, …). Pass notebook=True to instead embed the plot directly in the notebook cell’s output.

Parameters:

  • log_data (str | list[list[str]]) – Plot type. Can be a single string or a list of list of strings. E.g., [[‘step_start_time’, ‘step_size’], [‘assembly_time’, ‘linear_solver_time’]]

  • time_y_axis_type (str) – Type of the y-axis (‘linear’ or ‘log’) for simulation time-based data.

  • time_window_length (int) – Length of the time window (number of timesteps) for the plot. 0 Plots the whole log file.

  • iteration_window_length (int) – Length of the iteration window (number of iterations) for the plot. 0 Plots the whole log file.

  • update_interval (float) – Interval in seconds between plot updates.

  • notebook (bool) –

    If True, embed the plot in the notebook cell via Bokeh’s push_notebook() instead of opening a browser tab. A background thread redraws it every update_interval seconds until the simulation ends or terminate() is called; the call itself returns immediately.

    Warning

    Bokeh’s push_notebook() live updates do not work in VS Code’s Jupyter extension: this is an unresolved upstream limitation (bokeh/jupyter_bokeh#199), not something ogstools can work around. The plot draws once but never animates there. It works correctly in classic Jupyter and JupyterLab. In VS Code, use the default notebook=False (browser tab) instead.

Return type:

Popen | None

Returns:

The running Bokeh server subprocess when notebook=False. It is also closed by terminate(); call .terminate() on it directly for earlier, standalone control. Returns None when notebook=True — use terminate() to stop it early.

property meshseries_file: Path#

Get the path to the mesh series file.

property cmd: str#

Get the full command used to run the simulation.

error_report()[source]#

Generate an error report if the simulation failed.

Includes the last lines of the log file if available.

Return type:

str

Returns:

A formatted error report string.