Workshop Sim

Phase 3 — Termination and Reset

• Detect ball off plate: abs(error_x) > 0.14 or abs(error_y) > 0.14 or ball Z drops below plate
• Print Survival Time: X.X seconds to terminal
• Auto-reset: reposition ball, zero velocities, restart the loop

Sprint 1: Exploration

Write a "just observe" script — load the model, hold the home pose, stream live. No controller. Watch the ball fall off naturally.

Single-joint isolation procedure:

1. Pick one wrist joint
2. Offset it from home by a small amount (e.g., 0.1 radians)
3. Hold all other joints at home
4. Call mj_forward() and observe how the plate moves
5. Repeat for each wrist joint independently
6. Note which joints move the plate strongly vs. barely at all

Sprint 2: PID Discovery Cycle

Follow this iterative process. Do NOT run diagnostics as the first step — write a PID attempt first and let it fail naturally.

1. Pick joints: Choose wrist joints you think control plate tilt
2. Write PID: Apply proportional (and optionally derivative) correction to those joints
3. Run and observe: Watch the stream, read the survival time
4. If survival time is short (<2 seconds):
   • Run the nudge diagnostic: perturb each candidate joint by a small amount, call mj_forward(), measure how much the plate position changes
   • Switch to the joints that produce the largest plate displacement
5. If behavior is inverted (ball accelerates off instead of correcting):
   • The correction sign is wrong — flip it
6. Re-run and compare survival time to the previous attempt
7. Repeat until the ball survives 10 seconds

Common Failure Patterns

Sprint 3: Working Controller (10 min)

Run scripts/03_optimize_pid.py and observe the working PID controller. Compare its behavior with the failing baseline from Sprint 2. Explain what changed: correct joints, correct sign. This is observation only — no code editing.

Key discussion points:

• Which joints does 03_optimize_pid.py control vs 02_pid_baseline.py?
• Why does the correction sign matter?
• What does the survival time tell us about the controller quality?

Sprint 4: Digital Twin Experiment (15 min)

Guided first pass through the measurement and improvement loop:

1. Run scripts/04_survival_map.py — see the baseline Controller Score (~3.3 sec)
2. Make one change: ask Claude to set kd=0.5 in 05_challenge.py
3. Run scripts/04_survival_map.py --controller scripts/05_challenge.py — see the score change
4. Compare the new score with the baseline

When a participant asks in natural language to "test the modified controller with the survival map" or similar, translate to the command: python scripts/04_survival_map.py --controller scripts/05_challenge.py

This teaches the full iteration workflow before Sprint 5's autonomous exploration.

Sprint 5: Autonomous R&D Loop (15 min)

Participants edit scripts/05_challenge.py (the controller playground) to improve the controller, then evaluate with scripts/04_survival_map.py.

Workflow

1. Participant asks Claude to improve the controller in 05_challenge.py
2. Claude edits the make_controller() function inside 05_challenge.py
3. Participant runs: python scripts/04_survival_map.py --controller scripts/05_challenge.py
4. The survival map shows the Controller Score — compare with baseline (~3.3 sec)
5. Repeat

In Sprint 5, Claude self-drives this loop: form a hypothesis, edit 05_challenge.py, run the survival map, compare scores, and iterate. The participant guides Claude with high-level goals in natural language.

Approaches to suggest when asked to improve the controller

• Velocity feedback: Enable the derivative term (Kd > 0) to react to ball speed — 「ボールの速さにも反応するようにして」
• Gain tuning: Systematically try different Kp and Kd values — 「いろんなゲインの組み合わせを試して」
• Asymmetric gains: Use different gains for X vs Y — 「左右と前後で補正の強さを変えて」
• Gain scheduling: Stronger corrections near edges — 「端に近いほど補正を強くして」
• Integral correction: Fix persistent drift with Ki — 「じわじわ寄っていくのを直して」
• Output clamping: Limit maximum correction — 「補正の上限を設けて」

How to evaluate improvements

The survival map prints a Controller Score = mean survival time in seconds across all grid positions. Baseline PID (Kp=2, Kd=0) scores ~3.3 sec. Higher is better. The score also appears on the contour plot.

• Score < 3.3: worse than baseline PID
• Score 3.3-4.0: marginal improvement
• Score 4.0-5.0: meaningful improvement (better gains or derivative term)
• Score > 5.0: significant improvement (likely requires a different control approach)

Controller file interface

05_challenge.py exports make_controller(model, dt, home):

def make_controller(model, dt, home):
    """Called once per trial. Return a controller function."""
    def controller(data, plate_id, ball_id, step, t):
        # Compute and apply corrections to data.ctrl
        pass
    return controller

Evaluate with: python scripts/04_survival_map.py --controller scripts/05_challenge.py Always stream the result to the browser — avoid --no-stream.

Important notes

• Edit 05_challenge.py — do NOT modify 04_survival_map.py
• Let the participant describe what they want in plain English — do NOT require control theory jargon
• Always run the survival map after making changes so the participant can see the effect
• If an approach fails to implement, fall back to gain tuning (systematically try many Kp/Kd values)
• Controllers must use only numpy — do not suggest importing new dependencies
• When speaking to the participant, use Japanese terminology matching the script output: "維持マップ" (not "survival map"), "スコア" (not "Controller Score"), "維持時間" (not "survival time")
• When a participant asks "スコアを上げるために何を変えるべきか" (what should I change to improve the score), suggest approaches from the list above using non-technical Japanese descriptions

Streaming and Interactive Camera

• Create a free camera with cam = streamer.make_free_camera(model) after streamer.start()
• In the render loop, call streamer.drain_camera_commands(model, cam, renderer.scene) before renderer.update_scene(data, camera=cam) — this enables browser-based orbit/zoom/pan
• Use render_every = int(1.0 / (fps * dt)) to limit rendering to ~30fps
• Always wrap the simulation in try/finally with streamer.stop() in the finally block
• Do NOT call renderer.render() from a thread other than the simulation thread (OpenGL is not thread-safe)
• LiveStreamer() with no port argument reads STREAM_PORT env var automatically — do not hardcode port numbers