NREL-erad 0.1.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

erad/metrics/check_microgrid.py

@@ -0,0 +1,208 @@
+""" This module contains functions and utilities to check for the
+possibility of microgrid formation.
+"""
+
+from typing import List, Dict
+import math
+import json
+
+from neo4j import GraphDatabase
+import networkx as nx
+import matplotlib.pyplot as plt
+
+
+def create_directed_graph(
+    driver: GraphDatabase.driver,
+):
+    """Creates a directed graph representation of the power network.
+
+    For now we have read all the relationships and nodes. We will need to
+    filter this by feeder to avoid running into memory issues in future for
+    larger graph.
+
+    Args:
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+    """
+
+    # Get the buses, customers, pvs, energystorage and line sections
+    power_network_query = """
+    MATCH (sourceNode:Bus)-[relationship:CONNECTS_TO]-(targetNode:Bus)
+    return relationship{.*} , sourceNode {.*}, targetNode{.*}
+    """
+
+    # Gettings relations between customers and buses
+    customer_bus_network_query = """
+    MATCH (sourceNode:Bus)-[relationship:CONSUMES_POWER_FROM]-(targetNode:Load)
+    return relationship{.*} , sourceNode {.*}, targetNode{.*}
+    """
+
+    # Gettings relations between critical infrastructures and buses
+    critical_infra_bus_network_query = """
+    MATCH (sourceNode:Bus)-[relationship:GETS_POWER_FROM]-(targetNode)
+    return relationship{.*} , sourceNode {.*}, targetNode{.*}
+    """
+
+    # Gettting relations between PVs and buses
+    pv_bus_network_query = """
+    MATCH (sourceNode:Bus)-[relationship:INJECTS_ACTIVE_POWER_TO]-(targetNode:Solar)
+    return relationship{.*} , sourceNode {.*}, targetNode{.*}
+    """
+
+    # Getting relations between energy storage and buses
+    es_bus_network_query = """
+    MATCH (sourceNode:Bus)-[relationship:INJECTS_POWER]-(targetNode:EnergyStorage)
+    return relationship{.*} , sourceNode {.*}, targetNode{.*}
+    """
+
+    relations = []
+    for query in [
+        power_network_query,
+        customer_bus_network_query,
+        pv_bus_network_query,
+        es_bus_network_query,
+        critical_infra_bus_network_query
+    ]:
+
+        with driver.session() as session:
+            result = session.read_transaction(lambda tx: tx.run(query).data())
+        relations.extend(result)
+
+    graph = nx.Graph()
+    for rel in relations:
+
+        # Unpack the relationship data
+        relationship = rel["relationship"]
+        source_node = rel["sourceNode"]
+        target_node = rel["targetNode"]
+
+        # Add nodes if not already present in the graph
+        for node in [source_node, target_node]:
+            if not graph.has_node(node["name"]):
+                graph.add_node(node["name"], **node)
+
+        # Add relationship
+        graph.add_edge(source_node["name"], target_node["name"], **relationship)
+
+    return graph.to_directed()
+
+def node_connected_to_substation(
+    substation_nodes: List[str],
+    driver: GraphDatabase.driver
+):
+    """ Gives list of nodes still connected to substation. """
+    directed_graph = create_directed_graph(driver)
+    edges_to_be_removed = []
+
+    for edge in directed_graph.edges():
+        edge_data = directed_graph.get_edge_data(*edge)
+        if "survive" in edge_data and int(edge_data["survive"]) == 0:
+            edges_to_be_removed.append(edge)
+
+    if edges_to_be_removed:
+        directed_graph.remove_edges_from(edges_to_be_removed)
+        wcc = nx.weakly_connected_components(directed_graph)
+
+        for _, weak_component in enumerate(wcc):
+            wcc_graph = directed_graph.subgraph(weak_component)
+            nodes = wcc_graph.nodes()
+            for sub_node in substation_nodes:
+                if sub_node in nodes:
+                    return nodes
+    else:
+        nodes = []
+        for edge in directed_graph.edges():
+            nodes.extend(edge)
+        return nodes
+    return []
+            
+
+def check_for_microgrid(driver: GraphDatabase.driver, output_json_path: str):
+    """Checks for possibility of microgrid in each subgraph.
+
+    Args:
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+       output_json_path (str): JSON file path for exporting the metric.
+    """
+
+    directed_graph = create_directed_graph(driver)
+    node_data = {item[0]: item[1] for item in directed_graph.nodes(data=True)}
+
+    edges_to_be_removed = []
+    subgraphs = {}
+
+    for edge in directed_graph.edges():
+        edge_data = directed_graph.get_edge_data(*edge)
+        if "survive" in edge_data and int(edge_data["survive"]) == 0:
+            edges_to_be_removed.append(edge)
+
+    if edges_to_be_removed:
+        directed_graph.remove_edges_from(edges_to_be_removed)
+        wcc = nx.weakly_connected_components(directed_graph)
+
+        for id, weak_component in enumerate(wcc):
+
+            # Let's create a networkx representation to perform
+            # multiple source multiple sink max flow problem
+            # https://faculty.math.illinois.edu/~mlavrov/docs/482-fall-2019/lecture27.pdf
+            source_capacity, sink_capacity = 0, 0
+            wcc_graph = directed_graph.subgraph(weak_component)
+            wcc_graph = nx.DiGraph(wcc_graph)
+
+            for new_node in ["infinity_source", "infinity_sink"]:
+                if not wcc_graph.has_node(new_node):
+                    wcc_graph.add_node(new_node)
+
+            sinks, sources = [], []
+            for node in wcc_graph.nodes():
+                # Connect all loads to infinity sink
+
+                if "pv" in node or "es_" in node or node_data.get(node, {}).get('backup', None) == 1:
+                    wcc_graph.add_edge(node, "infinity_source", capacity=1e9)
+                    wcc_graph.add_edge("infinity_source", node, capacity=1e9)
+                    sources.append(node)
+
+                    cap_ = None 
+                    if 'kw' in node_data[node]:
+                        cap_ = node_data[node]["kw"]
+                    elif 'capacity' in node_data[node]:
+                        cap_ = node_data[node]["capacity"]
+                    elif 'backup_capacity_kw' in node_data[node]:
+                        cap_ = node_data[node]["backup_capacity_kw"]
+                    else:
+                        raise Exception('Not a valid source!')
+                    source_capacity += cap_
+
+                elif "load" in node or node_data.get(node, {}).get('survive', None) is not None :
+                    wcc_graph.add_edge(node, "infinity_sink", capacity=1e9)
+                    wcc_graph.add_edge("infinity_sink", node, capacity=1e9)
+                    sinks.append(node)
+                    sink_capacity += math.sqrt(
+                    node_data[node].get('kW', 0) ** 2
+                    + node_data[node].get('kvar', 0) ** 2
+                    ) * float(node_data[node].get("critical_load_factor", 0))
+                   
+            
+            # if id == 2:
+            #     breakpoint()
+            flow_value, _ = nx.maximum_flow(
+                wcc_graph, "infinity_source", "infinity_sink", capacity="kva"
+            )
+    
+            subgraphs[f"weak_component_{id}"] = {
+                "length": len(weak_component),
+                "max_flow": flow_value,
+                "sources": sources,
+                "sinks": sinks,
+                "source_capacity": source_capacity,
+                "sink_capacity": sink_capacity,
+            }
+
+
+
+    if output_json_path:
+        with open(output_json_path, "w") as fpointer:
+            json.dump(subgraphs, fpointer)
+
+    return subgraphs

erad/metrics/metric.py

@@ -0,0 +1,178 @@
+""" Module for handling computation of equity and resilience metrics.
+
+Idea is to create separate function for computing each metric. 
+"""
+
+from pathlib import Path
+from typing import Callable, Union, Dict, List
+import json
+
+from neo4j import GraphDatabase
+import pandas as pd
+import numpy as np
+
+from erad.utils import util
+from erad import exceptions
+
+
+def validate_export_path(file_path: Union[str, Path], file_type: str):
+    """Function for validating the export file path.
+
+    Args:
+        file_path (Union[str, Path]): Export file path
+        file_type (str): File type to be exported e.g. .csv
+    """
+
+    output_path = Path(file_path)
+    util.path_validation(output_path.parent)
+    if output_path.suffix != file_type:
+        raise exceptions.InvalidFileTypePassed(output_path, file_type)
+
+
+def is_customer_getting_power(
+    driver: GraphDatabase.driver, output_csv_path: str,
+    load_list: List[str] = None
+):
+
+    """Function for checking whether customer is still connected
+    to substation or not.
+
+    Args:
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+        output_csv_path (str): CSV file path for exporting the metric.
+    """
+    if not load_list:
+        load_list = []
+
+    validate_export_path(output_csv_path, ".csv")
+    cypher_query = """
+                    MATCH (b:Bus)
+                    MATCH (s:Substation)
+                    WHERE b <> s
+                    WITH b, shortestPath((b)-[:CONNECTS_TO*]-(s)) as p
+                    MATCH (c:Load)-[:CONSUMES_POWER_FROM]-(b)
+                    WITH c, p, apoc.coll.min([r in relationships(p) | r.survive]) AS max_p
+                    RETURN c.name, max_p
+                """
+    metric_container = {"load_name": [], "metric": []}
+    with driver.session() as session:
+        result = session.read_transaction(
+            lambda tx: tx.run(cypher_query).data()
+        )
+
+        for item in result:
+            metric_container["load_name"].append(item["c.name"])
+            metric_container["metric"].append(item["max_p"] \
+                                              if item["c.name"] not in load_list else 1)
+
+    df = pd.DataFrame(metric_container)
+    df.to_csv(output_csv_path)
+
+
+def energy_resilience_by_customer(
+    driver: GraphDatabase.driver, output_csv_path: str,
+    critical_infras: List = ["Grocery", "Hospital", "Pharmacy"]
+):
+    """Function for checking whether customer is still connected
+    to substation or not.
+
+    Args:
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+        output_csv_path (str): CSV file path for exporting the metric.
+    """
+
+    validate_export_path(output_csv_path, ".csv")
+
+    metric_container = {"load_name": [], "metric": [], "critical_service": []}
+    with driver.session() as session:
+
+        for cs in critical_infras:
+            cypher_query = (
+                f"""
+                    MATCH (lo:Load)
+                    MATCH (cs:{cs})
+                    """
+                + """
+                    WITH lo,cs, 
+                        point.distance(point({longitude: lo.longitude, latitude:lo.latitude}), 
+                        point({longitude: cs.longitude, latitude:cs.latitude}))/1000 AS d
+                    RETURN lo.name, sum(toInteger(toBoolean(cs.survive) OR toBoolean(cs.backup))/d) AS gamma
+                    """
+                    # count(d)/sum(d) AS gamma
+                    # WHERE cs.survive = 1 
+            )
+            result = session.read_transaction(
+                lambda tx: tx.run(cypher_query).data()
+            )
+
+            for item in result:
+                metric_container["load_name"].append(item["lo.name"])
+                metric_container["metric"].append(item["gamma"])
+                metric_container["critical_service"].append(cs)
+
+    df = pd.DataFrame(metric_container)
+    df.to_csv(output_csv_path)
+
+
+def equity_based_energy_resilience_by_income(
+    driver: GraphDatabase.driver,
+    path_to_energy_resilience_metric: str,
+    output_json_path: str,
+    category: Dict[str, Callable] = {
+        "low": lambda x: x < 90000,
+        "medium": lambda x: (90000 < x < 110000),
+        "high": lambda x: x > 110000,
+    },
+):
+    """Function to compute the equity based energy resilience metric.
+
+    Args:
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+        path_to_energy_resilience_metric (str): Path to energy resilience metric.
+        output_json_path (str): JSON file path for exporting the metric.
+        category (Dict[str, Callable]): Income categories
+    """
+
+    validate_export_path(output_json_path, ".json")
+    util.path_validation(path_to_energy_resilience_metric)
+
+    metric_container = {}
+
+    with driver.session() as session:
+
+        cypher_query = """
+                            MATCH (lo:Load)
+                            RETURN lo.income as income, lo.name as name
+                        """
+        result = session.read_transaction(
+            lambda tx: tx.run(cypher_query).data()
+        )
+
+    resilience_metric = pd.read_csv(path_to_energy_resilience_metric)
+    gamma_dict = (
+        resilience_metric.groupby("load_name").sum()["metric"].to_dict()
+    )
+
+    for id, func in category.items():
+
+        metric, income_flag_sum = 0, 0
+        for load in result:
+            load_income_flag = func(load["income"])
+            metric += load_income_flag * gamma_dict[load["name"]]
+            income_flag_sum += load_income_flag
+
+        metric_container[id] = (
+            metric / income_flag_sum if income_flag_sum else None
+        )
+
+    metric_values = [val for _, val in metric_container.items() if val]
+    if metric_values:
+        metric_container["community_resilience_equity_score"] = np.mean(
+            metric_values
+        ) / np.std(metric_values)
+
+    with open(output_json_path, "w") as fpointer:
+        json.dump(metric_container, fpointer)

erad/programs/backup.py

@@ -0,0 +1,62 @@
+""" This module will update the backup property for 
+critical infrastructure. """
+
+# standard imports
+from typing import List
+import random
+
+# third party imports
+from neo4j import GraphDatabase
+
+# internal imports
+from erad.db.utils import _run_read_query
+
+def apply_backup_program(
+    driver: GraphDatabase.driver,
+    electricity_backup: any,
+    critical_infras: List[str],
+):
+
+    """ Function that will update the backup 
+    property of critical infras based on backup percentage.
+    
+    Args:
+        driver (GraphDatabase.driver): Neo4J Driver instance
+        electricity_backup (float): backup percentage number between 0 and 1 or list of infras to set as backup
+        critical_infras (List[str]): list of critical infrastructure
+    """
+
+    infra_with_backups = []
+    for cri_infra in critical_infras:
+        cypher_query = f"""
+                        MATCH (c:{cri_infra})
+                        RETURN c.longitude, c.latitude, c.name, c.backup
+                    """
+        infras = _run_read_query(driver, cypher_query)
+        
+        for infra in infras:
+            
+            cypher_write_query = f"""
+                MATCH (c:{cri_infra})
+                WHERE c.name = $cname
+                SET c.backup = $backup
+            """
+
+            if not isinstance(electricity_backup, list):
+                backup = 1 if random.random() < electricity_backup else 0
+            else:
+                backup = 1 if infra['c.name'] in electricity_backup else 0 
+
+            if backup == 1:
+                infra_with_backups.append(infra['c.name'])
+
+            with driver.session() as session:
+                session.write_transaction(
+                    lambda tx: tx.run(
+                        cypher_write_query,
+                        cname=infra['c.name'],
+                        backup= backup
+                    )
+                )
+
+    return infra_with_backups

erad/programs/microgrid.py

@@ -0,0 +1,45 @@
+"""
+This module will update the survive property based on whether 
+the critica infrastructure is going to be powered from microgrid or not.
+"""
+
+
+from neo4j import GraphDatabase
+
+from erad.metrics.check_microgrid import check_for_microgrid
+
+
+def apply_microgrid_to_critical_infra(
+        driver: GraphDatabase.driver,
+        factor: float= (0.5 * 0.4)
+):
+    """ Function that will update the survive property of 
+    critical infrastructure if it can get power from microgrid."""
+
+    islands_jsons = check_for_microgrid(driver, output_json_path=None)
+    infra_island = [subdict['sinks'] for _, subdict \
+                      in islands_jsons.items() if len(subdict['sources'])>0]
+    infra_microgrid = [1 if subdict['source_capacity'] >= subdict['sink_capacity']*factor  else 0 for _, subdict \
+                      in islands_jsons.items()]
+
+    infra_survives = [el for id, el in enumerate(infra_island) \
+                      if infra_microgrid[id]]
+    all_sinks = [x for el in infra_survives for x in el]
+    infra_survives = [x for el in infra_survives for x in el if 'load' not in x]
+    
+    for infra in infra_survives:
+        cypher_query = f"""
+                        MATCH (c)
+                        WHERE c.name = $cname
+                        SET c.survive = 1
+                        SET c.survival_probability = 1
+                    """
+
+        with driver.session() as session:
+                session.write_transaction(
+                    lambda tx: tx.run(
+                        cypher_query,
+                        cname=infra,
+                    )
+                )
+    return all_sinks

erad/scenarios/abstract_scenario.py

@@ -0,0 +1,103 @@
+""" Module contains the base class defination for all scenarios.
+
+Each scenario type will extend the base class to implement a given scenario
+"""
+
+
+from shapely.geometry import MultiPolygon, Polygon, LineString, Point
+from datetime import datetime
+from typing import *
+import shapely
+
+from erad.scenarios.common import AssetTypes
+
+class BaseScenario:
+    
+    """Base class for scenario defination.
+
+    Attributes:
+        geodata (MultiPolygon, Point, LineString): Region of interest
+        probability_model (dict): Dictionary mapping asset types to probability funcitons
+        timestamp (datetime): Scenario occurance time 
+        kwargs (dict): Additional parameters relevant for a particular scenario type
+        
+    """
+    
+    def __init__(self,  geodata : Union[MultiPolygon, Point, LineString] , probability_model : dict, timestamp : datetime, **kwargs) -> None:
+        """Constructor for BaseScenario class.
+
+        Args:
+            geodata (MultiPolygon, Point, LineString): Region of interest
+            probability_model (dict): Dictionary mapping asset types to probability funcitons
+            timestamp (datetime): Scenario occurance time 
+            kwargs (dict): Additional parameters relevant for a particular scenario type
+        """
+        if probability_model is None:
+            probability_model = self.fragility_curves
+        self.valitate_user_defined_fragility_curves(probability_model)
+        
+    
+        if isinstance(geodata, Polygon):
+           geodata = MultiPolygon([geodata]) 
+        
+        if isinstance(geodata, MultiPolygon):
+            print("Is multipolygon")
+            self.multipolygon = geodata
+        elif isinstance(geodata, Point):
+            print("Is point")
+            self.origin = geodata
+        elif isinstance(geodata, LineString):
+            print("Is linestring")
+            self.front = geodata
+        else:
+            print(geodata, Point)
+            raise Exception(f"Invalid data type {type(geodata)}")
+        
+        self.probability_model = probability_model
+        self.to_projection = f"epsg:{self.identify_stateplane_projection}"
+        self.timestamp = timestamp
+        return
+    
+    @property
+    def area(self) -> float:
+        """Method to calculate area of affected region."""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+    
+    @property
+    def polygon(self) -> MultiPolygon:
+        """Method to return polygon for the affected region."""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+        
+    @property
+    def boundary(self) -> LineString:
+        """Method to return boundary for the affected region."""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+        
+    @property
+    def centroid(self) -> Point:
+        """Method to return the centroid of the affected region."""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+    
+    def increment_time(self) -> dict:
+        """Method to increment simulation time for time evolviong scenarios."""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+
+    def calculate_survival_probability(self, assets : dict, timestamp : datetime) -> dict:
+        """Method to calculate survival probaility of asset types.
+
+        Args:
+            assets (dict): The dictionary of all assets and their corresponding asset types
+        """
+        raise NotImplementedError("Method needs to be defined in derived classes")
+
+    def plot(self):
+        """Method to plot survival probaility of in the region of interest"""
+        raise NotImplementedError("Method needs to be defined in derived classes")
+   
+    def asset_survial_probability(self, asset_type):
+        raise NotImplementedError("Method needs to be defined in derived classes")
+    
+    def valitate_user_defined_fragility_curves(self, distributions):
+        for asset_type in distributions:
+            assert AssetTypes.has_asset(asset_type), f"{asset_type} is not a valid asset type. Valid options are {list(AssetTypes.__members__.keys())}"
+        return

erad/scenarios/common.py

@@ -0,0 +1,93 @@
+from shapely.geometry import MultiPolygon, Point,Polygon
+from random import random,seed
+from enum import IntEnum
+import numpy as np
+
+class ScenarioTypes(IntEnum):
+    flood_m = 0
+    wind_m_per_s = 1
+    fire_m = 2
+    earthquake_pga = 3
+    
+class AssetTypes(IntEnum):
+    substation = 0
+    solar_panels = 1
+    buried_lines = 2
+    wind_turbines= 3
+    battery_storage = 4
+    transmission_poles = 5
+    distribution_poles = 6
+    transmission_overhead_lines = 7
+    distribution_overhead_lines = 8
+    #substructures
+    #conduit_burial
+
+    @classmethod
+    def has_value(cls, value):
+        return value in cls._value2member_map_
+    
+    @classmethod
+    def has_asset(cls, asset):
+        print(asset)
+        return asset in cls.__members__
+
+
+def asset_list(x1=41.255, y1=-117.33, x2=41.255, y2=-117.33, samples=100):
+
+    x = np.linspace(x1, x2, samples)
+    y = np.linspace(y1, y2, samples)
+    
+    seed(3)
+    asset_probabilities = {
+        AssetTypes.substation: 1 / 10000.0,
+        AssetTypes.solar_panels : 1/500,
+        AssetTypes.buried_lines : 1/10.0,
+        AssetTypes.wind_turbines : 1/5000,
+        AssetTypes.battery_storage :1/2000,
+        AssetTypes.transmission_poles: 1 / 10.0,
+        AssetTypes.distribution_poles : 1 / 10.0,
+        AssetTypes.transmission_overhead_lines : 1/10.0,
+        AssetTypes.distribution_overhead_lines : 1/10.0,
+    }
+    
+    heights_ft = {
+        AssetTypes.substation.name : 3,
+        AssetTypes.solar_panels.name : 10,
+        AssetTypes.buried_lines.name : -3,
+        AssetTypes.wind_turbines.name : 25,
+        AssetTypes.battery_storage.name : 4,
+        AssetTypes.transmission_poles.name : 0,
+        AssetTypes.distribution_poles.name : 0,
+        AssetTypes.transmission_overhead_lines.name : 100,
+        AssetTypes.distribution_overhead_lines.name : 30,
+    }
+    
+    assets = {
+        AssetTypes.substation.name : {},
+        AssetTypes.solar_panels.name : {},
+        AssetTypes.buried_lines.name : {},
+        AssetTypes.wind_turbines.name : {},
+        AssetTypes.battery_storage.name :{},
+        AssetTypes.transmission_poles.name : {},
+        AssetTypes.distribution_poles.name : {},
+        AssetTypes.transmission_overhead_lines.name : {},
+        AssetTypes.distribution_overhead_lines.name : {},
+    }
+    
+    for asset_type, probability in asset_probabilities.items():
+        asset_id = 0
+        for x1 in x:
+            for y1 in y:    
+                if random() < probability:
+                    assets[asset_type.name][f"{asset_type.name} {asset_id}"] = {"coordinates" : (x1, y1), "heights_ft": heights_ft[asset_type.name]}
+                    asset_id += 1
+    
+    p1 = Point(x.min(), y.min())
+    p2 = Point(x.max(), y.min())
+    p3 = Point(x.max(), y.max())
+    p4 = Point(x.min(), y.max())
+    pointList = [p1, p2, p3, p4, p1]
+    poly = Polygon(pointList)
+    mypoly = MultiPolygon([poly]) 
+    
+    return assets, mypoly