epymorph.event

epymorph's event framework.

epymorph components may define a set of events relevant to their function, and during processing can publish to the singleton EventBus for subscription and processing by other systems.

OnStart

Bases: NamedTuple

Event payload for the start of a simulation.

simulator instance-attribute

simulator: str

Name of the simulator class.

rume instance-attribute

rume: RUME

The RUME for the simulation.

OnTick

Bases: NamedTuple

Event payload for the completion of a simulation tick.

tick_index instance-attribute

tick_index: int

The index of the just-completed tick.

ticks instance-attribute

ticks: int

The total number of ticks for the simulation.

OnMovementStart

Bases: NamedTuple

Event payload for the start of movement processing during a tick.

tick instance-attribute

tick: int

Which simulation tick.

day instance-attribute

day: int

Which simulation day.

step instance-attribute

step: int

Which tau step (by index).

OnMovementClause

Bases: NamedTuple

Event payload for the completion of processing a movement clause.

tick instance-attribute

tick: int

Which simulation tick.

day instance-attribute

day: int

Which simulation day.

step instance-attribute

step: int

Which tau step (by index).

clause_name instance-attribute

clause_name: str

The clause processed.

requested instance-attribute

requested: NDArray[SimDType]

The number of individuals this clause 'wants' to move, that is, the values returned by its clause function. (An NxN array.)

actual instance-attribute

actual: NDArray[SimDType]

The actual number of individuals moved, by source, destination, and compartment. (An NxNxC array.)

total instance-attribute

total: int

The number of individuals moved by this clause.

is_throttled instance-attribute

is_throttled: bool

Did the clause request to move more people than were available (at any location)?

OnMovementFinish

Bases: NamedTuple

Event payload for the completion of movement processing during a tick.

tick instance-attribute

tick: int

Which simulation tick.

day instance-attribute

day: int

Which simulation day.

step instance-attribute

step: int

Which tau step (by index).

total instance-attribute

total: int

The total number of individuals moved during this tick.

DownloadActivity

Bases: NamedTuple

Part of the ADRIOProgress event payload describing ADRIO network activity.

All fields are optional, as it may be possible to measure some but not others depending on the data source. ADRIOs should avoid reporting empty activity events and instead instead just report None (see ADRIO methods).

total instance-attribute

total: int | None

How many bytes are expected to be downloaded?

downloaded instance-attribute

downloaded: int | None

How many bytes have been downloaded?

download_speed instance-attribute

download_speed: int | None

What is the current approximate download speed?

ADRIOProgress

Bases: NamedTuple

Event payload for ADRIO data processing progress.

Not all ADRIOs will be able to report progress meaningfully, but those that do should emit one event when they start (with ratio_complete == 0) and one when they finish (with ratio_complete == 1). They are free to report as many intermediate progress events as they like.

adrio_name instance-attribute

adrio_name: str

The full name of the ADRIO class.

attribute instance-attribute

attribute: AbsoluteName

The name of the attribute being evaluated.

final instance-attribute

final: bool

Is this the last progress update for this ADRIO?

ratio_complete instance-attribute

ratio_complete: float

What ratio complete is it? (0: just started; 1: done)

download instance-attribute

download: DownloadActivity | None

Download activity if any, and if it can be measured.

duration instance-attribute

duration: float | None

If complete, how long did the ADRIO take overall (in seconds)?

EventBus

EventBus()

A singleton for epymorph event publishing and subscription.

Obtain a reference to the global event bus by constructing it as usual -- EventBus() -- but be aware that this will produce the same instance every time.

on_start instance-attribute

on_start: Event[OnStart] = Event()

Event fires at the start of a simulation run.

on_tick instance-attribute

on_tick: Event[OnTick] = Event()

Event fires after each tick has been processed.

on_finish instance-attribute

on_finish: Event[None] = Event()

Event fires after a simulation run is complete.

on_movement_start instance-attribute

on_movement_start: Event[OnMovementStart] = Event()

Event fires at the start of the movement processing phase for every simulation tick.

on_movement_clause instance-attribute

on_movement_clause: Event[OnMovementClause] = Event()

Event fires after processing each active movement clause.

on_movement_finish instance-attribute

on_movement_finish: Event[OnMovementFinish] = Event()

Event fires at the end of the movement processing phase for every simulation tick.

on_adrio_progress instance-attribute

on_adrio_progress: Event[ADRIOProgress] = Event()

Event fires when an ADRIO is fetching data.