rompy-ww3

The rompy-ww3 package provides a plugin for the rompy framework to facilitate the setup, configuration, and execution of WAVEWATCH III (WW3) models. It leverages rompy's modular architecture to streamline the creation of WW3 model control files, input datasets, and boundary conditions using templated configurations and pydantic validation.

Development Status

⚠️ ACTIVE DEVELOPMENT - UNRELEASED

This WW3 plugin is currently under active development and has not yet been officially released. The architecture and API are being refined to provide the cleanest possible interface for WW3 model configuration.

Backward compatibility is NOT guaranteed during this development phase. Changes will strongly favor clean interfaces and architectural improvements over maintaining legacy compatibility.

Features

This package provides:

• Complete WW3 model configuration capabilities with all namelist components
• Integration with the rompy framework using the new clean architecture
• Comprehensive namelist generation for single-grid and multi-grid configurations
• Support for all WW3 model components: domain, input, output, forcing, boundary, grid, and more
• Ready-to-use examples including full model run configurations
• Direct namelist object passing with full API access
• No redundant interfaces or parameter reconstruction
• Type-safe union types for flexible grid handling

Implemented Namelist Components

The rompy-ww3 plugin includes complete implementations for all major WW3 namelist components:

• DOMAIN_NML: Domain definition and model timing
• INPUT_NML: Input data configuration for single-grid models
• INPUT_GRID_NML: Input grid specification for multi-grid models
• MODEL_GRID_NML: Model grid specification for multi-grid models
• OUTPUT_TYPE_NML: Output field specifications
• OUTPUT_DATE_NML: Output timing configuration
• HOMOG_COUNT_NML: Homogeneous input counts
• HOMOG_INPUT_NML: Homogeneous input specifications
• SPECTRUM_NML: Frequency and direction discretization
• RUN_NML: Run parameterization
• TIMESTEPS_NML: Time step configuration
• GRID_NML & RECT_NML: Grid preprocessing parameters
• BOUND_NML: Boundary input preprocessing
• FORCING_NML: Forcing field preprocessing
• TRACK_NML: Track output post-processing
• FIELD_NML: Field output post-processing
• POINT_NML: Point output post-processing
• RESTART_NML: Restart file initialization
• OUNF_NML: Unformatted output (user-created)
• OUNP_NML: Point output (user-created)
• UPRSTR_NML: Restart update (user-created)
• PARAMS_NML: Model parameters (user-created)

Core Components

• Config: Main configuration class integrating all namelist components
• Grid: WW3-specific grid parameters and namelist generation
• Data: WW3-specific data handling with forcing and assimilation support
• Source: WW3-specific data sources with variable mapping
• Namelists: Complete set of Pydantic models for WW3 namelists

WW3 Executable Components

The rompy-ww3 package includes a comprehensive set of components for each WW3 executable:

• Shell Component (Shel): Handles the main WW3 shell program configuration (ww3_shel.nml)
• Grid Component (Grid): Handles WW3 grid preprocessing configuration (ww3_grid.nml)
• Multi-Grid Component (Multi): Handles multi-grid WW3 configuration (ww3_multi.nml)
• Boundary Conditions Component (Bounc): Handles WW3 boundary condition generation (ww3_bounc.nml)
• Boundary Data Component (Bound): Handles WW3 boundary data extraction (ww3_bound.nml)
• Preprocessor Component (Prnc): Handles WW3 preprocessor configuration (ww3_prnc.nml)
• Track Component (Trnc): Handles WW3 track processor configuration (ww3_trnc.nml)
• Output Fields Component (Ounf): Handles WW3 field output configuration (ww3_ounf.nml)
• Output Points Component (Ounp): Handles WW3 point output configuration (ww3_ounp.nml)
• Restart Update Component (Uptstr): Handles WW3 restart update configuration (ww3_upstr.nml)
• Physics Parameters Component (Namelists): Handles WW3 physics parameter configuration (namelists.nml)

Documentation

See https://rom-py.github.io/rompy-ww3/

Quick Start Example

from rompy_ww3.config import Config
from rompy_ww3.namelists import Domain, Input

# Create a basic WW3 configuration
config = Config(
    domain=Domain(
        start="20230101 000000",
        stop="20230107 000000",
        iostyp=1
    ),
    input_nml=Input(
        forcing={
            "winds": "T",
            "water_levels": "T"
        }
    )
)

# Generate namelist files
result = config(runtime=your_runtime_object)

# Generate template context for use in templates
context = config.get_template_context()

For more detailed examples, see the examples directory.

Code Formatting and Pre-commit Hooks

This repository enforces Python code formatting using black via the pre-commit framework.

To set up pre-commit hooks locally (required for all contributors):

pip install pre-commit
pre-commit install

This will automatically check code formatting before each commit. To format your code manually, run:

pre-commit run --all-files

All code must pass black formatting before it can be committed or merged.

Versioning and Release

This project uses tbump for version management.

To bump the version, run:

tbump <new_version>

This will update the version in src/rompy_ww3/__init__.py, commit the change, and optionally create a git tag.

tbump is included in the development requirements (requirements_dev.txt).

For more advanced configuration, see tbump.toml in the project root.

Related Packages

• rompy
• rompy-swan
• rompy-schism
• rompy-notebooks