cyecca
Cymbolic Estimation and Control with Computer Algebra
A lightweight Python library for robotics and control systems using Lie groups and symbolic mathematics with CasADi.
Features
- Lie Group Library: Complete implementations of SO(2), SO(3), SE(2), SE(3), SE_2(3), and R^n groups with multiple parameterizations
- Type-Safe Modeling Framework: Declarative API for building dynamical systems with full IDE autocomplete support
- Hybrid DAE Systems: Support for continuous/discrete states, algebraic constraints, event detection, and quadrature integration
- Symbolic Mathematics: CasADi-SymPy interoperability with Taylor series approximations and expression simplification
- Code Generation: Automatic C code generation from symbolic expressions for embedded systems
- Numerical Integration: RK4, RK8 (DOP853), and Euler integrators with adaptive stepping
- Trajectory Planning: Bezier curve tools for path planning with derivatives up to snap
- Visualization: CasADi expression graph rendering for debugging and documentation
Installation
git clone https://github.com/CogniPilot/cyecca.git
cd cyecca
poetry install
poetry run ./tools/test.sh # optional: run tests
Quick Start
# Lie groups for 3D transformations
import cyecca.lie as lie
import casadi as ca
X = lie.SE3Quat.elem(ca.DM([1, 2, 3, 1, 0, 0, 0])) # position + quaternion
X_inv = X.inverse()
# Type-safe modeling with full autocomplete
from cyecca.dynamics import ModelSX, state, input_var, param, output_var, symbolic
@symbolic
class States:
x: ca.SX = state(1, 1.0, "position") # Start at x=1
v: ca.SX = state(1, 0.0, "velocity")
@symbolic
class Inputs:
F: ca.SX = input_var(desc="force")
@symbolic
class Params:
m: ca.SX = param(1.0, "mass")
c: ca.SX = param(0.1, "damping")
k: ca.SX = param(1.0, "spring constant")
@symbolic
class Outputs:
position: ca.SX = output_var(desc="position output")
velocity: ca.SX = output_var(desc="velocity output")
model = ModelSX.create(States, Inputs, Params, output_type=Outputs)
x, u, p, y = model.x, model.u, model.p, model.y
# Mass-spring-damper: mx'' + cx' + kx = F
f_x = ca.vertcat(x.v, (u.F - p.c * x.v - p.k * x.x) / p.m)
# Output the full state
f_y = ca.vertcat(x.x, x.v)
model.build(f_x=f_x, f_y=f_y, integrator='rk4')
# Simulate free oscillation from x0=1
result = model.simulate(0.0, 10.0, 0.01)
# Output:
# Final position: -0.529209
# Final velocity: 0.323980
# result['out'][0, :] contains position trajectory
# result['out'][1, :] contains velocity trajectory
Documentation
📚 Read the documentation on GitHub Pages
The full documentation includes:
- Installation guide and quick start tutorial
- Comprehensive Lie groups guide with examples
- Modeling framework guide (hybrid systems, DAE, composition)
- Complete API reference (auto-generated from docstrings)
Interactive Examples: See cyecca_notebooks for Jupyter notebooks with tutorials and demonstrations.
Build locally:
cd docs && poetry run make html
# Open docs/_build/html/index.html in your browser
Modules
Lie Groups (cyecca.lie)
Complete implementations of SO(2), SO(3), SE(2), SE(3), SE_2(3), and R^n with multiple parameterizations.
Key features: Group operations, Lie algebra, Jacobians, conversions Learn more: Lie Groups Guide
Dynamics Framework (cyecca.dynamics)
Type-safe declarative API for building hybrid dynamical systems with IDE autocomplete.
Key features: Continuous/discrete states, events, DAE, composition, linearization Learn more: Modeling Guide
Pre-Built Models (cyecca.models)
Ready-to-use dynamics models: quadrotor, fixed-wing aircraft, RDD2 controller, Bezier trajectories
Path Planning (cyecca.planning)
Dubins path planner for fixed-wing aircraft with forward-only, fixed turn radius constraints.
Key features: CasADi-based symbolic planning, RSL/LSR/LSL/RSR path types, branch-free implementation Learn more: Planning Module
Other Modules
- integrators - RK4, RK8 (DOP853), Euler with adaptive stepping
- symbolic - SymPy ↔ CasADi conversion, Taylor series
- codegen - C code generation for embedded systems
- graph - Expression graph visualization
ROS 2 Integration
Launch files for quadrotor and fixed-wing simulation with RViz visualization, joystick control, and trajectory tracking.
ros2 launch cyecca rdd2_sim.xml # Quadrotor simulation
ros2 launch cyecca fixedwing_sim.xml # Fixed-wing simulation
Supported Lie Groups
| Group | Parameters | Use Cases |
|---|---|---|
| R^n | n | State vectors, positions, velocities |
| SO(2) | 1 (angle) | Planar robotics, heading |
| SO(3)Quat | 4 (w,x,y,z) | Attitude estimation, spacecraft control |
| SO(3)EulerB321 | 3 (ψ,θ,φ) | Aircraft dynamics, human-readable angles |
| SO(3)Mrp | 3 | Singularity-free attitude control |
| SE(2) | 3 (x,y,θ) | Mobile robots, 2D localization |
| SE(3)Quat | 7 (pos+quat) | Manipulators, 3D SLAM |
| SE_2(3) | 10 (p+v+quat) | IMU preintegration, VIO |
Dependencies
Core dependencies (automatically installed):
- casadi: Symbolic framework and optimization
- numpy: Numerical computing
- scipy: Scientific computing
- sympy: Symbolic mathematics
- beartype: Runtime type checking
- pydot: Graph visualization
Development
The library is actively used in CogniPilot projects for:
- Flight control system design
- Trajectory optimization
- State estimation
- Hardware-in-the-loop simulation
License
See LICENSE file for details.
Citation
If you use cyecca in your research, please cite:
@software{cyecca,
title = {cyecca: Symbolic Estimation and Control with Computer Algebra},
author = {Goppert, James and Lin, Li-Yu and Kmetko, Alex and others},
organization = {CogniPilot},
url = {https://github.com/CogniPilot/cyecca},
year = {2025}
}
Metadata
Release files for cyecca 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cyecca-0.3.0.tar.gz | 78.0 kB | Without provenance | Details for cyecca-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cyecca-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for cyecca-0.3.0-py3-none-any.whl |
Total release size: 171.2 kB
Release files / cyecca-0.3.0.tar.gz
| Download URL | cyecca-0.3.0.tar.gz |
|---|---|
| Size | 78.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b7e9e0fe099f7288b2b004b97e60faecdd74ce12d83b48befb748777fa09789e
|
|
BLAKE2b-256 checksum How to use checksums |
ee777967361b0ece0fa7f1470e2eed39ac3f6c5e6261d3dce4d8d78c9080cb0b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.12.3 Linux/6.14.0-36-generic
|
Release files / cyecca-0.3.0-py3-none-any.whl
| Download URL | cyecca-0.3.0-py3-none-any.whl |
|---|---|
| Size | 93.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd9148f71ac33ff49154d20908458d5d0497fab7d8b5cfded1314f4ac2e9d329
|
|
BLAKE2b-256 checksum How to use checksums |
4b8321d1792c1d6913a6fc8945885a2ed8d47484e2db6535f36ef770424740cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.12.3 Linux/6.14.0-36-generic
|
Security for cyecca 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.