Deep Wave Research
Wavelet-Domain ENSO ForecastingReport 2 of 9 · Deterministic ablations

Software companion

Deterministic Complex-Wavelet SST Forecasting under Limited Observations

Language
Python 3.10+ · CUDA
Scale
Shared repository · 87 modules · ~42,000 lines
Source
Not publicly released

Overview

This report asks whether direct adaptation on a few hundred observed windows can forecast at all, so the software problem is not modelling capacity but controlled comparison. Nine ablation families vary one thing each against a fixed protocol: which tensors unfreeze, which learning rates apply to fresh versus reused parameters, how often validation runs, and which objective is optimized. Everything else — data, split, normalization, selection rule — is held identical by construction, so a difference between families is attributable.

The instrumentation matters more than the training loop here. Low error in this setting is buyable with near-climatological damping, and a residual objective can spend itself cancelling persistence rather than improving on it, so the comparison writers report amplitude ratios and anti-cancellation diagnostics next to the error numbers. That is what turns a good-looking loss into a legible negative result.

Implementation

Sample
335 observed training windows from the 1981–2010 ERA5 slice
Retained protocol
Decoder-last-block adaptation, fresh and reused learning rates of 1e-4 and 5e-6, validation once per epoch, and the unweighted residual_skill_v0 objective
Selection
The guarded best_skill.pt rule, frozen here and reused unchanged by every later phase
Objective
Persistence-residual: the model predicts departures from persistence rather than the field itself
Diagnostics
Amplitude ratios, per-lead correlation, and an explicit residual anti-cancellation comparison

Components

phase_a.py
The ablation family definitions and the summary the report is written from
ablation.py
Generic ablation bookkeeping shared with later phases
training/freeze_policy.py
Which tensors train, including the partial-unfreeze variants the report rules out
training/losses.py
The residual skill objectives and the loss terms the families vary
training/loop.py
The supervised training loop, its validation cadence and its guarded checkpoint selection
training/metrics.py
Field and index metrics, including the amplitude and damping diagnostics
skill.py
Skill definitions shared across the series
scripts/summarize_phase_a.py
The cross-family comparison table
scripts/summarize_partial_unfreeze_ablation.py
The partial-unfreeze sweep summary
scripts/write_residual_skill_comparison.py
Residual-objective versus direct-objective comparison
scripts/write_anticancel_comparison.py
The diagnostic isolating residual learning that merely cancels persistence
scripts/write_long_residual_confirmation.py
The longer-run confirmation that the short-run verdict holds

Ablation protocol

  1. define Register the family in phase_a.py with exactly one varied factor.
  2. train Run the shared loop under the family’s freeze policy, learning rates and objective.
  3. select Apply the guarded best-checkpoint rule; no family gets a bespoke selection.
  4. evaluate Score the same validation windows with the same metric set.
  5. compare Write the cross-family table with amplitude and cancellation diagnostics beside the errors.

Reproducibility and validation

  • Every family shares data, split, normalization and selection rule, so the varied factor is the only admissible explanation for a difference.
  • Amplitude ratios are reported with every error number, because a near-climatological prediction wins on error while being useless.
  • The anti-cancellation writer exists specifically to detect a residual model that improves loss by undoing persistence rather than by adding information.
  • The protocol frozen here — freeze policy, learning rates, validation cadence, selection rule — is the protocol every later report inherits, so cross-report comparisons stay meaningful.

Availability

Not publicly released. The ablation harness has no data of its own: it runs on the ERA5-derived coefficient stores built by the system-validation stage, which need Copernicus credentials to rebuild.

Companion research

Nine controlled ablation families on 335 observed training windows: architecture access, trainability boundary, amplitude and skill-aware objectives, and persistence-residual target parameterizations.

Read the research report