bpo.simulator module

Classes:

CaseReporterElement()	A ReporterElement that keeps information about cases, specifically:
Event(event_type, moment, task[, resource, ...])	A simulation event.
EventLogReporterElement(filename[, ...])	A ReporterElement that stored the simulation events that occur in an event log.
EventType(value)	An enumeration for the types of event that can happen in the simulator.
Reporter([warmup, reporter_elements])	A Reporter consists of ReporterElement and reports on the information that is kept by its elements.
ReporterElement()	Abstract class that must be implemented by each concrete reporter element.
Simulator(problem, reporter, planner)	A Simulator simulates a specified Problem using a specified Planner.
TasksReporterElement()	A ReporterElement that keeps information about tasks, specifically:
TimeUnit(value)	An enumeration for the unit in which simulation time is measured.

class bpo.simulator.CaseReporterElement

Bases: bpo.simulator.ReporterElement

A ReporterElement that keeps information about cases, specifically:

• cases completed: the number of cases that completed during the simulation run.

• cases cycle time: the average of the cycle times of the completed cases.

This information is returned by the CaseReporterElement.summarize() method by the specified labels.

Methods:

report(event)	Is invoked when a simulation event occurs.
restart()	Is invoked when a simulation run starts.
summarize()	Is invoked when a simulation run ends.

report(event)

Is invoked when a simulation event occurs. Can store information about the event.

Parameters

event – the simulation Event that occurred.

restart()

Is invoked when a simulation run starts. Must erase all information to start a new report.

summarize()

Is invoked when a simulation run ends. Must return aggregate information about stored event information.

Returns

a list of tuples (label, value), where label is a meaningful name for the reported aggregate information, and value is the corresponding information.

class bpo.simulator.Event(event_type, moment, task, resource=None, nr_tasks=0, nr_resources=0)

Bases: object

A simulation event.

Parameters

• event_type – the EventType.

• moment – the moment in simulation time at which the event happens.

• task – the task that triggered, or None for event_type == PLAN_TASKS.

• resource – the resource that performs the task, or None for event_type not in [START_TASK, COMPLETE_TASK]

• nr_tasks – the number of tasks that must be planned, or 0 for event_type != PLAN_TASKS

• nr_resources – the number of resources that is available, or 0 for event_type != PLAN_TASKS

class bpo.simulator.EventLogReporterElement(filename, timeunit=TimeUnit.SECONDS, initial_time=datetime.datetime(2020, 1, 1, 0, 0), time_format='%Y-%m-%d %H:%M:%S.%f', data_fields=[])

Bases: bpo.simulator.ReporterElement

A ReporterElement that stored the simulation events that occur in an event log. The EventLogReporterElement.summarize() method does not return any information. 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 names of these data fields must correspond to names of data fields as they appear in the problem.

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.

Methods:

report(event)	Is invoked when a simulation event occurs.
restart()	Is invoked when a simulation run starts.
summarize()	Is invoked when a simulation run ends.

report(event)

Is invoked when a simulation event occurs. Can store information about the event.

Parameters

event – the simulation Event that occurred.

restart()

Is invoked when a simulation run starts. Must erase all information to start a new report.

summarize()

Is invoked when a simulation run ends. Must return aggregate information about stored event information.

Returns

a list of tuples (label, value), where label is a meaningful name for the reported aggregate information, and value is the corresponding information.

class bpo.simulator.EventType(value)

Bases: enum.Enum

An enumeration for the types of event that can happen in the simulator.

Attributes:

CASE_ARRIVAL	A case arrives.
COMPLETE_CASE	A case completes.
COMPLETE_TASK	A task completes.
PLAN_TASKS	An action is performed to assign tasks to resources.
SCHEDULE_RESOURCES	Resources are scheduled every full clock tick.
START_TASK	A task starts.
TASK_ACTIVATE	A task becomes ready to perform (but is not assigned to a resource).
TASK_PLANNED	A task is assigned to a resource.

CASE_ARRIVAL

A case arrives.

COMPLETE_CASE

A case completes.

COMPLETE_TASK

A task completes.

PLAN_TASKS

An action is performed to assign tasks to resources.

SCHEDULE_RESOURCES

Resources are scheduled every full clock tick.

START_TASK

A task starts.

TASK_ACTIVATE

A task becomes ready to perform (but is not assigned to a resource).

TASK_PLANNED

A task is assigned to a resource.

class bpo.simulator.Reporter(warmup=0, reporter_elements=None)

Bases: object

A Reporter consists of ReporterElement and reports on the information that is kept by its elements. Consequently, it does not do much itself, it mainly passes on events to and received aggregate information from its elements.

It receives a Reporter.report() call, each time a simulation event occurs, which it forwards to its elements to enable them to store information about that event. It receives a ReporterElement.summarize() call when a simulation run completes. It then collects the summaries from each of its elements and returns them in one list. It receives a ReporterElement.restart() call when a simulation run starts, which it forwards to its elements to enable them to restart.

During the specified warmup time, the reporter will ignore all events.

Parameters

• warmup – a duration in simulation time.

• reporter_elements – a list of ReporterElement instances, when None are provided, creates a reporter with a TaskReporterElement and a Case ReporterElement.

Methods:

aggregate(summaries)
report(event)
restart()
summarize()

static aggregate(summaries)

report(event)

restart()

summarize()

class bpo.simulator.ReporterElement

Bases: abc.ABC

Abstract class that must be implemented by each concrete reporter element. A reporter element is part of a Reporter. It receives a ReporterElement.report() call, each time a simulation event occurs. It can then store information about that event. Once a simulation run is completed, it receives a ReporterElement.summarize() call. It must then report aggregate information that it stored about the events. Each time a simulation run starts, it receives a ReporterElement.restart() call, upon which it must erase all previously stored information.

Methods:

report(event)	Is invoked when a simulation event occurs.
restart()	Is invoked when a simulation run starts.
summarize()	Is invoked when a simulation run ends.

abstract report(event)

Is invoked when a simulation event occurs. Can store information about the event.

Parameters

event – the simulation Event that occurred.

abstract restart()

Is invoked when a simulation run starts. Must erase all information to start a new report.

abstract summarize()

Is invoked when a simulation run ends. Must return aggregate information about stored event information.

Returns

a list of tuples (label, value), where label is a meaningful name for the reported aggregate information, and value is the corresponding information.

class bpo.simulator.Simulator(problem, reporter, planner)

Bases: object

A Simulator simulates a specified Problem using a specified Planner. The results of the simulation are generated using the specified Reporter. There are two main entry points into the simulator:

• simulate(), which simulates the (single) problem instance passed with the constructor; and

• replicate(), which simulates a collection of problem instances passed via the replicate method itself.

Attributes:

assigned_tasks	The tasks that are currently assigned.
available_resources	The set of resources that are currently available.
away_resources_weights	The set of resources that are currently away (on a break, home, or working in another process) and consequently not available.
busy_cases	The cases of which a task is currently being performed or must still be performed.
busy_resources	The resources that are currently busy.
now	The current simulation time.
reserved_resources	The resources that are currently reserved.
unassigned_tasks	The tasks that are currently not assigned.

Methods:

desired_nr_resources()	The number of resources that is currently desired to be working now according to the problem schedule.
init_simulation()	Re-initializes the simulation, such that it can be run again.
replicate(problem, planner, reporter, ...)	Creates a simulator for each of the problem_instances, using the specified planner and reporter.
simulate(running_time)	Runs the simulation for the instance that was passed in the constructor.
working_nr_resources()	The number of resources that is actually on the work floor now, either available, busy or reserved.

assigned_tasks

The tasks that are currently assigned. A dict task.id -> (task, resource, start), where:

• task is an instance of Task.

• start is the moment in simulation at which the resource will start or has started processing the task.

• resource is the label that identifies a resource in the Problem.

available_resources

The set of resources that are currently available. Each resource is a label that identifies a resource in the Problem.

away_resources_weights

The set of resources that are currently away (on a break, home, or working in another process) and consequently not available. An away resource is a pair (resource, weight), such that the weight is the weight belonging to the resource according to the problem, i.e.: away_resources_weights[i] == problem.resource_weights[problem.resources.index(away_resources[i])]

busy_cases

The cases of which a task is currently being performed or must still be performed. A dict case_id -> [active task_id] that maps case identifiers for which a task exists to the identifiers of those tasks.

busy_resources

The resources that are currently busy. A dict resource -> (task, start), where:

• task is an instance of Task is the task that the resource is working on.

• start is the moment in simulation time at which the resource started working on the task.

desired_nr_resources()

The number of resources that is currently desired to be working now according to the problem schedule.

Returns

a number of resources.

init_simulation()

Re-initializes the simulation, such that it can be run again.

now

The current simulation time.

static replicate(problem, planner, reporter, simulation_time, replications)

Creates a simulator for each of the problem_instances, using the specified planner and reporter. Simulates each problem instance by calling the simulate() method on it using the specified simulation time. Returns the list of summaries generated by the reporter, one summary for each simulated problem_instance.

Parameters

• problem – an instance of Problem to simulate.

• planner – a Planner.

• reporter – a Reporter.

• simulation_time – the amount of simulation time for which each problem instance should be simulated.

• replications – the number of replications to do.

Returns

a list of summaries, generated by the reporter, one for each element of problem_instances.

reserved_resources

The resources that are currently reserved. A dict resource -> (task, start), where:

• resource is the label that identifies a resource in the Problem.

• task is an instance of Task is the task on which the resource is expected to work.

• start is the moment in simulation at which the resource starts processing the task.

simulate(running_time)

Runs the simulation for the instance that was passed in the constructor. The simulator generates events (i.e. cases with their associated arrival times, data, and tasks) as they are produced by the problem instance. The simulator generates a plan event each time a task or resource becomes available. Events are handled by the reporter.

If the target utilization rate is set to a value (a fraction f) other than None, the simulator will ensure that resources are occupied for approximately the targeted fraction f of the time. It does that by making resources busy with ‘other tasks’ (i.e. tasks other than the ones of the problem being simulated, like tasks in another process). These ‘other tasks’ are not specified further and their activity is not logged, but the resources are being kept busy on those tasks.

Parameters

running_time – the amount of simulation time the simulation should be run for.

unassigned_tasks

The tasks that are currently not assigned. A dict task.id -> task, where task is an instance of Task. A task is in this list if it must still be performed. After a task is completed does not re-appear in this list.

working_nr_resources()

The number of resources that is actually on the work floor now, either available, busy or reserved.

Returns

a number of resources.

class bpo.simulator.TasksReporterElement

Bases: bpo.simulator.ReporterElement

A ReporterElement that keeps information about tasks, specifically:

• tasks completed: the number of tasks that completed during the simulation run.

• task proc time: the average of the processing times of the completed tasks.

• task wait time: the average of the waiting times of the completed tasks.

This information is returned by the TasksReporterElement.summarize() method by the specified labels.

Methods:

report(event)	Is invoked when a simulation event occurs.
restart()	Is invoked when a simulation run starts.
summarize()	Is invoked when a simulation run ends.

report(event)

Is invoked when a simulation event occurs. Can store information about the event.

Parameters

event – the simulation Event that occurred.

restart()

Is invoked when a simulation run starts. Must erase all information to start a new report.

summarize()

Is invoked when a simulation run ends. Must return aggregate information about stored event information.

Returns

a list of tuples (label, value), where label is a meaningful name for the reported aggregate information, and value is the corresponding information.

class bpo.simulator.TimeUnit(value)

Bases: enum.Enum

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

Attributes:

DAYS	Measured in days.
HOURS	Measured in hours.
MINUTES	Measured in minutes.
SECONDS	Measured in seconds.

DAYS

Measured in days.

HOURS

Measured in hours.

MINUTES

Measured in minutes.

SECONDS

Measured in seconds.