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')
Functions¶
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, ... )
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
Stationary parametric wave boundary conditions.
Defines wave conditions using bulk parameters (Hrms, Trep, dir0, m) without requiring any external files. XBeach generates the wave forcing internally.
Examples¶
boundary = BoundaryStat( ... Hrms=2.0, ... Trep=12.0, ... dir0=270.0, ... m=10, ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
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
¶
Functions¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for stationary wave boundary.
Parameters¶
destdir : str | Path Destination directory (not used for stat, but required for interface). grid : RegularGrid, optional Grid instance (not used for stat). time : TimeRange, optional Time range (not used for stat).
Returns¶
dict XBeach parameters including wbctype and wave parameters.
Bases: WaveBoundaryParams
Bichromatic wave boundary conditions.
Defines bichromatic wave conditions using bulk parameters including the long wave period (Tlong). No external files required.
Examples¶
boundary = BoundaryBichrom( ... Hrms=1.5, ... Trep=10.0, ... Tlong=80.0, ... dir0=270.0, ... m=10, ... )
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
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
¶
Functions¶
get(destdir: str | Path, grid: RegularGrid = None, time: TimeRange = None) -> dict
Return XBeach parameters for bichromatic wave boundary.
Parameters¶
destdir : str | Path Destination directory (not used for bichrom, but required for interface). grid : RegularGrid, optional Grid instance (not used for bichrom). time : TimeRange, optional Time range (not used for bichrom).
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')
Functions¶
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)')
Functions¶
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)')
Functions¶
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)')
Functions¶
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()
Bases: SpectralWaveBoundaryParams
Reuse previous boundary conditions.
Makes XBeach reuse wave time series from a previous simulation. Requires the ebcflist.bcf and qbcflist.bcf files from a previous run. The source field should point to the directory containing these files.
XBeach automatically looks for ebcflist.bcf and qbcflist.bcf in the run directory - no bcfile parameter is needed in params.txt.
.. note:: TODO: The ebcflist.bcf and qbcflist.bcf files reference additional files (typically with E_ and q_ prefixes) that also need to be present in the workspace. Currently these referenced files are not automatically fetched. Users must ensure all referenced files are available in the source directory.
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.')
Functions¶
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
¶
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.