Checkpoints and simulation state#
A simulation has two things worth keeping. The first is its dynamic state: the numbers the physics solvers advance every step, such as joint positions, velocities, and particle fields. Capturing that state and restoring it later lets you rewind a simulation or reset an environment between episodes, deterministically, from the exact state you left. The second is the scene itself: the entities, their geometry, and every option the scene was created with. Writing that to a file lets someone else open the very scene you built, on a machine holding none of the assets you built it from.
Genesis World offers four ways to keep them, which answer different needs.
Dynamic state, in memory:
scene.get_state()returns aSimStateobject, andscene.reset(state=...)writes it back. Fast, and the basis of episode resets in reinforcement learning.The whole scene and its state, in memory: the pickle protocol.
pickle.dumps(scene)gives a built copy that steps on exactly as the original, andscene.__getstate__()andscene.__setstate__()save and restore a built scene in place. Use it to checkpoint a run, or to hand a scene to another process.The scene, on disk:
scene.export(path)writes a.gscenefile, andgs.Scene.load(path)opens it into a new scene, ready to build. Use it to share a scene, attach one to a bug report, or rebuild one without its assets.A run, on disk:
scene.save_checkpoint(path)writes the scene with every array of its simulation, andscene.start_recording(gs.recorders.TrajectoryFile(...))writes a frame per step.gs.Scene.load_checkpoint(path)andgs.Scene.load_trajectory(path)open them in a built scene, to resume, seek, and replay, on any machine and backend.
A state snapshot assumes the scene it came from is already built. A scene file carries no simulated state, so a scene opened from one stands at the configuration its entities were given, and the state has to be reproduced by stepping it again. A checkpoint or a trajectory carries both, so the scene it opens stands where the recorded one stood.
State model#
A snapshot captures only the dynamic state: the fields that change as the simulation steps. It does not capture the scene’s structure: the entities, their morphs, the solver options, or the number of environments. That structure is fixed by how you build the scene, and restoring a snapshot assumes it is already in place.
SimState: the object returned byscene.get_state(). It holds one per-solver state object for each active solver, batched over environments.Dynamic state: positions, velocities, and the internal fields each solver integrates. This is what a snapshot holds.
Static structure: entities, morphs, geometry, and solver configuration. A snapshot leaves it out, and a scene file is how it travels (see below).
Because structure is not part of the snapshot, a snapshot is only valid for the scene it was taken from, or one built the same way. Restoring into a scene with different entities or solver options is undefined.
Snapshot and restore in memory#
scene.get_state() reads the current state into a SimState. scene.reset() returns the scene to a stored initial state, and scene.reset(state=...) restores an arbitrary snapshot:
scene.build()
for _ in range(100):
scene.step()
state = scene.get_state() # snapshot the state at step 100
for _ in range(50):
scene.step()
scene.reset(state=state) # rewind to the snapshot; the physics continue from there
A reset also sets the simulated time of the environments it touches back to zero, whichever snapshot it restores, so scene.get_time() counts from the reset rather than from the build.
Warning
Passing state to reset() also registers it as the scene’s initial state. A subsequent bare scene.reset() returns to this snapshot, not to the state the scene had at build time. Keep a separate reference to your build-time state if you need both.
The per-solver state objects are plain attribute holders. The rigid solver’s state carries qpos, dofs_vel, links_pos, and links_quat; reading one field looks like this:
state = scene.get_state()
rigid_state = state.solvers_state[scene.solvers.index(scene.rigid_solver)]
qpos = rigid_state.qpos # shape ([n_envs,] n_qs)
The differentiable example examples/deformable/differentiable_push.py uses this pattern: it calls scene.reset() to restart each optimization pass from a fixed initial state, and reads scene.get_state().solvers_state[...] to compute a loss from particle positions mid-rollout.
Resetting environments in parallel simulation#
In parallel simulation, the state is batched over environments, and reset() takes an envs_idx argument so you can reset a subset without disturbing the rest. This is the mechanism behind per-environment episode resets in reinforcement learning: when some environments finish, you restore only those to the initial state and let the others keep running.
scene.build(n_envs=4096)
init_state = scene.get_state() # the state all environments reset to
for step in range(episode_length):
scene.step()
obs, reward, done = get_observations()
if done.any():
done_envs = torch.where(done)[0] # indices of finished environments
scene.reset(state=init_state, envs_idx=done_envs)
envs_idx: the environments to reset, as any array-like of indices.None(the default) resets every environment.Partial reset: with
envs_idx, only the selected environments take the new state; the others advance uninterrupted.
envs_idx applies only to a scene built with environments, so on a non-parallelized scene it raises.
Checkpointing a built scene#
A SimState holds what you read back as positions and velocities. A checkpoint holds everything a step reads from one step to the next: the reduced-space state and the control inputs, the contacts and the constraint solution, the warm-start caches, and the link and geom poses the last step derived. Stepping a restored scene therefore lands bit-for-bit where the original went, on every backend.
The checkpoint is the pickle protocol. scene.__getstate__() returns a SceneCheckpoint: the scene description, the environment layout the scene was built with, and the arrays of every solver, copied where they live, so a save and a restore within one process stay on the device. scene.__setstate__(checkpoint) puts a scene built from the same description and layout back in that state, and rejects a checkpoint from another build by the name of what differs. Pickling a scene reads the same record, and unpickling creates and builds the scene before restoring it:
import pickle
scene.build(n_envs=16)
for _ in range(100):
scene.step()
checkpoint = scene.__getstate__() # a device-resident copy of the state at step 100
twin = pickle.loads(pickle.dumps(scene)) # a built copy of the scene, standing at step 100
for _ in range(50):
scene.step()
scene.__setstate__(checkpoint) # back to step 100, and the next 50 steps land where they did
A restore also restarts what surrounds the state, as a reset does: the gradient tape, the sensors, and the recorders forget the run that led there, and the viewer redraws. The simulated time of each environment comes back as recorded, since it is state. A differentiable scene carries the gradients of its arrays along, so a checkpoint taken after a backward pass restores them.
Checkpoint and trajectory files#
scene.save_checkpoint(path) writes a .gstraj file holding the scene as export writes it and every array of the simulation, scratch buffers included, so the exact state of a failing run is kept for inspection. gs.Scene.load_checkpoint(path) creates and builds the scene and restores that state:
scene.save_checkpoint("failing.gstraj")
scene = gs.Scene.load_checkpoint("failing.gstraj", show_viewer=True)
scene.step() # continues from the saved state
A trajectory is a checkpoint per step. Register a TrajectoryFile with scene.start_recording before the build, and every step appends a frame until scene.stop_recording(), which also records the state the run stopped at:
scene.start_recording(gs.recorders.TrajectoryFile(filename="run.gstraj"))
scene.build()
for _ in range(1000):
scene.step()
scene.stop_recording()
Every frame is kept. A step only copies its frame aside, without waiting for a GPU to finish the step, while a thread of its own compresses the frames and another writes the file, so recording holds real time on a single environment. Two modes trade size for exactness, and mode picks one:
Exact: a replay is bit-for-bit, and the simulation resumes from any frame exactly as it ran, but recording slows the simulation down significantly for large batch sizes.
Minimal: frames hold only the bare minimum state, which makes them far smaller: everything else is recovered by running a full simulation step, and may differ at the last bits, except the contacts of hibernated links, which are taken from the scene as it stood before the seek. A replay that plays the frames in order from the first one in a freshly loaded scene is unaffected.
By default a trajectory records in exact mode as long as a frame stays within 4 MiB, and in minimal mode otherwise, since every recorded step copies a whole frame.
hz records every few steps, chunk_size sets how many frames a chunk holds (larger chunks compress better and seek slower), and max_size caps the file, closing it as a valid log and raising at the next step past the cap, so a run left recording fills the disk by at most 2 GiB by default.
gs.Scene.load_trajectory(path) creates and builds the recorded scene and returns a Trajectory that plays in it. Frame i is the state after i steps; seek(i) puts the scene there, play() seeks every frame and redraws the viewer at the pace the recording ran at, frame(i) returns the arrays of a frame by name, time(i) the simulated time of each environment, and timings(i) the wall time of each phase of the step that led to frame i, as scene.timings names them. A negative index counts from the end. A file written in an earlier version of the format is refused, with its version named. The last frame, like a checkpoint file, holds every array but the configs and constants, the scratch of the solvers included, for the analysis of a failure that may depend on the platform and never reproduce once shared:
trajectory = gs.Scene.load_trajectory("run.gstraj", show_viewer=True)
trajectory.seek(500)
trajectory.scene.step() # steps on from frame 500 as the recorded run did
trajectory.play(loop=True) # replays until the viewer is closed
A trajectory replays on another machine, backend, or precision: the frames are shaped by the options, the description, and the number of environments, and their values are cast to the precision of the session. From the command line, gs replay run.gstraj opens the recorded scene in the viewer and plays it in a loop.
What a snapshot contains#
The dynamic state each solver contributes to a SimState:
Solver |
State fields |
|---|---|
Rigid |
|
Kinematic |
|
MPM |
|
SPH |
|
PBD |
|
FEM |
|
Reproducibility notes#
Configuration must match. A snapshot restores fields by position into an already-built scene. The entities, solver options, and environment count must match the scene that produced it. There is no compatibility check: a mismatch fails or silently corrupts state. A checkpoint or a trajectory frame restores arrays by name and checks their shapes, so one from another build is rejected and named. Both also carry a digest of the scene description, its entities and physics options, and restore only into a scene sharing it, whatever its viewer, visualizer and renderer options. The digest exports the description in memory, meshes included, once per built scene and once per trajectory opened, never per restore.
Precision limits exactness. Genesis World uses 32-bit floats by default (see Initialization and backends). Reproducing a run by stepping a loaded scene, or restoring a snapshot that went through a file, is therefore accurate to roughly single precision, not bit-exact. Initialize with
precision="64"if you need tighter reproducibility.
See also#
Parallel simulation: how state is batched over environments.
Scene API: the full signatures of
get_state,reset,export,load,save_checkpoint,load_checkpoint, andload_trajectory.Recording data: the recorder framework a trajectory is recorded through.