Code

Main script

class main.InitializationHardCodedTimeSleep

A hard-coded configuration class with number variables.

Provide the sleep times needed to properly initialize the simulation

interval_1

Time interval in seconds. Await simulation to start.

Type:

float

interval_2

Time interval in seconds. Internal loop to pause the simulation.

Type:

float

interval_3

Time interval in seconds. Await first pause stop to be concluded.

Type:

float

interval_4

Time interval in seconds. Running second at a time and waiting to get second precision simulation time.

Type:

float

interval_5

Time interval in seconds. Await CB changes to take full effect.

Type:

float

interval_6

Time interval in seconds. Internal loop for initializing the agents.

Type:

float

interval_7

Time interval in seconds. Time wait before emulating the fault event.

Type:

float

interval_8

Time interval in seconds. Needed time for the emulating fault event to take effect.

Type:

float

internal_9

Time interval in seconds. Internal loop verify if the simulation is done.

Type:

float

main.main(configuration: dict) → None

Main entry point for the simulation.

This script initializes the simulation environment, loads required data, starts the simulation, populate the agents, and once the simulation is done the outputs are written to file. The results are saved to the specified output directory as configure. The argument configuration contains all the required information. This script can be run from the command line the if __name__ == “__main__”: portion contain the file being loaded with the configuration.

Example

Run the simulation with example settings:

$ python /src/main.py

Parameters:

configuration (dict) – Contains all the required information. Please refer to the larger documentation for details.

Simulation class

class sim.Sim(config: dict)

https://gridappsd-training.readthedocs.io/en/develop/api_usage/3.6-Controlling-Simulation-API.html

on_measurment(sim, timestamp, measurements) → None

Do nothing

on_timestep(sim, timestep) → None

Do nothing

Main agents class and functions

class agents.HardCodedTimeSleep

A hard-coded configuration class with integer variables.

The added time sleep on the code is needed to enable time for the new information to arrive from the simulation to the agents or for a command to take effect in the simulation. Or for coordination withing the agents.

interval_1

Time interval in seconds. Method time_control after initialization to await distribution power system simulation and receive of messages by the actors.

Type:

int

interval_2

Time interval in seconds. Method update_cb_status the simulation needs time to implement a change.

Type:

int

interval_3

Time interval in seconds. Method on_upstream_message additional time for agents to finish current processing before proceeding.

Type:

int

class agents.SampleFeederAgent(upstream: MessageBusDefinition, downstream: MessageBusDefinition, config: Dict, area: Dict, simulation_id: str, simulation, agent_config: Dict)

A class representing a feeder agent in the distribution power system simulation.

This class extends the FeederAgent base class and includes methods for managing circuit breakers, processing messages, controlling simulation time, and handling sensor measurements. It interacts with other agents, updates internal mappings, and saves collected data to a file at the end of the simulation.

close_CB(CB_mrid: str) → None

Sends an asynchronous message to close a circuit breaker.

This method constructs and sends an asynchronous message to close the circuit breaker identified by the provided MRID (Measurement Reference ID) string.

Parameters:

CB_mrid (str) – The MRID of the circuit breaker to be closed. This string uniquely identifies the circuit breaker in the distribution network.

Returns:

None –

This method does not return any values. It sends an asynchronous message to close the specified

circuit breaker.

compute_time_for_next_event() → None

Computes and adjusts the time step for the next event in the simulation.

This method calculates the appropriate time step for the next event based on the current simulation messages. It ensures that the simulation progresses efficiently by adjusting the time step to be as large or small as needed.

message(message)

Processes and forwards messages of type ‘forwarding’, including handling communication delays and message loss.

This method handles incoming messages by recording them internally and forwarding them to the appropriate recipients. It takes into account communication delays and potential message loss during the forwarding process.

Parameters:

message (Dict) – A dictionary containing the message details. This includes information necessary for processing, handling delays, and managing message loss.

Returns:

None – This method does not return any values. It processes and forwards the message as described.

monitoring_to_file() → None

Saves the collected information to a file at the end of the simulation.

This method writes collected data to an HDF5 file that was created at the beginning of the simulation. It performs the following operations: - Saves temporal sensor measurement data in the HDF5 file, organized with metadata for sensors (e.g., a1, a2, a3, … an). - Creates a DataFrame from the message_record and saves it to the HDF5 file under the key ‘message_record’. - Pickles an overall configuration dictionary and stores it in the HDF5 file under the key ‘configuration_toml’.

Parameters:

None – This method does not take any arguments.

Returns:

None – This method does not return any values. It performs file operations to save collected data and configuration.

on_centralized_measurement(sim: Simulation, timestamp: str, measurements: Dict[str, Dict]) → None

Handles centralized sensor measurements for logging and simulation time management.

This method receives and processes sensor measurements from a centralized source, regardless of their location. It updates the sensor logs and manages simulation time based on the received data. This method is called by the simulation system whenever new measurements become available.

Parameters:

• sim (Simulation) – The simulation instance that is providing the sensor measurements and simulation time.

• timestamp (str) – A string representing the time at which the measurements were taken.

• measurements (Dict[str, Dict]) – A dictionary where keys are sensor IDs and values are dictionaries containing measurement data. Each inner dictionary holds the specific measurement details for the respective sensor.

Returns:

None –

This method does not return any values. It performs internal updates and logging based on the received

measurements and simulation time.

on_downstream_message(headers: Dict, message) → None

Processes asynchronous messages from the downstream message bus.

This method handles messages received from the downstream message bus. Messages with specific structures are processed according to the command message and message type. Messages that do not match the expected structure are logged with the instance ID, message header, and message content.

Parameters:

• headers (Dict) – A dictionary containing headers associated with the incoming message. The headers may include metadata such as instance ID and message type.

• message (Dict) – A dictionary containing the content of the incoming message. The message is processed based on its structure and type.

Returns:

None –

This method does not return any values. It performs processing and logging based on the message

received.

on_measurement(headers: Dict, message) → None

Processes asynchronous measurement messages from sensors in the distribution power system simulation.

On the first reception of a measurement message, the message is saved to a JSON file for understanding the structure of the data. For subsequent messages, it does nothing.

on_request(message_bus, headers: Dict, message) → None

Placeholder method for handling synchronous communication requests between instances.

This method is intended to be implemented for processing synchronous requests received via a message bus. It currently serves as a placeholder and does not perform any operations. The method is designed to handle requests with associated headers and messages.

Parameters:

• message_bus (_type_) – The message bus or communication channel used to receive the request.

• headers (Dict) – A dictionary containing headers associated with the request.

• message (Dict) – The request message to be processed.

on_upstream_message(headers: Dict, message) → None

Placeholder method for handling upstream message.

Not used given currently their is no upstream message.

Parameters:

• headers (Dict) – A dictionary containing headers associated with the request.

• message (Dict) – The request message to be processed.

open_CB(CB_mrid: str) → None

Sends an asynchronous message to open a circuit breaker.

This method constructs and sends an asynchronous message to open the circuit breaker identified by the provided MRID (Measurement Reference ID) string.

Parameters:

CB_mrid (str) – The MRID of the circuit breaker to be opened. This string uniquely identifies the circuit breaker in the distribution network.

Returns:

None –

This method does not return any values. It sends an asynchronous message to open the specified

circuit breaker.

test_status_of_all_agents() → None

Verifies if all registered instances of SampleSwitchAreaAgent have informed the feeder agent of completion.

This method checks the status of all registered instances to confirm whether they have communicated to the feeder agent that they have finished their processing. If all instances have reported completion, the power system simulation can proceed.

Parameters:

None – This method does not take any arguments.

Returns:

None –

This method does not return any values. It performs internal checks to determine if the simulation

can proceed based on the status of all agents.

time_control() → None

Manages the simulation time control, adjusting the time steps for the simulation as needed.

Initially, this method runs the simulation in 1-second increments while attempting to discover the simulation time via asynchronous messages. Once the simulation time is known, it computes the time for the next event and adjusts the simulation time steps accordingly. The method ensures that the simulation time steps are appropriately large or small, while handling a minimum time step of 1 second for the distribution power simulation.

Parameters:

None – This method does not take any arguments.

Returns:

None –

This method does not return any values. It performs internal adjustments to manage the simulation time

and time steps.

update_area_id_name_dict() → None

Updates internal dictionaries that map SampleSwitchAreaAgent IDs to names and vice versa.

This method refreshes two internal dictionaries: one that maps SampleSwitchAreaAgent IDs to their corresponding names and another that maps names to their corresponding IDs. This ensures that the mappings are current and accurate.

Parameters:

None – This method does not take any arguments.

Returns:

None – This method does not return any values. It updates internal dictionaries used for mapping IDs and names.

update_cb_status(CB: str) → None

Updates the status of circuit breakers based on the received CB string.

This method compares the current status of circuit breakers with the provided CB string. If the status of any circuit breaker differs from what is specified in the CB string, the method sends asynchronous messages to open or close the relevant circuit breakers accordingly with open_CB and close_CB methods.

Parameters:

CB (str) – A string representing the desired status of circuit breakers. The format of this string dictates which circuit breakers need to be opened or closed.

class agents.SampleSwitchAreaAgent(upstream: MessageBusDefinition, downstream: MessageBusDefinition, config: Dict, area: Dict, simulation_id: str, name: str, agent_config: Dict)

A sample implementation of a switch area agent for managing and processing messages in a distribution network.

This class extends SwitchAreaAgent and provides specific implementations for handling asynchronous messages, evaluating reconnection paths, managing circuit breaker status, and registering the agent. It includes methods for processing messages, updating sensor data, and communicating with other agents.

eval_reconnection_message_eval(dff: DataFrame) → None

Evaluates reconnection paths based on a DataFrame of evaluation requests from another instance.

This method receives a DataFrame containing reconnection paths evaluation requests from another instance. It processes the evaluation of these paths and sends an asynchronous message with the results back to the requesting instance. The evaluated reconnection paths evaluation message is then removed from the instance’s queue of messages.

Parameters:

dff (pd.DataFrame) – A DataFrame with reconnection paths evaluation requests from another instance. The DataFrame should contain the paths to be evaluated and any relevant parameters required for the evaluation.

Returns:

None – This method does not return any values. It performs asynchronous communication and message management.

evaluate_reconnection_path(paths_eval_df: DataFrame, local: bool) → DataFrame

Evaluates reconnection paths based on the given DataFrame and local flag.

Parameters:

• paths_eval_df (pd.DataFrame) – A DataFrame containing paths to be evaluated. The DataFrame should include relevant columns for path evaluation.

• local (bool) – A boolean flag indicating whether the evaluation is for self (True) or for a request from another source (False).

Returns:

pd.DataFrame – A DataFrame with the results of the path evaluation.

initiate_FLISR_variables() → None

Initializes the fault location isolation and service restoration (FLISR) variables.

This method sets up the variables used for the FLISR process, which involves isolating events and securing a time limit for reconnection attempts. It also initializes other auxiliary variables necessary for the cyclical FLISR process.

This method does not take any arguments and does not return any values. It is responsible for preparing the necessary state for subsequent FLISR operations.

is_matching_connection(row: Series, connection_list: list[tuple]) → bool

Checks if a connection specified by the given row exists in the connection list.

Parameters:

• row (pd.Series) – A Pandas Series representing a row of data with ‘area1’ and ‘area2’ fields.

• connection_list (list[tuple]) – A list of tuples where each tuple represents a connection with two elements corresponding to areas.

Returns:

bool –

True if the connection specified by the row (‘area1’, ‘area2’) exists in the connection list,

False otherwise.

menage_change_cb(dff: DataFrame) → None

Manages the status change of circuit breakers based on evaluated connection paths from other instances.

This method receives a DataFrame containing evaluated connection paths from other instances. It determines whether to change the status of multiple circuit breakers on the distribution network based on the agreement of feasibility among instances. Reconnection paths that are radial and require fewer circuit breaker changes are prioritized.

Parameters:

dff (pd.DataFrame) – A DataFrame with evaluated connection paths from other instances. The DataFrame should include information necessary for assessing the feasibility of the reconnection paths and deciding a reconnection path.

Returns:

None –

This method does not return any values. It executes commands to change the status of circuit breakers

as needed based on the evaluation.

on_downstream_message(headers: Dict, message: Dict) → None

Placeholder method for handling asynchronous messages from downstream

Parameters:

• headers (Dict) – message header

• message (Dict) – message

on_measurement(headers: Dict, message: Dict) → None

Processes asynchronous measurement messages from sensors in the distribution power system simulation.

On the first reception of a measurement message, the message is saved to a JSON file for understanding the structure of the data. For subsequent messages, if the simulation time and sensor log object are available, the message is processed by the sensor log object.

Parameters:

• headers (Dict) – A dictionary containing headers associated with the measurement message. Headers may include metadata such as sensor ID and timestamp.

• message (Dict) – A dictionary containing the measurement data from the sensor. The structure of the data is used for processing and logging.

Returns:

None –

This method does not return any values. It performs actions based on the reception and processing

of measurement messages.

on_request(message_bus, headers: Dict, message: Dict) → None

Placeholder method for handling synchronous communication requests between instances.

This method is intended to be implemented for processing synchronous requests received via a message bus. It currently serves as a placeholder and does not perform any operations. The method is designed to handle requests with associated headers and messages.

Parameters:

• message_bus (_type_) – The message bus or communication channel used to receive the request.

• headers (Dict) – A dictionary containing headers associated with the request.

• message (Dict) – The request message to be processed.

on_upstream_message(headers: Dict, message: Dict) → None

Processes asynchronous messages from the upstream message bus.

This method handles messages received from the upstream message bus. Messages with specific structures are processed according to the command message and message type. Messages that do not match the expected structure are logged with the instance ID, message header, and message content.

Parameters:

• headers (Dict) – A dictionary containing headers associated with the incoming message. The headers may include metadata such as instance ID and message type.

• message (Dict) – A dictionary containing the content of the incoming message. The message is processed based on its structure and type.

Returns:

None –

This method does not return any values. It performs processing and logging based on the message

received.

process_disconnected_messages(dff: DataFrame) → None

Processes self-connection status messages from all instances to update the current knowledge of disconnected areas.

This method receives a DataFrame containing self-connection status messages from all instances, including time information. It updates the internal state to reflect the current status of areas that are disconnected based on the received messages.

Parameters:

dff (pd.DataFrame) – A DataFrame with self-connection status messages from all instances. The DataFrame includes time information and status updates for areas, which are used to update the internal knowledge of disconnected areas.

Returns:

None –

This method does not return any values. It updates the internal state of the instance based on the

received messages.

process_messages() → None

Processes messages to update the knowledge of area connections and manage circuit breaker changes.

This method self-evaluates the instance’s message record to process incoming messages. It updates the internal knowledge of area connections and reconnection path evaluations. Based on the processed information, it calls the manage_change_cb method to decide whether to change the status of circuit breakers.

Parameters:

None – This method does not take any arguments.

Returns:

None – This method does not return any values. It performs internal updates and may trigger actions.

register() → None

Sends a specific registration message for the feeder agent.

This method sends a registration message to register the feeder agent. It is called only once during the instance creation to ensure that the agent is properly registered.

send_event_done_message() → None

Sends a message to inform that the instance has completed making evaluations.

This method creates and sends an asynchronous message to notify that the instance has finished its evaluation process. The communication is asynchronous, so this method initiates the sending of the message but does not wait for a response.

Parameters:

None – This method does not take any arguments.

Returns:

None – This method does not return any values. It handles the initiation of asynchronous communication.

tell_all_other_area_agents(m_content: str, m_type: str, key_delay: str) → None

Sends asynchronous messages to all other area agents.

This method constructs and sends asynchronous messages with the specified content, message type, and delay key to all other area agents. The delay key points to the time require to make the information for the message. The delay given the transportation delay is performed by the feeder agent. The messages are sent based on the provided parameters.

Parameters:

• m_content (str) – The content of the message to be sent.

• m_type (str) – The type of the message, which determines the nature of the message and how it should be handled.

• key_delay (str) – A delay key that may influence the timing or order of message delivery.

Returns:

None – This method does not return any values. It sends asynchronous messages to other area agents.

test_if_disconnected() → None

Tests if the current instance is disconnected.

This method performs a self-evaluation to determine if the instance is currently connected or disconnected. It will also send messages to other agents if there is a change in connection status or if an assessment of a reconnection path is needed. The communication with other agents is asynchronous, and this method initiates the sending of messages but does not wait for their responses.

This method does not return any values or take any arguments.

update_sensors() → None

Updates the sensor measurement data with the most recent data received from the distribution system simulation.

This method retrieves and processes the latest sensor measurement data from the distribution system simulation and updates the internal records with this new information.

Parameters:

None – This method does not take any arguments.

Returns:

None –

This method does not return any values. It updates the internal sensor measurement data with the

most recent data.

agents.filter_picklable(data) → Any

Filters a data structure to retain only picklable elements.

This function recursively traverses a data structure (which may include dictionaries, lists, and tuples) and retains only the elements that are picklable. Elements that cannot be pickled are excluded from the resulting structure. The function supports dictionaries, lists, and tuples as well as nested structures.

Parameters:

data – A data structure (dictionary, list, or tuple) to filter.

Returns:

Any –

A filtered version of the input data structure, containing only picklable elements. The type of the

returned structure matches the type of the input (dictionary, list, or tuple).

agents.is_picklable(obj) → bool

Checks if an object can be pickled.

This function attempts to pickle the provided object. If the object can be pickled without raising exceptions, it returns True. Otherwise, it returns False if the object raises a PicklingError, TypeError, or AttributeError.

Parameters:

obj – The object to check for picklability.

Returns:

bool – True if the object can be pickled, False otherwise.

agents.make_empty_message_dict() → Dict[str, str]

Creates an empty message dictionary with predefined keys.

This function initializes a dictionary where each key from a predefined list of keys is set to an empty string. The list of keys to include is specified by keys_to_check, which should be defined in the surrounding scope.

Returns:

Dict[str, str] – A dictionary with keys from keys_to_check, each mapped to an empty string.

agents.measurement_description(area: DistributedArea, agentID: str) → DataFrame

Provides a description of the mRID measurements.

Provides in a dataframe format having every row representing a given measurement mRID the:

• FROM and TO node name and mRID;

• rc4_2021 name;

• phase specification (i.e., A, B, and C);

• measurement_mRID;

• Type of measurement;

Parameters:

• area (DistributedArea) – processed cim module for the area of interest

• agentID (str) – agent ID for error logging

Returns:

pd.DataFrame – Descriptions of the measurement mRID

Helper functions

helper.comp_time(time: datetime) → str

Converts date and time to string number representation unix time

Parameters:

time (datetime) – date and time to be converted to unix time

Returns:

str – unix time of the date and time

helper.configure_logging(level: str, file_name: str, format: str, datefmt: str)

Configures the python logging

Besides configuring the python logging this functions also configure untracked exceptions to also be written to the log file.

Parameters:

• level (str) – logging level

• file_name (str) – path and name of file to have the log

• format (str) – format to write to log file

• datefmt (str) – date and time format for the log file

helper.human_time(time: str) → datetime

Convert string number to date and time

The conversions also includes the time zone. The timezone is hard codded to Coordinated Universal Time (UTC).

Parameters:

time (str) – string number representation of unix time

Returns:

datetime – date and time representation of the unix number date and time

helper.load_json(path: str) → dict

Reads text file of type json

Parameters:

path (str) – path and file name to be read

Returns:

dict – dictionary representation of the data read

helper.load_toml(path: str, core_key: str = 'core') → dict

Reads text file of type toml

The toml file is expected to have a key of core values to be replaced in a f-string stile for some of the other entries. This functions:

• reads the toml file

• calls for the update of the f-string

• reads the requested json files

Parameters:

• path (str) – path and name of file to be read

• core_key (str, optional) – key of read dictionary to be utilized as core variables for f-string type update. Defaults to ‘core’.

Returns:

dict – contains the data in toml and other files requested in the toml file

helper.os_variables(dictionary: dict) → None

Populate environmental variables

Parameters:

dictionary (dict) – key is the name of the environmental variable to be created and the value is the data to be contained in the variable.

helper.overwrite_parameters(feeder_id: str, area_id: str = '') → MessageBusDefinition

Overwrite parameters for message bus definition GridAPPSD

Parameters:

• feeder_id (str) – GridAPPSD feeder id

• area_id (str, optional) – Area of the GridAPPSD message bus. Defaults to “”.

Raises:

ValueError – missing initialization of variables to be able to utilize this function

Returns:

MessageBusDefinition – created GridAPPSD message bus for the specified feeder id and area

helper.pol_to_cart(rho: float, phi: float) → complex

Convert polar complex value format of two floats to a single complex number

Parameters:

• rho (float) – complex magnitude

• phi (float) – complex polar angle in degrees

Returns:

complex – complex number

helper.replace_json_references(d: dict)

Update dictionary with json file

For keys ending in .json the path and file name specified are read from the respective file and replaced in the dictionary.

Parameters:

d (dict) – dictionary with possible values strings ending in .json

helper.substitute_core_variables(config: dict, core: dict) → dict

Update dictionary value strings with f-string type formatting

The information to be replaced in the config dictionary is part of the core dictionary. Not using other variables other than the core dictionary for the updates.

Parameters:

• config (dict) – dictionary with f-string type string to be updated

• core (dict) – dictionary with the data to be replaced in the f-string

Returns:

dict – updated config dictionary

DFLISR specific helper functions

area_helper_functions.CB_switch_mrid(configuration: dict, meta_data: DataFrame) → None

Associates circuit breaker (CB) switch mRID (measurement Resource ID) information with the possible connections in the area agent configuration.

This function processes the connection data and the provided metadata to map the correct mRID to the relevant connections between nodes. It filters metadata for specific conditions, creates a unique identifier based on node names, and merges this data with the connection information in the configuration dictionary.

Parameters:

• configuration (dict) –

  A dictionary containing the area agent configuration. This function modifies the ‘connections’ key under ‘area_agent_configuration’ to include mRID information. The expected structure is:

  • ’connections’: A dictionary that includes:

    • ’connections’: DataFrame containing node connection information.

• meta_data (pd.DataFrame) –

  A DataFrame containing metadata related to the circuit breakers, which must include the following columns:

  • ’mRID’: Measurement Resource ID.

  • ’f_node_name’: From node name.

  • ’t_node_name’: To node name.

  • ’rc4_2021’: Type of equipment (e.g., ‘LoadBreakSwitch’).

  • ’measurement_type’: Type of measurement (e.g., ‘Pos’ for position).

  • ’phase’: Phase of the measurement (e.g., ‘A’).

Returns:

None –

The function modifies the configuration dictionary in place by adding a new key

’possible_connections_mrid’ under ‘connections’ with the updated DataFrame that includes mRID information.

area_helper_functions.additional_area_data(configuration: dict) → dict

Processes and organizes additional area-specific data for creating area agents.

This function reads various data files specified in the configuration dictionary, processes them, and updates the dictionary with structured data for area agents. It handles sensor data, connection data, Ybus matrices, and maximum load data, and organizes these into a format suitable for further use.

Parameters:

configuration (dict) –

A dictionary containing file paths and other configurations related to area agents. The dictionary keys must include:

• ’area_agent_configuration’: A dictionary with keys:

  • ’sensors’: File path for sensor data (HDF5 format).

  • ’connections’: File path for connection data (HDF5 format).

  • ’ybus’: File path for Ybus data (HDF5 format).

  • ’max_area_load’: File path for maximum area load data (HDF5 format).

Returns:

dict –

The updated configuration dictionary with the following additional keys:

• ’connections’: A dictionary with the following dataframes:

  • ’possible_connections’: Unique connections between areas.

  • ’area_connections_base’: Connections involving only areas.

  • ’substation_area_connection’: Connections involving substations.

  • ’interconnections’: List of unique node connections.

  • ’connections’: Original connections data.

• ’ybus_reduced’: A dictionary with reduced Ybus matrices for each key.

• ’max_area_load’: DataFrame with aggregated maximum load data, including additional columns for sensor names and node information.

ybus (dict): pd.Dataframe of each ybus area.

area_helper_functions.area_at_fault(prior_system_status: str, areas_disconnected: List[int], possible_connections: DataFrame, area_number: int) → bool | str

Determines if an area is at fault based on system status, disconnected areas, and possible connections.

This function evaluates whether a specific area (identified by area_number) is at fault. It checks the number of disconnected areas, validates the provided data, and analyzes the connections to determine if the area is at fault. The analysis uses graph-based path finding to identify connections between the area and the disconnected nodes.

Parameters:

• prior_system_status (str) – A string representing the prior system status, where the last part indicates circuit breaker status.

• areas_disconnected (List[int]) – A list of area numbers that are currently disconnected.

• possible_connections (pd.DataFrame) – A DataFrame containing possible connections between areas, with ‘area1’ and ‘area2’ columns.

• area_number (int) – The area number to be checked for fault status.

Returns:

Union[bool, str] – Returns True if the area is at fault, False if it is not, or an error message string if there are issues with the input data.

area_helper_functions.area_disconnected(df: DataFrame) → bool

Evaluate if area disconnected based on the sensor for that time dataframe

Parameters:

df (dataframe) – sensors for that time

Returns:

disconnected (boolean) – is or is not disconnected

area_helper_functions.calculate_path_cost(graph: Graph, path: List[int]) → float

Calculates the total cost of a path in a graph.

This function computes the cost of traversing a given path in the provided graph. It sums the costs of the edges that make up the path. The graph is expected to have edge attributes named ‘Cost’ which represent the cost of each edge.

Parameters:

• graph (nx.Graph) – A NetworkX graph object containing edge attributes ‘Cost’.

• path (List[int]) – A list of node identifiers representing the path in the graph.

Returns:

float – The total cost of traversing the given path.

area_helper_functions.create_eq_ybus_df(df: DataFrame, interconnections: DataFrame, area: int)

Creates an equivalent Y-bus matrix DataFrame by reducing the original DataFrame based on specified criteria.

This function processes the input DataFrame df to generate a reduced version of the Y-bus matrix, focusing on specific nodes derived from the intersection with interconnections and additional area-based nodes. It returns both the reduced Y-bus DataFrame and a list of area-specific nodes.

Parameters:

• df (pd.DataFrame) – The original DataFrame representing the Y-bus matrix.

• interconnections (pd.DataFrame) – DataFrame containing interconnection nodes to be preserved.

• area (int) – An integer representing the area to be considered for node filtering.

Returns:

tuple[pd.DataFrame, list[str]] – - pd.DataFrame: The reduced Y-bus matrix DataFrame with only the relevant nodes. - list[str]: A list of area-specific node names used in the reduction.

area_helper_functions.create_equivalent_ybus(ybus: ndarray, buses_to_keep: ndarray) → ndarray

Creates an equivalent ybus matrix by replacing the specified buses with equivalent admittances.

The relationship between current and voltage is given by:

$$ I = Y_{bus} V $$

Where:

$$left[begin{array}{c}I_{Study} \ I_{External}end{array}right]=left[begin{array}{ll}Y_{S,S} & Y_{S,E} \ Y_{E,S} & Y_{E,E}end{array}right] left[begin{array}{c}V_{Study} \ V_{External}end{array}right]$$

And:

$$I_{study}=(Y_{s,s}-Y_{s,e}Y_{e,e}^{-1}Y_{e,s})V_{study}+Y_{s,e}Y_{e,e}^{-1}I_{external}$$

Parameters:

• ybus (np.ndarray) – The original ybus matrix.

• buses_to_keep (np.ndarray) – Array of indices of the buses to keep.

Returns:

np.ndarray – The equivalent ybus matrix.

area_helper_functions.get_all_neighbors(G: Graph, area: int) → List[int]

Retrieves all neighbors of a given area in a network, including indirect neighbors.

This function uses a breadth-first search approach to identify not only the direct neighbors but also all indirectly connected nodes in the network. It explores the entire connected component of the specified area in the graph.

Parameters:

• G (nx.Graph) – A NetworkX graph object representing the network, with nodes and edges.

• area (int) – The node identifier for which neighbors are to be found.

Returns:

List[int] – A list of node identifiers representing all neighbors of the specified area, including indirect neighbors.

area_helper_functions.get_area_connected_neighbors(possible_connections: DataFrame, cd_new_for_path: str, path: List[int]) → List[int]

Retrieves the list of neighbors connected to a specified area based on updated circuit breaker status.

This function identifies the neighbors of a given area within a network, considering the updated circuit breaker status. It uses the provided connections data and the updated CB status to construct a graph and determine all connected neighbors.

Parameters:

• possible_connections (pd.DataFrame) – A DataFrame containing possible connections between areas with attributes such as ‘area1’, ‘area2’, and status.

• cd_new_for_path (str) – A string representing the updated circuit breaker status for the path.

• path (List[int]) – A list of node identifiers representing the path. The first node in this list is used to determine the area for which neighbors are to be identified.

Returns:

List[int] – A list of node identifiers representing the neighbors of the specified area.

area_helper_functions.get_new_expected_CB(cb: str, areas_disconnected: list, possible_connections: DataFrame) → str

Generates a new circuit breaker status string based on areas that are disconnected.

This function updates the given circuit breaker status string by setting the status of circuit breakers corresponding to disconnected areas to “0” (indicating open). It then returns the updated status string.

Parameters:

• cb (str) – A string representing the current circuit breaker status, where each character corresponds to the status of a specific breaker.

• areas_disconnected (list) – A list of areas that are currently disconnected from the network.

• possible_connections (pd.DataFrame) – A DataFrame containing the possible connections in the network, with columns ‘area1’ and ‘area2’ representing connections between areas.

Returns:

str – The updated circuit breaker status string with breakers in disconnected areas set to “0”.

area_helper_functions.get_results_model_reduction(Y_BUS: DataFrame, area_connections: DataFrame, sensor: DataFrame, substation_area_connection: DataFrame, sensors_area_max_load: DataFrame) → dict

Prepares ybus model to execute the state estimation with model reduction.

Performs state estimation (SE) on a power system model by modifying the Y-bus matrix and incorporating sensor data. The function processes connections and sensor data to simulate circuit breaker (CB) state changes and determines if a connection is feasible based on voltage magnitude thresholds.

Parameters:

• Y_BUS (pd.DataFrame) – The Y-bus admittance matrix of the system, which is modified in-place to reflect the current CB state. Rows and columns represent the nodes in the system.

• area_connections (pd.DataFrame) – DataFrame containing node-to-node connections within the area. Columns expected: [‘node1’, ‘node2’].

• sensor (pd.DataFrame) – DataFrame with sensor data for state estimation. This is concatenated with additional virtual sensors and reference voltages within the function.

• substation_area_connection (pd.DataFrame) – DataFrame containing the connection information for substations. Used to define reference voltages.

• sensors_area_max_load (pd.DataFrame) – DataFrame containing the maximum load sensor data for the area. Expected columns include [‘node1’, ‘node2’, ‘sensor_type’, ‘sensor_name’].

Returns:

dict –

A dictionary containing:

• ’V magnitude maximum’ (float): The maximum voltage magnitude resulting from state estimation.

• ’V magnitude minimum’ (float): The minimum voltage magnitude resulting from state estimation.

• ’connection_possible’ (bool): A flag indicating whether the connection is feasible based on voltage limits.

area_helper_functions.identify_CB_status_is_radial(possible_connections: DataFrame, cd_new_for_path: str) → bool

Determines if the circuit breaker status, represented by a given configuration string, is radial in respect to a substation.

This function evaluates the connectivity of the network based on the circuit breaker status described in cd_new_for_path. It checks if each area is connected to the substations in a way that would be classified as radial, meaning each area is directly connected to a substation without alternative paths.

Parameters:

• possible_connections (pd.DataFrame) – A DataFrame containing the possible connections in the network, with columns ‘area1’ and ‘area2’ representing connections between areas.

• cd_new_for_path (str) – A string representing the circuit breaker status, where each character corresponds to the status of a specific breaker.

Returns:

bool – True if the network configuration is radial with respect to substations, False otherwise.

area_helper_functions.identify_new_CB(system_status: str, possible_connections: DataFrame, path: List[int]) → Dict

Identifies circuit breaker (CB) changes for a given path based on the system status and possible connections.

This function determines which circuit breakers need to be changed (opened or closed) to accommodate a given path, based on the current system status and the status of possible connections. It returns a dictionary containing details about the path, circuit breaker changes, and affected areas.

Parameters:

• system_status (str) – A string representing the current system status, including circuit breaker states.

• possible_connections (pd.DataFrame) – A DataFrame containing possible connections between areas, with attributes such as status.

• path (List[int]) – A list of node identifiers representing the path for which CB changes are to be identified.

Returns:

Dict[str, bool, str, list, list] – - “path”: The given path as a list of node identifiers. - “substation_radial”: A boolean indicating if the CB status is radial. - “cb_path”: A string representing the updated CB status for the path. - “cbs_to_close”: A list of indices of circuit breakers that need to be closed. - “areas_involved”: A dictionary of areas involved in the path and their connected neighbors.

area_helper_functions.reconnection_paths(prior_system_status: str, areas_disconnected: List[int], possible_connections: DataFrame, area_number: int) → Dict

Computes potential reconnection paths and their associated costs based on the current system status.

This function analyzes reconnection paths for a specified area based on the prior system status, disconnected areas, and possible connections. It updates the costs of connections, builds a graph representation, and computes all simple paths between the area and potential reconnection targets. It also calculates the cost of each path.

Parameters:

• prior_system_status (str) – A string representing the prior system status, including circuit breaker states.

• areas_disconnected (List[int]) – A list of area numbers that are currently disconnected.

• possible_connections (pd.DataFrame) – A DataFrame containing possible connections between areas, with ‘area1’, ‘area2’, and edge attributes.

• area_number (int) – The area number for which reconnection paths are to be evaluated.

Returns:

Dict –

A dictionary where:

• Keys are strings representing targets and their path costs (e.g., ‘target’ and ‘target_cost’).

• Values are lists of simple paths or path costs, depending on the key.

State estimation module

Created on Thu Jul 7 10:52:28 2022

@author: Monish Mukherjee and Fernando

SE.SE.combine(a: list, n: int) → list

Combine a flat list into a list of sublists, where each sublist has a specified length n.

Parameters:

• a (list) – The list to be combined into sublists.

• n (int) – The length of each sublist.

Returns:

list of lists – A list containing sublists of length n from the original list a.

SE.SE.get_voltages_state_estimation(Y_bus: DataFrame, sensor: DataFrame, print_results: bool = False, CB_error: bool = False, measurement_error: bool = False) → tuple

Perform state estimation to get the voltage states for a power distribution system network.

This function estimates the voltage states (amplitude and angle) at various nodes of a power distribution system network using Weighted Least Squares (WLS) method. It processes sensor measurements, checks for bad data, and optionally prints the results.

Parameters:

• Y_bus (pd.DataFrame) – Admittance bus matrix of the power distribution system network.

• sensor (pd.DataFrame) – DataFrame containing sensor measurements and their characteristics (i.e., type, location, variance, and measurement).

• print_results (bool, optional) – If True, print detailed estimation results and bad data detection information. Defaults to False.

• CB_error (bool, optional) – If True, introduces a error in circuit breaker measurements for testing purposes. Defaults to False.

• measurement_error (bool, optional) – If True, introduces random measurement errors based on the variance of measurements. Defaults to True.

Returns:

tuple – - results_table (pd.DataFrame): DataFrame containing the estimated voltage amplitudes and angles at each node. - s_area (pd.DataFrame): DataFrame containing the processed sensor measurements and associated information. - bool: Boolean indicating whether bad data exists in the measurements (True if bad data exists, False otherwise). - s_u (np.ndarray): State vector obtained from the WLS estimation. - e_2 (np.ndarray): Residual vector from the WLS estimation.

SE.SE.split(a: list, n: int) → list

Split a list into n parts as evenly as possible.

Parameters:

• a (list) – The list to be split.

• n (int) – The number of parts to split the list into.

Returns:

list of lists – A list containing n sublists, with each sublist containing a portion of the original list a.

Created on Dec 12 2019

@author: Moosa Moghimi Original code available on: https://github.com/Moongar/DSSE/blob/master/WLS.py

@author: modified by Monish Mukherjee (2022)

SE.WLS.format_measurement(P_ij: ndarray, P_i: ndarray, Q_ij: ndarray, Q_i: ndarray, Vi: ndarray, Theta_i: ndarray, I_ij: ndarray) → ndarray

Format various power system sensor measurements into a standardized array.

This function takes different types of measurements (real power, reactive power, voltage magnitudes, etc.) and formats them into a unified NumPy array z with the appropriate measurement types.

Parameters:

• P_ij (np.ndarray) – Real power flow measurements between nodes (P_ij).

• P_i (np.ndarray) – Real power injections at nodes (P_i).

• Q_ij (np.ndarray) – Reactive power flow measurements between nodes (Q_ij).

• Q_i (np.ndarray) – Reactive power injections at nodes (Q_i).

• Vi (np.ndarray) – Voltage magnitudes at nodes (Vi).

• Theta_i (np.ndarray) – Voltage angles at nodes (Theta_i).

• I_ij (np.ndarray) – Current flow measurements between nodes (I_ij).

Returns:

np.ndarray – A 2D array containing the formatted measurements along with their types and associated information.

SE.WLS.state_estimation(ybus: ndarray, z: ndarray, zmeas: ndarray, err_cov: ndarray, iter_max: int, threshold: float, V_guess: ndarray, Theta_guess: ndarray) → tuple

Perform state estimation using the Weighted Least Squares (WLS) method.

This function estimates the voltage magnitudes and angles at each bus in the power distribution network based on the provided measurements and their covariance matrix using the WLS method.

Parameters:

• ybus (np.ndarray) – The admittance matrix of the power system network.

• z (np.ndarray) – Array containing measurement types and associated information.

• zmeas (np.ndarray) – Measurement values.

• err_cov (np.ndarray) – Error covariance matrix of the measurements.

• iter_max (int) – Maximum number of iterations allowed for the WLS method to converge.

• threshold (float) – Convergence threshold for the WLS method.

• V_guess (np.ndarray) – Initial guess for the voltage magnitudes.

• Theta_guess (np.ndarray) – Initial guess for the voltage angles.

Returns:

tuple – - v_phasor (np.ndarray): Estimated complex voltage phasors for each bus. - k (int): Number of iterations taken for the WLS method to converge. - f_ind (np.ndarray): Indices of measurement residuals. - s_u (float): Sum of the diagonal elements of the gain matrix. - e_2 (float): Sum of squares of measurement residuals.

Monitoring module

class MO.monitoring.DataProcessor(file_name: str, meta_data: DataFrame, w_unprocessed_data: bool, delta_time: int, max_rows: int = 200000, complevel: int = 1)

Bases: object

A class used to process and store data from simulations.

This class initialize the single output file from the simulation. This class stores and process the sensor measurement data only. The measurement data store by this class object is not utilized in the analysis.

file_name

The name of the file to store the processed data.

Type:

str

w_unprocessed_data

A flag indicating if raw data should be stored without processing.

Type:

bool

max_rows

The maximum number of rows to store before processing.

Type:

int

delta_time

The time interval for resampling data.

Type:

timedelta

name_key

A counter for naming data chunks written to the file.

Type:

int

complevel

The compression level for storing data in HDF5 format.

Type:

int

columns

The columns of the data being processed.

Type:

list

raw_data_storage

A DataFrame to temporarily store raw data.

Type:

pd.DataFrame

processed_data_storage

A DataFrame to store processed data.

Type:

pd.DataFrame

close_data_processor() → None

Processes any remaining data and writes it to the file before closing.

get_processed_data() → DataFrame

Returns the currently stored processed data.

Returns:

pd.DataFrame – A DataFrame containing the processed data.

process_data() → None

Processes the stored raw data based on the w_unprocessed_data flag and resampling requirements. If the number of processed rows exceeds max_rows, the data is written to the file.

receive_data(unique_id, timestamp, value) → None

Receives and stores incoming data. Processes the data if the storage exceeds the max_rows limit.

Parameters:

• unique_id (int) – The unique identifier for the data entry.

• timestamp (pd.Timestamp) – The timestamp of the data entry.

• value (float) – The value of the data entry.

start_file(meta_data: DataFrame) → None

Initializes the HDF5 file with metadata.

Parameters:

meta_data (pd.DataFrame) – The metadata to be stored in the file.

to_file() → None

Writes the processed data to the HDF5 file and increments the name_key. Clears the processed data storage.

class MO.trekker.DataTrekker(meta_data: DataFrame, sensors: DataFrame, max_rows: int = 200000)

Bases: object

A class used to process and store sensor data from simulations.

Differently than the class DataProcessor. This class store data is utilized for decision making. Furthermore, this class does not write any information to file. The simulation of the distributed power grid sensors is converted to the sensors according to the input sensor information with specific variances (i.e., precision). The data can be called to be utilized in evaluating the switch delimited area during the simulation.

meta_data

The metadata for the simulation.

Type:

pd.DataFrame

sensors

The sensor data for the simulation.

Type:

pd.DataFrame

max_rows

The maximum number of rows to store before removing old data.

Type:

int

columns

The columns of the data being processed.

Type:

list

sensor_data

A DataFrame to temporarily store sensor data.

Type:

pd.DataFrame

add_receive_data(new_data: DataFrame) → None

Adds new sensor data to the existing data storage.

Parameters:

new_data (pd.DataFrame) – The new data to be added.

get_most_recent_data() → DataFrame

Retrieves the most recent sensor data.

Returns:

pd.DataFrame – A DataFrame containing the most recent data.

organize_data() → None

Organizes the sensor data by sorting and removing duplicates.

process_metadata(meta_data: DataFrame) → None

Processes and updates the metadata.

Parameters:

meta_data (pd.DataFrame) – The metadata to be processed.

process_sensors(sensors: DataFrame) → None

Processes and updates the sensor data.

Parameters:

sensors (pd.DataFrame) – The sensor data to be processed.

receive_data(unique_id: str, timestamp: Timestamp, value: complex) → None

Receives and processes incoming sensor data.

Parameters:

• unique_id (str) – The unique identifier for the data entry.

• timestamp (pd.Timestamp) – The timestamp of the data entry.

• value (complex) – The value of the data entry.

remove_old_data() → None

Removes old sensor data exceeding the maximum row limit.