Architecture overview

Architecture overview#

How a batched IK step flows through mink-warp. For the Mink comparison, see Mink API parity.

Pipeline#

mujoco.MjModel
     ↓
Configuration(nworld)     # mjwarp model/data, device qpos
     ↓
Task.compute_residual() # W, e, mu per task (device)
     ↓
Solver backend          # assemble H, c; linear / ADMM solve
     ↓
integrate_inplace(v)    # mjwarp position step (out-of-place qpos)

Everything above the dashed host boundary stays on device in the hot path.

Configuration#

Configuration owns:

  • wp_model / wp_data from MuJoCo Warp (batched nworld)

  • q as wp.array (nworld, nq)

  • FK via mjwarp.kinematics + com_pos

  • Body-frame Jacobians via mjwarp.jac + a frame transform kernel

  • Integration via integrate_qpos (graph-safe out-of-place writes)

Tasks#

Tasks inherit from Task or TargetedTask. Each implements compute_residual(), returning weighted Jacobian rows W, error e, and optional Levenberg–Marquardt damping mu — the same stacking convention as Mink [FrameTaskJacobian].

Solvers#

Solver backends share Solver:

Backend

One step

Notes

DLSSolver (IKSolver alias)

\(v = \Delta q / dt\) from damped normal equations

Default; optional CUDA graph

LMSolver

LM step on configuration

Newton-style tiled Cholesky

LBFGSSolver

Quasi-Newton step

Multi-iter solve_and_integrate

ConstrainedSolver

Box or general G Δq ≤ h via ADMM

Mink QP equivalent; box path exactly feasible each iter

Kernels#

Low-level Warp code lives under mink_warp/kernels/ (frame Jacobians, residual stacking, tile Cholesky, box / general-inequality ADMM). Public code should call tasks and solvers, not kernels directly.