模拟器

Simulator 拥有物理求解器和耦合器，并在每次调用 scene.step() 时推进它们。它由 SimOptions 配置（时间步、重力、子步、可微分模式），以 sim_options 的形式传给场景，场景会自动构建它。

选项

class genesis.options.solvers.SimOptions(*, dt: float = 0.01, substeps: int = 1, substeps_local: int | None = None, gravity: tuple[float, float, float] = (0.0, 0.0, -9.81), floor_height: float = 0.0, requires_grad: bool = False) → None

Options configuring the top-level simulator.

Note

1. SimOptions specifies the global settings for the simulator. Some parameters exist both in SimOptions and SolverOptions. In this case, if such parameters are given in SolverOptions, it will override the one specified in SimOptions for this specific solver. For example, if dt is only given in SimOptions, it will be shared by all the solvers, while a solver given its own dt integrates over that interval instead, and the number of substeps of every solver follows from it.

2. In differentiable mode, substeps_local must be divisible by substeps, as external command is input per step, but substep. If requires_grad is False, we can use arbitrary substeps_local.

Parameters:

• dt (float, optional) – Time duration for each simulation step in seconds. Defaults to 1e-2.

• substeps (int, optional) – Number of substeps per simulation step, i.e. how many times each solver integrates per scene.step(). More substeps buy accuracy and stability, at a runtime cost that grows linearly with the count in the worst case though sub-linearly in practice. Setting both this and a solver dt that implies a different count raises an exception. Defaults to 1.

• substeps_local (int, optional) – Number of substeps stored in GPU memory. Defaults to None. This is used for differentiable mode.

• gravity (tuple, optional) – Gravity force in N/kg. Defaults to (0.0, 0.0, -9.81).

• floor_height (float, optional) – Height of the floor in meters. Defaults to 0.0.

• requires_grad (bool, optional) – Whether to enable differentiable mode. Defaults to False.

• use_hydroelastic_contact (bool, optional) – Whether to use hydroelastic contact. Defaults to False.

Simulator

class genesis.engine.simulator.Simulator(scene: Scene, options: SceneOptions)

Bases: RBC

A simulator is a scene-level simulation manager, which manages all simulation-related operations in the scene, including multiple solvers and the inter-solver coupler.

Parameters:

• scene (gs.Scene) – The scene object that the simulator is associated with.

• options (SceneOptions) – Every option the scene was created with. The simulator keeps the one that configures itself and hands each solver, the coupler and the visualizer the one that configures it. All of them stay reachable as sim.scene.options.

build()

destroy()

reset(state: SimState, envs_idx=None)

data(kinds: frozenset[genesis.utils.array_class.DataKind]) → Iterator[ArrayItem | ScalarItem]

Yield every item of the requested kinds that the simulator and its active solvers hold.

The items of the simulator are named under ‘Simulator’, and the ones of a solver under its class name.

reset_grad()

track_state(*tensors: Tensor)

Make the gradient-carrying tensors of a state queried at the current step differentiable.

In a differentiable scene, the tensors become the outputs of one read node of the current step (see genesis.grad.bridge) and retain their gradient, which collect_output_grads hands to the solvers. They stay the same tensor objects, so the solver may fill them afterwards. Called by ‘QueriedStates’ on registration.

reverse_step(step: int, epoch: int) → dict[int, torch.Tensor]

Run the reverse pass of one step and return the gradients of the inputs taped for it, keyed by tensor id.

step is the global index of the step, and epoch the rollout it belongs to (see genesis.grad.bridge). The autograd node of the step calls this once the gradients of the states read at that step and of every later step are in. The reverse pass of the later steps whose node the loss does not reach only rewinds the rollout. The gradient of an input given to several setters is summed over all of them.

f_global_to_f_local(f_global)

f_local_to_s_local(f_local)

f_global_to_s_local(f_global)

f_global_to_s_global(f_global)

step(in_backward=False)

process_input(in_backward=False)

Apply the inputs the entities taped for the coming step, given at step level rather than substep level.

Returns the inputs applied, of any type.

process_input_grad()

Run the reverse pass of the inputs applied at the current step, and return their (input, gradient) pairs.

substep(f)

sub_step_grad(f)

substep_pre_coupling(f)

substep_pre_coupling_grad(f)

substep_post_coupling(f)

substep_post_coupling_grad(f)

collect_output_grads()

Hand the gradients of the states queried at the current step to the solvers that registered them.

save_ckpt()

This function refreshes the gpu memory (copy the last frame to the first frame in the local memory), and then saves the checkpoint. This function is called every substeps_local steps, which means it’s called only once per step when requires_grad is True.

load_ckpt()

get_state()

set_gravity(gravity, envs_idx=None)

property steps: Tensor

The number of steps each environment has run since its last reset, of shape [B].

property dt: float

The time duration for each simulation step.

property substeps

The number of substeps per simulation step.

property substep_dt: float

Duration of one substep, in seconds, which is the interval every solver integrates over.

property scene

The scene object that the simulator is associated with.

property requires_grad

Whether the simulator requires gradients.

property is_forward_ready: bool

Whether the simulation may step forward, which a backward pass rewinding it to its start forbids until reset.

property n_entities: int

The number of entities in the simulator.

property entities

The list of entities in the simulator.

property substeps_local

The number of substeps stored in local memory.

property cur_substep_global

The current substep of the simulation.

property cur_substep_local

The current substep of the simulation in local memory.

property cur_step_local

The current step of the simulation in local memory.

property step_timer: StepTimer

The timer of the phases of the steps.

property cur_step_global

Number of scene.step() calls, counted for the whole batch.

Use it to tell that the simulation moved on, for instance to invalidate a cache. For the simulated time of an environment, use get_time.

get_time(envs_idx=None)

The simulated time of each environment, in seconds.

Environments are stepped and reset independently, so simulated time is per environment, and this is where it is read from.

property cur_t

the number of substeps run times the substep interval.

Shared by every environment, so it tells that the simulation moved on rather than what one environment has simulated, which is get_time.

Type:

How far the substep loop has advanced, in seconds

property coupler

The coupler object that manages the inter-solver coupling.

property solvers

The list of solvers in the simulator.

property active_solvers

The list of active solvers in the simulator.