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. SimOptions sets 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.

Every options object shares one base#

All gs.options.* classes derive from gs.options.Options, a Pydantic model. Two properties of that base matter in practice:

  • Fields are typed and validated on construction. A value of the wrong type, or out of range, raises immediately with a readable message, not deep inside the first scene.step().

  • Unknown fields are rejected. The base sets extra="forbid", so a misspelled argument such as gravty=(0, 0, -9.81) raises Unrecognized attribute 'gravty' instead of being silently ignored.

You never instantiate Options directly; you always use a concrete subclass. Each option class is documented in the API Reference alongside the component it configures.

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

Scene argument

Configures

gs.options.SimOptions

sim_options

Global timestep, gravity, substeps, differentiable mode.

gs.options.BaseCouplerOptions

coupler_options

Coupling between solvers. Concrete variants: LegacyCouplerOptions, SAPCouplerOptions, IPCCouplerOptions.

gs.options.RigidOptions

rigid_options

Rigid-body dynamics: contact, collision, constraints, integrator.

gs.options.MPMOptions

mpm_options

Material Point Method solver (elastic, plastic, granular, fluid).

gs.options.SPHOptions

sph_options

Smoothed Particle Hydrodynamics solver (fluids, granular flow).

gs.options.FEMOptions

fem_options

Finite Element Method solver (elastic material).

gs.options.SFOptions

sf_options

Stable Fluid solver (Eulerian gaseous simulation).

gs.options.PBDOptions

pbd_options

Position-Based Dynamics solver (cloth, deformables, liquids, particles).

gs.options.KinematicOptions

kinematic_options

Kinematic (non-dynamic) entities.

gs.options.ToolOptions

tool_options

Legacy tool solver. Slated for deprecation.

gs.options.VisOptions

vis_options

Visualization independent of any viewer or camera.

gs.options.ViewerOptions

viewer_options

The interactive viewer: camera pose, resolution, refresh rate.

gs.options.ProfilingOptions

profiling_options

Timing and FPS reporting.

gs.renderers.RendererOptions

renderer

Rendering backend: Rasterizer, RayTracer, or BatchRenderer.

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(),
)

See also#