Timers

Insert delays in your simulation

We can manage time within a simulation using timers.

Block

We can use a block to close off the flow of values for a certain amount of time. For example:

=Block(90, 'days')

This event will block the passage of any values it receives until 90 days elapses. After that, any values received will be passed along.

The timer (in this case measuring 90 days) begins the first time the event triggers.

We can think of a block as a closed valve that opens after a set amount of time or until a date is reached.

This second argument can be:seconds, minutes, hours, days, weeks,months, or years.

Alternatively, you may also use an ISO-format timestamp as the argument:

=Block("2024-01-30T18:30:49.848Z"<closed_until>)

This will prevent the "valve" from opening until that timestamp is exceeded in the simulation.

Wait

We can use a wait event to insert a delay, like so:

=Wait(7, 'days')

Where 7 is the number of days that should pass before the event executes.

This second argument can be: seconds, minutes, hours, days, weeks,months, or years.

Alternatively, you may pass an ISO-format timestamp as the first and only argument, like so:

=Wait("2024-01-30T18:30:49.848Z"<wait_until>)

Or with non-UTC timezone information:

=Wait("2024-03-01T12:49:11-06:00"<wait_until>)

This will fire the wait event once this timestamp is reached in the simulation.

If you pass an empty string to wait, it will short-circuit and any downstream events will not execute. This is useful when wait takes a run-time argument that you want to use to control downstream execution, like so:

=Wait(""<end_date>)

This wait will terminate without triggering downstream events.

If what you really want is for the wait to occur immediately, just pass in a zero: =Wait(0).

📘

What's the value?

A Wait is value-less, meaning it does not report any flow or sum to the ledger. It simply exists to trigger downstream events, or pass along the value of upstream events. Any value received by a wait event is passed downstream unchanged.

Halt

Sometimes you want to stop the simulation before the end date. You can do this using:

=Halt()

Halt takes no arguments. If you'd like to run the halt after a certain delay, you can easily combine it with a wait event, like so (-> indicates a route):

=Wait(3, 'months') -> =Halt()

Stopwatch

The Stopwatch event takes a single argument, a number of seconds:

=Stopwatch(3600<elapsed_time_allowed>)

When the event is triggered, the stopwatch begins counting. When the amount of specified time (in this case, 1 hour) has passed, the stopwatch will halt the simulation.

If the stopwatch is triggered a second time, the stopwatch will stop counting.

This makes the stopwatch useful for either halting the entire simulation after an absolute amount of time (trigger once), or for halting the simulation once certain events have fired a certain number of times (trigger twice+).