gds-symbolic¶

SymPy bridge for gds-control -- symbolic state equations, automatic linearization, and ODE code generation.

Package Identity¶

Distribution	Import	Role
`gds-symbolic`	`gds_domains.symbolic`	SymPy bridge for `gds-control` models
`gds-domains`	`gds_domains.symbolic`	Consolidated domain package distribution

What is this?¶

gds-symbolic extends gds-control's ControlModel with symbolic mathematics. Instead of writing numerical right-hand side functions by hand, you declare state and output equations as symbolic expressions and let the compiler do the rest.

StateEquation -- symbolic expression for dx/dt (e.g., "-k * x + b * u")
OutputEquation -- symbolic expression for sensor output y (e.g., "x + noise")
compile_to_ode() -- lambdifies symbolic equations into a callable ODEFunction compatible with gds-continuous
linearize() -- computes Jacobian matrices (A, B, C, D) at an operating point
Safe expression parsing -- uses sympy.parsing.sympy_parser.parse_expr, never eval

When to Use It¶

Use gds-symbolic when a control model's dynamics should be specified as symbolic equations and then linearized or compiled to ODE functions. Use gds-control alone when numerical callables are enough.

Architecture¶

gds-control (pip install gds-domains)
|
|  State-space control DSL: State, Input, Sensor, Controller.
|
+-- gds-symbolic (uv add gds-symbolic[sympy])
    |
    |  Symbolic layer: StateEquation, OutputEquation,
    |  compile_to_ode(), linearize().
    |
    +-- gds-continuous (optional integration)
        |
        |  ODE simulation engine: ODEModel, ODESimulation.

Key Types¶

Type	Purpose
`StateEquation`	Symbolic `dx_i/dt = expr(x, u, params)`
`OutputEquation`	Symbolic `y_i = expr(x, u, params)`
`SymbolicControlModel`	Extends `ControlModel` with symbolic equations
`ODEFunction`	Lambdified callable: `f(t, x, params) -> dx/dt`
`LinearSystem`	Matrices `(A, B, C, D)` from Jacobian linearization

How It Works¶

Symbolic expressions (strings)
    |
    v
parse_expr()  -->  SymPy Expr objects
    |
    v
compile_to_ode()  -->  ODEFunction (lambdified, numpy-backed)
    |                       |
    v                       v
linearize()           gds-continuous ODEModel
    |
    v
LinearSystem(A, B, C, D)   -->  eigenvalue analysis, controllability, etc.

All expression parsing uses sympy.parsing.sympy_parser.parse_expr with a restricted transformation set -- arbitrary code execution is not possible.

Quick Start¶

uv add "gds-symbolic[sympy]"

See Getting Started for a full walkthrough.

Relationship to the Ecosystem¶

gds-symbolic sits between the control DSL and continuous-time simulation. It extends gds-control models with SymPy expressions and can produce ODE functions for gds-continuous.

Credits¶

Built on gds-control by DynamicalSystemsGroup.