$$ % Define your custom commands here \newcommand{\bmat}[1]{\begin{bmatrix}#1\end{bmatrix}} \newcommand{\E}{\mathbb{E}} \newcommand{\P}{\mathbb{P}} \newcommand{\S}{\mathbb{S}} \newcommand{\R}{\mathbb{R}} \newcommand{\S}{\mathbb{S}} \newcommand{\norm}[2]{\|{#1}\|_{{}_{#2}}} \newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}} \newcommand{\pdd}[2]{\frac{\partial^2 #1}{\partial #2^2}} \newcommand{\vectornorm}[1]{\left|\left|#1\right|\right|} \newcommand{\abs}[1]{\left|{#1}\right|} \newcommand{\mbf}[1]{\mathbf{#1}} \newcommand{\mc}[1]{\mathcal{#1}} \newcommand{\bm}[1]{\boldsymbol{#1}} \newcommand{\nicefrac}[2]{{}^{#1}\!/_{\!#2}} \newcommand{\argmin}{\operatorname*{arg\,min}} \newcommand{\argmax}{\operatorname*{arg\,max}} \newcommand{\dd}{\operatorname{d}\!} $$

Walkthrough

Eight short scripts that take the package apart one layer at a time, on synthetic data with a known answer.

This section runs wdm one piece at a time: the model alone, a synthetic record with a hidden truth, the two estimation phases, the tape measure, the backtest, and the controller, first losing and then holding. At every step you run a short script, compare its output with the one shown, read the code it points at, and try a change. Everything here uses the package’s Python API, so it also serves as a guide to using wdm as a library.

How to use it. From weight-dynamics/code, after Getting started:

cd weight-dynamics/code && uv run python walkthrough/01_model.py

• Each page gives the command, the script itself (folded), the output it printed when the page was written (2026-10-28), what to notice in that output, where the code lives (file.py:line, under src/wdm/), the assumptions made at that layer, and a “Try this” exercise.
• All data are synthetic, with fixed seeds, so your numbers should match to the digits shown. Another JAX or SciPy version can change the last digits of the optimizer-driven results (steps 3 to 8).
• Steps 2 to 8 share one subject and one episode: a 40-year-old man, 175 cm, starting at 100 kg and 30 % body fat, eating about 80 % of his maintenance for 120 days, with a metabolism set deliberately away from the prior (the same values wdm demo and the tests use). Each script rebuilds that episode from the same seed, so each runs on its own.
• Everything runs on the CPU. Most of each step’s time is generating the synthetic episode, which steps one day at a time in Python.

The steps

Step	What it shows	Script	Runtime
1. The model	A diet simulated at the prior: the early water drop, slower tissue loss, adaptation	01_model.py	1.6 s
2. Synthetic data	Weigh-ins with noise, food logs, weekly waist readings, and the hidden truth	02_synthetic.py	15 s
3. Phase 1: the scale’s noise	Reading noise, steady-state gain and effective window, against the true noise	03_phase1.py	31 s
4. Phase 2: state and metabolism	The joint fit: parameter recovery against the truth, what “shift” means, maintenance	04_phase2.py	20 s
5. The waist tape	The same fit with and without waist readings: the fat-mass interval and bias	05_waist.py	22 s
6. The backtest	1- and 7-day forecasts against persistence, and their calibration	06_backtest.py	21 s
7. Planning	Deadline and sustainable plans, the constraint check, an impossible deadline	07_plan.py	27 s
8. Maintain	Holding today’s tissue and a weight 3 lb below: intake near maintenance, a gentle correction	08_maintain.py	25 s

Runtimes are wall-clock on a 20-thread desktop CPU, including Python and JAX start-up.

The steps in the pipeline

flowchart LR
  M("model<br/>step 1")
  D["synthetic episode:<br/>weigh-ins, food, waist<br/>step 2"]
  P1("phase 1<br/>noise of the scale<br/>step 3")
  P2("phase 2<br/>state + metabolism<br/>steps 4, 5")
  BT("backtest<br/>step 6")
  PL("controller<br/>steps 7, 8")
  D --> P1
  P1 -->|"reading noise"| P2
  D --> P2
  P2 --> BT
  P2 -->|"state, parameters"| PL
  M -.-> D
  M -.-> P2
  M -.-> PL

Where each step sits in the pipeline. Rounded boxes are what wdm computes; the model (step 1) is used by the generator, the filter and the controller alike.

The command-line tool runs the same chain: wdm fit-noise is step 3, wdm filter steps 4 and 5, wdm backtest step 6, and wdm plan steps 7 and 8 (--mode maintain). The theory behind each layer is in The model, Estimation and Control.