# State teacher, then visual student

Two registered tasks share the standalone UR5/bottle physics, 7 Cartesian/gripper
actions, reachable nominal-TCP goals, upstream lift-cube rewards and strict
lift/hold metrics:

| | State teacher | Visual task |
|---|---|---|
| ID | `Mjlab-GS-Bottle-UR5-State` | `Mjlab-GS-Bottle-UR5` |
| Actor | 37 privileged floats | 16 proprioception + 3 goal + RGB |
| Critic | 37 clean state floats | 62 privileged floats |
| Network | MLP 256–128–64 | ResNet18 + ACT-style transformer (256, 8 heads, 3 encoder / 2 decoder) |
| Camera computation | None | Gaussian + native composite, 320×200 |
| Default training worlds in registered config | 256 | 64 |
| Initial pose DR | Smaller teacher ranges | Broader visual ranges |
| Camera/appearance DR | Omitted | Enabled |

The state observation follows MJLab's native low-dimensional lift-cube recipe,
adapted to this robot and bottle. It is lift-cube-style privileged state, not a
Franka robot model. Tensor order is joint-position offsets (12), joint velocities
(12), TCP-to-bottle in base frame (3), bottle-to-goal in base frame (3), previous
action (7). Noise applies only to the training actor, not the critic/evaluation.
The gripper's coupled linkage joints account for the extra joints beyond the six
arm joints. See [full specification](task.md) for noise and domain ranges.

## Use the canonical tools

```bash
cd ~/mjlab_gs
source env.sh
mjlab-gs list
mjlab-gs view --task Mjlab-GS-Bottle-UR5-State --num-envs 4
mjlab-gs benchmark --task Mjlab-GS-Bottle-UR5-State --num-envs 256 \
  --task-config configs/teacher.json --steps 100
mjlab-gs evaluate --task Mjlab-GS-Bottle-UR5-State --num-envs 8 \
  --episodes 8 --steps 350 --dr-scale 1 --output reports/teacher_eval.json
# Ready for a later training run; not executed for this setup:
mjlab-gs train --task Mjlab-GS-Bottle-UR5-State --num-envs 256 \
  --task-config configs/teacher.json --iterations 3000 --output logs/rl/teacher
# Evaluate the eventual trained teacher:
mjlab-gs evaluate --task Mjlab-GS-Bottle-UR5-State --num-envs 8 \
  --checkpoint logs/rl/teacher/final.pt --episodes 32 --steps 3000
python scripts/evaluate_matrix.py --task Mjlab-GS-Bottle-UR5-State \
  --checkpoint logs/rl/teacher/final.pt --episodes 32
```

Headless state runs initialize no cameras and allocate no image observations.
MJViser can show the mesh scene and goal marker without a Gaussian wrist feed.
The 1 kHz physics, 20 Hz control, IK, and per-substep success metrics remain the
same workload. Benchmark speedups therefore depend on which component dominates.

## Student phase after a teacher succeeds

1. Train and qualify the state teacher over the intended physical distribution.
2. Freeze the teacher and query its state observations on the **same visual-task
   simulator states** that provide RGB/proprioception/goal to the student. Reuse
   the teacher's saved observation normalization and action convention.
3. Distill teacher actions into the visual policy; collecting teacher labels on
   student-driven rollouts (DAgger-style) can address state-distribution drift.
4. Evaluate the student with the same fixed-quota success metrics, then consider
   broader image DR or RL fine-tuning.

Steps 1–4 are the next experiment, not completed work. This update registers both
tasks, enables inference/checkpoint selection and goal-aware visual BC recording,
and validates their interfaces. It does not implement a teacher-label collector,
distillation optimizer or a trained policy. A state teacher checkpoint cannot be
loaded as a visual actor; their observation contracts intentionally differ.
The initial teacher's narrower physical DR must be accounted for when exposing
it to broader visual-task starts.


The visual network emits one 20-Hz action, not an ACT action chunk. It has no
CVAE, uses zero dropout and frozen BatchNorm statistics, and starts without
pretrained weights. Proprioceptive history remains one frame pending a temporal
policy experiment. Teacher MLPs are unchanged.

In the RL experiment workspace, ordinary broad-distribution success below 90%
is acceptable if unreachable starts explain it. The objective is reliable
behavior across reachable poses, assessed with existing graphs/videos and,
where needed, labeled restricted-DR tests using the same success metric. No
separate reachable-only metric or filtering system is requested.