Skip to content

Configuration#

NWM Coastal uses YAML configuration files to define simulation parameters. This page documents all available configuration options.

Minimal Configuration#

SCHISM (default)#

The simplest valid SCHISM configuration only requires:

simulation:
  start_date: 2021-06-11
  duration_hours: 24
  coastal_domain: hawaii
  meteo_source: nwm_ana

boundary:
  source: stofs

All other parameters have sensible defaults. When no model key is present, SCHISM is assumed.

SFINCS#

A minimal SFINCS configuration requires a model key and a model_config section:

model: sfincs

simulation:
  start_date: 2025-06-01
  duration_hours: 168
  coastal_domain: atlgulf
  meteo_source: nwm_ana

boundary:
  source: stofs

model_config:
  prebuilt_dir: /path/to/prebuilt/sfincs/model

Recommended: heredoc sbatch script

The preferred approach on clusters is to embed the YAML configuration directly in a sbatch script using a heredoc and use coastal-calibration run to execute it. This keeps the SLURM directives and workflow configuration in a single, self-contained file. See the CLI reference for details and complete examples in docs/examples/.

Variable Interpolation#

Configuration values support variable interpolation using ${section.key} syntax:

simulation:
  coastal_domain: hawaii

paths:
  work_dir: /data/${user}/${simulation.coastal_domain}
  # Resolves to: /data/<your_username>/hawaii

The ${user} variable is automatically resolved from the $USER environment variable.

Default Path Templates#

If not specified, paths are automatically generated using model-aware templates:

Path Default Template
work_dir /ngen-test/coastal/${user}/${model}_${simulation.coastal_domain}_${boundary.source}_${simulation.meteo_source}/${model}_${simulation.start_date}
raw_download_dir /ngen-test/coastal/${user}/${model}_${simulation.coastal_domain}_${boundary.source}_${simulation.meteo_source}/raw_data

The ${model} variable resolves to schism or sfincs based on the model key.

Configuration Sections#

Model Selection#

The top-level model key selects the model type. It defaults to schism if omitted.

model: sfincs  # or "schism" (default)

Simulation Settings#

Define the simulation time period and domain:

simulation:
  start_date: 2021-06-11         # Start date (ISO format)
  duration_hours: 24             # Simulation length
  coastal_domain: hawaii         # Domain name
  meteo_source: nwm_ana          # Meteorological data source
  timestep_seconds: 3600         # Forcing time step
Parameter Type Default Options
start_date datetime required ISO format date/datetime
duration_hours int required Positive integer
coastal_domain string required hawaii, prvi, atlgulf, pacific
meteo_source string required nwm_ana, nwm_retro
timestep_seconds int 3600 Forcing time step in seconds

Supported Date Formats#

The start_date field accepts multiple formats:

start_date: 2021-06-11              # Date only (midnight)
start_date: 2021-06-11T00:00:00     # ISO format with time
start_date: "2021-06-11 00:00:00"   # Date with space separator
start_date: 20210611                # Compact format

Boundary Settings#

Configure boundary conditions:

boundary:
  source: stofs          # Boundary condition source
  stofs_file:            # Optional: explicit STOFS file path
Parameter Type Default Options Description
source string tpxo tpxo, stofs Boundary condition source
stofs_file path null - Override STOFS file path

Path Settings#

Configure file system paths:

All path fields support ~ (tilde) expansion, so you can write ~/my_data instead of the full home directory path.

paths:
  work_dir: /path/to/work         # Working directory (auto-generated if not set)
  raw_download_dir: /path/to/data # Download directory (auto-generated if not set)
  nwm_dir: /path/to/nwm.v3.0.6
  hot_start_file:                 # Hot restart file for warm start
  parm_dir: /path/to/coastal/parm
Parameter Type Default
work_dir path Auto-generated from template
raw_download_dir path Auto-generated from template
nwm_dir path -
hot_start_file path null
parm_dir path -

Model Configuration#

Model-specific parameters live in the model_config section. The contents depend on the model key.

SCHISM Model Configuration#

# model: schism (default, can be omitted)
model_config:
  prebuilt_dir: /path/to/coastal/hawaii
  geogrid_file: /path/to/coastal/hawaii/geo_em_HI.nc
  nodes: 2                        # Number of compute nodes
  ntasks_per_node: 18             # MPI tasks per node
  exclusive: true                 # Request exclusive node access
  nscribes: 2                     # SCHISM I/O scribes
  omp_num_threads: 2              # OpenMP threads
  oversubscribe: false            # Allow MPI oversubscription
  schism_exe:                     # System-compiled SCHISM executable (optional)
  include_noaa_gages: true        # Enable NOAA observation stations & comparison plots
  runtime_env: {}                 # Extra env vars for model run (optional)
Parameter Type Default Description
prebuilt_dir path - Path to pre-built SCHISM model directory
geogrid_file path - WRF geogrid file for atmospheric forcing regridding
nodes int 2 Number of compute nodes
ntasks_per_node int 18 MPI tasks per node
exclusive bool true Request exclusive node access
nscribes int 2 SCHISM I/O scribes
omp_num_threads int 2 OpenMP threads
oversubscribe bool false Allow MPI oversubscription
schism_exe path - Path to a system-compiled SCHISM executable
include_noaa_gages bool false Enable NOAA station discovery and comparison
runtime_env dict {} Extra env vars for the model run subprocess

NOAA Observation Stations (include_noaa_gages)#

When set to true, two additional stages are activated in the SCHISM pipeline:

  • schism_obs: Automatically discovers NOAA CO-OPS water level stations within the model domain by computing a concave hull around the open boundary nodes in hgrid.gr3 and querying the CO-OPS API. Writes a station.in file so SCHISM outputs time-series at those locations, and a station_noaa_ids.txt companion that maps station indices to NOAA station IDs. The schism_prep stage then patches param.nml to enable station output (iout_sta = 1, nspool_sta = 18).
  • schism_plot: After the SCHISM run completes, reads the station output (staout_1), fetches the corresponding NOAA CO-OPS observations (converting from MLLW to MSL datum), and generates 2×2 comparison plots saved to figs/.

Both stages require network access for NOAA CO-OPS API calls and are classified as Python-only stages.

SFINCS Model Configuration#

model: sfincs

model_config:
  prebuilt_dir: /path/to/model    # Required: pre-built SFINCS model directory
  model_root:                     # Output directory (defaults to {work_dir}/sfincs_model)
  observation_points: []          # Observation point coordinates
  observation_locations_file:     # Observation locations file
  merge_observations: false       # Merge observations into model
  discharge_locations_file:       # Discharge source locations file
  merge_discharge: false          # Merge discharge into model
  include_noaa_gages: true        # Enable NOAA station discovery & comparison plots
  include_precip: true            # Add precipitation forcing
  include_wind: true              # Add wind forcing
  include_pressure: true          # Add atmospheric pressure forcing
  forcing_to_mesh_offset_m: 0.0  # Vertical offset added to boundary forcing
  vdatum_mesh_to_msl_m: 0.0      # Vertical offset converting model output to MSL
  meteo_res:                      # Meteo forcing resolution in meters (auto if null)
  sfincs_exe:                     # Explicit SFINCS executable path (overrides PATH lookup)
  omp_num_threads: 36             # OpenMP threads (defaults to CPU count)
  floodmap_dem:                   # High-resolution DEM for flood depth map
  floodmap_hmin: 0.05             # Minimum flood depth threshold (m)
  floodmap_enabled: true          # Enable flood depth map generation
Parameter Type Default Description
prebuilt_dir path required Path to pre-built SFINCS model
model_root path null Output directory (defaults to {work_dir}/sfincs_model)
observation_points list [] Observation point coordinates
observation_locations_file path null Observation locations file
merge_observations bool false Merge observations into model
discharge_locations_file path null Discharge source locations file
merge_discharge bool false Merge discharge into model
include_noaa_gages bool false Enable NOAA station discovery and comparison plots
include_precip bool false Add precipitation forcing from meteo data source
include_wind bool false Add spatially-varying wind forcing
include_pressure bool false Add atmospheric pressure forcing with barometric correction
forcing_to_mesh_offset_m float 0.0 Vertical offset (m) added to boundary forcing before simulation
vdatum_mesh_to_msl_m float 0.0 Vertical offset (m) added to model output for MSL comparison
meteo_res float null Meteo output resolution (m). Auto-derived from quadtree grid if null
sfincs_exe path null Explicit SFINCS executable path (overrides PATH lookup)
omp_num_threads int auto OpenMP threads (defaults to CPU count)
runtime_env dict {} Extra env vars for the model run subprocess
floodmap_dem path null High-resolution DEM GeoTIFF for flood depth downscaling
floodmap_hmin float 0.05 Minimum flood depth threshold (m); shallower cells are masked out
floodmap_enabled bool true Enable flood depth map generation after SFINCS run

Meteorological forcing resolution

When meteo_res is not set, the resolution is automatically derived from the base cell size of the SFINCS quadtree grid. This prevents the LCC → UTM reprojection of NWM data from inflating the meteo grid to the full CONUS extent, which can produce multi-GB forcing files and slow SFINCS runtime from minutes to hours.

Vertical datum offsets

SFINCS operates in the vertical datum of the mesh (e.g. NAVD88). When the boundary forcing is in a different datum, forcing_to_mesh_offset_m anchors the forcing signal to the correct height on the mesh. For tidal-only sources like TPXO, whose oscillations are centered on zero (MSL), this places the mean water level at the geodetic height of MSL on the mesh. For sources that already report water levels in the mesh datum (e.g. STOFS on a NAVD88 mesh), set this to 0.0.

After the simulation, vdatum_mesh_to_msl_m converts the model output from the mesh datum to MSL for comparison with NOAA CO-OPS observations. Both values can be obtained from the NOAA VDatum API.

For example, on the Texas Gulf coast (NAVD88 mesh), VDatum reports MSL is 0.171 m above NAVD88 at the domain centroid, so both parameters are set to 0.171.

Monitoring Settings#

Configure logging and monitoring:

monitoring:
  log_level: INFO                 # Logging verbosity
  log_file:                       # Optional log file path
  enable_progress_tracking: true  # Show progress bars
  enable_timing: true             # Track stage timing
Parameter Type Default Options
log_level string INFO DEBUG, INFO, WARNING, ERROR
log_file path null Path to log file
enable_progress_tracking bool true Show progress bars
enable_timing bool true Track and report stage timing

Download Settings#

Configure data download behavior:

download:
  enabled: true           # Enable automatic downloads
  skip_existing: true     # Skip already downloaded files
  timeout: 600            # Download timeout in seconds
  raise_on_error: true    # Fail on download errors
  limit_per_host: 4       # Concurrent downloads per host
Parameter Type Default Description
enabled bool true Enable automatic downloads
skip_existing bool true Skip already downloaded files
timeout int 600 Download timeout (seconds)
raise_on_error bool true Fail workflow on download errors
limit_per_host int 4 Concurrent downloads per host

Configuration Inheritance#

Use _base to inherit settings from another configuration file:

# base.yaml - shared settings
simulation:
  duration_hours: 24
  meteo_source: nwm_ana

boundary:
  source: stofs
# hawaii_run.yaml - inherits from base.yaml
_base: base.yaml

simulation:
  start_date: 2021-06-11
  coastal_domain: hawaii
# prvi_run.yaml - different domain, same settings
_base: base.yaml

simulation:
  start_date: 2022-09-18
  coastal_domain: prvi

This allows you to:

  • Share common settings across multiple runs
  • Override only the parameters that differ
  • Maintain consistency across related simulations

SFINCS Creation Configuration#

The create command uses a separate configuration schema (SfincsCreateConfig) to build a new SFINCS quadtree model from an AOI polygon. This config is independent of the run/simulation config above.

Minimal Create Config#

aoi: ./texas_aoi.geojson
output_dir: ./my_sfincs_model

elevation:
  datasets:
    - name: nws_topobathy
      zmin: -20000

data_catalog:
  data_libs:
    - ./dem/data_catalog.yml

Create Configuration Sections#

Top-Level Fields#

Parameter Type Default Description
aoi path required Path to AOI polygon (GeoJSON, Shapefile, etc.)
output_dir path required Directory where the model will be written
download_dir path {output_dir}/downloads Directory for downloaded data (NOAA DEMs)
add_noaa_gages bool false Auto-discover NOAA CO-OPS stations as obs points
observation_points list [] Observation point dicts (x, y, name)
observation_locations_file path null GeoJSON file with observation point locations
merge_observations bool false Merge with pre-existing observation points in model

Grid Settings (grid)#

grid:
  resolution: 50.0
  crs: utm
  rotated: true
  refinement:
    - polygon: ./aoi.geojson
      level: 4
      buffer_m: -3072
Parameter Type Default Description
resolution float 50.0 Base grid cell resolution in meters
crs str utm CRS ("utm" for auto-detection, or "EPSG:xxxxx")
rotated bool true Allow grid rotation for tighter bounding-box fit
refinement list [] Quadtree refinement levels (see below)

Each refinement entry:

Field Type Description
polygon path Polygon defining the area to refine
level int Refinement level (1 = base, 2 = base/2, 3 = base/4, …)
buffer_m float Inward buffer in meters (negative shrinks the polygon)

Elevation Settings (elevation)#

elevation:
  datasets:
    - name: nws_topobathy
      zmin: -20000
    - name: gebco
      zmin: -20000
  buffer_cells: 1
Parameter Type Default Description
datasets list copdem30 + gebco Ordered list of elevation datasets
buffer_cells int 1 Buffer cells around grid boundary

Each dataset entry:

Field Type Description
name str HydroMT data-catalog dataset name
zmin float Minimum elevation threshold
source str Auto-fetch source ("noaa" or null)
noaa_dataset str Explicit NOAA dataset name (auto-discovered if null)

Mask Settings (mask)#

Parameter Type Default Description
zmin float -5.0 Minimum elevation for active cells
boundary_zmax float -5.0 Maximum elevation for boundary cells
reset_bounds bool true Reset existing boundary conditions

Subgrid Settings (subgrid)#

Parameter Type Default Description
nr_subgrid_pixels int 5 Number of subgrid pixels per cell
lulc_dataset str esa_worldcover_2021 Land-use/land-cover dataset
reclass_table path null Custom reclassification table CSV
manning_land float 0.04 Default Manning coefficient for land
manning_sea float 0.02 Default Manning coefficient for sea

Data Catalog (data_catalog)#

Parameter Type Default Description
data_libs list [] Additional HydroMT data catalog YAML paths

River Discharge (river_discharge, Optional)#

When configured, adds river discharge source points to the model by intersecting hydrofabric flowpaths with the AOI boundary.

river_discharge:
  flowlines: ./selected_flowpaths.geojson
  nwm_id_column: feature_id
  max_snap_distance_m: 2000
Parameter Type Default Description
flowlines path required GeoJSON file with flowpath linestrings (e.g. exported from QGIS)
nwm_id_column str required Column whose values correspond to NWM feature_id in CHRTOUT
max_snap_distance_m float 2000 Max distance (m) to snap a point to an active cell; farther points are dropped

Validation#

Validate your configuration before running:

coastal-calibration validate config.yaml

The validation checks:

  • All required fields are present
  • Date ranges are valid for selected data sources
  • File paths exist (for required files)
  • Model-specific configuration is consistent (e.g., nscribes < total MPI tasks for SCHISM)