Merge pull request #19 from ak2ls2py/finalize1

Finalize1

.bumpversion.cfg

@@ -1,13 +1,15 @@
 [bumpversion]
-current_version = 0.1.0
+current_version = 0.2.0
 commit = True
 tag = True
 
-[bumpversion:file:setup.py]
-
-[bumpversion:file:docs/conf.py]
-
 [bumpversion:file:src/rrpam_wds/__init__.py]
 
 [bumpversion:file:src/rrpam_wds/examples/__init__.py]
 
+[bumpversion:file:src/rrpam_wds/gui/__init__.py]
+
+[bumpversion:file:setupdata.py]
+
+[bumpversion:file:docs/conf.py]
+

CHANGELOG.rst

@@ -1,13 +1,23 @@
 
 Changelog
 =========
+0.2.0 (2017-02-09)
+-----------------------------------
+
+* A major error calculating NPV fixed.
+
+* Documentation updated
+
 * First usable version
 
 * Essential features are complete
 
+* Added all essential sub-windows
+
+
 0.1.0 (2016-09-27)
 -----------------------------------------
 
 * First release on PyPI.
 
-* Developing network plot
+* Developed network plot

README.rst

@@ -81,19 +81,3 @@ To run the all tests (after installing miniconda `http://conda.pydata.org/minico
 
     ./service/test.bash
 
-Note, to combine the coverage data from all the tox environments run:
-
-.. list-table::
-    :widths: 10 90
-    :stub-columns: 1
-
-    - - Windows
-      - ::
-
-            set PYTEST_ADDOPTS=--cov-append
-            tox
-
-    - - Other
-      - ::
-
-            PYTEST_ADDOPTS=--cov-append tox

docs/about.rst

@@ -5,16 +5,17 @@ About RRPAMWDS
 RRPAMWDS is a software tool that demonstrates the concepts of Risk Based Decision Making and Whole 
 Life Cost Analysis concepts using water distribution networks as examples. 
 
-The intended use of the tool is for Asset Management Classes. 
+The intended use of the tool is for `Asset Management Classes <https://www.unesco-ihe.org/asset-management>`_. 
 
-The software was developed by Assela Pathirana
+The software was developed by `Assela Pathirana <http://assela.pathirana.net/index.php?title=Assela_Pathirana>`_
 
-Development was supported with a grant under the Global Partnership for Water and Development facility of 
+
+Development was supported with a grant under the `Global Partnership for Water and Development facility <https://www.unesco-ihe.org/global-partnership-water-and-development>`_ of 
 UNESCO-IHE and Ministry of Foreign Affairs of the Kingdom of Netherlands. 
 
 Copyright: Assela Pathirana, 2016, 2017 (All rights reserved). 
 
-This program is free software: you can redistribute it and/or modify
+    This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
@@ -25,4 +26,4 @@ This program is free software: you can redistribute it and/or modify
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    along with this program.  If not, see `http://www.gnu.org/licenses/ <http://www.gnu.org/licenses/>`_

docs/conf.py

@@ -27,7 +27,7 @@
 year = '2017'
 author = 'Assela Pathirana'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '0.1.0'
+version = release = '0.2.0'
 
 pygments_style = 'trac'
 templates_path = ['.']

docs/index.rst

@@ -4,10 +4,11 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   
+
    readme
    installation
    usage
+   tutorial
    reference/index
    contributing
    authors
@@ -20,4 +21,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/installation.rst

@@ -2,6 +2,15 @@
 Installation
 ============
 
+Install on windows
+------------------
+Download the latest self-extracting installation files from `github release page of RRPAMWDS project<https://github.com/asselapathirana/RRPam-WDS/releases>`_`. Double click on the downloaded file to install it.
+
+Install as a python package
+----------------------------
+
+If you follow this path, make sure you have installed python and other required packages first. Then, 
+
 At the command line::
 
     pip install rrpam-wds

docs/mydictionary.txt

@@ -7,3 +7,9 @@ conda
 Indices
 changelog
 tox
+RRPAM-WDS
+EPANET
+EPANET 2.0
+Shamir
+inp
+net

docs/tutorial.rst

@@ -0,0 +1,16 @@
+===================
+RRPAM-WDS Tutorial
+===================
+
+RRPAM-WDS or Risk-based renewal planning for asset management of water distribution systems, is a educational software tool that demonstrates one of the many approaches for renewal planning in the domain of infrastructure asset management. It uses water distribution networks as basis for demonstrating the renewal planning approach. However, the principles demonstrated here are applicable for any other infrastructure asset system (e.g. roads, electrical grids, drainage/sewerage networks) equally well.
+
+Tutorial pages
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial01
+   tutorial02
+   tutorial03
+   tutorial04

docs/tutorial01.rst

@@ -0,0 +1,59 @@
+===============
+Requirements
+===============
+Following information is required to do an analysis with RRPAM-WDS.
+
+1. Water distribution Network in EPANET 2.0 network format (*****.inp****)
+2. Reasonable estimations for the parameters of exponential aging formula :math:`N(t)=N_0 e^{A t}` after Shamir and Howard (1979).
+
+These requirements are explained below:
+
+
+
+Water distribution network
+---------------------------
+RRPAM-WDS works with water distribution networks created with EPANET 2.0 modeling software[2]_
+
+.. [2] EPANET 2.0 model is available for download (including comprehensive documentation) at `https://www.epa.gov/water-research/epanet <https://www.epa.gov/water-research/epanet>`_.
+
+EPANET 2.0 model uses two model file formats, namely ***\*.net*** format - which is a binary one and the text-based 'network file', *****.inp**** format. RRPAM-WDS can read the latter format. If the hydraulic network file is in ***\*.net*** format, it can be converted to a network (*****.inp**** ) file as follows:
+
+1. Open the ***\*.net*** with EPANET 2.0 desktop software.
+2. Use File > Export > Network menu item to export the network as ***\*.inp*** file.
+
+.. figure:: images/export2.PNG
+   :scale: 100 %
+   :alt: How to export ***\*.net*** file as *****.inp**** file.
+
+   How to export ***\*.net*** file as *****.inp**** file.
+
+Note: There are three example network files (in ***\*.inp*** provided with the software, these can obviously be used with RRPAM-WDS directly without the above conversion. These are available at the subdirectory ``rrpam_wds\examples``. For example on windows with default installation at ``C:\Program Files (x86)\rrpam-wds\rrpam_wds\examples``)
+
+.. WARNING:: Typical EPANET 2.0 network files has coordinates of all the junctions. However, while creating the network if coordinates are omitted for one or more junctions, that does not raise any errors in the hydraulic calculations (coordinates are not needed for the calculations). An example of this is the standard example file ***Net3.net*** provided with EPANET 2.0. In this network, the junction with ID ***177*** does **not** have **X** and **Y** coordinates! EPANET 2.0 simply does not display this junction (and its connecting links) on the network map. But the user can access the junction and related links using However, RRPAM-WDS expects to have coordinates for all the junctions in the network file. If you try to open a file with missing coordinates, RRPAM-WDS will complain and fail to open the network.
+
+.. figure:: images/no_coords.png
+   :scale: 100 %
+   :alt: EPANET 2.0 network files can have junctions with no coordinates.
+
+   EPANET 2.0 network files can have junctions with no coordinates. In this network (***Net3.net***), ID ***177*** does **not** have **X** and **Y** coordinates.
+
+
+Aging Parameters
+-----------------
+In RRPAM-WDS we use the exponential background-aging model after Shamir and Howard (1979)[1]_ which is :
+
+.. math::
+      N(t)=N_0 e^{A t}
+
+:where:
+    :math:`N(t)` - Number of failures per year per unit length (e.g. **#/km/year**)
+
+    :math:`t` - Age of the asset (pipe)
+
+    :math:`N_0` and :math:`A`  - Aging parameters
+
+There are a number of techniques to estimate values of the aging parameters (e.g. empirical fit to pipe failure history if available) These techniques are beyond the scope of this tutorial. [3]_
+
+.. [3] There are plans to create an add-on module to RRPAM-WDS that allows user to do regression analysis using failure history data. However, as this can be done with any spreadsheet software (like OpenOffice or Excel), this plan is not a priority at the moment.
+
+.. [1] Shamir U, Howard C. An Analytical Approach to Scheduling Pipe Replacement (PDF). Journal-American Water Works Association. 1979 May 1;71(5):248-58. `PDF<http://shamir.net.technion.ac.il/files/2012/04/1979-Shamir-and-Howard-Pipe-Replacement-JAWWA.pdf>`_

docs/tutorial02.rst

@@ -0,0 +1,43 @@
+===============
+Getting Started
+===============
+.. Attention::
+    Make sure that you have the required data ready before starting on this section. Refer to section :doc:`Requirements </tutorial01>`.
+
+There are a number of example EPANET 2.0 network files provided with RRPAM-WDS. They are available at :code:`rrpam_wds\examples` directory relative to your RRPAM-WDS installation. (e.g. In windows this is usually :code:`C:\Program Files (x86)\rrpam-wds\rrpam_wds\examples`) For this walk-though we use the example :code:`Adjumani_network_simplified2.inp`. This network is a hypothetical case loosely based on a actual case study from Sub-Saharan Africa.
+
+Step 1
+======
+First create a new project, which will ask you to locate the EPANET 2.0 file that you want to use in your project.
+
+.. figure:: images/new_project.PNG
+   :scale: 100 %
+   :alt: Create a new project
+
+Navigate to the location of :code:`Adjumani_network_simplified2.inp` and select that file.
+
+.. figure:: images/new_project2.PNG
+   :scale: 100 %
+   :alt: Locate :code:`Adjumani_network_simplified2.inp` file.
+
+Then you will be asked to select a location to save your project. While it is possible to save a new project in any location in your computer, it is advised to create a new directory and save your project inside that.
+
+.. figure:: images/new_project3.PNG
+   :scale: 100 %
+   :alt: Create a new directory :code:`my_project`
+
+.. figure:: images/new_project4.PNG
+      :scale: 100 %
+      :alt: Go to the directory :code:`my_project` and save your project.
+
+As shown about, for this example I created a directory :code:`my_project` on the Desktop and saved the project as :code:`project1` inside it.
+
+At this stage RRPAM-WDS will take a few seconds to perform hydraulic analysis on the network and show the following things:
+
+1. A diagram representing the hydraulic network;
+2. A list of 'links' of the network with their basic properties.
+3. A representation of the risk-matrix (We have not provided any information of the failure probabilities, so for the moment just ignore this window.)
+
+.. figure:: images/new_project5.PNG
+      :scale: 100 %
+      :alt: New project successfully created.

docs/tutorial03.rst

@@ -0,0 +1,39 @@
+===================
+RRPAM-WDS Tutorial
+===================
+
++----------+--------+-------------+-----------+
+|  Pipe ID | Length | Age (Years) | Material  |
++==========+========+=============+===========+
+| TX       | 600    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P1       | 100    | 20          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P2       | 300    | 20          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P9       | 100    | 30          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P10      | 500    | 32          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P3       | 500    | 20          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P11      | 300    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P4       | 500    | 20          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P5       | 300    | 20          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P13      | 300    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P17      | 500    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P24      | 100    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P27      | 1300   | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P28      | 100    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+| P50      | 500    | 35          | HDPE/PN10 |
++----------+--------+-------------+-----------+
+|          |        |             |           |
++----------+--------+-------------+-----------+

docs/tutorial04.rst

@@ -0,0 +1,21 @@
+Step 2
+======
+At this stage we need to input the failure rate data. We need to provide aging parameters (:math:`N_0` and :math:`A`) and the Age of each pipe (link) at the time of analysis.
+
+RRPAM-WDS facilitates input of aging parameters based on asset groups. Let's assume two groups of pipes. Following are the aging parameters estimated for each group. The last column gives the cost of replacement for a km of pipe in terms of millions of financial units.
+
++-----------------------+--------------------+---------------+---------------+
+|  Diameter Range       | :math:`N_0`        | :math:`A`     |Cost (millions)|
++=======================+====================+===============+===============+
+| :math:`d\ \leq` 80 mm | 0.120              | 0.0185        | 700           |
++-----------------------+--------------------+---------------+---------------+
+| 80 mm :math:`\gt\ d`  | 0.081              | 0.0136        | 1000          |
++-----------------------+----------------------+-------------+-+-------------+
+
+Go to the :strong:`Asset Data` window and select and select :strong:`Property Groups` tab,  Change the number of groups to 2 and enter the above values.
+
+.. figure:: images/asset_data1.PNG
+   :scale: 100 %
+   :alt: EPANET 2.0 network files can have junctions with no coordinates.
+
+Now the next step is to assign each pipe to one of these two groups. Go to the :strong:`Assign Assets` tab on the :strong:`Asset Data` (same) window. 

docs/usage.rst

@@ -2,6 +2,10 @@
 Usage
 =====
 
-To use RRPam-WDS in a project::
+If you have installed windows self-installation file (can be downloaded from `https://github.com/asselapathirana/RRPam-WDS/releases <https://github.com/asselapathirana/RRPam-WDS/releases>`_), simply double-click on the start-menu entry `RRPAMWDS`.
 
-	import rrpam_wds
+If you have installed as a python package (e.g. using pip install RRPAM-WDS), then type::
+
+     python -mrrpam_wds
+
+This should open the RRPAM-WDS desktop application. Then follow the `tutorial <tutorial.rst>`_.

setupdata.py

@@ -1,6 +1,6 @@
 __all__ = ['name', 'version', 'license', 'description', 'author', 'author_email', 'url']
 name = 'rrpam-wds'
-version = '0.1.0'
+version = '0.2.0'
 license = 'GPLV3'
 description = 'Risk-based renewal planning for asset management of water distribution systems'
 author = 'Assela Pathirana'

src/rrpam_wds/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/rrpam_wds/examples/__init__.py

@@ -1,4 +1,4 @@
 from .examples import networks
 
 __all__ = [networks]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/rrpam_wds/gui/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/rrpam_wds/gui/subdialogs.py

@@ -292,7 +292,7 @@ class ProjectPropertiesDataset(dt.DataSet):
         slider=False)
     _ex1 = dt.EndGroup("Direct cost total system down")
     _bx2 = dt.BeginGroup("Relative size in risk matrix")
-    SCALE = di.FloatItem("", default=10, min=0.0, max=+500, step=.1, slider=True)
+    SCALE = di.FloatItem("", default=0.001, min=0.0, max=+1000, step=.01)
     _ex2 = dt.EndGroup("Relative size in risk matrix")
     _bg2 = dt.BeginGroup("Discount rate (%)")
     discountrate = di.FloatItem("", default=10, min=-5, max=+50, step=0.1, slider=True)

src/rrpam_wds/project_manager.py

@@ -38,12 +38,13 @@ def do_the_job(self):
         self.pm.heres_a_curve_signal.emit(self.result)
 
     def _calculate(self):
+        """TODO: Add a test to compare this calculation with a manually done calculation"""
         d = self.project_data
         r = self.result
         r.year = np.arange(0, d.years, 1)
-        r.renewalcost = d.cost * np.exp(-r.year * d.r / 100.)
+        r.renewalcost = d.cost / (1 + d.r / 100.)**r.year
         tmp = _getProb(d.A, r.year, d.lunits, d.N0, d.length, d.age)
-        dc = tmp * np.exp(-d.r / 100. * r.year) * d.cons
+        dc = tmp / (1 + d.r / 100.)**r.year * d.cons
         r.damagecost = np.add.accumulate(dc)