mink-warp

mink-warp is batched differential inverse kinematics on MuJoCo Warp, with a Mink-shaped API. Given a robot configuration and a stack of task-space objectives, it computes joint velocities for many parallel worlds on the GPU — the same control-loop niche as Mink, scaled to nworld.

Features include:

• Mink-compatible tasks — FrameTask, RelativeFrameTask, PostureTask, ComTask, DampingTask, EqualityConstraintTask, soft JointLimitTask;
• Hard limits — ConfigurationLimit, VelocityLimit, CollisionAvoidanceLimit, LinearInequalityLimit via GPU ADMM (ConstrainedSolver);
• Device-native hot path — FK, Jacobians, residual assembly, and linear solves as Warp kernels on wp.array buffers;
• Interchangeable solvers — damped least squares (default), Levenberg–Marquardt, L-BFGS, constrained ADMM;
• Optional CUDA graph capture for fixed task sets in real-time loops;
• Runnable mjviser demos — numbered examples/01_… through 05_… (Panda → UR5e → Cassie → dual iiwa → G1).

For usage, concepts, and API reference, see the documentation.

Installation

From PyPI:

uv add mink-warp

Or clone and run locally:

git clone https://github.com/simeon-ned/mink-warp.git && cd mink-warp
uv sync --extra dev --extra examples

Requires Python 3.10+, MuJoCo 3.8+, mujoco-warp, and NVIDIA Warp. A CUDA-capable GPU is recommended for batched workloads.

Usage

import mink_warp as mw

cfg = mw.Configuration(model, nworld=512, device="cuda")

frame = mw.FrameTask("ee", "site", position_cost=1.0, orientation_cost=1.0)
frame.set_target_from_configuration(cfg)
posture = mw.PostureTask(model, cost=1e-2)
posture.set_target_from_configuration(cfg)

solver = mw.IKSolver(cfg)
solver.solve_and_integrate([frame, posture], dt=0.01, use_graph=True)

# Hard joint limits (Mink limits=None equivalent):
v = mw.solve_ik(cfg, [frame, posture], dt=0.01, limits=None)

Examples

Examples are ordered by increasing complexity:

uv run examples/01_panda_ik.py                  # FrameTask + soft limits, CUDA graph
uv run examples/02_constrained_ur5e.py          # hard config / velocity / collision limits
uv run examples/03_equality_cassie.py           # closed-chain EqualityConstraintTask
uv run examples/04_self_collision_dual_iiwa.py  # dual Kuka, inter-arm collision
uv run examples/05_relative_frame_g1.py         # G1 RelativeFrameTask + collision

Assets are vendored under examples/ from Mink (Panda, UR5e, Cassie, Kuka iiwa14, Unitree G1). See examples and the examples guide in the docs.

Benchmarks

Batched throughput and CPU-vs-Mink parity (benchmarks/README.md):

uv run python benchmarks/bench_ik.py             # solves/sec vs batch size
uv run python benchmarks/bench_constrained.py    # hard limits vs mink daqp
uv run python benchmarks/bench_parity.py         # agreement with mink (oracle)

See benchmarks/RESULTS.md for sample numbers.

Acknowledgements

mink-warp mirrors the API and conventions of Mink, which is a MuJoCo port of Pink (Pinocchio). The Lie-group helpers and task Jacobian conventions follow the same lineage as Mink and Pink.

Implementation patterns also draw from GPU IK / physics stacks in the MuJoCo Warp ecosystem and from Newton (NVIDIA + Google DeepMind), though mink-warp is not a wrapper around Newton — it targets differential IK with a Mink-shaped API on mujoco.MjModel + mjwarp.

Citation

If you use mink-warp in your research, please cite it as follows:

@software{nedelchev2026minkwarp,
  author       = {Nedelchev, Simeon and Domrachev, Ivan},
  title        = {{mink-warp: Batched differential inverse kinematics on MuJoCo Warp}},
  year         = {2026},
  version      = {0.1.0},
  url          = {https://github.com/simeon-ned/mink-warp},
  repository   = {https://github.com/simeon-ned/mink-warp},
  license      = {Apache-2.0},
}

Also available as CITATION.cff and CITATION.bib. Method papers: docs/references.bib.

License

Apache-2.0 — see LICENSE.