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.
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 inhgrid.gr3and querying the CO-OPS API. Writes astation.infile so SCHISM outputs time-series at those locations, and astation_noaa_ids.txtcompanion that maps station indices to NOAA station IDs. Theschism_prepstage then patchesparam.nmlto 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 tofigs/.
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)#
| 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:
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)