Cama Flood Integration

MANDATORY EXECUTION POLICY -- READ BEFORE PROCEEDING

You MUST run the actual CaMa-Flood Fortran binary (MAIN_cmf) described in this document. If the model fails to compile or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python routing formula, Muskingum equation, or hand-coded approximation in place of the real CaMa-Flood binary. Doing so produces scientifically invalid results and defeats the purpose of the KI.

Before starting, run: python preflight_check.py (in this KI directory) to verify that the model binary and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — The model's own documentation for expected formats/units
3. Find working examples — Check outputs/ or the model's shipped test data
4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

<!-- KI-MAP:BEGIN (projected by generate_skill_map.py — edit the KI, not this table) -->

KI map — what to read, and when

Projected 2026-08-20 from the KI's actual contents — 9 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

<!-- KI-MAP:END -->

<!-- KI-TOOL-INDEX:BEGIN (projected by generate_skill_map.py — the discoverability contract: every public tool, exact path; PURPOSE stays human-authored elsewhere) -->

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

6 public tools; _-prefixed helpers and packaging files excluded.

<!-- KI-TOOL-INDEX:END -->

CaMa-Flood v4.20 -- River Routing and Floodplain Model

CaMa-Flood (Catchment-based Macro-scale Floodplain model) is a global-scale river routing model that simulates river discharge, water depth, and floodplain inundation from gridded runoff input. It is the coupling backbone between land surface/hydrological models (VIC, wflow, HYPE) and local flood models (SFINCS).

Key Paths

Pipeline Overview

Stage 0: Preflight         python preflight_check.py
                           |
Stage 1: Prepare runoff    tools/prepare_runoff_input.py
         (VIC/wflow/HYPE   Converts model output -> CaMa NetCDF
          -> NetCDF)        Output: {basin}_runoff_1d_YYYY.nc
                           |
Stage 2: Configure basin   tools/configure_simulation.py
         (map preparation)  Step 2.1: Regionalize (cut_domain from glb_15min)
                            Step 2.2: Generate inpmat (VIC grid -> CaMa grid)
                            Step 2.3: Channel parameters (calc_outclm + calc_rivwth)
                            Step 2.4: Generate run script
                            Output: map/{basin}_15min/ with all .bin files
                           |
Stage 3: Execute           tools/run_cama.py
                            Runs MAIN_cmf via generated shell script
                            Handles spin-up, restart, yearly loops
                            Output: o_outflw{YYYY}.nc, o_flddph{YYYY}.nc, etc.
                           |
Stage 4: Post-process      tools/parse_cama_output.py
                            Extract discharge at gauge points
                            Compute flood statistics
                            Reduce a variable over a date window to a 2-D field (--field)
                            Reads BOTH output forms: o_{var}{YYYY}.nc and {var}{YYYY}.bin
                            Output: CSV time series, spatial summaries, field NetCDF
                           |
Stage 5: Flood extent      tools/downscale/run_downscale.sh   (15min -> 1min/30sec/...)
         (ONLY for         tools/gfd_flood_obs.py             (GFD v1.4 observation)
          fldfrc/fldare)    Output: flood_{YYYYMMDD}.bin, aggregated obs NetCDF

Validating flood extent (fldfrc, fldare) against GFD

docs/validation_convention.yaml (fldfrc / spatial_snapshot, determining metric csi, Bernhofen 2018 bands: satisfactory 0.5 / good 0.6 / very good 0.7) requires the sub-grid fraction to be downscaled to the native high-resolution grid before wet/dry thresholding. The raw 0.25° fldfrc is NOT comparable to a 250 m satellite mask. The working chain is:

# 1. the run MUST emit binary output -- the official downscaler cannot read o_*.nc
python tools/configure_simulation.py ... --output_format binary \
       --output_vars 'outflw,rivout,rivdph,rivvel,sfcelv,flddph,fldfrc,fldare,rivsto'

# 2. downscale flddph with CaMa's own downscale_flddph_trib
bash tools/downscale/run_downscale.sh --map_dir <map> --out_dir <out> \
     --syear 2001 --smon 8 --eyear 2001 --emon 11 --res 1min \
     --west 98 --east 109.5 --south 8.5 --north 21.75 --dest <dest>

# 3. build the observation on the SAME grid
python tools/gfd_flood_obs.py --event_id 1781 \
     --west 98 --east 109.5 --south 8.5 --north 21.75 \
     --resolution 0.0166666666666667 --out_nc gfd_1781_1min.nc

Three traps that silently destroy CSI (dt_cama_015):

1. Permanent water. GFD's flooded band EXCLUDES JRC permanent water; the downscaler FORCES every <res>.rivwth.bin pixel to max(0.1, depth). Drop permanent-water pixels (gfd_flood_obs.py does by default) and threshold the model strictly above 0.1 m.
2. Reduction. GFD band 1 is a composite MAXIMUM extent over the whole event window — so reduce the model with max over the same window, never sample one day.
3. Cloud / footprint. GFD is NaN outside the observed footprint and MODIS cannot see through cloud (clear_views, clear_perc). Require a minimum observed fraction per cell.

Pick the window as a multiple of BOTH the target resolution and 0.25°, at least 1.25° inside the map domain (the downscaler adds a 5-grid buffer), and confirm the raster footprint from the GeoTIFF's own bounds rather than the DFO centroid.

Stage Skill Documents

• Stage 0: Preflight skill
• Stage 1: Prepare runoff skill
• Stage 2: Configure basin skill
• Stage 3: Execute CaMa-Flood skill
• Stage 4: Post-process output skill

Data Preparation

Data Validation Reference: See data_ki/ObservedQ/SKILL.md for observed discharge validation data. See data_ki/ChinaDEM/SKILL.md for DEM and river network data.

Input Runoff Requirements

CaMa-Flood accepts gridded runoff on a regular lat/lon grid as NetCDF:

• Variable name: Runoff (capital R)
• Units: mm/day (CaMa-Flood converts internally to m3/s using grid area)
• Dimensions: (time, lat, lon)
• Latitude order: North-to-South (descending) -- this is critical; see dt_cama_007
• Grid resolution: Typically 0.25 deg (matching VIC/wflow)
• Time step: Daily (IFRQ_INP=24 hours)

Data KI Adapters

CRITICAL: Unit Mismatches (dt_cama_009)

VIC outputs runoff in mm/day. CaMa-Flood expects mm/day in the NetCDF. Do NOT convert to m3/s before feeding to CaMa -- the model handles the area-weighted conversion internally using ctmare.bin (catchment area).

If you accidentally provide m3/s, discharge will be off by orders of magnitude (typically 1e6 too high for large basins).

Map Preparation (Three Mandatory Steps)

CRITICAL WARNING: Every new basin requires fresh map preparation. NEVER reuse map files from another basin (dt_cama_005). The three steps MUST be executed in order.

Step 1: Regionalization (cut from global map)

Extracts a regional sub-domain from the global 15-minute river network.

# Directory: map/{basin}_15min/src_region/
# Inputs: region_info.txt with SOURCE, WEST, EAST, SOUTH, NORTH
# Tools: cut_domain, cut_bifway, set_map, combine_hires
# Output: nextxy.bin, ctmare.bin, elevtn.bin, nxtdst.bin, rivlen.bin,
#         fldhgt.bin, width.bin, 1min/ (high-res for downscaling)

The configure_simulation.py tool automates this step. If running manually:

1. Create the map directory: mkdir -p map/{basin}_15min/src_region
2. Copy tools from glb_15min: cp -r map/glb_15min/src_region/* map/{basin}_15min/src_region/
3. Recompile (binaries are platform-specific): cd map/{basin}_15min/src_region && make clean && make all
4. Edit s01-regional_map.sh with basin bounds (add buffer of ~0.5 deg)
5. Run: ./s01-regional_map.sh

Step 2: Input Matrix Generation (VIC grid -> CaMa grid mapping)

Creates the spatial mapping between the source runoff grid and the CaMa river network.

# Directory: map/{basin}_15min/src_param/
# Inputs: VIC grid extent (WESTIN, EASTIN, NORTHIN, SOUTHIN), grid resolution
# Tools: generate_inpmat
# Output: diminfo_{basin}_025deg.txt, inpmat_{basin}_025deg.bin

CRITICAL: WESTIN/EASTIN/NORTHIN/SOUTHIN must match the VIC grid extent, NOT the CaMa domain extent (dt_cama_002). Use cell edge coordinates (center +/- half resolution).

Step 3: Channel Parameters (width, depth, Manning's n)

Derives river channel geometry from climatological mean discharge.

# Must run calc_outclm from glb_15min/ (needs global river network, dt_cama_004)
# Then run calc_rivwth from the REGIONAL directory with REGIONAL diminfo (dt_cama_003/008)
# Output: rivwth.bin, rivhgt.bin, rivwth_gwdlr.bin, rivman.bin, outclm.bin

Default channel parameter coefficients:

• Width: W = WC * Q^WP, WC=2.50, WP=0.60, WMIN=5.0 m
• Depth: H = HC * Q^HP, HC=0.10, HP=0.50, HMIN=1.0 m
• Manning's n: 0.03 (river), 0.10 (floodplain)

Namelist Configuration (input_cmf.nam)

The CaMa-Flood binary reads configuration from a Fortran namelist file. Key sections:

&NRUNVER -- Run version control

&NDIMTIME -- Grid and time

&NPARAM -- Physical parameters

&NSIMTIME -- Simulation period

&NMAP -- River network files (ALL must use absolute paths)

&NFORCE -- Forcing input

&NOUTPUT -- Output control

6. Output Description

This section restates dag.yaml; if the body and dag ever disagree, dag.yaml wins.

Headline output (validation_rank: 1):

outflw -- Total main-river-network discharge (river outflow + floodplain outflow + bifurcation outflow); primary validation variable. (m3/s)

Other dag-declared outputs: rivout, rivdph, sfcelv, flddph, fldfrc, fldare, rivvel, rivsto.

8. Unit Conversion Table

This table records the body-level unit contract for input preparation and post-processing. For output variables, dag.yaml is authoritative.