Bamboost
bamboost/core/simulation/base

bamboost.core.simulation.base

Source: https://gitlab.com/cmbm-ethz/bamboost/-/blob/next/bamboost/core/simulation/base.py

Simulation management module for bamboost.

This module provides classes and utilities for managing simulations, including reading and writing simulation data, handling metadata and parameters, interfacing with HDF5 files, managing simulation status, and supporting HPC job submission and MPI parallelism.

Attributes

  • log=BAMBOOST_LOGGER.getChild('simulation')

Classes

Status

Enum representing the status of a simulation.

Attributes:
  • INITIALIZED='initialized'

    The simulation has been initialized but not yet started.

  • STARTED='started'

    The simulation is currently running.

  • FINISHED='finished'

    The simulation has completed successfully.

  • FAILED='failed'

    The simulation has failed.

  • UNKNOWN='unknown'

    The status of the simulation is unknown.

Status.format(self) -> str

Return the string representation of the status.

StatusInfo

StatusInfo(self, status, message=None) -> None

Detailed status information for a simulation.

Arguments:
  • status:Status
  • message:typing.Optional[str]=None
Attributes:
  • status:Status

    The current status of the simulation.

  • message:typing.Optional[str]=None

    An optional message providing additional details about the status.

StatusInfo.parse(cls, status) -> StatusInfo
Arguments:
  • cls
  • status:str
StatusInfo.format(self) -> str

SimulationName

Utility class for generating unique simulation names.

The SimulationName class provides a convenient way to generate or validate unique names for simulation runs. If no name is provided, a random unique identifier is generated using UUID, truncated to the specified length.

Examples:
>>> sim_name = SimulationName()  # Generates a unique name of length 10
>>> sim_name = SimulationName("my_simulation")
>>> print(sim_name)
my_simulation

Note

The generated name is guaranteed to be unique across MPI ranks by broadcasting the generated UUID from the root rank.

SimulationName.__new__(cls, name=None, length=10)
Arguments:
  • cls
  • name:typing.Optional[str]=None
  • length:int=10
SimulationName.generate_name(length) -> str
Arguments:
  • length:int

_Simulation

_Simulation(self, name, parent, comm=None, index=None, **kwargs)

Abstract base class for simulation objects.

This class should not be instantiated directly. Use Simulation for read-only access or SimulationWriter for writable access to simulation data.

Arguments:
  • name:str
  • parent:StrPath
  • comm:typing.Optional[Comm]=None
  • index:typing.Optional[Index]=None
  • kwargs={}
Attributes:
  • name:str=bamboost.core.simulation.base._Simulation(name)
  • path:pathlib.Path=Path(parent).joinpath(name).absolute()
  • _psize:int=bamboost.core.simulation.base._Simulation(self).bamboost.core.simulation.base._Simulation(self)._comm.bamboost.core.simulation.base._Simulation(self)._comm.size
  • _prank:int=bamboost.core.simulation.base._Simulation(self).bamboost.core.simulation.base._Simulation(self)._comm.bamboost.core.simulation.base._Simulation(self)._comm.rank
  • _ranks=np.array([i for i in range(self._psize)])
  • _index:Index=bamboost.core.simulation.base._Simulation(index) or bamboost.index.Index(comm=bamboost.core.simulation.base._Simulation(self).bamboost.core.simulation.base._Simulation(self)._comm)
  • collection_uid:CollectionUID=bamboost.core.simulation.base._Simulation(kwargs).bamboost.core.simulation.base._Simulation(kwargs).pop('collection_uid', None) or bamboost.core.simulation.base._Simulation(self).bamboost.core.simulation.base._Simulation(self)._index.bamboost.core.simulation.base._Simulation(self)._index.resolve_uid(bamboost.core.simulation.base._Simulation(self).bamboost.core.simulation.base._Simulation(self).path.bamboost.core.simulation.base._Simulation(self).path.parent)
  • _data_file:pathlib.Path=self.path.joinpath(constants.HDF_DATA_FILE_NAME)
  • _xdmf_file:pathlib.Path=self.path.joinpath(constants.XDMF_FILE_NAME)
  • _bash_file:pathlib.Path=self.path.joinpath(constants.RUN_FILE_NAME)
  • root:Group[bamboost._typing._MT]
  • mutable:bool
  • _orm:SimulationORM
  • uid:str

    Returns the full unique identifier (UID) of the simulation.

    The UID is constructed as "<collection_uid>:<simulation_name>", where collection_uid is the unique identifier of the collection containing the simulation, and simulation_name is the name of the simulation.

  • parameters:Parameters[bamboost._typing._MT]

    Returns the parameters associated with this simulation.

  • metadata:Metadata[bamboost._typing._MT]

    Returns the metadata associated with this simulation.

  • status:StatusInfo

    Returns the current status of the simulation.

  • created_at:datetime.datetime

    Returns the creation timestamp of the simulation.

  • description:str

    Returns the description of the simulation.

  • links:Links[bamboost._typing._MT]

    Returns the links associated with this simulation.

  • files

    Returns a file picker utility for the simulation directory.

  • git:GroupGit[bamboost._typing._MT]

    Returns the Git group associated with this simulation.

  • data:Series[bamboost._typing._MT]

    Returns the default data series for this simulation.

  • meshes:GroupMeshes[bamboost._typing._MT]
  • mesh:GroupMesh
_Simulation.__eq__(self, other) -> bool
Arguments:
_Simulation.from_uid(cls, uid, **kwargs) -> Self

Return the Simulation instance corresponding to the given UID.

Arguments:
  • cls
  • uid:str

    The full simulation UID in the format "<collection_uid>:<simulation_name>".

  • kwargs={}
Returns
typing_extensions.SelfAn instance of the simulation class corresponding to the UID.
Examples:
>>> sim = Simulation.from_uid("abc123:mysim")
_Simulation.edit(self) -> SimulationWriter

Return a mutable SimulationWriter object for editing the simulation.

This method provides an interface to obtain a mutable version of the current simulation, allowing modifications to simulation data, metadata, and parameters.

Returns
SimulationWriterAn object with write access to the simulation.
Examples:
>>> with sim.edit() as sim_writer:
...     sim_writer.parameters["new_param"] = 42
_Simulation.update_database(self, *, metadata=None, parameters=None) -> None

Push update to sqlite database.

Arguments:
  • metadata:typing.Optional[typing.Mapping]=None

    metadata dictionary to insert

  • parameters:typing.Optional[typing.Mapping]=None

    parameter dictionary to insert

_Simulation.open_in_paraview(self) -> None

Open the xdmf file in paraview.

_Simulation.enter_path(self)

A context manager for changing the working directory to this simulations' path.

>>> with sim.working_directory():
>>>     ...
_Simulation.require_series(self, path) -> Series[_MT]

Return a Series object for the given path.

A "series" in bamboost is a logical group in the HDF5 file that stores time-dependent or indexed simulation data, such as fields, scalars, or other arrays. Each series is identified by its path and can contain multiple fields and steps.

Arguments:
  • path:str

    Path to the series group within the simulation HDF5 file.

Returns
Series[bamboost._typing._MT]Series[_MT]: The Series object for the specified path.
_Simulation.create_xdmf(self, field_names=None, timesteps=None, *, series=None, filename=None, mesh_name=constants.DEFAULT_MESH_NAME)

Generate an XDMF file for visualization of simulation data.

This method creates an XDMF file that references the simulation's mesh and time-dependent field data, enabling visualization in tools such as ParaView.

Arguments:
  • field_names:typing.Optional[typing.Iterable[str]]=None

    Names of the fields to include in the XDMF file. If None, all available fields in the series are included.

  • timesteps:typing.Optional[typing.Iterable[float]]=None

    List of timesteps to include. If None, all timesteps in the series are included.

  • series:typing.Optional[Series[bamboost._typing._MT]]=None

    The data series to use for field and timestep information. If None, uses the default data series (self.data).

  • filename:typing.Optional[StrPath]=None

    Path to the output XDMF file. If None, defaults to "<simulation_path>/data.xdmf".

  • mesh_name:str=bamboost.constants.bamboost.constants.DEFAULT_MESH_NAME

    Name of the mesh to reference in the XDMF file. Defaults to the constant DEFAULT_MESH_NAME.

Examples:
>>> sim.create_xdmf(field_names=["velocity", "pressure"])
>>> sim.create_xdmf(timesteps=[0.0, 0.1, 0.2], filename="custom.xdmf")
_Simulation._repr_html_(self)

Simulation

Simulation(self, name, parent, comm=None, index=None, **kwargs)

Read-only simulation object.

The Simulation class provides read-only access to simulation data, metadata, and parameters. It is intended for inspecting and analyzing existing simulations without modifying their contents. For editing or managing simulations, use SimulationWriter (or sim_writer = sim.edit()).

Arguments:
  • name:str
  • parent:StrPath
  • comm:typing.Optional[Comm]=None
  • index:typing.Optional[Index]=None
  • kwargs={}
Attributes:
  • _file:HDF5File[bamboost._typing.Immutable]=HDF5File(self._data_file, comm=self._comm, mutable=False)
Examples:
>>> sim = Simulation("mysim", "/path/to/collection")
>>> print(sim.parameters)
>>> print(sim.metadata)
Bases
ElligibleForPlugin1
H5Object4
_Simulation34

SimulationWriter

SimulationWriter(self, name, parent, comm=None, index=None, **kwargs)

Mutable simulation object for editing and managing simulations.

The SimulationWriter class provides write access to simulation data, metadata, and parameters. It is intended for creating, editing, and managing simulations. Use this class when you need to modify the contents of a simulation, such as updating parameters, metadata, or simulation data.

Arguments:
  • name:str
  • parent:StrPath
  • comm:typing.Optional[Comm]=None
  • index:typing.Optional[Index]=None
  • kwargs={}
Attributes:
  • _file:HDF5File[bamboost._typing.Mutable]=HDF5File(self._data_file, comm=self._comm, mutable=True)
Examples:
>>> with SimulationWriter("mysim", "/path/to/collection") as sim_writer:
...     sim_writer.parameters["new_param"] = 42
...     sim_writer.metadata["description"] = "Updated simulation"
SimulationWriter.__exit__(self, exc_type, exc_val, exc_tb)
Arguments:
  • exc_type
  • exc_val
  • exc_tb
SimulationWriter.__enter__(self) -> SimulationWriter
SimulationWriter.initialize(self) -> None

Initialize the simulation.

This method sets up the simulation's HDF5 data file and required groups, and records initial metadata such as status and creation time.

SimulationWriter.status(self, value) -> None
Arguments:
  • value:typing.Union[StatusInfo, bamboost.core.simulation.base.Status]
SimulationWriter.description(self, value) -> None
Arguments:
  • value:str
SimulationWriter.require_series(self, path) -> Series[Mutable]
Arguments:
  • path:str
SimulationWriter.copy_files(self, files) -> None

Copy files to the simulation folder.

Arguments:
  • files:typing.Iterable[StrPath]

    list of files/directories to copy

SimulationWriter.create_run_script(self, commands, euler=False, sbatch_kwargs=None) -> None

Create a batch job and put it into the folder.

Arguments:
  • commands:list[str]

    A list of strings being the user defined commands to run

  • euler:bool=False

    If false, a local bash script will be written

  • sbatch_kwargs:typing.Optional[[str, typing.Any]]=None

    Additional sbatch arguments. This parameter allows you to provide additional arguments to the sbatch command when submitting jobs to a Slurm workload manager. The arguments should be provided in the format of a dict of sbatch option name and values.

    Use this parameter to specify various job submission options such as the number of tasks, CPU cores, memory requirements, email notifications, and other sbatch options that are not covered by default settings. By default, the following sbatch options are set:

    • --output: The output file is set to <uid>.out.
    • --job-name: The job name is set to <full_uid>.

    The following arguments should bring you far:

    • --ntasks: The number of tasks to run. This is the number of MPI processes to start.
    • --mem-per-cpu: The memory required per CPU core.
    • --time: The maximum time the job is allowed to run.
    • --tmp: Temporary scratch space to use for the job.
SimulationWriter.run_simulation(self, executable='bash') -> None

Run the simulation using the specified executable and the default run file in the simulation directory.

This method executes the simulation's run script using the provided executable. By default, it uses "bash" to run the script locally. If "sbatch" is specified, the script will be submitted to a Slurm workload manager.

Arguments:
  • executable:str='bash'

    The executable to use for running the simulation script. Defaults to "bash". Use "sbatch" to submit to a Slurm scheduler.

Examples:
>>> sim_writer.run_simulation()  # Runs locally with bash
>>> sim_writer.run_simulation(executable="sbatch")  # Submits to Slurm
SimulationWriter.submit_simulation(self) -> None

Submit the simulation to a job scheduler.

This method submits the simulation's run script to a job scheduler using "sbatch". It is a convenience wrapper around run_simulation(executable="sbatch").

Examples:
>>> sim_writer.submit_simulation()
SimulationWriter._initialize_series(self, path) -> None

Create the groups for a series. Does not manage file state.

Arguments:
  • path:str

    path of the series

simulation

Previous Page

dict

Next Page

On this page

Attributes
Classes
Status
format
StatusInfo
parse
format
SimulationName
__new__
generate_name
_Simulation
__eq__
from_uid
edit
update_database
open_in_paraview
enter_path
require_series
create_xdmf
_repr_html_
Simulation
SimulationWriter
__exit__
__enter__
initialize
status
description
require_series
copy_files
create_run_script
run_simulation
submit_simulation
_initialize_series