gds-core

Monorepo for the Generalized Dynamical Systems ecosystem — typed compositional specifications for complex systems, grounded in GDS theory (Zargham & Shorish, 2022).

Packages

Package	PyPI	Description
gds-framework		Core engine — blocks, composition algebra, compiler, verification
gds-viz		Mermaid diagram renderers for GDS specifications
gds-games		Typed DSL for compositional game theory (Open Games)
gds-examples		Six tutorial models demonstrating every framework feature

Quick Start

# Clone and install all packages (editable, workspace-linked)
git clone https://github.com/BlockScience/gds-core.git
cd gds-core
uv sync --all-packages

# Run tests for a specific package
uv run --package gds-framework pytest packages/gds-framework/tests -v

# Run all tests
uv run --package gds-framework pytest packages/gds-framework/tests packages/gds-viz/tests packages/gds-games/tests packages/gds-examples -v

# Lint & format
uv run ruff check packages/
uv run ruff format --check packages/

Development

This is a uv workspace monorepo. All four packages are developed together with shared tooling:

• Linting/formatting: Ruff (configured at root, line-length 88)
• Testing: pytest per-package
• Docs: Unified MkDocs Material site
• CI: GitHub Actions matrix across all packages
• Publishing: Tag-based per-package PyPI publishing (gds-framework/v0.3.1)

Documentation

Full documentation at blockscience.github.io/gds-core.

Citation

If you use GDS in your research, please cite:

M. Zargham & J. Shorish, "Generalized Dynamical Systems," 2022. DOI: 10.57938/e8d456ea-d975-4111-ac41-052ce73cb0cc

See CITATION.cff for BibTeX and other formats.

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.

License

Apache-2.0 — see LICENSE.