minilink

Write the equations once.
Simulate, analyze, control, plan, optimize, learn.

A unified Python framework for dynamical systems and control. One differentiable backbone connecting classical frequency design, trajectory optimization, and GPU-accelerated learning.

Alexandre Girard

The Fragmented Landscape

Dynamical systems and control engineering are split across isolated software silos
The Core Problem: Engineers rewrite the same physical dynamics $\dot{x} = f(x,u,t;p)$ across three incompatible tools, breaking continuity between education, optimization, and research.
Classical Control
  • Tools: MATLAB Control Toolbox, Simulink
  • Focus: Transfer functions, Bode, root locus, PID, state space
  • Friction: Proprietary binary .slx files, per-seat licenses, no autodiff
MATLAB & Simulink Script & Binary Model
G = tf(1, [m, b, k]); sim('plant.slx'); % Proprietary binary block
Trajectory Optimization
  • Tools: CasADi, Drake
  • Focus: Direct collocation, shooting, LQR, NLP transcriptions
  • Friction: Distinct symbolic graphs, steep learning curve, no frequency design
CasADi Symbolic Graph
xdot = vertcat(v, (u - b*v - k*p)/m); f = Function('f', [x, u], [xdot]);
Learning & Co-Design
  • Tools: Gymnasium, Stable-Baselines3, PyTorch
  • Focus: RL (PPO/SAC) & plant-controller co-design ($\theta \in \mathbb{R}^p$)
  • Friction: Discrete step functions, black-box physics, no stability certificates
Gymnasium Discrete Step Loop
def step(self, u): return self.x + dt*f(x, u), r, done, {}

The Minilink Backbone

Three foundations (System, PlanningProblem, MathematicalProgram) connecting all analytical and synthesis lanes
Minilink Architecture Pipeline Map

Continuous Core & Functional Purity

Equations are pure mathematical maps: arrays in, arrays out
$$\dot{x} = f(x, u, t; p)$$ $$y = h(x, u, t; p)$$ $$T = \mathrm{tf}(x, u, t; p)$$
Why Functional Purity?
  • Pure Array Maps: Stateless mathematical mappings ($x, u, t \to \dot{x}$). No simulation time cached on self.
  • Classroom-Ready NumPy Default: Pure NumPy/SciPy by default; zero compiler or GPU hurdles for undergraduate control courses.
  • Extensible Leaf Wrapping: Easily wrap legacy C/Python simulators, hardware sensors, or custom dynamics as a System leaf.
  • JAX Compilation Ready: Purity unlocks immediate JIT compilation, machine-precision sensitivities, and GPU batches.
mass_spring_damper.py NumPy / JAX
import numpy as np from minilink import DynamicSystem class MassSpringDamper(DynamicSystem): def __init__(self): super().__init__(n=2, input_dim=1, output_dim=1) def f(self, x, u, t=0, params=None): m, k, b = 1.0, 4.0, 0.3 p, v = x a = (u[0] - b * v - k * p) / m return np.array([v, a]) def h(self, x, u, t=0, params=None): return np.array([x[0]]) plant = MassSpringDamper() plant.x0[0] = 1.0 plant.compute_trajectory(tf=10.0) plant.plot_trajectory()

Compositional Closure: Diagrams as Systems

Pure Python replaces drag-and-drop GUIs; diagrams are auto-generated read-only inspections
READ-ONLY VISUAL INSPECTION (plot_diagram()) NO DRAG-AND-DROP GUI • CODE IS THE SINGLE SOURCE OF TRUTH
Closed Loop Diagram
Code as Single Source of Truth
  • No Drag-and-Drop Tax: Replaces Simulink's mouse-driven wiring and opaque binary .slx files with pure, version-controlled Python expressions.
  • Expressive Shortcuts: Common topologies wire instantly: C >> G (series), A + B (parallel), C @ G (feedback), sys % Δ ($ZOH$ digital clock sampling).
  • Explicit 1-Line Wiring: Canonical diag.connect(src, port, dst, port) and disconnect() wire arbitrary multi-loop networks with immediate port checks.
  • Full Syllabus Analysis: Closed loops analyze directly via bode(), nyquist(), root_locus(), linearize(), and state-space kalman().
  • Headless CI/CD & Testing: Runs natively in automated Linux Docker containers and GitHub Actions with zero display servers or license seat fees.
closed_loop_wiring.py Shortcuts & Explicit Connections
from minilink import DiagramSystem, PID, MassSpringDamper plant = MassSpringDamper() ctrl = PID(kp=10.0, ki=1.0, kd=2.0) # Option A: Expressive algebraic shortcut ('@' feedback) loop = ctrl @ plant # Option B: Explicit 1-line wiring (replaces Simulink GUI) diag = DiagramSystem() diag.add_subsystem(plant, "plant") diag.add_subsystem(ctrl, "controller") diag.connect("controller", "u", "plant", "u") diag.connect("plant", "y", "controller", "e") # Auto-generate read-only diagram for visual audit loop.plot_diagram()

Interactive Play & 3D Visualization

Real-time wall-clock simulation and hardware-accelerated 3D WebGL rendering
Wall-Clock Play & 3D Kinematics
  • Wall-Clock Play & 1 kHz Pacing: plant.game() drives plants with keyboard/gamepad (via pygame), or paces hardware-in-the-loop testbeds in real-time.
  • Multi-DoF Robotics Catalog: Built-in kinematic and dynamic models for industrial manipulators (UR-5), ground vehicles (Racecar MPC), and drones.
  • Declarative Geometry: $T = \mathrm{tf}(x, u, t; p)$ describes body poses; dynamics remain free of rendering loops.
  • MeshCat 3D WebGL: Hardware-accelerated interactive 3D rendering with orbit/pan controls right in the browser.
visualization_and_play.py Game & MeshCat
# Real-time wall-clock play with keyboard plant.game() # Interactive 3D WebGL animation via MeshCat plant.animate(traj, renderer="meshcat")
Interactive 3D WebGL Preview

Differentiable & Accelerated with JAX

Exact analytical derivatives, parallel GPU batches, and gradient-based tuning
$$A = \frac{\partial f}{\partial x}, \quad B = \frac{\partial f}{\partial u}, \quad S_p = \frac{\partial f}{\partial p}$$ $$\nabla_\theta J = \frac{\partial}{\partial \theta} \left[ \int_0^{t_f} g(x, u, t)\, dt + h(x(t_f)) \right]$$
  • Numerical Rigor: Machine-precision analytical sensitivities eliminate finite-difference approximation noise; float64 default verified against analytical baselines.
  • Opt-In Acceleration: Pure NumPy remains the default classroom engine; JAX activates with a single flag (backend="jax") for advanced research.
  • Parallel Batched Rollouts: Hardware-accelerated GPU/TPU rollouts over parameter families via JAX vmap.
  • Plant & Controller Co-Design: Exact gradient descent ($\nabla_\theta J$) optimizes feedback gains and physical plant parameters simultaneously.
jax_acceleration.py Core Verbs
# JAX compilation and exact sensitivities ev = plant.compile(backend="jax") A = plant.jacobian("f", "x", x_eq) S = plant.jacobian("f", "params", x_eq) # Vectorized rollouts over parameter batches xs = ev.rollout_batch(x0s, n_steps=1000, dt=0.005, params=p_batch) # Closed-loop gradient descent on gains and physical parameters dJ = jax.grad(lambda p: pe.evaluate(p).objective)(pe.params) best = Optimizer(pe.program(wrt=["controller.Kp", "plant.m"])).solve()

The Unified Optimization Boundary

A standardized interface connecting all transcriptions to plug-and-play solvers
$$\min_z \quad J(z; p) \quad \text{s.t.} \quad g(z; p) \le 0, \quad h(z; p) = 0$$
Lego-Block Inter-Compatibility
  • Lower Late: Trajectory collocation, parameter tuning, and policy search all lower to one standard MathematicalProgram.
  • Decoupled Solvers: Problem definitions and solvers are independent Lego blocks. Any solver runs on any program.
  • Pluggable Backends:
    • Gradient / Autodiff: gd, adam, l-bfgs (JAX)
    • Constrained NLP: SciPy (SLSQP), Ipopt (interior-point)
    • Native fixed-step solvers & custom user algorithms
optimization_interface.py MathematicalProgram & Optimizer
from minilink import Optimizer # Any problem lowers to a MathematicalProgram program = problem_evaluator.program(wrt=["controller.Kp", "plant.m"]) # Switch solvers with a single keyword: # method="auto", "adam", "l-bfgs", "slsqp", or "ipopt" opt = Optimizer(program, method="auto") result = opt.solve() # Optimal decision vector and convergence summary print(result.success, result.x, result.fun)

One Problem, Every Planner

A universal optimal control specification solved across paradigms
$$\min_{u(t)} \quad J = \int_0^{t_f} g(x, u, t; p)\, dt + h(x(t_f); p)$$ $$\text{s.t.} \quad \dot{x} = f(x, u, t; p), \quad x(0) = x_0$$ $$x(t) \in X, \quad u(t) \in U, \quad x(t_f) \in X_f$$
  • Unified Formulation: DP, Trajectory Optimization, RRT, and Deep RL solve the exact same mathematical problem.
  • Neural Policies as Systems: A trained neural network policy (NeuralPolicy / MLP) is a standard System: loop = policy @ plant.
  • Objective Benchmarking: Single compare() function evaluates open-loop trajectories, state-feedback, and neural policies on the identical task.
universal_planning.py Clean Problem & Solvers
# One problem definition problem = PlanningProblem(sys=plant, x_start=x0, Xf=Xf, cost=cost) # Solved by value iteration, collocation, or RL vi_sol = DynamicProgrammingPlanner(problem).solve() opt_sol = TrajectoryOptimizationPlanner(problem).solve() rl_sol = ReinforcementLearningPlanner(problem).solve() # NeuralPolicy # Every solution policy closes the loop: policy @ plant loop = rl_sol.policy @ plant # Evaluate side-by-side on the identical task print(compare(problem, DP=vi_sol, TrajOpt=opt_sol, RL=rl_sol))

How Minilink Compares

Clear architectural trade-offs across common dynamic systems and control frameworks
Capability Minilink MATLAB / Simulink Python-Control CasADi Gymnasium / SB3
Classical Control Yes (Control Toolbox) Yes No No
Optimal Control & Planning Separate add-ons No Yes (NLP solver) No
Autodiff & GPU Rollouts Limited (GPU Coder) No CPU AD PyTorch / JAX tensors
Model Syntax & Workflows Proprietary binary .slx Pure Python Symbolic graph (SX/MX) Step loop
License & Distribution Proprietary (Commercial) Open Source (BSD) Open Source (LGPL) Open Source (MIT)

Honest Boundaries: What Minilink is NOT

Disciplined architectural scope: where Minilink excels vs. where specialized tools belong
1. Not a Contact Engine
  • No rigid-body impulse dynamics, mesh collision, or complementarity solvers
  • Design pattern: Wrap external physics engines (MuJoCo, Drake) as leaf blocks in a diagram
2. Dense vs. Sparse NLP
  • Optimized for small-to-mid DoF systems, fixed-step MPC, and batched rollouts
  • For 100-knot trajectory optimization exploiting sparse block Jacobians, CasADi remains superior
3. Continuous-Time Primary
  • Physical dynamics are instantaneous rates ($\dot{x} = f(x,u)$)
  • Discrete clocks sit cleanly in the sibling step algebra (% operator), but continuous physics is the foundation

Key Advantages

A unified, modern foundation for dynamical systems, control, and optimization
  • One Model Across All Domains: Single equation definition ($\dot{x} = f(x,u,t;p)$) connects classical frequency design, optimal control, and reinforcement learning.
  • Zero-Friction Classroom Adoption: Runs out-of-the-box on standard NumPy and 1-click Google Colab with zero compiler or license hurdles on student laptops.
  • Git-Native Diagrams as Code: Pure Python operator algebra (>>, +, @, %) replaces binary .slx block diagrams with clean, reviewable PR diffs.
  • Headless Cloud Scaling: Spin up 10,000 parallel test runs in headless Linux Docker containers on AWS/GCP with zero per-core licensing bottlenecks.
  • Hardware-Accelerated with JAX: Machine-precision autodiff sensitivities, parallel GPU-batched rollouts via vmap, and exact plant-controller co-design ($\nabla_\theta J$).
  • Unified Optimization & Planning Boundary: Standardized MathematicalProgram and PlanningProblem interfaces decouple problems from plug-and-play gradient, NLP, and RL solvers.
pip install minilink  •  github.com/alx87grd/minilink Open Source (MIT License)

The Sky's the Limit

No architectural ceiling: pure array mappings scale from toy plants to billion-parameter frontier models
$$\dot{x} = f(x, u, t; p), \quad p \in \mathbb{R}^{\text{billions}}$$ $$\text{Pure Arrays} \xrightarrow{\text{XLA / SPMD}} \text{Automated Sharding across Cloud Data Centers}$$
Architectural Scalability
  • Pure Array Mappings: Minilink is fundamentally built on pure mathematical maps: arrays in $\to$ arrays out. There is no hardcoded limitation on state dimension or parameter count.
  • Billion-Parameter Neural Blocks: A controller or policy block in Minilink can be an arbitrary JAX neural network module. JAX is the exact engine used to train frontier foundation models.
  • Automated Sharding & Cloud Scale: JAX compiles via XLA with automated array sharding across multi-GPU / multi-TPU cloud data centers (jax.shard_map, SPMD).
  • Zero Architectural Redesign: The identical functional contract that models a 2-state pendulum on a student laptop scales seamlessly to massive neural policies across distributed clusters.
frontier_scale.py Frontier Neural Policy in Minilink
import jax import jax.numpy as jnp from minilink import DynamicSystem class FrontierTransformerPolicy(DynamicSystem): """Massive neural policy wrapped as a standard Minilink block.""" def f(self, x, u, t=0, params=None): # Pure forward pass over sharded multi-billion parameter weights weights = params["weights"] return transformer_forward(x, weights) # Standard feedback composition: loop = policy @ plant loop = FrontierTransformerPolicy() @ plant_cluster # XLA compilation with automated TPU/GPU sharding across data center pods sharded_sim = jax.jit( loop.compile(backend="jax"), in_shardings=(mesh, None) )

The Future: Continuum Systems & Pluggable Backends

Scaling to finite-element research models and extensible execution/rendering engines
Continuum Mechanics & Pluggable Engines
  • Prototype 1 • ANCF Dynamic Tire Ring: 32 nodes ($n = 288$ states) with nonlinear elasticity, stretch, bending, and contact/friction in JAX (live MeshCat preview).
  • Prototype 2 • FE Dynamic Fishing Net: Multi-thousand-node dynamic mesh ($n > 14,000$ states) with Morison hydrodynamic drag running as a native Minilink block.
  • Pluggable Execution (Rust & ROS): Pure array interface enables switching between NumPy and JAX, and compiling models to standalone Rust binaries or optimized ROS / ROS2 real-time nodes.
  • Photorealistic Visual Backends: Declarative kinematics ($T = \mathrm{tf}(x,u,t)$) stream cleanly into Unreal Engine 5, Unity, or NVIDIA Isaac Sim.
ancf_tire_prototype.py Continuum System in Minilink
# ANCF dynamic tire ring: 288 states, contact & friction model = make_ancf_tire_model(n_nodes=32, radius=0.5, k_bend=25.0) sys = ANCFTireSystem(model, center=(0, 0, 1.15), angular_velocity=(0, 18, 0)) # Standard Minilink pipeline: compiled JAX integration (future: Rust, ROS node) traj = sys.compute_trajectory(tf=0.6, dt=0.0002, backend="jax") sys.animate(traj, renderer="meshcat")
Continuum Dynamic Prototypes
pip install minilink  •  github.com/alx87grd/minilink Open Source (MIT License) • Future Architecture