repast4py.schedule module

This module includes classes and functions for scheduling events in a Repast4py simulation. Users will typically only use the repast4py.schedule.SharedScheduleRunner.

class repast4py.schedule.OneTimeEvent(at, evt, priority_type=PriorityType.RANDOM, priority=nan)

Bases: ScheduledEvent

Scheduled event that executes only once.

Parameters:

  • at (float) – the time of the event.

  • evt (Callable) – the callable to execute when this event is executed.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

reschedule(queue)

Null-op as this OneTimeEvent only occurs once.

void()

Voids this ScheduledEvent so that it will not execute

class repast4py.schedule.PriorityType(value)

Bases: IntEnum

Enums used to specify the priority type for scheduled events.

BY_PRIORITY = 3
FIRST = 0
LAST = 1
RANDOM = 2
class repast4py.schedule.RepeatingEvent(at, interval, evt, priority_type=PriorityType.RANDOM, priority=nan)

Bases: ScheduledEvent

Scheduled event that repeats at some specified interval.

Parameters:

  • at (float) – the time of the event.

  • interval (float) – the interval at which to repeat.

  • evt (Callable) – the callable to execute when this event is executed.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

reschedule(queue)

Reschedules this event to occur after its interval has passed.

Parameters:

  • queue (List) – the priority queue list to schedule this event on

  • sequence_count – the original sequeuce count for this event. The sequence count is used to order events scheduled for the same tick.

void()

Voids this ScheduledEvent so that it will not execute

class repast4py.schedule.Schedule

Bases: object

Encapsulates a dynamic schedule of events and a method for iterating through that schedule and exectuting those events.

Events are added to the schedule for execution at a particular tick, and with a particular priority. The first valid tick is 0. Events will be executed in tick order, earliest before latest. When multiple events are scheduled for the same tick, the events’ priorities will be used to determine the order of execution within that tick. If an event is scheduled before the current executing tick (i.e., scheduled to occur in the past) then that event is ignored.

execute()

Executes this schedule by repeatedly popping the next scheduled events off the queue and executing them.

next_tick()

Gets the tick of the next scheduled event.

Returns:

the tick at which the next scheduled event will occur or -1 if nothing is scheduled.

Return type:

float

schedule_event(at, evt, priority_type=PriorityType.RANDOM, priority=nan)

Schedules the specified event to execute at the specified tick with the specified priority. By default, events are scheduled with a random priority type.

An event’s priority_type and priority determines when it will execute with respect to other events scheduled for the same tick. The priority types are:

  • PriorityType.FIRST - events will execute before those with other PriorityTypes.

    All events with a FIRST priority type will execute in the order in which they are scheduled with respect to other FIRST priority type events.

  • PriorityType.RANDOM - events will execute in a random order, after the FIRST

    priority type events, and before the LAST priority type events. If there are BY_PRIORITY events scheduled for the same tick as RANDOM events, the RANDOM events will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.BY_PRIORITY - events will execute in the order specified by the

    priority parameter (lower values are higher priority), and after any FIRST priority events and before any LAST priority events. If there are RANDOM priority events scheduled for the same tick as BY_PRIORITY events, those will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.LAST - events will execute after those with other priority types.

    All events with a LAST priority type will execute in the order in which they are scheduled with respect to other LAST priority type events.

Parameters:

  • at (float) – the time of the event.

  • evt (Callable) – the Callable to execute when the event occurs.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

Returns:

The ScheduledEvent instance that was scheduled for execution.

Return type:

ScheduledEvent

schedule_repeating_event(at, interval, evt, priority_type=PriorityType.RANDOM, priority=nan)

Schedules the specified event to execute at the specified tick with the specified priority, and to repeat at the specified interval. By default, events are scheduled with a random priority type.

An event’s priority_type and priority determines when it will execute with respect to other events scheduled for the same tick. The priority types are:

  • PriorityType.FIRST - events will execute before those with other PriorityTypes.

    All events with a FIRST priority type will execute in the order in which they are scheduled with respect to other FIRST priority type events.

  • PriorityType.RANDOM - events will execute in a random order, after the FIRST

    priority type events, and before the LAST priority type events. If there are BY_PRIORITY events scheduled for the same tick as RANDOM events, the RANDOM events will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.BY_PRIORITY - events will execute in the order specified by the

    priority parameter (lower values are higher priority), and after any FIRST priority events and before any LAST priority events. If there are RANDOM priority events scheduled for the same tick as BY_PRIORITY events, those will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.LAST - events will execute after those with other priority types.

    All events with a LAST priority type will execute in the order in which they are scheduled with respect to other LAST priority type events.

Parameters:

  • at (float) – the time of the event.

  • interval (float) – the interval at which to repeat event execution.

  • evt (Callable) – the Callable to execute when the event occurs.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

Returns:

The ScheduledEvent instance that was scheduled for execution.

Return type:

ScheduledEvent

class repast4py.schedule.ScheduleGroup

Bases: object

A ScheduleGroup is used internally by repast4py to order events for execution.

add_evt(evt)
Parameters:

evt (ScheduledEvent) –

execute(queue)
Parameters:

queue (List) –

execute_evts(evts, queue)
Parameters:

  • evts (List) –

  • queue (List) –

Return type:

bool

reset()
property size: int
sort()
class repast4py.schedule.ScheduledEvent(at, evt, priority_type, priority)

Bases: object

A callable base class for all scheduled events. Calling instances of this class will execute the Callable evt.

Parameters:

  • at (float) – the time of the event.

  • evt (Callable) – the callable to execute when this event is executed.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

reschedule(queue)

Implemented by subclasses.

void()

Voids this ScheduledEvent so that it will not execute

class repast4py.schedule.SharedScheduleRunner(comm)

Bases: object

Encapsulates a dynamic schedule of executable events shared and synchronized across processes.

Events are added to the schedule for execution at a particular tick, and with a particular priority. The first valid tick is 0. Events will be executed in tick order, earliest before latest. When multiple events are scheduled for the same tick, the events’ priorities will be used to determine the order of execution within that tick. If an event is scheduled before the current executing tick (i.e., scheduled to occur in the past) then that event is ignored. The scheduled is synchronized across process ranks by determining the global cross-process minimum next scheduled event time, and executing only the events schedule for that time. In this way, no schedule runs ahead of any other.

Parameters:

comm (Intracomm) – the communicator over which this schedule is shared.

execute()

Executes this SharedSchedule by repeatedly popping the next scheduled events off the queue and executing them.

schedule_end_event(evt)

Schedules the specified event (a Callable) for execution when the schedule terminates and the simulation ends.

Parameters:

evt (Callable) – the Callable to execute when simulation ends.

Returns:

The ScheduledEvent instance that was scheduled to execute at the end.

Return type:

ScheduledEvent

schedule_event(at, evt, priority_type=PriorityType.RANDOM, priority=nan)

Schedules the specified event to execute at the specified tick with the specified priority. By default, events are scheduled with a random priority type.

An event’s priority_type and priority determines when it will execute with respect to other events scheduled for the same tick. The priority types are:

  • PriorityType.FIRST - events will execute before those with other PriorityTypes.

    All events with a FIRST priority type will execute in the order in which they are scheduled with respect to other FIRST priority type events.

  • PriorityType.RANDOM - events will execute in a random order, after the FIRST

    priority type events, and before the LAST priority type events. If there are BY_PRIORITY events scheduled for the same tick as RANDOM events, the RANDOM events will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.BY_PRIORITY - events will execute in the order specified by the

    priority parameter (lower values are higher priority), and after any FIRST priority events and before any LAST priority events. If there are RANDOM priority events scheduled for the same tick as BY_PRIORITY events, those will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.LAST - events will execute after those with other priority types.

    All events with a LAST priority type will execute in the order in which they are scheduled with respect to other LAST priority type events.

Parameters:

  • at (float) – the time of the event.

  • evt (Callable) – the Callable to execute when the event occurs.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

Returns:

The ScheduledEvent instance that was scheduled for execution.

Return type:

ScheduledEvent

schedule_repeating_event(at, interval, evt, priority_type=PriorityType.RANDOM, priority=nan)

Schedules the specified event to execute at the specified tick with the specified priority, and to repeat at the specified interval. By default, events are scheduled with a random priority type.

An event’s priority_type and priority determines when it will execute with respect to other events scheduled for the same tick. The priority types are:

  • PriorityType.FIRST - events will execute before those with other PriorityTypes.

    All events with a FIRST priority type will execute in the order in which they are scheduled with respect to other FIRST priority type events.

  • PriorityType.RANDOM - events will execute in a random order, after the FIRST

    priority type events, and before the LAST priority type events. If there are BY_PRIORITY events scheduled for the same tick as RANDOM events, the RANDOM events will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.BY_PRIORITY - events will execute in the order specified by the

    priority parameter (lower values are higher priority), and after any FIRST priority events and before any LAST priority events. If there are RANDOM priority events scheduled for the same tick as BY_PRIORITY events, those will be shuffled at random into the ordered BY_PRIORITY events.

  • PriorityType.LAST - events will execute after those with other priority types.

    All events with a LAST priority type will execute in the order in which they are scheduled with respect to other LAST priority type events.

Parameters:

  • at (float) – the time of the event.

  • interval (float) – the interval at which to repeat event execution.

  • evt (Callable) – the Callable to execute when the event occurs.

  • priority_type (PriorityType) – a repast4py.schedule.PriorityType specifying the type of priority used to order events that occur at the same tick.

  • priority (float) – when priority_type is PriorityType.BY_PRIORITY, the priority value is used to order all the events assigned a BY_PRIORITY priority type. Otherwise, this value is ignored. Lower values have a higher priority and will execute before those with a higher value.

Returns:

The ScheduledEvent instance that was scheduled for execution.

Return type:

ScheduledEvent

schedule_stop(at)

Schedules the execution of this schedule to stop at the specified tick.

Parameters:

at (float) – the tick at which the schedule will stop.

Returns:

The ScheduledEvent instance that executes the stop event.

Return type:

ScheduledEvent

stop()

Stops schedule execution. All events scheduled for the current tick will execute and then schedule execution will stop.

tick()

Gets the current tick.

Returns:

the currently executing tick.

Return type:

float

repast4py.schedule.create_arg_evt(evt, *args, **kwargs)

Creates a new Callable that will call the specified Callable, passing it the specified arguments when it is executed as part of a schedule. The returned Callable can be scheduled using the SharedScheduleRunner’s schedule_* methods.

Parameters:

  • evt (Callable) – the Callable to execute

  • args – the positional arguments to pass to the evt Callable

  • kwargs – the keyword arguments to pass to the evt Callable.

Returns:

A new Callable that is compatible with SharedScheduleRunner’s schedule_* methods arguments.

Return type:

Callable

repast4py.schedule.init_schedule_runner(comm)

Initializes the default schedule runner, a dynamic schedule of executable events shared and synchronized across processes.

Events are added to the scheduled for execution at a particular tick. The first valid tick is 0. Events will be executed in tick order, earliest before latest. Events scheduled for the same tick will be executed in the order in which they were added. If during the execution of a tick, an event is scheduled before the executing tick (i.e., scheduled to occur in the past) then that event is ignored. The scheduled is synchronized across process ranks by determining the global cross-process minimum next scheduled event time, and executing only the events schedule for that time. In this way, no schedule runs ahead of any other.

Parameters:

comm (Intracomm) – the communicator over which this scheduled is shared.

Returns:

The default SharedScheduledRunner instance that can be used to schedule events.

Return type:

SharedScheduleRunner

repast4py.schedule.runner()

Gets the default schedule runner, a dynamic schedule of executable events shared and synchronized across processes.

Returns:

The default SharedScheduledRunner instance that can be used to schedule events.

Return type:

SharedScheduleRunner