Reporters¶

Classes:

`BindingEventLogReporter`(filename[, separator])	A reporter that exports an event log based on the timed bindings that occur during the simulation.
`EventLogReporter`(filename[, timeunit, ...])	A reporter that heavily depends on the process prototypes (task, start_event, intermediate_event, end_event) to report on what happens.
`ProcessReporter`([warmup_time])	A reporter that heavily depends on the process prototypes (task, start_event, intermediate_event, end_event) to report on what happens.
`Replicator`(sim_problem, duration[, warmup, ...])	Class to handle the replication of simulation runs.
`Reporter`()	A reporter can be passed to the simpn.simulator.SimProblem.simulate function to report on what happens during the simulator.
`SimpleReporter`()	A simple reporter that just prints the occurring events to the standard output.
`TimeUnit`(value[, names, module, qualname, ...])	An enumeration for the unit in which simulation time is measured.
`WarmupReporter`()	A reporter that reports on the warmup period of a simulation by computing the average cycle times over time.

class simpn.reporters.BindingEventLogReporter(filename, separator=',')¶

A reporter that exports an event log based on the timed bindings that occur during the simulation. Each binding is of the form (binding, time, event), where binding is a tuple of (variable, value). The event log that is produced has the columns: event, time, variable_1, variable_2, … For each binding, a new row is added to the log with the corresponding event, time, and variable values.

Parameters:

filename – the name of the file in which the event log must be stored.
separator – the separator to use in the log.

Methods:

callback(timed_binding)

A function that is invoked by a simpn.simulator.SimProblem each time a event happened.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.

class simpn.reporters.EventLogReporter(filename, timeunit=TimeUnit.MINUTES, initial_time=datetime.datetime(2020, 1, 1, 0, 0), time_format='%Y-%m-%d %H:%M:%S.%f', separator=',', data_fields=None)¶

A reporter that heavily depends on the process prototypes (task, start_event, intermediate_event, end_event) to report on what happens. It stores the events that happen in an event log that can be mined with some process mining tool. As simulation time is a numerical value, some processing is done to convert simulation time into a time format that can be read and interpreted by a process mining tool. To that end, the timeunit in which simulation time is measured must be passed as well as the initial_time moment in calendar time from which the simulation time will be measured. A particular simulation_time moment will then be stored in the log as: initial_time + simulation_time timeunits. Data can also be reported on by specifying the corresponding data fields. The log will contain these data fields as additional columns in the order specified. Data will be taken from a case token from the BPMN prototype, which is always of the form (case_id, data). We recognize 3 forms of data: - basic datatype (int, float, str, bool): the start event and each task must have only one value and len(data_fields) == 1. - list or tuple of basic datatypes: the start event and each task must have len(data) == len(data_fields). - dictionary of basic datatypes: for each event, the data withs keys in data_fields will be included.

Parameters:

filename – the name of the file in which the event log must be stored.
timeunit – the TimeUnit of simulation time.
initial_time – a datetime value.
time_format – a datetime formatting string.
data_fields – the data fields to report in the log.
separator – the separator to use in the log.
data_fields – a list of data field names to include in the log.

Methods:

callback(timed_binding)

A function that is invoked by a simpn.simulator.SimProblem each time a event happened.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.

class simpn.reporters.ProcessReporter(warmup_time=0)¶

A reporter that heavily depends on the process prototypes (task, start_event, intermediate_event, end_event) to report on what happens. It assumes tasks are executed for cases that arrive via start_events and complete at end_events. It measures: - nr_started: the number of cases that started. - nr_completed: the number of cases that completed. - total_wait_time: the sum of waiting times of completed cases. - total_proc_time: the sum of processing times of completed cases. - total_cycle_time: the sum of cycle times of completed cases. - resource_busy_times: a mapping of resource_id -> the time the resource was busy during simulation. - activity_processing_times: a mapping of activity_id -> list of processing times.

Methods:

`aggregate_results`(results_list)	Takes a list of results as returned by get_results and aggregates them into a single result.
`callback`(timed_binding)	A function that is invoked by a simpn.simulator.SimProblem each time a event happened.
`general_statistics_graph`(aggregated_results, ax)	Plots the general statistics graph on the given matplotlib axis.
`get_results`()	Returns a dictionary of dictionaries.
`possible_graphs`()	Returns a dict of possible graphs that can be plotted based on the results.
`resource_utilization_graph`(...)	Plots the resource utilization graph on the given matplotlib axis.
`task_processing_times_graph`(...)	Plots the task processing times graph on the given matplotlib axis.
`warmup_graph`(aggregated_results, ax)	Plots the warmup graph on the given matplotlib axis.

static aggregate_results(results_list)¶: Takes a list of results as returned by get_results and aggregates them into a single result. It does this by computing averages and standard deviations. It does this flexibly, i.e., it is unaware of the precise items in each section, but just computes averages and standard deviations of values. Note that a section is either a dictionary item -> value, or a dictionary item -> item -> value.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.

static general_statistics_graph(aggregated_results, ax)¶

Plots the general statistics graph on the given matplotlib axis. Uses two y-axes, one for counts and one for times.

Parameters:

aggregated_results – the aggregated results as returned by aggregate_results.
ax – the matplotlib axis to plot on.

get_results()¶

Returns a dictionary of dictionaries:

{
    warmup: {
        avg_cycle_time_over_time: [(time, avg_cycle_time), ...]
    },
    general: {
        nr_started: (int, float), # (average, stddev)
        nr_completed: (int, float), # (average, stddev)
        avg_wait_time: (float, float), # (average, stddev)
        avg_proc_time: (float, float), # (average, stddev)
        avg_cycle_time: (float, float) # (average, stddev)
    },
    resources: {
        role: {
            utilization: (float, float) # (average, stddev)
        },
        ...
    },
    activities: {
        activity_id: {
            nr_started: (int, float), # (average, stddev)
            nr_completed: (int, float), # (average, stddev)
            avg_proc_time: (float, float) # (average, stddev)
        },
        ...
    }
}

static possible_graphs()¶

Returns a dict of possible graphs that can be plotted based on the results.

Returns:: a dict graph name -> graphing function

static resource_utilization_graph(aggregated_results, ax)¶

Plots the resource utilization graph on the given matplotlib axis.

Parameters:

aggregated_results – the aggregated results as returned by aggregate_results.
ax – the matplotlib axis to plot on.

static task_processing_times_graph(aggregated_results, ax)¶

Plots the task processing times graph on the given matplotlib axis.

Parameters:

aggregated_results – the aggregated results as returned by aggregate_results.
ax – the matplotlib axis to plot on.

static warmup_graph(aggregated_results, ax)¶

Plots the warmup graph on the given matplotlib axis. It plots the average cycle time over time.

Parameters:

aggregated_results – the aggregated results as returned by aggregate_results.
ax – the matplotlib axis to plot on.

class simpn.reporters.Replicator(sim_problem: SimProblem, duration: float, warmup: float = 0, nr_replications: int = 1, callback: Callable[[float], bool] | None = None)¶

Class to handle the replication of simulation runs. The replicator uses a ProcessReporter to report on the replications.

Parameters:

sim_problem – the simulation problem to replicate.
duration – the duration of each replication.
nr_replications – the number of replications to perform.
callback – an optional callback function that is called after each replication with the percentage of replications completed, if it returns True, replications will continue, if it returns False, replications will stop.

Returns:

a dictionary containing the result of each replication.

class simpn.reporters.Reporter¶

A reporter can be passed to the simpn.simulator.SimProblem.simulate function to report on what happens during the simulator. To this end, a reported must implement the callback function.

Methods:

callback(timed_binding)

A function that is invoked by a simpn.simulator.SimProblem each time a event happened.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.

class simpn.reporters.SimpleReporter¶

A simple reporter that just prints the occurring events to the standard output.

Methods:

callback(timed_binding)

A function that is invoked by a simpn.simulator.SimProblem each time a event happened.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.

class simpn.reporters.TimeUnit(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

An enumeration for the unit in which simulation time is measured.

Attributes:

`DAYS`	int([x]) -> integer int(x, base=10) -> integer
`HOURS`	int([x]) -> integer int(x, base=10) -> integer
`MINUTES`	int([x]) -> integer int(x, base=10) -> integer
`SECONDS`	int([x]) -> integer int(x, base=10) -> integer

DAYS = 4¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4 The type of the None singleton.

HOURS = 3¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4 The type of the None singleton.

MINUTES = 2¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4 The type of the None singleton.

SECONDS = 1¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4 The type of the None singleton.

class simpn.reporters.WarmupReporter¶

A reporter that reports on the warmup period of a simulation by computing the average cycle times over time. It assumes tasks are executed for cases that arrive via start_events and complete at end_events.

Methods:

callback(timed_binding)

A function that is invoked by a simpn.simulator.SimProblem each time a event happened.

callback(timed_binding)¶

A function that is invoked by a simpn.simulator.SimProblem each time a event happened. It receives a timed_binding, which is a triple (binding, time, event): - binding = [(v1: SimVar, t1: SimToken), (v2: SimVar, t2: SimToken), …] of the variable values that caused the event. - time is the simulation time at which the event happened. - event: SimEvent is the event that happened.

Parameters:: timed_binding – the triple (binding, time, event) that described the event that happened with its variable values and the time at which it happened.