gds-viz 0.1.0

Mermaid diagram renderers for gds-framework specifications

gds-viz

Mermaid diagram renderers for gds-framework specifications.

uv add 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 because they require semantics that GDS does not define:

State Machine View

A state machine requires discrete states and transition guards — e.g., "if infected > threshold, move to EPIDEMIC state." GDS defines a continuous state space X (the product of entity variables: floats, ints, etc.). There is no finite set of named states, no guard predicates, and no transition labels in the formalism. A state machine view would require discretizing X and defining guards, which is domain-specific interpretation layered on top of GDS — not something derivable from {h, X}.

Simulation / Execution Order View

A simulation view would describe when blocks execute, in what order, with what timing (synchronous? event-driven? what dt?). GDS deliberately specifies only structural relationships — who feeds whom, what role each block plays, which variables get updated. It never prescribes an execution schedule. The composition algebra defines topology, not a runtime. That's why SystemIR has blocks and wirings but no step() method.

The dependency partial order (which blocks must complete before others) IS derivable and is already shown as edges in Views 3-6. But calling it "execution order" would overstate its meaning — it defines constraints, not a schedule.

Where these views belong

Both views require operational semantics that live outside the specification layer:

Concern	In GDS?	Where it belongs
State space X (continuous)	Yes	GDSSpec, CanonicalGDS
Block topology	Yes	SystemIR, GDSSpec
Dependency partial order	Yes	SpecQuery.dependency_graph()
Parameter influence	Yes	SpecQuery.param_to_blocks()
Discrete state machine	No	Domain-specific layer or gds-sim
Execution schedule	No	Simulator / runtime (gds-sim)
Time semantics (dt, sync)	No	Simulator / runtime (gds-sim)

A future gds-sim package could consume GDSSpec and add execution semantics, at which point state machine and simulation views would become derivable from (GDSSpec, SimConfig) — but not from GDSSpec alone.

License

Apache-2.0

Credits & Attribution

Development & Implementation

• Primary Author: Rohan Mehta
• Organization: BlockScience

Theoretical Foundation

This codebase is a direct implementation of the research and mathematical frameworks developed by:

• Dr. Jamsheed Shorish (@jshorish) and Dr. Michael Zargham (@mzargham).
• Key Reference: Generalized Dynamical Systems, Part I: Foundations (BlockScience, 2021).

Architectural Inspiration

The design patterns and structural approach of this library are heavily influenced by the prior work of Sean McOwen (@SeanMcOwen), specifically:

• MSML: For system specification logic.
• bdp-lib: For block-data processing architecture.

Contributors

• Peter Hacker (@phacker3) — Code auditing and review (BlockScience).

Intellectual Lineage

This project exists within the broader ecosystem of:

• cadCAD: For foundational philosophy in Complex Adaptive Dynamics.