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.
cstar.roms.ROMSSimulation.run#
- ROMSSimulation.run(account_key: str | None = None, walltime: str | None = None, queue_name: str | None = None, job_name: str | None = None) ExecutionHandler#
Execute the ROMS simulation.
This method runs the compiled ROMS executable using the configured environment. If a job scheduler is available, the simulation is submitted as a scheduled job; otherwise, it runs as a local process.
- Parameters:
account_key (str, optional) – The user’s account key on the system (required if using a job scheduler).
queue_name (str, optional) – The name of the scheduler queue to submit the job to. Defaults to the system’s primary queue.
walltime (str, optional) – The maximum allowed execution time for a scheduler job in HH:MM:SS format. Defaults to the queue’s max walltime if a scheduler is used.
job_name (str, optional) – The name of the job submitted to the scheduler, which also sets the output file name job_name.out.
- Returns:
ExecutionHandler – An execution handler object tracking the simulation’s execution status, logs, and completion.
- Raises:
ValueError –
If the ROMS executable path is not set (self.exe_path is None). - If account_key is required but not provided for scheduled jobs.
RuntimeError – If ROMS fails to start or encounters an execution error.
Notes
If a job scheduler is available, this method generates a job script and submits it using the appropriate scheduler command.
If no scheduler is available, ROMS runs as a local process using MPI (mpiexec or equivalent).
The number of time steps is computed based on start_date and end_date if they are set; otherwise, a default of 1 time step is used.
Examples
Running locally: >>> execution = simulation.run() >>> execution.status ‘RUNNING’
Running with a scheduler: >>> execution = simulation.run(account_key=”ABC123”, job_name=”roms_simulation”) >>> execution.status ‘QUEUED’