Skip to main content
$$ % 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}\!} $$

wdm documentation

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.

Where to start

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.