Data API¶
API reference for data interfaces that generate boundary conditions from external sources.
Wave Boundaries¶
JONS Boundary Type¶
Bases: SpectraMixin, BoundaryJonsBase, SpectralWaveBoundaryParams, BoundaryBaseStation
Wave boundary conditions from station type spectra dataset such as SMC.
Bases: ParamMixin, BoundaryJonsBase, SpectralWaveBoundaryParams, BoundaryBaseStation
Wave boundary conditions from station type parameters dataset such as SMC.
Attributes¶
class-attribute
instance-attribute
¶
source: SOURCE_PARAM_TYPES = Field(description='Dataset source reader, must support CRS', discriminator='model_type')
class-attribute
instance-attribute
¶
model_type: Literal['station_param_jons'] = Field(default='station_param_jons', description='Model type discriminator')
Bases: ParamMixin, BoundaryJonsBase, SpectralWaveBoundaryParams, BoundaryBasePoint
Wave boundary conditions from point timeseries type parameters dataset.
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['point_param_jons'] = Field(default='point_param_jons', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: SOURCE_TIMESERIES_TYPES = Field(description='Dataset source reader for point timeseries type data', discriminator='model_type')
Bases: ParamMixin, BoundaryJonsBase, SpectralWaveBoundaryParams, BoundaryBaseGrid
Wave boundary conditions from grid type parameters dataset.
Attributes¶
class-attribute
instance-attribute
¶
source: SOURCE_PARAM_TYPES = Field(description='Dataset source reader, must support CRS', discriminator='model_type')
class-attribute
instance-attribute
¶
model_type: Literal['grid_param_jons'] = Field(default='grid_param_jons', description='Model type discriminator')
JONSTABLE Boundary Type¶
Bases: SpectraMixin, BoundaryJonstableBase, SpectralWaveBoundaryParams, BoundaryBaseStation
Wave boundary conditions from station type spectra dataset such as SMC.
Bases: ParamMixin, BoundaryJonstableBase, SpectralWaveBoundaryParams, BoundaryBaseStation
Wave boundary conditions from station type parameters dataset such as SMC.
Attributes¶
class-attribute
instance-attribute
¶
source: SOURCE_PARAM_TYPES = Field(description='Dataset source reader, must support CRS', discriminator='model_type')
class-attribute
instance-attribute
¶
model_type: Literal['station_param_jonstable'] = Field(default='station_param_jonstable', description='Model type discriminator')
Bases: ParamMixin, BoundaryJonstableBase, SpectralWaveBoundaryParams, BoundaryBasePoint
Wave boundary conditions from point timeseries type parameters dataset.
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['point_param_jonstable'] = Field(default='point_param_jonstable', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: SOURCE_TIMESERIES_TYPES = Field(description='Dataset source reader for point timeseries type data', discriminator='model_type')
Bases: ParamMixin, BoundaryJonstableBase, SpectralWaveBoundaryParams, BoundaryBaseGrid
Generate XBeach JONSTABLE wave boundary conditions from gridded parameter data.
This class reads wave parameters (Hm0, Tp, Dir, Spread, Gamma) from a gridded data source, selects/interpolates the data at the offshore boundary location of the XBeach grid, and writes the time-varying parameters to a JONSTABLE format file.
Attributes¶
class-attribute
instance-attribute
¶
source: SOURCE_PARAM_TYPES = Field(description='Dataset source reader, must support CRS', discriminator='model_type')
class-attribute
instance-attribute
¶
model_type: Literal['grid_param_jonstable'] = Field(default='grid_param_jonstable', description='Model type discriminator')
SWAN Boundary Type¶
Bases: FilelistMixin, SpectraMixin, SpectralWaveBoundaryParams, BoundaryBaseStation
SWAN wave boundary from station type spectra dataset.
XBeach assumes the directional information in the SWAN file is according to the nautical convention. If the file uses the Cartesian convention for directions, the user must specify the angle in degrees to rotate the x-axis in SWAN to the x-axis in XBeach (by the Cartesian convention). This value is specified in params.txt using the keyword dthetaS_XB.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
model_type: Literal['station_spectra_swan'] = Field(default='station_spectra_swan', description='Model type discriminator')
Methods:¶
Instantiate the boundary file writer object.
Parameters¶
data : xr.Dataset Dataset containing single time for the boundary spectral data.
get(destdir: str | Path, grid: RegularGrid, time: Optional[TimeRange] = None) -> dict
Write the selected boundary data to file.
Parameters¶
destdir : str | Path
Destination directory for the boundary files.
grid : RegularGrid
Grid instance to use for selecting the boundary points.
time: TimeRange, optional
The times to filter the data to, only used if self.crop_data is True.
Returns¶
dict XBeach parameters including wbctype, bcfile, and wave boundary settings.
File-Based Boundaries¶
For using pre-existing boundary files:
Bases: FilelistMixin, BoundaryFileSpectralBase
JONSWAP boundary from pre-existing bcfile(s).
Use this class when you have existing JONSWAP boundary files created outside of rompy (e.g., manually or from another tool).
If filelist=True, the source bcfile is expected to be a FILELIST file, and
all files referenced within it will also be fetched from the same directory.
Examples¶
from rompy_xbeach.types import XBeachDataBlob
Single bcfile¶
boundary = BoundaryFileJons( ... bcfile_source=XBeachDataBlob(source="/path/to/bcfile"), ... )
FILELIST with multiple bcfiles¶
boundary = BoundaryFileJons( ... bcfile_source=XBeachDataBlob(source="/path/to/bcfile"), ... filelist=True, ... )
Attributes¶
class-attribute
instance-attribute
¶
id: Literal['parametric'] = Field(default='parametric', description='Boundary type identifier, the XBeach wbctype for JONSWAP spectra')
class-attribute
instance-attribute
¶
model_type: Literal['file_jons'] = Field(default='file_jons', description='Model type discriminator')
Bases: BoundaryFileSpectralBase
JONSTABLE boundary from pre-existing bcfile.
Use this class when you have an existing JONSTABLE boundary file created outside of rompy (e.g., manually or from another tool).
JONSTABLE files are always single files (no FILELIST support needed).
Examples¶
from rompy_xbeach.types import XBeachDataBlob boundary = BoundaryFileJonstable( ... bcfile_source=XBeachDataBlob(source="/path/to/jonstable.txt"), ... )
Bases: FilelistMixin, BoundaryFileSpectralBase
SWAN spectral boundary from pre-existing bcfile(s).
Use this class when you have existing SWAN spectral boundary files created outside of rompy (e.g., manually or from another tool).
If filelist=True, the source bcfile is expected to be a FILELIST file, and
all files referenced within it will also be fetched from the same directory.
Examples¶
from rompy_xbeach.types import XBeachDataBlob
Single bcfile¶
boundary = BoundaryFileSwan( ... bcfile_source=XBeachDataBlob(source="/path/to/swan_spectrum.txt"), ... )
FILELIST with multiple bcfiles¶
boundary = BoundaryFileSwan( ... bcfile_source=XBeachDataBlob(source="/path/to/filelist.txt"), ... filelist=True, ... )
Non-Spectral Boundaries¶
Bases: WaveBoundaryParams
Wave boundary conditions from bulk parameters (wbctype=params).
Defines constant wave conditions using bulk parameters (Hrms, Trep, dir0, m)
without requiring any external files. XBeach generates the wave forcing
internally. When Tlong is set, XBeach generates bichromatic waves with wave
groups of period Tlong instead, which is only allowed with the surfbeat wave
model.
Examples¶
Constant wave conditions:
boundary = BoundaryParams(Hrms=2.0, Trep=12.0, dir0=270.0, m=10)
Bichromatic wave groups:
boundary = BoundaryParams(Hrms=1.5, Trep=10.0, Tlong=80.0)
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
Tlong: Optional[float] = Field(default=None, description='Wave group period (s). When set, XBeach generates bichromatic waves, which requires the surfbeat wave model (XBeach default: not set, constant wave conditions)', ge=20.0, le=300.0)
class-attribute
instance-attribute
¶
dir0: float = Field(default=270.0, description='Mean wave direction, nautical convention (degrees)', ge=-360.0, le=360.0)
class-attribute
instance-attribute
¶
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for the wave boundary.
Parameters¶
destdir : str | Path Destination directory (not used, but required for interface). grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters including wbctype and wave parameters.
Bases: WaveBoundaryParams
Time-varying parametric wave boundary from stat_table file.
Requires a file with time-varying Hrms, Tp, direction, etc. in JONSWAP table format.
Examples¶
from rompy_xbeach.types import XBeachDataBlob boundary = BoundaryStatTable( ... source=XBeachDataBlob(source="/path/to/stat_table.txt"), ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
model_type: Literal['file_stat_table'] = Field(default='file_stat_table', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: XBeachDataBlob = Field(description='Source for stat_table boundary file')
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for stat_table wave boundary.
Parameters¶
destdir : str | Path Destination directory for boundary files. grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters including wbctype, bcfile, and wave parameters.
Bases: WaveBoundaryParams
Time series wave boundary at single location (ts_1).
Requires a bc/gen.ezs file with columns: time, zs, E. The file will be fetched to destdir/bc/ subdirectory.
Examples¶
from rompy_xbeach.types import XBeachDataBlob boundary = BoundaryTs1( ... source=XBeachDataBlob(source="/path/to/gen.ezs"), ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
model_type: Literal['file_ts_1'] = Field(default='file_ts_1', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: XBeachDataBlob = Field(description='Source for time series boundary file (bc/gen.ezs format)')
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for ts_1 wave boundary.
Parameters¶
destdir : str | Path Destination directory for boundary files. grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters including wbctype, bcfile, and wave parameters.
Bases: WaveBoundaryParams
Time series wave boundary at two locations (ts_2).
Requires a bc/gen.ezs file with columns: time, zs, E. The file will be fetched to destdir/bc/ subdirectory.
Examples¶
from rompy_xbeach.types import XBeachDataBlob boundary = BoundaryTs2( ... source=XBeachDataBlob(source="/path/to/gen.ezs"), ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
model_type: Literal['file_ts_2'] = Field(default='file_ts_2', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: XBeachDataBlob = Field(description='Source for time series boundary file (bc/gen.ezs format)')
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for ts_2 wave boundary.
Parameters¶
destdir : str | Path Destination directory for boundary files. grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters including wbctype, bcfile, and wave parameters.
Bases: WaveBoundaryParams
Non-hydrostatic time series wave boundary (ts_nonh).
Requires a Boun_u.bcf file with columns: scalar/vector, t, U, Zs, W.
Examples¶
from rompy_xbeach.types import XBeachDataBlob boundary = BoundaryTsNonh( ... source=XBeachDataBlob(source="/path/to/Boun_u.bcf"), ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
model_type: Literal['file_ts_nonh'] = Field(default='file_ts_nonh', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: XBeachDataBlob = Field(description='Source for non-hydrostatic time series boundary file (Boun_u.bcf format)')
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for ts_nonh wave boundary.
Parameters¶
destdir : str | Path Destination directory for boundary files. grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters including wbctype, bcfile, and wave parameters.
Special Boundaries¶
Bases: WaveBoundaryParams
No wave forcing.
Use this when you don't want any wave forcing in the model.
Examples¶
boundary = BoundaryOff()
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for no wave boundary.
Parameters¶
destdir : str | Path Destination directory (not used, but required for interface). grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters with wbctype='off' and wave boundary settings.
Bases: SpectralWaveBoundaryParams
Reuse previous boundary conditions.
Makes XBeach reuse wave time series from a previous simulation. The list files ebcflist.bcf and qbcflist.bcf (and esbcflist.bcf when the previous run used single_dir), and the series files they reference, are copied from the previous run directory into the workspace.
XBeach automatically looks for these files in the run directory - no bcfile parameter is needed in params.txt.
Examples¶
from rompy_xbeach.types import XBeachDirectoryBlob boundary = BoundaryReuse( ... previous_run=XBeachDirectoryBlob(source="/path/to/previous/run") ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
previous_run: XBeachDirectoryBlob = Field(description='Directory containing ebcflist.bcf and qbcflist.bcf files from a previous XBeach simulation.')
Methods:¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for reuse wave boundary.
Parameters¶
destdir : str | Path Destination directory where boundary files will be fetched. grid : RegularGrid, optional Grid instance (not used). time : TimeRange, optional Time range (not used).
Returns¶
dict XBeach parameters with wbctype='reuse' and wave boundary settings.
Base Parameter Classes¶
Bases: RompyBaseModel
Base wave boundary condition parameters.
These are general parameters that apply to ALL wave boundary condition types, whether spectral (jons, swan, vardens, jonstable) or non-spectral (stat, ts_1, ts_2, ts_nonh, bichrom).
The boundary conditions affect wave generation, energy scaling, and the treatment of Stokes drift and wave group variance at the boundary.
Attributes¶
class-attribute
instance-attribute
¶
nmax: Optional[float] = Field(default=None, description='Maximum ratio of cg/c for computing long wave boundary conditions (XBeach default: 0.8)', ge=0.5, le=1.0)
class-attribute
instance-attribute
¶
wbcevarreduce: Optional[float] = Field(default=None, description='Reduction factor of short-wave group variance at the boundary (XBeach default: 1.0, no reduction)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
bclwonly: Optional[bool] = Field(default=None, description='Switch to run boundary conditions with long waves only (XBeach default: 0)')
class-attribute
instance-attribute
¶
swkhmin: Optional[float] = Field(default=None, description='Minimum kh value to include in wave action balance. Waves with lower kh are included in NLSWE instead (XBeach default: -0.01)', ge=-0.01, le=0.35)
class-attribute
instance-attribute
¶
wbcRemoveStokes: Optional[bool] = Field(default=None, description='Switch to remove long wave Stokes drift component at the offshore boundary (XBeach default: 1)')
class-attribute
instance-attribute
¶
wbcScaleEnergy: Optional[bool] = Field(default=None, description='Switch to correct random time series of wave height to exactly match input Hm0 (XBeach default: 1)')
class-attribute
instance-attribute
¶
cyclicdiradjust: Optional[bool] = Field(default=None, description='Adjust alongshore wave length to fit inside domain with cyclic boundary conditions (XBeach default: 0)')
class-attribute
instance-attribute
¶
taper: Optional[float] = Field(default=None, description='Spin-up time of wave boundary conditions, in morphological time (XBeach default: 100.0)', ge=0.0, le=1000.0, examples=[100.0])
class-attribute
instance-attribute
¶
ARC: Optional[bool] = Field(default=None, description='Switch for active reflection compensation at seaward boundary. Compensates for spurious long wave reflection (XBeach default: 1)')
class-attribute
instance-attribute
¶
freewave: Optional[bool] = Field(default=None, description='Switch for free wave propagation at the boundary. When enabled, assumes incoming long waves propagate at sqrt(gh) instead of group velocity cg. Affects absorbing/radiating boundary calculations (XBeach default: 0)')
class-attribute
instance-attribute
¶
thetamin: Optional[float] = Field(default=None, description='Minimum wave angle (degrees). When thetanaut=0, this is relative to the grid x-axis (shore-normal); when thetanaut=1, this is in nautical convention (N=0°, E=90°). Only used when swave=1 (XBeach default: -90.0)', ge=-360.0, le=360.0)
class-attribute
instance-attribute
¶
thetamax: Optional[float] = Field(default=None, description='Maximum wave angle (degrees). When thetanaut=0, this is relative to the grid x-axis (shore-normal); when thetanaut=1, this is in nautical convention (N=0°, E=90°). Only used when swave=1 (XBeach default: 90.0)', ge=-360.0, le=360.0)
class-attribute
instance-attribute
¶
dtheta: Optional[float] = Field(default=None, description='Wave directional resolution (degrees). Automatically computed from thetamax-thetamin when single_dir=1. Only used when swave=1 (XBeach default: 10.0)', ge=0.1, le=180.0)
class-attribute
instance-attribute
¶
dtheta_s: Optional[float] = Field(default=None, description='Directional resolution (degrees) of the stationary refraction model used when single_dir=1, which is the XBeach default for surfbeat on 2D grids. Required by XBeach in that case. Only used when swave=1 (XBeach default: 10.0)', ge=0.1, le=20.0)
class-attribute
instance-attribute
¶
thetanaut: Optional[bool] = Field(default=None, description='Switch for wave direction convention. When 0 (default), wave angles are relative to the grid x-axis and rotated by alfa internally. When 1, wave angles are in nautical convention (N=0°, E=90°) using real-world coordinates and alfa is ignored. Only used when swave=1 (XBeach default: 0)')
class-attribute
instance-attribute
¶
order: Optional[Literal[1, 2]] = Field(default=None, description='Order of wave steering at the boundary. 1 = first-order (short wave energy only), 2 = second-order (bound long wave corresponding to short wave forcing is added) (XBeach default: 2)')
Bases: WaveBoundaryParams
Spectral wave boundary condition parameters.
These parameters are specific to spectral boundary conditions (wbctype = jons, swan, vardens, jonstable). They control how wave spectra are generated and applied at the offshore boundary.
Inherits all general wave boundary parameters from WaveBoundaryParams.
Attributes¶
class-attribute
instance-attribute
¶
rt: Optional[float] = Field(default=None, description='Duration (s) of wave spectrum at offshore boundary, in morphological time (XBeach default: min(3600.d0, tstop))', ge=1200.0, le=7200.0, examples=[3600.0])
class-attribute
instance-attribute
¶
dtbc: Optional[float] = Field(default=1.0, description='Timestep (s) used to describe time series of wave energy and long wave flux at offshore boundary (not affected by morfac) (XBeach default: 1.0)', ge=0.1, le=2.0, examples=[1.0])
class-attribute
instance-attribute
¶
dthetas_xb: Optional[float] = Field(default=None, description=('The (counter-clockwise) angle in the degrees needed to rotate from the x-axis in swan to the x-axis pointing east (XBeach default: 0.0)',), ge=-360.0, le=360.0)
class-attribute
instance-attribute
¶
tm01switch: Optional[bool] = Field(default=None, description='Switch to enable tm01 rather than tm-10 (XBeach default: 0)')
class-attribute
instance-attribute
¶
correcthm0: Optional[bool] = Field(default=None, description='Switch to enable hm0 correction (XBeach default: 1)')
class-attribute
instance-attribute
¶
fcutoff: Optional[float] = Field(default=None, description='Low-freq cutoff frequency in Hz for jons, swan or vardens boundary conditions (XBeach default: 0.0)', ge=0.0, le=40.0)
class-attribute
instance-attribute
¶
nonhspectrum: Optional[Literal[0, 1]] = Field(default=None, description='Spectrum format for wave action balance of nonhydrostatic waves (XBeach default: 0)')
class-attribute
instance-attribute
¶
nspectrumloc: Optional[int] = Field(default=None, description='Number of input spectrum locations (XBeach default: 1)', ge=1)
class-attribute
instance-attribute
¶
nspr: Optional[bool] = Field(default=None, description=('Switch to enable long wave direction forced into centres of short wave bins (XBeach default: 0)',))
class-attribute
instance-attribute
¶
random: Optional[bool] = Field(default=None, description=('Switch to enable random seed for jons, swan or vardens boundary conditions (XBeach default: 1)',))
class-attribute
instance-attribute
¶
sprdthr: Optional[float] = Field(default=None, description='Threshold ratio to maximum value of s above which spectrum densities are read in (XBeach default: 0.08)', ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
trepfac: Optional[float] = Field(default=None, description=('Compute mean wave period over energy band: par%trepfac*maxval(sf) for jons, swan or vardens; converges to tm01 for trepfac = 0.0 (XBeach default: 0.01)',), ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
wbcversion: Optional[Literal[1, 2, 3]] = Field(default=None, description='Version of wave boundary conditions (XBeach default: 3)')
Tide / Water Level¶
Tidal Constituents¶
Bases: TideConsBase, BaseDataGrid
Water level forcing from gridded tide cons processed with oceantide.
Attributes¶
class-attribute
instance-attribute
¶
model_type: Literal['tide_cons_grid'] = Field(default='tide_cons_grid', description='Model type discriminator')
class-attribute
instance-attribute
¶
source: SourceCRSOceantide = Field(description='Source of the tide data')
Bases: TideConsBase, BaseDataPoint
Water level forcing from single tide cons point processed with oceantide.
Water Level Timeseries¶
Wind¶
Bases: WindMixin, BaseDataStation
Wind forcing from station data.
Namelist¶
- windfile : str Name of file with non-stationary wind data.