diff --git a/docs/case-studies/axelrod.md b/docs/case-studies/axelrod.md new file mode 100644 index 0000000..1d48d17 --- /dev/null +++ b/docs/case-studies/axelrod.md @@ -0,0 +1,79 @@ +# Axelrod Tournament + +**One model, many views** — an interactive exploration of Axelrod's iterated Prisoner's Dilemma tournament, built on the GDS ecosystem. + +[:octicons-link-external-16: Live Site](https://blockscience.github.io/gds-axelrod/)   [:octicons-mark-github-16: Source](https://github.com/BlockScience/gds-axelrod) + +--- + +## Overview + +[gds-axelrod](https://github.com/BlockScience/gds-axelrod) demonstrates how a single OGS game specification can be projected through six distinct analytical lenses — from narrative storytelling to formal mathematical decomposition to interactive parameter exploration — without simplification or compromise. + +The project is a concrete realization of the **specification-as-interoperability-layer** pattern described in the [Interoperability Guide](../guides/interoperability.md): one compositional model serves as the single source of truth, and multiple independent tools consume it for different purposes. + +## Architecture + +The project splits into two tiers: + +``` +Pipeline (Python) Site (Vite/JavaScript) +┌──────────────────────┐ ┌──────────────────────────┐ +│ OGS game definition │──export──→ │ Canvas Petri dish viz │ +│ gds-sim population │ (JSON) │ Mermaid diagrams │ +│ gds-psuu sweeps │ │ Narrative chapters │ +│ Nash/dominance calc │ │ Pyodide PSUU sandbox │ +└──────────────────────┘ └──────────────────────────┘ +``` + +**Pipeline**: Python data generation using `gds-games`, `gds-sim`, `gds-psuu`, and `gds-viz`. Produces JSON artifacts consumed by the frontend. + +**Site**: Vite-based JavaScript frontend with Canvas rendering, responsive chapter navigation, and browser-side Python execution via Pyodide. + +## Six Showcase Views + +Each page presents the same underlying Prisoner's Dilemma model through a different analytical lens: + +| View | What It Shows | GDS Package | +|------|---------------|-------------| +| **Story** | Narrative chapters with interactive sandbox simulation | Strategy definitions from OGS | +| **Formal Structure** | Canonical `h = f . g` decomposition | `GDSSpec` + `project_canonical()` | +| **Visualizations** | Mermaid diagrams across 6 view types | `gds-viz` on `SystemIR` | +| **Simulation** | Population trajectory tracking over generations | `gds-sim` | +| **Nash Analysis** | Equilibria and dominance calculations | `PatternIR` from `gds-games` | +| **PSUU** | Interactive parameter space exploration | `gds-psuu` via Pyodide | + +## GDS Ecosystem Integration + +gds-axelrod exercises four GDS packages together, demonstrating the composability of the ecosystem: + +- **gds-games** (`ogs`) — defines the game as an OGS pattern, compiles to `PatternIR` and `GDSSpec` +- **gds-viz** (`gds_viz`) — renders Mermaid diagrams from the compiled `SystemIR` +- **gds-sim** (`gds_sim`) — runs population dynamics simulation over iterated tournament rounds +- **gds-psuu** (`gds_psuu`) — parameter sweeps compiled to WebAssembly via Pyodide for in-browser execution + +## Key Patterns Demonstrated + +### Specification as Single Source of Truth + +The OGS game definition is written once. Every view — visualization, simulation, equilibrium analysis, parameter exploration — derives from the same specification. No view has a private copy of the model. + +### Thin Projections + +Each analytical tool is a thin projection over the specification: + +- `PatternIR` → Nash equilibria via Nashpy +- `PatternIR` → payoff matrix → tournament simulation +- `SystemIR` → Mermaid diagrams via gds-viz +- `GDSSpec` → canonical decomposition + +### Browser-Side Computation + +The PSUU page compiles Python (gds-sim + gds-psuu) to WebAssembly via Pyodide, enabling interactive parameter exploration without a backend server. + +## Related + +- [Interoperability Guide](../guides/interoperability.md) — the specification-as-interoperability-layer pattern +- [Evolution of Trust](../examples/examples/evolution-of-trust.md) — the in-repo tutorial model that gds-axelrod builds upon +- [Prisoner's Dilemma](../examples/examples/prisoners-dilemma.md) — the base GDS framework version +- [View Stratification](../guides/view-stratification.md) — the theoretical basis for "one model, many views" diff --git a/docs/case-studies/index.md b/docs/case-studies/index.md new file mode 100644 index 0000000..470c3d8 --- /dev/null +++ b/docs/case-studies/index.md @@ -0,0 +1,7 @@ +# Case Studies + +Real-world projects built on the GDS ecosystem, demonstrating how compositional specifications translate into interactive applications, research tools, and educational platforms. + +| Project | Domain | GDS Packages Used | Description | +|---------|--------|-------------------|-------------| +| **[Axelrod Tournament](axelrod.md)** | Game Theory | gds-games, gds-sim, gds-psuu, gds-viz | Interactive exploration of the iterated Prisoner's Dilemma through six analytical views | diff --git a/mkdocs.yml b/mkdocs.yml index c8a9910..421aab0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,6 +114,9 @@ plugins: - {psuu/getting-started.md: "Installation + first parameter sweep"} - psuu/guide/*.md - psuu/api/*.md + Case Studies: + - {case-studies/index.md: "Real-world projects built on the GDS ecosystem"} + - {case-studies/axelrod.md: "Axelrod tournament — one model, many views with gds-games, gds-sim, gds-psuu, gds-viz"} Ecosystem: - {framework/ecosystem.md: "All packages, their imports, and dependency relationships"} @@ -332,6 +335,9 @@ nav: - gds_psuu.optimizers: psuu/api/optimizers.md - gds_psuu.sweep: psuu/api/sweep.md - gds_psuu.results: psuu/api/results.md + - Case Studies: + - case-studies/index.md + - Axelrod Tournament: case-studies/axelrod.md - Design & Research: - Layer 0 Milestone: guides/architecture-milestone-layer0.md - DSL Roadmap: guides/dsl-roadmap.md