Events

Action

An action is either a Function or an Expr or a Tuple of them. It can be scheduled in an event for later execution.

fun(f::Function, args...; kwargs...)

Save a function f and its arguments in a closure for later execution.

Arguments

The arguments args... and keyword arguments kwargs... to fun are passed to f at execution but may change their values between beeing captured in fun and fs later execution. If f needs their current values at execution time there are two possibilities:

1. fun can take funs, function closures, symbols or expressions at the place of values or variable arguments. They are evaluated at event time just before being passed to f. There is one exception: if f is an event!, its arguments are passed on unevaluated.
2. A mutable type argument (Array, struct ...) is always current. You can also change its content from within a function.

If using Symbols or Expr in fun you get a one time warning. They are evaluated at global scope in Module Main only and therefore cannot be used by other modules.

Timing

Enumeration type for scheduling events and timed conditions:

• at: schedule an event at a given time,
• after: schedule an event a given time after current time,
• every: schedule an event every given time from now on,
• before: a timed condition is true before a given time,
• until: delay until t.

event!([clk], ex, t; <keyword arguments>)
event!([clk], ex, t, cy; <keyword arguments>)
event!([clk], ex, T, t; <keyword arguments>)

Schedule an event for a given time t.

If t is a Distribution, event time is evaluated as rand(t). If cy is a Distribution, the event is repeated after a random interval rand(cy). If the evaluated time ≤ clk.time, the event is scheduled at clk.time.

Arguments

• clk<:AbstractClock: clock, it not supplied, the event is scheduled to 𝐶,
• ex<:Action: an expression or function or a tuple of them,
• T::Timing: a timing, one of at, after or every,
• t: event time, Number or Distribution,
• cy: repeat cycle, Number or Distribution.

Keyword arguments

• n::Int=typemax(Int): number of repeating events,
• cid::Int=clk.id: if cid ≠ clk.id, assign the event to the parallel clock with id == cid. This overrides spawn,
• spawn::Bool=false: if true, spawn the event at other available threads,

Examples

julia> using DiscreteEvents, Distributions, Random

julia> Random.seed!(123);

julia> c = Clock()
Clock 1: state=:idle, t=0.0, Δt=0.01, prc:0
  scheduled ev:0, cev:0, sampl:0

julia> f(x) = x[1] += 1
f (generic function with 1 method)

julia> a = [0]
1-element Array{Int64,1}:
 0

julia> event!(c, fun(f, a), 1)                     # 1st event at 1

julia> event!(c, fun(f, a), at, 2)                 # 2nd event at 2

julia> event!(c, fun(f, a), after, 3)              # 3rd event after 3

julia> event!(c, fun(f, a), every, Exponential(3)) # Poisson process with λ=1/3

julia> run!(c, 50)
"run! finished with 26 clock events, 0 sample steps, simulation time: 50.0"

julia> a
1-element Array{Int64,1}:
 26

event!([clk], ex, cond; <keyword arguments>)

Schedule ex as a conditional event, conditions cond get evaluated at each clock tick.

Arguments

• clk<:AbstractClock: if no clock is supplied, the event is scheduled to 𝐶,
• ex<:Action: an expression or function or a tuple of them,
• cond<:Action: a condition is true if all functions or expressions therein return true,

Keyword arguments

• cid::Int=clk.id: if cid ≠ clk.id, assign the event to the parallel clock with id == cid. This overrides spawn,
• spawn::Bool=false: if true, spawn the event at other available threads.

Examples

julia> using DiscreteEvents

julia> c = Clock()   # create a new clock
Clock 1: state=:idle, t=0.0, Δt=0.01, prc:0
  scheduled ev:0, cev:0, sampl:0

julia> event!(c, fun((x)->println(tau(x), ": now I'm triggered"), c), fun(>=, fun(tau, c), 5))

julia> run!(c, 10)   # sampling is not exact, so it takes 502 sample steps to fire the event
5.009999999999938: now I'm triggered
"run! finished with 0 clock events, 502 sample steps, simulation time: 10.0"

@event f(arg...) T t [n]

Schedule a function f(arg...) as an event to a clock.

Arguments

• f: function to be executed at event time,
• arg...: its arguments, the first argument must be a clock,
• T: a Timing (at, after, every),
• t: a Number or a Distribution,
• n::Int: repetitions for a repeat event.

@event f(farg...) c(carg...)
@event f(farg...) ca

Schedule a function f(farg...) as a conditional event to a clock.

Arguments

• f: function to be executed at event time,
• farg...: its arguments, the first argument must be a clock,
• c: function to be evaluated at the clock's sample rate, if it returns true, the event is triggered,
• carg...: arguments to c,
• ca: an anyonymous function of the form ()->... to be evaluated at the clock's sample rate, if it returns true, the event is triggered.

sample_time!([clk::Clock], Δt::N) where {N<:Number}

Set the clock's sample rate starting from now (tau(clk)).

Arguments

• clk::Clock: if not supplied, set the sample rate on 𝐶,
• Δt::N: sample rate, time interval for sampling

periodic!([clk], ex, Δt; <keyword arguments>)
periodic!(clk, ex; <keyword arguments>)

Register an Action ex for periodic execution at the clock`s sample rate.

Arguments

• clk<:AbstractClock: if not supplied, it registers on 𝐶,
• ex<:Action: an expression or function or a tuple of them,
• Δt<:Number=clk.Δt: set the clock's sampling rate, if no Δt is given, it takes the current sampling rate, if ≤ 0, it calculates a positive one,

Keyword arguments

• cid::Int=clk.id: if cid ≠ clk.id, sample at the parallel clock with id == cid. This overrides spawn,
• spawn::Bool=false: if true, spawn the periodic event to other available threads.

@periodic f(arg...) [Δt]

Register a function f(arg...) for periodic execution at the clock`s sample rate.

Arguments

• f: function to be executed periodically,
• arg...: its arguments, the first argument must be a clock,
• Δt: for setting the clock's sample rate.