Weight-dynamics modeling: an energy-balance state-space model of body weight, a joint Kalman filter that learns one person’s metabolism from a scale and a food log, and a model-predictive controller that turns the estimate into a daily calorie and macronutrient prescription.
wdm is a Python package (JAX, Equinox, Diffrax) with a command-line tool of the same name. The subject weighs in each morning and logs food as the day goes; once a day wdm re-estimates the state and replans what to eat next. The presentation tells the story in slides; these pages are the manual.
NoteThe code is private
The package lives in a private repository. These pages document it in full, and the API reference is generated from its docstrings, but installing it and running the walkthrough’s scripts require access to that repository.
How the pieces fit
flowchart LR
O["observations.csv"] --> V("validate")
V --> P1("phase 1<br/>scale noise")
P1 --> P2("phase 2<br/>state and metabolism")
C["subject.toml"] --> P2
P2 --> M("controller")
C --> M
M --> T["today's prescription<br/>plans/log.csv"]
One day of use. Square boxes are files; rounded boxes are what wdm computes. wdm daily records the weigh-in and runs the chain from validation to the plans log; wdm log adds meals and shows what is left of today’s prescription.
The pieces summarizes the model, the two estimation phases, and the controller.
Look something up:Commands lists every command and option; The observations file and The subject file define every column and setting; Reading the output explains each number the tool prints, what to expect when, and what to do when something looks wrong.
Learn the code: the walkthrough runs the package one layer at a time on synthetic data with known truth.
Use it from Python: the API reference; Development covers the layout, the tests, and regenerating the figures and numbers.
WarningNot medical advice
This is a modeling exercise built on population-level physiology and fitted to one person’s self-reported data. Its estimates come with honest, often wide, intervals, and its safety limits are general guidance, not anything specific to any one person. Talk to a doctor or a registered dietitian before acting on an aggressive plan.