Repository Map

Back to Codebase Guide

Use this page when you know what to change but not where it belongs.

Rust crates

Path	Owns	Do not put here
crates/commol-core/src/types/	The model data types shared by all crates and serialized from Python: Model (header, engine, process, structure), Process (process.rs: bins, accumulators, stratifications, transitions; the names NEIGHBORS and NEIGHBORS_PREFIX), ModelStructure (one variant per kind, tagged by kind), Aggregate (aggregate.rs: InitialConditions, Neighbors and their checks, AggregateVariant), Transition (transitions.rs), …; types/test_kind.rs only with the test-kind feature.	Engine behavior.
crates/commol-core/src/types/engine.rs	EngineType, the one list of engines (model types): per entry, the model kinds it runs (kinds, engines_of; ModelKind, with the value types it accepts, ModelValueType), the form of its dynamics (DynamicsForm: its schedule and the left-hand side of its equations), its settings and their validation, the meaning of a rate, and the positions it reports at (reports_at_integer_steps, check_position, the one rule every engine and the builder read). ModelEngine, the engine and settings of a model.	The engines themselves.
crates/commol-core/src/position.rs	When two positions on the axis are one (same_position, POSITION_TOLERANCE), for every crate.	A tolerance of positions of its own.
crates/commol-core/src/parallelism.rs	Parallelism (a number of threads and the Levels that run in parallel), the rayon pool of each setting (install), and inner_levels_in_parallel, which a nested level reads.	A pool of its own elsewhere; the global pool of rayon.
crates/commol-core/src/math_expression/	The language of formulas (language.rs: FUNCTIONS and the check of a formula, MathExpression::check), the engine variables (variables.rs); the parser of formulas and its nesting limit (jit/parser.rs: MAX_NESTING), the tree of a formula (jit/ast.rs), the Cranelift JIT and its global cache (jit/).	Model-specific variables.
crates/commol-core/src/simulation_engine.rs	The SimulationEngine trait, for an engine of any kind: runs at positions (check_position), outputs (output_names, state_outputs, output_sums), parameters, reset, the seed of a stochastic engine (set_seed), the entry of the list of engines it runs and whether it draws random numbers (engine_type, is_stochastic), and the values of its kind (plan_values, apply_values, ValuePlan); Trajectory, check_positions, run_replicates (one run per seed, in parallel); the rules NUM_STEPS, REPLICATE_COUNT and SEED (a whole number from 0 to 2^64 - 1, the one rule of every seed). What calibration needs from any engine.	Code for one engine or one kind.
crates/commol-core/src/range.rs	The range rules of the settings, as data: Count (a whole number, at least a minimum or in an interval, read from a signed number with one message for every value outside), Real with its two Bounds (open or closed; NaN is always outside), Rule, the rules of one object of the Python API (Ranges, whose check reads each setting as a Setting of its own type: a whole number, a number, a list or not a number) and check_object, which finds the object in the tables of the crates; CONFIDENCE_LEVEL, the one rule of a confidence level, which each caller checks at its boundary, and the table of the replicates of a simulation and of the axis patterns (RANGES).	A rule of a setting written as a check of its own; a message of a range elsewhere.
crates/commol-random/	What every stochastic engine and inference method shares and no model: the generator (Generator, Xoshiro256PlusPlus seeded by SplitMix64, with its uniforms and the generator trait of rand_core, which the particle swarm draws with), replicate_seed, seed_or_drawn (the one place a seed that its caller does not set is drawn), Stream (streams.rs), the one registry of the seed streams of every method that draws from a seed, the starts of a calibration and the inference methods: each stream with its own number, its method and its purpose (Stream::ALL), and the one scheme of a draw, seed, then Stream::seed, then Stream::replicate for each draw or replicate, the samplers (sample: exponential, Poisson, binomial, multinomial, normal, gamma, an index below n), SumTree, the rates of a set of events, which the stochastic engine of the test kind uses (StochasticEvents scans its propensities), and latin_hypercube on the unit cube.	Anything of a model or an engine; a sampler in another crate; a stream number written in a method.
crates/commol-statistics/src/statistics.rs	The one quantile (weighted, midpoints of the cumulative weights; Hazen with equal weights), used by the summary of the replicates of a calibration and by every interval, sample and band of commol-inference and by the bindings, which import it from this crate; weighted mean and covariance, the weighted summary of a column (summary: mean, median, central interval, minimum and maximum, the reduction of every band and of every summary of runs), Kish's effective size; the two quantiles of a central interval (interval_levels, a pure function: the caller checks the level with commol_core::CONFIDENCE_LEVEL) and the check of quantile levels (check_levels). It depends on no crate of commol.	Quantiles or summaries anywhere else.
crates/commol-statistics/src/numeric.rs	The numerical helpers that the calibration and the inference methods share, one copy of each: log_sum_exp, x_log_y, x_log1p_y, ln_gamma, ln_beta, digamma, trigamma, and the log densities of the normal, the log-normal and the Student t in one or several dimensions.	A second copy of a helper or a density; anything of a model.
crates/commol-model/src/builder.rs	Expansion of the bins and accumulators of a process over its stratifications (expand, expand_compartments, expand_accumulators), the initial state (initial_state), the checks of an aggregate model (check_model: variant, neighbors, names, whole units for a stochastic engine; as_whole), the subgroup total names (subgroup_total_names), impulse schedules and the compilation into CompiledModel (try_from_model).	Flow planning; stepping.
crates/commol-model/src/layout.rs	CompartmentLayout: compartments in engine order with their labels, and lookups by bin and categories.	Name parsing.
crates/commol-model/src/labels.rs	OutputLabels (bin and categories of an output) and output_sums (bin totals and partial totals).	Name parsing.
crates/commol-model/src/engine.rs	CompartmentalEngine: what a compartmental engine gives besides SimulationEngine: its compiled model (model, model_mut), and from it by default compartments, output_labels, initial_state and total; set_initial_condition. What the four engines share: delegate_to_compiled_model! (the methods of SimulationEngine that read the compiled model), IntegerStepper and record_steps (the run of an engine that reports only at integer steps), rounded (the numbers of a message).	Code for one engine.
crates/commol-model/src/initial_conditions.rs	How initial-condition values reach a compartmental engine (InitialConditionPlan: resolution, layers, remainder); the plan_values and apply_values of every engine of the aggregate kind use it.	Parameter values.
crates/commol-model/src/flows.rs	Transition flow planning (plan_transition_flows), the sums the neighbors of a unit are (resolve_neighbors), and the description of the flows for Python (describe_flows).	Rate evaluation at run time.
crates/commol-model/src/helpers.rs	Stratified-rate resolution and rate rewriting helpers.	New public API.
crates/commol-model/src/rates.rs	Evaluation of a compiled rate: fast path or JIT with resolved slots; an error names the transition.	Flow logic.
crates/commol-model/src/rules.rs	The rule of each value of a model, declared once: an initial amount (check_bin_amount, check_compartment_amount), the fractions of a stratification (check_fractions), an impulse (check_impulse) and the points of a series (check_series). The compiler and the Python object of the value call them.	A check of a value written in the compiler or in Python.
crates/commol-model/src/system.rs	The flows every engine reads: flow_rates (the value of each flow), transition_rates (its rate), flow_changes (the change of one event of each flow), the right-hand side derivatives built on them; impulses (apply_impulses, impulse_rates, impulse_changes, impulse_positions); the positions where a rate can jump (breakpoints, reads_time); the parameters a caller sets (set_parameter, check_parameter: a constant or a parameter to calibrate); the accessors the engines use.	Stepping along the axis.
crates/commol-model/src/types.rs	CompiledModel, compiled flows, FlowChange (one event of a flow), impulse schedules, series lookup (SeriesParameter).	Python types.
crates/commol-difference/src/simulation.rs	DifferenceEquations: the discrete step (state += derivatives), impulses at integer steps, and its IntegerStepper, SimulationEngine and CompartmentalEngine implementations.	Model compilation.
crates/commol-differential/src/lib.rs	DifferentialEquations: state, output positions, impulses, and its SimulationEngine and CompartmentalEngine implementations.	Numerical methods.
crates/commol-differential/src/solve.rs	The integration with diffsol: pieces between the breakpoints of the model, the finite-difference J·v, dense or sparse matrices (SPARSE_THRESHOLD).	Model compilation.
crates/commol-stochastic/src/events.rs	StochasticEvents: whole units one event at a time (the direct method, with a time change when a rate reads t) or in leaps (tau-leaping, fixed or chosen as Cao, Gillespie and Petzold 2006 do), stopping at the breakpoints; its SimulationEngine and CompartmentalEngine implementations.	Samplers; flows.
crates/commol-stochastic/src/steps.rs	StochasticSteps: the chain binomial (one multinomial per source, capped Poisson draws for absolute flows), the check of its per-step probabilities, and its IntegerStepper, SimulationEngine and CompartmentalEngine implementations.	Samplers; flows.
crates/commol-stochastic/src/units.rs	What both stochastic engines share: the generator, the whole start of a run (largest_remainder, random_rounding) and impulses that move whole units.	Anything of one engine.
crates/commol-calibration/src/calibration_problem.rs	CalibrationProblem: the layers below, built once (new, which refuses observation models with a stochastic engine; with_replicates; with_replicate_settings, the replicates, seed and summary a stochastic engine needs, with the message that names a missing one; with_observation_normalization, with_initial_condition_remainder), a copy with other observed values and weights (with_data), a copy whose runs also report at the positions of other observations (observing), the one evaluation of a point (evaluate), the predictions of one seeded run (predict_once), and the position check that names an observation or constraint (check_positions). It uses only SimulationEngine.	Penalties; optimizer setup; anything of one model kind.
crates/commol-calibration/src/forward.rs	ForwardModel: every clone, reset, write of values and run of the engine (run_schedule, run_observed, run_at), one run per replicate of a stochastic engine, or one run seeded by its caller (run_once); the same model on other observations (with_observations, which checks their positions), or with none (unobserved, which asks a stochastic engine for replicates and a seed); Workspace; the one schedule of a set of observations (schedule_of: each position and window start, sorted, once) and the one mean over replicates (replicate_mean).	Loss, penalties, history; a second schedule or mean over replicates.
crates/commol-calibration/src/series.rs	SeriesIndex: the one index of the series of a set of observations (or of labels): the labels in order of first appearance, and the entries of each in position order. Every method that reads the observations series by series uses it.	A second grouping of observations by label.
crates/commol-calibration/src/observation.rs	ObservationOperator: one prediction per observation from the rows of a run (rows, sums of outputs, windows, factors); index_at, the row of a position within the tolerance of the axis; the arithmetic of every window: window_start and check_window_end, the window of an observation; window_increments, which windowed_totals also reads; the grid of windows that results, figures and reports read (window_bounds, window_index, window_ends, windows_in).	Comparison with data.
crates/commol-calibration/src/feasibility.rs	Feasibility (bounds, constraints), Violation and EvaluationError.	Penalties.
crates/commol-calibration/src/discrepancy.rs	Discrepancy and DiscrepancyConfig: the loss, or the negative log-likelihood of observation models, of predictions against the data, with weights, per-series normalization of a loss and the summary of the replicates; the discrepancy of one run (of_run); the base of the penalty (penalty_base).	Running engines.
crates/commol-calibration/src/likelihood/	The observation models: ObservationModel and Argument (likelihood/mod.rs), Likelihood (the model and trials of each observation, the checks of models, noise parameters and observed values, the pointwise log-likelihood), Noise (density.rs: a model with numbers for its noise, its log density, the means it allows, its scores and Fisher information), TermDerivatives (the gradient and the expected curvature of each observation's term, also of a loss through Discrepancy::term_derivatives).	Draws; running engines.
crates/commol-calibration/src/objective.rs	OptimizationObjective: the argmin cost function, the only place that turns a violation into a penalty; score_all, the points of a swarm in parallel and in order; the history decorator (Recorded).	Recording history inside the objective.
crates/commol-calibration/src/starts.rs	The starts of a multi-start optimization (start_points: the guess, then a Latin hypercube) and optimize_starts, the one function that runs them in parallel and chooses the best (Starts), for a calibration and every fit of a replicate.	Statistics.
crates/commol-calibration/src/ranges.rs	The range rule of each setting of a calibration (observations, constraints, observation models, optimizers, the problem) and the table RANGES of their objects of the Python API. The functions and constructors that take a setting check it with its rule (ObservedDataPoint::check_ranges, NelderMeadConfig::check_ranges, …).	A check of a range written in a function.
crates/commol-calibration/src/types.rs	LossConfig (every loss, and replicate_loss), ReplicateSummary (its median and quantile by statistics::quantiles), crps and weighted_crps, Replicates, the observation, parameter, constraint and result types.	Optimizer setup.
crates/commol-calibration/src/values.rs	How calibrated values reach any engine: parameters by id, which the engine checks when a problem is built (set_parameter on a copy), values of the model kind through the engine (ValueWriter, check_model_values, configured_engine); a factor has positive bounds (ValueWriter::new).	How a kind resolves its values; a check of parameter ids in Python.
crates/commol-calibration/src/optimization.rs	Nelder-Mead and particle swarm setup on the argmin fork, from a start point and the seed of a swarm (optimize, optimize_from, optimize_with_history), and on a subproblem (optimize_subproblem: a smaller search space, or the augmented Lagrangian of the fork around the problem's optimizer); no output to the process streams.	Loss definitions; numerical methods that know no model, such as the sine transform of the bounds or the handling of a NaN cost by the swarm (the argmin fork).
crates/commol-calibration/src/subproblem.rs	Subproblem: the problem with one parameter held (left out of the search) or one prediction held (an equality constraint, ConstraintSettings); predict, the value of a prediction; SubproblemResult.	Stepping along a profile; thresholds.
crates/commol-inference/src/ranges.rs	The range rule of each setting of the inference methods, the distributions and the quantities of interest, and the table RANGES of their objects of the Python API; the method that takes a setting checks it with its rule.	A check of a range written in a method.
crates/commol-inference/src/error.rs	MethodError, the one error of every method, and its ErrorKind (Invalid or Failed), which sets the Python exception.	An error type of one method.
crates/commol-inference/src/sample.rs	ParameterSample: weighted draws, their invariants and statistics, resampling.	What a method does.
crates/commol-inference/src/predictive.rs	Predictive (the run of every draw, its bands), observation_draws through ForwardModel::with_observations, the ObservationNoise port (one draw's whole vector), NoNoise, and DistributionNoise with the draw of each observation model; Band, the one layout of a band ([position][output], also of the delta method) and its one reducer (Band::of, on statistics::summary); share_among_replicates, the one share of the weight of a draw among its replicates.	Noise models of one method; a second band reducer or layout.
crates/commol-inference/src/resampling/	Fits to reweighted or resampled data: blocks.rs (BlockScheme, the automatic block length, and the one resolution of a block length, given or automatic, with its estimates: BlockScheme::resolve, BlockScheme::at_fit, which the sandwich, the bootstraps, the jackknife, the calibration of η and the conformal methods call), residuals.rs (Residuals on a scale, residuals by series and position), resamplers.rs (the Resampler port, Perturbation, the Bayesian, residual and wild bootstraps, ParametricResampler), runner.rs (ReplicateRunner and its one loop fit_all, ReplicateFits, FitUnit, bootstrap), jackknife.rs (block_jackknife), noise.rs (ResidualNoise).	Changes to the problem other than through with_data.
crates/commol-inference/src/conformal/	Conformal prediction intervals: score.rs (NonconformityScore, Pooling, ConformalSettings, the scale of a score), quantile.rs (the conformal quantile, the order statistics of jackknife+), intervals.rs (PredictionIntervals, ConformalRun), predict.rs (predictions and spread at any observations, the target points), and one file per variant: split.rs, rolling.rs, jackknife_plus.rs (with cv_plus_bound), enbpi.rs, adaptive.rs (AdaptiveLevel).	A second quantile or score of one variant.
crates/commol-inference/src/scores.rs	Coverage, interval score, weighted interval score, sample CRPS, PIT, the log score of observation models, and their means per series.	—
crates/commol-inference/src/sensitivity/	SensitivitySource, the port of derivatives of the predicted observations; FiniteDifferences on the design of the observations or a dense one; the scaled sensitivities and observation_scales.	Ranks, verdicts.
crates/commol-inference/src/design.rs, crates/commol-inference/src/quantity.rs, batch.rs	What a design-based method shares: InputSpace (independent distributions or a sample) and its designs (Latin hypercube, Morris trajectories, the Saltelli matrices, the scale F(x)); Series, Quantity (a series and its reduction, read from JSON) and Quantities, read through the observation operator, with the schedule of a list of quantities and the quantities of a run that is done (evaluate_run); BatchRunner, every point through a forward model in parallel, replicate by replicate or as their mean, which rejects a quantity that is NaN.	Estimators.
crates/commol-inference/src/global_sensitivity/	analysis.rs (ForwardAnalysis: the forward model, the inputs and the seed streams, and each method in one call; with no seed it draws one, which a stochastic engine refuses), and the estimators: prcc.rs (weighted PRCC and its test), morris.rs, sobol.rs (with the bootstrap of rows), chaos.rs (ChaosExpansion, a surrogate, and Truncation, the terms its basis keeps).	Designs; code of one engine.
crates/commol-inference/src/identifiability/	The analyses: structural_rank (ranks, null space, combinations), collinearity (Brun's indices), sample_identifiability (contraction, correlations, modes), starts_identifiability.	Derivatives; reports.
crates/commol-inference/src/profiles/	Profile likelihood: tracer.rs (ProfileTracer, the adaptive step and the secant start, Profile and its interval), threshold.rs (chi_square, beale, bootstrap_thresholds), verdict.rs (ProfileVerdict), resets.rs (read_structure: the resets of a flat profile, StructuralReading).	Holding a quantity (a Subproblem's); optimizers.
crates/commol-inference/src/target.rs	Target (a log density, −∞ outside the support) and discrepancy_in_support.	Penalties.
crates/commol-inference/src/distribution.rs, special.rs	Family and Distribution, one family truncated to the bounds of a parameter (density, distribution function, quantile, closed-form moments, draws by inversion); the normal distribution function and its inverse, the regularized incomplete gamma and beta functions and the quantiles of the Student t and the F (special.rs, on libm). The quantile sets the bracket of the root and takes the root finder from the argmin fork (NewtonRoot).	Distributions from a dependency, whose draws change with it; a root finder of its own.
crates/commol-inference/src/priors.rs	Priors: one distribution per parameter, the check of their bounds, the joint density and draws.	Defaults of a prior.
crates/commol-inference/src/transform.rs	Transform: the unbounded scale a move proposes on (logit, log or identity by the bounds) and its log Jacobian; on_bound and ON_BOUND, the one rule of a value on a bound, which the curvature, the Laplace mixture and the profiles read.	Kernels; a second rule of a bound.
crates/commol-inference/src/local/	Local approximations at a fit: Curvature (Gauss–Newton or the stepped Hessian of the finitediff crate of the argmin fork, on the unbounded scale, with the term gradients), CurvatureKind and laplace_approximation (approximation.rs), Gaussian and laplace (gaussian.rs), delta_band (band.rs), sandwich, block_meat and sandwich_approximation (sandwich.rs), laplace_mixture (mixture.rs).	Finite-difference formulas of their own; samplers.
crates/commol-inference/src/psis.rs, importance.rs	Pareto-smoothed importance sampling (smooth, k̂); importance_sample of a Target from a Proposal on the unbounded scale, and TemperedPosterior, the last level of a TemperedTarget as a Target, which runs a stochastic model with one replicate of its seed (Stream::PosteriorReplicate) at every point.	Proposals of one method.
crates/commol-inference/src/smc/	Sequential Monte Carlo: the TemperedTarget port (smc/mod.rs), SmcSampler, next_level and abc_rejection (sampler.rs), the Kernel port and RandomWalk (kernel.rs), GibbsTarget with the calibrations of η (gibbs.rs), AbcTarget with its distances (abc.rs), LikelihoodTarget and bayesian_posterior (likelihood.rs).	Anything of one target in the sampler.

PyO3 bindings

Path	Owns	Do not put here
py-commol/build.rs, py-commol/src/build_info.rs	The version and the commit of a build: the build script reads the commit from the git metadata of the source and writes COMMOL_VERSION and COMMOL_COMMIT, which py-commol/src/lib.rs gives as __version__ and __commit__ of the extension; build_info.rs holds the rule (the placeholder 0.1.0 is not a release) and its tests.	Anything that runs the git program.
py-commol/src/core.rs	Bindings of the model types (Model, Process, Aggregate, …).	Logic.
py-commol/src/counts.rs	count and optional_count, the one reading of a count or a seed a binding takes from Python: the binding takes a count as i64 and a seed as i128 (its range ends at 2^64 - 1), so PyO3 reads only the type, and the rule of the setting in the engine converts it, with its message for a value outside the range.	A message or a minimum of its own.
py-commol/src/ranges.rs	commol_rs.core.check_ranges, the one check of the range rules of an object of the Python API, which joins the tables RANGES of commol-core, commol-calibration and commol-inference, and range_rules, each rule with a value outside its range and its message, for the tests.	A rule of a setting (the crates').
py-commol/src/model.rs	The queries of commol_rs.model on a process and its aggregate structure: initial_state, expanded_outputs, transition_flows, subgroup_total_names; check_model on a model; the rules of the values of a model (check_bin_amounts, check_compartment_amounts, check_fractions, check_impulse, check_series); the names NEIGHBORS and NEIGHBORS_PREFIX.	Logic beyond type conversion.
py-commol/src/engine.rs	commol_rs.engine: Engine::build (the four engines of the aggregate kind and those of the test kind), which checks the kind and builds the implementation of the pair of an EngineType entry and the kind of the structure, and the Python classes Engine (any engine, built from a model), EngineType (the list, for Python to ask) and ModelKind.	Engine logic.
py-commol/src/test_kind.rs	TestEngine and TestStochasticEngine, the engines of the test model kind, and commol_rs.test_kind.threads_of_runs, the threads that ran them; only with the test-kind feature.	Anything a release needs.
py-commol/src/calibration.rs	The calibration types (observations, parameters, constraints, loss, optimizers, results), the checks that take an Engine, and the windows of the engine (check_window, check_window_end, window_bounds, window_index, window_ends, windows_in, window_increments).	Logic beyond type conversion.
py-commol/src/identifiability.rs	commol_rs.inference: structural_rank, collinearity, sample_identifiability, starts_identifiability and their result classes.	Logic beyond type conversion.
py-commol/src/smc.rs	commol_rs.inference: Distribution, the priors as Python passes them, the runners of the sequential Monte Carlo methods (gibbs_posterior, bayesian_posterior, information_matching_eta, bootstrap_coverage_eta, abc_smc, abc_rejection) and SMCRun, EtaCoverage.	Logic beyond type conversion.
py-commol/src/local.rs	commol_rs.inference: the runners of the local approximations (laplace, sandwich, delta_band, laplace_mixture) and LocalRun, MixtureRun.	Logic beyond type conversion.
py-commol/src/conformal.rs	commol_rs.inference: check_conformal_settings, the runners of the conformal methods (split_conformal, rolling_conformal, jackknife_plus, enbpi, adaptive_conformal) and ConformalRun.	Logic beyond type conversion.
py-commol/src/sensitivity.rs	commol_rs.inference: ForwardAnalysis, the wrapper of the Rust type (one call per method, the predictive, the observation draws with no noise), chaos_evaluate, SobolRun, ChaosRun.	Logic beyond type conversion.
py-commol/src/quantity.rs	commol_rs.inference: the quantities of interest read from the JSON of their classes, quantities_as_read, which writes them back, quantity_schedule, and quantities_of_runs, the quantities of runs that are done.	Logic beyond type conversion.
py-commol/src/inference.rs	commol_rs.inference: CalibrationProblem (built once from a Calibrator, with a loss or observation models: starts, history, predictions, the predictive, the log score, the pointwise log-likelihood), ParameterSample, Predictive, ObservationDraws, BootstrapRun, JackknifeRun, weighted_quantiles, weighted_summary (WeightedSummary), effective_size, by_series, quantile_error; the runners of methods (the bootstraps, parametric_bootstrap, jackknife).	Logic beyond type conversion.
py-commol/src/profiles.rs	commol_rs.inference: trace_profiles, BootstrapSettings, Profile, ProfileRun.	Logic beyond type conversion.
py-commol/src/parallelism.rs	commol_rs.parallelism: the setting of the threads (a contextvars variable that holds a Parallelism), current, and parallel, the one helper through which every binding releases the GIL and runs its work in the pool of the setting.	A call of py.detach in another binding.
py-commol/src/python_observer.rs	The progress table of a verbose optimization, written to Python's sys.stdout.	Writes to the standard error.
py-commol/commol/commol_rs/_commol_rs.pyi	The type stub of the extension. Update it with every binding change.	—

Python package (py-commol/commol/)

Path	Owns	Do not put here
api/model_builder.py	The fluent ModelBuilder, which writes the process; build(structure, engine) joins it with a structure.	Validation rules that belong to the model; anything of one structure.
api/simulation.py	Simulation: runs (run, run_at, with the seed of a stochastic engine), replicates (replicates, ReplicateRuns), output grouping through ModelStructure.outputs_by_source.	Expansion rules; which positions a model type accepts; anything of one model kind.
api/results.py	SimulationResults (values with their positions, seed and model, its report, its plot and its quantities), SimulationReplicates (runs with one seed each, their statistics, their report, their plot and their quantities); outputs_for and total_series, the outputs of a source and their sum, which a simulation, a report and a figure share; sample, which reads positions with index_at of Rust.	Engine rules.
api/calibrator.py	Calibrator: the one conversion of a problem to Rust types, run(starts=n), run_with_history, and the entry point uncertainty; check_values, the check of the values a calibration or an analysis sets.	Loss or optimizer logic.
api/build_info.py	BuildInfo and build_info, the version and the commit the extension was built from, and the source of commol.__version__.	Reading the version or the commit in Python.
api/sensitivity.py	SensitivityAnalysis: the inputs, the replicates and the seed of an analysis, its forward model in Rust, and the entry point run.	Estimators.
api/inference/	What reads a sample: Predictive (predictive.py), Scenarios, the predictive of each scenario and their paired comparison (scenarios.py), the scores (api/inference/scores.py, exposed as commol.scores), the one interval convention (intervals.py: weighted_quantiles, member_statistics, ci_percentiles), the registry of method runners (registry.py), the runners of the identifiability methods (api/inference/identifiability.py), which build the report, the runners of the resampling methods (api/inference/resampling.py), of the sequential Monte Carlo methods (api/inference/smc.py), of the local approximations (api/inference/local.py), of the conformal methods (api/inference/conformal.py), which build ConformalResult, of the sensitivity methods (api/inference/global_sensitivity.py), and of the profiles (api/inference/profiles.py), which build ProfileResult.	Transforms of predictions; quantile formulas.
api/reporting.py	The private functions that build the blocks of the reports: of a run and of an ensemble (_simulation_report, for SimulationResults.report, SimulationReplicates.report and Predictive.report), of the applied parameters (_applied_parameters_report, for Model.applied_parameters, with the sections the structure adds, ModelStructure.report_sections) and of an identifiability analysis (_identifiability_report, for IdentifiabilityReport.report).	Domain vocabulary; sections of one model kind; a public report function.
api/parallelism.py	set_threads, threads, get_threads and get_levels, which set and read the setting of commol_rs.parallelism.	Validation (the engine's).
api/patterns.py, api/windows.py	Rates that change along the axis (AxisPattern), and windowed totals.	Physical units inside the model; window arithmetic (the engine's).
api/plotting/	The figures of results: the plot accessors of SimulationResults, SimulationReplicates and Predictive (accessors.py), plot_compared, the figure of several of them on the same panels (compared.py), the private drawing functions, which also draw the plot() of the results of sensitivity methods and profiles (figures.py, the only module that imports matplotlib), and the data of each panel, computed without matplotlib (panels.py).	Computation of results; a public drawing function.
context/inference/	InferenceMethod and its kinds UncertaintyMethod, IdentifiabilityMethod and SensitivityMethod (method.py), ParameterSample, SampleMethod, ParameterSummary, the identifiability methods and IdentifiabilityReport (context/inference/identifiability.py), the observation noise (noise.py: NoNoise, ResidualNoise, DistributionNoise), the distributions and Priors (distributions.py), and the settings and results of the resampling methods (context/inference/resampling.py), of the sequential Monte Carlo methods (context/inference/smc.py: GibbsPosterior, BayesianPosterior, InformationMatchingEta, BootstrapCoverageEta, ABCSMC, ABCRejection, the distances, SMCResult, GibbsResult), of the local approximations (context/inference/local.py: Laplace, Sandwich, LaplaceMixture, its targets, LaplaceResult, SandwichResult, DeltaBand, ImportanceResult), of the conformal methods (context/inference/conformal.py), of the sensitivity methods with InputSpace (context/inference/global_sensitivity.py), the quantities of interest (quantities.py: a series, Level or Increments, and its reduction), and of the profiles (context/inference/profiles.py: ProfileLikelihood, PredictionProfile, PredictionSpec, Threshold, ProfileResult).	Runners.
api/description.py	The renderers of a ModelDescription: text, Markdown (Mermaid), LaTeX, JSON and Graphviz DOT, and save.	Anything of one model kind: a renderer reads only blocks.
context/	The Pydantic model: fields, validation, JSON I/O, update methods.	Engine rules.
context/model.py	Model: the header, the engine, the process and the structure of any kind, generic in its structure class (Model[Aggregate]).	Anything of one model kind.
context/process.py	Process: bins, accumulators, stratifications and transitions, and the checks of the process by itself.	Checks that depend on a structure.
context/structure.py	ModelStructure, the interface every model kind gives the generic layers, and its registry of kinds and variants.	Code of one kind.
context/aggregate.py	Aggregate: the initial amounts and the neighbors, their checks against the process, and the aggregate side of the interface.	Generic code.
context/initial_conditions.py	InitialConditions, the fields Aggregate holds (bin amounts, category fractions, compartment amounts), the check of each amount and fraction with the rule of the engine, and their updates.	Checks against the process; the rule of an amount or a fraction (rules.rs).
context/bin.py, context/stratification.py, context/stratification_condition.py	Bin and Accumulator; Stratification and the checks of its categories; StratificationCondition.	Expansion (the engine's).
context/parameter.py	Parameter (a number, a formula, a series or None for calibration) and SeriesValue.	Evaluation of a formula or a series (the engine's).
context/calibration.py	The calibration problem as settings: CalibrationProblem, ObservedDataPoint, CalibrationParameter, CalibrationConstraint, Quantile, the optimizer settings (NelderMeadConfig, ParticleSwarmConfig and its parts, the stop rules), and the results (CalibrationResult, StartSummary, CalibrationHistory).	Losses, penalties, optimizers (the engine's).
context/ranges.py	RangeChecked, the base of every model of an object with range rules: its validator calls the check of the engine for the object (commol_rs.core.check_ranges) when the model is built.	A range constraint of pydantic; a rule of a setting.
context/result_model.py	ComparedByValue, the one equality of every result: == over the values a result compares (canonical), a NaN equal to a NaN, and never equal to a plain dict or list; ResultModel, its base of every result model (of a calibration, a method, a sample, a predictive band, a scenario summary, a score, and their parts), which compares the public fields and gives a frozen result a hash that agrees. SimulationResults and SimulationReplicates subclass ComparedByValue.	An __eq__ or a __hash__ of one result; the base of a setting.
context/constants.py	The enumerations of the calibration settings: CalibrationParameterType, LossFunction, OptimizationAlgorithm and those of a particle swarm.	—
context/visualization.py	PlotConfig, the settings of a figure, and its presets.	Drawing (api/plotting/).
context/neighbors.py	Complete and Groups, who the neighbors of a unit are.	How the terms resolve (the engine's).
context/description.py	ModelDescription and its blocks (Text, Table, Equations, StateGraph, Matrix): a description as data.	Rendering; code of one kind.
context/transition.py	Transition and StratifiedRate.	—
context/observation_models.py	The observation models of a calibration problem (NormalObservations, …, BinomialObservations, the union ObservationModel), as settings.	Densities and checks (the engine's).
context/axis_units.py	AxisUnits: values in units to steps of the axis, rates asked from the engine (Model.axis_units), the window grid of a width in a unit (from the engine), and the calendar of an axis with an origin (dates to positions, ends of days and weeks).	Formulas of a rate per engine (they are in RateMeaning).
context/engine.py	ModelEngine (Model.engine: the engine type and its settings, read with the class of that engine), the settings classes ODESolver, StochasticEventsSettings and StochasticStepsSettings (their defaults are constants of the engine, and each checks itself with check_settings of its engine), Rounding, and the names of the engines as the Literal EngineName.	Settings validation or engine meanings: ask commol_rs.engine.EngineType.
context/_model/engine_state.py	The only Python access to the engine queries, and build_engine, which builds the engine the model names.	Python re-implementations of them.
context/_model/describe.py	The sections every kind shares and the layouts of a description ("default", "odd").	Sections of one kind.
context/_model/ (other files)	Internals of an aggregate model: the sections of its description (aggregate_description.py, and the equations, event table and state graphs of _model/equations.py), unit checker, calibration write-back, the initial_amounts and category_splits report sections (report.py); JSON rendering of any model.	Public API.
context/report_entry.py	The spread of a report entry from the summary of a sample (Interval, entry_interval), for every kind.	—
utils/security.py	Validation of every user expression: the text guards and the limits of SecurityConfig, then the check of the engine (commol_rs.core.MathExpression).	Expression evaluation; a list of functions.
utils/equations.py	Dimensional analysis with pint: one unit rule per function of the engine (_FUNCTION_UNITS).	—
commol/constants.py	The names of the variables every expression has (TOTAL_VARIABLE) and the prefix of the subgroup totals (SUBGROUP_TOTAL_PREFIX), read from the engine (commol_rs.model).	Names that depend on a model (ask the engine).
commol/scores.py	The module commol.scores: the scores of api/inference/scores.py under a public path.	The scores themselves.

Other paths

Path	Owns
py-commol/tests/	Python tests: one package per page of the user guide (building/, transitions/, rates/, axis_patterns/, initial_conditions/, simulation/, stochastic/, units/, calibration/, uncertainty/, parallelism/, reporting/, plotting/, description/, docs/); reference_models/, published models checked against their stated results; model_kinds/, the test model kind through every generic layer; suite/, the checks of the rules of the tests; and support/ with the shared model factories, the test kind (kinds.py), the threads that run a method (support/parallelism.py), what a figure draws (support/plotted.py), the test uncertainty method (methods.py), the handler that shows the messages of commol in a test run (support/logs.py), the coverage harness (coverage.py), the planning scripts of .github/scripts/ loaded as modules (planning.py), the flow models, the reference solver, the oracles and the assertions. See Tests.
crates/*/tests/, #[cfg(test)] modules	Rust tests.
docs/	This site. docs/codebase/ is for maintainers; the rest is for users.
.github/ISSUE_TEMPLATE/	The templates of a proposal, a bug or small change, and a release (Planning).
.github/scripts/start.sh	Start an issue: write the links of the releases (parallel.py --releases), check the issue, take it, set it to In Progress, and create its branch and worktree, linked to the issue; then refresh the precedence levels (parallel.py --levels).
.github/scripts/next.sh	The next proposals and changes to implement: open, not blocked, not taken, not touching an issue in progress, by priority, the version of the milestone and number, after it writes the links of the releases and refreshes the precedence levels (parallel.py --releases --levels --next).
.github/scripts/parallel.py	The proposals and changes that can run in parallel, from their Touches or Where and the links of the open issues, printed and never written into an issue body; --next gives the next ones, --releases writes the links of the releases (Milestones), and --levels writes the precedence level of each open issue into the field Level of the project.
.github/scripts/github.py	The REST calls of parallel.py: every page, and one line that says why GitHub refused a request.
.github/scripts/affected.py	The open issues that the changes of a branch affect: those whose body names a changed path, read as a path by names_a_path of parallel.py.
.github/scripts/release_notes.py	The notes of a GitHub release, from its section of the changelog.
.github/scripts/rust_coverage.sh, .github/scripts/rust_uncovered.py	The Rust coverage as CI measures it: the Rust tests and pytest on an instrumented extension, and the check that every line no test runs has a // coverage: <reason> marker (Coverage).
.github/actions/set-version	The version of a release, from its tag, written into [workspace.package] of the root manifest.
.github/workflows/	CI: code quality, build, docs, release, the coverage studies (coverage.yaml), which Build and the release call, and the external links of the documentation (links.yaml).

If you need to…

Task	Start with	Then check
Change how a model expands into compartments	crates/commol-model/src/builder.rs (expand)	layout.rs, py-commol/commol/context/_model/engine_state.py
Change how transitions become flows	crates/commol-model/src/flows.rs	helpers.rs, system.rs (flow_rates, flow_changes, derivatives), context/_model/equations.py (DynamicsDescription)
Change the difference step, or the ODE engine and its solver settings	crates/commol-difference/src/simulation.rs; crates/commol-differential/src/solve.rs	crates/commol-core/src/simulation_engine.rs, crates/commol-differential/src/lib.rs, crates/commol-core/src/types/engine.rs (OdeSolver), py-commol/commol/context/engine.py
Add a model type (engine)	crates/commol-core/src/types/engine.rs (EngineType)	py-commol/src/engine.rs (Engine), py-commol/commol/context/engine.py, the checklist "Model type (engine)" in docs/codebase/maintainer-playbook.md
Add a model kind	py-commol/commol/context/structure.py (ModelStructure)	crates/commol-core/src/types/structure.rs, crates/commol-core/src/types/engine.rs (ModelKind), py-commol/src/engine.rs, the checklist "Model kind" in docs/codebase/maintainer-playbook.md
Change how a rate reads the neighbors of a unit	crates/commol-model/src/flows.rs (resolve_neighbors)	crates/commol-core/src/types/aggregate.rs (Neighbors), builder.rs (check_model), py-commol/commol/context/neighbors.py
Change impulses	crates/commol-model/src/system.rs (apply_impulses)	crates/commol-stochastic/src/units.rs (apply_impulses), every engine of the aggregate kind, crates/commol-model/src/rules.rs (check_impulse), py-commol/commol/context/transition.py
Change which positions a model type accepts, or how results, windows and reports read them	crates/commol-core/src/types/engine.rs (EngineType::check_position); py-commol/commol/api/results.py	crates/commol-core/src/position.rs (same_position), crates/commol-calibration/src/observation.rs (index_at, window_increments, the grid of windows), each engine's check_position, crates/commol-calibration/src/calibration_problem.rs (check_positions), api/windows.py, api/reporting.py, api/plotting/, api/inference/predictive.py
Change axis units, the calendar of an axis or axis patterns	py-commol/commol/context/axis_units.py; py-commol/commol/api/patterns.py	crates/commol-calibration/src/observation.rs (the grid of windows), context/_model/units.py, crates/commol-core/src/types/engine.rs (RateMeaning), docs/guide/units-and-equations.md, docs/guide/axis-patterns.md
Change a figure	py-commol/commol/api/plotting/ (panels.py, the data; figures.py, the drawing)	api/plotting/accessors.py, api/plotting/compared.py (plot_compared), the plot method of the result, docs/guide/simulations.md (Plotting), docs/codebase/decisions/figures.md
Add a function, a variable or an operator to rate expressions, or change their grammar	crates/commol-core/src/math_expression/ (language.rs: FUNCTIONS, check; jit/parser.rs: parse_expression, MAX_NESTING)	jit/ast.rs (Expr), jit/codegen.rs, py-commol/commol/utils/equations.py (_FUNCTION_UNITS), docs/guide/mathematical-expressions.md
Change initial conditions	py-commol/commol/context/initial_conditions.py	crates/commol-model/src/builder.rs (initial_state), crates/commol-model/src/rules.rs (the rule of an amount or a fraction), py-commol/commol/context/aggregate.py, docs/guide/building-models.md
Change a stochastic engine (events, chain binomial, whole units), seeds or samplers	crates/commol-stochastic/src/ (events.rs, steps.rs, units.rs); crates/commol-random/ (streams.rs: the seed streams of every method that draws from a seed)	crates/commol-core/src/types/engine.rs (StochasticEventsSettings, Rounding, is_stochastic), crates/commol-model/src/system.rs (flow_changes, breakpoints), crates/commol-core/src/simulation_engine.rs (set_seed, run_replicates), py-commol/commol/context/engine.py, py-commol/commol/api/simulation.py (replicates), docs/guide/stochastic.md
Change calibration	crates/commol-calibration/src/calibration_problem.rs and its layers (forward.rs, observation.rs, feasibility.rs, discrepancy.rs, objective.rs); crates/commol-calibration/src/starts.rs	values.rs, crates/commol-model/src/initial_conditions.rs, py-commol/commol/api/calibrator.py, py-commol/src/inference.rs (CalibrationProblem)
Add or change an observation model or the likelihood	crates/commol-calibration/src/likelihood/ (likelihood/mod.rs, density.rs)	crates/commol-inference/src/predictive.rs (draw_observation), py-commol/src/calibration.rs (ObservationModel), py-commol/commol/context/observation_models.py, context/_model/engine_state.py (rust_observation_models), docs/guide/uncertainty/observation-models.md
Add an uncertainty method	crates/commol-inference/	py-commol/src/ (inference.rs or the module of its family), py-commol/commol/context/inference/, api/inference/registry.py, the checklist "Uncertainty method" in docs/codebase/maintainer-playbook.md
Change a profile, its thresholds or a subproblem that holds a quantity	crates/commol-inference/src/profiles/ (tracer.rs, threshold.rs, verdict.rs, resets.rs), crates/commol-calibration/src/subproblem.rs	crates/commol-calibration/src/optimization.rs (optimize_subproblem), py-commol/src/profiles.rs, py-commol/commol/context/inference/profiles.py, api/inference/profiles.py, docs/guide/uncertainty/profiles.md
Change sensitivities or identifiability	crates/commol-inference/src/sensitivity/, crates/commol-inference/src/identifiability/	crates/commol-core/src/simulation_engine.rs (output_accuracy), py-commol/src/identifiability.rs, py-commol/commol/context/inference/identifiability.py, api/inference/identifiability.py, docs/guide/uncertainty/identifiability.md
Change a bootstrap, the jackknife, blocks or residual noise	crates/commol-inference/src/resampling/	crates/commol-calibration/src/calibration_problem.rs (with_data), py-commol/src/inference.rs (bootstrap, jackknife), py-commol/commol/context/inference/resampling.py, api/inference/resampling.py, docs/guide/uncertainty/resampling.md
Change a sequential Monte Carlo method (the sampler, a target, a move kernel) or a prior	crates/commol-inference/src/smc/ (sampler.rs, gibbs.rs, abc.rs, kernel.rs); distribution.rs, priors.rs, transform.rs	py-commol/src/smc.rs, py-commol/commol/context/inference/smc.py, context/inference/distributions.py, api/inference/smc.py, docs/guide/uncertainty/smc.md
Change a conformal method, its scores or its quantile	crates/commol-inference/src/conformal/	py-commol/src/conformal.rs, py-commol/commol/context/inference/conformal.py, api/inference/conformal.py, docs/guide/uncertainty/conformal.md
Change a sensitivity method, a design or a quantity of interest	crates/commol-inference/src/global_sensitivity/; design.rs, crates/commol-inference/src/quantity.rs, batch.rs	crates/commol-calibration/src/forward.rs (unobserved), py-commol/src/sensitivity.rs, py-commol/src/quantity.rs, py-commol/commol/context/inference/quantities.py, context/inference/global_sensitivity.py, api/sensitivity.py, api/inference/global_sensitivity.py, api/results.py (quantities), docs/guide/uncertainty/sensitivity.md
Change a local approximation (the curvature, Laplace, the sandwich, the Laplace mixture) or PSIS	crates/commol-inference/src/local/; psis.rs, importance.rs	crates/commol-calibration/src/likelihood/density.rs (information, scores), discrepancy.rs (term_derivatives), py-commol/src/local.rs, py-commol/commol/context/inference/local.py, api/inference/local.py, docs/guide/uncertainty/local.md
Change the parameter sample, the predictive, the scenarios, the scores or the quantile	crates/commol-inference/src/sample.rs, predictive.rs, scores.rs; crates/commol-statistics/src/statistics.rs (the one quantile, also of the replicates of a calibration)	py-commol/commol/context/inference/sample.py, api/inference/ (scenarios.py), docs/guide/uncertainty/index.md
Change the Python API	py-commol/commol/api/	docs/api/, the guide page of that feature
Expose a Rust function to Python	py-commol/src/; py-commol/src/engine.rs for a function that takes an engine; parallel (py-commol/src/parallelism.rs) to run parallel work	py-commol/commol/commol_rs/_commol_rs.pyi, py-commol/commol/context/_model/engine_state.py (the only Python caller of the engine queries)
Change the threads of parallel work	crates/commol-core/src/parallelism.rs (Parallelism)	py-commol/src/parallelism.rs (parallel), py-commol/commol/api/parallelism.py (commol.threads), docs/guide/parallelism.md
Change the version or the commit a build reports	py-commol/build.rs, py-commol/src/build_info.rs	py-commol/commol/api/build_info.py, .github/actions/set-version, docs/development/release.md
Change how a model is described	py-commol/commol/context/description.py (blocks), context/_model/describe.py (layouts)	ModelStructure.describe, context/_model/aggregate_description.py, api/description.py (renderers), docs/guide/describing-models.md
Change reports	py-commol/commol/api/reporting.py (the blocks)	the methods that call it (api/results.py: SimulationResults.report, SimulationReplicates.report; api/inference/predictive.py: Predictive.report; context/model.py: Model.applied_parameters; context/inference/identifiability.py: IdentifiabilityReport.report), ModelStructure.report_sections, context/_model/report.py, docs/codebase/decisions/results.md (Reports)

Placement rule

Place code at the narrowest owner that can hold it:

1. A rule about how a model becomes numbers → a Rust crate.
2. Type conversion between Python and Rust → py-commol/src/.
3. Validation of user input → the Pydantic model in context/.
4. User-facing workflow → api/.
5. Presentation (reports, figures) → api/reporting.py, api/plotting/.

Navigation

Previous: Architecture | Next: Design decisions