Should an event which modifies state call sim.forward()?

[rdeits-bd]

Let's say I have two events (both on mode="reset" for simplicity). Event A modifies the root state via entity.write_root_velocity_to_sim(new_root_vel), and Event B does something which involves reading root velocity, e.g. entity.data.root_link_vel_w.

Currently, this doesn't work, and it fails in a really sneaky way: Writing the root state modifies qvel, but reading the root state reads from xvel, and those values are inconsistent until somebody calls sim.forward(). The result is that Event B always sees the wrong state: In practice it sees what the root velocity was right before Event A fired, since that's what happens to be left in xvel from the most recent forward().

What's the right way to handle this? Should Event A manually call sim.forward()? Should Event B check if the data is dirty (is this possible?) and call sim.forward()?

This is likely to be a gotcha for other users coming from IsaacLab, as IsaacLab uses a "timestamp" field on its cached data to ensure that this kind of mismatch doesn't happen.

[rdeits-bd]

cc @bd-aadubredu since you might run into this as well

[louislelay]

For future readers, this was resolved in PR #297.

The decided solution was:

1. All write methods write to the state (qpos, qvel, xfrc_applied, ctrl, etc.) Thus write methods are all "up-to-date" in that sense.
2. Read properties, on the other hand, read from derived quantities (e.g., xpos, cvel) and thus, it is the user's responsibility to call sim.forward() if they need up-to-date values with respect to the current state. This is particularly important when using multiple events: if Event A writes state and Event B reads state, you must call sim.forward() between them.
3. All inputs and outputs use world frame. Internal MuJoCo conventions (e.g., angular velocity in body frame) are handled automatically.