Options system#
Genesis World is configured through options objects: small, typed parameter groups under gs.options.* that you pass to gs.Scene(...) and to scene.add_entity(...). Rather than have a scene accept dozens of loose keyword arguments, we give each concern its own object with its own defaults: one for the global simulator, one per physics solver, one for the viewer, and one per renderer. This page explains what those objects are, how they compose into a scene, and how we resolve a setting given in two places.
If you have not built a scene yet, read Hello, Genesis World first. It uses SimOptions and ViewerOptions in passing. This page is the conceptual reference behind that usage.
Composing a scene from options#
Every configurable component of a scene is described by one options object. Construct the objects you care about and hand them to the scene; anything you omit uses its defaults.
import genesis as gs
gs.init(backend=gs.gpu)
scene = gs.Scene(
sim_options=gs.options.SimOptions(dt=0.01, gravity=(0, 0, -9.81)),
rigid_options=gs.options.RigidOptions(enable_collision=True),
viewer_options=gs.options.ViewerOptions(
camera_pos=(3.5, 0.0, 2.5),
camera_lookat=(0.0, 0.0, 0.5),
camera_fov=40,
),
show_viewer=True,
)
The options split into three roles, plus a set of per-entity options passed to add_entity rather than to the scene:
Global.
SimOptionssets the properties of the simulation as a whole, and the coupler options set how solvers interact.Per solver. One options object per physics solver (rigid, MPM, SPH, FEM, SF, PBD), each configuring that solver alone.
Visualization. The viewer, the solver-independent visualization, and the renderer.
Solver options override simulator options#
SimOptions holds settings that are global by default: most importantly the timestep dt (seconds) and gravity (m/s², pointing down -Z). Each solver also exposes those same settings on its own options object, where they default to None.
A value set on a solver’s options overrides the global SimOptions value, for that solver only, and a solver whose field is left at None inherits the global value.
SimOptions.dt is how much simulated time one scene.step() advances. A solver’s dt is the interval it integrates over, so it must divide the step a whole number of times, and that quotient is the number of substeps per step. Every active solver advances together, so the count one solver asks for is the count they all take, and two solvers asking for different intervals raise. SimOptions.substeps requests the same count directly, and setting both raises unless they agree.
scene = gs.Scene(
sim_options=gs.options.SimOptions(dt=0.01), # one step advances 0.01 s
rigid_options=gs.options.RigidOptions(dt=0.005), # two substeps per step, for every solver
# mpm_options left unset -> the MPM solver, if used, integrates twice per step as well, over 0.005 s
)
The same inheritance applies to gravity, and each solver keeps its own value, so read it back from the solver simulating the entity, for example scene.rigid_solver.get_gravity(envs_idx). A scene coupling its solvers through IPC applies the SimOptions gravity to every body it couples, so a coupled solver authoring a different one raises at build time. Settings that are meaningful only to one solver (for example RigidOptions.constraint_solver or RigidOptions.max_collision_pairs) live solely on that solver’s options and have no global counterpart.
Scene-level option groups#
Each of these is an optional argument to gs.Scene(...).
Options class |
|
Configures |
|---|---|---|
|
Global timestep, gravity, substeps, differentiable mode. |
|
|
Coupling between solvers. Concrete variants: |
|
|
Rigid-body dynamics: contact, collision, constraints, integrator. |
|
|
Material Point Method solver (elastic, plastic, granular, fluid). |
|
|
Smoothed Particle Hydrodynamics solver (fluids, granular flow). |
|
|
Finite Element Method solver (elastic material). |
|
|
|
Stable Fluid solver (Eulerian gaseous simulation). |
|
Position-Based Dynamics solver (cloth, deformables, liquids, particles). |
|
|
Kinematic (non-dynamic) entities. |
|
|
|
Legacy tool solver. Slated for deprecation. |
|
Visualization independent of any viewer or camera. |
|
|
The interactive viewer: camera pose, resolution, refresh rate. |
|
|
Timing and FPS reporting. |
|
|
Rendering backend: |
The solver and coupler options are documented beside their solver and coupler in the physics engine reference, the global SimOptions under Scene, and the viewer, visualization, and renderer options in the visualization reference.
Note
Not every solver runs in every scene. A solver is active only once you add an entity whose material targets it: adding a rigid entity activates the rigid solver, and so on. Options for an inactive solver are simply unused.
Per-entity options#
add_entity takes its own options describing a single entity rather than the scene:
franka = scene.add_entity(
morph=gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"),
material=gs.materials.Rigid(),
surface=gs.surfaces.Default(),
)
Morph: the entity’s geometry and initial pose. See Hello, Genesis World for loading morphs and the morph API.
Material: how the entity responds to physical forces, and which solver simulates it. See Beyond rigid bodies.
Surface: how the entity looks when rendered. See Surfaces and textures.
See also#
Hello, Genesis World: the minimal scene that uses these options.
Visualization: the interactive viewer and command-line tools.
Rendering: cameras, image types, video, and rendering backends.
API Reference: each option class, documented with the component it configures.