Skip to content

Tutorials

End-to-end, runnable walkthroughs of vardax on the Lorenz-63 and Lorenz-96 testbeds. Notebooks 01–08 cover state estimation with 4DVar and 4DVarNet; 09–11 port the parameter-estimation, bilevel-optimisation and gradient-learning chapters of the legacy mfourdvar book; 12–17 cover model error, closures, uncertainty, observation operators, cycling and amortized inference. Each page is a jupytext percent-format .py source under docs/notebooks/, executed when the documentation is built, so the outputs you see here are produced by the released code.

# Notebook What it shows
01 Model-based 4DVar on L63 Classical strong-constraint 4DVar (StrongFourDVar) with the Lorenz-63 ODE as forward model: background vs analysis
02 Unrolling vs fixed-point on L63 The unrolled learned solver vs the prior-only fixed-point solver, plus warm-start initialisation
03 4DVarNet end-to-end on L63 Training FourDVarNet1D with the demo training loop
04 4DVarNet 2-D demo FourDVarNet2D on synthetic spatiotemporal fields
05 End-to-end L63 pipeline Simulation, patching, masking, standardisation, training
06 End-to-end L96 pipeline The same pipeline on Lorenz-96
07 Prior pre-training on L63 Two-stage training: pre-train the prior, then fine-tune
08 Classical 4DVar vs 4DVarNet Gradient descent on the variational cost vs the learned solver
09 Parameter estimation on L63 Learning ODE parameters (and the initial state) with DynTrajectory and strong_variational_cost
10 Bilevel optimisation on L63 Learning the cost weights by differentiating through the inner 4DVar solve
11 Learning the gradient update Training only the ConvLSTMGradMod1D against vanilla gradient descent, with a solver-steps ablation
12 Weak-constraint 4DVar on L63 WeakFourDVar with a biased model: model-error increments, the \(Q\) dial, and the same cost in trajectory space via DynIncrements.bind
13 Neural closures on two-level L96 Learning the unresolved coupling offline (regression) and online (through the ODE solve), forecast skill, and the hybrid model inside 4DVar
14 Posterior uncertainty on L63 LaplaceCovariance, GaussNewtonHessian and EnsembleCovariance for a 4DVar analysis, uncertainty along the window, calibration and SBC
15 Observation operators Masks vs selection matrices, InterpObs off-grid data, the AveragingKernel bias, and MultiInstrumentFusion on a Gaussian random field
16 Cycled assimilation on L63 pipekit_cycle forecast–analysis loops: spin-up, the error equilibrium, tuning \(B\) by innovations, and windowed 4DVar cycling
17 Amortized posterior on L63 Simulation-based training of AmortizedPosterior, a multi-start 4DVar oracle, and the three validation gates

Running locally

uv sync --all-extras --group docs
uv run jupytext --to notebook docs/notebooks/01_model_based_4dvar_L63.py
uv run jupyter lab docs/notebooks/01_model_based_4dvar_L63.ipynb

Committed .ipynb files are not allowed in this repository (a pre-commit hook rejects them); edit the .py source and let jupytext --sync keep a local .ipynb in step.

See also