Adds single-shot events

[renezurbruegg]

Description

This PR introduces one-shot events.

A one-shot event is triggered at most once before the environment is reset. This makes it possible to modify the environment at a specific time, for example by lowering the friction after one second or by applying forces at different moments such as 1s, 2s, and 3s.

Example

The following example schedules different forces to be applied at one-second intervals without being repeated. Without the is_single_shot option, the pull_up event would instead be triggered repeatedly at 1s, 2s, and 3s.

@configclass
class SingleShotEventExample:
    pull_up = EventTerm(
        func=mdp.pull_object,
        mode="interval",
        is_global_time=True,
        interval_range_s=(1.0, 1.0),
        is_single_shot=True,
        params={"direction": (0.0, 0.0, 1.0)},
    )
    
    pull_down = EventTerm(
        func=mdp.pull_object,
        mode="interval",
        is_global_time=True,
        interval_range_s=(2.0, 2.0),
        is_single_shot=True,
        params={"direction": (0.0, 0.0, -1.0)},
    )
    
    pull_left = EventTerm(
        func=mdp.pull_object,
        mode="interval",
        is_global_time=True,
        interval_range_s=(3.0, 3.0),
        is_single_shot=True,
        params={"direction": (1.0, 0.0, 0.0)},
    )
    reset_in_betweeen = EventTerm(
        func=mdp.reset,
        mode="interval",
        is_global_time=True,
        interval_range_s=(1.0, 1.0),
    )

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[jtigue-bdai]

lgtm

[Mayankm96]

Would there be a case where someone says they want N-shot? 🤔

[renezurbruegg]

Maybe yes, personally I think it's unlikely. In this case, one could just put N single shot events in the config.

Thinking about it, being able to specify initial delay and interval on the other hand, might be interesting and would be able to also mimic the single shot behavior (infinite interval time with finite inital delay). But I fear this would introduce unwanted breaking changes.

[ooctipus]

I am wonder if feature like this is better to be written as custom function to combined with interval, rather than allocate a new attribute in EventsManager.

[renezurbruegg]

I am wonder if feature like this is better to be written as custom function to combined with interval, rather than allocate a new attribute in EventsManager.

I think there are enough practical use cases to justify a dedicated flag. Requiring a custom functor would force the user to move away from the functional interface and implement a separate class with state, which adds unnecessary complexity for something that could be handled more directly.

[ooctipus]

ok between combining interval + is_single_shot as an extra attribute
vs
maybe giving a new mode called one_shot_mode, wondering your opinion, which one do you thinks make more sense?

[renezurbruegg]

To me the current implementation is more efficient coding wise whereas one_shot_mode would avoid another "this argument is only used if mode is set to reset|interval" argument, which I think is nice to avoid.

Thinking more about it, imo the cleanest solution would be to introduce EventResetTermCfg, EventIntervalTermCfg, EventSingleShotTermCfg, ... and move all "interval|reset only" arguments to these configs. But this would introduce quite some breaking changes.

What's your opinion? I think removing the argument and having it in the mode as you said is cleaner.

[ooctipus]

Thinking more about it, imo the cleanest solution would be to introduce EventResetTermCfg, EventIntervalTermCfg, EventSingleShotTermCfg, ... and move all "interval|reset only" arguments to these configs. But this would introduce quite some breaking changes.

if this is the future way to go, then having one shot mode will prepare us to that goal and somewhat aligns with that separation, I'd say removing the argument and having it in the mode.

But no rush at all : ))
Thanks for considering my opinion!

@Mayankm96 would also be great if you can give some input here as well