{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with the Network Topology"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import display, HTML\n",
    "display(HTML('<a target=\"_blank\" href=\"https://colab.research.google.com/github/WaterFutures/EPyT-Flow/blob/main/docs/examples/network_topology.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example demonstrates how to retrieve detailed information about the topology of a WDN and how to perform some common tasks such as finding shortest paths."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install epyt-flow --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from epyt_flow.data.networks import load_net1\n",
    "from epyt_flow.simulation import ScenarioSimulator, EpanetConstants\n",
    "from epyt_flow.topology import flowunit_to_str"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load the Net1 network by calling [load_net1()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.data.html#epyt_flow.data.networks.load_net1):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "network_config = load_net1(verbose=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create dummy scenario simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wdn = ScenarioSimulator(scenario_config=network_config) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the network topology by calling [get_topology()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.simulation.html#epyt_flow.simulation.scenario_simulator.ScenarioSimulator.get_topology):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "topo = wdn.get_topology()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "List all edges/links:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.edges)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "List all nodes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.nodes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Find the shortest path between nodes \"2\" and \"22\" by utilizing the [get_shortest_path()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.get_shortest_path) function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.get_shortest_path(\"2\", \"22\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Compute the adjacency matrix of the WDN by calling [get_adj_matrix()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.get_adj_matrix):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.get_adj_matrix().todense())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Show information associated with node \"2\" by utilizing the [get_node_info()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.get_node_info) function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.get_node_info(\"2\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Show information associated with link \"10\" by utilizing the [get_link_info()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.get_link_info) function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(topo.get_link_info(\"10\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get topology as a `geopandas.GeoDataFrame` instance by calling [to_gis()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.to_gis):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get topology as GeoDataFrame\n",
    "geo_data = topo.to_gis()\n",
    "\n",
    "# Show GeoDataFrame for nodes\n",
    "geo_data[\"nodes\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Which flow units are used in this NetworkTopology instance?\n",
    "\n",
    "We can find out by checking the property [flow_units](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.flow_units) and convert it to a human-radable format by calling [flowunit_to_str()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.flowunit_to_str):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(flowunit_to_str(topo.flow_units))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Convert units to SI METRIC -- i.e. flow units to cubic meter per hours and pressure to meter. This will results yield pipe diameter in *millimeter*, pipe length in *meter*, node elevation in *meter*, ...\n",
    "\n",
    "See [EPANET documentation](http://wateranalytics.org/EPANET/_units.html) for details.\n",
    "\n",
    "Units in a [NetworkTopology](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology) instance can be changed by calling [convert_units()](https://epyt-flow.readthedocs.io/en/stable/epyt_flow.html#epyt_flow.topology.NetworkTopology.convert_units):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_topo = topo.convert_units(flow_units=EpanetConstants.EN_CMH, pressure_units=EpanetConstants.EN_METERS)\n",
    "\n",
    "# Show information associated with node \"2\"\n",
    "print(new_topo.get_node_info(\"2\"))\n",
    "\n",
    "# Show information associated with link \"10\"\n",
    "print(new_topo.get_link_info(\"10\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Convert units back to US CUSTOMARY -- i.e., flow units should be gallons per minute and pressure in psi:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_topo = new_topo.convert_units(flow_units=EpanetConstants.EN_GPM, pressure_units=EpanetConstants.EN_PSI)\n",
    "\n",
    "print(new_topo.get_node_info(\"2\"))\n",
    "print(new_topo.get_link_info(\"10\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Do not forget to close the simulator!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "wdn.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.9.20"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}