:py:mod:`metacast.event_handling.event_queue` ============================================= .. py:module:: metacast.event_handling.event_queue .. autoapi-nested-parse:: Creation: Author: Martin Grunnill Date: 2024/03/08 Description: Event que for simulating models between events. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: metacast.event_handling.event_queue.EventQueue metacast.event_handling.event_queue._EventQueue .. py:class:: 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. :param events: Events to go into event queue. :type events: list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent) .. method:: reset_event_queue() Resets event queue to state at initialisation. .. method:: change_event_proportion(event_names, proportion) Change proportion attribute value of events in event_names. .. method:: change_event_factor(event_names, factor) Change factor attribute value of events in event_names. .. method:: change_event_value(event_names, value) Change value attribute value of events in event_names. .. method:: make_events_nullevents(event_names) Turns events into nullevents (do nothing events). .. method:: get_event_names() Return list of event names. .. method:: events_at_same_time() Returns a dictionary of events occurring at same time. Keys are time values are lists of event names. .. method:: 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. .. py:method:: reset_event_queue() Resets event queue to state at initialisation. :rtype: Nothing .. py:method:: _event_names_checker(event_names) .. py:method:: change_event_proportion(event_names, proportion) Change proportion attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param proportion: Value for which proportion attribute is changed to. :type proportion: float/int between 0 and 1 :rtype: Nothing .. py:method:: change_event_factor(event_names, factor) Change factor attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param factor: Value for which factor attribute is changed to. :type factor: int/float :rtype: Nothing .. py:method:: change_event_value(event_names, value) Change value attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param value: Value for which value attribute is changed to. :type value: int/float :rtype: Nothing .. py:method:: make_events_nullevents(event_names) Turns events into nullevents (do nothing events). :param event_names: Name of event(s). If 'all' is entered all events are made nullevents. :type event_names: list-like of strings or single string :rtype: Nothing .. py:method:: get_event_names() Return list of event names. :returns: Event names. :rtype: List of strings .. py:method:: 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. :rtype: dictionary .. py:method:: 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. :param model_object: Object used to define and simulate model. :type model_object: object :param run_attribute: Name of model_objects method that simulates model. Must return either a numpy array of pandas.DataFrame. :type run_attribute: string :param y0: Intial values of state varibles. :type y0: numpy.array :param end_time: End time of simulations. :type end_time: float/int :param parameters_attribute: Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints). :type parameters_attribute: string :param parameters: Parameters being used by model. :type parameters: dict {str : floats/ints} :param start_time: Start time of simulations. :type start_time: float/int, default 0 :param simulation_step: Time steps used in simulations. :type simulation_step: float/int, default 1 :param full_output: If true an info_dict is returned outlining full_output information given from running of model between events. :type full_output: bool, default False :param return_param_changes: If true dictionary outlining parameters value changes made by events. :type return_param_changes: bool, default is False :param kwargs_to_pass_to_func: Key word arguments to pass to run_attribute method. :type kwargs_to_pass_to_func: **kwargs :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. .. py:class:: _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. :param events: Events to go into event queue. :type events: list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent) .. attribute:: 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 .. attribute:: events_at_same_time A dictionary of events occurring at same time. Keys are time values are lissts of event names. :type: dict .. attribute:: times Times of events. :type: list of floats or int values. .. attribute:: earliest_event_time(self) Get the earliest event's time. .. attribute:: len Number of events in queue. :type: int .. method:: poptop() Pops item from top of queue going by order of the lowest event time first. .. method:: prep_queue_for_sim_time(start_time, end_time) Edits event queue removing events before start_time or after end_time. .. method:: not_empty() Checks that event queue is not empty. .. py: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 .. py:property:: earliest_event_time Get the earliest event's time. :rtype: int or float. .. py:method:: 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. .. py:method:: prep_queue_for_sim_time(start_time, end_time) Edits event queue removing events before start_time or after end_time. :param start_time: Start time of simulations. :type start_time: float or int :param end_time: End time of simulations. :type end_time: float or int :rtype: Nothing .. py:method:: not_empty() Checks that event queue is not empty. :rtype: bool .. py:method:: __len__() Returns number of event in queue. :rtype: int .. py:method:: __repr__() Return repr(self).