$$ % 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. You weigh in each morning, log what you eat as you go, and once a day it re-estimates where you are and replans what to eat next. The presentation tells the story in slides; these pages are the manual.

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 model has five states: tissue, fat mass, glycogen-bound water, sodium-bound water, and adaptive thermogenesis. Its nine metabolic parameters are personal and unknown.
• Phase 1 learns how noisy your scale readings are, from weight alone.
• Phase 2 estimates the states and the parameters together, from weight, food, and an optional weekly waist measurement.
• The controller plans the next weeks of intake to reach a goal weight by a date (deadline mode) or to lose at a safe steady rate (sustainable mode). Tissue, not scale weight, sits in its objective and safety limits. Only today’s line is a prescription; tomorrow it replans.

Where to start

• Use it: Getting started installs it and sets up your files; The daily routine is the whole day-to-day obligation (two commands).
• 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.
• Lifting: Exercise energy estimates exercise_kcal from a routine or a workout spreadsheet.
• Learn the code: the walkthrough runs the package one layer at a time on synthetic data with known truth.
• Understand the method: the model, estimation, control, their limitations, and the notation.
• Use it from Python: the API reference, generated from the docstrings; Development covers the layout, the tests, and rebuilding the report and these pages.

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 you. Talk to a doctor or a registered dietitian before acting on an aggressive plan.