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

erad/db/assets/critical_infras.py

@@ -0,0 +1,171 @@
+""" This module contains functions to update 
+survival probability and survive property
+based on disaster event. """
+
+# manage python imports
+from datetime import datetime 
+import random
+
+from neo4j import GraphDatabase
+
+from erad.db.utils import _run_read_query
+from erad.metrics.check_microgrid import node_connected_to_substation
+
+
+def _update_critical_infra_based_on_grid_access_fast(
+    critical_infras,
+    driver: GraphDatabase.driver   
+):
+    """ A faster function to update survive attribute 
+    based on whether critical infra has access to grid power."""
+    # Let's get substation 
+    cypher_query = f"""
+        MATCH (n:Substation)
+        WHERE n.survive is NULL OR n.survive<>0 
+        RETURN n.name
+    """
+    substations = _run_read_query(driver, cypher_query)
+    substations = [item["n.name"]  for item in substations]
+    
+    nodes = node_connected_to_substation(substations, driver)
+
+    # Get all critical infra and check if they are in above nodes
+    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.survive = $survive
+                SET c.survival_probability = $s_prob
+            """
+
+            with driver.session() as session:
+                session.write_transaction(
+                    lambda tx: tx.run(
+                        cypher_write_query,
+                        cname=infra['c.name'],
+                        s_prob= 1 if infra['c.name'] in nodes or int(infra['c.backup'])==1 else 0,
+                        survive=1 if infra['c.name'] in nodes or int(infra['c.backup'])==1 else 0 
+                    )
+                )
+
+
+
+def _update_critical_infra_based_on_grid_access(
+    critical_infras,
+    driver: GraphDatabase.driver 
+):
+    """ A function to update survive attribute 
+    based on whether critical infra has access to grid power."""
+
+    # Let's get substation 
+    cypher_query = f"""
+        MATCH (n:Substation)
+        WHERE n.survive is NULL OR n.survive<>0 
+        RETURN n.name
+    """
+    substations = _run_read_query(driver, cypher_query)
+    substations = [item["n.name"]  for item in substations]
+
+    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:
+            connected = []
+            for substation in substations:
+
+                _name = "{name:" + f'"{infra["c.name"]}"' + "}"
+                substation_name = "{name:" + f'"{substation}"' + "}"
+                cypher_query = f"""
+                    MATCH 
+                        (g:{cri_infra} {_name})-[:GETS_POWER_FROM]-(b:Bus),
+                        (s:Substation {substation_name}),
+                        p=shortestPath((b)-[:CONNECTED_TO*]-(s))
+                    WHERE all(r in relationships(p) WHERE r.survive is NULL OR r.survive<>0 )
+                    RETURN length(p)
+                """
+
+                if not infra['c.backup']: 
+                    path = _run_read_query(driver, cypher_query)
+                    connected.append(1 if path else 0) 
+                else:
+                    connected.append(1)
+                
+
+            cypher_write_query = f"""
+                MATCH (c:{cri_infra})
+                WHERE c.name = $cname
+                SET c.survive = $survive
+                SET c.survival_probability = $s_prob
+            """
+
+            with driver.session() as session:
+                session.write_transaction(
+                    lambda tx: tx.run(
+                        cypher_write_query,
+                        cname=infra['c.name'],
+                        s_prob= int(any(connected)),
+                        survive=int(any(connected)) 
+                    )
+                )
+
+def _update_critical_infra(
+        scenario,
+        critical_infras,
+        driver: GraphDatabase.driver,
+        timestamp: datetime 
+):
+
+    critical_infras_items = {}
+    assets = {}
+
+    for infra in critical_infras:
+        cypher_query = f"""
+                        MATCH (c:{infra})
+                        RETURN c.longitude, c.latitude, c.name
+                    """
+        critical_infras_items[infra] = _run_read_query(driver, cypher_query)
+
+    
+    for c_infra, data in critical_infras_items.items():
+        assets[c_infra] =  {
+            item["c.name"]: {
+                "coordinates": [item["c.longitude"], item["c.latitude"]]
+            } for item in data
+            if all([item["c.longitude"], item["c.latitude"]])
+        }
+
+    survival_prob = scenario.calculate_survival_probability(assets, datetime.now())
+    
+    # update the survival probability
+    for infra in critical_infras:
+        cypher_query = f"""
+                        MATCH (c:{infra})
+                        WHERE c.name = $cname
+                        SET c.survive = $survive
+                        SET c.survival_probability = $s_prob
+                    """
+
+        with driver.session() as session:
+            for cname, cdict in survival_prob[infra].items():
+                session.write_transaction(
+                    lambda tx: tx.run(
+                        cypher_query,
+                        cname=cname,
+                        s_prob=cdict["survival_probability"],
+                        survive=int(
+                            random.random() < cdict["survival_probability"]
+                        ),
+                    )
+                )

erad/db/assets/distribution_lines.py

@@ -0,0 +1,101 @@
+""" This module contains a function to get the distribution 
+line assets and update it's survival probability and survive
+attribute based on event scenario. 
+"""
+
+# Manage python imports
+from datetime import datetime
+import random
+import json
+import random
+
+random.seed(20)
+
+from neo4j import GraphDatabase
+
+from erad.db.utils import _run_read_query
+
+
+def _create_assets(lines):
+    """ Takes the list of lines and convert into
+    asset dictionary. """
+
+    return {
+            line["r.name"]: {
+                "coordinates": [line["r.latitude"], line["r.longitude"]],
+                "heights_ft": float(line["r.height_m"])*3.28084,
+                "elevation_ft": random.randint(50, 400)
+            }
+            for line in lines
+            if all([line["r.longitude"], line["r.latitude"]])
+        }
+
+def _update_distribution_lines_survival(
+    survival_probability,
+    driver: GraphDatabase.driver   
+):
+    """ Takes survival probabilty and update survival 
+    probability and survive property. """
+
+  
+
+    cypher_query = """
+                    MATCH (b1:Bus)-[r:CONNECTS_TO {name: $rname}]-(b2:Bus)
+                    SET r.survive = $survive
+                    SET r.survival_probability = $s_prob
+                """
+    with driver.session() as session:
+        for rname, rdict in survival_probability.items():
+            session.write_transaction(
+                lambda tx: tx.run(
+                    cypher_query,
+                    rname=rname,
+                    s_prob=rdict.get("survival_probability", 1),
+                    survive=int(random.random() < rdict.get("survival_probability", 1)),
+                )
+            )
+
+
+def _update_distribution_overhead_lines(scenario, driver: GraphDatabase.driver, timestamp: datetime):
+    """Get overhead lines and update the survival probability."""
+
+    # Cypher query to get overhead line segments
+    cypher_query = """ 
+                    MATCH (b1:Bus)-[r:CONNECTS_TO]-(b2:Bus)
+                    WHERE r.ampacity IS NOT NULL AND r.type = 'overhead'
+                    RETURN r.longitude, r.latitude, r.name, r.type, r.height_m
+                """
+    overhead_lines = _run_read_query(driver, cypher_query)
+
+    if overhead_lines:
+        assets = {"distribution_overhead_lines": _create_assets(overhead_lines)}
+
+        survival_prob = scenario.calculate_survival_probability(assets, timestamp)
+
+        # with open('surv.json', "w") as fp:
+        #     json.dump(survival_prob,fp)
+        _update_distribution_lines_survival(
+            survival_prob['distribution_overhead_lines'],
+            driver
+        )
+
+def _update_distribution_underground_lines(scenario, driver: GraphDatabase.driver, timestamp: datetime):
+    """Get overhead lines and update the survival probability."""
+
+    # Cypher query to get overhead line segments
+    cypher_query = """ 
+                    MATCH (b1:Bus)-[r:CONNECTS_TO]-(b2:Bus)
+                    WHERE r.ampacity IS NOT NULL AND r.type = 'underground'
+                    RETURN r.longitude, r.latitude, r.name, r.type, r.height_m
+                """
+    underground_lines = _run_read_query(driver, cypher_query)
+
+    if underground_lines:
+        assets = {"buried_lines": _create_assets(underground_lines)}
+
+        survival_prob = scenario.calculate_survival_probability(assets, timestamp)
+        _update_distribution_lines_survival(
+            survival_prob['buried_lines'],
+            driver
+        )
+

erad/db/credential_model.py

@@ -0,0 +1,20 @@
+""" Module for storing pydantic model for neo4j credential. """
+
+from pydantic import BaseModel, validator
+
+from erad.exceptions import DatabaseMissingInfo
+
+
+class Neo4jConnectionModel(BaseModel):
+    neo4j_url: str
+    neo4j_username: str
+    neo4j_password: str
+
+    @validator("neo4j_url", "neo4j_username", "neo4j_password")
+    def check_string(cls, value):
+        if not all(value):
+            raise DatabaseMissingInfo(
+                "Credential and/or connection URL missing \
+                to connect to Neo4J database!"
+            )
+        return value

erad/db/disaster_input_model.py

@@ -0,0 +1,23 @@
+""" Module for storing pydantic model for injecting scenarios. """
+
+from typing import Dict, Optional, List
+import datetime
+
+from pydantic import BaseModel, validator, confloat
+
+
+class PointEarthquake(BaseModel):
+    longitude: confloat(ge=-180, le=180)
+    latitude: confloat(ge=-90, le=90)
+    probability_model: Optional[Dict]
+    timestamp: datetime.datetime
+    magnitude: confloat(ge=0, le=10)
+    depth: confloat(ge=0)
+
+class PolygonFlooding(BaseModel):
+    polygon: List
+    probability_model: Optional[Dict]
+    timestamp: datetime.datetime
+    file_flow: str 
+    file_levels: str 
+    file_gaugues: str

erad/db/inject_earthquake.py

@@ -0,0 +1,52 @@
+""" Module for injecting scenario data into graph database. """
+
+
+from neo4j import GraphDatabase
+import shapely
+
+from erad.db import disaster_input_model
+from erad.scenarios import earthquake_scenario
+from erad.db.assets.distribution_lines import (
+    _update_distribution_overhead_lines,
+    _update_distribution_underground_lines
+)
+
+from erad.db.assets.critical_infras import (
+    _update_critical_infra_based_on_grid_access_fast
+)
+
+
+def inject_point_earthquake(
+    scenario_input: disaster_input_model.PointEarthquake,
+    driver: GraphDatabase.driver,
+    critical_infras: None
+):
+    """Function to update the survival probability of different assets
+    due to user input based earthquake scenario.
+
+    Args:
+        scenario_input (scenario_model.PointEarthquake): Should be an instance
+            of `scenario_model.PointEarthquake` data model.
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+    """
+    if not critical_infras:
+        critical_infras = []
+
+
+    scenario = earthquake_scenario.EarthquakeScenario(
+        shapely.geometry.Point(
+            scenario_input.longitude, scenario_input.latitude
+        ),
+        scenario_input.probability_model,
+        scenario_input.timestamp,
+        Magnitude=scenario_input.magnitude,
+        Depth=scenario_input.depth,
+    )
+    
+    _update_distribution_overhead_lines(scenario, driver, scenario_input.timestamp)
+    _update_distribution_underground_lines(scenario, driver, scenario_input.timestamp)
+    if len(critical_infras):
+        _update_critical_infra_based_on_grid_access_fast(critical_infras, driver)
+    
+            

erad/db/inject_flooding.py

@@ -0,0 +1,53 @@
+""" Module for injecting flooding scenario data into graph database. """
+
+
+from neo4j import GraphDatabase
+from shapely import MultiPolygon, Polygon
+
+from erad.db import disaster_input_model
+from erad.scenarios import flood_scenario
+from erad.db.assets.distribution_lines import (
+    _update_distribution_overhead_lines,
+    _update_distribution_underground_lines
+)
+
+from erad.db.assets.critical_infras import (
+    _update_critical_infra_based_on_grid_access_fast
+)
+
+
+def inject_polygon_flooding(
+    scenario_input: disaster_input_model.PolygonFlooding,
+    driver: GraphDatabase.driver,
+    critical_infras: None
+):
+    """Function to update the survival probability of different assets
+    due to user input based flooding scenario.
+
+    Args:
+        scenario_input (scenario_model.PolygonFlooding): Should be an instance
+            of `scenario_model.PolygonFlooding` data model.
+        driver (GraphDatabase.driver): Instance of `GraphDatabase.driver`
+            instance
+    """
+    if not critical_infras:
+        critical_infras = []
+
+
+    scenario = flood_scenario.FlooadScenario(
+        MultiPolygon(
+            [Polygon(el) for el in scenario_input.polygon]
+        ),
+        scenario_input.probability_model,
+        scenario_input.timestamp,
+        file_flow=scenario_input.file_flow,
+        file_levels=scenario_input.file_levels,
+        file_gaugues=scenario_input.file_gaugues
+    )
+    
+    _update_distribution_underground_lines(scenario, driver, scenario_input.timestamp)
+    _update_distribution_overhead_lines(scenario, driver, scenario_input.timestamp)
+    if len(critical_infras):
+        _update_critical_infra_based_on_grid_access_fast(critical_infras, driver)
+    
+            

erad/db/neo4j_.py

@@ -0,0 +1,162 @@
+"""Module contains class and utility functions to manage
+interactions with Neo4J database. 
+"""
+
+# standard libraries
+import os
+import logging
+from typing import Union
+
+
+# third-party libraries
+from dotenv import load_dotenv
+from neo4j import GraphDatabase, basic_auth
+
+# internal imports
+from erad.db.credential_model import Neo4jConnectionModel
+
+
+load_dotenv()
+NEO4J_URL = os.getenv("NEO4J_URL")
+NEO4J_USERNAME = os.getenv("NEO4J_USERNAME")
+NEO4J_PASSWORD = os.getenv("NEO4J_PASSWORD")
+
+logger = logging.getLogger(__name__)
+
+
+class Neo4J:
+    """Class for managing interaction with Neo4J database.
+
+    Attributes:
+        neo4j_url (str): URL for connecting to Neo4j
+        neo4j_username (str): Username for Neo4j database
+        neo4j_password (str): Password for Neo4j database
+        use_env (bool): True if above info are to be collected
+            from env file.
+        driver (GraphDatabase.driver): Neo4J driver instance
+    """
+
+    def __init__(
+        self,
+        neo4j_url: Union[str, None] = None,
+        neo4j_username: Union[str, None] = None,
+        neo4j_password: Union[str, None] = None,
+    ) -> None:
+        """Constructor for Neo4J class.
+
+        Args:
+            neo4j_url (str): URL for connecting to Neo4j
+            neo4j_username (str): Username for Neo4j database
+            neo4j_password (str): Password for Neo4j database
+        """
+
+        self.neo4j_url = NEO4J_URL if NEO4J_URL else neo4j_url
+        self.neo4j_username = (
+            NEO4J_USERNAME if NEO4J_USERNAME else neo4j_username
+        )
+        self.neo4j_password = (
+            NEO4J_PASSWORD if NEO4J_PASSWORD else neo4j_password
+        )
+
+        connection = Neo4jConnectionModel(
+            neo4j_url=self.neo4j_url,
+            neo4j_username=self.neo4j_username,
+            neo4j_password=self.neo4j_password,
+        )
+
+        self.driver = GraphDatabase.driver(
+            connection.neo4j_url,
+            auth=basic_auth(
+                connection.neo4j_username, connection.neo4j_password
+            ),
+        )
+
+        logger.debug(
+            f"Connected to {connection.neo4j_url} database successfully"
+        )
+
+    @staticmethod
+    def rename_labels(label):
+        """Method to replace the invalid character."""
+        invalid_chars = ["-", ":", "(", ")", "."]
+        for invalid_char in invalid_chars:
+            if invalid_char in label:
+                label = label.replace(invalid_char, "__")
+        return label
+
+    # def add_node(
+    #     self,
+    #     labels: Union[List, None] = None,
+    #     properties: Union[Dict, None] = None,
+    # ) -> None:
+    #     """Method to add node to the Neo4j database.
+
+    #     Args:
+    #         labels (Union[List, None]): List of labels to be used for node
+    #         properties (Union[Dict, None]): Properties to be used for the node
+    #     """
+    #     if labels is None:
+    #         labels = []
+
+    #     if properties is None:
+    #         properties = {}
+
+    #     labels = ":".join([self.rename_labels(label) for label in labels])
+    #     cypher_query = "CREATE (:" + labels + " $properties)"
+
+    #     with self.driver.session() as session:
+    #         session.write_transaction(
+    #             lambda tx: tx.run(cypher_query, properties=properties)
+    #         )
+
+    # def add_relationship(
+    #     self,
+    #     from_node_label: str,
+    #     to_node_label: str,
+    #     from_node: str,
+    #     to_node: str,
+    #     relationship_label: str,
+    #     relationship_properties: Union[Dict, None] = None,
+    # ) -> None:
+    #     """Method to create relationship in graph database.
+
+    #     Args:
+    #         from_node_label (str): Node label for from node
+    #         to_node_label (str): Node label for to node
+    #         from_node (str): From node name
+    #         to_node (str): To node name
+    #         relationship_label (str): Relationship label name
+    #         relationship_properties (Union[Dict, None]): Properties to be used
+    #             for relationship
+    #     """
+
+    #     if relationship_properties is None:
+    #         relationship_properties = {}
+
+    #     cypher_query = (
+    #         f"MATCH (a:{from_node_label}),(b:{to_node_label}) WHERE a.name = '{from_node}'"
+    #         + f" AND b.name = '{to_node}' CREATE (a)-[:"
+    #         + self.rename_labels(relationship_label)
+    #         + " $properties]->(b)"
+    #     )
+
+    #     with self.driver.session() as session:
+    #         session.write_transaction(
+    #             lambda tx: tx.run(
+    #                 cypher_query, properties=relationship_properties
+    #             )
+    #         )
+
+    # def read_query(self, cypher_query: str) -> List:
+    #     """Executes a Cypher read query."""
+
+    #     with self.driver.session() as session:
+    #         result = session.read_transaction(
+    #             lambda tx: tx.run(cypher_query).data()
+    #         )
+
+    #     return result
+
+    def close_driver(self):
+        """Method to close the driver."""
+        self.driver.close()

erad/db/utils.py

@@ -0,0 +1,14 @@
+""" This module contains utility functions 
+utilized throughout the modules and subpackages
+contained within db subpackage."""
+
+from neo4j import GraphDatabase
+
+def _run_read_query(driver:GraphDatabase.driver, cypher_query: str):
+    """ Runs a cypher query and returns result. """
+
+    with driver.session() as session:
+        result = session.read_transaction(
+            lambda tx: tx.run(cypher_query).data()
+        )
+    return result

erad/exceptions.py

@@ -0,0 +1,68 @@
+""" Module for managing exceptions raised by ERAD package."""
+
+# standard libraries
+from pathlib import Path
+
+
+class ERADBaseException(Exception):
+    """All exception should derive from this."""
+
+
+class FeatureNotImplementedError(ERADBaseException):
+    """Exception raised because specific feature requested has not been implemented."""
+
+
+class PathDoesNotExist(ERADBaseException):
+    """Exception raised bacause expected file/folder path does not exist."""
+
+    def __init__(self, path):
+        self.message = (
+            f"Expected path {path} does not exist. please check you file path!"
+        )
+        super().__init__(self.message)
+
+
+class NotAFileError(ERADBaseException):
+    """Exception raised because file is expected but folder path is provided."""
+
+    def __init__(self, path):
+        self.message = f"Expected file path {path} is not a file!"
+        super().__init__(self.message)
+
+
+class EmptyEnvironmentVariable(ERADBaseException):
+    """Exception raised because environment variable required is empty."""
+
+
+class DatabaseMissingInfo(ERADBaseException):
+    """Exception raised because information required to connect to database is missing."""
+
+
+class InvalidFileTypePassed(ERADBaseException):
+    """Exceptions raised because invalid file type is passed."""
+
+    def __init__(self, path, valid_type):
+
+        self.message = f"Invalid file type of {Path(path).suffix} is passed! Please pass valid file type of {valid_type}"
+        super().__init__(self.message)
+
+
+class SMARTDSInvalidInput(ERADBaseException):
+    """Exceptions raised because invalid input is provided for SMART DS data download."""
+
+
+class EmptyScenarioPolygon(ERADBaseException):
+    """Exceptions raised because no polygons are found."""
+
+
+class OpenDSSCommandError(ERADBaseException):
+    """Exceptions raised because opendss command execution ran into an error."""
+
+
+class MultiStatePlaneError(ERADBaseException):
+    """Exceptions raised because the corrdinates are in more than one state plane
+    coordinates."""
+
+
+class DittoException(ERADBaseException):
+    """Exceptions raised because application ran into an issus using Ditto."""