SympLie

SympLie is an experimental JAX package for simulating and differentiating controlled rigid-body attitude dynamics on $SO(3)$. Its core is a Moser–Veselov variational integrator for rotational motion.

It currently provides:

• Torque-free and forced Moser–Veselov integration, including a composable step for custom JAX scans and zero-order-hold control loops.
• The $SO(3)$ maps, invariant diagnostics, and nonlinear-solver diagnostics needed to use and inspect that step.
• Geometric attitude stabilization and trajectory tracking.
• Gyroscope attitude propagation with optional bias compensation.
• Batched geometry, JIT compilation, and automatic differentiation.

Installation

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

For tests and figure generation:

python -m pip install -e ".[dev]"
pytest

Optional CUDA support

The default installation uses CPU-backed JAX. To use a CUDA backend instead, install the matching JAX package:

python -m pip install --upgrade "jax[cuda13]"
python -c 'import jax; print(jax.devices()); assert jax.default_backend() == "gpu"'

Use jax[cuda12] when required by the installed driver or CUDA installation. Consult the JAX installation guide for current compatibility requirements. The test suite uses the active JAX backend.

Quickstart

import jax.numpy as jnp
from symplie import rigid_body_step

J = jnp.diag(jnp.array([0.6, 1.0, 1.8]))
R = jnp.eye(3)
pi = jnp.array([0.2, 0.7, 1.0])
torque = jnp.array([0.01, -0.02, 0.03])

R_next, pi_next, info = rigid_body_step(
    R,
    pi,
    J,
    torque,
    torque,
    dt=0.01,
)
assert info.converged, info.residual_norm

rigid_body_step advances attitude and body angular momentum by one forced timestep and reports whether its nonlinear solve converged.

The closed-loop examples demonstrate fixed-target stabilization and smooth attitude trajectory tracking:

python examples/attitude_stabilization.py
python examples/attitude_tracking.py

Documentation

The documentation covers installation, frame and torque-sampling conventions, numerical validation, and the complete public API.

Scope

SympLie deliberately focuses on rotational dynamics and control; it is not a replacement for jaxlie, Sophus, Drake, or Pinocchio. It does not implement translation, full $SE(3)$ rigid-body dynamics, contact, constraints, actuator allocation, state estimation, or robotics middleware. The package includes $SE(3)$ exponential and logarithm utilities, but they are not part of its dynamics model.