Publish self-pumped swing policy

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+media/preview.mp4 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,118 @@
+---
+library_name: onnx
+pipeline_tag: reinforcement-learning
+tags: [microduck, microduck-policy, mjlab, robotics, reinforcement-learning, swing]
+license: apache-2.0
+---
+
+# microduck-swing
+
+This MicroDuck policy starts motionless at the bottom of a two-cord swing and
+pumps with its articulated head and legs. The best strict 36-second rollout
+reaches a **173.20° full span**; 71 of 100 randomized seeds pass every
+full-horizon physical-validity gate.
+
+<video controls muted loop src="https://huggingface.co/HannesVonEssen/microduck-swing/resolve/main/media/preview.mp4" style="max-width:640px;width:100%"></video>
+
+The complete task, PPO configuration, selected PyTorch checkpoint and
+selection endpoints, deterministic evaluator, seat generator, printable
+meshes, and collision hulls are in
+[`Vottivott/microduck-playground`](https://github.com/Vottivott/microduck-playground)
+at commit
+[`5eec677`](https://github.com/Vottivott/microduck-playground/commit/5eec677cbf0e092523ee9b33bda57e81b9115817).
+
+## Try it in simulation
+
+```bash
+git clone https://github.com/Vottivott/microduck-playground.git
+cd microduck-playground
+git checkout 5eec677cbf0e092523ee9b33bda57e81b9115817
+uv sync
+
+# Reproduce the best strict 36-second audit from the source checkpoint.
+uv run python scripts/evaluate_swing_checkpoint.py \
+  experiments/swing/checkpoints/alpha050.pt \
+  --output /tmp/swing-seed27.json \
+  --device cpu --duration 36 --seed 27
+
+# Download the deployment graph separately.
+hf download HannesVonEssen/microduck-swing policy.onnx \
+  --local-dir policies/swing
+```
+
+## Runtime contract
+
+- input: `obs`, float32 `[1, 61]`
+- output: `actions`, float32 `[1, 14]`
+- control rate: 50 Hz
+- action scale: 0.7 rad, joint-position targets around MicroDuck HOME
+- observation normalizer: baked into `policy.onnx`
+- entry state: retained in the seat, bottom of the arc, motionless
+- robot: MicroDuck hardware revision 1, 14 Dynamixel XL330 servos
+- mechanism: two independent 380 mm elastic, tension-only cords
+- policy horizon: trained episodically; evaluated for 36 seconds
+
+The observation order is `base_ang_vel(3), projected_gravity(3),
+joint_pos(14), joint_vel(14), previous_actions(14), swing_plane_cue(3),
+zeros(4), zeros(6)`.
+
+### Important: the three cue slots are not velocity commands
+
+This model preserves the standard 61-D MicroDuck tensor shape, but repurposes
+the usual three twist-command slots as a deployable swing-plane feedback cue:
+
+```text
+[0, body_y_axis_world.x, body_y_axis_world.z]
+```
+
+`body_y_axis_world` must come from the robot's IMU orientation expressed
+relative to the known still-start frame. The remaining 10 command slots are
+zeros. A standard walking runtime that supplies a requested velocity in these
+slots is therefore incompatible without this small observation adapter. No
+cord, pivot, camera, or motion-capture measurement is supplied to the actor.
+
+## Simulation evaluation
+
+The selected model is the exact all-row alpha-0.50 final-layer interpolation
+documented in the source repository. Selection uses mechanism validity rather
+than angle alone.
+
+| metric | result |
+|---|---:|
+| randomized evaluation | 100 seeds × 36 s |
+| strict full-horizon passes | 71/100 |
+| geometry-debt-free passes | 73/100 |
+| median peak-to-peak span | 163.03° |
+| median final-six half-cycle span | 161.09° |
+| best strict rollout | seed 27, 173.20° |
+| seed-27 cord envelope | 370.38–392.02 mm |
+| seed-27 maximum lateral displacement | 10.35 mm |
+| seed-27 maximum attachment-alignment penalty | 0.02037 |
+
+Strict screening rejects a rollout for excessive lateral displacement,
+attachment misalignment, deep cord slack, overextension, NaNs, reset, or
+accumulated geometry debt. The preview is the strict seed-27 rollout; it is
+silent and the overlay reports the running maximum full-span angle.
+
+## Sim-to-real boundary
+
+The task retains deployment-oriented MicroDuck modeling, including BAM XL330
+voltage/back-EMF/current behavior, battery variation and load-dependent sag,
+control delay, actuator friction variation, encoder bias, IMU/encoder noise,
+and two independent elastic tension-only cords. The actor uses only
+IMU/encoder/action-history signals available on the robot.
+
+This is a **simulation result, not a hardware-validated policy**. It requires
+the retained swing seat, 380 mm cords, and a suitable rigid frame. Cord knots,
+frame flex, textile strap contact, seat padding, real collision geometry,
+servo temperature, assembly tolerances, and the IMU-frame calibration are not
+fully captured. Use a separate safety tether, current limits, an emergency
+stop, a clear exclusion zone, and conservative incremental testing.
+
+<a href="https://hfviewer.com/HannesVonEssen/microduck-swing?utm_source=huggingface&amp;utm_medium=embedded_model_card&amp;utm_campaign=HannesVonEssen__microduck-swing_card&amp;utm_content=embedded_card_open_viewer&amp;from=embedded-model-card" target="_blank" rel="noopener">
+  <img
+    src="https://hfviewer.com/api/card.svg?source=HannesVonEssen%2Fmicroduck-swing&amp;granularity=auto&amp;v=20260516-title-pills-card"
+    alt="Architecture graph for HannesVonEssen/microduck-swing. Open in hfviewer"
+    width="100%"
+  />
+</a>

SHA256SUMS

@@ -0,0 +1,4 @@
+4a12e5d3bba08b99228353976a908ce2989bc436f3707d0a196523b6be3fdea9  README.md
+5a8812bc58f96d8a6537fa7433c8bccd19c7855b0a9b9bbb637d11137af70aa9  manifest.json
+0caa869bcf46ac3ef9029ea73b3998cc86c3e7b4b3314717bd790474354b718d  policy.onnx
+558651776cd5798e73c69048d8496b44d776606612ce888a2bc79e7c9f46a289  media/preview.mp4

manifest.json

@@ -0,0 +1,94 @@
+{
+  "schema_version": 3,
+  "model_api": 1,
+  "name": "microduck-swing",
+  "kind": "episodic",
+  "obs_len": 61,
+  "action_len": 14,
+  "action_scale": 0.7,
+  "entry_pose": "retained in swing seat at the bottom of the arc, motionless",
+  "duration_s": 36.0,
+  "status": "sim-only-hardware-candidate",
+  "description": "Self-pumped MicroDuck swing policy on two 380 mm elastic, tension-only cords.",
+  "observation": {
+    "layout": "base_ang_vel(3), projected_gravity(3), joint_pos(14), joint_vel(14), previous_actions(14), swing_plane_cue(3), zero_head(4), zero_body(6)",
+    "swing_plane_cue": "[0, body_y_axis_world.x, body_y_axis_world.z] from IMU orientation relative to the still-start frame",
+    "privileged_actor_inputs": false,
+    "normalizer_baked_into_onnx": true
+  },
+  "robot": {
+    "model": "microduck",
+    "hw_rev": 1,
+    "servos": "14x Dynamixel XL330",
+    "control_hz": 50,
+    "hardware_modifications_required": true
+  },
+  "mechanism": {
+    "cord_count": 2,
+    "cord_model": "independent elastic tension-only tendons",
+    "rest_length_m": 0.38,
+    "stiffness_n_m": 2000.0,
+    "simulation_limit_m": 0.395,
+    "anchor_height_m": 0.75,
+    "seat": "retained-seat generator and printable meshes in Vottivott/microduck-playground"
+  },
+  "training": {
+    "task_id": "Mjlab-SwingPump-MicroDuck",
+    "algorithm": "PPO (rsl_rl)",
+    "repo": "Vottivott/microduck-playground",
+    "source_commit": "5eec677cbf0e092523ee9b33bda57e81b9115817",
+    "upstream_base": "pollen-robotics/microduck_rl@1e79c29c97d8b38aee9eefde77a545860ba7658e",
+    "selection": "alpha 0.50 interpolation of all final actor-layer rows between frontier_source_3500.pt and planar_target_3600.pt",
+    "selected_checkpoint_sha256": "bd10d6b38eaa193dbde589cb9b51259b7469d3eef247cc9cbc121444a16ea2eb",
+    "source_checkpoint_sha256": "70e1e82b45b46a62c57943c1c528e26e724902fef76d1c2aa53b3256f2c08b04",
+    "target_checkpoint_sha256": "9c80750ad567c19d5183ada5bb98742a86798313a352ce37e36823a2d44be114",
+    "export": "scripts/export.py; observation normalizer baked into policy.onnx"
+  },
+  "eval": {
+    "sim_proxy": "mjlab / MuJoCo Warp with BAM XL330 M6 actuator model",
+    "seeds": 100,
+    "duration_s": 36.0,
+    "control_dt_s": 0.02,
+    "strict_full_horizon_passes": 71,
+    "geometry_debt_free_passes": 73,
+    "median_peak_to_peak_deg": 163.0279718838097,
+    "median_final_six_half_cycle_peak_to_peak_deg": 161.08761759344662,
+    "best_strict_seed": 27,
+    "best_strict_peak_to_peak_deg": 173.19988233166998,
+    "best_strict_final_six_half_cycle_peak_to_peak_deg": 171.67248924707994,
+    "best_strict_max_lateral_m": 0.010354727506637573,
+    "best_strict_max_attachment_alignment_penalty": 0.020374774932861328,
+    "best_strict_cord_envelope_m": [0.370378702878952, 0.392024964094162],
+    "strict_gates": {
+      "deep_slack_below_m": 0.37,
+      "overextension_above_m": 0.394,
+      "lateral_above_m": 0.02,
+      "alignment_penalty_above": 0.05
+    }
+  },
+  "sim2real": {
+    "retained": [
+      "BAM XL330 M6 voltage control, back-EMF, current limiting, battery variation, and load-dependent sag",
+      "control delay and actuator friction variation",
+      "encoder bias and IMU/encoder observation noise",
+      "two independent elastic tension-only cord dynamics"
+    ],
+    "hardware_validated": false,
+    "known_limits": [
+      "cord knots and frame compliance",
+      "textile strap contact and seat padding",
+      "real collision geometry and assembly tolerance",
+      "servo temperature",
+      "still-start IMU frame calibration"
+    ]
+  },
+  "media": {
+    "preview": "media/preview.mp4",
+    "preview_seed": 27,
+    "preview_duration_s": 36.0,
+    "audio": false,
+    "camera": "fixed",
+    "overlay": "running maximum full-span angle"
+  },
+  "source_artifact_sha256": "0caa869bcf46ac3ef9029ea73b3998cc86c3e7b4b3314717bd790474354b718d"
+}

media/preview.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:558651776cd5798e73c69048d8496b44d776606612ce888a2bc79e7c9f46a289
+size 7003769

policy.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0caa869bcf46ac3ef9029ea73b3998cc86c3e7b4b3314717bd790474354b718d
+size 793720