# oggm-adapbs: development notes

Started 2026-11-11 (code moved out of OGGM's `adapbs` branch, where it was written from
2026-10-30). Fabien Maussion with Claude.

## Why this package exists

- AdaPBS (adaptive particle batch smoother, Aalstad et al., 2026, GMD 19, 8565-8596) is an
  adaptive multiple importance sampling (AMIS) scheme from MuSA (E. Alonso-González,
  K. Aalstad; https://github.com/ealonsogzl/MuSA). Chloe Hancock (PhD student, Bristol)
  uses it through MuSA for OGGM calibration and runoff uncertainty; we want it in OGGM's
  workflows.
- Licences: MuSA is GPL-3.0, OGGM is BSD-3. The AdaPBS code was first written inside OGGM
  (PR OGGM/oggm#2023, branch `adapbs`), which blocks a merge.
- Email thread with Esteban and Kristoffer (2026-11-03 to 05, copy in
  `../oggm-mac/claude/adapbs/license_mails.txt`):
  - Esteban first proposed an OGGM backend inside MuSA. Fabien: MuSA is not
    pip-installable with light requirements (Fortran, data, FSM, no tests), and OGGM must
    never import MuSA. Proposed two tracks: short term a BSD grant for the AdaPBS files or
    a small separate GPL package (this one), long term an OGGM backend in MuSA.
  - 2026-11-05, Esteban: they will pull the DA schemes (not only AdaPBS) out into a small,
    numpy-only, BSD-3 package (citation requested, not a legal condition), to share with
    Fabien and Chloe before it goes public. Go ahead with our own implementation
    meanwhile and switch later. He will want help with a MuSA(OGGM) implementation.
  - Kristoffer (2026-10-22): fine to fork the AMIS scheme rather than depend on MuSA;
    PRs back welcome; cite the AdaPBS paper (and perhaps the MuSA one).
- So: this package is temporary. When the MuSA authors' BSD package is out, the
  algorithm should come from there, and the OGGM-specific parts (prior, forward models,
  tasks, notebooks) can move into OGGM.

## What is in the repo

- `oggm_adapbs/adapbs.py`: the algorithm, no OGGM import. `run_adapbs(forward, obs,
  obs_err, x_min, x_max, prior_mean=, prior_sd=, n_particles=, max_iterations=,
  neff_threshold=0.3, rng=)`; `amis_weights` (MuSA's `AMIS`), `glogit`/`gexpit`
  (logit-normal priors), `nearest_pd`, `weighted_quantile`, `weighted_summary`. The
  differences with MuSA are listed in the module docstring (slogdet, numpy replacements
  for statsmodels, logit-normal only, NaN runs get zero weight, log evidence returned,
  rng passed in, default threshold 0.3 instead of MuSA's 0.1).
  - `forward(theta, iteration)`: theta (Ne, Np) in parameter space, returns (Ne, No)
    predictions, NaN for failed runs, or a tuple (predictions, dict of per-particle
    extras). `iteration` is for forward models which need it (e.g. unique file names per
    particle and iteration in dynamical runs).
- `oggm_adapbs/massbalance.py`: OGGM tools for melt_f, prcp_fac, temp_bias:
  - `informed_temp_bias`: copied from OGGM's `mb_calibration_from_geodetic_mb` (BSD-3).
    OGGM master has no public function for it (the refactor of the `adapbs` branch was
    dropped). Could be replaced by an OGGM function later.
  - `mb_prior`: centres from `cfg.PARAMS['melt_f']`, `cfg.PARAMS['prcp_fac']` or
    `decide_winter_precip_factor`, the temp bias file (else 0); default bounds melt_f
    from settings, prcp_fac centre /2 to x2, temp_bias centre +-3 K; overrides with
    `prior_centre` / `prior_bounds`.
  - `static_mb_model`: MB model on the inversion flowlines.
  - `seasonal_specific_mb`: winter / summer / annual MB of hydrological years (NH
    default Oct-Apr / May-Sep; SH with `start_month=4, summer_start_month=10`).
  - `mb_calibration_from_geodetic_mb_adapbs`: entity task, returns an xarray Dataset of
    particles, weights, predictions, diagnostics. Writes nothing to the gdir.
- `oggm_adapbs/dynamic.py` (2026-11-13, experimental): AdaPBS replaces static calibration
  + regional inversion + dynamic spinup for one glacier.
  - `run_dynamic_particle(gdir, params, filesuffix, ...)`: per-particle settings file and
    inversion (OGGM tasks with input/output filesuffix, `glen_a`, fs=0), growth period
    (`ConstantMassBalance` centred on the spinup period, temp_bias + offset, as in
    `run_dynamic_spinup`), historical run in memory (`run_until_and_store` without
    files), then deletes the particle's files (`*{suffix}.*`). Rejects before the
    dynamics if the inverted volume is outside `volume_bounds`.
  - `dynamic_calibration_adapbs`: entity task; spawn pool (`n_workers`, config via
    `cfg.pack_config()`), targets dmdtda (per RGI area, Hugonnet err x 0.2), area_min_h
    (2 m) and volume at RGI date + 1. Overrides `ref_mb`, `ref_volume`... for tests.
  - `iceboost_volume` (v20260705 tables, with `vol_err_km3`), `terminus_step_km2`,
    `area_error_km2`, `dynamic_prior`.
  - Cost on Vernagtferner: ~0.13 s per particle; 2500 runs in 88 s on 6 workers.
  - Note: a prototype which grew the glacier with the default A instead of the
    particle's gave a different MB (-845 vs -927): the module uses the particle's A in
    all three phases (checked: without growth, identical to `run_from_climate_data`).
- Tests (`oggm_adapbs/tests/`): algorithm tests (transforms, quantiles, AMIS = importance
  sampling with one proposal, linear-Gaussian analytic posterior, failed runs, MuSA
  comparison) and OGGM tests on `hef_gdir` (prior, seasonal MB against monthly sums,
  geodetic task).
- CI: one OGGM image + a MuSA-master job allowed to fail (`ci/get_musa.sh`).
- `pyproject.toml`: hatchling, version in `__init__.py` (0.1.0.dev0), `oggm` listed
  unpinned (it needs OGGM master, see CLAUDE.md).

## Decisions

- 2026-10-30: logit-normal priors centred on OGGM's informed values, not mid-range (the
  evidence prefers it on Hef). Prior centres never from `gdir.settings`.
- 2026-10-30: default Neff/Ne threshold 0.3 (MuSA uses 0.1, which stopped too early:
  noisy posteriors).
- 2026-11-05: separate GPL package (this one) rather than waiting for a licence grant.
- 2026-11-11: no OGGM change needed for the package to work; the OGGM `adapbs` branch is
  back to master's files.
- 2026-11-11: tests mirror OGGM's (OGGM fixtures via its conftest, one OGGM docker
  image on CI).
- 2026-11-11: MuSA comparison test pinned to the commit we ported from; a separate CI job
  against MuSA master is allowed to fail (not a weekly job: overkill, Fabien).
- 2026-11-11: "AdaPBS" without "the" when used as a noun (Fabien's usage).
- 2026-11-11 (WGMS notebook): the "mean MB only" experiment was dropped; it gets its own
  notebook (no silver bullet there). Part 1 uses OGGM's default bounds for the prior so
  that the comparison with `mb_calibration_to_rmsd` is not about the bounds.
- 2026-11-11: fixed the AMIS log evidence: it was too low by log(number of iterations)
  (`lse_psi` is the log of the *sum* of the proposal densities, so divide by Ne, not
  Nl * Ne). Found with a 200k-sample brute-force reference on Vernagtferner (log Z
  -10.34, AdaPBS -12.19 after 6 iterations); new check against the analytic evidence in
  `test_run_adapbs_linear_gaussian`. The weights were not affected. The E2/E3 evidence
  values in `../oggm-mac/claude/adapbs/CLAUDE.md` all stopped after 2 iterations: each is
  log 2 too low, their comparison holds.
- 2026-11-11 (notebook 2): "no prior" = flat prior: logit-normal centred mid-range,
  sd 1.4, OGGM's bounds. 1000 particles, max 20 iterations (Kristoffer's advice for weak
  data). Information gain as KL = E_post[log L] - log Z (no package helper yet: a
  function in the notebook).
- 2026-11-13 (notebook 3, dynamic calibration, Chloe's workflow): AdaPBS replaces the
  static calibration + dynamic spinup. Code in a package module (`dynamic.py`), not only
  the notebook, so Chloe can run it on the cluster. Parameters: melt_f, prcp_fac,
  temp_bias, log10 of a Glen A factor (centred on OGGM's default A, not the regionally
  calibrated one: no IceBoost information in the prior; bounds +-1 like OGGM's a_bounds),
  growth temperature offset (added to temp_bias during the growth period, centre 0,
  +-3 K). Volume sigma = IceBoost `vol_err_km3` x factor (default 1): only the
  `*_v20260705` tables on the cluster have errors (OGGM uses `v20260701`, same volumes).
  Area sigma from Fabien's Slack formula (5% + discretisation term).
- 2026-11-13 (Fabien): third target = mean thickness (IceBoost vol / IceBoost area
  against model volume / total model area), sigma 20% (`volume_target='thickness'`,
  `volume_rel_err=0.2` are the defaults): IceBoost errors (66% on Vernagtferner) make
  the volume uninformative, and thickness depends less on the size and is less
  correlated with the area target. Volume target kept as an option.
- 2026-11-13 (Fabien): **notebook 3 is a sensitivity experiment, not a calibration:
  priors must be wide.** Glen A factor from 0.1x to 10x the default.
- 2026-11-13: why A was unconstrained (volume sigma 20%, informed priors): the volume
  at the RGI date depends on A, but the growth offset compensates it (posterior corr
  log A / growth offset -0.66, d lnV/d log10A -0.59, d lnV/dK growth -0.33); the MB
  parameters matter much more after the dynamics than in the inversion
  (V_inv ~ A^-0.2 melt_f^0.15 prcp_fac^0.04).
- 2026-11-13: Fabien found the demo plot (area growing 1974-2015) suspicious. Checked:
  the historical run uses the particle's temp_bias (the growth offset only goes to
  the growth MB model); the prior centre is just far from calibrated (MB 1974-83
  +930, 2000-19 -455 vs -913 observed), and the area lags the volume by ~10 years.
  The particle series now include the growth period (time starts `growth_years`
  before the historical run). Notebook demo particles should start from calibrated
  values. The "OGGM standard workflow" reference must be
  `run_dynamic_melt_f_calibration` (spinup + melt_f recalibration), not
  `run_dynamic_spinup` alone (Fabien).
- 2026-11-13 (Fabien): the dynamic workflow and its notebook must work for any glacier:
  no WGMS data in it (no WGMS target, no WGMS validation).
- 2026-11-13 (finding, not in the notebook): calibrated parameter sets (OGGM L3 static,
  AdaPBS wide posterior median) match MB 2000-19 but are 300-400 kg m-2 yr-1 too
  positive in 1979-93 vs WGMS (L3: +241 / -172 for 1979-83 / 1984-93, WGMS -251 /
  -498): the modelled trend 1980s -> 2010s is ~2x the observed one. The 30-yr spinup
  runs through this period. Cause (climate data or MB sensitivity) not known.
- 2026-11-13: notebook reference = `run_dynamic_melt_f_calibration` on a copy of the
  gdir, `ys=1974`, `ref_mb_err_scaling_factor=0.2` (with 1, the static calibration's
  -88 mismatch is within the error and melt_f is not changed). Result: melt_f 5.16,
  MB -905, area 8.55, thickness 53.7 m, 4 s. Validation plot: volume (IceBoost +-20%
  and its own error), area, annual specific MB (geodetic target), growth period shaded.
- 2026-11-13: the 2025.6 "W5E5" directories ship climate from 1901 (GSWP3-W5E5), not
  1979: a 30-year spinup before the RGI date is possible.

## Notebook 1: `example_workflows/wgms_static_calibration.ipynb`

Static MB calibration against WGMS data with AdaPBS. Vernagtferner (RGI60-11.00719),
L3 2025.6 W5E5 dirs, WGMS winter/summer/annual 1980-2019 (39 years; Hef has seasonal data
since 2013 only).

- Part 1, one target (annual MB series), the AdaPBS equivalent of
  `mb_calibration_to_rmsd`, used to explain the method: why a prior, logit-normal and
  `glogit`/`gexpit`, the observation error, the forward model, the iterations (figure of
  the particles per iteration, Neff), weights and resampled particles, posterior, fit.
- Part 2, winter / summer / winter+summer.
- Then "How much does the prior matter?" (narrow `mb_prior` bounds vs wide).
- Choices: prior sd 1 in normal space; 300 particles, max 10 iterations, threshold 0.3,
  seed 0; error of each annual value sigma_a = RMSD of the deterministic calibration
  (so the most likely AdaPBS parameters minimise the RMSD); seasonal errors
  sigma_a / sqrt(2); years treated as independent (posteriors probably too narrow).
- Results (with OGGM's hydrological-year `mb_calibration_to_rmsd`):
  - deterministic: melt_f 3.54, prcp_fac 1.08, temp_bias 1.47, RMSD 251;
    AdaPBS annual: 3.54 [2.81, 4.39], 1.13 [0.69, 1.66], 1.49 [0.69, 2.40]. Same solution.
  - Both fit the annual MB (RMSD 250) with seasonal biases of ~530-550 kg m-2 (too little
    accumulation and melt).
  - winter constrains prcp_fac (2.56), not melt_f; summer constrains melt_f/temp_bias
    and also wants a low prcp_fac; winter+summer constrains all three (melt_f 3.69,
    prcp_fac 2.59, temp_bias 2.79), seasonal biases < 60, annual RMSD 316.
  - Narrow prior: annual prcp_fac piles at the 1.68 bound (1.97), temp_bias 2.48;
    winter+summer unchanged.
- Runs in ~20 s with OGGM's vectorised MB (was ~4 min).
- The text was filled from the outputs: after any rerun, check the numbers in the text.

## Notebook 2: `example_workflows/geodetic_equifinality.ipynb`

Calibration of the three parameters against the 2000-2020 geodetic MB of Vernagtferner
(-913 +- 154 kg m-2 yr-1), with `mb_calibration_from_geodetic_mb_adapbs`. Runs in ~35 s.

- Four `mb_calibration_from_geodetic_mb` calls (after resetting `gdir.settings` to
  OGGM's starting values: the L3 settings hold the calibrated ones, which OGGM uses as
  starting values): melt_f only 12.38 / 3.36 / 0; temp_bias only 5 / 3.36 / 2.26;
  prcp_fac only 5 / 0.50 / 0; informed three-step 5.29 / 2.69 / 1.71. All -913.1.
- Flat prior: 6 iterations, 6000 runs. Posterior melt_f 6.75 [2.28, 14.70] (prior
  9.28 [3.00, 15.60]), prcp_fac 4.05 [0.64, 9.50] (5.03 [1.04, 9.06]), temp_bias
  1.57 [-1.27, 6.67] (-0.04 [-12.3, 12.3]). Pair plots coloured by the third parameter:
  a 2D surface; the 4 deterministic points lie on it. Low melt_f/prcp_fac favoured
  (less temperature-sensitive MB, thicker surface).
- KL 3.92 nats (brute force 3.89). Half error: +0.65 (theory log 2), marginals
  unchanged, 10 iterations; two decades: 3.95.
- Equifinal particles: winter MB 2000-2019 242-2897 (WGMS 874), dMB for +1 K -539 to
  -2066 (factor ~4); deterministic -572 to -1552; informed three-step winter MB 935.
- Priors: flat / informed OGGM bounds / informed narrow: KL 3.92 / 3.16 / 2.01,
  dMB(+1K) 5-95% [-2066, -539] / [-1512, -499] / [-1440, -633], log Z -10.40 / -9.60 /
  -8.45.
- Note: with the posterior a thin curved surface, AdaPBS (Gaussian proposals) converges
  slowly when the error gets smaller (obs error /4: Neff/Ne < 0.2 after 20 iterations
  with 1000-2000 particles, in the prototypes).

## Notebook 3: `example_workflows/dynamic_calibration.ipynb` (experimental)

Chloe's workflow, as a **sensitivity experiment** (wide priors): AdaPBS replaces static
calibration + regional inversion + dynamic calibration. Vernagtferner L3 2025.6 W5E5;
spinup 30 yr (1974-2020), growth 20 yr; 500 particles, max 20 iterations, 6 workers.
Runs in ~7.5 min if the laptop stays awake (it sleeps with the lid closed: runs then
take hours). Builder script: `build_nb3b.py` in the session scratchpad (edit cell
sources with nbformat).

- Prior: logit-normal sd 1.4 centred mid-range; melt_f 1.5-17, prcp_fac 0.1-10
  (OGGM), temp_bias informed +-5 K, log10 A factor +-1, growth offset +-3 K.
- Targets: MB -913 (sigma 30.8 = 0.2 x 154), area 8.56 km2 (sigma 0.436),
  mean thickness 51.6 m (sigma 20% = 10.3; IceBoost error 66%).
- Demo particles: OGGM static calibration + default A: MB -971 in the dynamical run
  (static/dynamic mismatch); +1 K growth loses its tongue after 1990.
- With growth: 19 iterations (9500 runs, 271 s), 250/500 prior particles fail or are
  rejected. Posterior melt_f 4.69 [2.22, 11.41], prcp_fac 2.14 [0.55, 7.21],
  temp_bias 1.57 [-1.17, 5.23], log10 A 0.12 [-0.73, 0.79] (prior [-0.82, 0.81]),
  growth 0.13 [-2.20, 1.28]. Fit MB -909, area 8.41, thickness 52.8.
- OGGM `run_dynamic_melt_f_calibration` (copy of gdir, err x 0.2): melt_f 5.16,
  spinup temp_bias 1.64, A x2.3; MB -905, area 8.55, thickness 53.7: inside the
  AdaPBS ranges.
- Without growth: 10 iterations (133 s); log10 A 0.37 [-0.28, 0.90] (constrained,
  median x2.3 like OGGM's); log Z -14.22 vs -15.06 with growth.
- Main message: A is identifiable only without the growth period (the growth offset
  compensates A); the data do not ask for the growth period.

## Kristoffer's AdaPBS Q&A (Google doc, meeting with Chloe 2026-10-22)

What it means for this package (his answers in short, then our status):

- **Several observations:** `obs`, `pred` and the error variances must match entry by
  entry (same observable, time, place, ideally resolution). The diagonal Gaussian
  error (additive white noise) is for convenience, not a requirement of AMIS:
  correlated or non-Gaussian errors are a possible extension. Ours: same assumption.
  Notebook 1 treats the years as independent and says the posteriors are probably too
  narrow; a full error covariance in `amis_weights` (e.g. AR(1) for annual MB residuals)
  would be the fix (idea, not decided).
- **Number of particles:** 100 is MuSA's default, rarely lower (30 gave overconfident
  UQ in Clarissa's CryoGrid runs; Ruitang used 200). Rather than 1000 particles, run
  several seeds. Iterations matter at least as much as particles: in Ruitang's glacier
  runs some did not converge with `maxit=10` but nearly all did with 100. Ours: the
  geodetic task defaults to 200 particles and `max_iterations=6`, notebook 1 uses 300
  and 10. Worth revisiting the default `max_iterations` (open question).
- **Forking and attribution:** fine to fork any scheme from `filters.py`, PRs back
  welcome; he would rename MuSA's `AMIS` function to AdaPBS some day (watch for it when
  syncing). Cite the AdaPBS paper (and perhaps MuSA): they had a paper using MuSA
  resubmitted elsewhere with every mention of MuSA removed. Attribution matters to
  them: keep the citations prominent in README, docstrings and notebooks.
- **Bounds:** should only come from physical limits; narrow bounds make sensitive
  parameters pile up against them (his ±20% FSM2 bounds were a demonstration). Ours:
  `mb_prior`'s default bounds (prcp_fac ×/÷2, temp_bias ±3 K) are not physical limits,
  and notebook 1's prior section shows exactly this piling up. Open question: should
  `mb_prior` default to wider (OGGM's) bounds, keeping the information in the centre
  and the sd instead?
- **Early stopping with few observations:** to tell a well-constrained posterior from
  "the data barely update the prior", raise the Neff threshold, use more particles and a
  high `maxit`, then quantify the information content with the information gain (KL
  divergence between prior and posterior). Ours: notebook 2 computes it as
  E_post[log L] - log Z (no package helper yet; a candidate for `adapbs.py`).
- **Priors:** MuSA has normal, log-normal and logit-normal (inference always in an
  unbounded space). Avoid log-normal (fat tails waste particles). A logit-normal centred
  mid-range with σ ≈ 1.4 is the maximum-entropy, near-uniform shape; shifting the
  median skews it; larger σ makes it bimodal. AMIS itself accepts any prior (gamma etc.
  would be an extension). The prior's parameters matter more than its form; he favours
  weakly informative priors. References: Aitchison and Shen (1980) on the logistic
  normal, https://www.jstor.org/stable/2335470; Banner et al. (2020) on priors,
  https://besjournals.onlinelibrary.wiley.com/doi/10.1111/2041-210X.13407 (Table 1:
  classes of priors). Ours: logit-normal only, informed centres, σ = 1.
- 2026-11-11: our docstrings and notebook 1 said the logit-normal becomes bimodal above
  σ ≈ 1.8. Wrong: centred mid-range it is bimodal above √2 ≈ 1.41 (checked
  numerically; off-centre priors stay single-peaked longer, e.g. still one mode at 1.8
  for a normal-space centre of -1.2). Fixed in `adapbs.py`, `massbalance.py` and the
  notebook text.

## Earlier work (in `../oggm-mac/claude/adapbs/`, not in this repo)

- `CLAUDE.md` there: the full log of the static experiments on Hef (E0: identical to
  MuSA's AMIS and to Chloe's loop; E1: AdaPBS against a 40k-sample brute-force reference,
  thresholds and particle numbers; E2/E3: prior centring, decadal vs 20-yr geodetic obs).
- `aletsch/`: dynamic calibration of Great Aletsch (1500-2025 runs, melt_f, prcp_fac,
  temp_bias against Hugonnet MB, RGI area and volume), particles in a spawn pool, one
  settings file per particle. Result: less accumulation and less melt than the static
  calibration fits all three targets. `HANDOVER.md`: summary for the cluster runs.
- Open issue from there: OGGM's area is discrete (one grid point at a time), so an area
  likelihood with a small sigma becomes a step function on small glaciers. Proposal:
  add a discretisation term to the area error.
- `MuSA/`: MuSA clone (commit eb56ca7); `code_samples_261029/`: Chloe's scripts.

## State (2026-11-13)

- Package, tests, CI, README and notebook 1 written; the relevant tests pass locally.
  Fabien committed the first version (commits `8cde749`, `4817f75`); the rerun notebook
  is not committed. Nothing pushed by Claude; CI not run yet.
- The notebook's saved outputs need OGGM's `rmsd_calib` branch (hydrological years,
  vectorised MB), to be merged soon.
- 2026-11-11: notebook 2 (`geodetic_equifinality.ipynb`) written and run, log evidence
  fix in `adapbs.py` + test (the whole suite passes). Not committed.

- 2026-11-13: `dynamic.py` + `tests/test_dynamic.py` + notebook 3 (v2: wide priors,
  thickness target, growth series, OGGM dynamic calibration reference) written and
  run; README updated; whole suite passes (`pytest --run-slow oggm_adapbs`, MuSA test
  skipped without MUSA_DIR). Not committed. Next: decide on the growth period, the
  1974-2000 MB problem, Aletsch / cluster runs (Chloe).
- 2026-11-16: `claude/HANDOVER_cluster.md` written for a Claude session on the cluster
  (experiments E1-E5: other glaciers with / without growth, Aletsch cost, spinup
  length, convergence, thickness error). `claude/` and CLAUDE.md are not in git: copy
  them by hand; the cluster also needs the uncommitted `dynamic.py` and its tests.
- 2026-11-16 (cluster): `dynamic.py` and its tests committed (`648a8aa`). Cluster clone set
  up with a sandbox (`.cluster_env/`, runs in `.cluster_env/runs/`), OGGM master
  `3e63e978`; `pytest --run-slow oggm_adapbs`: 14 passed, 1 skipped (MuSA), ~2 min.
- 2026-11-16 (Fabien): **the purpose was misread.** Chloe's paper 1 is a sensitivity /
  equifinality study of OGGM as it is used today (static calibration, inversion, dynamic
  spinup): keep the plausible parameter sets (AdaPBS replaces her earlier LHS +
  acceptance threshold, GLUE style), then study what drives the spread of downstream
  metrics (2000-2020 runoff so far; she uses SALib). A poorly constrained A or initial
  state offset is a result, not a failure. Renames: `dynamic_calibration_adapbs` ->
  `dynamic_equifinality_adapbs`, notebook -> `dynamic_equifinality.ipynb`; "growth" ->
  "initial state" (`initial_state_years`, `initial_state_temp_offset`): the period does
  not reconstruct a past glacier (Eis et al. 2019 TC, 2021 Front. Earth Sci.), it stands
  for the unknown state at the start of the historical run. Plan:
  `~/.claude/plans/alright-i-want-to-modular-teapot.md` (nb3 rewrite, nb4 runoff +
  simple sensitivity analysis without SALib, slurm scripts, a few glaciers, handover).
- 2026-11-16 (Fabien): runoff = OGGM's total runoff (on + off glacier) over a fixed
  catchment = the glacier area in 2000 (`ref_area_yr=2000`), not the max area of the run.
- 2026-11-16: hydro timing on Vernagtferner (login node, wide priors, seed 0; the
  AdaPBS runs reproduce the laptop numbers exactly, log Z -15.06 / -14.22, but take
  513 / 217 s on 6 workers vs 271 / 133 s on the laptop). Per particle: 0.27 s in
  memory, 0.68 s with `run_with_hydro` (monthly; the hydro part ~0.46 s). Neff 155 but
  2677 particles hold 99.9% of the weight (716 without initial state period), 327
  distinct among 500 resampled draws. Serial cost with initial state period: hydro in
  every run 107 min, rerun of the 99.9% particles 73 min, rerun of the resampled 47 min.
  Storing the geometries during AdaPBS (58 kB + 26 kB diagnostics per run, ~0.8 GB per
  glacier) does not pay off. Decision (Fabien): hydro is a rerun after AdaPBS, on any
  particle selection, default the particles holding 99.9% of the weight (weights
  kept); resampled set as an option. Making `run_with_hydro` faster: another project.
- 2026-11-16: done (not committed): renames; `_particle_start` shared by
  `run_dynamic_particle` and the new `run_dynamic_particle_hydro` (identical glacier,
  tested); `select_particles`, `dynamic_hydro_rerun`, `runoff_metrics`; tests (17 pass);
  `scripts/` (run_glacier.py tested locally; submit.sh / run_slurm.sh with config.sh,
  frozen snapshot, containall: **not tested on slurm yet**); nb3 rewritten as
  `dynamic_equifinality.ipynb` (same numbers as before), nb4
  `dynamic_runoff_sensitivity.ipynb`. Notebooks load saved runs from
  `example_workflows/out/<experiment>/<rgi_id>_adapbs.nc` / `_hydro.nc` (same layout
  as run_glacier.py; Fabien: "load if on disk").
- 2026-11-16 nb4 results (Vernagtferner, 2677 reruns, 339 s on 6 workers): mean
  runoff 2000-2019 22.6 Mt/yr [11.5, 57.8] (factor 5), all from prcp_fac (Spearman
  1.00, binned first-order index 0.98): the geodetic MB fixes the mass loss (~7.8
  Mt/yr), the rest is precipitation, so the runoff spread is the prcp_fac range the
  prior allows. Jul-Sep fraction 0.63-0.87, set by temp_bias (0.98); peak always
  August. Glacier melt share 0.52-0.95 (temp_bias 0.90, prcp_fac 0.81). A and the
  initial state offset: indices 0.1-0.3, probably through their correlation with
  prcp_fac (0.23, 0.30). Sums of indices > 1 (correlated parameters).
- 2026-11-16 (Fabien): the thickness error he meant on 11-13 was a factor on the
  IceBoost error, not 20% of the thickness. Not sure what is best: keep both options;
  new default `volume_rel_err=None, volume_err_factor=0.5` (compromise; relative
  IceBoost error applied to the thickness). Vernagtferner: 33% (17.1 m) instead of
  20% (10.3 m). Alps: 0.5 x error is 14 / 30 / 101% (5/50/95%), Aletsch 12.5%.
  The nb3/nb4 numbers above (wide priors, 20%) are now outdated: notebooks to rerun.
- 2026-11-16: area discretisation term (`area_k=0.25`, sigma = half a grid point)
  discussed: the textbook value for a rounding error is 1/12 (0.29 grid point), but
  then the second-nearest area step gets ~0.3% weight (one step only); 0.25 keeps the
  two steps around the observation within 2 sigma. Worth a test on small glaciers.
- 2026-11-16 (Fabien, from the nb3 demo plot): 30-yr spinup maybe too short, the area
  lags. Memory test (Vernagtferner, static MB params, A x10^0.37, offsets -2..+2 K):
  spread of the area 2004 between offsets 5.1 km2 (spinup 30 yr), 5.0 (50), 4.3 (70),
  2.4 (100); MB 2000-19 spread 1080 / 1080 / 950 / 620. A 50-yr initial state period
  doubles the spread of the starting volumes (1.1 vs 0.6 km3). The model does not
  forget the initial state within the available climate (from 1901): it is a real
  unknown. Possible later study (Fabien: keep 30 yr for now): spinup 30/50/100,
  initial state period 20/50.
- 2026-11-16 (Fabien): priors of the notebooks: melt_f and prcp_fac vary in log10
  (`log10_melt_f`, `log10_prcp_fac`, now the defaults of `DYNAMIC_PARAMS`; linear still
  possible; OGGM's bounds 1.5-17 and 0.1-10, prior medians ~5 and 1 instead of 9.2 and
  5.1), temp_bias informed +-10 K (the +-5 K posterior was close to the upper bound),
  initial state offset +-2 K (also the new default of `dynamic_prior`). The
  notebooks store their settings in the saved runs and refuse to load runs made with
  other settings.
- 2026-11-16 (Fabien): the area looked loose (plausible areas 8.04-9.00 km2, 5-95%,
  extremes ~1 km2 off), but OGGM's flowline area is crude. Keep 5%, framed in nb3 as
  observation + representation error (flowline glacier, grid point steps, 2 m
  threshold), larger than the outline error. Area error 2.5% vs 5%: later, with the
  thickness error options (the area 2004 is what constrains the initial state).
- 2026-11-16 (Fabien): not sure the initial state "can of worms" helps Chloe; likes
  the nb3 section on it. **To discuss with the supervision team.** Kept:
  `calibrate_params` (no rename), "posterior" in tables and legends.
- 2026-11-16: slurm scripts tested in the container on the login node (containall,
  read-only binds): two fixes. (1) `--containall` gives a small in-memory /tmp: pip's
  clone of OGGM fails -> `TMPDIR` in the scratch. (2) The download cache
  `/home/data/download/cluster.klima.uni-bremen.de/~oggm` is a symlink to
  `/home/www/oggm`: invisible in the container (and never to be bound), so jobs
  download into their scratch (`DOWNLOAD_CACHE` empty). Probably the same for the lmr
  jobs. Configs for this cluster in `.cluster_env/slurm/` (outputs straight to
  `example_workflows/out/`). First test job: 599804 (RGI60-11.00731).
- 2026-11-16: job 599804 failed in 8 s: no DNS in the container on node09 (pip could
  not reach GitHub). Not Claude's safeguards (no proxy env): `--no-mount bind-paths`
  drops /etc/resolv.conf on the compute nodes (diagnostic job 599805: containall alone,
  plain exec, or + `--bind /etc/resolv.conf:ro` resolve; + /etc/hosts does not help;
  the login node resolves anyway). Fix in run_slurm.sh. The lmr handover's
  isolation flags would have the same problem on the nodes.
- 2026-11-16: job 599806 (RGI60-11.00731, 0.43 km2, new priors, 32 cpus) ok in 5.5 min:
  10000 AdaPBS runs (151 s, max 20 iterations reached, Neff/Ne 0.24 < 0.3), 4841 hydro
  reruns (157 s). Fabien: keep max_iterations 20. `save_netcdf` (float32 + zlib like
  OGGM's compiled outputs, weights float64): hydro file 174 -> 41 MB, metrics unchanged
  (< 4e-7). Submitted 599807 (wide_priors: Vernagt, Hef, 11.00834) and 599808 (Vernagt
  without initial state period, no hydro).
- 2026-11-16: all four glaciers ok on the cluster (2-6 min each, 32 cpus); results in
  `claude/cluster_results.md`. nb3/nb4 rebuilt from these runs and their text rewritten
  (new settings: Vernagtferner 7 iterations, Neff 175; A unconstrained with and without
  the initial state period; volume 2020 0.05-0.49 km3; runoff 12.4 [8.9, 36.3] Mt/yr,
  prcp_fac 0.99 / S1 0.87). nb4 got the cumulative weight plot (Fabien: is the weight
  carried by few particles? here 150 largest = 75%, 99.9% = 646 runs; 99% would save a
  quarter) and a weighted-vs-resampled comparison (5 draws of 500: medians stable,
  95% quantile of runoff 30.6-36.3). The initial state offset leans cold on all four
  glaciers and reaches the -2 K bound.
- 2026-11-16 bug (not fixed, to ask): a vanished glacier gives status
  `ZeroDivisionError` (thickness = volume / 0), weight zero anyway.
- 2026-11-16 (Fabien): fixed: status `disappeared` (no glacier at state_year, zero
  weight); a glacier which disappears after state_year is a valid run ("could be the
  truth"). Test added.
- 2026-11-16, IceBoost v2.0 paper (Maffezzoli et al. 2026, Sci. Data) and its SI:
  per-glacier error = MC input-perturbation spread + XGBoost/CatBoost disagreement,
  summed with rho=1 ("upper bound"); larger over thick flat ice, smaller in steep
  terrain where confidence is lowest; product "tagged 2010-2018". Validation (SI S2):
  glacier-level held-out RMSE, Central Europe the only robust mid-latitude region
  (109 glaciers), models "consistent" there; the RMSE values are only in Fig. S1
  (vector, not readable here; v1.1 Table 2 is an image). Plausible runs thin 15%
  (large) to 25-30% (small) between 2004 and 2012. Decisions (Fabien): keep the RGI
  date (IceBoost has no real date; part of the uncertainty, said in nb3); error model
  undecided: Fabien to read Fig. S1 (region 11), meanwhile 0.5 x IceBoost error.
- 2026-11-16 (Fabien): prior bounds: prcp_fac 0.5-5 (log10; OGGM's 0.1-10 let runs
  with 0.17 through), initial state offset -3 to +2 K (all four glaciers pushed
  against -2 K). In run_glacier.py (`--prcp-fac-min/max`, `--offset-min/max`) and the
  nb3 builder. Cluster runs and notebooks not redone yet.
- 2026-11-16 (Fabien, after IceBoost SI Fig. S1: RGI 11 point RMSE ~35 m, like
  Farinotti, Millan ~46 m; not convertible to a per-glacier relative error without a
  project of its own): back to `volume_rel_err=0.2` as the default (pragmatic, same
  for all glaciers; 30% the next to try). `volume_rel_err=None` + `volume_err_factor`
  kept as an option (`--volume-err-factor` in run_glacier.py). 18 tests pass.
- 2026-11-16: second cluster round with all the new settings (jobs 599811, 599812),
  results in `claude/cluster_results.md`; nb3 and nb4 rebuilt from them and their text
  rewritten (Vernagt: 7 iterations, Neff 165, A unconstrained, offset leans cold but
  no longer cut, volume 2020 factor 3, runoff 16.5 [12.0, 31.7] Mt/yr, resampling
  stable). State: package, scripts, notebooks ready; not committed; step 7 (handover
  text for Chloe) left.
- 2026-11-16: committed on main as `4bb70d0` (Fabien), not pushed. nbstripout set up
  for this repo (`nbstripout --install`, repo-local .git/config; Fabien installed it in
  oggm_env): notebooks are committed without outputs. Left: step 7 (handover text for
  Chloe), E4 convergence (seeds x particles; final Neff ~ 0.3 x n_particles by
  construction) as a first experiment for Chloe.

## Next notebooks

- Done: notebook 2, the underconstrained problem (geodetic MB only).
- Other candidates (Claude-suggested, 2026-11-11, not decided):
  - From the posterior to projections: run a dynamical projection with the resampled
    particles (`posterior_theta`) and show the spread of future volume / runoff, against
    the deterministic run. The natural sequel of notebook 1.
  - Dynamic calibration (Chloe's case, Aletsch-like): AdaPBS with full transient runs
    against geodetic MB, area and volume; parallel particles, failed runs, extras with
    time series. Heavier (minutes on several cores).
  - Is it converged? Seeds, particle numbers, Neff threshold, comparison with a
    brute-force reference (as in E1).
