Crate ferromotion_learn 

ferromotion-learn — differentiable, physics-informed learning for physical AI

Where ferromotion_core gives you the physics — rigid-body dynamics, variational integrators, contact, estimation — this crate gives you the learning: the differentiable machinery for models that blend physics priors with data. It is the on-device, pure-Rust, WASM-clean counterpart to the PyTorch-based physics-informed-ML stacks: no BLAS, no Python, no GPU required.

The organizing idea (from the physics-informed ML literature) is that a physics prior can enter a learned model at one of three places:

• guided — in the data / features (engineered inputs, geometric projections);
• informed — in the loss (penalize violation of a differential equation — a PINN);
• encoded — in the architecture (Lagrangian/Hamiltonian nets, Neural ODEs, structure-preserving integrators).

Everything rests on one keystone: automatic differentiation. [autodiff] is reverse-mode (for gradients of a scalar loss w.r.t. many parameters — backpropagation); [dual] is forward-mode (for exact higher-order derivatives w.r.t. a model’s inputs, which PINNs and Lagrangian nets need). Both are verified against finite differences.

Modules

calib

Gradient-based real-to-sim calibration — fit a robot’s inertial parameters and joint friction to recorded trajectories, by exact gradients through the dynamics.

nls

Differentiable nonlinear least squares — optimization as a layer, the theseus-class capability (upstream frozen since 2024) in pure Rust.

smoothed

Smoothed gradients through contact make/break — the correct-gradients-through-contact frontier (Dojo; “Differentiable Physics Simulations with Contacts: do they have correct gradients?”). An analytic contact adjoint with the frozen active set (the OptNet/theseus convention ferromotion uses in its constraint solver) is exact everywhere except at the activation boundaries — where a contact makes or breaks, stick switches to slip, or a body grazes an obstacle. There the true gradient is a subgradient or a cliff, and a naive descent stalls (flat pre-contact region) or oscillates (a jump).

Structs

Delan

A Deep Lagrangian Network for a 2-DOF system: learns L(q) (→ M = LLᵀ) and V(q).

Dual

A first-order dual number re + eps·ε (ε² = 0). Evaluating f on Dual::var(x) yields f(x) in re and f'(x) in eps.

Grad

The result of a backward pass: the gradient of the seed output w.r.t. every node on the tape.

Hnn

A Hamiltonian network H_θ(q, p) (two inputs, one scalar output).

HyperDual

A second-order (hyper-)dual number re + e1·ε₁ + e2·ε₂ + e12·ε₁ε₂, with ε₁² = ε₂² = 0. Seeding ε₁ and ε₂ on two inputs makes e12 the exact mixed partial ∂²f/∂x∂y; seeding both on the same input makes e12 = f''.

Mlp

A fully-connected network with tanh hidden activations and a linear output layer.

ModelBasedControl

Learn a plant model from data, tune a PID inside it, and deploy on the true plant.

Msnn

A blend of local linear models with partition-of-unity triangular memberships over one scheduling input.

NeuralOde

A Neural ODE for a 2-D system: an MLP field f_θ : ℝ² → ℝ², trained by trajectory matching.

PidController

A PID controller (gains [Kp, Ki, Kd]) tuned by differentiating through the plant rollout.

Pinn

A trained PINN for the harmonic oscillator u'' + ω² u = 0 on [0, t_max] with u(0)=1, u'(0)=0.

Sindy

A discovered model: the library term names and the sparse coefficient matrix Ξ (one column per state dimension).

Tape

The tape (Wengert list) recording the forward computation. Create Vars from it, compute, then call Var::backward. Interior mutability lets Copy Var handles append nodes during ordinary arithmetic.

Var

A differentiable value: a Copy handle carrying its numeric value and its position on the Tape.

Functions

monomial_exponents

All monomial exponent tuples for n_vars variables up to total degree degree (including the constant).