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 layer at a time on synthetic data with a known answer: 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. Everything uses the package’s Python API, so it also serves as a guide to using wdm as a library. The theory behind each layer is in The model, Estimation and Control.
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 (folded), the output it printed on 2026-11-18, what to notice in it, the modules and functions it uses (under
wdm, documented in the API reference), and a “Try this” exercise. - Seeds are fixed, 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 values
wdm demoand the tests use). Each script rebuilds the episode from the same seed, so each runs on its own.
The steps
| Step | What it shows | Script | CLI equivalent | Runtime |
|---|---|---|---|---|
| 1. The model | A diet simulated at the prior: the early drop in water and gut content, slower tissue loss, adaptation | 01_model.py |
none | 1.6 s |
| 2. Synthetic data | Weigh-ins with noise, food logs, weekly waist readings, and the hidden truth | 02_synthetic.py |
wdm demo |
1.2 s |
| 3. Phase 1: the scale’s noise | Reading noise, steady-state gain and effective window, against the true noise | 03_phase1.py |
wdm fit-noise |
5.7 s |
| 4. Phase 2: state and metabolism | The joint fit: parameter recovery against the truth, what “shift” means, maintenance | 04_phase2.py |
wdm filter |
5.6 s |
| 5. The waist tape | The same fit with and without waist readings: the fat-mass interval and bias | 05_waist.py |
wdm filter |
7.6 s |
| 6. The backtest | 1- and 7-day forecasts against persistence, and their calibration | 06_backtest.py |
wdm backtest |
7.2 s |
| 7. Planning | Deadline and sustainable plans, the constraint check, an impossible deadline | 07_plan.py |
wdm plan |
14 s |
| 8. Maintain | Holding today’s tissue and a weight 3 lb below: intake near maintenance, a gentle correction | 08_maintain.py |
wdm plan --mode maintain |
8.5 s |
Runtimes are wall-clock on a 20-thread desktop CPU, including Python and JAX start-up.