How sandeep026/simulatetraj works
Project type & purpose (what you’re diagramming)
This is a Python library (not a service/app) named simulatetraj whose purpose is to simulate/propagate ODE initial value problems (IVPs) for systems of the form:
\[
\dot{x}=f(x,u,t,p)
\]
It uses CasADi as the computational/symbolic backend and leverages SUNDIALS/CVODES (via CasADi’s integrator interface) for adaptive numerical integration. It also supports creating symbolic trajectories to embed into nonlinear optimization expression graphs (multiple shooting reuse is explicitly mentioned).
File structure analysis (what maps to components)
Key folders/files:
• simulatetraj/
• __init__.py → package surface / exports
• simulate.py → the core implementation (this is almost certainly where simulatetraj function/class lives)
• tests/
• test.py → verification harness; helps infer public API usage patterns
• doc/source/ + doc/build/
• Sphinx + notebooks (examples/*.ipynb) describe expected usage and architecture concepts (symbolic, optimization)
• pyproject.toml
• packaging + dependencies (Poetry); indicates library distribution
• dist/
• built wheels/tarballs (release artifacts)
This strongly suggests a single-module core (simulate.py) with docs/examples/tests around it.
README architecture cues (what must appear
From the README:
• Inputs: \(x_0\), \(u(t)\), \(t_0,t_f\), parameters \(p\), dynamics \(f(\cdot)\)
• Backend: CasADi integrator supporting RK4, IRK, CVODES
• Supports symbolic objects → produces symbolic trajectory nodes usable in CasADi graphs
• Internal step: time normalization from \([t_0,t_f]\) to \([0,1]\)
• Key optimization: integrator object reuse (important for multiple shooting)
• Dependencies: casadi, numpy, scipy, matplotlib (matplotlib likely used in examples/docs rather than core)
User / Client Code
• Python scripts, notebooks, or optimization code using the library
• Source: doc/source/examples/*.ipynb, user code implied by README
simulatetraj Public API
• Likely simulatetraj.simulate or simulatetraj.simulatetraj function exported via __init__.py
• Source: simulatetraj/__init__.py
Core Simulation Module
• simulatetraj/simulate.py
• argument validation & shaping
• building CasADi expressions/functions for \(f\)
• time-domain normalization \([t_0,t_f]\to[0,1]\)
• integrator creation/configuration (RK4/IRK/CVODES)
• integrator reuse/caching strategy (if present)
• running numeric integration vs building symbolic trajectory outputs
CasADi Engine
• Symbolic graph construction (MX/SX)
• Integrator API (integrator(...))
• Acts as a gateway to numeric solvers
SUNDIALS/CVODES (external native solver)
• Only when using CVODES modes; show as an external dependency behind CasADi
Outputs
• Numeric: arrays/trajectories (numpy arrays likely)
• Symbolic: CasADi expressions usable in NLP/multiple shooting
Docs/Examples/Test Harness (secondary components)
• doc/source/* as “reference usage + validation”
• tests/test.py as “CI-style verification”
• Packaging/Distribution: pyproject.toml → build → dist/*.whl
• Plotting: matplotlib used by examples (not core)
• User Code → imports → simulatetraj (API)
• simulatetraj (API) → calls → simulate.py
• simulate.py → depends on → CasADi
• CasADi → uses → CVODES (only for that integrator choice)
• simulate.py → depends on → numpy/scipy (if used for data shaping/interpolation; verify in simulate.py)
• Examples/Docs → depend on → matplotlib
Major pipeline:
Inputs
• \(x_0\), \(u(t)\), \(p\), \(t_0,t_f\), dynamics \(f\)
Flow
Integrator executes
• purely in CasADi numeric backend, or
• delegates to CVODES for adaptive integration
Returns
• numeric trajectory samples
• and/or symbolic representation of the trajectory
Important architectural patterns/design principles
For this project, emphasize:
Facade API over a heavy backend
• A thin public API wrapping CasADi complexity.
Backend strategy (pluggable integrator methods)
• “method = RK4/IRK/CVODES → choose backend config”
Symbolic + numeric dual-mode
• The same function can yield numeric results or symbolic graphs (important to show explicitly).
Performance optimization: integrator reuse
• Caching/pooling of integrator objects for multiple shooting.
Relevant technologies
• Python package: simulatetraj
• Symbolic + integrator interface: CasADi
• Adaptive ODE solver: SUNDIALS CVODES (native)
• Array handling: NumPy
• Optional utilities: SciPy (interpolation, etc. if present), Matplotlib (examples)
Top row (Actors)
• User Script / Notebook / NLP (multiple shooting)
Middle row (Library)
• simulatetraj API (__init__.py)
• simulate.py Core
Bottom row (Backends)
• CasADi (symbolic graph + integrator interface)
• CVODES (adaptive integration, via CasADi)
• NumPy/SciPy (array utilities / interpolation if used)
Right side (Outputs)
• Numeric trajectory arrays
• Symbolic trajectory expressions (CasADi graph nodes)
Before finalizing, quickly open:
• simulatetraj/simulate.py: confirm
• function names / public entrypoints
• whether integrator caching exists and how (module-level cache? class instance? user-passed integrator?)
• how u(t) is represented (callable? piecewise constant? interpolant?)
• output format (dict? arrays? CasADi DM/MX?)
• tests/test.py: confirm the canonical usage and expected outputs
• doc/source/examples/*.ipynb: confirm typical workflows (multiple shooting, optimization embedding)