Initial commit

Author: henrytsay

.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main, solution]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: CPU tests (Stages 1-4)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      MUJOCO_GL: osmesa
+      JAX_PLATFORMS: cpu
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install OSMesa (headless MuJoCo rendering)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libosmesa6 libgl1 libglfw3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync environment
+        run: uv sync --locked --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Setup check
+        run: uv run python scripts/check_setup.py
+
+      # Student TODOs raise NotImplementedError, which conftest.py reports as
+      # "not started" (a skip), not a failure. So this job is green on the
+      # starter `main` for all provided code, and green on `solution` for
+      # everything.
+      - name: Fast tests
+        run: uv run pytest -m "not gpu and not ros and not slow" -q
+
+      - name: Slow tests (PPO smoke)
+        timeout-minutes: 15
+        run: uv run pytest -m "slow and not gpu and not ros" -q
+
+      - name: Progress report
+        if: always()
+        run: uv run python scripts/progress.py --no-run
+
+  ros2:
+    name: ROS 2 sim2sim (Stage 5)
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build the ROS 2 image
+        run: docker build -t hrc/pup-ros2:jazzy docker/ros2
+
+      - name: Run the Stage 5 smoke test
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}:/ws" \
+            -e ROS_DOMAIN_ID=42 \
+            -w /ws/ros2_ws \
+            hrc/pup-ros2:jazzy \
+            /ws/tests/test_05_ros2_smoke.sh

.gitignore

@@ -0,0 +1,23 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+runs/
+ros2_ws/build/
+ros2_ws/install/
+ros2_ws/log/
+.DS_Store
+.vscode/
+.idea/
+MUJOCO_LOG.TXT
+.pup_progress.json
+*.log
+
+# NOTE: results/ is deliberately NOT ignored -- your learning curve, eval JSONs
+# and GIFs are part of the submission (see SUBMISSION.md).
+
+# The agent-facing build spec lives on the `solution` branch only; this keeps
+# it from being re-committed here when you switch branches.
+ONBOARDING_SPEC.md

.python-version

@@ -0,0 +1 @@
+3.11

README.md

@@ -0,0 +1,124 @@
+# HRC Software Onboarding — Fall 2026
+
+**Purdue Humanoid Robotics Club · software team**
+
+You are going to build the exact pipeline the club
+uses to make NEMO walk: a MuJoCo robot with a PD controller, a vectorized
+JAX/MJX environment, a Brax PPO training run, an exported numpy policy, and ROS 2
+nodes running that policy against a simulator through the same interfaces the
+real hardware uses. The robot is a 12-DoF quadruped called **Pup**. By the end
+you will have written a piece of every stage yourself, and you will have a
+walking robot to show for it.
+
+![Pup walking under the trained policy](docs/media/pup_walk.gif)
+
+## The pipeline
+
+```mermaid
+flowchart LR
+    S1["<b>Stage 1</b><br/>MuJoCo + PD<br/><i>mujoco, numpy</i>"]
+    S2["<b>Stage 2</b><br/>JAX for robotics<br/><i>jax</i>"]
+    S3["<b>Stage 3</b><br/>MJX environment<br/><i>mjx, playground</i>"]
+    S4["<b>Stage 4</b><br/>Brax PPO + export<br/><i>brax, colab</i>"]
+    S5["<b>Stage 5</b><br/>ROS 2 sim2sim<br/><i>ros 2, docker</i>"]
+    S1 --> S2 --> S3 --> S4 --> S5
+    S1 -. "same PD equation" .-> S5
+    S3 -. "same 45-dim observation" .-> S5
+```
+
+| Stage | Doc | You write | Time |
+|---|---|---|---|
+| 0 | [Setup](docs/00_setup.md) | — | 0.5–1 h |
+| 1 | [MuJoCo and the PD controller](docs/01_mujoco_and_pd.md) | `PDController`, `stand_up`, gain tuning | 2 h |
+| 2 | [JAX for robotics](docs/02_jax_for_robotics.md) | three JAX exercises, quaternion maths | 1.5 h |
+| 3 | [The MJX environment](docs/03_mjx_environment.md) | observation, termination, commands, `step`, three reward terms | 4 h |
+| 4 | [Training with Brax PPO](docs/04_training_with_brax.md) | the training wiring, `export_policy`, `NumpyPolicy` | 2.5 h |
+| 5 | [ROS 2 sim2sim](docs/05_ros2_sim2sim.md) | `policy_node`, the launch file | 3 h |
+
+**Total: ~13.5 hours of hands-on work.** This is a generous estimate, and it very possible to finish in much less time.
+
+Also useful: [glossary](docs/glossary.md) ·
+[FAQ and troubleshooting](docs/faq_and_troubleshooting.md) ·
+[reading packet](docs/reading_packet.md)
+
+## Start here
+
+```bash
+# 1. Click "Use this template" on GitHub, then:
+git clone https://github.com/<your-username>/onboarding-fall26.git
+cd onboarding-fall26
+
+# 2. Install
+curl -LsSf https://astral.sh/uv/install.sh | sh     # if you don't have uv
+uv python install 3.11
+uv sync
+
+# 3. Check
+uv run python scripts/check_setup.py
+uv run python scripts/progress.py
+```
+
+Then open [`docs/00_setup.md`](docs/00_setup.md).
+
+## Experience assumptions
+
+We assume you can program in Python, use `git`, and have seen `numpy` arrays
+before. We assume **no** background in robot control, reinforcement learning,
+JAX, or ROS 2 — every one of those is taught here from zero.
+
+If you have never used the command line for anything beyond `git commit`, this
+will be hard but not impossible; budget extra time for Stage 0 and Stage 5, and
+ask in Discord early rather than late.
+
+## System requirements
+
+| | Minimum | Notes |
+|---|---|---|
+| OS | Linux, macOS, or Windows 11 + WSL2 | Linux native is the smoothest |
+| Python | 3.11 (3.12 works) | not 3.13 — no `jaxlib` wheel |
+| RAM | 8 GB | 16 GB is more comfortable |
+| Disk | ~6 GB | ~2 GB of that is the ROS 2 Docker image |
+| GPU | not required | Stage 4 uses a free Colab T4; everything else is CPU |
+| Docker | required for Stage 5 | or a native ROS 2 Jazzy install |
+
+Stages 1–3 and 5 run on any laptop. Stage 4 is the only one that wants a GPU,
+and there is a Colab notebook for it.
+
+
+## Tests and markers
+
+Your progress bar is:
+
+```bash
+uv run python scripts/progress.py          # per-stage checklist
+uv run python scripts/progress.py --slow   # also runs the PPO smoke test
+```
+
+Tests report **▷ NOT STARTED** (the function still raises `NotImplementedError`),
+**✗ FAILED** (you wrote something and it's wrong), or **✓ PASSED**.
+
+| Marker | Needs | Runs by default? | Command | What it covers |
+|---|---|---|---|---|
+| *(none)* | CPU only | yes | `pytest` | Stages 1–3 and the Stage 4 export equivalence check |
+| `slow` | CPU, under a minute | yes | `pytest -m slow` | the Stage 4 `cpu_smoke` PPO run, end to end |
+| `gpu` | an NVIDIA GPU | auto-skipped without one | `pytest -m gpu` | JAX really is on the GPU; vmapped env throughput |
+| `ros` | the ROS 2 container | auto-skipped outside it | `pytest -m ros` inside the container | `policy_node`'s observation, ordering, and 50 Hz publish |
+
+Stage 5 as a whole is checked by `tests/test_05_ros2_smoke.sh`, which runs the
+`ros` tests and then launches the real stack. It runs inside the container:
+
+```bash
+docker compose -f docker/compose.yaml run --rm ros2 /ws/tests/test_05_ros2_smoke.sh
+```
+
+The default CPU suite finishes in well under ten minutes.
+
+## Submission
+
+1. Commit your work, plus a `results/` directory containing your learning-curve
+   PNG, `eval_training.json`, `eval_sim2sim.json`, and your GIFs.
+2. Fill in [`SUBMISSION.md`](SUBMISSION.md) — the stage checklist, your pasted
+   `scripts/progress.py` output, your eval numbers, any escape hatches you used,
+   the Stage 5 reflection paragraph, and what was hardest.
+3. Push to your own `onboarding-fall26` repository.
+4. **DM the software lead (Henry Tsay) on Discord once you are done or show it at a meeting.**

SUBMISSION.md

@@ -0,0 +1,91 @@
+# Submission — HRC Software Onboarding Fall 2026
+
+**Name:**
+**Discord handle:**
+**Repository:**
+**Date:**
+
+---
+
+## Stage checklist
+
+- [ ] **Stage 0** — Setup. `scripts/check_setup.py` exits 0.
+- [ ] **Stage 1** — MuJoCo + PD controller. Tests green.
+- [ ] **Stage 2** — JAX exercises. Tests green.
+- [ ] **Stage 3** — MJX environment. Tests green.
+- [ ] **Stage 4** — Brax PPO. Trained a policy, exported it, `NumpyPolicy` matches.
+- [ ] **Stage 5** — ROS 2 sim2sim. Smoke test green, teleop GIF recorded.
+
+## `scripts/progress.py` output
+
+<details>
+<summary>paste the full output here</summary>
+
+```
+$ uv run python scripts/progress.py --slow
+
+(paste)
+```
+
+</details>
+
+## Stage 4 — training results
+
+**Config used:** (`full` / `t4_fast` / other) &nbsp; **Seed:** &nbsp;
+**Where it ran:** (Colab T4 / local GPU / …) &nbsp; **Wall-clock:**
+
+Learning curve: `results/learning_curve.png`
+Rollout GIF: `results/training.gif`
+
+```json
+(paste results/eval_training.json)
+```
+
+Did it meet the acceptance criteria (`"walking_passes": true`)?
+
+## Stage 5 — sim2sim results
+
+Teleop GIF: `results/sim2sim_teleop.gif`
+
+```json
+(paste results/eval_sim2sim.json)
+```
+
+Measured `/pup/joint_command` rate from `ros2 topic hz`:
+
+## Escape hatches used
+
+- [ ] I used `checkpoints/pup_joystick_flat_reference.npz` for Stage 5 instead
+      of my own policy.
+- [ ] Other (describe):
+
+*(Using one is fine. Not declaring one is not.)*
+
+## Reflection — Stage 5
+
+**List two ways sim2sim can pass while real hardware still fails, and what you
+would add to the sim node to catch each.**
+
+>
+
+## What was hardest?
+
+One paragraph. This is will help us improve onboarding.
+
+>
+
+## Time spent
+
+| Stage | Hours |
+|---|---|
+| 0 Setup | |
+| 1 MuJoCo + PD | |
+| 2 JAX | |
+| 3 MJX env | |
+| 4 Brax + export | |
+| 5 ROS 2 | |
+| **Total** | |
+
+---
+
+**Then DM the software lead (Henry Tsay) on Discord or show during a meeting.**

checkpoints/README.md

@@ -0,0 +1,55 @@
+# Checkpoints — the Stage 5 escape hatch
+
+## What's here
+
+`pup_joystick_flat_reference.npz` — a trained, exported Pup joystick policy, in
+the format `pup/train/export.py` produces and `pup/policy/mlp_numpy.py` loads.
+
+## Why it exists
+
+**No stage may be a dead end.** Stage 5 (ROS 2) is worth doing even if Stage 4
+(training) did not converge for you — the two teach completely different things,
+and getting stuck on one should never cost you the other.
+
+So if your own policy doesn't walk: use this one.
+
+```bash
+ros2 launch pup_bringup sim2sim.launch.py \
+  policy_path:=/ws/checkpoints/pup_joystick_flat_reference.npz
+```
+
+That is the default path in the launch file, so this is also what happens if you
+pass nothing.
+
+**Say so in `SUBMISSION.md`.** There is a checkbox for it. Declaring an escape
+hatch costs you nothing; quietly pretending you trained it costs you the
+reviewer's trust, and they can tell — your `results/` has to contain a learning
+curve and an eval JSON from your own run either way.
+
+## Using your own instead
+
+```bash
+uv run python -m pup.train.export \
+  --checkpoint runs/colab/policy.pkl \
+  --out results/my_policy.npz
+```
+
+Then point `policy_path` at it. Commit it — it is a couple of hundred kilobytes.
+
+## What's inside the file
+
+```python
+import numpy as np
+archive = np.load("checkpoints/pup_joystick_flat_reference.npz")
+print(archive.files)
+print(str(archive["obs_layout"]))
+```
+
+`obs_mean` / `obs_std` (the observation normalizer), `kernel_i` / `bias_i` for
+each MLP layer in forward order, and metadata: `n_layers`, `obs_size`,
+`action_size`, `action_scale`, `default_pose`, `hidden_activation`,
+`obs_layout`.
+
+`obs_layout` is the important one. It is the authoritative statement of what the
+45 numbers mean, travelling inside the file with the weights, so that a policy
+and a robot can never quietly disagree about it.