metacast.event_handling.event_queue

Creation:

Author: Martin Grunnill Date: 2024/03/08

Description: Event que for simulating models between events.

Module Contents

Classes

EventQueue	An event queue for processing events from lowest to the highest time. User defined method simulates model between events.
_EventQueue	Event queue internal to EventQueue class above.

class metacast.event_handling.event_queue.EventQueue(events)

An event queue for processing events from lowest to the highest time. User defined method simulates model between events.

See method run_simulation on how to customise simulating of model between events.

Parameters:

events (list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent)) – Events to go into event queue.

reset_event_queue()

Resets event queue to state at initialisation.

change_event_proportion(event_names, proportion)

Change proportion attribute value of events in event_names.

change_event_factor(event_names, factor)

Change factor attribute value of events in event_names.

change_event_value(event_names, value)

Change value attribute value of events in event_names.

make_events_nullevents(event_names)

Turns events into nullevents (do nothing events).

get_event_names()

Return list of event names.

events_at_same_time()

Returns a dictionary of events occurring at same time. Keys are time values are lists of event names.

run_simulation(model_object, run_attribute, y0, end_time, parameters_attribute, parameters,

start_time=0, simulation_step=1, full_output=False, return_param_changes=False, **kwargs_to_pass_to_func)

Carries out events in queue, running simulations using user defined method between events.

reset_event_queue()

Resets event queue to state at initialisation.

Return type:

Nothing

_event_names_checker(event_names)

change_event_proportion(event_names, proportion)

Change proportion attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• proportion (float/int between 0 and 1) – Value for which proportion attribute is changed to.

Return type:

Nothing

change_event_factor(event_names, factor)

Change factor attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• factor (int/float) – Value for which factor attribute is changed to.

Return type:

Nothing

change_event_value(event_names, value)

Change value attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• value (int/float) – Value for which value attribute is changed to.

Return type:

Nothing

make_events_nullevents(event_names)

Turns events into nullevents (do nothing events).

Parameters:

event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered all events are made nullevents.

Return type:

Nothing

get_event_names()

Return list of event names. :returns: Event names. :rtype: List of strings

events_at_same_time()

Returns a dictionary of events occurring at same time. Keys are time values are lists of event names.

Returns:

Keys are floats/ints values are lists of strings.

Return type:

dictionary

run_simulation(model_object, run_attribute, y0, end_time, parameters_attribute, parameters, start_time=0, simulation_step=1, full_output=False, return_param_changes=False, **kwargs_to_pass_to_func)

Carries out events in queue, running simulations using user defined method between events.

Parameters:

• model_object (object) – Object used to define and simulate model.

• run_attribute (string) – Name of model_objects method that simulates model. Must return either a numpy array of pandas.DataFrame.

• y0 (numpy.array) – Intial values of state varibles.

• end_time (float/int) – End time of simulations.

• parameters_attribute (string) – Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints).

• parameters (dict {str : floats/ints}) – Parameters being used by model.

• start_time (float/int, default 0) – Start time of simulations.

• simulation_step (float/int, default 1) – Time steps used in simulations.

• full_output (bool, default False) – If true an info_dict is returned outlining full_output information given from running of model between events.

• return_param_changes (bool, default is False) – If true dictionary outlining parameters value changes made by events.

• kwargs_to_pass_to_func (**kwargs) – Key word arguments to pass to run_attribute method.

Returns:

• y (numpy.array or pandas.Dataframe) – Solution from simulating model and processing events.

• transfers_df (pandas.Dataframe) – Details of values being transferred by events between state variables.

class metacast.event_handling.event_queue._EventQueue(events)

Event queue internal to EventQueue class above. This is kept separate from EventQueue so that a master copy can be kept for reverting changes back to.

Parameters:

events (list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent)) – Events to go into event queue.

queue

Queue events ordered by time (keys of ordered dict). When more then one event occurs at a time a deque object used to stack events. Events occurring at same time are processed under first one in first one out order.

Type:

OrderedDict

events_at_same_time

A dictionary of events occurring at same time. Keys are time values are lissts of event names.

Type:

dict

times

Times of events.

Type:

list of floats or int values.

earliest_event_time(self)

Get the earliest event’s time.

len

Number of events in queue.

Type:

int

poptop()

Pops item from top of queue going by order of the lowest event time first.

prep_queue_for_sim_time(start_time, end_time)

Edits event queue removing events before start_time or after end_time.

not_empty()

Checks that event queue is not empty.

property times

Return a list of the times of events. :returns: A list of the times of events. :rtype: list of floats or int values

property earliest_event_time

Get the earliest event’s time.

Return type:

int or float.

poptop()

Pops item from top of queue going by order of the lowest event time first.

Returns:

• event_time (float) – Time of event.

• event (child of event_handling.event.BaseEvent) – An event.

prep_queue_for_sim_time(start_time, end_time)

Edits event queue removing events before start_time or after end_time.

Parameters:

• start_time (float or int) – Start time of simulations.

• end_time (float or int) – End time of simulations.

Return type:

Nothing

not_empty()

Checks that event queue is not empty. :rtype: bool

__len__()

Returns number of event in queue.

Return type:

int

__repr__()

Return repr(self).