Design Decisions

Back to Codebase Guide

A design decision is a rule that is not obvious from the code: breaking one gives results that are wrong but look correct. Each area has one page, and each rule names where it lives and the test that guards it. Before you change an area, read its page only.

Area	Decisions
Model kinds	One interface for every model kind, A model is a header, a process, a structure and an engine, Neutral terms carry a process across structures
Model structure	Compartments are labels with a name, State, amount, total and subgroup total, The initial state is an amount per bin, Stratification order is part of the model, Outputs are resolved by label, The engine owns the variable names
Transitions and rates	Absolute and proportional rates, The most specific stratified rate wins, Formula parameters are evaluated every step, in order, Compiled expressions are cached globally
Initial conditions	Category fractions compose down the condition chain, A compartment amount overrides the expansion, Calibrated initial conditions are applied in layers, The remainder keeps the sum the model declares
Time	Physical units are not in the model, An origin puts the axis on the calendar, One step unit in the unit check, Time inside a step, Impulses come before the flows of their step, Windowed observations, The engine owns positions, Results carry their positions
Engines	One list of engines, Every engine reads one set of flows, A difference step never leaves an amount below zero, Stochastic engines and seeds, Whole units in a stochastic engine, The solver is diffsol
Calibration	One meaning of an observation weight, A problem has a loss or observation models, A Simulation follows its model, The engine says which parameters a caller sets, One observation operator, Constraints bound the support, A subproblem holds one quantity fixed, A result records its seed, Parallel work runs in the pool of the setting
Optimizers	Nelder-Mead searches inside the bounds, A swarm scores in parallel and keeps the order of its particles, A swarm stops by a rule the modeller sets, One function runs the starts and chooses the best, A swarm takes its seed from its caller
Uncertainty	A sample carries its weights, Methods plug into one entry point, Methods raise one error type, A replicate changes only the data, One SMC core, many targets, Observation noise is an argument, Conformal variants share one score and one quantile, Scenarios pair the draws of one sample
Identifiability	Sensitivities come from one port, Two verdicts per parameter
Sensitivity analysis	An analysis needs no data, A quantity is a series and a reduction, NaN propagates in a run and stops a reduction across runs, The quantities of one run take the path of a propagation, A ratio combines its replicates as the user chooses, The modeller truncates a polynomial chaos basis
Local approximations	The curvature lives on the unbounded scale, Gauss–Newton by default, the Hessian on request, Scores and information live in commol-calibration, The sandwich sums scores over blocks, The Laplace approximation needs observation models, PSIS lives in commol-inference
Profiles	A profile steps with the adaptive step of Raue, A threshold states the noise, A verdict needs a threshold above the tolerance, A flat profile is read by resetting the others
Results	One confidence-interval convention, A setting has one name and one check, A method takes its seed from its source and fits from its starts, Fits that fail have one place, A description is data, rendered apart, Reports, Model files are written in full
Python models	Public models forbid unknown fields, A value of a model has its rule in the engine, Results compare by their values
Figures	Figures are read from their results
Security	Every user expression is validated, The engine defines the language of formulas, The engine parses formulas with a parser of its own

Navigation

Previous: Repository map | Next: Conventions