gds-stockflow

Declarative stock-flow DSL over GDS semantics — system dynamics with formal guarantees.

Table of Contents

• Quick Start
• What is this?
• Architecture
• Elements
• Semantic Type System
• Verification
• Examples
• Status
• Credits & Attribution

Quick Start

pip install gds-stockflow

from stockflow import (
    Stock, Flow, Auxiliary, Converter,
    StockFlowModel, compile_model, compile_to_system, verify,
)

# Declare a simple population model
model = StockFlowModel(
    name="Population",
    stocks=[Stock(name="Population", initial=1000.0)],
    flows=[
        Flow(name="Births", target="Population"),
        Flow(name="Deaths", source="Population"),
    ],
    auxiliaries=[
        Auxiliary(name="Birth Rate", inputs=["Population", "Fertility"]),
        Auxiliary(name="Death Rate", inputs=["Population"]),
    ],
    converters=[Converter(name="Fertility")],
)

# Compile to GDS — produces a real GDSSpec with role blocks, entities, wirings
spec = compile_model(model)
ir = compile_to_system(model)
print(f"{len(ir.blocks)} blocks, {len(ir.wirings)} wirings")

# Verify — domain checks + optional GDS structural checks
report = verify(model, include_gds_checks=True)
print(f"{report.checks_passed}/{report.checks_total} checks passed")

What is this?

gds-stockflow is a domain DSL that compiles stock-flow diagrams to GDS specifications. You declare stocks, flows, auxiliaries, and converters as plain data models — the compiler handles the mapping to GDS role blocks, entities, composition trees, and wirings.

Your declaration                    What the compiler produces
────────────────                    ─────────────────────────
Stock("Population")          →     Mechanism + Entity (state update f + state X)
Flow("Births", target=...)   →     Policy (rate computation g)
Auxiliary("Birth Rate")      →     Policy (decision logic g)
Converter("Fertility")       →     BoundaryAction (exogenous input U)
StockFlowModel(...)          →     GDSSpec + SystemIR (full GDS specification)

Once compiled, all downstream GDS tooling works immediately — canonical projection (h = f ∘ g), semantic checks, SpecQuery dependency analysis, JSON serialization, and gds-viz diagram generation.

Architecture

DSL over GDS

StockFlowModel (user-facing declarations)
       │
       ▼  compile_model()
GDSSpec (entities, blocks, wirings, parameters)
       │
       ▼  compile_to_system()
SystemIR (flat IR for verification + visualization)

No parallel IR stack. The compiler produces a real GDSSpec with real GDS role blocks. This means stock-flow models are first-class GDS citizens — they compose with other GDS models, share the same verification engine, and render with the same visualization tools.

Composition Tree

The compiler builds a tiered composition tree:

(converters |) >> (auxiliaries |) >> (flows |) >> (stock mechanisms |)
    .loop([stock forward_out → auxiliary forward_in])

• Within each tier: parallel composition (|) — independent elements run side-by-side
• Across tiers: sequential composition (>>) — converters feed auxiliaries, auxiliaries feed flows, flows feed stock mechanisms
• Temporal recurrence: .loop() — stock levels at timestep t feed back to auxiliaries at timestep t+1

Elements

Four declaration types, each mapping to a specific GDS role:

Stock

Stock(name="Population", initial=1000.0, non_negative=True)

GDS mapping: Mechanism (state update f) + Entity (state X)

A stock accumulates value over time. Each stock becomes a GDS entity with a level state variable, and a mechanism block that applies incoming flow rates. Stocks emit a Level port for temporal feedback.

Flow

Flow(name="Births", target="Population")
Flow(name="Deaths", source="Population")
Flow(name="Migration", source="CityA", target="CityB")

GDS mapping: Policy (rate computation g)

A flow transfers value between stocks (or from/to "clouds" — external sources/sinks). Flows with only a target are inflows; flows with only a source are outflows; flows with both transfer between stocks.

Auxiliary

Auxiliary(name="Birth Rate", inputs=["Population", "Fertility"])

GDS mapping: Policy (decision logic g)

An auxiliary computes intermediate values from stocks, converters, or other auxiliaries. Auxiliaries form an acyclic dependency graph — the compiler validates this at construction time.

Converter

Converter(name="Fertility", units="births/person/year")

GDS mapping: BoundaryAction (exogenous input U)

A converter represents an exogenous constant or parameter — a value that enters the system from outside. Converters have no internal inputs.

Semantic Type System

Three distinct semantic spaces, all float-backed but structurally separate — this prevents accidentally wiring a rate where a level is expected:

Verification

Five domain-specific checks validate the stock-flow model structure before compilation:

from stockflow import verify

# Domain checks only
report = verify(model)

# Domain checks + GDS structural checks (G-001..G-006)
report = verify(model, include_gds_checks=True)

Examples

Two tutorial examples in gds-examples demonstrate stock-flow modeling using the GDS framework primitives:

Status

v0.1.0 — Alpha. Complete DSL with 5 verification checks and full GDS compilation. 215 tests.

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.