Codebase Guide¶
This guide helps you find the right code before you change Commol. It is an index for maintainers and AI agents, not an API reference: for the public API, see the User Guide and the API Reference.
These pages describe main
The dev version of this site is built from main and may describe
unreleased code. The latest version is built from the last release tag.
Who this is for¶
| Reader | Use this guide to |
|---|---|
| New maintainer | Build the mental model before you touch files. |
| Contributor | Find the module that owns a behavior. |
| Reviewer | Check that a pull request changes the right layer. |
| AI agent | Start from AGENTS.md, then read these pages by path. |
The golden rule¶
Rust decides how a model becomes numbers, and Python asks it. The Mental model states the rule and draws the layers.
Guide pages¶
| Page | Job |
|---|---|
| Mental model | What Commol is, what it is not, and the invariants every change must keep. |
| Architecture | Diagrams of the two halves, the Rust crates, and the path of a simulation and a calibration. |
| Repository map | Which module owns which behavior, and where new code goes. |
| Design decisions | The rules that are not obvious from the code, one page per area, with the tests that guard them. |
| Conventions | How code, comments, docs and commits are written. |
| Tests | The layout, the models, the oracles and the tolerances of the tests; what a test must not check, duplicates, skips and the time budget. |
| Coverage and mutation testing | The coverage of Python and Rust, its thresholds, the lines left out and why, and mutation testing. |
| Maintainer playbook | Checklists by type of change. |
Recommended reading path¶
- Mental model.
- Architecture for the picture of the code.
- Repository map before you edit code.
- The page of Design decisions of the area you change.
- Maintainer playbook before you open or review a pull request.
Related pages¶
| Page | Job |
|---|---|
| Development workflow | Setup, branches, CI, and merge rules. |
| Contributing | Bug reports, pull requests, code review. |
| Release process | How a version reaches PyPI. |
| Model structure | Reference of the model data types. |