GDS Framework Examples

Six complete domain models demonstrating every gds-framework feature. Each model.py is written as a tutorial chapter with inline GDS theory commentary — read them in order.

Quick Start

# Run all example tests (168 tests)
uv run pytest examples/ -v

# Run a specific example
uv run pytest examples/sir_epidemic/ -v

# Generate all 6 views for one example
uv run python examples/sir_epidemic/generate_views.py --save

Learning Path

#	Example	New Concept	Composition
1	SIR Epidemic	Fundamentals — TypeDef, Entity, Space, blocks	>> \|
2	Thermostat PID	.feedback(), CONTRAVARIANT backward flow	>> .feedback()
3	Lotka-Volterra	.loop(), COVARIANT temporal iteration	>> \| .loop()
4	Prisoner's Dilemma	Nested \|, multi-entity X, complex trees	\| >> .loop()
5	Insurance Contract	ControlAction role, complete 4-role taxonomy	>>
6	Crosswalk Problem	Mechanism design, discrete Markov transitions	>>

Start with SIR Epidemic and work down — each introduces one new concept.

File Structure

Each example follows the same layout:

examples/sir_epidemic/
├── __init__.py          # empty
├── model.py             # types, entities, spaces, blocks, build_spec(), build_system()
├── test_model.py        # comprehensive tests for every layer
├── generate_views.py    # generates all 6 visualization views with commentary
└── VIEWS.md             # generated output — 6 Mermaid diagrams with explanations

Credits

Author: Rohan Mehta — BlockScience

Theoretical foundation: Dr. Michael Zargham and Dr. Jamsheed Shorish

Lineage: Part of the cadCAD ecosystem for Complex Adaptive Dynamics.