{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Node Breaker Models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This section contains description of transmission node-breaker modeling concepts and usage of the CIMantic Graphs `NodeBreakerModel` class for accessing CIM feeder models in a centralized and distributed manner.\n",
    "\n",
    "All diagrams within this page have been auto-generated using mermaid.js and the `cimgraph.utils` module of CIMantic Graphs, which can be imported using"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cimgraph import utils\n",
    "from mermaid import Mermaid"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Transmission Network Models in CIM\n",
    "\n",
    "CIM was originally designed to support full node-breaker modeling of transmission network models and substations "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Provide sample Node Breaker Model diagram"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading a FeederModel from an XML File\n",
    "\n",
    "It is possible to use CIMantic Graphs without any database and instead directly build the graph from an XML file. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first step is to import the correct CIM profile to use and set the associated environment variable used by CIM-Graph. For an explanation of CIM profiles, see [Profiles Overview](../02_cim_profiles/2_1_profiles_overview.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ['CIMG_CIM_PROFILE'] = 'cim17v40' # import and env var must match\n",
    "\n",
    "import cimgraph.data_profile.cim17v40 as cim # import and env var must match"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, use the `XMLFile` interface to open the XML file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cimgraph.databases import XMLFile\n",
    "\n",
    "file = XMLFile(filename='../../sample_models/maple10nodebreaker.xml')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If custom extensions are used, provide a namespaces dictionary mapping the prefix to the custom namespaces:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "namespaces={'cim': 'http://iec.ch/TC57/CIM100#',\n",
    "            'gmdm': 'http://epri.com/gmdm/2025#',\n",
    "            'rdf': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',\n",
    "            'gad': 'http://gridappsd.org/CIM/extension#'}\n",
    "\n",
    "file = XMLFile(filename='../../sample_models/maple10nodebreaker.xml',\n",
    "               namespaces=namespaces)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, create a new `NodeBreakerModel` network class to load the transmission model into the graph:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cimgraph.models import NodeBreakerModel\n",
    "\n",
    "network = NodeBreakerModel(container=None, connection=file)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <div class=\"mermaid-59ac6be7-a5e2-402a-920c-33f1bb585b4f\"></div>\n",
       "        <script type=\"module\">\n",
       "            import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10.1.0/+esm'\n",
       "            const graphDefinition = 'mindmap\\n    _276809df((**Breaker**\\n        name: hv_bk_1\\n        normalOpen: False\\n        open: False\\n        retained: True\\n        ratedCurrent: 400.0\\n        breakingCapacity: 400.0))\\n        [Location]\\n            _6a85ee07(**Location**\\n                name: hv_bk_1_Loc)\\n        [EquipmentContainer]\\n            _bb020444(**VoltageLevel**\\n                name: SUB1_230.0_B1)\\n        [BaseVoltage]\\n            _91e72b6a(**BaseVoltage**\\n                name: BaseV_230.0000)\\n        [\"Terminals\"]\\n            _88c03456(**Terminal**\\n                name: hv_bk_1_T2)\\n            _ce6dd7ca(**Terminal**\\n                name: hv_bk_1_T1)\\n';\n",
       "            const element = document.querySelector('.mermaid-59ac6be7-a5e2-402a-920c-33f1bb585b4f');\n",
       "            const { svg } = await mermaid.render('graphDiv-59ac6be7-a5e2-402a-920c-33f1bb585b4f', graphDefinition);\n",
       "            element.innerHTML = svg;\n",
       "        </script>\n",
       "        "
      ],
      "text/plain": [
       "<mermaid.mermaid.Mermaid at 0x75a1915381c0>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get first breaker in graph\n",
    "breaker = network.first(cim.Breaker)\n",
    "# Display the line\n",
    "Mermaid(utils.get_mermaid(breaker))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modifying Files\n",
    "\n",
    "Objects can be created, modified, or deleted using the `.add_to_graph(object)`, `.delete(object)`,  and `.create('incremental_file.xml')` methods"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_breaker = cim.Breaker(name='new_breaker', open=False)\n",
    "network.add_to_graph(new_breaker)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "network.delete(new_breaker)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "network.modify(breaker, 'open', True, incremental_file='breaker_incremental.xml')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving to a File\n",
    "\n",
    "Use the `utils.write_xml()` and `utils.write_json_ld` methods to save modified network to file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cimgraph import utils\n",
    "\n",
    "utils.write_xml(network, '../../sample_models/maple10nodebreaker_modified.xml')\n",
    "utils.write_json_ld(network, '../../sample_models/maple10nodebreaker_modified.jsonld')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Advanced Concepts - Distributed Modeling\n",
    "\n",
    "These features are still in development and intended to provide a preview of planned capabilities. Under certain use cases, users may wish to instantiate a new typed property graph for each substation and voltage level as its own standalone network. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "network = NodeBreakerModel(container=None, connection=file, distributed = True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "for sr_area in network.distributed_areas[cim.SubGeographicalRegion].values():\n",
    "    print(\"subregion\", sr_area.container.name)\n",
    "    for sub_area in sr_area.distributed_areas[cim.Substation].values():\n",
    "        print(\"substation\", sub_area.container.name)\n",
    "\n",
    "        for vl_area in sub_area.distributed_areas[cim.VoltageLevel].values():\n",
    "            print(\"voltage level\", vl_area.container.name)\n",
    "            \n",
    "        for feeder_area in sub_area.distributed_areas[cim.Feeder].values():\n",
    "            print(\"feeder\", feeder_area.container.name, \"contains PV aggregates\")\n",
    "            feeder_area.get_all_edges(cim.PowerElectronicsConnection)\n",
    "            feeder_area.get_all_edges(cim.PhotoVoltaicUnit)\n",
    "            if cim.PowerElectronicsConnection in feeder_area.graph:\n",
    "                for pv in feeder_area.graph[cim.PowerElectronicsConnection].values():\n",
    "                    print(pv.name, float(pv.p)/1000000, \"MW\")\n",
    "            else:\n",
    "                print(\"none\")\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "cim-documentation-py3.10",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}