gds-viz 0.1.1

Mermaid diagram renderers for gds-framework specifications

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	Function	Input	Answers
1. Structural	system_to_mermaid()	SystemIR	What blocks exist and how are they wired?
2. Canonical GDS	canonical_to_mermaid()	CanonicalGDS	What is the formal decomposition h = f ∘ g?
3. Architecture (role)	spec_to_mermaid()	GDSSpec	How do blocks group by GDS role?
4. Architecture (domain)	spec_to_mermaid(group_by=...)	GDSSpec	How do blocks group by domain/agent?
5. Parameter influence	params_to_mermaid()	GDSSpec	What does each parameter control?
6. Traceability	trace_to_mermaid()	GDSSpec	What can affect a specific state variable?

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")

What gds-viz does NOT cover

The six views above exhaust what is derivable from the GDS specification {h, X}. Two commonly requested views are deliberately excluded:

State Machine View — requires discrete states and transition guards. GDS defines a continuous state space X, not a finite set of named states. Discretizing X is domain-specific interpretation, not derivable from {h, X}.

Simulation / Execution Order View — requires operational semantics (when blocks execute, in what order, with what timing). GDS specifies only structural relationships. The composition algebra defines topology, not a runtime.

Concern	In GDS?	Where it belongs
State space, block topology, dependencies, parameters	Yes	GDSSpec, SystemIR, SpecQuery
Discrete state machine	No	Domain-specific layer or gds-sim
Execution schedule, time semantics	No	Simulator / runtime (gds-sim)

A future gds-sim package could add execution semantics, making these views derivable from (GDSSpec, SimConfig).

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.