lzwei196/kiss---knowledge-infrastructure-for-scientific-simulation/docs

Apply Deltas to VIC Forcing — Skill Document

Stage ID: s3_apply_deltas

Pipeline order: 3 of 4

Depends on: s2_compute_deltas (delta file), VIC baseline forcing (forcing_1d output)

Purpose

Generate future VIC forcing files by applying CMIP6 monthly climate change deltas to the existing CMFD/MSWX baseline forcing. This preserves the sub-daily variability and all 7 meteorological variables from the baseline while incorporating projected changes in temperature and precipitation.

Prerequisites

Before starting this stage, verify:

• [ ] Delta file exists: deltas/{MODEL}_{ssp}_deltas_{basin}_{period}.nc
• [ ] Baseline forcing_1d files exist: outputs/{basin}/vic_temp/forcing/forcing_1d/temp_*.nc, prec_*.nc, etc.
• [ ] VIC grid file exists
• [ ] Python environment activated

Inputs

Procedure

Step 1: Choose target period

The target period should match the FUTURE_PERIOD used in delta computation. For a 30-year window:

FUTURE_PERIOD = 2041-2070

The tool recycles baseline years to fill the target period. Leap and non-leap baseline years are cycled separately, in order: a leap target year takes the next leap baseline year (real Feb 29), a normal target year the next normal baseline year; within each leap-status group every baseline year is used before any is reused. Example: baseline 1990-2000 (leap: 1992, 1996, 2000; normal: the other 8) onto 2041-2044 gives 1990, 1991, 1993, 1992 (2044 is leap). So the baseline year order is not kept exactly. Only monthly forcing_1d files are accepted (annual files stop the tool). If the target period has a leap year but the baseline has none, the tool stops with an error (it does not invent Feb 29).

Baseline forcing_1d NetCDF units (CMFD / MSWX convention, required by both S3 tools): temp K, prec kg m-2 s-1, pres Pa, srad W m-2, lrad W m-2, shum kg kg-1 (specific humidity), wind m s-1, 3-hourly. Do not pre-convert to degC / mm / kPa; that happens in Step 3 (VIC ASCII output). All 7 variables and all three deltas (delta_pr, delta_tasmax, delta_tasmin) are required: a precipitation-only GCM or a missing baseline variable/month stops the tool with exit code 2.

Step 2: Run delta application

python skills/climate-projection/tools/s3_apply_deltas/apply_deltas_forcing.py \
  outputs/{basin}/vic_temp/forcing/forcing_1d \
  outputs/{basin}/climate_projection/deltas/{MODEL}_{ssp}_deltas_{basin}_2041-2070.nc \
  outputs/{basin}/vic_temp/grid/basin_grid.nc \
  outputs/{basin}/climate_projection/forcing_{MODEL}_{ssp} \
  {basin} {MODEL} {ssp} \
  2041 2070

Expected result: 7 variables × 30 years = 210 NetCDF files in forcing_{MODEL}_{ssp}/

Runtime: 5-15 minutes (reads and rewrites all forcing files).

Step 3: Convert projected forcing NC → VIC ASCII

Use the dedicated conversion tool (NOT process_forcing.py, which requires error-prone config editing):

python skills/climate-projection/tools/s3_apply_deltas/convert_projected_forcing.py \
  outputs/{basin}/climate_projection/forcing_{MODEL}_{ssp} \
  outputs/{basin}/climate_projection/forcing_final_{MODEL}_{ssp} \
  outputs/{basin}/vic_temp/soil/SOIL_PARAM_COMPLETE.txt \
  "{forcing_prefix}" "{basin_tag}" \
  2041 2070

Where:

• {forcing_prefix} matches the baseline prefix (e.g., nuxia_0.25deg_). Check with: ls outputs/{basin}/vic_temp/forcing/forcing_final/ | head -1
• {basin_tag} is the suffix used in NC filenames (usually the basin name from config_paths.py)

Expected result: One ASCII file per grid cell in forcing_final_{MODEL}_{ssp}/, each with 87,664 lines (30 years × 365.25 days × 8 timesteps/day). 7 columns: air_temp, prec, pressure, swdown, lwdown, vp, wind.

Runtime: ~2-5 minutes per SSP scenario.

Step 4: Verify projected forcing

# Check file count matches grid cells
ls outputs/{basin}/climate_projection/forcing_final_{MODEL}_{ssp}/ | wc -l
 
# Check line count (should be ~87,664 for 30 years of 3-hourly data)
wc -l outputs/{basin}/climate_projection/forcing_final_{MODEL}_{ssp}/* | tail -1
 
# Spot-check temperature (should be in Celsius, not Kelvin)
head -3 outputs/{basin}/climate_projection/forcing_final_{MODEL}_{ssp}/*_30.0000_*

Expected Outputs

Validation Checks

1. Temperature increase: Mean annual temperature in projected forcing > baseline
2. Variable completeness: All 7 variables present (not just temp and prec)
3. No NaN values: Projected forcing should have no gaps
4. Non-negative precipitation: All precip values >= 0 after multiplicative scaling

Common Pitfalls

PITFALL: Using process_forcing.py instead of convert_projected_forcing.py

The old approach required editing hardcoded paths in process_forcing.py (INPUT_DATA_DIR, START_DATE, etc.) — error-prone and not reusable.

Do this instead: Use convert_projected_forcing.py which takes all parameters as CLI arguments.

See diagnostic triplet dt_cc_006.

PITFALL: Time coordinate mismatch

When cycling baseline years into future years, leap years must line up. apply_deltas_forcing.py now cycles leap and non-leap baseline years separately, so each target year gets a baseline year with the same leap status (Feb 29 is only dropped if the baseline has no non-leap year at all), and convert_projected_forcing.py stops if time steps are duplicated, missing or irregular.

Do this instead: Use a baseline of at least 4 consecutive years (it then always contains both leap and non-leap years).

PITFALL: Missing variables or NaN in projected forcing

convert_projected_forcing.py needs all 7 variables with the NetCDF units above. It no longer fills missing variables or NaN with defaults: it stops with exit 1 (missing variable / wrong unit) or exit 2 (NaN cells, time gaps), and lists the failed cells.

This skill document is part of the climate-projection knowledge infrastructure. Stage 3 of 4 | Tools used: apply_deltas_forcing | Related triplets: dt_cc_006, dt_cc_007