Model specification guide: defining compartmental systems

[jc-macdonald]

Summary

Write a user-facing guide for the docs site covering how to write an op_system model specification in YAML.

Motivation

The current docs site has only a placeholder getting-started page and auto-generated API reference. There is no guide explaining the specification format to users who want to build compartmental models with op_system.

Scope

The guide should cover:

1. States — defining compartments and their initial conditions.
2. Transitions — specifying flows between states with rate expressions.
3. Axes — adding population structure (age groups, spatial regions, risk strata).
4. Mixing — contact matrices and cross-group interactions.
5. Operators — operator splitting for multi-scale processes (if applicable).
6. Expression syntax — how rate expressions are parsed and evaluated.
7. Constraints — cross-axis constraints / axis masking (Document constraints block in README and guides #39).
8. Complete example — a fully worked SEIR-with-age-groups spec with annotations.

Placement

Should live under docs/guides/ on the op_system docs site. Link from the README.

Related

• Document constraints block in README and guides #39 (document constraints block — can be a section in this guide)
• Realistic tutorial: epidemic model with op_system and op_engine flepimop2#198 (realistic tutorial that uses op_system specs)