epyt_joss_simple_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple example\n",
    "\n",
    "The `EPyT` python class, epanet, includes properties of the input network model, static properties, public functions, and local functions that directly call the `EPANET` shared object library or the executable. The full API with detailed examples is provided in the link. In the following paragraphs, we introduce a selection of the capabilities of the tool and an illustrative smart water research example.\n",
    "\n",
    "Through `EPyT`, users can easily load EPANET network models, as demonstrated by importing the module and loading the `Net1.inp` network in a provided example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Initialize EPANET Python Toolkit (EPyT)\n",
    "\n",
    "You should always begin with this command to import the toolkit.\n",
    "\n",
    "[EPyT](https://github.com/OpenWaterAnalytics/EPyT) is available on [PyPI](https://pypi.org/project/epyt/) and can be installed via `pip install epyt`. To upgrade to the latest version if it's already installed, use `pip install --upgrade epyt`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install epyt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "from epyt import epanet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Load EPANET Input File\n",
    "G = epanet('Net1.inp')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, `G` is an epanet object which can be defined mathematically as the set comprised of the network graph topology (such as nodes and links), structural parameters (such as pipe lengths, diameters, etc.), and functions (such as hydraulic solvers, etc.). `G` can also be shared between different functions as an argument.\n",
    "\n",
    "When the object is constructed, the module reads the `EPANET` input network file and populates more than 500 object parameters. To view some of the parameters and receive assistance with respect to the methods, the user can use the following commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Lists all available functions and properties\n",
    "dir(G)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Retrieve some examples for the function\n",
    "help(G.getNodeElevations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using object `G`, the user can call all the public toolkit functions. The toolkit contains a large set of functions that allow the user to retrieve or update the network data and simulate hydraulic and quality analysis for different scenarios using the EPANET libraries. Examples of how to retrieve some common network parameter values are provided below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Retrieve Link diameters\n",
    "diameters = G.getLinkDiameter()\n",
    "print(diameters)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Retrieve Node elevations\n",
    "elevations = G.getNodeElevations()\n",
    "print(elevations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variables diameters and elevations are two arrays, corresponding to the number of links, and the number of nodes in the `Net1` network, respectively. Note that, in case the network model changes, these parameters will be updated. This is demonstrated in the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Link diameter for links 2 & 10\n",
    "diameters = G.getLinkDiameter([2, 10])\n",
    "print(diameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To modify some parameters, we can use the set commands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Update the link 10 diameter from 100 to 90\n",
    "G.setLinkDiameter(10, 90)\n",
    "# Retrieve the diameter of link 10\n",
    "n_diameter = G.getLinkDiameter(10)\n",
    "print(n_diameter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we show how to simulate the water distribution network, such as flows/pressures and water quality. Various functions have been included in the toolkit to simplify the workflows of solving and retrieving the data from the library memory. One way is to solve the hydraulics and quality equations using the `EPANET` library and store the results in data structures."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Solve hydraulics in library\n",
    "# H = G.getComputedHydraulicTimeSeries()\n",
    "\n",
    "# Solve quality dynamics in library\n",
    "# Q = G.getComputedQualityTimeSeries()\n",
    "\n",
    "# Solve all dynamics in library, create a binary file to store the computed values\n",
    "R = G.getComputedTimeSeries()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To access the different values, the user can use the dot notation, such as `R.Flow` to create an array with the flows and `R.NodeQuality` for the water quality at the nodes. It is important to note that the time intervals may be different for the hydraulic and quality time series, due to the simulation settings; the user can call `R.Time`, to retrieve the time in seconds.\n",
    "\n",
    "Executing the functions `G.plot()` or `G.plot_ts()`, a figure of the network along with its components is displayed. The nodes i.e., junctions, reservoirs, tanks, and the links, i.e., pipes, valves, and pumps, are depicted using different colors and shapes. An example is provided below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Plot link flows and quality\n",
    "hrs_time = R.Time / 3600\n",
    "link_indices = [1, 3, 5, 10]\n",
    "link_names = G.getLinkNameID(link_indices)\n",
    "G.plot_ts(X=hrs_time, Y=R.Flow[:, link_indices],\n",
    "          title=f'Flow, Link IDs: {link_names}', figure_size=[4, 3], legend_location='best',\n",
    "          xlabel='Time (hrs)', ylabel=f'Flow ({G.units.LinkFlowUnits})',\n",
    "          marker=None, labels=link_names, save_fig=True) #, filename='figures/paper_flows')\n",
    "G.plot_ts(X=hrs_time, Y=R.LinkQuality[:, link_indices],\n",
    "          title=f'Quality, Link IDs: {link_names}', legend_location='best',\n",
    "          xlabel='Time (hrs)', ylabel=f'Quality', figure_size=[4, 3],\n",
    "          marker=None, labels=link_names, save_fig=True) #, filename='figures/paper_link_quality')\n",
    "\n",
    "# Plot node pressures and quality\n",
    "node_indices = [2, 4, 6, 10]\n",
    "node_names = G.getNodeNameID(node_indices)\n",
    "G.plot_ts(X=hrs_time, Y=R.Pressure[:, node_indices], legend_location='best',\n",
    "          title=f'Pressure, Node IDs: {node_names}', figure_size=[4, 3],\n",
    "          xlabel='Time (hrs)', ylabel=f'Pressure ({G.units.NodePressureUnits})',\n",
    "          marker=None, labels=node_names, save_fig=True) #, filename='figures/paper_pressures')\n",
    "\n",
    "G.plot_ts(X=hrs_time, Y=R.NodeQuality[:, node_indices],\n",
    "          title=f'Quality, Node IDs: {node_names}', legend_location='best',\n",
    "          xlabel='Time (hrs)', ylabel=f'Quality', figure_size=[4, 3],\n",
    "          marker=None, labels=node_names, save_fig=True) #, filename='figures/paper_node_quality')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Unload library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "G.unload()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (Spyder)",
   "language": "python3",
   "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.14"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}