CADETProcess.dynamicEvents.EventHandler

class CADETProcess.dynamicEvents.EventHandler(cycle_time, _lock)

Bases: CachedPropertiesMixin, Structure

A handler for dynamic events that affect parameters in a process.

The EventHandler class provides a framework to schedule and manage events that cause changes to parameters during a simulation or process. This includes single point events as well as durations, and it allows for events to be dependent on others, forming complex relationships. Events can be associated with transformations or factors that determine their effect.

Primary functionalities: - Schedule events with specific timings and effects. - Establish dependencies between events. - Manage durations or continuous periods with specific characteristics. - Access sorted lists of independent and dependent events.

Attributes:

eventslist

A sorted list of scheduled events, ordered by their execution time.

durationslist

List of time durations with specific characteristics.

event_dictdict

A dictionary containing detailed information about all scheduled events.

durations_dictdict

A dictionary containing detailed information about all defined durations.

independent_eventslist

A list of events that are not influenced by other events.

dependent_eventslist

A list of events that rely on other events.

event_performersdict (not shown in provided code, description based on context)

A mapping of objects that can perform or be affected by events.

event_parameterslist

A list of unique parameters that the events will affect.

event_timeslist

A list of unique times when events are scheduled to occur, sorted chronologically.

section_timeslist

A list of times demarcating sections based on event timings.

n_sectionsint

int: Number of sections.

section_statesdict

A dictionary providing the state of event parameters at the beginning of every section.

parameter_eventsdict

A dictionary mapping each parameter to the list of events that affect it.

See also

Event

Represents a single point change in the system’s parameters.

Duration

Represents a continuous time period with specific attributes or effects.

Notes

The class relies heavily on the concept of “events”, which are instances of dynamic changes that can influence parameters in the system. These events can be independent or based on other events, creating intricate relationships to capture complex scenarios.

add_duration(name: str, time: float = 0.0) → Duration

Register a new duration or time point of interest.

Durations are specific moments in the process that do not necessarily modify attributes but are noteworthy or need to be tracked.

Parameters:

name: str

Name of the event.

timefloat

Time point for perfoming the event.

Returns:

Event:

The new Event.

Raises:

CADETProcessError

If Duration already exists.

See also

durations

remove_duration

Duration

add_event

add_event_dependency

add_event(name: str, parameter_path: str, state: float, time: float = 0.0, indices: int = None, dependencies: list = None, factors: list = None, transforms: list | None = None) → Event

Add a new event that changes a parameter during the process.

An event is a dynamic alteration that occurs at a specified time and can modify the attributes of specific objects involved in the process.

Parameters:

namestr

Name of the event.

parameter_pathstr

Path of the parameter that is changed in dot notation.

statefloat

Value of the attribute that is changed at Event execution.

timefloat

Time at which the event is executed.

dependencieslist

List of the events on which the event time depends.

factorsList

List with factors for linear combination of dependencies.

indicesint

Index slices for events that modify an entry of a parameter array.

transformslist, optional

List of functions used to transform the parameter value. Length must be equal the length of independent events. If None, no transform is applied.

Returns:

Event:

The new Event.

Raises:

CADETProcessError

If Event already exists in the event_dict

CADETProcessError

If EventPerformer is not found in EventHandler

See also

events

remove_event

add_event_dependency

Event

Event.add_dependency

add_duration

add_event_dependency(dependent_event: str, independent_events: list, factors: list | None = None, transforms: list | None = None) → None

Create a dependency relationship between events.

This method establishes how one event (dependent) is influenced by one or more other events (independents) through factors and optional transformation functions. For example, the time of a dependent event could be determined by the sum of the times of independent events multiplied by their corresponding factors.

Parameters:

dependent_eventstr

Event whose value will depend on other events.

independent_eventslist

List of independent event names.

factorslist, optional

List of factors used for the relation with the independent events. Length must be equal the length of independent events. If None, all factors are assumed to be 1.

transformslist, optional

List of functions used to transform the parameter value. Length must be equal the length of independent events. If None, no transform is applied.

Raises:

CADETProcessError

If dependent_event OR independent_events are not found. If length of factors does not equal length of independent events. If length of transforms does not equal length of independent events.

See also

Event

add_event

add_duration

remove_event_dependency

check_config() → bool

Validate the event configuration.

Ensure no duplicate events exist for a specific parameter and index and verify that constants are incorporated in polynomials.

Returns:

bool

True if all validations pass, False otherwise.

check_duplicate_events() → bool

Ensure no simulateneous events are scheduled for a specific parameter and index.

Evaluates all events scheduled for each parameter and index combination. Raises a warning if multiple events are scheduled to occur simultaneously, as this can lead to unexpected system or simulation behavior.

Returns:

bool

True if no duplicate events are detected, False otherwise.

Warning

If events are detected to occur at the same timestamp.

check_uninitialized_indices() → bool

Ensure all indices are specified when a parameter isn’t initialized.

Returns:

bool

True if all indices are properly defined, False otherwise.

Warning

If there are parameters with uninitialized entries for some indices.

cycle_time

Parameter descriptor for unsigned floating-point parameters.

property dependent_events: list[Event]

list: All events that are dependent on other events.

property durations: list[Duration]

List of all durations in the process.

property event_parameters: list[str]

list: Event parameters.

property event_performers: list[str]

list: Event peformers.

property event_times: list[float]

list: Time of events, sorted by Event time.

property events: list[Event]

list: All Events ordered by event time.

See also

Event

add_event

remove_event

event_dependencies

Durations

property events_dict: dict[str, Event | Duration]

Return Events and Durations orderd by name.

property independent_events: list[Event]

list: All events that are not dependent on other events.

property n_sections: int

int: Number of sections.

property parameter_events: dict[str, list[Event] | dict[int, list[Event]]]

Return event parameters mapped to their corresponding events.

This dictionary associates each event parameter with its list of events. For events that are index-specific, an inner dictionary is used, where each index maps to its list of events.

Notes

For index-dependent events, a separate key is added for each index.

property parameter_timelines: Dict[str, TimeLine]

Return Dict: TimeLine representation for every event parameter.

This dictionary associates each event parameter with its TimeLine object. If an event parameter is considered as one of the ‘sized parameters’, it gets associated with a MultiTimeLine object, which handles multi-dimensional or indexed data.

Each timeline, be it a regular or multi-timeline, consists of sections representing time intervals where the parameter holds a specific value or state.

property parameters: dict

dict: The EventHandler parameters.

In addition to the standard parameters retrieved from the superclass, this property adds event parameters from independent events, parameters from durations, and the cycle time.

property performer_events: Dict[str, list[Event]]

Return Dict: Event performer mapped to their corresponding list of events.

For every event, this dictionary associates the event’s performer with the event. This allows for easy retrieval of all events carried out by a specific performer.

property performer_timelines: Dict[str, dict[str, TimeLine]]

Return Dict: Each performer mapped to their TimeLines based on event parameters.

This dictionary provides a representation of event parameters in the form of timelines for each performer. This hierarchical structure helps in quickly accessing the TimeLine of any event parameter specific to a performer.

plot_events(x_axis_in_minutes: bool = True, ax: ndarray[Axes] | None = None, setup_figure_kwargs: dict | None = None) → tuple[Figure, ndarray[tuple[Any, ...], dtype[Axes]]]

Plot parameter state as a function of time.

The method creates a plot for each parameter timeline and displays the state of the parameter against time. The time is represented on the x-axis, while the parameter state is shown on the y-axis.

Parameters:

x_axis_in_minutes: bool, default=True

If True, the x-axis will be plotted using minutes.

axnp.ndarray[plt.Axes] | None, default=None

Optional array of Matplotlib Axes. If not provided, a new figure is created.

setup_figure_kwargsdict | None, default=None

Additional options to setup the figure.

Returns:

tuple[plt.Figure, npt.NDArray[plt.Axes]]

Figure and axes objects.

Notes

The time is divided into 1001 linearly spaced points between 0 and the cycle time for the evaluation of the parameter state.

remove_duration(duration_name: str) → None

Remove a specified duration or time point from tracking.

This method ensures that the specified duration is no longer considered a point of interest in the process.

Parameters:

duration_namestr

Name of the duration be removed from the EventHandler.

Raises:

CADETProcessError

If Duration is not found.

See also

add_duration

Duration

remove_event_dependency

remove_event(evt_name: str) → None

Remove a specified event from the event handler.

This method ensures that the specified event will no longer influence the process by dynamically changing any attributes.

Parameters:

evt_namestr

Name of the event to be removed

Raises:

CADETProcessError

If Event is not found.

See also

add_event

Event

Event.remove_dependency

Notes

!!! Check remove_event_dependencies

remove_event_dependency(dependent_event: str, independent_events: list) → None

Remove a previously defined dependency between events.

Parameters:

dependent_eventstr

Name of the event whose value will depend on other events.

independent_eventslist

List of independent event names.

Raises:

CADETProcessError

If dependent_event is not in list events. If one or more independent event is not in list events and durations.

See also

Event

Event.remove_dependecy

add_event_dependency

property section_states: Dict[float, dict[float, ndarray]]

Return state of event parameters at every section.

property section_times: list[float]

list: Section times.

Includes 0 and cycle_time if they do not coincide with event time.

property sized_parameters: dict

dict: Compilation of parameters from events with indices.

Besides the sized parameters fetched from the superclass, this property collects parameters from events that have associated indices.