gds-framework

Typed compositional specifications for complex systems, grounded in Generalized Dynamical Systems theory (Zargham & Shorish, 2022).

Package Identity

Distribution	Import	Role
gds-framework	gds	Core specification, composition, compilation, and structural verification

What is this?

gds-framework is a foundation layer for specifying dynamical systems as compositions of typed blocks. It provides the domain-neutral primitives — you bring the domain knowledge.

gds-framework                          Your domain package
─────────────────                       ──────────────────
Block, Interface, Port                  PredatorBlock, PreyBlock
>> | .feedback() .loop()                predator >> prey >> environment
TypeDef, Space, Entity                  Population(int, ≥0), EcosystemState
GDSSpec, verify()                       check_conservation(), check_stability()
compile_system() → SystemIR             visualize(), simulate()

gds-framework defines specifications and verifies their structure. It does not directly execute trajectories; simulation lives in separate runtime and analysis packages. See Relationship to Simulation and Analysis.

A Generalized Dynamical System is a pair {h, X} where X is a state space and h: X → X is a state transition map. The GDS canonical form decomposes h into a pipeline of typed blocks — observations, decisions, and state updates — that compose via wiring:

GDS concept	Paper notation	gds-framework
State Space	X	Entity with StateVariables
Exogenous observation	g(·)	BoundaryAction
Decision / policy	g: X → U_x	Policy
State update	f: X × U_x → X	Mechanism
Admissible input constraint	U: X → ℘(U)	ControlAction
Transition map	h = f|_x ∘ g	Composed wiring (>>)
Trajectory	x₀, x₁, ...	Temporal loop (.loop())

When to Use It

Use gds-framework when you need to define the structure of a system, verify typed composition, compile to GDS IR, or declare canonical GDS roles. Use a domain DSL when you want a more compact vocabulary for stock-flow, control, game, software, or business models.

Quick Start

pip install gds-framework

from gds import (
    BoundaryAction, Policy, ControlAction,
    interface, Wiring,
    compile_system, verify,
)
from gds.ir.models import FlowDirection

# Define blocks with GDS roles and typed interfaces
sensor = BoundaryAction(
    name="Temperature Sensor",
    interface=interface(forward_out=["Temperature"]),
)
controller = Policy(
    name="PID Controller",
    interface=interface(
        forward_in=["Temperature", "Setpoint"],
        forward_out=["Heater Command"],
        backward_in=["Energy Cost"],
    ),
)
plant = ControlAction(
    name="Room",
    interface=interface(
        forward_in=["Heater Command"],
        forward_out=["Temperature"],
        backward_out=["Energy Cost"],
    ),
)

# Compose with operators — types checked at construction time
system = (sensor >> controller >> plant).feedback([
    Wiring(
        source_block="Room", source_port="Energy Cost",
        target_block="PID Controller", target_port="Energy Cost",
        direction=FlowDirection.CONTRAVARIANT,
    )
])

# Compile to flat IR and verify
ir = compile_system("Thermostat", system)
report = verify(ir)
print(f"{len(ir.blocks)} blocks, {len(ir.wirings)} wirings")
# 3 blocks, 3 wirings
print(f"{report.checks_passed}/{report.checks_total} checks passed")
# 13/14 checks passed (G-002 flags BoundaryAction for having no inputs — expected)

What's Included

Layer 1 — Composition Algebra: Blocks with bidirectional typed interfaces, composed via four operators (>>, |, .feedback(), .loop()). A 3-stage compiler flattens composition trees into flat IR. Six generic verification checks validate structural properties.

Layer 2 — Specification Layer: TypeDef with runtime constraints, typed Spaces, Entity with StateVariables, block roles (BoundaryAction, Policy, Mechanism, ControlAction), GDSSpec registry, ParameterSchema for configuration space Θ, CanonicalGDS projection deriving the formal h = f ∘ g decomposition, Tagged mixin for inert semantic annotations, semantic verification (completeness, determinism, reachability, type safety, parameter references, canonical wellformedness), SpecQuery for dependency analysis, and JSON serialization.

Relationship to Simulation and Analysis

gds-framework is the specification and verification foundation. It defines typed blocks, interfaces, state spaces, parameters, canonical structure, and structural checks. Runtime behavior is handled by packages above or beside the framework:

Goal	Package
Run standalone discrete-time simulations	gds-sim
Run continuous-time ODE simulations	gds-continuous
Bridge GDSSpec structures into simulation workflows	gds-analysis
Sweep parameters, optimize KPIs, and run sensitivity analysis	gds_analysis.psuu

For the full package map, see Packages. For the runtime path specifically, see Simulation & Analysis.

Status

Alpha. The composition algebra and specification layer are implemented and tested. Domain DSLs, visualization, interchange, simulation, and analysis now live in separate packages in the GDS ecosystem; gds-framework remains the domain-neutral foundation they build on.

Credits

Author: Rohan Mehta — DynamicalSystemsGroup

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 (DynamicalSystemsGroup).
• Peter Hacker — Code auditing and review (DynamicalSystemsGroup).

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