Metadata-Version: 2.4
Name: gds-viz
Version: 0.1.0
Summary: Mermaid diagram renderers for gds-framework specifications
Project-URL: Homepage, https://github.com/BlockScience/gds-viz
Project-URL: Repository, https://github.com/BlockScience/gds-viz
Author-email: Rohan Mehta <rohan@block.science>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: block-diagram,gds-framework,generalized-dynamical-systems,mermaid,system-specification,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: gds-framework>=0.2.0
Description-Content-Type: text/markdown

# gds-viz

Mermaid diagram renderers for [gds-framework](https://pypi.org/project/gds-framework/) specifications.

```bash
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).

```python
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.

```python
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.

```python
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:

```python
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?"

```python
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?"

```python
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](mailto:rohan@block.science)
* **Organization:** [BlockScience](https://block.science/)

### Theoretical Foundation
This codebase is a direct implementation of the research and mathematical frameworks developed by:
* **Dr. Jamsheed Shorish** ([@jshorish](https://github.com/jshorish)) and **Dr. Michael Zargham** ([@mzargham](https://github.com/mzargham)).
* **Key Reference:** [Generalized Dynamical Systems, Part I: Foundations](https://blog.block.science/generalized-dynamical-systems-part-i-foundations-2/) (BlockScience, 2021).

### Architectural Inspiration
The design patterns and structural approach of this library are heavily influenced by the prior work of **Sean McOwen** ([@SeanMcOwen](https://github.com/SeanMcOwen)), specifically:
* [MSML](https://github.com/BlockScience/MSML): For system specification logic.
* [bdp-lib](https://github.com/BlockScience/bdp-lib): For block-data processing architecture.

### Contributors
* **Peter Hacker** ([@phacker3](https://github.com/phacker3)) — Code auditing and review (BlockScience).

### Intellectual Lineage
This project exists within the broader ecosystem of:
* [cadCAD](https://github.com/cadCAD-org/cadCAD): For foundational philosophy in Complex Adaptive Dynamics.
