Attention

This project is still in an early phase of development.

The python API is not yet stable, and some aspects of the schema for the blueprint and workplan will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.

ROMSSimulation

class cstar.roms.ROMSSimulation(name: str, directory: str | Path, discretization: ROMSDiscretization, runtime_code: AdditionalCode, compile_time_code: AdditionalCode | None = None, codebase: ROMSExternalCodeBase | None = None, start_date: str | datetime | None = None, end_date: str | datetime | None = None, valid_start_date: str | datetime | None = None, valid_end_date: str | datetime | None = None, marbl_codebase: MARBLExternalCodeBase | None = None, model_grid: ROMSModelGrid | None = None, initial_conditions: ROMSInitialConditions | None = None, tidal_forcing: ROMSTidalForcing | None = None, river_forcing: ROMSRiverForcing | None = None, cdr_forcing: ROMSCdrForcing | None = None, nesting_info: ROMSNestingInfo | None = None, boundary_forcing: list[ROMSBoundaryForcing] | None = None, surface_forcing: list[ROMSSurfaceForcing] | None = None, forcing_corrections: list[ROMSForcingCorrections] | None = None)

Bases: Simulation

A specialized Simulation subclass for configuring and running ROMS (Regional Ocean Modeling System) simulations.

This class extends Simulation to provide ROMS-specific functionality, including managing model grids, forcing files, and discretization parameters. It also facilitates the setup, execution, and post-processing of ROMS simulations.

name

The name of this simulation.

Type:

str

directory

The local directory in which this simulation will be prepared and executed.

Type:

Path

start_date

The starting date of the simulation.

Type:

str or datetime

end_date

The ending date of the simulation.

Type:

str or datetime

valid_start_date

The earliest allowed start date, based on, e.g. the availability of input data.

Type:

str or datetime

valid_end_date

The latest allowed end date, based on, e.g., the availability of input data.

Type:

str or datetime

codebase

The repository containing the base source code for this simulation.

Type:

ExternalCodeBase

marbl_codebase

The repository containing the base source code for MARBL (Marine Biogeochemistry Library).

Type:

MARBLExternalCodeBase

runtime_code

Additional code needed by ROMS at runtime (e.g. a .in file)

Type:

AdditionalCode

roms_runtime_settings

A structured representation of the .in file found in runtime_code, available after the code has been fetched with ROMSSimulation.runtime_code.get() or ROMSSimulation.setup()

Type:

ROMSRuntimeSettings

compile_time_code

Additional ROMS source code to be included at compile time (e.g. .opt files)

Type:

AdditionalCode

model_grid

The model grid used in the simulation.

Type:

ROMSModelGrid

initial_conditions

Initial conditions for the simulation.

Type:

ROMSInitialConditions

tidal_forcing

Tidal forcing data used in the simulation.

Type:

ROMSTidalForcing

river_forcing

River inflow data specifying locations and fluxes.

Type:

ROMSRiverForcing

surface_forcing

List of surface forcing datasets.

Type:

list[ROMSSurfaceForcing]

boundary_forcing

List of boundary forcing datasets.

Type:

list[ROMSBoundaryForcing]

forcing_corrections

List of forcing correction datasets.

Type:

list[ROMSForcingCorrections]

exe_path

Path to the compiled ROMS executable.

Type:

Path

partitioned_files

Paths to partitioned input files for distributed ROMS runs.

Type:

List[Path]

input_datasets

A flat list of all input datasets attached to this simulation.

Type:

list[ROMSInputDataset]

codebases

List of all external codebases in use (e.g., ROMS, MARBL).

Type:

list

is_setup

True if all required components have been retrieved and configured locally.

Type:

bool

setup()

Configures and prepares the ROMS simulation environment.

build(rebuild=False)

Compiles the ROMS executable if necessary.

pre_run()

Performs pre-processing steps before execution.

run(account_key=None, walltime=None, queue_name=None, job_name=None)

Submits the ROMS simulation for execution.

post_run()

Processes model outputs after execution.

restart(new_end_date)

Creates a new ROMS simulation instance from a restart file.

See also

Simulation

Base class providing general simulation functionalities.

Methods

ROMSSimulation.build([rebuild])	Compile the ROMS executable from source code.
ROMSSimulation.from_blueprint(blueprint)	Create a ROMSSimulation instance from a YAML blueprint.
ROMSSimulation.from_dict(simulation_dict, ...)	Create a ROMSSimulation instance from a dictionary representation.
ROMSSimulation.persist()	Save the current state of the simulation to a file.
ROMSSimulation.post_run()	Perform post-processing steps after the ROMS simulation run.
ROMSSimulation.pre_run([...])	Perform pre-processing steps needed to run the ROMS simulation.
ROMSSimulation.restart(new_end_date)	Restart the ROMS simulation from the end of the current simulation, if possible.
ROMSSimulation.restore(directory)	Restore a previously saved simulation state.
ROMSSimulation.run([account_key, walltime, ...])	Execute the ROMS simulation.
ROMSSimulation.setup()	Prepare this ROMSSimulation locally by fetching necessary files and compiling any external codebases.
ROMSSimulation.state_file_from(directory)	The path where a state file containing a pickled Simulation will be created upon successful completion of a simulation, when that simulation uses the supplied directory as it's working directory.
ROMSSimulation.to_dict()	Convert the ROMSSimulation instance into a dictionary representation.
ROMSSimulation.tree()	Display a tree-style representation of the ROMS simulation structure.

Attributes

ROMSSimulation.T
ROMSSimulation.codebases	Returns a list of external codebases associated with this ROMS simulation.
ROMSSimulation.default_codebase	Returns the default ROMS external codebase.
ROMSSimulation.fs_manager	Return the file system manager for the simulation.
ROMSSimulation.input_datasets	Retrieves all input datasets associated with this ROMS simulation.
ROMSSimulation.is_setup	Check whether the ROMSSimulation is fully configured locally.
ROMSSimulation.log	Return the logger instance for this class.
ROMSSimulation.roms_runtime_settings	Generate and return a ROMSRuntimeSettings object for the simulation.
ROMSSimulation.state_file	The path where a state file containing the pickled Simulation will be created upon successful completion of the simulation.
ROMSSimulation.discretization
ROMSSimulation.runtime_code