Model Architecture

Model Architecture

CHESS turns a population of coastal storms into the probabilistic response of one coastal structure transect, a Protective System Element (PSE). Every run follows the same six steps. The library script (CHESS_Usage_Example.m) and the GUI call the same functions; only the input screens differ.

The four building blocks

Block	What it is	Where it comes from
Configuration (config)	Project details, the PSE, the workflow and every switch	A PSE input file: CHESS_*_inputs.xlsx or PSE_Templates/*.csv. See Model Inputs and config_reference
PSE (structure)	The 1-D cross-section: structure type, crest, toe, slopes, armor	The geometry rows of the input file (create_structure_geometry.m)
Storm database (storm, prob_mass, db_info)	Every storm at the savepoint (water level and waves, Peaks and/or Timeseries), TC storm weights, bias and uncertainty	CHS savepoint files, or a prepared .mat. See Model Inputs
Uncertainty	Forcing uncertainty (SWL, Hm0) and response uncertainty (q, R2%, Dn50, P1)	CHS_Dependencies (by region) or manual values, and primary_responses_epistemic_uncertainties.txt

Pipeline

 PSE input file ──► 1. SETUP                call_input_parser.m
                        │                  read_chess_input → finalize_structure_config → finalize_config
                        │                  call_environment_setup.m (output paths, hotstart level)
                        ▼
 CHS .zip/.h5/.mat ─► 2. STORM DATABASE      call_chs_data_formater.m
                        │                  convert + quality check → <db>.mat (storm, prob_mass, db_info)
                        ▼
                     3. PROJECT FORCING      call_project_forcing_formater.m
                        │                  PROS: replicates   LCS: life cycles   DET: every storm once
                        ▼
                     4. UNCERTAINTY          call_uncertainty_engine.m   (skipped by DET)
                        │                  SWL and Hm0 perturbed per replicate / storm
                        ▼
                     5. ADJUSTMENTS          call_project_forcing_adjuster.m
                        │                  sea level rise, random tides, depth limitation, dry toe
                        ▼
                     6. RESPONSES            call_project_response.m
                                           PROS: chess_pros → hazard curves (PST / JPM)
                                           LCS:  chess_csr  → life-cycle reliability, damage
                                           DET:  chess_det  → response per storm
                        ▼
                     Results + plots       <db>_<wflow>_project_responses.mat, CHESSPlots

Step	Main function	Output	Details
1. Setup	call_input_parser.m	config, structure	config_reference, Hotstart Levels
2. Storm database	call_chs_data_formater.m	storm, prob_mass, db_info	Model Inputs
3. Project forcing	call_project_forcing_formater.m	project_forcing	CHESS PROS, CHESS LCS, CHESS DET
4. Uncertainty	call_uncertainty_engine.m	perturbed project_forcing	Model Conventions
5. Adjustments	call_project_forcing_adjuster.m	adjusted project_forcing	Model Conventions
6. Responses	call_project_response.m	Resp	PSE Hydraulic Responses

Each step saves its result, so a rerun of the same case can skip the steps whose inputs did not change (Hotstart Levels). File locations are on Model Outputs.

What each workflow does with the forcing

workflow	Name	Forcing (step 3)	Responses (step 6)	Answers
1	CHESS PROS	Every storm, with uncertainty replicates	Response per replicate → hazard curve with confidence limits	What response has a 1% annual chance of being exceeded?
4	PROS-FB	As PROS	Forcing hazard curves → responses from them	Same, for responses built from forcing hazard curves
3	CHESS LCS	Monte Carlo life cycles of Poisson-sampled storms	Response per storm per life cycle → reliability, damage progression	How does the structure perform over a 50-year life?
2	CHESS DET	Every storm once, as recorded	Response per storm, no statistics	What does each storm do to this structure?

Code map

Folder	Holds
Setup/	Input reading, config rules, output paths, hotstart, storm database info
CHS/	CHS HDF5 conversion, storm preparation and quality checks
Forcing_Generation/	Project forcing per workflow, LCS sampling, tides, adjustments
Uncertainty/	Forcing uncertainty
Structure_Reponses/	Response equations, PROS, LCS-CSR and DET drivers
Extreme_Value_Analysis/	PST (XC) and JPM (TC) hazard curve engines
Visualization/	Plot classes (CHESSPlots → pros_methods, lcs_methods, det_methods)
PSE_Templates/	One input template per structure type
GUI/	The CHESS app
docs/	config_reference.md