Model Inputs

Model Inputs

A CHESS run needs a PSE input file, a storm database source and, optionally, a tide file and the CHS_Dependencies folder. Field-by-field details are in config_reference.

1. PSE input file

One file describes the project, the PSE (structure transect) and the run settings. There is one template per structure type:

Structure type	struc_type	Library template	Excel template
Levee	1	PSE_Templates/levee_pse.csv	CHESS_levee_inputs.xlsx
Floodwall	2	PSE_Templates/floodwall_pse.csv	CHESS_floodwall_inputs.xlsx
Rubble mound	3	PSE_Templates/rubble_mound_pse.csv	CHESS_rubble_mound_inputs.xlsx
Low-crested breakwater	4	PSE_Templates/low_crested_breakwater_pse.csv	CHESS_low_crested_breakwater_inputs.xlsx

• Format. .csv or .xlsx. The .csv files need no Excel; the GUI reads them first and falls back to the .xlsx copy.
• Layout. read_chess_input.m finds every section by its "Model Variable Symbol" header, in any column and any order, and reads each section to the next title. Only the symbol and the value matter; do not rename symbols.
• Hidden fields. A few advanced fields (e.g. the LCS sampling switches) are not in the templates. Add their row with the symbol and value to use them; otherwise defaults apply.
• Elevations are signed, in the project datum. Enter a toe below datum zero as a negative elevation, not as a positive depth (Model Conventions).

The file is read into config and structure by call_input_parser.m. Structure rules (berms hidden, floodwall toe) and run rules (response restrictions per structure type, defaults, output files) are applied by finalize_structure_config.m and finalize_config.m.

2. Storm database

The storm database <db>.mat holds storm (every storm, by storm type, data type and dataset), prob_mass (TC storm weights and intensity bins) and db_info (bias, uncertainty, offshore elevation, build date). It is built once per project and shared by every PSE and alternative (Model Outputs).

Sources (chs_zip in the input file)

Source	What it contains	Notes
CHS .zip or .h5 files	Savepoint files downloaded from the Coastal Hazards System	Converted with chs_h5_converter.m. The .zip is read without unzipping until the build
CHS_Data .mat	Already converted CHS files	Skips the HDF5 conversion
storm + prob_mass .mat	A prepared storm database (e.g. custom modelling)	No CHS file checks; the request must be in the provided data

CHS file rules

Checked by file name before anything is unzipped or converted (chs_storm_file_names.m, chs_study_identity.m, chs_storm_file_slots.m):

• Only .h5 files with a Peaks or Timeseries data type token are read. Other files (HC, AEP, AEF) are ignored.
• One CHS study: one region, one simulation, one post type, one water level (ADCIRC) savepoint and one wave savepoint.
• Each storm type × data type slot is empty or holds exactly one water level file and one wave file (e.g. XC Peaks = ADCIRC + SWAN).
• The run's request must be covered: CC needs TC and XC; use_timeseries needs Timeseries for every requested storm type; WLP/WHP need both Peaks and Timeseries.

File names follow <region>_<storm type>_<simulation>_<post type>_SP<id>_<model>_<data type>.h5, for example CHS-NA_XH_SimB_Post0_SP05572_ADCIRC01_Peaks.h5.

Datasets

Dataset	Meaning
Peaks Default	The peak SWL and the peak wave conditions of each storm, as in the CHS Peaks files
Peaks WLP	Water Level Priority: wave conditions taken at the time of the peak water level (needs Timeseries)
Peaks WHP	Wave Height Priority: water level taken at the time of the peak wave height (needs Timeseries)
Timeseries Default	The full hourly hydrograph of each storm

Storm types

Code	Storm type	Probability model
XC	Extratropical	Record length: Nstm_XC storms in Nyrs_XC years
TC	Tropical	Discrete storm weights from CHS_Dependencies (needs the region's probability masses)
CC	Combined	TC and XC together

Without CHS_Dependencies coverage for the region, CHESS runs XC only; a TC or CC request stops the run with an explanation.

3. CHS_Dependencies (regional data)

A read-only folder (config.chs_dependencies) with, per CHS region:

• Probability masses for TC sampling and hazard curves.
• Study grid, used for the savepoint's offshore elevation (offshore_elevation, the grid point nearest the savepoint).
• Bias and uncertainty for SWL and Hm0.

These values are written into the storm database's db_info when it is built. Without them, bias and uncertainty are entered manually and the offshore elevation comes from the PSE file.

4. Tide file (optional)

Needed only when apply_random_tides = 1. An hourly two-column .csv (Date, Prediction [m]) of NOAA tide predictions, at least as long as the longest storm hydrograph. Each storm gets a random tide start hour; the tide is added to its SWL.

Create one with:

create_tide_file('8423898', 'MSL', '20260101', 'chess_tidal_file.csv');

• The datum must match the storm data datum, because the tide is added directly to the storm water levels.
• noaa_tide_stations.m lists NOAA harmonic prediction stations and noaa_station_datums.m lists the datums a station accepts.
• Predictions are downloaded at 6-minute intervals and stored hourly. Tide files made by older versions hold 6-minute data and should be recreated.
• Station list: NOAA Tides & Currents.