SCHISM Boundary Conditions#

Overview#

The SCHISM boundary conditions system provides a unified interface for configuring all types of boundary conditions in SCHISM simulations. This system replaces the previous separate tidal and ocean configurations with a single, flexible approach that supports:

Harmonic boundaries - Pure harmonic tidal forcing using tidal constituents
Hybrid boundaries - Combined harmonic and external data forcing
River boundaries - Constant or time-varying river inputs
Nested boundaries - Coupling with parent model outputs
Custom configurations - Flexible mixing of different boundary types

Key Classes#

SCHISMDataBoundaryConditions#

The main class for configuring boundary conditions. This unified interface handles all boundary types and their associated data sources.

class rompy.schism.data.SCHISMDataBoundaryConditions(*, data_type: ~typing.Literal['boundary_conditions'] = 'boundary_conditions', tidal_data: ~rompy.schism.boundary_core.TidalDataset | None = None, boundaries: ~typing.Dict[int, ~rompy.schism.data.BoundarySetupWithSource] = <factory>, setup_type: ~typing.Literal['tidal', 'hybrid', 'river', 'nested'] | None = None, hotstart_config: ~rompy.schism.data.HotstartConfig | None = None)[source]#

Bases: RompyBaseModel

This class configures all boundary conditions for SCHISM including tidal, ocean, river, and nested model boundaries.

It provides a unified interface for specifying boundary conditions and their data sources, replacing the separate tides and ocean configurations.

field boundaries: Dict[int, BoundarySetupWithSource] [Optional]#

Boundary configuration by boundary index

Validated by:

convert_numpy_types
validate_setup_type
validate_tidal_data

validator convert_numpy_types » all fields[source]#: Convert any numpy values to Python native types

field data_type: Literal['boundary_conditions'] = 'boundary_conditions'#

Model type discriminator

Validated by:

convert_numpy_types
validate_setup_type
validate_tidal_data

get(destdir: str | Path, grid: SCHISMGrid, time: TimeRange) → Dict[str, str][source]#

Process all boundary data and generate necessary input files.

Parameters:

destdir (str | Path) – Destination directory
grid (SCHISMGrid) – SCHISM grid instance
time (TimeRange) – Time range for the simulation

Returns:

Paths to generated files

Return type:

Dict[str, str]

field hotstart_config: HotstartConfig | None = None#

Configuration for hotstart file generation

Validated by:

convert_numpy_types
validate_setup_type
validate_tidal_data

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': ()}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field setup_type: Literal['tidal', 'hybrid', 'river', 'nested'] | None = None#

Predefined boundary setup type

Validated by:

convert_numpy_types
validate_setup_type
validate_tidal_data

field tidal_data: TidalDataset | None = None#

Tidal forcing dataset

Validated by:

convert_numpy_types
validate_setup_type
validate_tidal_data

validator validate_setup_type » all fields[source]#: Validate setup type specific requirements.

validator validate_tidal_data » all fields[source]#: Ensure tidal data is provided when needed for TIDAL or TIDALSPACETIME boundaries.

BoundarySetupWithSource#

Configures individual boundary segments with their data sources and boundary condition types.

class rompy.schism.data.BoundarySetupWithSource(*, elev_type: int = 5, vel_type: int = 5, temp_type: int = 0, salt_type: int = 0, const_elev: float | None = None, const_flow: float | None = None, const_temp: float | None = None, const_salt: float | None = None, inflow_relax: float = 0.5, outflow_relax: float = 0.1, temp_nudge: float = 1.0, salt_nudge: float = 1.0, temp_th_path: str | None = None, temp_3d_path: str | None = None, salt_th_path: str | None = None, salt_3d_path: str | None = None, flow_th_path: str | None = None, elev_st_path: str | None = None, vel_st_path: str | None = None, mean_elev: List[float] | None = None, mean_flow: List[List[float]] | None = None, elev_source: DataBlob | SCHISMDataBoundary | None = None, vel_source: DataBlob | SCHISMDataBoundary | None = None, temp_source: DataBlob | SCHISMDataBoundary | None = None, salt_source: DataBlob | SCHISMDataBoundary | None = None)[source]#

Bases: BoundarySetup

Enhanced boundary setup that includes data sources.

This class extends BoundarySetup to provide a unified configuration for both boundary conditions and their data sources.

field const_elev: float | None = None#

Constant elevation value (for type 2)

Validated by:

validate_data_sources

field const_flow: float | None = None#

Constant flow value (for type 2)

Validated by:

validate_data_sources

field const_salt: float | None = None#

Constant salinity value (for type 2)

Validated by:

validate_data_sources

field const_temp: float | None = None#

Constant temperature value (for type 2)

Validated by:

validate_data_sources

field elev_source: DataBlob | SCHISMDataBoundary | None = None#

Data source for elevation boundary condition

Validated by:

validate_data_sources

field elev_st_path: str | None = None#

Path to space-time elevation file (for types 2/4)

Validated by:

validate_data_sources

field elev_type: int = 5#

Elevation boundary type (0-5)

Validated by:

validate_data_sources

field flow_th_path: str | None = None#

Path to flow time history file (for type 1)

Validated by:

validate_data_sources

field inflow_relax: float = 0.5#

Relaxation factor for inflow (0-1)

Validated by:

validate_data_sources

field mean_elev: List[float] | None = None#

Mean elevation for Flather boundaries

Validated by:

validate_data_sources

field mean_flow: List[List[float]] | None = None#

Mean flow for Flather boundaries

Validated by:

validate_data_sources

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': ()}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field outflow_relax: float = 0.1#

Relaxation factor for outflow (0-1)

Validated by:

validate_data_sources

field salt_3d_path: str | None = None#

Path to 3D salinity file (for type 4)

Validated by:

validate_data_sources

field salt_nudge: float = 1.0#

Salinity nudging factor (0-1)

Validated by:

validate_data_sources

field salt_source: DataBlob | SCHISMDataBoundary | None = None#

Data source for salinity boundary condition

Validated by:

validate_data_sources

field salt_th_path: str | None = None#

Path to salinity time history file (for type 1)

Validated by:

validate_data_sources

field salt_type: int = 0#

Salinity boundary type (0-4)

Validated by:

validate_data_sources

field temp_3d_path: str | None = None#

Path to 3D temperature file (for type 4)

Validated by:

validate_data_sources

field temp_nudge: float = 1.0#

Temperature nudging factor (0-1)

Validated by:

validate_data_sources

field temp_source: DataBlob | SCHISMDataBoundary | None = None#

Data source for temperature boundary condition

Validated by:

validate_data_sources

field temp_th_path: str | None = None#

Path to temperature time history file (for type 1)

Validated by:

validate_data_sources

field temp_type: int = 0#

Temperature boundary type (0-4)

Validated by:

validate_data_sources

validator validate_data_sources » all fields[source]#: Ensure data sources are provided when needed for space-time boundary types.

field vel_source: DataBlob | SCHISMDataBoundary | None = None#

Data source for velocity boundary condition

Validated by:

validate_data_sources

field vel_st_path: str | None = None#

Path to space-time velocity file (for types 2/4)

Validated by:

validate_data_sources

field vel_type: int = 5#

Velocity boundary type (-4, -1, 0-5)

Validated by:

validate_data_sources

BoundaryHandler#

Core boundary handler that extends BoundaryData and supports all SCHISM boundary types.

class rompy.schism.boundary_core.BoundaryHandler(grid_path: str | Path, tidal_data: TidalDataset | None = None, boundary_configs: Dict[int, BoundaryConfig] | None = None, *args, **kwargs)[source]#

Bases: BoundaryData

Handler for SCHISM boundary conditions.

This class extends BoundaryData to handle all SCHISM boundary condition types including tidal, river, nested, and hybrid configurations.

create_bctides() → Bctides[source]#

Create a Bctides instance from this configuration.

Returns:: Configured Bctides instance
Return type:: Bctides

get_constant_values() → Dict[str, List[float]][source]#

Get constant values for boundaries.

Returns:: Dictionary of constant values for each boundary type
Return type:: dict

get_flags_list() → List[List[int]][source]#

Get list of boundary flags for Bctides.

Returns:: Boundary flags for each boundary
Return type:: list of list of int

set_boundary_config(boundary_index: int, config: BoundaryConfig)[source]#

Set configuration for a specific boundary.

Parameters:

boundary_index (int) – Index of the boundary
config (BoundaryConfig) – Configuration for the boundary

set_boundary_type(boundary_index: int, elev_type: ElevationType, vel_type: VelocityType, temp_type: TracerType = TracerType.NONE, salt_type: TracerType = TracerType.NONE, **kwargs)[source]#

Set boundary types for a specific boundary.

Parameters:

boundary_index (int) – Index of the boundary
elev_type (ElevationType) – Elevation boundary condition type
vel_type (VelocityType) – Velocity boundary condition type
temp_type (TracerType, optional) – Temperature boundary condition type
salt_type (TracerType, optional) – Salinity boundary condition type
**kwargs – Additional parameters for the boundary configuration

set_run_parameters(start_time, run_days)[source]#

Set start time and run duration.

Parameters:

start_time (datetime or list) – Start time for the simulation
run_days (float) – Duration of the simulation in days

write_boundary_file(output_path: str | Path) → Path[source]#

Write the bctides.in file.

Parameters:: output_path (str or Path) – Path to write the file
Returns:: Path to the written file
Return type:: Path
Raises:: ValueError – If start_time and rnday are not set

BoundaryConfig#

Configuration for individual boundary segments.

class rompy.schism.boundary_core.BoundaryConfig(*, elev_type: ElevationType = ElevationType.NONE, vel_type: VelocityType = VelocityType.NONE, temp_type: TracerType = TracerType.NONE, salt_type: TracerType = TracerType.NONE, ethconst: float | None = None, vthconst: float | None = None, tthconst: float | None = None, tobc: float | None = 1.0, temp_th_path: str | None = None, temp_3d_path: str | None = None, sthconst: float | None = None, sobc: float | None = 1.0, salt_th_path: str | None = None, salt_3d_path: str | None = None, flow_th_path: str | None = None, inflow_relax: float | None = 0.5, outflow_relax: float | None = 0.1, eta_mean: List[float] | None = None, vn_mean: List[List[float]] | None = None, elev_st_path: str | None = None, vel_st_path: str | None = None)[source]#

Bases: BaseModel

Configuration for a single SCHISM boundary segment.

field elev_st_path: str | None = None#: Path to space-time elevation file (for SPACETIME type)

field elev_type: ElevationType = ElevationType.NONE#: Elevation boundary condition type

field eta_mean: List[float] | None = None#: Mean elevation profile for Flather boundary

field ethconst: float | None = None#: Constant elevation value (for CONSTANT type)

field flow_th_path: str | None = None#: Path to flow time history file (for type 1)

field inflow_relax: float | None = 0.5#: Relaxation factor for inflow (0-1, 1 is strongest nudging)

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field outflow_relax: float | None = 0.1#: Relaxation factor for outflow (0-1, 1 is strongest nudging)

field salt_3d_path: str | None = None#: Path to 3D salinity file (for type 4)

field salt_th_path: str | None = None#: Path to salinity time history file (for type 1)

field salt_type: TracerType = TracerType.NONE#: Salinity boundary condition type

field sobc: float | None = 1.0#: Salinity nudging factor (0-1, 1 is strongest nudging)

field sthconst: float | None = None#: Constant salinity value (for CONSTANT type)

field temp_3d_path: str | None = None#: Path to 3D temperature file (for type 4)

field temp_th_path: str | None = None#: Path to temperature time history file (for type 1)

field temp_type: TracerType = TracerType.NONE#: Temperature boundary condition type

field tobc: float | None = 1.0#: Temperature nudging factor (0-1, 1 is strongest nudging)

field tthconst: float | None = None#: Constant temperature value (for CONSTANT type)

field vel_st_path: str | None = None#: Path to space-time velocity file (for SPACETIME type)

field vel_type: VelocityType = VelocityType.NONE#: Velocity boundary condition type

field vn_mean: List[List[float]] | None = None#: Mean velocity profile for Flather boundary

field vthconst: float | None = None#: Constant velocity/flow value (for CONSTANT type)

Boundary Type Enums#

ElevationType#

class rompy.schism.boundary_core.ElevationType(value)[source]#

Elevation boundary condition types.

CONSTANT = 2#

EXTERNAL = 4#

HARMONIC = 3#

HARMONICEXTERNAL = 5#

NONE = 0#

TIMEHIST = 1#

VelocityType#

class rompy.schism.boundary_core.VelocityType(value)[source]#

Velocity boundary condition types.

CONSTANT = 2#

EXTERNAL = 4#

FLATHER = -1#

HARMONIC = 3#

HARMONICEXTERNAL = 5#

NONE = 0#

RELAXED = -4#

TIMEHIST = 1#

TracerType#

class rompy.schism.boundary_core.TracerType(value)[source]#

Temperature/salinity boundary condition types.

CONSTANT = 2#

EXTERNAL = 4#

INITIAL = 3#

NONE = 0#

TIMEHIST = 1#

Factory Functions#

The boundary conditions module provides convenient factory functions for creating common boundary configurations. These functions return SCHISMDataBoundaryConditions objects that can be directly used in SCHISM simulations.

High-Level Configuration Functions#

create_tidal_only_boundary_config#

rompy.schism.boundary_conditions.create_tidal_only_boundary_config(constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear')[source]#

Create a configuration where all open boundaries are treated as tidal boundaries.

Parameters:

constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”

Returns:

Configured boundary conditions

Return type:

SCHISMDataBoundaryConditions

Example Usage:

from rompy.schism.boundary_conditions import create_tidal_only_boundary_config

# Basic tidal configuration
bc = create_tidal_only_boundary_config(
    constituents=["M2", "S2", "N2", "K1", "O1"],
    tidal_elevations="/path/to/h_tpxo9.nc",
    tidal_velocities="/path/to/u_tpxo9.nc"
)

# With earth tidal potential
bc = create_tidal_only_boundary_config(
    constituents=["M2", "S2", "K1", "O1"],
    ntip=1  # Enable earth tidal potential
)

create_hybrid_boundary_config#

rompy.schism.boundary_conditions.create_hybrid_boundary_config(constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear', elev_source: Any | None = None, vel_source: Any | None = None, temp_source: Any | None = None, salt_source: Any | None = None)[source]#

Create a configuration for hybrid harmonic + external data boundaries.

Parameters:

constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”
elev_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for elevation
vel_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for velocity
temp_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for temperature
salt_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for salinity

Returns:

Configured boundary conditions

Return type:

SCHISMDataBoundaryConditions

Example Usage:

from rompy.schism.boundary_conditions import create_hybrid_boundary_config
from rompy.core.data import DataBlob

# Hybrid configuration with external data
bc = create_hybrid_boundary_config(
    constituents=["M2", "S2"],
    tidal_elevations="/path/to/h_tpxo9.nc",
    tidal_velocities="/path/to/u_tpxo9.nc",
    elev_source=DataBlob(source="/path/to/elev2D.th.nc"),
    vel_source=DataBlob(source="/path/to/uv3D.th.nc"),
    temp_source=DataBlob(source="/path/to/TEM_3D.th.nc"),
    salt_source=DataBlob(source="/path/to/SAL_3D.th.nc")
)

create_river_boundary_config#

rompy.schism.boundary_conditions.create_river_boundary_config(river_boundary_index: int = 0, river_flow: float = -100.0, other_boundaries: Literal['tidal', 'hybrid', 'none'] = 'tidal', constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear')[source]#

Create a configuration with a designated river boundary and optional tidal boundaries.

Parameters:

river_boundary_index (int) – Index of the river boundary
river_flow (float) – Flow rate (negative for inflow)
other_boundaries (str) – How to treat other boundaries (“tidal”, “hybrid”, or “none”)
constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”

Returns:

Configured boundary conditions

Return type:

SCHISMDataBoundaryConditions

Example Usage:

from rompy.schism.boundary_conditions import create_river_boundary_config

# River boundary with tidal forcing on other boundaries
bc = create_river_boundary_config(
    river_boundary_index=1,
    river_flow=-500.0,  # 500 m³/s inflow
    river_temp=15.0,    # 15°C
    river_salt=0.1,     # 0.1 PSU (fresh water)
    other_boundaries="tidal",
    constituents=["M2", "S2", "N2"]
)

# River-only configuration
bc = create_river_boundary_config(
    river_boundary_index=0,
    river_flow=-200.0,
    other_boundaries="none"
)

create_nested_boundary_config#

rompy.schism.boundary_conditions.create_nested_boundary_config(with_tides: bool = True, inflow_relax: float = 0.8, outflow_relax: float = 0.2, elev_source: Any | None = None, vel_source: Any | None = None, temp_source: Any | None = None, salt_source: Any | None = None, constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear')[source]#

Create a configuration for nested model boundaries with external data.

Parameters:

with_tides (bool) – Include tidal components
inflow_relax (float) – Relaxation parameter for inflow (0-1)
outflow_relax (float) – Relaxation parameter for outflow (0-1)
elev_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for elevation
vel_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for velocity
temp_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for temperature
salt_source (Union[DataBlob, SCHISMDataBoundary], optional) – Data source for salinity
constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”

Returns:

Configured boundary conditions

Return type:

SCHISMDataBoundaryConditions

Example Usage:

from rompy.schism.boundary_conditions import create_nested_boundary_config
from rompy.schism.data import SCHISMDataBoundary
from rompy.core.source import SourceFile

# Nested boundary with tides and parent model data
bc = create_nested_boundary_config(
    with_tides=True,
    inflow_relax=0.9,
    outflow_relax=0.1,
    constituents=["M2", "S2"],
    elev_source=SCHISMDataBoundary(
        source=SourceFile(uri="/path/to/parent_model.nc"),
        variables=["ssh"]
    ),
    vel_source=SCHISMDataBoundary(
        source=SourceFile(uri="/path/to/parent_model.nc"),
        variables=["u", "v"]
    )
)

# Nested boundary without tides
bc = create_nested_boundary_config(
    with_tides=False,
    inflow_relax=0.8,
    outflow_relax=0.2,
    elev_source=elev_data,
    vel_source=vel_data
)

Low-Level Boundary Creation Functions#

These functions create BoundaryHandler objects for direct grid-based boundary manipulation:

rompy.schism.boundary_core.create_tidal_boundary(grid_path: str | Path, constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear') → BoundaryHandler[source]#

Create a tidal-only boundary.

Parameters:

grid_path (str or Path) – Path to SCHISM grid
constituents (str or list, optional) – Tidal constituents, by default “major”
tidal_database (str or Path, optional) – Tidal database path for pyTMD to use, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0

Returns:

Configured tidal boundary

Return type:

BoundaryHandler

rompy.schism.boundary_core.create_hybrid_boundary(grid_path: str | Path, constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear') → BoundaryHandler[source]#

Create a hybrid boundary with tides + external data.

Parameters:

grid_path (str or Path) – Path to SCHISM grid
constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”

Returns:

Configured hybrid boundary

Return type:

BoundaryHandler

rompy.schism.boundary_core.create_river_boundary(grid_path: str | Path, river_flow: float = -100.0, river_boundary_index: int = 0) → BoundaryHandler[source]#

Create a river boundary with constant flow.

Parameters:

grid_path (str or Path) – Path to SCHISM grid
river_flow (float, optional) – River flow value (negative for inflow), by default -100.0
river_boundary_index (int, optional) – Index of the river boundary, by default 0

Returns:

Configured river boundary

Return type:

BoundaryHandler

rompy.schism.boundary_core.create_nested_boundary(grid_path: str | Path, with_tides: bool = False, inflow_relax: float = 0.8, outflow_relax: float = 0.8, constituents: str | List[str] = 'major', tidal_database: str | Path | None = None, tidal_model: str | None = 'FES2014', nodal_corrections: bool = True, tidal_potential: bool = True, cutoff_depth: float = 50.0, tide_interpolation_method: str = 'bilinear') → BoundaryHandler[source]#

Create a nested boundary with optional tides.

Parameters:

grid_path (str or Path) – Path to SCHISM grid
with_tides (bool, optional) – Whether to include tides, by default False
inflow_relax (float, optional) – Relaxation factor for inflow, by default 0.8
outflow_relax (float, optional) – Relaxation factor for outflow, by default 0.8
constituents (str or list, optional) – Tidal constituents to include, by default “major”
tidal_database (str or Path, optional) – Path to tidal database for pyTMD, by default None
tidal_model (str, optional) – Tidal model to use, by default ‘FES2014’
nodal_corrections (bool, optional) – Whether to apply nodal corrections, by default True
tidal_potential (bool, optional) – Whether to include tidal potential, by default True
cutoff_depth (float, optional) – Depth threshold for tidal potential, by default 50.0
tide_interpolation_method (str, optional) – Method for tide interpolation, by default “bilinear”

Returns:

Configured nested boundary

Return type:

BoundaryHandler

Usage Examples#

Tidal-Only Configuration#

For simulations with purely tidal forcing:

from rompy.schism.boundary_conditions import create_tidal_only_boundary_config
from rompy.schism.data import SCHISMData

# Create tidal-only boundary configuration
boundary_conditions = create_tidal_only_boundary_config(
    constituents=["M2", "S2", "N2", "K1", "O1"],
    tidal_database="tpxo",
    tidal_elevations="path/to/tidal_elevations.nc",
    tidal_velocities="path/to/tidal_velocities.nc",
)

# Use in SCHISM configuration
schism_data = SCHISMData(
    boundary_conditions=boundary_conditions,
)

Hybrid Tidal + Ocean Data#

For simulations combining tidal forcing with external ocean data:

from rompy.schism.boundary_conditions import create_hybrid_boundary_config
from rompy.core.data import DataBlob

# Create hybrid boundary configuration
boundary_conditions = create_hybrid_boundary_config(
    constituents=["M2", "S2"],
    tidal_elevations="path/to/tidal_elevations.nc",
    tidal_velocities="path/to/tidal_velocities.nc",
    # Add ocean data sources
    elev_source=DataBlob(source="path/to/elev2D.th.nc"),
    vel_source=DataBlob(source="path/to/uv3D.th.nc"),
    temp_source=DataBlob(source="path/to/TEM_3D.th.nc"),
    salt_source=DataBlob(source="path/to/SAL_3D.th.nc"),
)

River Boundary Configuration#

For simulations with river inputs:

from rompy.schism.boundary_conditions import create_river_boundary_config

# Create river boundary configuration
boundary_conditions = create_river_boundary_config(
    river_boundary_index=1,     # Index of the river boundary
    river_flow=-100.0,          # Negative for inflow (m³/s)
    other_boundaries="tidal",   # Other boundaries are tidal
    constituents=["M2", "S2"],
    tidal_elevations="path/to/tidal_elevations.nc",
    tidal_velocities="path/to/tidal_velocities.nc",
)

Nested Model Configuration#

For simulations nested within a larger model:

from rompy.schism.boundary_conditions import create_nested_boundary_config
from rompy.schism.data import SCHISMDataBoundary
from rompy.core.source import SourceFile

# Create nested boundary configuration
boundary_conditions = create_nested_boundary_config(
    with_tides=True,
    inflow_relax=0.8,
    outflow_relax=0.2,
    constituents=["M2", "S2"],
    tidal_elevations="path/to/tidal_elevations.nc",
    tidal_velocities="path/to/tidal_velocities.nc",
    # Add parent model data sources
    elev_source=SCHISMDataBoundary(
        source=SourceFile(uri="path/to/parent_model.nc"),
        variables=["ssh"],
    ),
    vel_source=SCHISMDataBoundary(
        source=SourceFile(uri="path/to/parent_model.nc"),
        variables=["u", "v"],
    ),
)

Direct Boundary Handler Usage#

For maximum control, use the BoundaryHandler class directly:

from rompy.schism.boundary_core import (
    BoundaryHandler,
    ElevationType,
    VelocityType,
    TracerType
)

# Create boundary handler
boundary = BoundaryHandler(
    grid_path="path/to/hgrid.gr3",
    constituents=["M2", "S2", "K1", "O1"],
    tidal_database="tpxo",
    tidal_elevations="path/to/h_tpxo9.nc",
    tidal_velocities="path/to/uv_tpxo9.nc"
)

# Configure different boundary types
boundary.set_boundary_type(
    0,  # Ocean boundary with tides
    elev_type=ElevationType.HARMONIC,
    vel_type=VelocityType.HARMONIC
)

boundary.set_boundary_type(
    1,  # River boundary
    elev_type=ElevationType.NONE,
    vel_type=VelocityType.CONSTANT,
    vthconst=-500.0  # River inflow
)

# Set simulation parameters and write output
boundary.set_run_parameters(start_time, run_days)
boundary.write_boundary_file("path/to/bctides.in")

Custom Boundary Configuration#

For complex scenarios with mixed boundary types:

from rompy.schism.data import SCHISMDataBoundaryConditions, BoundarySetupWithSource
from rompy.schism.boundary_core import ElevationType, VelocityType, TracerType
from rompy.core.data import DataBlob

# Create custom boundary configuration
boundary_conditions = SCHISMDataBoundaryConditions(
    constituents=["M2", "S2"],
    tidal_database="tpxo",
    boundaries={
        # Ocean boundary (harmonic + external data)
        0: BoundarySetupWithSource(
            elev_type=ElevationType.HARMONICEXTERNAL,
            vel_type=VelocityType.HARMONICEXTERNAL,
            temp_type=TracerType.EXTERNAL,
            salt_type=TracerType.EXTERNAL,
            elev_source=DataBlob(source="path/to/elev2D.th.nc"),
            vel_source=DataBlob(source="path/to/uv3D.th.nc"),
            temp_source=DataBlob(source="path/to/TEM_3D.th.nc"),
            salt_source=DataBlob(source="path/to/SAL_3D.th.nc"),
        ),
        # River boundary (constant flow)
        1: BoundarySetupWithSource(
            elev_type=ElevationType.NONE,
            vel_type=VelocityType.CONSTANT,
            temp_type=TracerType.CONSTANT,
            salt_type=TracerType.CONSTANT,
            const_flow=-100.0,  # m³/s, negative for inflow
            const_temp=15.0,    # °C
            const_salt=0.5,     # PSU
        ),
    }
)

Boundary Types#

The system supports various boundary condition types for different variables:

Elevation Types#

NONE - No elevation boundary condition
TIMEHIST - Time history from elev.th
CONSTANT - Constant elevation
HARMONIC - Pure harmonic tidal elevation using tidal constituents
EXTERNAL - Time-varying elevation from external data (elev2D.th.nc)
HARMONICEXTERNAL - Combined harmonic and external elevation data

Velocity Types#

NONE - No velocity boundary condition
TIMEHIST - Time history from flux.th
CONSTANT - Constant velocity/flow rate
HARMONIC - Pure harmonic tidal velocity using tidal constituents
EXTERNAL - Time-varying velocity from external data (uv3D.th.nc)
HARMONICEXTERNAL - Combined harmonic and external velocity data
FLATHER - Flather type radiation boundary
RELAXED - Relaxation boundary condition (for nesting)

Tracer Types#

NONE - No tracer boundary condition
TIMEHIST - Time history from temp/salt.th
CONSTANT - Constant tracer value
INITIAL - Initial profile for inflow
EXTERNAL - Time-varying tracer from external data

Data Sources#

The system supports multiple data source types:

DataBlob#

Simple file-based data source for pre-processed SCHISM input files:

from rompy.core.data import DataBlob

elev_source = DataBlob(source="path/to/elev2D.th.nc")

SCHISMDataBoundary#

Advanced data source with variable mapping and coordinate transformation:

from rompy.schism.data import SCHISMDataBoundary
from rompy.core.source import SourceFile

vel_source = SCHISMDataBoundary(
    source=SourceFile(uri="path/to/ocean_model.nc"),
    variables=["u", "v"],
    crop_coords={"lon": [-180, 180], "lat": [-90, 90]},
)

Configuration Files#

The boundary conditions can also be configured via YAML files:

Tidal-Only Configuration:

boundary_conditions:
  data_type: boundary_conditions
  constituents: ["M2", "S2", "N2", "K1", "O1"]
  tidal_database: tpxo
  tidal_data:
    elevations: path/to/h_tpxo9.nc
    velocities: path/to/u_tpxo9.nc
  setup_type: tidal

Hybrid Configuration:

boundary_conditions:
  data_type: boundary_conditions
  constituents: ["M2", "S2", "N2", "K1", "O1"]
  tidal_database: tpxo
  tidal_data:
    elevations: path/to/h_tpxo9.nc
    velocities: path/to/u_tpxo9.nc
  setup_type: hybrid
  boundaries:
    0:
      elev_type: HARMONICEXTERNAL
      vel_type: HARMONICEXTERNAL
      temp_type: EXTERNAL
      salt_type: EXTERNAL
      elev_source:
        data_type: blob
        source: path/to/elev2D.th.nc
      vel_source:
        data_type: blob
        source: path/to/uv3D.th.nc
      temp_source:
        data_type: blob
        source: path/to/TEM_3D.th.nc
      salt_source:
        data_type: blob
        source: path/to/SAL_3D.th.nc

River Configuration:

boundary_conditions:
  data_type: boundary_conditions
  constituents: ["M2", "S2"]
  tidal_database: tpxo
  setup_type: river
  boundaries:
    0:  # Tidal boundary
      elev_type: HARMONIC
      vel_type: HARMONIC
      temp_type: NONE
      salt_type: NONE
    1:  # River boundary
      elev_type: NONE
      vel_type: CONSTANT
      temp_type: CONSTANT
      salt_type: CONSTANT
      const_flow: -500.0
      const_temp: 15.0
      const_salt: 0.1

Nested Configuration:

boundary_conditions:
  data_type: boundary_conditions
  constituents: ["M2", "S2"]
  tidal_database: tpxo
  tidal_data:
    elevations: path/to/h_tpxo9.nc
    velocities: path/to/u_tpxo9.nc
  setup_type: nested
  boundaries:
    0:
      elev_type: HARMONICEXTERNAL
      vel_type: RELAXED
      temp_type: EXTERNAL
      salt_type: EXTERNAL
      inflow_relax: 0.8
      outflow_relax: 0.2
      elev_source:
        data_type: schism_boundary
        source:
          data_type: source_file
          uri: path/to/parent_model.nc
        variables: ["ssh"]
      vel_source:
        data_type: schism_boundary
        source:
          data_type: source_file
          uri: path/to/parent_model.nc
        variables: ["u", "v"]

Benefits of the New System#

Unified Interface - Single configuration object for all boundary types
Flexible Configuration - Mix different boundary types per segment
Factory Functions - Simplified setup for common scenarios
Better Validation - Comprehensive validation of boundary configurations
Data Source Integration - Seamless integration with data processing pipeline
Backward Compatibility - Maintains compatibility with existing workflows where possible
Clear Naming - Module and class names reflect actual functionality
Consolidated Code - Eliminates duplication between modules

Advanced Features#

Factory Function Parameters#

All factory functions support additional parameters for fine-tuning:

Common Parameters:

constituents: List of tidal constituents (e.g., [“M2”, “S2”, “N2”, “K1”, “O1”])
tidal_database: Database identifier (“tpxo”, “fes2014”, “got”)
tidal_elevations: Path to tidal elevation NetCDF file
tidal_velocities: Path to tidal velocity NetCDF file

Tidal Potential:

bc = create_tidal_only_boundary_config(
    constituents=["M2", "S2", "K1", "O1"],
    ntip=1,          # Enable tidal potential
    tip_dp=1.0,      # Depth threshold
    cutoff_depth=50.0,  # Cutoff depth
)

Relaxation Parameters:

bc = create_nested_boundary_config(
    with_tides=True,
    inflow_relax=0.8,   # Strong relaxation for inflow
    outflow_relax=0.2,  # Weak relaxation for outflow
)

Multiple Tidal Databases:

bc = create_tidal_only_boundary_config(
    tidal_database="fes2014",  # Alternative: "tpxo", "got"
    constituents=["M2", "S2", "N2", "K2", "K1", "O1", "P1", "Q1"],
)

Custom Boundary Types:

from rompy.schism.data import BoundarySetupWithSource
from rompy.schism.boundary_core import ElevationType, VelocityType, TracerType

# Custom boundary with specific types
custom_boundary = BoundarySetupWithSource(
    elev_type=ElevationType.HARMONICEXTERNAL,
    vel_type=VelocityType.HARMONICEXTERNAL,
    temp_type=TracerType.EXTERNAL,
    salt_type=TracerType.EXTERNAL,
    inflow_relax=0.9,
    outflow_relax=0.1
)

Flather Radiation Boundaries#

Configure Flather radiation boundaries using the low-level BoundaryHandler:

from rompy.schism.boundary_core import BoundaryHandler, ElevationType, VelocityType

# Create boundary handler
boundary = BoundaryHandler(grid_path="path/to/hgrid.gr3")

# Configure Flather boundary
boundary.set_boundary_type(
    boundary_index=1,
    elev_type=ElevationType.NONE,
    vel_type=VelocityType.FLATHER,
    eta_mean=[0.0, 0.0, 0.0],        # Mean elevation at each node
    vn_mean=[[0.1], [0.1], [0.1]]    # Mean normal velocity at each node
)

Common Tidal Constituents#

Major Constituents (recommended for most applications):

M2, S2, N2, K1, O1

Semi-diurnal:

M2 (Principal lunar), S2 (Principal solar), N2 (Lunar elliptic), K2 (Lunisolar)

Diurnal:

K1 (Lunar diurnal), O1 (Lunar principal), P1 (Solar principal), Q1 (Larger lunar elliptic)

Long Period:

Mf (Lunisolar fortnightly), Mm (Lunar monthly), Ssa (Solar semiannual)

Full Set Example:

bc = create_tidal_only_boundary_config(
    constituents=[
        "M2", "S2", "N2", "K2",     # Semi-diurnal
        "K1", "O1", "P1", "Q1",     # Diurnal
        "Mf", "Mm", "Ssa"           # Long period
    ]
)

Best Practices#

Start Simple: Begin with tidal-only configurations using major constituents
Validate Data: Ensure tidal and external data files cover your model domain and time period
Check Units: River flows are in m³/s (negative for inflow)
Relaxation Values: Use 0.8-1.0 for strong nudging, 0.1-0.3 for weak nudging
File Formats: Use NetCDF files for better performance and metadata
Coordinate Systems: Ensure all data sources use consistent coordinate systems
Time Coverage: External data must cover the entire simulation period plus spin-up

Table of Contents

SCHISM Boundary Conditions#

Overview#

Key Classes#

SCHISMDataBoundaryConditions#

BoundarySetupWithSource#

BoundaryHandler#

BoundaryConfig#

Boundary Type Enums#

ElevationType#

VelocityType#

TracerType#

Factory Functions#

High-Level Configuration Functions#

create_tidal_only_boundary_config#

create_hybrid_boundary_config#

create_river_boundary_config#

create_nested_boundary_config#

Low-Level Boundary Creation Functions#

Usage Examples#

Tidal-Only Configuration#

Hybrid Tidal + Ocean Data#

River Boundary Configuration#

Nested Model Configuration#

Direct Boundary Handler Usage#

Custom Boundary Configuration#

Boundary Types#

Elevation Types#

Velocity Types#

Tracer Types#

Data Sources#

DataBlob#

SCHISMDataBoundary#

Configuration Files#

Benefits of the New System#

Advanced Features#

Factory Function Parameters#

Flather Radiation Boundaries#

Common Tidal Constituents#

Best Practices#

See Also#

This Page