ogstools.core.execution module#

class ogstools.core.execution.Execution[source]#

Bases: StorageBase

Configuration for OGS simulation execution parameters.

This class encapsulates all settings related to how an OGS simulation is executed, including parallelization, containerization, and logging options.

OGS binary / container selection

The ogs_path parameter accepts either:

  • A directory containing the OGS executable ("/path/to/bin").

  • A container image path or URL (.sif / .squashfs), in which case OGS is run inside the container as ogs.

Use pre-built container image URLs:

Execution(ogs_path=Execution.CONTAINER_PARALLEL_V6_5_7)

When ogs is not set, the executable is looked up via OGS_BIN_PATH and, if not defined, on PATH.

Site-wide defaults via OGS_EXECUTION_DEFAULTS

Point the environment variable to a YAML file (e.g. in .envrc, activate, or .bashrc) to set site-wide defaults:

export OGS_EXECUTION_DEFAULTS=/path/to/my_execution_defaults.yaml

A typical cluster defaults file:

ogs_path:    "/scratch/containers/ogs-6.5.7-petsc.squashfs"
mpi_wrapper: "srun --ntasks"
write_logs:  true

A typical developer defaults file:

ogs_path: "ogs/build/release/bin"

Initialize an Execution configuration.

Parameters:

  • interactive (bool) – If True, use interactive mode for stepwise control.

  • args (str | None) – Extra OGS command-line flags appended verbatim (see ogs --help for the full list). Useful flags: Example: "--write-prj --log-parallel".

  • mpi_wrapper (str | None) – MPI launcher prefix, e.g. "mpirun -np", "mpiexec -n", "srun --ntasks".

  • wrapper (str | None) – Generic command prefix prepended before the full command, e.g. "valgrind", "perf stat".

  • ogs_path (str | None) – Directory containing the OGS executable, or a container image path/URL (.sif / .squashfs). When not set, looked up via OGS_BIN_PATH or PATH.

  • mpi_ranks (int | None) – Number of MPI ranks. None = serial run.

  • omp_num_threads (int | None) – OpenMP threads per MPI rank. None = let OGS decide. See OpenMP parallelization.

  • ogs_asm_threads (int | None) –

    OGS assembly threads. None = let OGS decide. See OpenMP parallelization.

  • write_logs (bool) – If True, write OGS log output to a file.

  • log_level (str | None) – OGS log verbosity: none|error|warn|info|debug|all. None omits the -l flag (OGS default is info).

  • id (str | None) – Optional unique identifier for this execution config.

default: Execution#
CONTAINER_SERIAL = 'https://vip.s3.ufz.de/ogs/public/binaries/ogs6/6.5.7/ogs-6.5.7-serial.squashfs'#
CONTAINER_PARALLEL = 'https://vip.s3.ufz.de/ogs/public/binaries/ogs6/6.5.7/ogs-6.5.7-petsc.squashfs'#

Default Execution instance, created at import time via auto-detection.

Use this to inspect or share the default execution configuration without creating a new object each time.

Users can override the default for the entire session:

Execution.default = Execution(ogs_path="/path/to/bin")
__init__(interactive=False, args=None, mpi_wrapper='mpirun -np', wrapper=None, ogs_path=None, mpi_ranks=None, omp_num_threads=None, ogs_asm_threads=None, write_logs=True, log_level=None, id=None)[source]#

Initialize an Execution configuration.

Parameters:

  • interactive (bool) – If True, use interactive mode for stepwise control.

  • args (str | None) – Extra OGS command-line flags appended verbatim (see ogs --help for the full list). Useful flags: Example: "--write-prj --log-parallel".

  • mpi_wrapper (str | None) – MPI launcher prefix, e.g. "mpirun -np", "mpiexec -n", "srun --ntasks".

  • wrapper (str | None) – Generic command prefix prepended before the full command, e.g. "valgrind", "perf stat".

  • ogs_path (str | None) – Directory containing the OGS executable, or a container image path/URL (.sif / .squashfs). When not set, looked up via OGS_BIN_PATH or PATH.

  • mpi_ranks (int | None) – Number of MPI ranks. None = serial run.

  • omp_num_threads (int | None) –

    OpenMP threads per MPI rank. None = let OGS decide. See OpenMP parallelization.

  • ogs_asm_threads (int | None) –

    OGS assembly threads. None = let OGS decide. See OpenMP parallelization.

  • write_logs (bool) – If True, write OGS log output to a file.

  • log_level (str | None) – OGS log verbosity: none|error|warn|info|debug|all. None omits the -l flag (OGS default is info).

  • id (str | None) – Optional unique identifier for this execution config.

classmethod from_file(filepath)[source]#

Restore an Execution object from an execution.yaml file.

Parameters:

filepath (Path | str) – Path to execution.yaml file.

Return type:

Self

Returns:

Restored Execution instance.

Raises:

FileNotFoundError – If the specified file does not exist.

classmethod from_id(execution_id)[source]#

Load Execution from the user storage path using its ID. StorageBase.Userpath must be set.

Parameters:

execution_id (str) – The unique ID of the Execution to load.

Return type:

Self

Returns:

An Execution instance restored from disk.

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

list[Path]

property env: dict[str, str]#

Process environment for OGS subprocess, with OMP/ASM thread vars injected.

property container_path: str | None#

Container reference for the active run, or None for native execution.

property container_prefix: str | None#

Container launch prefix, e.g. ‘apptainer exec /path/to.sif’, or None.

property cmd: str#

OGS invocation command without project file and meshes path.

classmethod from_default(file=None)[source]#

Create the default Execution instance.

If OGS_EXECUTION_DEFAULTS is set, load settings from that file and construct with those values. Otherwise use the empty constructor.

Return type:

Self