Skip to content

Quickstart Guide

This guide will help you get up and running with Rompy quickly. For more detailed information, check out our User Guide.

Installation

Install from PyPI

The easiest way to install Rompy is from PyPI:

pip install rompy

Install from source code

If you want the latest development version:

git clone git@github.com:rom-py/rompy.git
cd rompy
pip install -e .

Your First Model Run

This example demonstrates a simple model configuration using real Rompy classes. Since this documentation is built with the actual Rompy library available, you can see how the real API works:

from rompy.model import ModelRun
from rompy.core.config import BaseConfig
from rompy.core.time import TimeRange
from datetime import datetime

# Create a basic model configuration
config = BaseConfig()  # Empy configuration for demonstration purposes
print('Created BaseConfig')

# Create a time range for the simulation
time_range = TimeRange(
    start=datetime(2023, 1, 1),     # Start time of the simulation
    end=datetime(2023, 1, 2),       # End time of the simulation
    interval='1H',                  # Time interval between outputs
)
print(f'Created TimeRange from {time_range.start} to {time_range.end} with {time_range.interval} interval')

# Create a model run instance
run = ModelRun(
    run_id='my_first_run',              # Unique identifier for this run
    period=time_range,                  # The time period object
    config=config,                      # The configuration object
    output_dir='./output',              # Directory for output files
)
print(f'Created ModelRun with ID: {run.run_id}')
print(f'Output directory: {run.output_dir}')

To generate the model workspace, we then run the generate method, with will create all necessary input files based on the configuration provided (noting here that we are just using the base objects here with very little active configuration, so the generated workspace is very minimal).

# Generate model input files (this requires actual templates)
run.generate()
print('Generated model workspace')

Finally, we execute the model run using a local backend configuration. In a real run, the command would be configured as the actual model executable, here we just use a placeholder command (ls -l) for demonstration purposes to list the generated files in the model workspace.

# Execute the model run with a local backend (this requires actual model executables)
from rompy.backends import LocalConfig
backend_config = LocalConfig(
    timeout=3600,                  # Maximum runtime in seconds
    command='ls -l',  # Command to run your model
)
success = run.run(backend=backend_config)

if success:
    print('Model run completed successfully!')
else:
    print('Model run failed.')

Understanding the Components

  1. ModelRun: The main class that manages your model execution. It handles the time period, output locations, and configuration.

  2. TimeRange: Defines when your model simulation starts and ends, and the time interval for outputs.

  3. BaseConfig: A basic configuration object that you can extend or replace with more specific model configurations.

  4. Backend Configuration: Determines how and where your model runs (locally, in Docker, on HPC, etc.).

Next Steps

For more detailed information about Rompy concepts and usage:

For real ocean modeling examples, see the Examples section and the examples/ directory in the repository.