Preview

A preview runs your task without training a policy. It checks how the robot starts, how its joints respond, and whether the task behaves under the same step loop training uses. Run it before you pay for training time, and run it again after every change to the robot or task.

Preview checks whether the scene and task are ready to train. After training, evaluation measures the checkpoint against your success rule over fixed episodes.

simulo create NAME writes preview.py next to task.py and train.py:

import simulo

from task import StarterTask, app


@app.job(type="preview", system=simulo.SystemType.TIER_1, timeout=15 * 60)
def preview(num_envs: int = 16, checks: str = "all"):
    return simulo.preview(StarterTask(), num_envs=num_envs, checks=checks, video=True)

Run it like any other job:

simulo run preview.py

After a fix, re-run one check quickly with simulo run preview.py --checks settle. The --checks option accepts all or a comma-separated list of settle, joint-sweep, random-moves, training-loop, and action-map.

The preview returns a report and writes one MCAP recording. It makes no policy.

The four checks

The checks run in this order:

Check	What it looks for
Settle	Leaves the robot alone for two simulated seconds. It fails if state becomes non-finite, a joint exceeds the explosion speed, the base goes more than 0.25 m below the floor, or driven joints and the base do not come to rest. Motion from a passive joint is a warning.
Joint sweep	Commands each driven joint directly and watches whether it reaches or holds its target without exploding or oscillating. A joint with no stiffness or damping is not swept and produces a warning.
Random moves	Runs the task’s real step loop for ten simulated seconds with random actions in every preview environment. It checks for non-finite state, excessive joint speed, and a robot that moves more than 50 m from its environment’s origin.
Training loop	Runs random-action and zero-action passes, then moves each action dimension at +1 and -1. It checks observation size, finite observations and rewards, episode length, resets, and which joints each action moves.

A warning does not fail a check. The whole preview fails only when at least one check has a failing finding.

Read a finding

Each warning or failure answers four questions:

• Problem says what the preview observed.
• Fix gives the first thing to change.
• Owner says whether the evidence points to your task, your robot, either one, or Simulo.
• In the recording gives the time, time range, and environment where the finding appears. Some findings also include measured Detail.

For example, a robot that starts below the floor produces a finding like this:

  Settle          Failed
    ✗ Robot stays above the floor
      Problem: The robot's base was more than 0.25 m below the floor.
      Fix: Preview cannot tell which caused this: raise the spawn pose (initial_pose in build() or the pose reset_idx() sets) or repair the robot's collision mesh.
      Owner: Your task or your robot
      Detail: lowest base height -0.35 m above the floor
      In the recording at <time> s, environment 0

Fix the named problem, then run the preview again. A failed check does not prevent you from submitting a training job, so the report is the point where you decide whether the task is ready.

Exit codes

simulo run preview.py exits with:

Exit code	Meaning
0	Every check passed. Warnings are allowed.
1	At least one check failed. The preview job still completed and kept its report and recording.
2	The job failed, timed out, was cancelled, or returned no valid preview report.

The CLI also compares a completed report with the newest earlier completed preview for the same job name and task. This helps you see which check statuses changed after an edit.

Open the recording

The report ends with the command for its recording:

Recording:  simulo recordings job_<adjective>-<noun>-<suffix>

Run it to download the MCAP file:

simulo recordings job_<adjective>-<noun>-<suffix>

The recording holds the robot’s joint positions and velocities, its base pose, and every finding at the time it describes. With the starter’s video=True, it also includes video from the camera the preview adds. The download writes Lichtblick and Foxglove layout files next to the MCAP file, with panels for the video, environment 0’s joint positions, and the findings.

Recordings & live view explains MCAP recordings and how to open them. For a complete fix-and-rerun workflow, see Preview before training.

What it helps you troubleshoot

Preview catches scene mistakes before training spends GPU time on them: a robot that starts under the floor or inside another object, episodes that end at once, and a reset that does not restore the starting state. Each finding names the task method to inspect. Troubleshoot a scene with preview walks through each case from the report to the fix. Problems that only show up in a trained policy, such as a reward that pays for the wrong thing, need evaluation; see Troubleshoot a policy with evaluation.