MuJoCo foundations
Physics and control on the laptop: hand-written PD, a scripted fish gait, then a small PPO swimmer. Everything lands in the harness.
Weeks 1–2 · Sim only · MacBook · $0 · 01_mujoco_foundations/




Goal
Load a stock MJCF model, step physics, and open the viewer. Learn the XML: bodies, joints, actuators, geoms, contacts. Write PD by hand on a pendulum (do not import a controller). Tune until it holds a setpoint, then put the same gains on a double pendulum and write why it fails. Write down the observation vector, action units, and loop rate. Build a 3–5 link robotic fish with a CPG gait on MuJoCo hydrodynamics. Learn the same behaviour with a small PPO run toward randomized targets. Compare scripted vs learned on the same held-out set. Change one reward term. Ship common/eval_harness/ v0 with run_type already accepting sim | real | paired.
Why it matters
This lab repeats one pattern: model something, write a controller, test on data you held out, log it, then fix what was wrong. Project 1 does that once on a laptop so the pieces are concrete before anything expensive depends on them. Cartpole as the whole project is out. A balanced pole convinces nobody. The fish stays in sim on purpose. Waterproofing a printed fish is a month of sealing and servo failures with almost no sensing, and there would be no sim-to-real gap to measure. Put “real” on the harness schema now or you re-instrument everything later.
The work
- 01
Load a stock MJCF model, step physics, render the viewer. Learn bodies, joints, actuators, geoms, contacts.
- 02
Write PD by hand on a pendulum. Tune until it holds a setpoint. Carry the same gains to a double pendulum and write why it fails.
- 03
Write down observation contents, action units, and loop rate. This is the most common later bug source.
- 04
Build a 3–5 link swimmer with a CPG gait (sinusoidal joints, phase-offset down the body, PD-tracked) on MuJoCo hydrodynamics.
- 05
Small PPO run toward randomized targets. Compare against the scripted gait on the same 20 held-out targets. Change one reward term; capture before/after.
- 06
Ship common/eval_harness/ v0 logging every run, with run_type: sim | real | paired.
Done looks like
- p1/SETUP.md with exact package versions and a one-command repro script.
- A video of the fish swimming under the scripted CPG gait.
- A video of the fish swimming under the learned PPO policy.
- Results table: scripted vs learned on 20 held-out targets (distance-to-target, time-to-reach, path efficiency).
- One reward-term change with a before/after behaviour clip and the numbers.
- common/eval_harness/ v0 logging every run above, run_type already accepting sim | real | paired.
Stack card
| Simulator | MuJoCo 3.x (native Apple Silicon) |
|---|---|
| Trains on | MacBook M4 Max |
| Runs on | MacBook M4 Max |
| Buy | $0 |
| ROS 2 | No |
| Gazebo | No |
| Compute / target | None |
| Install | mujoco, mujoco-python-viewer, numpy, matplotlib, gymnasium, stable-baselines3, Python 3.11, uv or conda |
Repos to study
Watch out
- On macOS the viewer must be launched with mjpython / make view, never plain python.
- Do not overwrite configs/heldout_targets.json. Freeze the set before training.
- The fish stays in sim. Do not spend a month waterproofing a printed fish.
Workstreams
MJCF models, hand-written PD, CPG gait, PPO training on the laptop, SETUP.md and one-command repro.
Frozen 20-target set, scripted-vs-learned table, reward A/B, harness v0 with sim | real | paired.
Cross-check. Either stream can launch make smoke / make eval and read the other's numbers.
What this proves
You can read a simulator’s API, write a controller instead of importing one, and design a held-out experiment before anyone hands you a GPU.
Read a simulator’s API, write a controller instead of importing one, and design a held-out experiment before anyone hands over a GPU.
Study videos
Gear / BOM
