Open source · Dynamical Systems Group
GDS Core
A typed Python framework for turning domain knowledge into composable system specifications—and carrying those specifications from discovery and design into diagrams, executable scaffolds, simulation, and scenario analysis.
- My role
- Author and maintainer
- Status
- Alpha · Active
- Language
- Python
- License
- Apache-2.0
Motivation
Why I built it
I wanted to capture model-based systems engineering in a typed Python framework that I could use to enter unfamiliar domains, make their structure explicit, and compare them without flattening away what made each domain distinct.
Complex systems are usually described in disconnected artefacts: interviews, requirements, diagrams, equations, spreadsheets, simulation code, and domain-specific notation. Each artefact captures a useful view, but the relationships between them are often maintained by hand. The model described in a workshop drifts from the diagram, the diagram drifts from the code, and the code eventually becomes the only representation precise enough to execute but too implementation-specific to reason about.
GDS Core is an attempt to create a stable middle layer. A system is expressed as typed entities, state, interfaces, blocks, and composition rules. That specification is precise enough to verify and compile, but remains independent of any one simulator, diagram, or domain vocabulary.
The longer arc
From discovery to scenario analysis
The goal is not only a modeling library. It is a continuous pipeline in which each stage preserves enough structure for the next one to be generated, checked, or revised.
- 01Discover
Capture actors, boundaries, state, decisions, constraints, and feedback from domain experts and existing artefacts.
- 02Design
Turn observations into explicit entities, interfaces, mechanisms, policies, and system boundaries.
- 03Specify
Encode the design as typed compositional Python with constraints that can be checked before execution.
- 04Generate
Derive diagrams, intermediate representations, documentation, and code scaffolds from the same specification.
- 05Execute
Connect the specification to discrete or continuous simulation runtimes and cadCAD-style workflows.
- 06Explore
Run parameter sweeps, uncertainty analysis, optimization, and scenario comparison through PSUU.
Parts of this pipeline exist today across the GDS package ecosystem; others remain an active direction. The important commitment is that discovery, design, diagrams, code, and analysis should share a traceable structural source rather than becoming separate models that drift apart.
The core idea
A specification before a simulation
GDS separates two questions that modeling tools often collapse: is this system coherently specified? and what happens when this system runs?
The framework layer answers the first question. It defines typed blocks, interfaces, spaces, entities, state variables, parameters, and composition. It can reject incompatible wiring, compile a model into a common intermediate representation, and run structural checks without choosing how time advances.
Execution belongs to separate runtimes. A discrete simulator, an ODE solver, a parameter-search tool, or a domain-specific analysis package can consume the specification without redefining its structure. This separation lets the same model support multiple forms of analysis while keeping the assumptions visible.
Names carry constraints and compatible interfaces, not only labels.
Small blocks can be wired, placed in parallel, closed through feedback, and reused.
Structural errors can be found before simulation or generated code hides them.
The specification describes the system without committing it to one execution engine.
Generalization
Different fields, recurring structures
The point is not to pretend that every discipline is the same. It is to make recurring structural ideas comparable while preserving domain-specific language and checks.
| Domain | Native concepts | Shared structural questions |
|---|---|---|
| Systems engineering | Requirements, components, interfaces, verification | What exists, how is it connected, and what must remain true? |
| Control systems | Plant, controller, observations, actions, feedback | What state is observed, what acts on it, and how does the loop close? |
| Game theory | Players, strategies, information, payoffs | Who decides, what can they observe, and how do choices compose? |
| Business dynamics | Stocks, flows, policies, delays, incentives | What accumulates, what changes it, and where does feedback create behavior? |
Domain packages provide the familiar vocabulary. The shared framework provides composition, compilation, verification, and interchange beneath it. That makes it possible to look for generalizations without forcing every model into the notation of a single field.
What exists today
An ecosystem rather than one package
gds-framework provides the domain-neutral specification layer. Domain packages cover control systems, games, stock-flow models, software architecture, business dynamics, and symbolic mathematics. Other packages generate diagrams, export formal representations, execute discrete and continuous simulations, bridge specifications into analysis workflows, and run reachability or parameter studies.
The split is deliberate. A domain model should be able to evolve without pulling an entire simulation stack into the core, and a runtime should be replaceable without rewriting the model's conceptual structure.
Lineage
Built on Generalized Dynamical Systems
I wrote and maintain the GDS Core codebase, translating the formal ideas into typed Python, composition operators, compilers, verification, domain-specific languages, visualization, and analysis tooling.
The theoretical foundation is Generalized Dynamical Systems, developed by Dr. Michael Zargham and Dr. Jamsheed Shorish. I built the implementation with their guidance through the Dynamical Systems Group. The theory supplies the formal basis; this project is my attempt to turn it into an engineering environment that can be used across domains.