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 a scene taking dozens of loose keyword arguments, each concern (the global simulator, one physics solver, the viewer, a renderer) gets its own object with its own defaults. This page explains what those objects are, how they compose into a scene, and how a setting given in two places is resolved.

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.

A scene is assembled from options#

Every configurable component of a scene is described by one options object. You 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; 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, 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. See the Options API for the full class list.

Simulator options override solver options#

SimOptions holds settings that are global by default: most importantly the timestep dt (seconds) and gravity (N/kg, pointing down -Z). Each solver also exposes those same settings on its own options object, where they default to None.

The rule is: a value set on a solver’s options overrides the global SimOptions value, for that solver only. A solver whose field is left at None inherits the global value. This lets most scenes set dt once while allowing a single solver to run at a different rate.

scene = gs.Scene(
    sim_options=gs.options.SimOptions(dt=0.01),        # global timestep
    rigid_options=gs.options.RigidOptions(dt=0.005),   # rigid solver only, overrides the global dt
    # mpm_options left unset -> the MPM solver, if used, inherits dt=0.01
)

The same inheritance applies to gravity. 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(...). Pass an instance to configure that component; omit it to accept the defaults.

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 scene- and solver-level options are documented in the simulator, coupler, and solver options reference; the viewer, visualization, and renderer options in the visualization reference.

Note

Not every solver runs in every scene. A solver is only active 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.