Preview before training

A preview checks your robot inside your task before you spend time training it. It makes no policy. This guide uses the preview.py that simulo create writes, then introduces a bad starting pose so you can follow a failure from the report to the fix.

1. Run the preview

From the app folder:

simulo run preview.py

The starter runs all four checks. A passing report for its cartpole has this shape:

PREVIEW  job_<adjective>-<noun>-<suffix>

No earlier completed preview matched this task.

  Settle          Passed with warnings
    ⚠ cart_to_pole comes to rest
      Problem: cart_to_pole is passive and still swinging at the end.
      Fix: Add damping to the robot's joint if it should come to rest.
      Owner: Your robot
      Detail: cart_to_pole: tail mean speed <speed> rad/s; final position <position> rad
      In the recording at <time> s (to <time> s), environment 0
    ✓ Driven joints and base came to rest
      base stayed still; base height <height> m above the floor; slider_to_cart tail mean speed <speed> m/s; nothing fell through the floor
      In the recording at <time> s (to <time> s), environment 0
  Joint sweep     Passed with warnings
    ✓ slider_to_cart responds to its velocity target
      slider_to_cart: velocity sweep, target -<speed> m/s; held for <time> s; tail mean error <speed> m/s; reached the commanded joint limit
      In the recording at <time> s (to <time> s), environment 0
    ✓ slider_to_cart responds to its velocity target
      slider_to_cart: velocity sweep, target +<speed> m/s; held for <time> s; tail mean error <speed> m/s; reached the commanded joint limit
      In the recording at <time> s (to <time> s), environment 0
    ✓ slider_to_cart responds to its velocity target
      slider_to_cart: velocity sweep, target +<speed> m/s; held for <time> s; tail mean error <speed> m/s
      In the recording at <time> s (to <time> s), environment 0
    ⚠ cart_to_pole is not driven
      Problem: cart_to_pole has neither stiffness nor damping, so it was not swept.
      Fix: Add stiffness for position control or damping for velocity control to the robot's joint if it should be driven.
      Owner: Your robot
      In the recording at <time> s (to <time> s), environment 0
  Random moves    Passed
    ✓ Stable under random actions
      stable for <time> s of random actions in <n> environments, <resets> resets
      In the recording at <time> s (to <time> s)
  Training loop   Passed
    ✓ Observations stay finite
      observations: 4 values, all finite under random actions
      In the recording at <time> s (to <time> s)
    ✓ Rewards stay finite
      rewards finite under random actions; range -<reward> to <reward>
      In the recording at <time> s (to <time> s)
    ✓ Episodes last long enough
      episodes last <duration> s on average (<steps> steps) under random actions; ended by task <share>%
      In the recording at <time> s (to <time> s)
    ✓ Reset restores the requested state
      <resets> finite, matching resets under random actions
      In the recording at <time> s (to <time> s)
    ✓ Observations stay finite
      observations: 4 values, all finite under zero actions
      In the recording at <time> s (to <time> s)
    ✓ Rewards stay finite
      rewards finite under zero actions; range -<reward> to <reward>
      In the recording at <time> s (to <time> s)
    ✓ Episodes last long enough
      episodes last <duration> s on average (<steps> steps) under zero actions; ended by task <share>%
      In the recording at <time> s (to <time> s)
    ✓ Reset restores the requested state
      <resets> finite, matching resets under zero actions
      In the recording at <time> s (to <time> s)
    ✓ Action 0 moves joints
      action 0 -> slider_to_cart, +<displacement> m at +1, -<displacement> m at -1; action 0 -> cart_to_pole, +<displacement> rad at +1, -<displacement> rad at -1
      In the recording at <time> s (to <time> s)

This preview made no policy.
Recording:  simulo recordings job_<adjective>-<noun>-<suffix>
Next:       simulo run train.py

The cartpole’s passive pole can produce warnings in Settle and Joint sweep. Warnings still exit 0. Read every warning before continuing, since a warning can describe intentional behavior or something you need to change.

2. Read the report

Each row starts with one of three symbols:

Symbol	Meaning
✓	The check passed and reports what it measured.
⚠	The preview found something to review, but the check still passed.
✗	The check failed. Fix the finding before training.

A warning or failure includes the problem, a suggested fix, who owns the likely change, and where to look in the recording. Read Preview for what each check does and how the exit codes work.

When preview fails, troubleshoot a scene with preview to follow a report back to the task code and confirm the fix.

3. Reproduce and fix a failure

To see Settle catch a bad starting pose, temporarily put the robot below the floor in task.py:

self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.identity())
self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.from_xyz(0.0, 0.0, -0.35))

Run the preview again:

simulo run preview.py

The report includes this failure. Settle also flags two joints moving too fast, a side effect of starting below the floor. They are shown as ... here:

  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

The preview job completed and kept its report and recording, but the command exits 1 because a check failed. Restore the starting pose:

self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.from_xyz(0.0, 0.0, -0.35))
self.robot = simulo.Robot(asset=cartpole, initial_pose=simulo.Pose.identity())

Re-run only Settle for a quick check of the fix:

simulo run preview.py --checks settle

--checks accepts settle, joint-sweep, random-moves, training-loop, and action-map. Pass a comma-separated list to run several, or use all to run the full preview. Confirm that Settle passes.

4. Inspect the evidence

Download the failed preview’s recording with the job ID printed by the failed run, not the later Settle recheck:

simulo recordings job_<failed-preview-id>

The download prints the layout files and the MCAP path:

Saved <recording>.lichtblick-layout.json
Saved <recording>.foxglove-layout.json
Open in Lichtblick: <path>.mcap

Open the .mcap file in Lichtblick and import the <recording>.lichtblick-layout.json layout. For Foxglove, import the <recording>.foxglove-layout.json layout. The layout puts video, joint positions, and findings on one timeline, so you can jump to the time named in the report.

5. Train after the preview passes

simulo run train.py

Run the preview again before training whenever you change the robot asset, spawn pose, joints, action mapping, observations, rewards, episode conditions, or reset behavior. Train cartpole continues from this command to the policy and its checkpoints.