Release the SpeedTuning simulation reproduction

.github/workflows/sim-tests.yml

@@ -0,0 +1,58 @@
+name: Simulation tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      MUJOCO_GL: osmesa
+      PYOPENGL_PLATFORM: osmesa
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify checkpoint-free release contents
+        run: |
+          forbidden="$(git ls-files | grep -E '(^|/)(outputs|checkpoints|runs|wandb)/|\.(pt|pth|ckpt|onnx|h5|hdf5|pkl|pickle)$' || true)"
+          if [ -n "$forbidden" ]; then
+            echo "Generated model artifacts must not be tracked:"
+            echo "$forbidden"
+            exit 1
+          fi
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: pip
+      - name: Install headless MuJoCo rendering libraries
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes libgl1 libosmesa6
+      - name: Install public package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[rl,learned,test]" build twine
+      - name: Run tests
+        run: pytest -q
+      - name: Run supported integration commands
+        run: |
+          speedtuning-sim
+          speedtuning-sim --speed 1.5
+          speedtuning-check-chunks
+          speedtuning-rainbow-poc
+          speedtuning-eval-speed --task tea_bag --base-policy recorded-chunk --episodes 1
+          speedtuning-sweep --task tea_bag --base-policy scripted --speed-start 1.0 --speed-stop 1.1 --episodes-per-speed 1 --output /tmp/sweep.json
+      - name: Build source and wheel distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+          tar -tzf dist/*.tar.gz | grep 'docs/SCRIPTED_REPRODUCTION.md'
+          tar -tzf dist/*.tar.gz | grep 'benchmarks/scripted_results.json'
+      - name: Verify the wheel and packaged MuJoCo assets
+        run: |
+          python -m venv /tmp/speedtuning-package-check
+          /tmp/speedtuning-package-check/bin/python -m pip install dist/*.whl
+          cd /tmp
+          /tmp/speedtuning-package-check/bin/python -c "from experiment_config import load_experiment_config; assert load_experiment_config('scripted-pick-and-place')[0]['decisions'] == 100000"
+          /tmp/speedtuning-package-check/bin/speedtuning-sim --task tea_bag

.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Environments and editors
+.venv/
+.venv-legacy/
+.vscode/
+.idea/
+**/.DS_Store
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Generated research artifacts
+outputs/
+results/
+logs/
+tmp/
+.tmp/
+data/
+data_local/
+checkpoints/
+*.pt
+*.pth
+*.ckpt
+wandb/
+_wandb/

.python-version

@@ -0,0 +1 @@
+3.10

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0
+
+- Released pick-and-place, insertion, and tea-bag MuJoCo tasks.
+- Added parameterized execution speed for retained waypoint policies.
+- Added a model-agnostic variable-speed action-chunk interface.
+- Added external chunk-policy and speed-policy factory loading.
+- Added supported Rainbow DQN speed-policy training, checkpoints, and evaluation.
+- Added decision-level speed execution with fresh receding-horizon chunks and
+  shared frame-skip semantics for training and evaluation.
+- Added stacked proprioceptive/visual speed observations with pretrained, random,
+  and external image-encoder support.
+- Added retained ACT checkpoint/backbone adapters, checkpointed preprocessing,
+  seeded physical-acceleration metrics, fixed-speed sweeps, and plotting.
+- Added an archival paper configuration and manifests for every published
+  simulation ablation.
+- Added runnable scripted-policy presets for pick-and-place, insertion, and tea
+  bag, including the retained reward and Rainbow update schedule.
+- Added from-scratch reproduction instructions and machine-readable reference
+  results for all three simulated tasks.
+- Added seeded tea-bag pose randomization as a separately labeled robustness
+  protocol while preserving the fixed-pose historical environment.
+- Added periodic training snapshots, task/protocol metadata validation, and safe
+  loading for locally generated speed-policy checkpoints.
+- Added clean-install packaging, continuous integration, and release tests.
+- Removed real-robot, private-path, scratch-output, and trained-checkpoint
+  artifacts from the public surface.

CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the SpeedTuning paper."
+title: "SpeedTuning simulation and speed-policy infrastructure"
+type: software
+version: 0.1.0
+authors:
+  - family-names: Yuan
+    given-names: David D.
+license: MIT
+repository-code: "https://github.com/DaivdYuan/SpeedTuning"
+preferred-citation:
+  type: conference-paper
+  title: "SpeedTuning: Speeding Up Policy Execution with Lightweight Reinforcement Learning"
+  authors:
+    - family-names: Yuan
+      given-names: David D.
+    - family-names: Zhao
+      given-names: Tony Z.
+    - family-names: Burns
+      given-names: Kaylee
+    - family-names: Finn
+      given-names: Chelsea
+  collection-title: "2025 IEEE International Conference on Robotics and Automation (ICRA)"
+  year: 2025
+  doi: "10.1109/ICRA55743.2025.11128753"

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Bug reports and focused pull requests for the supported simulation surface are
+welcome. Before opening a pull request:
+
+1. Install Python 3.10 and the development extras with
+   `uv sync --extra rl --extra learned --extra test`.
+2. Run `uv run pytest -q`.
+3. Run `uv run speedtuning-sim` and `uv run speedtuning-check-chunks` when
+   changing tasks, policies, interpolation, or physics assets.
+4. Run `uv run speedtuning-rainbow-poc` when changing speed-policy learning.
+5. Run a two-point `speedtuning-sweep` smoke test when changing metrics,
+   decision timing, or experiment manifests.
+
+Please keep real-robot dependencies, private checkpoints, datasets, machine-local
+paths, and generated outputs outside this repository. New external policy support
+should use the public adapters instead of adding a dependency on another research
+repository to the core environment.
+
+By contributing, you agree that your contribution may be distributed under the
+license applicable to the directory you modify.

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Tony Z. Zhao
+Copyright (c) 2024-2026 David D. Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,7 @@
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include NOTICE.md
+include requirements-sim.txt
+recursive-include benchmarks *.json *.md
+recursive-include docs *.md *.png

NOTICE.md

@@ -0,0 +1,22 @@
+# Notices and attribution
+
+SpeedTuning simulation and speed-policy infrastructure includes code and assets
+derived from [Action Chunking with Transformers
+(ACT)](https://github.com/tonyzhaozh/act), originally released under the MIT
+License. The original Tony Z. Zhao copyright notice is retained in `LICENSE`.
+
+The files under `detr/` are modified from
+[DETR](https://github.com/facebookresearch/detr) and are distributed under the
+Apache License 2.0 included at `detr/LICENSE`.
+
+The ALOHA/ViperX MuJoCo XML files and meshes under `assets/` were inherited from
+the MIT-licensed ACT repository history. Task-specific tea-bag environment files
+were added in the SpeedTuning development history and are distributed under this
+repository's MIT License.
+
+SpeedTuning simulator recovery, public integration, and release engineering:
+Copyright (c) 2024-2026 David D. Yuan.
+
+The README teaser image is rendered from the SpeedTuning project-page figure,
+Copyright (c) the SpeedTuning authors and shared under CC BY-SA 4.0. The source
+project page is https://daivdyuan.github.io/speed-tuning/.