tsdynamics 4.0.0

Zero-warmup Rust-engine ODE/DDE/SDE integration, discrete maps, and chaos analysis for dynamical systems.

TSDynamics

Dynamical systems in Python: 149 built-in systems, a native Rust integration engine, and chaos analysis — with the simplest system-definition contract anywhere.

You write the math (one symbolic method); TSDynamics lowers it to a native Rust engine and handles integration, Lyapunov spectra, bifurcation diagrams, Poincaré sections, and even the documentation page for your system.

import tsdynamics as ts

lor = ts.Lorenz()
traj = lor.integrate(final_time=100.0, dt=0.01)
traj["x"]                              # named component access
lor.lyapunov_spectrum()                # → [0.91, ~0, -14.57]
ts.kaplan_yorke_dimension(_)           # → ~2.06

📖 Documentation: https://el3ssar.github.io/TSDynamics/

---

Highlights

• Three families, one interface — ODEs, delay-differential equations (including DDE Lyapunov spectra), and discrete maps, all running on the same native Rust engine. All implement one stepping protocol, so every analysis tool works on every system.
• 149 built-in systems with literature parameters: Lorenz, Rössler, Chua, 21 Sprott flows, Mackey–Glass, Hénon, ... each with an auto-generated docs page showing its equations and attractor.
• Native engine, zero warmup — equations lower to a Rust engine (an SSA-tape interpreter, with a Cranelift JIT alongside) in-process; parameters are runtime control values, so changing them is free and there is no compile step or cache.
• Composition — a PoincareMap of a flow is a discrete map, so orbit_diagram(PoincareMap(Rossler(), (1, 0.0)), "c", values) draws the bifurcation diagram of a flow with one line.
• Analysis toolkit — orbit/bifurcation diagrams, Poincaré sections (root-refined), maximal Lyapunov exponent without Jacobians, Kaplan–Yorke dimension, fixed points with stability.

Install

pip install tsdynamics            # or: uv add tsdynamics

A prebuilt abi3 wheel (manylinux / musllinux / macOS / Windows) bundles the native Rust engine, so no Rust toolchain and no C compiler are needed to install or run. Building from the sdist needs a Rust toolchain (the build backend is maturin).

Optional extra: tsdynamics[plot] (matplotlib).

Define your own system

import tsdynamics as ts

class MySystem(ts.ContinuousSystem):
    params = {"a": 0.2, "b": 0.2, "c": 5.7}
    dim = 3
    variables = ("x", "y", "z")            # optional niceties

    @staticmethod
    def _equations(y, t, *, a, b, c):
        x, yv, z = y(0), y(1), y(2)
        return (-yv - z, x + a * yv, b + z * (x - c))

That's the whole contract. The class auto-registers: the bulk test-suite sweeps it, and the docs build renders its equations (LaTeX, straight from the symbolics) and its attractor figure — zero extra steps. Delay systems use y(0, t - tau); maps implement _step/_jacobian (signature order is validated at import).

A taste of the analysis layer

import numpy as np
import tsdynamics as ts

# Bifurcation diagram of the logistic map
od = ts.orbit_diagram(ts.Logistic(), "r", np.linspace(2.5, 4.0, 600))
x, y = od.flat()

# Poincaré section of the Rössler attractor (root-refined crossings)
section = ts.poincare_section(ts.Rossler(), plane=(1, 0.0), n=500)

# Fixed points of the Hénon map, with stability
ts.fixed_points(ts.Henon())
# [FixedPoint([-1.131354  -0.339406], unstable, ...),
#  FixedPoint([ 0.631354   0.189406], unstable, ...)]

# Maximal Lyapunov exponent, no Jacobian needed
ts.max_lyapunov(ts.Lorenz(ic=[1, 1, 1]), dt=0.05)    # ≈ 0.91

Development

git clone https://github.com/El3ssar/TSDynamics && cd TSDynamics
uv sync --group dev --group docs
uv run pytest -m "not slow" --no-cov     # fast tier
uv run pytest --no-cov                   # full local suite
TSD_DOCS_FIGURES=0 uv run mkdocs serve   # docs preview

Releases are automated: conventional-commit PR titles drive semantic-release on merge — see CONTRIBUTING.

License

MIT © Daniel Estevez