Simulator¶

Classes:

`SimEvent`(_id[, guard, behavior, incoming, ...])	A simulation event SimEvent that can happen when tokens are available on all of its incoming SimVar and its guard evaluates to True.
`SimProblem`([debugging, binding_priority])	A simulation problem SimProblem, which consists of a collection of simulation variables SimVar and a collection of simulation events SimEvent.
`SimToken`(value[, time, delay])	A token SimToken, which is a possible value of a SimVar.
`SimVar`(_id[, priority])	A simulation variable SimVar has an identifier and a marking.
`SimVarQueue`(simvar)	A simulation variable that contains the queue of tokens from another SimVar.
`SimVarTime`(problem)	A simulation variable that contains the simulation time.

Functions:

event(sim_problem, inflow, outflow[, guard])

A decorator that can be used to turn a Python function into a SimEvent.

class simpn.simulator.SimEvent(_id, guard=None, behavior=None, incoming=None, outgoing=None)¶

A simulation event SimEvent that can happen when tokens are available on all of its incoming SimVar and its guard evaluates to True. When it happens, it consumes a token from each of its incoming SimVar and produces a token on each of its outgoing places according to behavior. The behavior takes just the values of the SimVar as input, but produces tokens as output: values with a delay. The delay can also be 0, meaning the token is produced with 0 delay. For example, consider the event with incoming SimVar [a, b] that have 2@1 and 2@1. The event has outgoing SimVar [c, d], behavior lambda a, b: [(a + b)@+1, (a - b)@+2]. This event can happen for a = 2@1 and b = 2@1. Thus, it will happen at time 1, generating [3@+1, 1@+2] according to its behavior. Therefore, after the event has happened, c and d will have the tokens 3@2 and 1@3.

Parameters:

_id – the identifier of the event.
incoming – a list of incoming SimVar of the event.
outgoing – a list of outgoing SimVar of the event
guard – a function that takes as many parameters as there are incoming SimVar. The function must evaluate to True or False for all possible values of SimVar. The event can only happen for values for which the guard function evaluates to True.
behavior – a function that takes as many parameters as there are incoming SimVar. The function must return a list with as many elements as there are outgoing SimVar. The elements must be tokens that carry the resulting values and the delay with which these values become available. When the event happens, the function is performed on the incoming SimVar and the result of the function is put on the outgoing SimVar with the corresponding delays.

Methods:

`set_guard`(func)	Set the guard function.
`set_inflow`(incoming)	Set the incoming SimVar.
`set_outflow`(outgoing)	Set the outgoing SimVar.

set_guard(func)¶

Set the guard function.

Parameters:: func – a function with as many input parameters as there are incoming SimVar, which generates a list with as many elements as there are outgoing SimVar.

set_inflow(incoming)¶

Set the incoming SimVar.

Parameters:: incoming – a list of SimVar.

set_outflow(outgoing)¶

Set the outgoing SimVar.

Parameters:: outgoing – a list of SimVar.

class simpn.simulator.SimProblem(debugging=True, binding_priority=<function SimProblem.<lambda>>)¶

A simulation problem SimProblem, which consists of a collection of simulation variables SimVar and a collection of simulation events SimEvent. The simulation has a time and a marking of SimVar. A marking is an assignment of values to SimVar variables (also see SimVar). The difference between a normal Python variable and a SimVar is that: (1) a SimVar can have multiple values; and (2) these values have a simulation time at which they become available. A SimEvent is a function that takes SimVar values as input and produces SimVar values (also see SimEvent). The difference with normal Python functions is that events can happen whenever its incoming SimVar parameters have a value. If a SimVar parameter has multiple values, it can happen on any of these values.

Parameters:

debugging – if set to True, produces more information for debugging purposes (defaults to True).
binding_priority – a function that takes a list of binding as input and returns the binding that will be selected in case there are multiple possible bindings to fire.

Methods:

`add_event`(inflow, outflow, behavior[, name, ...])	Creates a new SimEvent with the specified parameters (also see SimEvent).
`add_place`(**kwargs)	Adds a SimVar to the problem.
`add_prototype_var`(var)	Adds the SimVar to the problem.
`add_transition`(**kwargs)	Creates a new SimEvent with the specified parameters.
`add_var`(name[, priority])	Creates a new SimVar with the specified name as identifier.
`bindings`()	Calculates the set of timed bindings that is enabled over all events in the problem.
`event_bindings`(event)	Calculates the set of bindings that enables the given event.
`fire`(timed_binding)	Fires the specified timed binding.
`place`(**kwargs)	Returns the SimVar with the given name.
`restore_checkpoint`(name)	Restores the state of the simulator to the checkpoint with the given name.
`set_binding_priority`(func)	Sets the binding priority function.
`simulate`(duration[, reporter])	Executes a simulation run for the problem for the specified duration.
`step`()	Executes a single step of the simulation.
`store_checkpoint`(name)	Stores the state of the simulator as a checkpoint with the given name.
`tokens_combinations`(event)	Creates a list of token combinations that are available to the specified event.
`var`(name)	Returns the SimVar with the given name.

add_event(inflow, outflow, behavior, name=None, guard=None)¶

Creates a new SimEvent with the specified parameters (also see SimEvent). Adds the SimEvent to the problem and returns it.

Parameters:

inflow – a list of incoming SimVar of the event.
outflow – a list of outgoing SimVar of the event/
behavior – a function that takes as many parameters as there are incoming SimVar. The function must return a list with as many elements as there are outgoing SimVar. When the event happens, the function is performed on the incoming SimVar and the result of the function is put on the outgoing SimVar.
name – the identifier of the event.
guard – a function that takes as many parameters as there are incoming SimVar. The function must evaluate to True or False for all possible values of SimVar. The event can only happen for values for which the guard function evaluates to True.

Returns:

a SimEvent with the specified parameters.

add_place(**kwargs)¶: Adds a SimVar to the problem. This function is a wrapper around add_var for people with a Petri-net background.

add_prototype_var(var)¶: Adds the SimVar to the problem. This function should only be used for prototypes.

add_transition(**kwargs)¶: Creates a new SimEvent with the specified parameters. This function is a wrapper around add_event for people with a Petri-net background.

add_var(name, priority=<function SimProblem.<lambda>>)¶

Creates a new SimVar with the specified name as identifier. Adds the SimVar to the problem and returns it.

Parameters:

name – a name for the SimVar.
priority – a function that takes a token as input and returns a value that is used to sort the tokens in the order in which they will be processed (lower values first). The default is processing in the order of the time of the token.

Returns:

a SimVar with the specified name as identifier.

bindings()¶: Calculates the set of timed bindings that is enabled over all events in the problem. Each binding is a tuple ([(place, token), (place, token), …], time, event) that represents a single enabling binding. If no timed binding is enabled at the current clock time, updates the current clock time to the earliest time at which there is. :return: list of tuples ([(place, token), (place, token), …], time, event)

event_bindings(event)¶

Calculates the set of bindings that enables the given event. Each binding is a tuple ([(place, token), (place, token), …], time) that represents a single enabling binding. A binding is a possible token combination (see token_combinations), for which the event’s guard function evaluates to True. In case there is no guard function, any combination is also a binding. The time is the time at which the latest token is available. For example, if a event has incoming SimVar a and b with tokens 1@2 on a and 2@3, 3@1 on b, the possible bindings are ([(a, 1@2), (b, 2@3)], 3) and ([(a, 1@2), (b, 3@1)], 2)

Parameters:: event – the event for which to calculate the enabling bindings.
Returns:: list of tuples ([(place, token), (place, token), …], time)

fire(timed_binding)¶: Fires the specified timed binding. Binding is a tuple ([(place, token), (place, token), …], time, event)

place(**kwargs)¶: Returns the SimVar with the given name. This function is a wrapper around var for people with a Petri-net background.

restore_checkpoint(name)¶: Restores the state of the simulator to the checkpoint with the given name.

set_binding_priority(func)¶

Sets the binding priority function.

Parameters:: func – a function that takes a list of binding as input and returns the binding that will be selected in case there are multiple possible bindings to fire.

simulate(duration, reporter=None)¶

Executes a simulation run for the problem for the specified duration. A simulation run executes events until this is no longer possible, or until the specified duration. If at any moment multiple events can happen, one is selected at random. At the end of the simulation run, the problem is in the state that is the result of the run. If the reporter is set, its callback function is called with parameters (binding, time, event) each time a event happens (for a binding at a moment in simulation time).

Parameters:

duration – the duration of the simulation.
reporter – a class that implements a callback function, which is called each time a event happens. reporter can also be a list of reporters, in which case the callback function of each reporter is called.

step()¶: Executes a single step of the simulation. If multiple events can happen, one is selected at random. Returns the binding that happened, or None if no event could happen.

store_checkpoint(name)¶: Stores the state of the simulator as a checkpoint with the given name. The checkpoint can be restored later with restore_checkpoint.

static tokens_combinations(event)¶

Creates a list of token combinations that are available to the specified event. These are combinations of tokens that are on the incoming SimVar of the event. For example, if a event has incoming SimVar a and b with tokens 1@0 on a and 2@0, 3@0 on b, the possible combinations are [(a, 1@0), (b, 2@0)] and [(a, 1@0), (b, 3@0)]

Parameters:: event – the event to return the token combinations for.
Returns:: a list of lists, each of which is a token combination.

var(name)¶

Returns the SimVar with the given name. Raises an error if no such SimVar exists.

Parameters:: name – the name of the SimVar.
Returns:: the SimVar with the given name or an Error.

class simpn.simulator.SimToken(value, time=0, delay=0)¶

A token SimToken, which is a possible value of a SimVar. A token has a value and the time at which this value is available in a SimVar. When the SimToken is used as the return value of an event behavior, the delay can be used. This represents the delay with which the value will be available. The value will then be available at <time of event> + <delay>.

Parameters:

value – the value of the token.
time – the time at which the value is available.
delay – should only be used when returning the token from an event behavior. The value represents the delay. The token will then be available as <time of event> + <delay>.

class simpn.simulator.SimVar(_id, priority=<function SimVar.<lambda>>)¶

A simulation variable SimVar has an identifier and a marking. A simulation variable can have multiple values. These values are available at particular times. For example, a variable van have the value 1 at time 0 (denoted as 1@0) and also 2@0. These values are also called tokens. Multiple tokens are called a marking of the variable. The marking is represented as a sorted list, which keeps tokens in the order of their priority, by default this is their timestamp. The functions put and remove, put and remove tokens in such a way that the order is maintained.

Parameters:

_id – the identifier of the SimVar.
priority – a function that takes a token as input and returns a value that is used to sort the tokens in the order in which they will be processed (lower values first). The default is processing in the order of the time of the token.

Methods:

`add_token`(token[, count])	Adds a token value in the SimVar.
`put`(value[, time])	Put a token value in the SimVar at a particular time.
`remove_token`(token)	Removes a token value (once) from the SimVar.
`restore_checkpoint`(name)	Restores the SimVar marking from the checkpoint with the given name.
`store_checkpoint`(name)	Stores a checkpoint of the SimVar marking with the given name.

add_token(token, count=1)¶

Adds a token value in the SimVar.

Parameters:

token – the token value to put in the SimVar.
count – the number of times to put the token value in the SimVar (defaults to 1 time).

put(value, time=0)¶

Put a token value in the SimVar at a particular time.

Parameters:

value – the value to put in the SimVar.
time – the time to make this value available at.

remove_token(token)¶

Removes a token value (once) from the SimVar.

Parameters:: token – the token value to remove from the SimVar.

restore_checkpoint(name)¶: Restores the SimVar marking from the checkpoint with the given name.

store_checkpoint(name)¶: Stores a checkpoint of the SimVar marking with the given name. The checkpoint can be restored later with restore_checkpoint.

class simpn.simulator.SimVarQueue(simvar)¶

A simulation variable that contains the queue of tokens from another SimVar. The identifier of this SimVar is <simvar_id>.queue, where simvar_id is the _id of the SimVar of which it contains the queue. Regular SimVar have a queue property that refers to their SimVarQueue variable.

Methods:

`add_token`(token[, count])	Adds a token value in the SimVar.
`put`(value[, time])	Put a token value in the SimVar at a particular time.
`remove_token`(token)	Removes a token value (once) from the SimVar.

add_token(token, count=1)¶

Adds a token value in the SimVar.

Parameters:

token – the token value to put in the SimVar.
count – the number of times to put the token value in the SimVar (defaults to 1 time).

put(value, time=0)¶

Put a token value in the SimVar at a particular time.

Parameters:

value – the value to put in the SimVar.
time – the time to make this value available at.

remove_token(token)¶

Removes a token value (once) from the SimVar.

Parameters:: token – the token value to remove from the SimVar.

class simpn.simulator.SimVarTime(problem)¶

A simulation variable that contains the simulation time. This variable only always has a single token value, which is the simulation time. The identifier of this SimVar is ‘time’, which consequently is a reserved name.

Methods:

`add_token`(token[, count])	Adds a token value in the SimVar.
`put`(value[, time])	Put a token value in the SimVar at a particular time.
`remove_token`(token)	Removes a token value (once) from the SimVar.

add_token(token, count=1)¶

Adds a token value in the SimVar.

Parameters:

token – the token value to put in the SimVar.
count – the number of times to put the token value in the SimVar (defaults to 1 time).

put(value, time=0)¶

Put a token value in the SimVar at a particular time.

Parameters:

value – the value to put in the SimVar.
time – the time to make this value available at.

remove_token(token)¶

Removes a token value (once) from the SimVar.

Parameters:: token – the token value to remove from the SimVar.

simpn.simulator.event(sim_problem: SimProblem, inflow: list, outflow: list, guard=None)¶

A decorator that can be used to turn a Python function into a SimEvent. The event will be added to the specified sim_problem. If they do not yet exist, SimVar will be added for each parameter of the Python function and for each element in outflow. The parameters of the function will be treated as inflow variables of the SimEvent (by name). The elements of outflow must be names of SimVar and will be treated as outflow variables of the SimEvent (by name). The name of the SimEvent will be the name of the Python function.

Parameters:

sim_problem – the SimProblem to which to add the SimEvent.
inflow – a list of names of inflow variables. Just there for documentation purposes, it is not being used.
outflow – a list of names of outflow variables.
guard – an optional guard for the SimEvent.

Returns:

the Python function.