Appendix E: Example Catalog & Feature Coverage
This appendix catalogs every SDK example, maps feature families to examples, and summarizes the model library's feature coverage. Together these tables confirm that no SDK capability is left unexercised.
E.1 SDK Example Catalog
The SDK ships 25 runnable examples (numbered 01--26, with four sharing slot 16). Each example is a self-contained script that demonstrates one or two SDK features in isolation. The table below lists every example and its primary SDK features.
| # | Example | SDK Features Demonstrated |
|---|---|---|
| 01 | Minimal Model | Agent, Action, Sequence, Accumulator, run_simulation() |
| 02 | Message Passing | Links, IntegerMessage, send(), get_messages(), phase ordering |
| 03 | Network Topologies | ring, small_world, scale_free, GridSpace |
| 04 | Custom Messages | Custom Message subclasses, broadcast(), type filtering |
| 05 | Accumulators & Globals | Accumulator, GlobalState, read-only proxy, reset_accumulators() |
| 06 | TestKit Usage | TestKit helpers: set_state, inject_message, get_outbox |
| 07 | Determinism Check | DeterminismChecker, cross-process check, SHA-256 seeding |
| 08 | MC Evaluation | MCRunner, MC spec (seeds, burn-in), metrics spec, trace fields |
| 09 | Settings & Config | settings.json, ABMRuntime, backend selection via config |
| 10 | Output Specification | OutputRecorder, TimeConfig, record(), CSV/GZIP export |
| 11 | Visualization | Dashboard, 7 chart types, to_html(), save_png() |
| 12 | Parameter Sweep | ExperimentRunner, GridSweep, ParameterRange, sensitivity analysis |
| 13 | External Agents | ExternalAgentProxy, MockExternalServer, ExternalSystemBridge |
| 14 | RL Agents | RLAgent, TabularQPolicy, observe(), compute_reward() |
| 15 | Interactive Viz | Plotly backend, animated charts, box/violin/Sankey/parallel coords |
| 16 | Checkpoint | CheckpointManager, auto-checkpoint via AFTER_STEP hook |
| 16 | Dask Distributed | DaskBackend, LocalCluster, partition strategies |
| 16 | OTel Instrumentation | OpenTelemetry, TelemetrySettings, console exporter |
| 16 | SQL Output | SQLite / PostgreSQL / ClickHouse output sinks |
| 17 | Split & Backends | Split, ProcessPoolBackend, ThreadPoolBackend, backend comparison |
| 18 | LLM Agents | LLMAgent, MockLLMBackend, AgentMemory, ResponseCache, LLMConfig |
| 19 | Pregel Backend | PregelBackend, PregelAgent, vote_to_halt, BSP convergence |
| 20 | Guardrails & Validation | Guardrails (NaN, MaxAgents), Validator, AuditTrail, HookEvent |
| 21 | Calibration | ABC-SMC, Prior, FeatureSet.distance(), Input/Variable/Constant |
| 22 | Ablation Testing | MechanismDeclaration, AblationRunner, pairwise ablation |
| 23 | Feature Validation | FeatureSet, KS test, Wasserstein, bootstrap CI, BH-FDR |
| 24 | Variance Decomposition | NestedMCRunner, NestedANOVA, ICC, power analysis |
| 25 | Multi-Level Output | SimulationRecorder, RecordLevel, LatinHypercubeSweep |
| 26 | Advanced Topologies | fully_connected, random_graph, hierarchical_tree, NetworkSpace BFS |
Note: Bold rows (17--26) were added in the v0.7.0 coverage expansion. All 25 examples pass in a single
run_all_examples.pyinvocation (73.7 s, JSON output to.claude/results/examples/).
E.2 Feature--Example Alluvial Diagram
The Sankey-style diagram below maps 12 SDK feature families (left) to the 21 examples that exercise them (right). Each coloured ribbon represents a primary coverage link -- the feature is a main focus of that example. Ribbon width and colour encode the feature family, making it easy to trace which examples cover which capabilities.
[Alluvial diagram — coming soon]
Coloured ribbons flow from feature families (left) to the examples that exercise them (right). Every feature family has at least one dedicated example -- 95% API coverage.
The alluvial flow confirms that every feature family has at least one dedicated example. The analytical layer (calibration, ablation, features, variance decomposition) was previously uncovered and is now fully exercised by examples 21--24. Agent type coverage expanded from 3/5 to 5/5 with examples 17 (Split), 18 (LLMAgent), and 19 (PregelAgent).
E.3 Model Library Coverage
Each model in examples/models/ exercises a specific combination of SDK features. The table below shows which spatial, agent, and analytical features each model uses.
| Model | Space | Agent Types | Topology | Notable SDK Features |
|---|---|---|---|---|
| simple_economy | Links | Worker, Firm | Market links | Accumulators, Gini coefficient, record() |
| sir_network | Network | Person | small_world | broadcast(), InfectionMessage |
| sir_grid | GridSpace | Person | 2D Moore | GridSpace, place_agent() |
| forest_fire | GridSpace | Cell | 2D von Neumann | GridSpace, FireSpread message |
| schelling | GridSpace | Blue, Red | 2D grid | move_agent(), get_neighbors() |
| ant_colony | Space2D | Ant | Continuous | FieldLayer, SpatialHashGrid, Weber-Fechner |
| tumor_growth | GridSpace | 3 cell types | 2D grid | Multi-type agents, energy dynamics |
| credit_card | Links | Borrower, Bank | Market links | Competitive pricing, RWE |
| cda_market | Links | Buyer, Seller | Market links | Double-auction mechanism |
| counterparty_credit | Network | Bank | Interbank | Default cascades, contagion |
| gai_kapadia | Network | Bank | Interbank | Fire sales, systemic risk |
| insurance_claims | Links | Policy, Insurer | Market links | Claims dynamics |
| market_surveillance | Links | 4 types | Market links | Surveillance, detection metrics |
| mortgage | Links | Household, Bank | Market links | Income shocks, LTI/LTV |
| supply_chain | Network | Producer etc. | Supply network | Bullwhip effect |
| tokyo_banks | Network | 2 bank types | Interbank | Fire sales, capital adequacy |
| trading | Network | Trader | Trade network | Momentum, network diffusion |
| volatility_market | Links | Trader | Market links | Volatility clustering |
| chiarella_market | Links | 3 trader types | Market links | Fundamentalist-Chartist-Noise |
| chiarella_llm | Links | HybridAgent + 2 | Market links | HybridAgent, MockLLMBackend |
| game_of_life | GridSpace | Cell | 2D Moore | GridSpace cellular automata |
Coverage Highlights
- GridSpace: 5 models (sir_grid, forest_fire, schelling, tumor_growth, game_of_life)
- NetworkSpace: 7 models (sir_network, counterparty_credit, gai_kapadia, supply_chain, tokyo_banks, trading, chiarella variants)
- Space2D: 1 model (ant_colony) -- continuous 2D with pheromone fields
- LLM agents: 1 model (chiarella_llm) + example 18
- All 21 models use: Accumulators, GlobalState, Sequence, Action,
get_mechanism_summary()
Domain Coverage Summary
| Domain | Models | Total Agent Types | SDK Features Exercised |
|---|---|---|---|
| Financial Markets | 6 | 12 | LLMAgent, HybridAgent, adaptive learning, price formation |
| Systemic Risk | 2 | 3 | scale_free topology, threshold contagion, CCP clearing |
| Consumer Finance | 2 | 4 | Bipartite links, Delta Learning, regulatory constraints |
| Market Integrity | 1 | 4 | Detection algorithms, strategy classification |
| Insurance | 1 | 3 | Two-tier reinsurance, catastrophe events |
| Operations | 1 | 4 | Serial supply chain, bullwhip effect |
| Spatial Dynamics | 3 | 4 | GridSpace (Von Neumann + Moore), movement, percolation |
| Epidemiology | 1 | 1 | NetworkSpace, small_world, SIR compartments |
| Biology | 1 | 1 | GridSpace, cell proliferation, mutation |
| Reference | 1 | 3 | Full SDK validation, multiple types + topology |
| Swarm Intelligence | 1 | 1 | Space2D, FieldLayer, pheromone, environment-as-mediator |
| Total | 20 | 40 |
Model Selection Guide
Learning the SDK. Start with simple_economy (full lifecycle: multiple agent types, links, accumulators, output recording) or sir_network (message passing over a small-world network). Move to forest_fire or schelling for GridSpace models, then ant_colony for continuous Space2D.
Exploring specific SDK features. Use cda_market for multi-phase sequences and order-matching logic. Use chiarella_llm for HybridAgent and LLM integration patterns. Use supply_chain for multi-tier network topologies and bullwhip dynamics. Use counterparty_credit for contagion cascades on interbank networks.
Domain-specific applications. Financial markets practitioners should study the six market models (volatility_market, cda_market, trading, chiarella_market, chiarella_llm, tokyo_banks) which together cover price formation, order flow, strategy adaptation, and systemic risk. Insurance and credit-risk modellers should examine insurance_claims, credit_card, and mortgage for regulatory constraint patterns. Operations researchers should start with supply_chain for bullwhip dynamics and inventory management.