A Step-by-Step Run Log for Reproducible Robot Simulation: Inputs, Observations, Exceptions and Owner

Reproducible robot simulation depends less on the visual fidelity of a mesh than on whether another engineer can repeat a run and obtain the same numerical outcome. On robo3dlearning.com, which focuses on reproducible robot simulation, the practical unit of work is not a screenshot or a video but a written run log. A run log captures the inputs supplied to the simulator, the observations recorded during execution, the exceptions encountered along the way, and the person accountable for the entry. When teams keep such records, comparisons between simulation frames, inertia values, or camera poses become traceable rather than speculative.

Why a Written Run Log Matters for Simulation Work

A simulation run is a process that transforms input assets into output data. The PROV Model Primer describes provenance as a record of the entities, activities, and agents involved in producing a piece of data, and gives a vocabulary for saying how something came to be. In robot simulation, the entity might be a URDF description, the activity the physics stepping loop, and the agent the engineer who launched the job. Without a log, a discrepancy between two runs is hard to diagnose: one may have used a different solver iteration count, another a modified joint limit, and neither difference is visible in the rendered result. Writing down what was supplied and what was seen makes the difference between a debugging session and a guess.

The habit also supports asset provenance. When a collision model is derived from a published mesh rather than the visual mesh used for display, the log should state which asset was used and who produced it. This separates published facts from editorial inference, a concern we return to in /type/17.html where provenance records for simulation assets are treated in more detail. For now, the point is narrow: a run log is the smallest document that makes a single execution repeatable.

Recording Inputs Before the Simulator Starts

Inputs include the world file, the robot description, the physics parameters, the initial joint states, and any sensor configuration. Each should be named by version or hash where possible, and the command or launch invocation recorded verbatim. If a random seed is used for terrain generation or sensor noise, the seed value belongs in the input block. Teams often overlook the initial time offset or the real-time factor used by the executor; these change the observation timeline even when the nominal physics step is fixed, which is why /type/14.html insists that simulation speed is recorded separately from the physics step before comparing runs.

A hypothetical example may clarify the format. Suppose an engineer configures a mobile manipulator with a lidar sensor and sets the physics step to 1 millisecond with a real-time factor of 0.5; the input block would list the world file path, the URDF revision, the step size, the real-time factor, the seed 20261028, and the launch command. This hypothetical example (假设示例) is not drawn from a published project but shows the fields a log should carry. The owner field names the engineer who assembled the inputs, since later questions about a missing plugin are directed to that person rather than to the group.

Observations During the Run

Observations are the values an engineer actually looks at while the simulation executes: joint position trajectories, contact force spikes, camera image timestamps, and solver convergence messages. They differ from inputs because they are produced by the run rather than supplied to it. The PROV distinction between usage and generation is useful here: the simulator uses the input files and generates the observation stream. Recording observations means copying them into the log with the simulation clock time at which they were seen, not the wall-clock time, because the two diverge when a real-time factor below one is used.

When a simulated camera produces images, the pose logged at the moment of capture is not the same as its calibration, a separation explored in /type/25.html. The run log should therefore note both the transform topic values read from the simulator and the intrinsic parameters loaded from the configuration file. If a trajectory deviates from the planned path, the deviation magnitude and the joint at which it first appears are worth writing down, because they point to a specific body rather than to the whole model.

Exceptions and Their Context

Exceptions include solver failures, missing plugin warnings, out-of-range joint commands, and asset loading errors. Each exception entry should contain the simulation time, the message text, and whether the run continued or aborted. A common exception in practice is a deprecated inertial tag that the parser accepts with a warning; if the warning is not logged, a later reviewer may believe inertia was validated when it was merely ignored. Another is a timeout in the sensor bridge that silently drops frames; the count of dropped frames is an exception observation even though no error dialog appeared.

Context matters as much as the message. An exception raised after a parameter change is likely caused by that change, whereas the same message during an unchanged run suggests an environment difference such as a library version bump. The log should therefore mark the preceding input modification, if any, so the exception is read against the correct baseline. The owner of the exception entry is usually the person monitoring the console, but if an automated harness caught it, the harness name and its maintainer should be recorded instead.

Assigning an Owner and Reviewing the Entry

Every log entry needs an accountable individual. In provenance terms, the agent is responsible for the activity that produced the entity; in a team setting this means the run log carries a name or identifier rather than only a machine hostname. The owner answers questions about missing fields and confirms that the observations were transcribed without rounding. Review does not mean the owner must have written every line, but that a named person has checked the block before it is archived.

Review also catches the case where an input is described inconsistently across two logs. If one entry says the friction coefficient was 0.8 and a related entry says 0.9 for the same paired run, the mismatch is visible only when both are attributed to owners who can be asked which value was intended. This practice complements the frame comparison discipline described in /type/14.html: a time and a name are attached to the record, not just a numerical result.

From Single Runs to Comparable Records

Individual run logs become useful when several are placed side by side. Differences in outcome are then traceable to differences in input or observation conditions rather than to simulator nondeterminism. The additive manufacturing community has faced a related need for measurement standards as processes mature; NIST additive manufacturing work stresses that comprehensive measurements are critical for industrial use of layered fabrication. Simulation for robots is not fabrication, but the parallel holds: as reproducible robot simulation matures, shared record formats make runs comparable across sites.

The final step is archival with the links intact. A run log should reference the asset provenance note for the mesh it used, the speed and step record for the executor settings, and the camera pose note if sensors were involved. Those three internal anchors — /type/14.html, /type/25.html, and /type/17.html — give a reader the surrounding context without repeating the details. The log itself stays narrow: inputs, observations, exceptions, and owner, written so the next person can run the same thing and see the same numbers.