Events

Events are a way to react to something specific occurring, by adding a function known as a callback which will be called each time the event is triggered. They are common in other languages such as C#.

narupatools uses events thoroughly to allow easy extensibility of code. Events allow you to insert code that runs for certain events such as after each dynamics step or at the start of each interaction. An event is created as so:

from narupatools.core.event import Event
event = Event()

A callback is a function (normally a local function) that we wish to be called each time the event occurs. We add a callback to a event by either calling the add_callback function or by using the += operator:

def callback(**kwargs):
    print("Hello World")

event.add_callback(callback)

Note

It is strongly advised that all callback functions have **kwargs as their final argument. This means they accept arbitrary arguments that will be ignored. If you don’t do this, if the event gains a parameter in the future your callback will not work.

Adding the callback does not call the function. Also note we are passing in the name of the function (so callback instead of callback()).

Now, when we want to trigger the event, we call the invoke() method. This iterates through all the callbacks added to the event and calls them.

>>> event.invoke()
Hello World