Parameter Reference¶
This document maps XBeach parameters to their location in rompy-xbeach components.
The structure follows the rompy-xbeach component hierarchy, with references to the corresponding XBeach manual tables. This ensures consistency between the documentation and the actual code structure.
Finding Parameters
- By rompy-xbeach component: Use the sections below (Physics, Sediment, Output, etc.)
- By XBeach table: Look for the table reference in each section header (e.g., "Table 36")
- By XBeach parameter name: Use your browser's search (Ctrl+F / Cmd+F)
Physics Component¶
The Physics component controls wave models, flow computation, friction, viscosity, and related numerical settings.
Process Switches¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
wavemodel |
physics.wavemodel |
Wave model type (stationary/surfbeat/nonh) |
swave |
physics.swave |
Enable short wave action balance |
lwave |
physics.lwave |
Enable long wave propagation |
flow |
physics.flow |
Enable flow computation |
avalanching |
physics.avalanching |
Enable avalanching |
gwflow |
physics.gwflow |
Enable groundwater flow |
wind |
physics.wind |
Enable wind forcing |
vegetation |
physics.vegetation |
Enable vegetation effects |
ships |
physics.ships |
Enable ship-induced waves |
roller |
physics.roller |
Enable roller model |
wci |
physics.wci |
Wave-current interaction |
Wave Model Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
break |
physics.wavemodel.breaktype |
Breaker formulation |
gamma |
physics.wavemodel.breaktype.gamma |
Breaker parameter |
alpha |
physics.wavemodel.breaktype.alpha |
Wave dissipation coefficient |
n |
physics.wavemodel.breaktype.n |
Power in breaker formulation |
gammax |
physics.wavemodel.breaktype.gammax |
Maximum ratio Hb/hb |
single_dir |
physics.wavemodel.single_dir |
Single directional bin (Surfbeat) |
nhbreaker |
physics.wavemodel.nhbreaker |
Non-hydrostatic breaker (Nonh) |
solver |
physics.wavemodel.solver |
Pressure solver (Nonh) |
Topt |
physics.wavemodel.Topt |
Optimal timestep (Nonh) |
kdmin |
physics.wavemodel.kdmin |
Minimum kd for dispersion (Nonh) |
Bed Friction Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
bedfriction |
physics.bedfriction |
Bed friction formulation (cf/chezy/manning/white-colebrook/white-colebrook-grainsize) |
bedfriccoef |
physics.bedfriction.bedfriccoef |
Friction coefficient |
bedfricfile |
physics.bedfriction.bedfricfile |
Spatially varying friction file |
mincf |
physics.bedfriction.mincf |
Minimum friction coefficient (Manning/WhiteColebrook) |
maxcf |
physics.bedfriction.maxcf |
Maximum friction coefficient (Manning/WhiteColebrook) |
friction_acceleration |
physics.bedfriction.friction_acceleration |
Acceleration effect on roughness |
friction_infiltration |
physics.bedfriction.friction_infiltration |
Infiltration effect on roughness |
friction_turbulence |
physics.bedfriction.friction_turbulence |
Turbulence effect on roughness |
gamma_turb |
physics.bedfriction.gamma_turb |
Turbulence calibration factor |
Viscosity Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
nuh |
physics.viscosity.nuh |
Horizontal viscosity coefficient |
nuhfac |
physics.viscosity.nuhfac |
Viscosity calibration factor |
nuhv |
physics.viscosity.nuhv |
Longshore viscosity enhancement |
smag |
physics.viscosity.smag |
Enable Smagorinsky model |
Wave Numerics¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
scheme |
physics.wave_numerics.scheme |
Numerical scheme |
wavint |
physics.wave_numerics.wavint |
Wave integration interval |
maxerror |
physics.wave_numerics.maxerror |
Maximum wave convergence error |
maxiter |
physics.wave_numerics.maxiter |
Maximum wave iterations |
Flow Numerics¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
cfl |
physics.flow_numerics.cfl |
CFL criterion |
eps |
physics.flow_numerics.eps |
Threshold depth |
eps_sd |
physics.flow_numerics.eps_sd |
Threshold velocity difference |
epsi |
physics.flow_numerics.epsi |
Mean/varying current ratio |
hmin |
physics.flow_numerics.hmin |
Minimum water depth |
deltahmin |
physics.flow_numerics.deltahmin |
Dimensionless min depth coefficient |
oldhmin |
physics.flow_numerics.oldhmin |
Use old hmin parameter |
umin |
physics.flow_numerics.umin |
Minimum velocity |
secorder |
physics.flow_numerics.secorder |
Second-order advection |
oldhu |
physics.flow_numerics.oldhu |
Old hu/hv formulation |
defuse |
physics.flow_numerics.defuse |
Enable diffusion in flow solver |
dtset |
physics.flow_numerics.dtset |
Fixed timestep |
maxdtfac |
physics.flow_numerics.maxdtfac |
Maximum timestep factor |
Physical Constants¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
rho |
physics.constants.rho |
Water density |
rhoa |
physics.constants.rhoa |
Air density |
g |
physics.constants.g |
Gravitational acceleration |
depthscale |
physics.constants.depthscale |
Depth scale for lab tests |
lat |
physics.coriolis.lat |
Latitude for Coriolis |
wearth |
physics.coriolis.wearth |
Earth angular velocity |
Vegetation Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
vegetation |
physics.vegetation |
Enable vegetation |
nsec |
physics.vegetation.nsec |
Number of vegetation sections |
ah |
physics.vegetation.ah |
Vegetation height |
bv |
physics.vegetation.bv |
Stem diameter |
Nv |
physics.vegetation.Nv |
Stem density |
Cd |
physics.vegetation.Cd |
Drag coefficient |
Sediment Component¶
The Sediment component controls sediment transport, morphology, bed composition, and groundwater flow. This corresponds to XBeach Tables 36-41.
Process Switches
The main switches sedtrans and morphology are fields on the Sediment component, not Physics. Set sediment.sedtrans=True or provide a SedimentTransport object to enable sediment transport.
Sediment Transport (XBeach Table 36)¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
form |
sediment.sedtrans.form |
Transport formulation |
waveform |
sediment.sedtrans.waveform |
Wave shape formulation |
turb |
sediment.sedtrans.turb |
Turbulence formulation |
turbadv |
sediment.sedtrans.turbadv |
Turbulence advection model |
sws |
sediment.sedtrans.sws |
Short wave stirring |
lws |
sediment.sedtrans.lws |
Long wave stirring |
lwt |
sediment.sedtrans.lwt |
Long wave turbulence |
BRfac |
sediment.sedtrans.BRfac |
Bore runup factor |
Tbfac |
sediment.sedtrans.Tbfac |
Bore interval factor |
Tsmin |
sediment.sedtrans.Tsmin |
Minimum adaptation time |
facua |
sediment.sedtrans.facua |
Onshore transport factor |
facAs |
sediment.sedtrans.facAs |
Asymmetry factor |
facSk |
sediment.sedtrans.facSk |
Skewness factor |
facsl |
sediment.sedtrans.facsl |
Bed slope factor |
facDc |
sediment.sedtrans.facDc |
Diffusion coefficient factor |
bed |
sediment.sedtrans.bed |
Bed transport calibration |
sus |
sediment.sedtrans.sus |
Suspended transport calibration |
bulk |
sediment.sedtrans.bulk |
Bulk transport switch |
ci |
sediment.sedtrans.ci |
Mass coefficient (inertia) |
cm |
sediment.sedtrans.cm |
Mass coefficient (shields) |
dilatancy |
sediment.sedtrans.dilatancy |
Dilatancy switch |
fallvelred |
sediment.sedtrans.fallvelred |
Fall velocity reduction |
bdslpeffmag |
sediment.sedtrans.bdslpeffmag |
Bed slope magnitude effect |
bdslpeffdir |
sediment.sedtrans.bdslpeffdir |
Bed slope direction effect |
bdslpeffini |
sediment.sedtrans.bdslpeffini |
Bed slope initiation effect |
reposeangle |
sediment.sedtrans.reposeangle |
Angle of internal friction |
tsfac |
sediment.sedtrans.tsfac |
Sediment source term factor |
z0 |
sediment.sedtrans.z0 |
Zero velocity level |
Morphology (XBeach Table 39)¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
morfac |
sediment.morphology.morfac |
Morphological acceleration |
morfacopt |
sediment.morphology.morfacopt |
Adjust output times for morfac |
morstart |
sediment.morphology.morstart |
Morphology start time |
morstop |
sediment.morphology.morstop |
Morphology stop time |
wetslp |
sediment.morphology.wetslp |
Critical wet slope |
dryslp |
sediment.morphology.dryslp |
Critical dry slope |
dzmax |
sediment.morphology.dzmax |
Maximum avalanching change |
hswitch |
sediment.morphology.hswitch |
Wet/dry slope switch depth |
lsgrad |
sediment.morphology.lsgrad |
Longshore gradient factor |
struct |
sediment.morphology.struct |
Enable structures |
ne_layer |
sediment.morphology.ne_layer |
Non-erodible layer file |
Bed Update (XBeach Table 40)¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
fwfile |
sediment.bed_update.fwfile |
Wave friction file |
fwcutoff |
sediment.bed_update.fwcutoff |
Wave friction cutoff |
Bed Composition¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
D50 |
sediment.bed_composition.D50 |
Median grain size |
D90 |
sediment.bed_composition.D90 |
90th percentile grain size |
D15 |
sediment.bed_composition.D15 |
15th percentile grain size |
ngd |
sediment.bed_composition.ngd |
Number of grain classes |
nd |
sediment.bed_composition.nd |
Number of bed layers |
rhos |
sediment.bed_composition.rhos |
Sediment density |
por |
sediment.bed_composition.por |
Porosity |
dzg1 |
sediment.bed_composition.dzg1 |
Layer 1 thickness |
dzg2 |
sediment.bed_composition.dzg2 |
Layer 2 thickness |
dzg3 |
sediment.bed_composition.dzg3 |
Layer 3 thickness |
sedcal |
sediment.bed_composition.sedcal |
Sediment calibration factor |
ucrcal |
sediment.bed_composition.ucrcal |
Critical velocity calibration |
ws_nonh |
sediment.bed_composition.ws_nonh |
Fall velocity (nonh mode) |
Transport Numerics¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
cmax |
sediment.transport_numerics.cmax |
Maximum concentration |
dtlimts |
sediment.transport_numerics.dtlimts |
Timestep limiter factor |
oldTsmin |
sediment.transport_numerics.oldTsmin |
Use old Tsmin parameter |
sourcesink |
sediment.transport_numerics.sourcesink |
Source-sink bed update |
thetanum |
sediment.transport_numerics.thetanum |
Upwind/central scheme |
Quasi-3D Transport¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
q3d |
sediment.quasi3d.q3d |
Enable quasi-3D transport |
kmax |
sediment.quasi3d.kmax |
Number of sigma layers |
sigfac |
sediment.quasi3d.sigfac |
Layer distribution factor |
vicmol |
sediment.quasi3d.vicmol |
Molecular viscosity |
vonkar |
sediment.quasi3d.vonkar |
Von Karman constant |
rwave |
sediment.quasi3d.rwave |
Wave roughness factor |
Groundwater Flow (XBeach Table 41)¶
Groundwater Switch
The main switch gwflow is on the Physics component (physics.gwflow), but the detailed groundwater parameters are on Sediment.groundwater.
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
gwflow |
physics.gwflow |
Enable groundwater flow (on Physics) |
gwnonh |
sediment.groundwater.gwnonh |
Non-hydrostatic groundwater |
kx |
sediment.groundwater.kx |
Horizontal permeability |
ky |
sediment.groundwater.ky |
Vertical permeability |
gwheadmodel |
sediment.groundwater.gwheadmodel |
Head boundary model |
Boundary Conditions¶
Boundary conditions are configured at the Config level, not within Physics or Sediment components.
Flow Boundary Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
front |
flow_boundary.front |
Front boundary type |
back |
flow_boundary.back |
Back boundary type |
left |
flow_boundary.left |
Left boundary type |
right |
flow_boundary.right |
Right boundary type |
lateralwave |
flow_boundary.lateralwave |
Lateral wave boundary |
Tide Boundary Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
tideloc |
tide_boundary.tideloc |
Number of tide locations |
tidetype |
tide_boundary.tidetype |
Tide boundary type |
zs0 |
tide_boundary.zs0 |
Initial water level |
paulrevere |
tide_boundary.paulrevere |
Sea/land boundary |
Wave Boundary Parameters¶
Wave boundary parameters are specified directly on the wave boundary data classes via Config.input.wave. See Wave Boundaries for full documentation.
Common Parameters (All Boundaries):
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
wbctype |
input.wave (class determines type) |
Wave boundary type |
bcfile |
input.wave.get() (generated) |
Boundary condition file |
thetamin |
input.wave.thetamin |
Minimum wave direction |
thetamax |
input.wave.thetamax |
Maximum wave direction |
dtheta |
input.wave.dtheta |
Directional resolution |
thetanaut |
input.wave.thetanaut |
Nautical convention |
ARC |
input.wave.ARC |
Active reflection compensation |
freewave |
input.wave.freewave |
Free wave boundary |
nmax |
input.wave.nmax |
Maximum cg/c ratio |
taper |
input.wave.taper |
Spin-up time |
Spectral Parameters (Spectral Boundaries Only):
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
rt |
input.wave.rt |
Wave spectrum duration |
dtbc |
input.wave.dtbc |
Boundary update interval |
random |
input.wave.random |
Random seed switch |
fcutoff |
input.wave.fcutoff |
Low-frequency cutoff |
correcthm0 |
input.wave.correcthm0 |
Hm0 correction switch |
sprdthr |
input.wave.sprdthr |
Spreading threshold |
trepfac |
input.wave.trepfac |
Representative period factor |
nspr |
input.wave.nspr |
Long wave direction switch |
wbcRemoveStokes |
input.wave.wbcRemoveStokes |
Remove Stokes drift |
wbcScaleEnergy |
input.wave.wbcScaleEnergy |
Scale energy to match Hm0 |
Hotstart Component¶
The Hotstart component enables initialization from a previous simulation state.
Hotstart Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
hotstart |
hotstart |
Enable hotstart |
hotstartfileno |
hotstart.hotstartfileno |
Hotstart file number |
writehotstart |
output.writehotstart |
Write hotstart files |
tinth |
output.tinth |
Hotstart output interval |
Output Component¶
The Output component controls what variables are written and at what intervals.
Output Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
outputformat |
output.outputformat |
Output file format |
tintg |
output.tintg |
Global output interval |
tintm |
output.tintm |
Mean output interval |
tintp |
output.tintp |
Point output interval |
tstart |
output.tstart |
Output start time |
nglobalvar |
output.globalvars |
Computed from globalvars list length |
nmeanvar |
output.meanvars |
Computed from meanvars list length |
npointvar |
output.pointvars |
Computed from pointvars list length |
nrugauge |
output.rugauges |
Computed from rugauges list length |
nrugdepth |
output.nrugdepth |
Number of runup depths |
rugdepth |
output.rugdepth |
Runup depth thresholds |
MPI Component¶
The Mpi component controls domain decomposition for parallel execution.
MPI Parameters¶
| XBeach Parameter | Rompy Location | Description |
|---|---|---|
mpiboundary |
mpi.mpiboundary |
MPI boundary type |
mmpi |
mpi.mmpi |
MPI partitions in m |
nmpi |
mpi.nmpi |
MPI partitions in n |
Data-Driven Parameters¶
These parameters are generated automatically by data interface classes. They should not be set manually - instead, configure the appropriate data source and the parameters will be computed during model generation.
Grid Parameters¶
Generated by RegularGrid from grid.py:
| XBeach Parameter | Source | Description |
|---|---|---|
nx |
grid.nx - 1 |
Number of computational cells in x-direction |
ny |
grid.ny - 1 |
Number of computational cells in y-direction |
dx |
grid.dx |
Grid spacing in x-direction |
dy |
grid.dy |
Grid spacing in y-direction |
xori |
grid.x0 |
X-coordinate of grid origin |
yori |
grid.y0 |
Y-coordinate of grid origin |
alfa |
grid.alfa |
Angle of x-axis from east (degrees) |
projection |
grid.proj4 |
PROJ4 projection string |
Bathymetry Parameters¶
Generated by bathymetry data classes:
| XBeach Parameter | Source | Description |
|---|---|---|
depfile |
bathy.get() |
Bathymetry file name |
posdwn |
bathy.get() |
Positive down convention (1 or -1) |
vardx |
bathy.get() |
Variable grid spacing flag |
Water Level / Tide Parameters¶
Generated by WaterLevelGrid, TideConsGrid, etc. from data/waterlevel.py:
| XBeach Parameter | Source | Description |
|---|---|---|
zs0file |
input.tide.get() |
Tide/water level time series file |
tideloc |
input.tide.tideloc |
Number of tide boundary locations (1, 2, or 4) |
tidelen |
input.tide.get() |
Number of time steps in tide series |
Wind Parameters¶
Generated by WindGrid, WindStation, WindPoint from data/wind.py:
| XBeach Parameter | Source | Description |
|---|---|---|
windfile |
input.wind.get() |
Wind forcing file (contains windv, windth time series) |
Wave Boundary Parameters¶
Generated by boundary classes in data/boundary.py. These return a SpectralWaveBoundary specification:
| XBeach Parameter | Source | Description |
|---|---|---|
wbctype |
input.wave.id |
Wave boundary type (jons, jonstable, swan, etc.) |
bcfile |
input.wave.get() |
Wave boundary condition file or FILELIST |
JONS/Parametric boundaries (BoundaryStationParamJons, BoundaryGridParamJons, etc.):
| XBeach Parameter | Source | Description |
|---|---|---|
Hm0 |
Data-derived | Significant wave height |
Tp |
Data-derived | Peak period |
mainang |
Data-derived | Main wave direction |
gammajsp |
Data-derived | JONSWAP peak enhancement factor |
s |
Data-derived | Directional spreading coefficient |
fnyq |
input.wave.fnyq |
Nyquist frequency for spectrum |
dfj |
input.wave.dfj |
Frequency step for spectrum |
JONSTABLE boundaries (BoundaryStationParamJonstable, BoundaryGridParamJonstable, etc.):
| XBeach Parameter | Source | Description |
|---|---|---|
Hm0 |
Data-derived (time series) | Significant wave height |
Tp |
Data-derived (time series) | Peak period |
mainang |
Data-derived (time series) | Main wave direction |
gammajsp |
Data-derived (time series) | JONSWAP gamma |
s |
Data-derived (time series) | Spreading coefficient |
duration |
Computed from times | Duration of each condition |
dtbc |
input.wave.wbc.dtbc |
Boundary update timestep |
SWAN spectral boundaries (BoundaryStationSpectraSwan):
| XBeach Parameter | Source | Description |
|---|---|---|
freq |
Data-derived | Frequency array |
dir |
Data-derived | Direction array |
efth |
Data-derived | 2D energy density spectrum |
Wave Boundary Condition Parameters¶
These can be set via input.wave.wbc (a SpectralWaveBoundaryConditions object):
| XBeach Parameter | Source | Description |
|---|---|---|
dtbc |
input.wave.wbc.dtbc |
Boundary condition timestep |
nmax |
input.wave.wbc.nmax |
Maximum ratio cg/c for long waves |
rt |
input.wave.wbc.rt |
Duration of wave spectrum |
taper |
input.wave.wbc.taper |
Spin-up time for boundary |
fcutoff |
input.wave.wbc.fcutoff |
Low-frequency cutoff |
sprdthr |
input.wave.wbc.sprdthr |
Spreading threshold |
trepfac |
input.wave.wbc.trepfac |
Representative period factor |
correcthm0 |
input.wave.wbc.correcthm0 |
Correct Hm0 for directional spreading |
random |
input.wave.wbc.random |
Random seed for boundary generation |
nspr |
input.wave.wbc.nspr |
Long wave direction switch |
wbcversion |
input.wave.wbc.wbcversion |
Wave boundary version |
wbcRemoveStokes |
input.wave.wbc.wbcRemoveStokes |
Remove Stokes drift |
wbcScaleEnergy |
input.wave.wbc.wbcScaleEnergy |
Scale energy to match Hm0 |
Data Interface Pattern
The data interfaces follow a consistent pattern: configure the source data and variable mappings, then call get(destdir, grid, time) which writes the necessary files and returns a dict or object with the XBeach parameters to include in params.txt.