MimicIK model zoo
MimicIK is a research checkpoint collection for learned robot inverse kinematics. The release contains MIP/SuDeepDiT, ChiUNet, pure-MLP, diffusion UNet, RoboTwin, FK-loss ablation, recovery, and controlled NoStatic update-strategy checkpoints produced by the NatureIK codebase.
Source code:
RedAmancy918/NatureIK
Executable training/evaluation revision:
fd6f8d026475b1cd0da01a1ea1aa41b015faa348. Documentation and experiment-semantics audit:
e66b7b389cae9eba4012fabedd9c0c9534a4f8d2 (documentation plus a non-functional code-comment correction).
Repository layout
| Path | Contents | Weight files | Approx. bytes |
|---|
models/main/ | Main MIP/SuDeepDiT and ChiUNet experiments | 64 | 9.24 GB |
models/natureik_unet/ | Diffusion-policy UNet experiments | 30 | 30.57 GB |
models/pure_mlp_ik/ | Pure-MLP IK baselines | 35 | 0.45 GB |
models/robotwin/ | RoboTwin and dual-arm experiments | 25 | 3.54 GB |
models/fk_weight_ablation/ | FK-loss-weight ablations | 15 | 2.13 GB |
models/comparison_imports/ | NoStatic joint-loss comparison checkpoint | 1 | 0.14 GB |
models/loss_design_ablation/ | NoStatic legacy_two_step controlled comparison | 2 | 0.28 GB |
models/main_recovery/ | Recovery runs for main MIP experiments | 15 | 2.13 GB |
The models/ tree contains 187 weight files plus 64 YAML configuration/provenance files (251 files; 48,484,266,591 logical bytes before Xet deduplication). Datasets, W&B run data, raw training logs, cached outputs, and local environments are intentionally excluded. Five W&B-generated YAML metadata copies are also excluded because the corresponding canonical run/Hydra configurations are already included.
Model interface
The AIRBOT IK checkpoints are single-arm policies:
- observation: 20D = current joints (6) + current end-effector pose (XYZ + quaternion, 7) + target end-effector pose (XYZ + quaternion, 7)
- action: 6D delta-joint command
- quaternion convention: XYZW
- position/joint units: metres/radians
- kinematic asset:
play_g2_usb_cam, end-effector link end_link
The dual-arm service evaluates two single-arm observations with batch=2, then combines the two 6D joint outputs with two external gripper values to form a 14D robot command. The gripper dimensions are not predicted by these IK checkpoints.
SudeepDiT depth (for example, 8 transformer layers) describes network architecture. The MIP sampler in this code performs exactly two network evaluations (zero-start coarse prediction, then refinement at t=0.9). Architecture depth, these two inference evaluations, and optimizer-update count are independent concepts.
Important experiment semantics
models/comparison_imports/joint_loss_nostatic_20260807/ is the Aug-2026 NoStatic model trained with a single joint update: MIP loss + 0.1 * FK loss, followed by one backward pass and one optimizer step.models/loss_design_ablation/legacy_two_step_nostatic_seed0/ is the outer-step-matched NoStatic comparison run. It uses the same mathematical loss, data split, normalizer, architecture, seed, scheduler configuration, batch size, and 300k outer steps as the joint reference. What changed is the optimizer-update strategy.- Historical May-2026 MIP+FK checkpoints were produced by the legacy optimizer behavior: a MIP step/gradient clear/EMA update, one scheduler advance, then a separate FK step at the newly scheduled learning rate. The FK step has no trailing gradient clear or EMA update, so its gradient is accumulated into the next outer step's MIP backward. Historical configs predate the
fk_update_strategy field; use task.fk_update_strategy=legacy_two_step with current code when exact reproduction is required.
- “Two-step MIP inference” and “legacy two-step optimizer updates” are different concepts.
- A
*-final.pt file contains final-step weights, but the val_loss embedded in its filename is the run's historical best and may not be the final step's own validation loss.
NoStatic update-strategy comparison
Both rows below use the same 224-episode / 61,317-frame tok2 subset from the frozen NoStatic validation split and the corrected target-relative SO(3) rotation metric. Reported aggregate metrics are episode-macro means (compute each episode's metric, then average episodes) unless explicitly identified as a global single-frame extreme.
| Strategy | Outer steps | AdamW steps | Final-step MIP val loss | Mean pos. (mm) | P95 (mm) | Rotation (deg) | SR@5mm |
|---|
joint reference | 300k | 300k | 0.014432 | 2.25 | 3.02 | 0.16 | 99.60% |
legacy_two_step | 300k | 600k | 0.012258 | 2.24 | 2.96 | 0.15 | 99.66% |
The observed legacy differences are small. In an episode-paired bootstrap (224 episodes, 200,000 resamples), the mean-position change was -0.015442 mm with a 95% interval of [-0.022630, -0.008321] mm. This is statistically distinguishable on this validation subset but only about 15.4 micrometres; moreover, the global worst single frame was worse for legacy (13.941 mm versus 11.815 mm). This is
not a pure loss ablation: the loss formula is unchanged, while legacy performs two AdamW updates and extra FK compute per outer step. The evaluation set is held-out from gradient training but is a validation subset used for checkpoint selection, not an independent test set. These single-seed numbers therefore do not establish a general causal advantage or engineering-significant gain. See
release_metadata.yaml for exact optimizer semantics, hashes, W&B provenance, split fingerprints, and evaluation limitations. The legacy best-step and final bundles are both from step 300k and contain tensor-identical config/normalizer/raw/EMA state; their whole-file hashes differ because they are separate pickle serializations.
Data and evaluation caveats
- The historical and NoStatic models do not all share the same training dataset, split, scheduler, or normalizer. Cross-family numbers should not be interpreted as a loss-only ablation unless those factors, initialization seeds, checkpoint selection, and evaluation data are held fixed. Equal outer steps also give
legacy_two_step twice as many AdamW updates as joint, so outer-step-matched and optimizer-update/compute-matched comparisons answer different questions.
- The corrected rotation metric is the target-relative SO(3) geodesic angle. Results produced before the metric fix must not be compared as rotation error.
- The 224-episode tok2 evaluation set used in recent comparisons is a held-out validation subset (61,317 frames), not an independent test set.
- Datasets are not included in this model repository. YAML files preserve the original local paths for provenance; replace those paths for your machine.
Representative training environments were Python 3.12/3.13 with PyTorch 2.11–2.13 and CUDA 13 builds. Use the adjacent YAML and the matching NatureIK code for exact architecture and preprocessing details; do not mix normalizers between checkpoints.
Loading a checkpoint
Download the desired file and load it with the matching NatureIK code and YAML configuration:
1from huggingface_hub import hf_hub_download
2import torch
3
4checkpoint_path = hf_hub_download(
5 repo_id="vistar918/MimicIK",
6 filename=(
7 "models/comparison_imports/joint_loss_nostatic_20260807/"
8 "step=0300000-val_loss=0.014348_sudeepdit-final.pt"
9 ),
10)
11
12# PyTorch checkpoint files use pickle. Only load artifacts from sources you trust.
13bundle = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
14print(bundle.keys())
Checkpoint formats differ by model family. MIP bundles include model/EMA state and normalization data; diffusion UNet files use their corresponding Lightning-style checkpoint format. Use each checkpoint with its adjacent YAML configuration.
Safety and limitations
These checkpoints are research artifacts. They do not guarantee collision or self-collision avoidance, joint-limit compliance, singularity handling, calibration robustness, workspace validity, or safe behavior on physical hardware. Offline teacher-forced validation does not establish closed-loop robot safety. Apply velocity/acceleration/position limits, workspace clamps, collision checking, an emergency stop, and human supervision before hardware use.
Performance outside the training robots, URDF, calibration, payload, cameras, and workspace is not established. PyTorch .pt/.ckpt files can execute code during deserialization; verify file origin and hashes and only load artifacts you trust.
License
MIT. See LICENSE and NOTICE for attribution and the NatureIK source repository for source licensing.
