Skip to content

Configuration

This guide covers how to configure XBeach simulations using rompy-xbeach.

The Config Class

The Config class is the central configuration object. It accepts components for different aspects of the model:

from rompy_xbeach.config import Config

config = Config(
    grid=...,           # Grid definition
    bathy=...,          # Bathymetry
    input=...,          # Data-driven boundary conditions
    physics=...,        # Physical processes
    sediment=...,       # Sediment transport and morphology
    output=...,         # Output configuration
    flow_boundary=...,  # Flow boundary conditions
    tide_boundary=...,  # Tide boundary parameters
    wave_boundary=...,  # Manual wave boundary specification
    hotstart=...,       # Hotstart initialisation
    mpi=...,            # MPI parallelisation
)

All fields are optional and have sensible defaults.

Configuration Methods

Python Objects

Direct instantiation with full IDE support:

from rompy_xbeach.config import Config
from rompy_xbeach.components.physics import Physics
from rompy_xbeach.components.physics.wavemodel import Surfbeat
from rompy_xbeach.components.sediment import Sediment
from rompy_xbeach.components.sediment.morphology import Morphology

config = Config(
    physics=Physics(
        wavemodel=Surfbeat(),
    ),
    sediment=Sediment(
        morphology=Morphology(morfac=10),
    ),
)

YAML Files

Declarative configuration for reproducibility:

model_type: xbeach

physics:
  wavemodel:
    model_type: surfbeat
  sedtrans: true

sediment:
  morphology:
    morfac: 10

import yaml
from rompy_xbeach.config import Config

with open("config.yml") as f:
    config = Config(**yaml.safe_load(f))

Dictionary

Useful for programmatic configuration:

config = Config(**{
    "physics": {
        "wavemodel": {"model_type": "surfbeat"},
        "sedtrans": True,
    },
    "sediment": {
        "morphology": {"morfac": 10},
    },
})

The model_type Discriminator

When using YAML or dictionaries, the model_type field tells Pydantic which class to instantiate:

wavemodel:
  model_type: surfbeat  # Creates Surfbeat instance
  breaktype:
    model_type: roelvink1  # Creates Roelvink1 instance
    gamma: 0.55

This enables type-safe deserialisation of discriminated unions.

Process Switches

Many XBeach features use the Union[bool, Component] pattern:

# Enable with defaults
physics = Physics(vegetation=True)

# Enable with custom parameters
from rompy_xbeach.components.physics.vegetation import Vegetation
physics = Physics(vegetation=Vegetation(nsec=2, ah=[1.5]))

# Disable explicitly
physics = Physics(vegetation=False)

# Omit (uses XBeach default)
physics = Physics()

This pattern applies to:

Field Component XBeach Parameter
vegetation Vegetation vegetation
viscosity Viscosity nuh, smag, etc.
wind Wind wind, Cd
bedfriction BedFriction bedfriction, bedfriccoef
ships Ships ships
hotstart Hotstart hotstart, hotstartfileno

Validation

Pydantic validates configuration at construction time:

from rompy_xbeach.components.sediment import Morphology

# Valid
morph = Morphology(morfac=10)

# Invalid - raises ValidationError
morph = Morphology(morfac=-1)  # morfac must be >= 0

Range Validation

Most numeric parameters have valid ranges:

from rompy_xbeach.components.physics.wavemodel import Roelvink1

# gamma must be between 0.4 and 0.9
breaker = Roelvink1(gamma=0.55)  # OK
breaker = Roelvink1(gamma=1.5)   # ValidationError

Cross-Field Validation

Some validations involve multiple fields:

from rompy_xbeach.components.sediment.composition import BedComposition

# D90 must be greater than D50
bed = BedComposition(D50=[0.0002], D90=[0.0003])  # OK
bed = BedComposition(D50=[0.0003], D90=[0.0002])  # ValidationError

Mutual Exclusivity

The wave boundary source can only be specified once:

from rompy_xbeach.config import Config, DataInterface

# This raises ValidationError
config = Config(
    input=DataInterface(wave=...),  # Data-driven
    wave_boundary=...,              # Manual - can't have both!
)

Serialisation

When the config is called, it serialises to a flat dictionary:

# During model generation
params = config(runtime)

# params is a dict like:
{
    "wavemodel": "surfbeat",
    "morfac": 10,
    "bedfriccoef": 0.01,
    # ... all XBeach parameters
}

This dictionary is written to params.txt.

Boolean Conversion

Python booleans are converted to XBeach integers:

Physics(sedtrans=True)   # → sedtrans = 1
Physics(sedtrans=False)  # → sedtrans = 0

None Values

None values are excluded from output, allowing XBeach defaults:

Physics(swave=None)  # swave not written, XBeach uses default

Accessing Parameters

After configuration, you can inspect the parameters:

config = Config(...)

# Get the params dict (after calling)
params = config(runtime)

# Or access the stored params
print(config.params)

Environment Variables

Some paths can use environment variables:

from rompy_xbeach.data.bathy import XBeachBathy

from rompy_xbeach.source import SourceGeotiff

bathy = XBeachBathy(
    source=SourceGeotiff(
        filename="${DATA_DIR}/bathymetry.tif",
    ),
)

Next Steps