Components API¶
API reference for all rompy-xbeach components.
Physics¶
Physics (Aggregator)¶
Bases: XBeachBaseModel
XBeach physical processes configuration.
XBeach supports a variety of physical processes from generic, like waves and flow, to very specific, like ship motions and point discharge. Each process can be switched on or off. The commonly used processes are turned on by default.
This class allows configuration of all physical process switches in XBeach. All fields default to None, meaning XBeach's default values will be used unless explicitly specified.
See https://xbeach.readthedocs.io/en/latest/xbeach_manual.html#physical-processes for more information.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
wavemodel: Optional[Union[Stationary, Surfbeat, Nonh]] = Field(default=None, description='Wave model configuration: Stationary, Surfbeat or Nonh (XBeach default: surfbeat)', discriminator='model_type')
class-attribute
instance-attribute
¶
advection: Optional[bool] = Field(default=None, description='Include advection in flow solver (XBeach default: 1)')
class-attribute
instance-attribute
¶
avalanching: Optional[bool] = Field(default=None, description='Turn on avalanching (XBeach default: 1)')
class-attribute
instance-attribute
¶
bedfriction: Optional[Union[Cf, Chezy, Manning, WhiteColebrook, WhiteColebrookGrainsize]] = Field(default=None, description='Bed friction formulation (XBeach default: manning)', discriminator='model_type')
class-attribute
instance-attribute
¶
cyclic: Optional[bool] = Field(default=None, description='Turn on cyclic boundary conditions (XBeach default: 0)')
class-attribute
instance-attribute
¶
flow: Optional[bool] = Field(default=None, description='Turn on flow calculation (XBeach default: 1)')
class-attribute
instance-attribute
¶
gwflow: Optional[bool] = Field(default=None, description='Turn on groundwater flow (XBeach default: 0)')
class-attribute
instance-attribute
¶
lwave: Optional[bool] = Field(default=None, description='Turn on short wave forcing on NLSW equations and boundary conditions (XBeach default: 1)')
class-attribute
instance-attribute
¶
roller: Optional[Union[bool, Roller]] = Field(default=None, description='Switch to enable roller model (XBeach default: 1)')
class-attribute
instance-attribute
¶
setbathy: Optional[bool] = Field(default=None, description='Turn on timeseries of prescribed bathy input (XBeach default: 0)')
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
single_dir: Optional[bool] = Field(default=None, description='Turn on stationary model for refraction, surfbeat based on mean direction (XBeach default: 1)')
class-attribute
instance-attribute
¶
snells: Optional[bool] = Field(default=None, description="Turn on Snell's law for wave refraction (XBeach default: 0)")
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
swrunup: Optional[bool] = Field(default=None, description='Turn on short wave runup (XBeach default: 0)')
class-attribute
instance-attribute
¶
vegetation: Optional[Union[bool, Vegetation]] = Field(default=None, description='Turn on interaction of waves and flow with vegetation (XBeach default: 0)')
class-attribute
instance-attribute
¶
viscosity: Optional[Union[bool, Viscosity]] = Field(default=None, description='Include viscosity in flow solver. Can be True/False to enable/disable, or a Viscosity object to enable with custom parameters (XBeach default: 1)')
class-attribute
instance-attribute
¶
wci: Optional[Union[bool, WaveCurrentInteraction]] = Field(default=None, description='Switch to turn on wave-current interaction (XBeach default: 0)')
class-attribute
instance-attribute
¶
wind: Optional[Union[bool, Wind]] = Field(default=None, description='Include wind in flow solver. Can be True/False to enable/disable, or a Wind object to enable with custom parameters like Cd (XBeach default: 1)')
class-attribute
instance-attribute
¶
flow_numerics: Optional[FlowNumerics] = Field(default=None, description='Flow numerical parameters (eps, hmin, deltahmin, umin, secorder, etc.)')
class-attribute
instance-attribute
¶
wave_numerics: Optional[WaveNumerics] = Field(default=None, description='Wave numerical parameters (scheme, maxiter, maxerror, wavint)')
class-attribute
instance-attribute
¶
constants: Optional[PhysicalConstants] = Field(default=None, description='Physical constants (g, rho, depthscale)')
class-attribute
instance-attribute
¶
coriolis: Optional[Coriolis] = Field(default=None, description='Coriolis force parameters (lat, wearth)')
Functions¶
Wave Models¶
Bases: XBeachBaseModel
Stationary wave model configuration.
Efficiently solves wave-averaged equations but neglects infragravity waves. Useful for conditions where incident waves are relatively small and/or short.
Bases: XBeachBaseModel
Surfbeat (instationary) wave model configuration.
Resolves short wave variations on the wave group scale (short wave envelope) and the long waves associated with them. This is the XBeach default mode.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
breaktype: Optional[Union[Roelvink1, Roelvink2, RoelvinkDaly]] = Field(default=None, description='Type of breaker formulation for the surfbeat wave model', discriminator='model_type', alias='break')
Bases: XBeachBaseModel
Non-hydrostatic (wave-resolving) wave model configuration (XBeach Table 42).
Uses non-linear shallow water equations with a pressure correction term, allowing modeling of propagation and decay of individual waves.
Wave breaking is implemented using the Hydrostatic Front Approximation (HFA), where the non-hydrostatic pressure term is disabled when waves exceed a certain steepness, after which bore-like breaking takes over.
Note¶
XBeach has a legacy nonh parameter (0/1 switch) that is deprecated.
The XBeach source code shows that if nonh=1 is specified, XBeach logs
a warning and internally sets wavemodel=nonh. Setting both nonh=1
and a different wavemodel causes XBeach to halt with an error.
Use this Nonh class via Physics(wavemodel=Nonh(...)) instead of
the legacy nonh parameter. This outputs wavemodel = nonh in params.txt.
These are advanced options and it is recommended not to change them unless you have specific requirements.
References¶
Smit et al. (2014), McCall et al. (2014), Zijlema et al. (2011)
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
Topt: Optional[float] = Field(default=None, description='Absolute period to optimize coefficient (XBeach default: 10.0 s)', ge=1.0, le=20.0)
class-attribute
instance-attribute
¶
breakviscfac: Optional[float] = Field(default=None, description='Factor to increase viscosity during breaking (XBeach default: 1.5)', ge=1.0, le=3.0)
class-attribute
instance-attribute
¶
breakvisclen: Optional[float] = Field(default=None, description='Ratio between local depth and length scale in extra breaking viscosity (XBeach default: 1.0)', ge=0.75, le=3.0)
class-attribute
instance-attribute
¶
dispc: Optional[float] = Field(default=None, description='Coefficient in front of the vertical pressure gradient (XBeach default: -1.0)', ge=0.1, le=2.0)
class-attribute
instance-attribute
¶
kdmin: Optional[float] = Field(default=None, description='Minimum value of kd (pi/dx > min(kd)) (XBeach default: 0.0)', ge=0.0, le=0.05)
class-attribute
instance-attribute
¶
maxbrsteep: Optional[float] = Field(default=None, description='Maximum wave steepness criterium for breaking (XBeach default: 0.4)', ge=0.3, le=0.8)
class-attribute
instance-attribute
¶
nhbreaker: Optional[int] = Field(default=None, description='Non-hydrostatic breaker model (XBeach default: 2)', ge=0, le=2)
class-attribute
instance-attribute
¶
nhlay: Optional[float] = Field(default=None, description='Layer distribution in the nonhydrostatic model (XBeach default: 0.33)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
nonhq3d: Optional[bool] = Field(default=None, description='Turn on reduced two-layer non-hydrostatic model for improved dispersive behavior (XBeach default: 0)', alias='nhq3d')
class-attribute
instance-attribute
¶
reformsteep: Optional[float] = Field(default=None, description='Wave steepness criterium to reform after breaking. XBeach default: 0.25 * maxbrsteep', ge=0.0)
class-attribute
instance-attribute
¶
secbrsteep: Optional[float] = Field(default=None, description='Secondary maximum wave steepness criterium. XBeach default: 0.5 * maxbrsteep', ge=0.0)
class-attribute
instance-attribute
¶
solver: Optional[Literal['sip', 'tridiag']] = Field(default=None, description='Solver used to solve the linear system (XBeach default: tridiag)')
class-attribute
instance-attribute
¶
solver_acc: Optional[float] = Field(default=None, description='Accuracy with respect to the right-hand side used in termination criterion: ||b-ax|| < acc*||b|| (XBeach default: 0.005)', ge=1e-05, le=0.1)
class-attribute
instance-attribute
¶
solver_maxit: Optional[int] = Field(default=None, description='Maximum number of iterations in the linear sip solver (XBeach default: 30)', ge=1, le=1000)
class-attribute
instance-attribute
¶
solver_urelax: Optional[float] = Field(default=None, description='Underrelaxation parameter (XBeach default: 0.92)', ge=0.5, le=0.99)
Breaker Formulations¶
Bases: WaveDissipation
Roelvink (1993a) breaker model configuration.
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['roelvink1'] = Field(default='roelvink1', description='Model type discriminator')
class-attribute
instance-attribute
¶
alpha: Optional[float] = Field(default=None, description='Wave dissipation coefficient (XBeach default: 1.38)', ge=0.5, le=2.0)
class-attribute
instance-attribute
¶
gamma: Optional[float] = Field(default=None, description='Breaker parameter gamma (XBeach default: 0.46)', ge=0.4, le=0.9)
class-attribute
instance-attribute
¶
n: Optional[float] = Field(default=None, description='Power in roelvink dissipation model (Xbeach default: 10.0)', ge=5.0, le=20.0)
Bases: WaveDissipation
Daly et al. (2010) breaker model configuration.
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['roelvink_daly'] = Field(default='roelvink_daly', description='Model type discriminator')
class-attribute
instance-attribute
¶
gamma2: Optional[float] = Field(default=None, description='End of breaking parameter (XBeach default: 0.34)', ge=0.0, le=0.5)
Friction¶
Bases: FrictionModifiers
Base class for bed friction formulations with common parameters.
Most bed friction formulations allow specification of a friction coefficient either as a single value or spatially varying via a file. Additional parameters control depth cutoffs and XBeach-G specific friction modifications that apply to all friction formulations.
Attributes¶
class-attribute
instance-attribute
¶
bedfriccoef: Optional[float] = Field(default=None, description='Bed friction coefficient (XBeach default: 0.01)', ge=0.0)
class-attribute
instance-attribute
¶
bedfricfile: Optional[XBeachDataBlob] = Field(default=None, description='Bed friction file with spatially varying friction coefficients. If specified, overrides bedfriccoef.')
Functions¶
Viscosity¶
Bases: XBeachBaseModel
Horizontal viscosity configuration.
XBeach uses the Smagorinsky (1963) model by default to compute horizontal viscosity, accounting for momentum exchange at spatial scales smaller than the computational grid. Alternatively, a user-defined constant viscosity can be specified.
The nuh parameter has dual meaning depending on smag:
- If smag=1 (default): nuh is the Smagorinsky constant (default: 0.1)
- If smag=0: nuh is the horizontal background viscosity in m²/s
When this class is used in Physics.viscosity, it automatically enables viscosity in the flow solver (viscosity=1).
References¶
Smagorinsky, J. (1963). General circulation experiments with the primitive equations: I. The basic experiment. Monthly weather review, 91(3), 99-164.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
smag: Optional[bool] = Field(default=None, description='Switch for Smagorinsky subgrid model for viscosity. If enabled (1), nuh is the Smagorinsky constant. If disabled (0), nuh is the constant horizontal viscosity (XBeach default: 1)')
class-attribute
instance-attribute
¶
nuh: Optional[float] = Field(default=None, description='Horizontal viscosity parameter. Meaning depends on smag: If smag=1: Smagorinsky constant (dimensionless, XBeach default: 0.1). If smag=0: Horizontal background viscosity (m2/s, XBeach default: 0.1)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
nuhfac: Optional[float] = Field(default=None, description='Viscosity switch for roller induced turbulent horizontal viscosity (XBeach default: 1.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
nuhv: Optional[float] = Field(default=None, description='Longshore viscosity enhancement factor, following Svendsen (XBeach default: 1.0)', ge=1.0, le=20.0)
Functions¶
Vegetation¶
Bases: XBeachBaseModel
Vegetation model configuration.
The presence of aquatic vegetation within the area of wave propagation or wave breaking results in an additional dissipation mechanism for short waves. This is modeled using the approach of [Mendez and Losada, 2004], which was adjusted by [Suzuki et al., 2012] to take into account vertically heterogeneous vegetation, see [van Rooijen et al., 2015]. The short wave dissipation due to vegetation is calculated as function of the local wave height and several vegetation parameters. The vegetation can be schematized in a number of vertical elements with each pecific property. In this way the wave damping effect of vegetation such as mangrove trees, with a relatively dense root system but sparse stem area, can be modeled. The dissipation term is then computed as the sum of the dissipation per vegetation layer ([Suzuki et al., 2012])
See https://xbeach.readthedocs.io/en/latest/xbeach_manual.html#vegetation for more information.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
veggiefile: Optional[XBeachDataBlob] = Field(default=None, description='Name of veggie species list file')
class-attribute
instance-attribute
¶
veggiemapfile: Optional[XBeachDataBlob] = Field(default=None, description='Name of veggie species map file')
class-attribute
instance-attribute
¶
vegcanflo: Optional[bool] = Field(default=None, description='Include incanopy flow (XBeach default: 0)')
class-attribute
instance-attribute
¶
vegnonlin: Optional[bool] = Field(default=None, description='Include non-linear wave effect (XBeach default: 0)')
class-attribute
instance-attribute
¶
veguntow: Optional[bool] = Field(default=None, description='Include undertow in phase-averaged vegetation (XBeach default: 1)')
Functions¶
Numerics¶
Bases: XBeachBaseModel
Wave action balance numerical parameters.
These parameters control the numerical aspects of the wave action balance solver, including the numerical scheme and convergence criteria.
The Warming and Beam (1976) scheme is used by default to overcome undesired effects of steepening of wave groups through a small additional diffusion term.
References¶
Beam, R. M., & Warming, R. F. (1976). An implicit finite-difference algorithm for hyperbolic systems in conservation-law form. Journal of computational physics, 22(1), 87-110.
Attributes¶
class-attribute
instance-attribute
¶
scheme: Optional[Literal['upwind_1', 'lax_wendroff', 'upwind_2', 'warmbeam']] = Field(default=None, description='Numerical scheme for wave propagation. Options: upwind_1 (first-order upwind), lax_wendroff (Lax-Wendroff), upwind_2 (second-order upwind), warmbeam (Warming-Beam) (XBeach default: warmbeam)')
class-attribute
instance-attribute
¶
maxiter: Optional[int] = Field(default=None, description='Maximum number of iterations in wave stationary solver (XBeach default: 500)', ge=2, le=1000)
class-attribute
instance-attribute
¶
maxerror: Optional[float] = Field(default=None, description='Maximum wave height error in wave stationary iteration (XBeach default: 0.0005 m)', ge=1e-05, le=0.001)
class-attribute
instance-attribute
¶
wavint: Optional[float] = Field(default=None, description='Interval between wave module calls in seconds (only in stationary wave mode, XBeach default: 600.0 s)', ge=1.0, le=3600.0)
Bases: XBeachBaseModel
Flow numerical parameters.
These parameters control numerical aspects of the shallow water equations, particularly handling of very shallow water and wet/dry transitions.
The threshold parameters (eps, hmin, umin) prevent unrealistic behavior in shallow water by setting minimum values for depth and velocity calculations.
Attributes¶
class-attribute
instance-attribute
¶
eps: Optional[float] = Field(default=None, description='Threshold water depth above which cells are considered wet (XBeach default: 0.005 m)', ge=0.001, le=0.1)
class-attribute
instance-attribute
¶
epsi: Optional[float] = Field(default=None, description='Ratio of mean current to time varying current through offshore boundary (XBeach default: -1.0)', ge=-1.0, le=0.2)
class-attribute
instance-attribute
¶
eps_sd: Optional[float] = Field(default=None, description='Threshold velocity difference to determine conservation of energy head versus momentum (XBeach default: 0.5 m/s)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
hmin: Optional[float] = Field(default=None, description='Threshold water depth above which Stokes drift is included (XBeach default: 0.0 m). See also deltahmin and oldhmin', ge=0.001, le=1.0)
class-attribute
instance-attribute
¶
oldhu: Optional[bool] = Field(default=None, description='Switch to enable old hu calculation (XBeach default: 0)')
class-attribute
instance-attribute
¶
secorder: Optional[bool] = Field(default=None, description='Use second order corrections to advection/non-linear terms based on MacCormack scheme (XBeach default: 0)')
class-attribute
instance-attribute
¶
umin: Optional[float] = Field(default=None, description='Threshold velocity for upwind velocity detection and for vmag2 in equilibrium sediment concentration (XBeach default: 0.0 m/s)', ge=0.0, le=0.2)
class-attribute
instance-attribute
¶
deltahmin: Optional[float] = Field(default=None, description='Dimensionless coefficient to determine the threshold water depth above which Stokes drift is included (XBeach default: 0.1)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
oldhmin: Optional[bool] = Field(default=None, description='Switch to apply the old hmin parameter instead of deltahmin. If 1, hmin is used directly as minimum water depth (XBeach default: 0)')
class-attribute
instance-attribute
¶
defuse: Optional[bool] = Field(default=None, description='Switch to enable diffusion in the flow solver to prevent numerical instabilities (XBeach default: 1)')
class-attribute
instance-attribute
¶
dtset: Optional[float] = Field(default=None, description='Fixed timestep (s). If > 0, overrides automatic timestep calculation. Use with caution - may cause instabilities (XBeach default: 0.0, automatic)', ge=0.0, le=100.0)
class-attribute
instance-attribute
¶
maxdtfac: Optional[float] = Field(default=None, description='Maximum factor for timestep increase in explosion prevention mechanism. For surfbeat/stationary: 10-200 (default 50). For nonh: 100-1000 (default 500)', ge=10.0, le=1000.0)
class-attribute
instance-attribute
¶
cfl: Optional[float] = Field(default=None, description='Maximum Courant-Friedrichs-Lewy number for timestep control. Lower values give more stability but slower computation (XBeach default: 0.7)', ge=0.1, le=0.9)
Functions¶
Constants¶
Bases: XBeachBaseModel
Physical constants used in XBeach computations.
These fundamental physical constants are used throughout XBeach calculations. The depthscale parameter allows scaling of various depth-related thresholds for laboratory-scale simulations.
Attributes¶
class-attribute
instance-attribute
¶
depthscale: Optional[float] = Field(default=None, description='Depth scale of (lab) test simulated. Affects eps, hmin, hswitch and dzmax. A value lower than 1 increases the cut-off values (XBeach default: 1.0 for field scale)', ge=1.0, le=200.0)
class-attribute
instance-attribute
¶
g: Optional[float] = Field(default=None, description='Gravitational acceleration (m/s²) (XBeach default: 9.81)', ge=9.7, le=9.9)
class-attribute
instance-attribute
¶
rho: Optional[float] = Field(default=None, description='Density of water (kg/m³) (XBeach default: 1025.0)', ge=1000.0, le=1040.0)
class-attribute
instance-attribute
¶
rhoa: Optional[float] = Field(default=None, description='Density of air (kg/m³) (XBeach default: 1.25)', ge=1.0, le=2.0)
Sediment¶
Sediment (Aggregator)¶
Bases: XBeachBaseModel
XBeach sediment transport and morphology configuration.
This component groups all sediment-related parameters including: - Sediment transport formulations and processes - Morphological evolution (morfac, time windows) - Avalanching - Bed composition and layering - Quasi-3D sediment transport - Prescribed bathymetry evolution
All fields default to None, meaning XBeach's default values will be used unless explicitly specified.
Examples¶
from rompy_xbeach.components.sediment import Sediment from rompy_xbeach.components.sediment.transport import SedimentTransport from rompy_xbeach.components.sediment.morphology import Morphology
sediment = Sediment( ... transport=SedimentTransport( ... form="vanthiel_vanrijn", ... facua=0.15, ... bdslpeffmag="roelvink_total", ... ), ... morphology=Morphology( ... morfac=10.0, ... morstart=0.0, ... morstop=3600.0, ... ), ... )
See Also¶
rompy_xbeach.components.sediment.transport : Sediment transport parameters rompy_xbeach.components.sediment.morphology : Morphology parameters rompy_xbeach.components.sediment.bed : Bed composition parameters
References¶
Roelvink, D., & Reniers, A. (2011). A guide to modeling coastal morphology. Advances in Coastal and Ocean Engineering, Vol. 12.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
sedtrans: Optional[Union[bool, SedimentTransport]] = Field(default=None, description='Sediment transport parameters from XBeach Table 36, including formulations, bed slope effects, process switches, and calibration factors')
class-attribute
instance-attribute
¶
numerics: Optional[TransportNumerics] = Field(default=None, description='Sediment transport numerical parameters (cmax, sourcesink, thetanum, dtlimts, oldTsmin)')
class-attribute
instance-attribute
¶
morphology: Optional[Union[bool, Morphology]] = Field(default=None, description='Morphological evolution parameters from XBeach Table 39 (morfac, morfacopt, morstart, morstop, lsgrad, struct, ne_layer, dryslp, wetslp, hswitch, dzmax)')
class-attribute
instance-attribute
¶
bed_composition: Optional[BedComposition] = Field(default=None, description='Bed composition parameters including grain size (D50, D90), sediment density (rhos), porosity (por), and layer thickness (dzg1/2/3)')
class-attribute
instance-attribute
¶
bed_update: Optional[BedUpdate] = Field(default=None, description='Bed update parameters from XBeach Table 40 (frac_dz, merge, nd_var, nsetbathy, setbathyfile, split)')
class-attribute
instance-attribute
¶
groundwater: Optional[GroundwaterFlow] = Field(default=None, description='Groundwater flow parameters from XBeach Table 41 (aquiferbot, aquiferbotfile, dwetlayer, gw0, gw0file, gwReturb, gwfastsolve, gwheadmodel, gwhorinfil, gwnonh, gwscheme, kx, ky, kz)')
class-attribute
instance-attribute
¶
q3d: Optional[Union[bool, Quasi3D]] = Field(default=None, description='Turn on quasi-3D sediment transport (XBeach default: 0)')
Transport¶
Bases: XBeachBaseModel
Sediment transport parameters (XBeach Table 36).
This class consolidates all sediment transport parameters from XBeach's Table 36, including: - Sediment transport formulations (form, waveform) - Wave asymmetry and skewness effects (facAs, facSk, facua) - Bed slope effects (bdslpeff*, facsl, reposeangle) - Process switches (sws, lws, lwt, turb, turbadv) - Bed and suspended load calibration (bed, sus, bulk) - Advanced calibration parameters (Tsmin, tsfac, facDc, etc.)
All fields default to None, meaning XBeach's default values will be used unless explicitly specified.
References¶
Roelvink, D., & Reniers, A. (2011). A guide to modeling coastal morphology. Soulsby, R. (1997). Dynamics of marine sands. Van Rijn, L. C. (1993). Principles of sediment transport in rivers, estuaries and coastal seas. Van Thiel de Vries, J. S. M. (2009). Dune erosion during storm surges.
Attributes¶
class-attribute
instance-attribute
¶
sedtrans: Literal[True] = Field(default=True, description='Enable sediment transport (always True when using SedimentTransport class)')
class-attribute
instance-attribute
¶
BRfac: Optional[float] = Field(default=None, description='Calibration factor for surface slope (XBeach default: 1.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
Tbfac: Optional[float] = Field(default=None, description='Calibration factor for bore interval: tbore = Tbfac * tbore (XBeach default: 1.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
Tsmin: Optional[float] = Field(default=None, description='Minimum adaptation time scale in advection-diffusion equation (XBeach default: 0.5 s)', ge=0.01, le=10.0)
class-attribute
instance-attribute
¶
bdslpeffdir: Optional[Literal['none', 'talmon']] = Field(default=None, description='Modify the direction of sediment transport based on bed slope (XBeach default: none)')
class-attribute
instance-attribute
¶
bdslpeffdirfac: Optional[float] = Field(default=None, description='Calibration factor in the modification of the direction (XBeach default: 1.0)', ge=0.0, le=2.0)
class-attribute
instance-attribute
¶
bdslpeffini: Optional[Literal['none', 'total', 'bed']] = Field(default=None, description='Modify the critical shields parameter based on bed slope (XBeach default: none)')
class-attribute
instance-attribute
¶
bdslpeffmag: Optional[Literal['none', 'roelvink_total', 'roelvink_bed', 'soulsby_total', 'soulsby_bed']] = Field(default=None, description='Modify the magnitude of sediment transport based on bed slope (XBeach default: roelvink_total)')
class-attribute
instance-attribute
¶
bed: Optional[float] = Field(default=None, description='Calibration factor for bed transports (XBeach default: 1.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
bermslope: Optional[float] = Field(default=None, description='Swash zone slope for (semi-)reflective beaches (XBeach default: 0.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
betad: Optional[float] = Field(default=None, description='Dissipation parameter for long wave breaking turbulence (XBeach default: 1.0)', ge=0.0, le=10.0)
class-attribute
instance-attribute
¶
bulk: Optional[bool] = Field(default=None, description='Switch to compute bulk transport rather than bed and suspended load separately (XBeach default: 0)')
class-attribute
instance-attribute
¶
ci: Optional[float] = Field(default=None, description='Mass coefficient in shields inertia term (XBeach default: 1.0)', ge=0.5, le=1.5)
class-attribute
instance-attribute
¶
cm: Optional[float] = Field(default=None, description='Mass coefficient in shields inertia term (XBeach default: 1.5)', ge=0.0, le=3.0)
class-attribute
instance-attribute
¶
dilatancy: Optional[bool] = Field(default=None, description='Switch to reduce critical shields number due to dilatancy (XBeach default: 0)')
class-attribute
instance-attribute
¶
facAs: Optional[float] = Field(default=None, description='Calibration factor for time-averaged flows due to wave asymmetry (XBeach default: 0.2)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
facDc: Optional[float] = Field(default=None, description='Option to control sediment diffusion coefficient (XBeach default: 1.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
facSk: Optional[float] = Field(default=None, description='Calibration factor for time-averaged flows due to wave skewness (XBeach default: 0.15)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
facsl: Optional[float] = Field(default=None, description='Factor for bed slope effect (XBeach default: 1.6)', ge=0.0, le=1.6)
class-attribute
instance-attribute
¶
facua: Optional[float] = Field(default=None, description='Calibration factor for time-averaged flows due to wave skewness and asymmetry (alias for setting both facAs and facSk) (XBeach default: 0.1)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
fallvelred: Optional[bool] = Field(default=None, description='Switch to reduce fall velocity for high concentrations (XBeach default: 0)')
class-attribute
instance-attribute
¶
form: Optional[Literal['soulsby_vanrijn', 'vanthiel_vanrijn', 'vanrijn1993']] = Field(default=None, description='Equilibrium sediment concentration formulation (XBeach default: vanthiel_vanrijn)')
class-attribute
instance-attribute
¶
jetfac: Optional[float] = Field(default=None, description='Option to mimic turbulence production near revetments (XBeach default: 0.0)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
lws: Optional[bool] = Field(default=None, description='Switch to enable long wave stirring (XBeach default: 1)')
class-attribute
instance-attribute
¶
lwt: Optional[bool] = Field(default=None, description='Switch to enable long wave turbulence (XBeach default: 0)')
class-attribute
instance-attribute
¶
phit: Optional[float] = Field(default=None, description='Phase lag angle in Nielsen transport equation (XBeach default: 25.0 degrees)', ge=0.0, le=90.0)
class-attribute
instance-attribute
¶
pormax: Optional[float] = Field(default=None, description='Maximum porosity used in the expression of Van Rhee (XBeach default: 0.5)', ge=0.3, le=0.6)
class-attribute
instance-attribute
¶
reposeangle: Optional[float] = Field(default=None, description='Angle of internal friction (XBeach default: 30.0 degrees)', ge=0.0, le=45.0)
class-attribute
instance-attribute
¶
rheeA: Optional[float] = Field(default=None, description='A parameter in the Van Rhee expression (XBeach default: 0.75)', ge=0.75, le=2.0)
class-attribute
instance-attribute
¶
smax: Optional[float] = Field(default=None, description='Maximum shields parameter for equilibrium sediment concentration according to Diane Foster (XBeach default: -1.0, no limit)', ge=-1.0, le=3.0)
class-attribute
instance-attribute
¶
sus: Optional[float] = Field(default=None, description='Calibration factor for suspension transports (XBeach default: 1.0)', ge=0.0)
class-attribute
instance-attribute
¶
sws: Optional[bool] = Field(default=None, description='Switch to enable short wave and roller stirring and undertow (XBeach default: 1)')
class-attribute
instance-attribute
¶
tsfac: Optional[float] = Field(default=None, description='Coefficient determining ts = tsfac * h/ws in sediment source term (XBeach default: 0.1)', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
turb: Optional[Literal['none', 'wave_averaged', 'bore_averaged']] = Field(default=None, description='Switch to include short wave turbulence (XBeach default: wave_averaged)')
class-attribute
instance-attribute
¶
turbadv: Optional[Literal['none', 'lagrangian', 'eulerian']] = Field(default=None, description='Switch to activate turbulence advection model (XBeach default: none)')
class-attribute
instance-attribute
¶
waveform: Optional[Literal['ruessink_vanrijn', 'vanthiel']] = Field(default=None, description='Wave shape model for asymmetry and skewness (XBeach default: vanthiel)')
class-attribute
instance-attribute
¶
z0: Optional[float] = Field(default=None, description='Zero flow velocity level in Soulsby and Van Rijn (1997) sediment concentration (XBeach default: 0.006 m)', ge=0.0001, le=0.05)
Functions¶
no_bore_averaged_with_ruessink_vanrijn() -> SedimentTransport
Bore-averaged turbulence cannot be used with ruessink_vanrijn waveform.
The Ruessink et al. (2012) formulation does not determine an exact wave shape, so the bore interval cannot be calculated. Bore-averaged short-wave turbulence requires the bore interval to be computed from the wave shape.
See: https://xbeach.readthedocs.io/en/latest/xbeach_manual.html#wave-shape
Morphology¶
Bases: XBeachBaseModel
Morphological evolution parameters (XBeach Table 39).
Controls morphological time acceleration (morfac), the period during which morphology is active, avalanching slopes, and non-erodible structures.
The morfac parameter allows decoupling of hydrodynamic and morphological time scales, enabling faster simulation of slow morphological processes.
Avalanching occurs when bed slopes exceed critical values, causing the bed to collapse and slide downward. Different critical slopes apply above and below water due to different effective friction.
References¶
Roelvink, D. (2006). Coastal morphodynamic evolution techniques. Coastal Engineering, 53(2-3), 277-287.
Attributes¶
class-attribute
instance-attribute
¶
morphology: Literal[True] = Field(default=True, description='Turn on morphology (XBeach default: 0)')
class-attribute
instance-attribute
¶
dryslp: Optional[float] = Field(default=None, description='Critical avalanching slope above water (dz/dx and dz/dy) (XBeach default: 1.0)', ge=0.1, le=2.0)
class-attribute
instance-attribute
¶
dzmax: Optional[float] = Field(default=None, description='Maximum bed level change due to avalanching per time step (XBeach default: 0.05 m/s/m)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
hswitch: Optional[float] = Field(default=None, description='Water depth at which is switched from wetslp to dryslp (XBeach default: 0.1 m)', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
lsgrad: Optional[float] = Field(default=None, description='Factor to include longshore transport gradient in 1D simulations. dSy/dy = lsgrad * Sy; dimension 1/length scale of longshore gradients (XBeach default: 0.0 m⁻¹)', ge=-0.1, le=0.1)
class-attribute
instance-attribute
¶
morfac: Optional[float] = Field(default=None, description='Morphological acceleration factor. Multiplies all morphological change by this factor, allowing faster simulation of slow processes (XBeach default: 1.0, no acceleration)', ge=0.0, le=1000.0)
class-attribute
instance-attribute
¶
morfacopt: Optional[bool] = Field(default=None, description='Switch to adjust output times for morfac. If enabled (1), simulation time is shortened by morfac. If disabled (0), simulation runs for full hydrodynamic time (XBeach default: 1)')
class-attribute
instance-attribute
¶
morstart: Optional[float] = Field(default=None, description='Start time for morphology in morphological time (XBeach default: 0.0 s)', ge=0.0)
class-attribute
instance-attribute
¶
morstop: Optional[float] = Field(default=None, description='Stop time for morphology in morphological time (XBeach default: 2000.0 s)', ge=0.0, le=10000000.0)
class-attribute
instance-attribute
¶
ne_layer: Optional[XBeachDataBlob] = Field(default=None, description='Name of file containing thickness of the erodible layer. File format same as bathymetry file. Values define thickness of erodible layer on top of non-erodible layer (m)')
class-attribute
instance-attribute
¶
struct: Optional[bool] = Field(default=None, description='Switch for enabling hard structures (non-erodible layers) (XBeach default: 0)')
class-attribute
instance-attribute
¶
wetslp: Optional[float] = Field(default=None, description='Critical avalanching slope under water (dz/dx and dz/dy) (XBeach default: 0.3)', ge=0.1, le=1.0)
Functions¶
Bed Composition¶
Bases: XBeachBaseModel
Bed composition parameters for sediment properties.
These parameters define the physical properties of the sediment bed including grain size distribution, density, porosity, and layer structure. They are critical for morphological simulations.
XBeach supports multiple sediment classes (ngd > 1) for simulating graded sediments. When using multiple classes, D50 and D90 become lists with one value per class.
The bed is divided into layers with thickness defined by dzg1 (top), dzg2 (variable middle), and dzg3 (bottom). The variable layer (dzg2) can grow or shrink during simulation.
Note¶
For gravel beaches (XBeach-G), use larger grain sizes: - D50: 0.002-0.08 m (default 0.01 m) - D90: 0.003-0.12 m (default 0.015 m)
For sandy beaches, use smaller grain sizes: - D50: 0.00005-0.0008 m (default 0.0002 m) - D90: 0.0001-0.0015 m (default 0.0003 m)
References¶
XBeach manual: Bed composition parameters section.
Attributes¶
class-attribute
instance-attribute
¶
ngd: Optional[int] = Field(default=None, description='Number of sediment classes. Use ngd > 1 for graded sediments (XBeach default: 1)', ge=1, le=20)
class-attribute
instance-attribute
¶
nd: Optional[int] = Field(default=None, description='Number of computational layers in the bed (XBeach default: 3)', ge=3, le=1000)
class-attribute
instance-attribute
¶
D50: Optional[List[float]] = Field(default=None, description='Median grain diameter (m) for each sediment class. For sandy beaches: ~0.0002 m (XBeach default). For gravel beaches: ~0.01 m. Provide a list if ngd > 1.')
class-attribute
instance-attribute
¶
D90: Optional[List[float]] = Field(default=None, description='90th percentile grain diameter (m) for each sediment class. For sandy beaches: ~0.0003 m (XBeach default). For gravel beaches: ~0.015 m. Provide a list if ngd > 1.')
class-attribute
instance-attribute
¶
D15: Optional[List[float]] = Field(default=None, description='15th percentile grain diameter (m) for each sediment class. Only used when dilatancy=1 (XBeach default: 0.00015 m)')
class-attribute
instance-attribute
¶
rhos: Optional[float] = Field(default=None, description='Sediment density (kg/m³) (XBeach default: 2650.0)', ge=2400.0, le=2800.0)
class-attribute
instance-attribute
¶
por: Optional[float] = Field(default=None, description='Bed porosity (volume fraction of voids) (XBeach default: 0.4)', ge=0.3, le=0.5)
class-attribute
instance-attribute
¶
dzg1: Optional[float] = Field(default=None, description='Thickness of top sediment layer (m) (XBeach default: 0.1 m). Also sets default for dzg2 and dzg3 if not specified.', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
dzg2: Optional[float] = Field(default=None, description='Nominal thickness of variable (middle) sediment layer (m). This layer can grow/shrink during simulation (XBeach default: dzg1)', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
dzg3: Optional[float] = Field(default=None, description='Thickness of bottom sediment layer (m) (XBeach default: dzg1)', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
sedcal: Optional[List[float]] = Field(default=None, description='Sediment transport calibration factor for each sediment class (XBeach default: 1.0 for each class)')
class-attribute
instance-attribute
¶
ucrcal: Optional[List[float]] = Field(default=None, description='Critical velocity calibration factor for each sediment class (XBeach default: 1.0 for each class)')
class-attribute
instance-attribute
¶
ws_nonh: Optional[float] = Field(default=None, description='Sediment fall velocity (m/s). Only used in non-hydrostatic mode (wavemodel=nonh). If not specified, XBeach computes this internally from D50 using Ahrens (2000) (XBeach default: 0.0, computed)', ge=0.0, le=1.0)
Functions¶
validate_grain_size_lists() -> BedComposition
Validate that grain size lists match ngd if specified.
validate_d90_greater_than_d50() -> BedComposition
Validate that D90 > D50 for each sediment class.
Groundwater¶
Bases: XBeachBaseModel
Groundwater flow parameters (XBeach Table 41).
Controls groundwater flow processes including Darcy flow permeability, aquifer properties, and groundwater head modeling.
The vertical permeability coefficient can be set differently than the horizontal using kx, ky, and kz keywords. The initial bed level of the aquifer and groundwater head can be specified using external files or uniform values.
References¶
XBeach manual: Grid and bathymetry section for file format details.
Attributes¶
class-attribute
instance-attribute
¶
aquiferbot: Optional[float] = Field(default=None, description='Level of uniform aquifer bottom (XBeach default: -10.0 m)', ge=-100.0, le=100.0)
class-attribute
instance-attribute
¶
aquiferbotfile: Optional[XBeachDataBlob] = Field(default=None, description='Name of the aquifer bottom file. File format same as bathymetry file')
class-attribute
instance-attribute
¶
dwetlayer: Optional[float] = Field(default=None, description='Thickness of the top soil layer interacting more freely with the surface water (XBeach default: 0.1 m)', ge=0.01, le=1.0)
class-attribute
instance-attribute
¶
gw0: Optional[float] = Field(default=None, description='Level of initial groundwater level (XBeach default: 0.0 m)', ge=-5.0, le=5.0)
class-attribute
instance-attribute
¶
gw0file: Optional[XBeachDataBlob] = Field(default=None, description='Name of initial groundwater level file. File format same as bathymetry file')
class-attribute
instance-attribute
¶
gwReturb: Optional[float] = Field(default=None, description='Reynolds number for start of turbulent flow in case of gwscheme = turbulent (XBeach default: 100.0)', ge=1.0, le=600.0)
class-attribute
instance-attribute
¶
gwfastsolve: Optional[bool] = Field(default=None, description='Reduce full 2D non-hydrostatic solution to quasi-explicit in longshore direction (XBeach default: 0)')
class-attribute
instance-attribute
¶
gwheadmodel: Optional[Literal['parabolic', 'exponential']] = Field(default=None, description='Model to use for vertical groundwater head (XBeach default: parabolic)')
class-attribute
instance-attribute
¶
gwhorinfil: Optional[bool] = Field(default=None, description='Switch to include horizontal infiltration from surface water to groundwater (XBeach default: 0)')
class-attribute
instance-attribute
¶
gwnonh: Optional[bool] = Field(default=None, description='Switch to turn on or off non-hydrostatic pressure for groundwater (XBeach default: 0)')
class-attribute
instance-attribute
¶
gwscheme: Optional[Literal['laminar', 'turbulent']] = Field(default=None, description='Scheme for momentum equation (XBeach default: laminar)')
class-attribute
instance-attribute
¶
kx: Optional[float] = Field(default=None, description='Darcy-flow permeability coefficient in x-direction (XBeach default: 0.0001 m/s)', ge=1e-05, le=0.1)
class-attribute
instance-attribute
¶
ky: Optional[float] = Field(default=None, description='Darcy-flow permeability coefficient in y-direction (XBeach default: 0.0001 m/s)', ge=1e-05, le=0.1)
class-attribute
instance-attribute
¶
kz: Optional[float] = Field(default=None, description='Darcy-flow permeability coefficient in z-direction (XBeach default: 0.0001 m/s)', ge=1e-05, le=0.1)
Functions¶
Output¶
Bases: XBeachBaseModel
XBeach output configuration.
XBeach supports four different types of output: 1) instantaneous spatial output 2) time-averaged spatial output 3) fixed point output or 4) run-up gauge output. In principle any variable in XBeach can be outputted as long as it is part of the spaceparams structure defined in variables.f90 in the XBeach source code.
This class simplifies output configuration by using list fields (meanvars,
globalvars, pointvars, points, rugauges) to define variables and locations.
The corresponding count keywords (nmeanvar, nglobalvar, npointvar, npoints,
nrugauge) are automatically set based on list lengths when generating params.txt.
Empty lists disable that output type.
Instantaneous spatial output¶
Instantaneous spatial output (globalvars) describes the instantaneous state of
variables across the entire model domain at various points in time.
Time-averaged spatial output¶
Time-averaged spatial output (meanvars)describes the time-averaged state of
variables across the entire model domain at various points in time. The user can
define the averaging period using the tintm field.
Fixed point output¶
Fixed point output (pointvars) allows the user to select one or more locations for
which a time series of data is stored. This output describes a time-series of one or
more variables at one point in the model domain. To make use of this option, the
user must specify the output locations using the points field describing the
location coordinates given as the x-coordinate and y-coordinate and in world
coordinates. XBeach will link the output location to the nearest computational point.
Run-up gauge output¶
Run-up gauge output describes a time-series of a number of variables at the (moving) waterline. In this case XBeach scans in an x-directional transect defined by the user for the location of the waterline. Output information is recorded for this moving point. This is particularly useful to keep track of run-up levels in cross-shore transects.
The definition of run-up gauges is similar to the definition of fixed point output.
The user needs to specify the run-up gauge locations using the rugauges field,
describing the coordinates of the initial location of the run-up gauge. XBeach will
subsequently link the initial run-up gauge location to the nearest computational
cross-shore transect rather than just the nearest computational point.
Run-up gauges share their selection of output variables with regular point output. However, in the case of run-up gauges, XBeach will automatically also include the variables xw, yw and zs to the point output variables, if these variables were not specified using the npointvar keyword in params.txt. Note that the user should refer to the pointvars.idx output file to check order of output variables for points and run-up gauges.
See https://xbeach.readthedocs.io/en/latest/xbeach_manual.html#output-selection for more information.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
outputformat: Optional[Literal['fortran', 'netcdf', 'debug']] = Field(default='netcdf', description='Output file format (XBeach default: fortran)')
class-attribute
instance-attribute
¶
outputprecision: Optional[Literal['single', 'double']] = Field(default=None, description='Netcdf output precision (XBeach default: double)')
class-attribute
instance-attribute
¶
ncfilename: Optional[str] = Field(default=None, description='Xbeach netcdf output file name (XBeach default: xboutput.nc)')
class-attribute
instance-attribute
¶
meanvars: list[OutputVarsEnum] = Field(default=[], description='Mean output variables (sets `nmeanvar` and variable list in params.txt)')
class-attribute
instance-attribute
¶
globalvars: list[OutputVarsEnum] = Field(default=[], description='Global output variables (sets `nglobalvar` and variable list in params.txt)')
class-attribute
instance-attribute
¶
points: list[tuple[float, float]] = Field(default=[], description='Point locations as (x, y) coordinate pairs (sets `npoints` and point coordinates in params.txt)')
class-attribute
instance-attribute
¶
pointvars: list[OutputVarsEnum] = Field(default=[], description='Point output variables (sets `npointvar` and variable list in params.txt)')
class-attribute
instance-attribute
¶
rugauges: list[tuple[float, float]] = Field(default=[], description='Runup gauge locations as (x, y) coordinate pairs (sets `nrugauge` and gauge coordinates in params.txt)')
class-attribute
instance-attribute
¶
nrugdepth: Optional[int] = Field(default=None, description='Number of depths to compute runup in runup gauge', ge=1, le=10)
class-attribute
instance-attribute
¶
rugdepth: Optional[float] = Field(default=None, description='Minimum depth for determination of last wet point in runup gauge (XBeach default: 0)', ge=0, le=0.1)
class-attribute
instance-attribute
¶
timings: Optional[bool] = Field(default=None, description='Switch enable progress output to screen (XBeach default: True)')
class-attribute
instance-attribute
¶
tstart: Optional[float] = Field(default=None, description='Start time (s) of output, in morphological time (XBeach default: 0)', ge=0.0)
class-attribute
instance-attribute
¶
tintc: Optional[float] = Field(default=None, description='Interval time (s) of cross section output (XBeach default: -123)', gt=0.0)
class-attribute
instance-attribute
¶
tintg: Optional[float] = Field(default=None, description='Interval time (s) of global output (XBeach default: 1), the first output is given at tstart', gt=0.0)
class-attribute
instance-attribute
¶
tintm: Optional[float] = Field(default=None, description='Interval time (s) of mean, var, max, min output (XBeach default: tstop - tstart), the first output is given at tstart+tintm and represents the average condition over the interval between tstart and tstart+tintm', gt=0.0)
class-attribute
instance-attribute
¶
tintp: Optional[float] = Field(default=None, description='Interval time (s) of point and runup gauge output (XBeach default: the value defined for tintg), the first output is given at tstart', gt=0.0)
class-attribute
instance-attribute
¶
tinth: Optional[float] = Field(default=None, description='Output interval (s) for writing hotstart files (XBeach default: 0). If not specified or 0, hotstart is written only at the end of simulation.', ge=0.0)
class-attribute
instance-attribute
¶
writehotstart: Optional[bool] = Field(default=None, description='Write hotstart files during simulation (XBeach default: 0). Hotstart files can be used to initialize a subsequent simulation.')
class-attribute
instance-attribute
¶
tsglobal: Optional[XBeachDataBlob] = Field(default=None, description='File source containing timings of global output')
class-attribute
instance-attribute
¶
tsmean: Optional[XBeachDataBlob] = Field(default=None, description='File source containing timings of mean, max, min and var output')
class-attribute
instance-attribute
¶
tspoint: Optional[XBeachDataBlob] = Field(default=None, description='File source containing timings of point output')
class-attribute
instance-attribute
¶
projection: Optional[str] = Field(default=None, description='Projection string specifying the coordinate reference system. Stored in netCDF output file as metadata. Does not influence model results.')
class-attribute
instance-attribute
¶
remdryoutput: Optional[bool] = Field(default=None, description='Switch to remove dry output points from output data of zs etc (XBeach default: 1)')
class-attribute
instance-attribute
¶
rotate: Optional[bool] = Field(default=None, description='Switch to rotate output as postprocessing with angle specified by grid alfa (XBeach default: 1)')
Functions¶
classmethod
¶
Validate that variable lists don't contain duplicates.
classmethod
¶
Validate that variable lists don't exceed XBeach limits.
validate_point_output_consistency() -> Output
Validate consistency between pointvars and point/rugauge locations.
fixed_or_file_times() -> Output
Validate that either fixed times or file times are specified.
Transforms variable lists into XBeach params format with count keys.
Fetch external timing files if specified, and return the params dict.
Boundaries¶
Flow Boundaries¶
Bases: XBeachBaseModel
Flow boundary condition parameters for shallow water equations.
Controls boundary conditions at all domain boundaries: offshore (front), bay side (back), and lateral (left/right). These parameters determine how flow, water levels, and waves interact with the domain boundaries.
The default absorbing-generating (abs_2d) boundary condition is recommended for most applications as it allows waves to pass through with minimal reflection.
Attributes¶
class-attribute
instance-attribute
¶
front: Optional[FrontType] = Field(default=None, description='Seaward boundary condition type. abs_1d/abs_2d = absorbing-generating (weakly-reflective), wall = no flux, wlevel = water level specification, nonh_1d = non-hydrostatic, waveflume = flume experiments (XBeach default: abs_2d)')
class-attribute
instance-attribute
¶
back: Optional[BackType] = Field(default=None, description='Bay side boundary condition type. wall = no flux, abs_1d/abs_2d = absorbing-generating, wlevel = water level specification (XBeach default: abs_2d)')
class-attribute
instance-attribute
¶
left: Optional[LeftRightType] = Field(default=None, description='Lateral boundary at ny+1. neumann = no gradient, wall = no flux, no_advec = advective terms only, neumann_v = copy velocity from adjacent cell, abs_1d = absorbing (XBeach default: neumann)')
class-attribute
instance-attribute
¶
right: Optional[LeftRightType] = Field(default=None, description='Lateral boundary at 0. neumann = no gradient, wall = no flux, no_advec = advective terms only, neumann_v = copy velocity from adjacent cell, abs_1d = absorbing (XBeach default: neumann)')
class-attribute
instance-attribute
¶
lateralwave: Optional[LateralWaveType] = Field(default=None, description='Lateral wave boundary type. neumann = zero longshore gradient (may cause shadow zones), wavecrest = zero gradient along wave crest (better for surfbeat), cyclic = periodic boundary (XBeach default: neumann)')
class-attribute
instance-attribute
¶
nc: Optional[int] = Field(default=None, description='Smoothing distance for estimating mean current (umean) at the offshore boundary, defined as number of grid cells (XBeach default: ny+1)', ge=1)
class-attribute
instance-attribute
¶
highcomp: Optional[bool] = Field(default=None, description='Switch for high-order compensation at the boundary. Enables additional correction terms for improved accuracy (XBeach default: 0)')
Tide Boundaries¶
Bases: XBeachBaseModel
Tide and surge boundary condition parameters.
Controls how tidal and surge water levels are applied at the domain boundaries. XBeach supports up to four time-varying tidal signals applied to the four corners (offshore-right, offshore-left, backshore-left, backshore-right).
The tideloc parameter determines how many tide signals are used: - 0: Uniform water level (zs0 value applied everywhere) - 1: One time-varying signal (applied to offshore boundary) - 2: Two time-varying signals (requires paulrevere to specify application) - 4: Four time-varying signals (one per corner)
Attributes¶
class-attribute
instance-attribute
¶
tideloc: Optional[TideLocType] = Field(default=None, description='Number of tide/surge boundary locations. 0 = uniform water level (zs0), 1 = one signal at offshore, 2 = two signals (sea/land corners), 4 = four signals (all corners) (XBeach default: 0 if zs0 set, else 2)')
class-attribute
instance-attribute
¶
tidetype: Optional[TideTypeType] = Field(default=None, description='Type of tide boundary condition. instant = instantaneous water level, velocity = velocity boundary, hybrid = combination (XBeach default: velocity)')
class-attribute
instance-attribute
¶
zs0: Optional[float] = Field(default=None, description='Initial/constant water level (m). Used when tideloc=0 for uniform water level, or as backshore boundary value when tideloc=1 (XBeach default: 0.0)', ge=-5.0, le=5.0)
class-attribute
instance-attribute
¶
paulrevere: Optional[PaulRevereType] = Field(default=None, description='Specifies which boundary receives tide signals when tideloc=2. land = one signal to land corners, one to sea corners; sea = opposite assignment (XBeach default: land)')
Wave Boundaries¶
Bases: WaveBoundary
Spectral wave boundary specification.
For spectral boundary types: jons, parametric, swan, vardens, jonstable. These always require a boundary file containing spectral information.
Examples¶
JONSWAP boundary with pre-existing file¶
boundary = SpectralWaveBoundary( ... wbctype="jons", ... bcfile="jonswap.txt", ... wbc=SpectralWaveBoundaryConditions( ... nmax=0.8, ... rt=3600.0, ... dtbc=1.0, ... ) ... )
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['spectral'] = Field(default='spectral', description='Model type discriminator for spectral wave boundaries')
class-attribute
instance-attribute
¶
wbctype: Literal['jons', 'parametric', 'swan', 'vardens', 'jonstable'] = Field(description='Spectral wave boundary type (jons, parametric, swan, vardens, jonstable)')
class-attribute
instance-attribute
¶
bcfile: str = Field(description='Path to spectral boundary file (required for spectral boundaries)')
class-attribute
instance-attribute
¶
wbc: Optional[SpectralWaveBoundaryConditions] = Field(default=None, description='Spectral wave boundary parameters')
Bases: WaveBoundary
Non-spectral wave boundary specification.
For non-spectral boundary types: stat, stat_table, ts_1, ts_2, ts_nonh, bichrom.
File requirements: - stat: No file needed (parameters only) - bichrom: No file needed (parameters only) - stat_table: Requires JONSWAP table format file - ts_1, ts_2: Requires bc/gen.ezs file (time, zs, E) - ts_nonh: Requires Boun_u.bcf file (t, U, Zs, W)
Examples¶
Stationary waves (no file needed)¶
boundary = NonSpectralWaveBoundary( ... wbctype="stat", ... wbc=NonSpectralWaveBoundaryConditions( ... Hrms=2.0, ... Trep=12.0, ... dir0=285.0, ... m=10, ... ) ... )
Time series (file required)¶
boundary = NonSpectralWaveBoundary( ... wbctype="ts_1", ... bcfile="bc/gen.ezs", ... wbc=NonSpectralWaveBoundaryConditions( ... Hrms=2.0, ... Trep=12.0, ... ) ... )
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['nonspectral'] = Field(default='nonspectral', description='Model type discriminator for non-spectral wave boundaries')
class-attribute
instance-attribute
¶
wbctype: Literal['stat', 'stat_table', 'ts_1', 'ts_2', 'ts_nonh', 'bichrom'] = Field(description='Non-spectral wave boundary type (stat, stat_table, ts_1, ts_2, ts_nonh, bichrom)')
class-attribute
instance-attribute
¶
bcfile: Optional[str] = Field(default=None, description='Path to boundary file (required for stat_table, ts_1, ts_2, ts_nonh)')
class-attribute
instance-attribute
¶
wbc: Optional[NonSpectralWaveBoundaryConditions] = Field(default=None, description='Non-spectral wave boundary parameters')
Functions¶
Hotstart¶
Bases: XBeachBaseModel
Hotstart configuration for initializing from previous simulation state.
XBeach can read hotstart files from a previous simulation to initialize a new simulation, avoiding spin-up time. Hotstart files follow the naming convention: hotstart_{varname}{fileno:06d}.dat
The minimum required files are: zs, zb, uu, vv (always written/read). Additional files may be present depending on the simulation options (groundwater, wave energy, sediment, etc.).
Usage in Config
hotstart: false # No hotstart (default) hotstart: true # Enable hotstart, files must exist in run directory hotstart: # Full hotstart configuration hotstartfileno: 3 source: source: /path/to/previous/run
See https://xbeach.readthedocs.io/en/latest/xbeach_manual.html#hotstart-beta for more information.
Attributes¶
class-attribute
instance-attribute
¶
hotstart: Literal[True] = Field(default=True, description='Initialize simulation with hotstart files (XBeach default: 0)')
class-attribute
instance-attribute
¶
hotstartfileno: int = Field(default=0, description='Hotstart file number to use for initialization. Selects which set of hotstart files to read when multiple snapshots exist (0-999).', ge=0, le=999)
class-attribute
instance-attribute
¶
source: Optional[XBeachHotstartBlob] = Field(default=None, description='Directory containing hotstart files from a previous XBeach simulation. If not specified, hotstart files must already exist in the run directory.')
Functions¶
MPI¶
Bases: XBeachBaseModel
MPI parallelisation parameters (XBeach Table 45).
Controls how the model domain is subdivided into sub-models for parallel execution on multiple cores. Each sub-model is computed on a separate core, which increases computational speed. Sub-models only exchange information over their boundaries when necessary.
The domain subdivision strategy is controlled by mpiboundary:
- auto: Subdivides domain to minimise internal boundary length
- x: Subdivides in cross-shore direction (full alongshore extent per domain)
- y: Subdivides in alongshore direction (full cross-shore extent per domain)
- man: Manual subdivision using mmpi and nmpi values
Note¶
The number of sub-models is determined by the MPI wrapper (e.g., MPICH2 or OpenMPI), not by XBeach itself.
References¶
XBeach manual: MPI section for parallelisation details.
Attributes¶
class-attribute
instance-attribute
¶
mmpi: Optional[int] = Field(default=None, description='Number of domains in cross-shore direction when manually specifying MPI domains (XBeach default: 2)', ge=1, le=100)
class-attribute
instance-attribute
¶
mpiboundary: Optional[Literal['auto', 'x', 'y', 'man']] = Field(default=None, description='Strategy for MPI domain boundaries: auto (shortest boundary), x (cross-shore subdivision), y (alongshore subdivision), or man (manual using mmpi/nmpi) (XBeach default: auto)')
class-attribute
instance-attribute
¶
nmpi: Optional[int] = Field(default=None, description='Number of domains in alongshore direction when manually specifying MPI domains (XBeach default: 4)', ge=1, le=100)