gds-viz

Mermaid diagram renderers for gds-framework specifications.

uv add gds-viz
# or: pip install gds-viz

Views

gds-viz provides six views — each a different projection of the GDS specification {h, X}:

View 1: Structural

The compiled block graph from SystemIR. Shows composition topology — sequential, parallel, feedback, temporal — with role-based shapes (stadium for boundary, double-bracket for mechanism) and wiring types (solid, dashed, thick).

from gds_viz import system_to_mermaid
mermaid = system_to_mermaid(system)

View 2: Canonical GDS

The mathematical decomposition: X_t → U → g → f → X_{t+1} with parameter space Θ. Derives from CanonicalGDS (via project_canonical(spec)). Shows state variables in X nodes, role subgraphs, labeled update edges, and parameter dependencies.

from gds.canonical import project_canonical
from gds_viz import canonical_to_mermaid
mermaid = canonical_to_mermaid(project_canonical(spec))

Views 3 & 4: Architecture

Domain-level diagrams from GDSSpec. Show entity state cylinders, typed wire labels (from Wire.space), and mechanism-to-entity update edges. View 3 groups by GDS role; View 4 groups by any tag key.

from gds_viz import spec_to_mermaid
by_role = spec_to_mermaid(spec)                    # View 3
by_agent = spec_to_mermaid(spec, group_by="domain") # View 4

Tags are set on blocks at definition time:

sensor = BoundaryAction(name="Sensor", ..., tags={"domain": "Observation"})

View 5: Parameter Influence

Shows Θ → block → entity causal map. Hexagon nodes for parameters, dashed edges to blocks that use them, then forward through the dependency graph to entities. Answers: "if I change parameter X, what state is affected?"

from gds_viz import params_to_mermaid
mermaid = params_to_mermaid(spec)

View 6: Traceability

For a single entity variable, traces every block that can transitively affect it and every parameter feeding those blocks. Right-to-left layout with thick edges for direct updates. Answers: "what controls this variable?"

from gds_viz import trace_to_mermaid
mermaid = trace_to_mermaid(spec, "Susceptible", "count")

License

Apache-2.0

Built with Claude Code. All code is test-driven and human-reviewed.

Credits & Attribution

Author: Rohan Mehta — BlockScience

Theoretical foundation: Dr. Michael Zargham and Dr. Jamsheed Shorish — Generalized Dynamical Systems, Part I: Foundations (2021).

Architectural inspiration: Sean McOwen — MSML and bdp-lib.

Contributors:

• Michael Zargham — Project direction, GDS theory guidance, and technical review (BlockScience).
• Peter Hacker — Code auditing and review (BlockScience).

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