src.basement_tools module

BASEMENT interface module for simulation management.

This module provides the SimulationManager class which handles:

• Simulation setup and execution via BASEMENT software

• Results processing and data extraction

• Friction and discharge parameter management

Example

>>> from src.basement_tools import SimulationManager
>>> manager = SimulationManager(sim_folder='simulation/', run_parameters={})
>>> manager.run_simulation()

class src.basement_tools.SimulationManager(sim_folder: str, run_parameters: dict, logger: Logger | None = None, silent: bool = False, log_dev: bool = False)

Bases: object

A class to manage simulation setup, execution, data extraction, and friction definition.

sim_folder

Path to the simulation folder.

Type:

str

run_parameters

Simulation run parameters.

Type:

dict

logger

Logger instance for tracking operations.

Type:

logging.Logger

basement_path

Path to BASEMENT installation.

Type:

str

_get_save_freq() → int

Get the saving frequency from the simulation configuration.

Returns:

The saving frequency in seconds.

Return type:

int

_load_model_config() → dict[str, Any]

Load the model configuration from the JSON file.

Returns:

The model configuration dictionary.

Return type:

dict

_validate_paths(paths: list[str], error_message: str | None = None, raise_error: bool = True) → bool

Validate the existence of required file paths.

Parameters:

• paths – List of file paths to validate.

• error_message – Custom error message if validation fails.

• raise_error – Whether to raise an error if validation fails.

Returns:

True if all paths are valid, False otherwise.

Return type:

bool

Raises:

FileNotFoundError – If a path does not exist and raise_error is True.

define_discharge(new_discharge: float, file: bool = False) → None

Define or update the discharge boundary condition.

Parameters:

• new_discharge – The new discharge value or file path.

• file – If True, new_discharge is treated as a file path (default: False).

define_friction(mesh_filepath: dict[str, str], friction: ndarray = array([], dtype=float64), target_region: list | None = None, read_model_friction: bool = False, define_in_h5: bool = False) → ndarray

Define or update friction values for the simulation based on mesh regions.

Parameters:

• mesh_filepath – Dictionary mapping mesh file names to their file paths.

• friction – Existing friction array if updating (default: None).

• target_region – List of region names to update (default: None).

• read_model_friction – If True, return model friction without applying (default: False).

• define_in_h5 – If True, update friction values in the HDF5 file (default: False).

Returns:

Updated or initialized friction array.

Return type:

np.ndarray

Raises:

Exception – For errors during file reading, processing, or saving data.

extract_sim_data(centroids_dict: dict, sim_time: int = -1) → dict[str, Any]

Extract calibration data from a simulation folder.

The results are stored in an HDF5 file under the following structure:

results.h5
└── RESULTS
    └── CellsAll
        └── Saving times
            └── Results array (wse, ux, uy)

Water surface elevation (wse) is stored in the first column. To calculate water depth, subtract bed elevation from wse. Bed elevation is located in:

results.h5
└── CellsAll
    └── BottomEl

Parameters:

• centroids_dict – Dictionary containing mesh centroids indexed by mesh name.

• sim_time – Simulation time to extract data from. Default is -1 (last timestep).

Returns:

Dictionary containing extracted simulation data with keys:

• time: Simulation time in seconds

• centroids: Cell centroids array

• hyd: Hydrodynamic data (wse, qx, qy, h, ux, uy)

• rey: Reynolds state data

• trb: Turbulence state data

• turb_k: Turbulent kinetic energy

• turb_rey: Turbulent Reynolds stress

Return type:

dict

Raises:

• FileNotFoundError – If results file is not found.

• ValueError – If specified simulation time not found in data.

get_computational_mesh_name() → str

Get the name of the computational mesh file.

Reads the model configuration and extracts the mesh filename.

Returns:

The basename of the mesh file, or empty string if not found.

Return type:

str

load_simulation_setup() → dict[str, Any]

Load the simulation setup from the simulation folder.

Reads the setup.h5 file and extracts mesh name and friction data.

Returns:

Dictionary containing mesh_name and friction array.

Return type:

dict

run_results_processing(run_parameters: dict[str, Any] | None = None) → None

Process simulation results using the BASEMENT software.

Parameters:

run_parameters – Dictionary of simulation parameters (optional).

Raises:

• FileNotFoundError – If required files are missing.

• Exception – If results processing fails.

run_setup(run_parameters: dict[str, Any] | None = None) → None

Process the simulation setup using BASEMENT software.

Parameters:

run_parameters – Dictionary of simulation parameters (optional).

Raises:

• FileNotFoundError – If required files are missing.

• Exception – If setup processing fails.

run_simulation(run_parameters: dict[str, Any] | None = None) → int | None

Execute a simulation using the BASEMENT software.

Parameters:

run_parameters – Dictionary of simulation parameters (optional).

Raises:

• FileNotFoundError – If required files are missing.

• Exception – If simulation fails.