camdl

Compartmental Model Description Language

camdl is a language and toolkit for stochastic compartmental models of epidemics. You write a .camdl file that says what the compartments are (for example susceptible, infected and recovered), how individuals move between them and how fast. The compiler checks the file and expands it into a flat model description, which camdl then simulates and fits to data.

Most guides and reference pages here are the same text the binary carries: camdl docs <topic> prints them offline, matched to the installed version. The tutorials are website-only, because they show the real output of each command, regenerated from the current code every time the site is built.

About these docs. Much of this documentation was drafted with an AI model and is being revised by hand. In the tutorials, every command was run when the site was built, and the output shown is what camdl printed. The guides, concepts and reference pages are prose checked against the code, and can be wrong. If something is unclear, contradicts what camdl does, or looks wrong, please open an issue.

How camdl runs a model The modeler writes the model. The compiler checks its units, dimensions and names and expands its strata into a flat intermediate representation (IR), from which the runtime performs simulation and inference. The modeler is responsible for the model structure, a scientific hypothesis, for the priors and their sources, and for choosing the right model for the question at hand: all science, no implementation. camdl is responsible for compiling the model correctly to the IR, faithful simulation of the declared model, correct inference, and an efficient runtime: all implementation, no science. MODELER CAMDL Model model.camdl compartments transitions observations priors Compiler camdlc checks units, dimensions, names expands strata Runtime simulation inference IR Responsible for •model structure, a scientific hypothesis •priors and their sources •the right model for the question at hand All science, no implementation. Responsible for •compiling the model correctly to the intermediate representation (IR) •faithful simulation of the declared model •correct inference •an efficient runtime All implementation, no science.
How camdl splits responsibility between the modeler and camdl’s developers. The modeler states the model’s structure and prior assumptions, and writes no simulation or inference code; camdl’s job is to execute the declared model exactly. A trajectory that contradicts the declared model is therefore a bug in camdl, not in the modeler’s work, and implementation risk moves from many privately maintained code bases to one shared, tested one.

camdl by exampleThe language, one construct at a time. Fitting the boarding-school outbreakFourteen days of influenza counts, fitted and read. The fit workflowFrom a model and data to a checked posterior. Language specificationThe normative reference for the DSL. Dimensions and stratificationAge, place and disease stage, expanded by the compiler. Diagnosing a fitWhat to do when a fit will not behave. CheatsheetEvery DSL form on one page.