diff --git a/.gitignore b/.gitignore index 643ae47a6..01ebf9a57 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,5 @@ temp* examples/*.inp wntr/tests/*.png +documentation/_local +documentation/apidoc diff --git a/README.md b/README.md index e89bd6905..7a92e9c6c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- +


[![build](https://github.com/USEPA/WNTR/workflows/build/badge.svg)](https://github.com/USEPA/WNTR/actions/workflows/build_tests.yml) diff --git a/documentation/_static/epa_logo.png b/documentation/_static/epa_logo.png new file mode 100644 index 000000000..fcc6403f3 Binary files /dev/null and b/documentation/_static/epa_logo.png differ diff --git a/documentation/figures/logo.jpg b/documentation/_static/logo.jpg similarity index 100% rename from documentation/figures/logo.jpg rename to documentation/_static/logo.jpg diff --git a/documentation/_static/snl_logo.png b/documentation/_static/snl_logo.png new file mode 100644 index 000000000..1572badfa Binary files /dev/null and b/documentation/_static/snl_logo.png differ diff --git a/documentation/_static/wntr-favicon.svg b/documentation/_static/wntr-favicon.svg new file mode 100644 index 000000000..721c39ec9 --- /dev/null +++ b/documentation/_static/wntr-favicon.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/documentation/_templates/autosummary/base.rst b/documentation/_templates/autosummary/base.rst new file mode 100644 index 000000000..667f19687 --- /dev/null +++ b/documentation/_templates/autosummary/base.rst @@ -0,0 +1,15 @@ +{% if objtype == 'property' %} +:orphan: +{% endif %} + +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +{% if objtype == 'property' %} +property +{% endif %} + +.. auto{{ objtype }}:: {{ fullname | replace(module + ".", module + "::") }} diff --git a/documentation/_templates/autosummary/class.rst b/documentation/_templates/autosummary/class.rst new file mode 100644 index 000000000..9e9adf167 --- /dev/null +++ b/documentation/_templates/autosummary/class.rst @@ -0,0 +1,37 @@ +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + +{% block methods %} +{% if methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + + {% if methods or attributes %} + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + {% endif %} diff --git a/documentation/_templates/autosummary/exception.rst b/documentation/_templates/autosummary/exception.rst new file mode 100644 index 000000000..8d05ab977 --- /dev/null +++ b/documentation/_templates/autosummary/exception.rst @@ -0,0 +1,34 @@ +{{ objname | escape | underline}} + +.. rubric:: *module* :mod:`{{ module }}` + +.. currentmodule:: {{ module }} + +.. autoexception:: {{ objname }} + :no-inherited-members: + +{% block methods %} +{% if methods %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_methods %} + {%- if not item.startswith('_') or item in ['__call__'] %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages. + .. autosummary:: + + {% for item in all_attributes %} + {%- if not item.startswith('_') %} + {{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/documentation/_templates/autosummary/module.rst b/documentation/_templates/autosummary/module.rst new file mode 100644 index 000000000..83da37cbc --- /dev/null +++ b/documentation/_templates/autosummary/module.rst @@ -0,0 +1,73 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :exclude-members: {% for item in attributes %}{{ item }}, {% endfor %}{% for item in functions %}{{ item }}, {% endfor %}{% for item in classes %}{{ item }}, {% endfor %}{% for item in exceptions %}{{ item }}, {% endfor %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + :toctree: + :template: autosummary/base.rst + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/base.rst + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/class.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :nosignatures: + :toctree: + :template: autosummary/exception.rst + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: + :template: autosummary/module.rst +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/documentation/acknowledgements.rst b/documentation/acknowledgements.rst index 62a6b6cef..3812cd8e3 100644 --- a/documentation/acknowledgements.rst +++ b/documentation/acknowledgements.rst @@ -3,7 +3,7 @@ \clearpage Acknowledgements -====================================== +================ WNTR is developed through a collaboration between U.S. Environmental Protection Agency, Sandia National Laboratories, and the open-source community. The U.S. Environmental Protection Agency acknowledges the diff --git a/documentation/acronyms.rst b/documentation/acronyms.rst index c72b00c1f..79d05effa 100644 --- a/documentation/acronyms.rst +++ b/documentation/acronyms.rst @@ -12,24 +12,46 @@ Abbreviations ====================================== -**API**: Application programming interface +**AML**: algebraic modeling system -**CSV**: Comma-separated values +**API**: application programming interface + +**CRS**: coordinate reference system + +**CSV**: comma-separated values + +**DD**: demand-driven `(DDA now the preferred term)` + +**DDA**: demand-driven analysis **EPA**: Environmental Protection Agency -**GIS**: Geographic information system +**EPANET**: a water network modeling tool, see :cite:t:`ross00` and :cite:t:`rwts20` + +**GIS**: geographic information system **HDF**: Hierarchical Data Format -**IDE**: Integrated development environment +**IDE**: integrated development environment + +**INP file**: a text input file for EPANET + +**I/O**: input and output **JSON**: JavaScript Object Notation +**PDA**: pressure-driven analysis + +**PDD**: pressure dependent demand `(PDA now the preferred term)` + +**SCADA**: supervisory control And data acquisition + **SI**: International System of Units **SQL**: Structured Query Language **US**: United States +**UTM**: Universal Transverse Mercator + **WNTR**: Water Network Tool for Resilience diff --git a/documentation/apidoc/wntr.epanet.io.rst b/documentation/apidoc/wntr.epanet.io.rst deleted file mode 100644 index 92600f190..000000000 --- a/documentation/apidoc/wntr.epanet.io.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.epanet.io module -===================== - -.. automodule:: wntr.epanet.io - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.epanet.rst b/documentation/apidoc/wntr.epanet.rst deleted file mode 100644 index 613df4e41..000000000 --- a/documentation/apidoc/wntr.epanet.rst +++ /dev/null @@ -1,18 +0,0 @@ -wntr.epanet package -=================== - -.. automodule:: wntr.epanet - :members: - :no-undoc-members: - :show-inheritance: - - -Submodules ----------- - -.. toctree:: - - wntr.epanet.io - wntr.epanet.toolkit - wntr.epanet.util - diff --git a/documentation/apidoc/wntr.epanet.toolkit.rst b/documentation/apidoc/wntr.epanet.toolkit.rst deleted file mode 100644 index 3556c750a..000000000 --- a/documentation/apidoc/wntr.epanet.toolkit.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.epanet.toolkit module -=================================== - -.. automodule:: wntr.epanet.toolkit - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.epanet.util.rst b/documentation/apidoc/wntr.epanet.util.rst deleted file mode 100644 index 9e367ec0d..000000000 --- a/documentation/apidoc/wntr.epanet.util.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.epanet.util module -======================= - -.. automodule:: wntr.epanet.util - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.gis.geospatial.rst b/documentation/apidoc/wntr.gis.geospatial.rst deleted file mode 100644 index b1ecdef10..000000000 --- a/documentation/apidoc/wntr.gis.geospatial.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.gis.geospatial module -===================================== - -.. automodule:: wntr.gis.geospatial - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.gis.network.rst b/documentation/apidoc/wntr.gis.network.rst deleted file mode 100644 index 236c31d19..000000000 --- a/documentation/apidoc/wntr.gis.network.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.gis.network module -===================================== - -.. automodule:: wntr.gis.network - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.gis.rst b/documentation/apidoc/wntr.gis.rst deleted file mode 100644 index 69a81375c..000000000 --- a/documentation/apidoc/wntr.gis.rst +++ /dev/null @@ -1,15 +0,0 @@ -wntr.gis package -==================== - -.. automodule:: wntr.gis - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.gis.network - wntr.gis.geospatial diff --git a/documentation/apidoc/wntr.graphics.color.rst b/documentation/apidoc/wntr.graphics.color.rst deleted file mode 100644 index 62faef5e7..000000000 --- a/documentation/apidoc/wntr.graphics.color.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.graphics.color module -==================================== - -.. automodule:: wntr.graphics.color - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.graphics.curve.rst b/documentation/apidoc/wntr.graphics.curve.rst deleted file mode 100644 index 61823bf13..000000000 --- a/documentation/apidoc/wntr.graphics.curve.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.graphics.curve module -==================================== - -.. automodule:: wntr.graphics.curve - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.graphics.layer.rst b/documentation/apidoc/wntr.graphics.layer.rst deleted file mode 100644 index cb0ce7e24..000000000 --- a/documentation/apidoc/wntr.graphics.layer.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.graphics.layer module -==================================== - -.. automodule:: wntr.graphics.layer - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.graphics.network.rst b/documentation/apidoc/wntr.graphics.network.rst deleted file mode 100644 index a87b73ded..000000000 --- a/documentation/apidoc/wntr.graphics.network.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.graphics.network module -==================================== - -.. automodule:: wntr.graphics.network - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.graphics.rst b/documentation/apidoc/wntr.graphics.rst deleted file mode 100644 index 6d05f1b27..000000000 --- a/documentation/apidoc/wntr.graphics.rst +++ /dev/null @@ -1,18 +0,0 @@ -wntr.graphics package -===================== - -.. automodule:: wntr.graphics - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.graphics.network - wntr.graphics.layer - wntr.graphics.curve - wntr.graphics.color - diff --git a/documentation/apidoc/wntr.metrics.economic.rst b/documentation/apidoc/wntr.metrics.economic.rst deleted file mode 100644 index 5ca22bda1..000000000 --- a/documentation/apidoc/wntr.metrics.economic.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.metrics.economic module -============================= - -.. automodule:: wntr.metrics.economic - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.metrics.hydraulic.rst b/documentation/apidoc/wntr.metrics.hydraulic.rst deleted file mode 100644 index 83432d025..000000000 --- a/documentation/apidoc/wntr.metrics.hydraulic.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.metrics.hydraulic module -================================ - -.. automodule:: wntr.metrics.hydraulic - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.metrics.misc.rst b/documentation/apidoc/wntr.metrics.misc.rst deleted file mode 100644 index 99dba99d6..000000000 --- a/documentation/apidoc/wntr.metrics.misc.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.metrics.misc module -========================= - -.. automodule:: wntr.metrics.misc - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.metrics.rst b/documentation/apidoc/wntr.metrics.rst deleted file mode 100644 index 9278e295e..000000000 --- a/documentation/apidoc/wntr.metrics.rst +++ /dev/null @@ -1,18 +0,0 @@ -wntr.metrics package -====================== - -.. automodule:: wntr.metrics - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.metrics.topographic - wntr.metrics.hydraulic - wntr.metrics.water_security - wntr.metrics.economic - wntr.metrics.misc diff --git a/documentation/apidoc/wntr.metrics.topographic.rst b/documentation/apidoc/wntr.metrics.topographic.rst deleted file mode 100644 index 992b1ce5e..000000000 --- a/documentation/apidoc/wntr.metrics.topographic.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.metrics.topographic module -=============================== - -.. automodule:: wntr.metrics.topographic - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.metrics.water_security.rst b/documentation/apidoc/wntr.metrics.water_security.rst deleted file mode 100644 index a1d0629c3..000000000 --- a/documentation/apidoc/wntr.metrics.water_security.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.metrics.water_security module -===================================== - -.. automodule:: wntr.metrics.water_security - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.morph.link.rst b/documentation/apidoc/wntr.morph.link.rst deleted file mode 100644 index 94d3d0a9f..000000000 --- a/documentation/apidoc/wntr.morph.link.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.morph.link module -===================================== - -.. automodule:: wntr.morph.link - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.morph.node.rst b/documentation/apidoc/wntr.morph.node.rst deleted file mode 100644 index 70b826f60..000000000 --- a/documentation/apidoc/wntr.morph.node.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.morph.node module -===================================== - -.. automodule:: wntr.morph.node - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.morph.rst b/documentation/apidoc/wntr.morph.rst deleted file mode 100644 index 888d0a1ef..000000000 --- a/documentation/apidoc/wntr.morph.rst +++ /dev/null @@ -1,16 +0,0 @@ -wntr.morph package -==================== - -.. automodule:: wntr.morph - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.morph.node - wntr.morph.link - wntr.morph.skel diff --git a/documentation/apidoc/wntr.morph.skel.rst b/documentation/apidoc/wntr.morph.skel.rst deleted file mode 100644 index 2969ece7b..000000000 --- a/documentation/apidoc/wntr.morph.skel.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.morph.skel module -===================================== - -.. automodule:: wntr.morph.skel - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.base.rst b/documentation/apidoc/wntr.network.base.rst deleted file mode 100644 index cd3152561..000000000 --- a/documentation/apidoc/wntr.network.base.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.base module -===================================== - -.. automodule:: wntr.network.base - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.controls.rst b/documentation/apidoc/wntr.network.controls.rst deleted file mode 100644 index 07036c787..000000000 --- a/documentation/apidoc/wntr.network.controls.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.controls module -=================================== - -.. automodule:: wntr.network.controls - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.elements.rst b/documentation/apidoc/wntr.network.elements.rst deleted file mode 100644 index 26cef395e..000000000 --- a/documentation/apidoc/wntr.network.elements.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.elements module -===================================== - -.. automodule:: wntr.network.elements - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.io.rst b/documentation/apidoc/wntr.network.io.rst deleted file mode 100644 index 190a5e351..000000000 --- a/documentation/apidoc/wntr.network.io.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.io module -=================================== - -.. automodule:: wntr.network.io - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.layer.rst b/documentation/apidoc/wntr.network.layer.rst deleted file mode 100644 index ef1a5c171..000000000 --- a/documentation/apidoc/wntr.network.layer.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.layer module -===================================== - -.. automodule:: wntr.network.layer - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.model.rst b/documentation/apidoc/wntr.network.model.rst deleted file mode 100644 index c40d391e4..000000000 --- a/documentation/apidoc/wntr.network.model.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.network.model module -===================================== - -.. automodule:: wntr.network.model - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.options.rst b/documentation/apidoc/wntr.network.options.rst deleted file mode 100644 index 69baf0350..000000000 --- a/documentation/apidoc/wntr.network.options.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.network.options module -===================================== - -.. automodule:: wntr.network.options - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.network.rst b/documentation/apidoc/wntr.network.rst deleted file mode 100644 index 05dbe11ca..000000000 --- a/documentation/apidoc/wntr.network.rst +++ /dev/null @@ -1,21 +0,0 @@ -wntr.network package -==================== - -.. automodule:: wntr.network - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.network.base - wntr.network.controls - wntr.network.elements - wntr.network.io - wntr.network.model - wntr.network.layer - wntr.network.options - diff --git a/documentation/apidoc/wntr.rst b/documentation/apidoc/wntr.rst deleted file mode 100644 index abab02a50..000000000 --- a/documentation/apidoc/wntr.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _api_documentation: - -API documentation -=================== - -.. automodule:: wntr - :members: - :no-undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - :maxdepth: 1 - - wntr.epanet - wntr.graphics - wntr.gis - wntr.metrics - wntr.morph - wntr.network - wntr.scenario - wntr.sim - wntr.utils - diff --git a/documentation/apidoc/wntr.scenario.earthquake.rst b/documentation/apidoc/wntr.scenario.earthquake.rst deleted file mode 100644 index 3daaddef7..000000000 --- a/documentation/apidoc/wntr.scenario.earthquake.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.scenario.earthquake module -=============================== - -.. automodule:: wntr.scenario.earthquake - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.scenario.fragility_curve.rst b/documentation/apidoc/wntr.scenario.fragility_curve.rst deleted file mode 100644 index 1fcd14d21..000000000 --- a/documentation/apidoc/wntr.scenario.fragility_curve.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.scenario.fragility_curve module -===================================== - -.. automodule:: wntr.scenario.fragility_curve - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.scenario.rst b/documentation/apidoc/wntr.scenario.rst deleted file mode 100644 index 88a7aec78..000000000 --- a/documentation/apidoc/wntr.scenario.rst +++ /dev/null @@ -1,16 +0,0 @@ -wntr.scenario package -===================== - -.. automodule:: wntr.scenario - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.scenario.earthquake - wntr.scenario.fragility_curve - diff --git a/documentation/apidoc/wntr.sim.aml.rst b/documentation/apidoc/wntr.sim.aml.rst deleted file mode 100644 index ffdb96180..000000000 --- a/documentation/apidoc/wntr.sim.aml.rst +++ /dev/null @@ -1,12 +0,0 @@ -wntr.sim.aml module -============================ - -.. automodule:: wntr.sim.aml.aml - :members: - :no-undoc-members: - :show-inheritance: - -.. automodule:: wntr.sim.aml.expr - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.sim.core.rst b/documentation/apidoc/wntr.sim.core.rst deleted file mode 100644 index fa5e1eb9c..000000000 --- a/documentation/apidoc/wntr.sim.core.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.sim.core module -============================= - -.. automodule:: wntr.sim.core - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.sim.epanet.rst b/documentation/apidoc/wntr.sim.epanet.rst deleted file mode 100644 index 2a6fab645..000000000 --- a/documentation/apidoc/wntr.sim.epanet.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.sim.epanet module -====================== - -.. automodule:: wntr.sim.epanet - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.sim.hydraulics.rst b/documentation/apidoc/wntr.sim.hydraulics.rst deleted file mode 100644 index 289b92411..000000000 --- a/documentation/apidoc/wntr.sim.hydraulics.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.sim.hydraulics module -============================== - -.. automodule:: wntr.sim.hydraulics - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.sim.results.rst b/documentation/apidoc/wntr.sim.results.rst deleted file mode 100644 index 6e6c78b6f..000000000 --- a/documentation/apidoc/wntr.sim.results.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.sim.results module -============================== - -.. automodule:: wntr.sim.results - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.sim.rst b/documentation/apidoc/wntr.sim.rst deleted file mode 100644 index cc230a09d..000000000 --- a/documentation/apidoc/wntr.sim.rst +++ /dev/null @@ -1,20 +0,0 @@ -wntr.sim package -================ - -.. automodule:: wntr.sim - :members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.sim.core - wntr.sim.epanet - wntr.sim.hydraulics - wntr.sim.results - wntr.sim.solvers - wntr.sim.aml - diff --git a/documentation/apidoc/wntr.sim.solvers.rst b/documentation/apidoc/wntr.sim.solvers.rst deleted file mode 100644 index 4bd3ac9b2..000000000 --- a/documentation/apidoc/wntr.sim.solvers.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.sim.solvers module -============================ - -.. automodule:: wntr.sim.solvers - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.utils.logger.rst b/documentation/apidoc/wntr.utils.logger.rst deleted file mode 100644 index a778dc33d..000000000 --- a/documentation/apidoc/wntr.utils.logger.rst +++ /dev/null @@ -1,7 +0,0 @@ -wntr.utils.logger module -======================== - -.. automodule:: wntr.utils.logger - :members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.utils.ordered_set.rst b/documentation/apidoc/wntr.utils.ordered_set.rst deleted file mode 100644 index 45610dd78..000000000 --- a/documentation/apidoc/wntr.utils.ordered_set.rst +++ /dev/null @@ -1,8 +0,0 @@ -wntr.utils.ordered_set module -=================================== - -.. automodule:: wntr.utils.ordered_set - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: diff --git a/documentation/apidoc/wntr.utils.rst b/documentation/apidoc/wntr.utils.rst deleted file mode 100644 index f613c8e99..000000000 --- a/documentation/apidoc/wntr.utils.rst +++ /dev/null @@ -1,17 +0,0 @@ -wntr.utils package -================== - -.. automodule:: wntr.utils - :members: - :inherited-members: - :no-undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - wntr.utils.logger - wntr.utils.ordered_set - diff --git a/documentation/citations.bib b/documentation/citations.bib new file mode 100644 index 000000000..6e5b3eef6 --- /dev/null +++ b/documentation/citations.bib @@ -0,0 +1,410 @@ +@article{abdelmottaleb2019, + author = "Abdel-Mottaleb, N. and Ghasemi Saghand, P. and Charkhgard, H. and Zhang, Q.", + title = "An Exact Multiobjective Optimization Approach for Evaluating Water Distribution Infrastructure Criticality and Geospatial Interdependence", + journal = "Water Resources Research", + volume = "55", + number = "7", + pages = "5255--5276", + keywords = "interdependency, critical infrastructure, water distribution resilience, criticality analysis, transportation networks, decision making", + doi = "10.1029/2018WR024063", + year = "2019" +} + +@inproceedings{antonowicz2019, + author = "Antonowicz, Ariel and Bałut, Alicja and Urbaniak, Andrzej and Zakrzewski, Przemysław", + booktitle = "2019 20th International Carpathian Control Conference (ICCC)", + title = "Algorithm for Early Warning System for Contamination in Water Network", + year = "2019", + pages = "1--5", + doi = "10.1109/CarpathianCC.2019.8765966" +} + +@article{antonowicz2022, + author = "Antonowicz, Ariel and Urbaniak, Andrzej", + volume = "70", + number = "4", + journal = "Bulletin of the Polish Academy of Sciences: Technical Sciences", + pages = "e141594", + howpublished = "online", + year = "2022", + title = "Optimization of the process of restoring the continuity of the WDS based on the matrix and genetic algorithm approach", + doi = "10.24425/bpasts.2022.141594", + keywords = "WNTR, aggregation of failures, water distribution system, EPANET Solver, graph searching algorithm, genetic algorithm, optimization, post-disaster events" +} + +@mastersthesis{bjerke2019, + author = "Bjerke, Martin", + school = "Norwegian University of Science and Technology (NTNU)", + title = "Leak Detection in Water Distribution Networks using Gated Recurrent Neural Networks", + year = "2019", + url = "http://hdl.handle.net/11250/2625834" +} + +@mastersthesis{bunn2018, + author = "Bunn, Brendan B.", + school = "Naval Postgraduate School", + title = "An operational model of interdependent water and power distribution infrastructure systems", + year = "2018", + address = "Monterey, CA", + url = "https://apps.dtic.mil/sti/citations/AD1065269" +} + +@article{fan2021, + author = "Fan, Xudong and Zhang, Xijin and Yu, Xiong (Bill)", + title = "Machine learning model and strategy for fast and accurate detection of leaks in water supply network", + journal = "Journal of Infrastructure Preservation and Resilience", + year = "2021", + month = "Apr", + day = "15", + volume = "2", + number = "1", + pages = "10", + issn = "2662--2521", + doi = "10.1186/s43065-021-00021-6" +} + +@inproceedings{han2018, + author = "Han, Qing and Eguchi, Ronald and Mehrotra, Sharad and Venkatasubramanian, Nalini", + booktitle = "2018 IEEE 37th Symposium on Reliable Distributed Systems (SRDS)", + title = "Enabling State Estimation for Fault Identification in Water Distribution Systems Under Large Disasters", + year = "2018", + pages = "161-170", + doi = "10.1109/SRDS.2018.00027" +} + +@inproceedings{han2019, + author = "Han, Qing and Mehrotra, Sharad and Venkatasubramanian, Nalini", + title = "AquaEIS: Middleware Support for Event Identification in Community Water Infrastructures", + year = "2019", + isbn = "9781450370097", + publisher = "Association for Computing Machinery", + address = "New York, NY, USA", + doi = "10.1145/3361525.3361554", + booktitle = "Proceedings of the 20th International Middleware Conference (Middleware '19)", + pages = "293--305", + numpages = "13", + keywords = "Human Engagement, In-situ Sensing, Event Processing, Complex System, Event Identification", + location = "Davis, CA, USA", +} + +@article{huang2022, + author = "Huang, Honglan and Burton, Henry V.", + title = "Dynamic seismic damage assessment of distributed infrastructure systems using graph neural networks and semi-supervised machine learning", + journal = "Advances in Engineering Software", + volume = "168", + pages = "103113", + year = "2022", + issn = "0965--9978", + doi = "10.1016/j.advengsoft.2022.103113", + keywords = "Graph neural network, Seismic risk assessment, Distributed infrastructure systems, Water distribution system, Damage assessment" +} + +@article{iannacone2022, + author = "Iannacone, Leandro and Sharma, Neetesh and Tabandeh, Armin and Gardoni, Paolo", + title = "Modeling Time-varying Reliability and Resilience of Deteriorating Infrastructure", + journal = "Reliability Engineering \& System Safety", + volume = "217", + pages = "108074", + year = "2022", + issn = "0951-8320", + doi = "10.1016/j.ress.2021.108074", + keywords = "Resilience, Recovery, Deterioration, Water Infrastructure, Physics-based models" +} + +@article{kammoun2022, + author = "Kammoun, Maryam and Kammoun, Amina and Abid, Mohamed", + title = "Experiments based comparative evaluations of machine learning techniques for leak detection in water distribution systems", + journal = "Water Supply", + volume = "22", + number = "1", + pages = "628--642", + year = "2022", + publisher = "IWA Publishing", + doi = "10.2166/ws.2021.248" +} + +@article{liu2022, + author = "Liu, Jun and Kang, Yinyin", + year = "2022", + month = "11", + pages = "100--109", + title = "Segment-based resilience response and intervention evaluation of water distribution systems", + volume = "71", + number = "1", + journal = "AQUA -- Water Infrastructure, Ecosystems and Society", + doi = "10.2166/aqua.2021.133" +} + +@article{liu2020, + author = "Liu, Yang and Barrows, Clayton and Macknick, Jordan and Mauter, Meagan", + title = "Optimization Framework to Assess the Demand Response Capacity of a Water Distribution System", + journal = "Journal of Water Resources Planning and Management", + volume = "146", + number = "8", + pages = "04020063", + year = "2020", + doi = "10.1061/(ASCE)WR.1943-5452.0001258" +} + +@article{logan2021, + author = "Logan, Kevin T. and Leštáková, Michaela and Thiessen, Nadja and Engels, Jens Ivo and Pelz, Peter F.", + title = "Water Distribution in a Socio-Technical System: Resilience Assessment for Critical Events Causing Demand Relocation", + journal = "Water", + volume = "13", + year = "2021", + number = "15", + pages = "2062", + issn = "2073-4441", + doi = "10.3390/w13152062" +} + +@article{lorenz2020, + author = "Lorenz, Imke-Sophie and Pelz, Peter F.", + title = "Optimal Resilience Enhancement of Water Distribution Systems", + journal = "Water", + volume = "12", + year = "2020", + number = "9", + pages = "2602", + issn = "2073-4441", + doi = "10.3390/w12092602" +} + +@article{marlim2022, + author = "Marlim, Malvin S. and Kang, Doosun", + title = "Contaminant Flushing in Water Distribution Networks Incorporating Customer Faucet Control", + journal = "Sustainability", + volume = "14", + year = "2022", + number = "4", + pages = "2249", + issn = "2071-1050", + doi = "10.3390/su14042249" +} + +@inproceedings{mazumder2019, + author = "Mazumder, Ram Krishna and Salman, Abdullahi and Li, Yue and Yu, Xiong", + year = "2019", + pages = "", + booktitle = "13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, May 26-30, 2019, Seoul, South Korea", + title = "A Decision-making Framework for Water Distribution Systems using Fuzzy Inference and Centrality Analysis" +} + +@article{mazumder2022, + author = "Ram K. Mazumder and Abdullahi M. Salman and Li, Yue", + title = "Post-disaster sequential recovery planning for water distribution systems using topological and hydraulic metrics", + journal = "Structure and Infrastructure Engineering", + volume = "18", + number = "5", + pages = "728--743", + year = "2022", + publisher = "Taylor \\& Francis", + doi = "10.1080/15732479.2020.1864415" +} + +@inproceedings{mulrillo2021, + author = "Murillo, Andres and Taormina, Riccardo and Tippenhauer, Nils and Galelli, Stefano", + title = "Co-Simulating Physical Processes and Network Data for High-Fidelity Cyber-Security Experiments", + year = "2021", + isbn = "9781450390026", + publisher = "Association for Computing Machinery", + address = "New York, NY", + doi = "10.1145/3442144.3442147", + booktitle = "Sixth Annual Industrial Control System Security (ICSS) Workshop", + pages = "13--20", + numpages = "8", + location = "Austin, TX, USA", +} + +@article{nikolopoulos2020, + author = "Nikolopoulos, Dionysios and Moraitis, Georgios and Bouziotas, Dimitrios and Lykou, Archontia and Karavokiros, George and Makropoulos, Christos", + title = "Cyber-Physical Stress-Testing Platform for Water Distribution Networks", + journal = "Journal of Environmental Engineering", + volume = "146", + number = "7", + pages = "04020061", + year = "2020", + doi = "10.1061/(ASCE)EE.1943-7870.0001722" +} + +@article{nikolopoulos2021, + author = "Nikolopoulos, Dionysios and Ostfeld, Avi and Salomons, Elad and Makropoulos, Christos", + title = "Resilience Assessment of Water Quality Sensor Designs under Cyber-Physical Attacks", + journal = "Water", + volume = "13", + year = "2021", + number = "5", + pages = "647", + issn = "2073-4441", + doi = "10.3390/w13050647" +} + +@article{nikolopoulos2022a, + author = "Nikolopoulos, Dionysios and Kossieris, Panagiotis and Tsoukalas, Ioannis and Makropoulos, Christos", + title = "Stress-Testing Framework for Urban Water Systems: A Source to Tap Approach for Stochastic Resilience Assessment", + journal = "Water", + volume = "14", + year = "2022", + number = "2", + pages = "154", + issn = "2073-4441", + doi = "10.3390/w14020154" +} + +@article{nikolopoulos2020b, + author = "Nikolopoulos, Dionysios and Makropoulos, Christos", + title = "Stress-testing water distribution networks for cyber-physical attacks on water quality", + journal = "Urban Water Journal", + volume = "19", + number = "3", + pages = "256--270", + year = "2022", + publisher = "Taylor \\& Francis", + doi = "10.1080/1573062X.2021.1995446" +} + +@article{nyahora2020, + author = "Nyahora, Passwell Pepukai and Babel, Mukand Singh and Ferras, David and Emen, Andres", + title = "Multi-objective optimization for improving equity and reliability in intermittent water supply systems", + journal = "Water Supply", + volume = "20", + number = "5", + pages = "1592--1603", + year = "2020", + issn = "1606-9749", + doi = "10.2166/ws.2020.066" +} + +@article{pagani2021, + author = "Pagani, Alessio and Wei, Zhuangkun and Silva, Ricardo and Guo, Weisi", + title = "Neural Network Approximation of Graph Fourier Transform for Sparse Sampling of Networked Dynamics", + year = "2021", + issue_date = "February 2022", + publisher = "Association for Computing Machinery", + address = "New York, NY, USA", + volume = "22", + number = "1", + issn = "1533-5399", + doi = "10.1145/3461838", + journal = "ACM Trans. Internet Technol.", + articleno = "21", + numpages = "18", + keywords = "neural networks, graph fourier transform, Sampling theory", + eprint = "2002.05508" +} + +@article{rahimigolkhandan2022, + author = "Rahimi-Golkhandan, Armin and Aslani, Babak and Mohebbi, Shima", + title = "Predictive resilience of interdependent water and transportation infrastructures: A sociotechnical approach", + journal = "Socio-Economic Planning Sciences", + volume = "80", + pages = "101166", + year = "2022", + issn = "0038-0121", + doi = "10.1016/j.seps.2021.101166", + keywords = "Infrastructure systems, Interdependency, Social vulnerability, Predictive analytics, Natural disasters, Cascading random failure, Community detection" +} + +@article{randeniya2022, + author = "Randeniya, Aruna and Radhakrishnan, Mohanasundar and Sirisena, T. A. J. G. and Masih, Ilyas and Pathirana, Assela", + title = "Equity--performance trade-off in water rationing regimes with domestic storage", + journal = "Water Supply", + volume = "22", + number = "5", + pages = "4781-4797", + year = "2022", + issn = "1606-9749", + doi = "10.2166/ws.2022.188" +} + +@inproceedings{sharma2019, + author = "Sharma, Neetesh and Tabandeh, Armin and Gardoni, Paolo", + title = "Recovery optimization of interdependent infrastructure: A multi-scale approach", + year = "2019", + language = "English (US)", + booktitle = "13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, Seoul, South Korea" +} + +@article{sharma2020, + author = "Sharma, Neetesh and Tabandeh, Armin and Gardoni, Paolo", + title = "Regional resilience analysis: A multiscale approach to optimize the resilience of interdependent infrastructure", + journal = "Computer-Aided Civil and Infrastructure Engineering", + volume = "35", + number = "12", + pages = "1315-1330", + doi = "10.1111/mice.12606", + year = "2020" +} + +@phdthesis{tabandeh2018, + author = "Tabandeh, Seyedarmin", + school = "University of Illinois at Urbana-Champaign", + title = "Societal risk and resilience analysis: A multi-scale approach to model the dynamics of infrastructure-social systems", + year = "2018" +} + +@article{tabandeh2022, + author = "Tabandeh, Armin and Sharma, Neetesh and Gardoni, Paolo", + title = "Uncertainty propagation in risk and resilience analysis of hierarchical systems", + journal = "Reliability Engineering \& System Safety", + volume = "219", + pages = "108208", + year = "2022", + issn = "0951-8320", + doi = "10.1016/j.ress.2021.108208", + keywords = "Sensitivity analysis, Uncertainty quantification, Hierarchical systems, Risk and resilience analysis, Infrastructure" +} + +@article{tomar2020, + author = "Tomar, Agam and Burton, Henry V. and Mosleh, Ali and Lee, Ji Yun", + title = "Hindcasting the Functional Loss and Restoration of the Napa Water System Following the 2014 Earthquake Using Discrete-Event Simulation", + journal = "Journal of Infrastructure Systems", + volume = "26", + number = "4", + pages = "04020035", + year = "2020", + doi = "10.1061/(ASCE)IS.1943-555X.0000574" +} + +@inproceedings{vrachimis2018a, + author = "Vrachimis, S.G. and Kyriakou, M.S. and Demetrios G. Eliades, and Marios M.Polycarpou", + booktitle = "1st International WDSA/CCWI Joint Conference Proceedings", + volume = "1", + number = "146", + title = "LeakDB: A benchmark dataset for leakage diagnosis in water distribution networks", + year = "2018", + url = "https://ojs.library.queensu.ca/index.php/wdsa-ccw/article/view/12315", +} + +@inproceedings{vrachimis2018b, + author = "Vrachimis, Stelios G. and Eliades, Demetrios G. and Polycarpou, Marios M.", + booktitle = "2018 IEEE Conference on Control Technology and Applications (CCTA)", + title = "Leak Detection in Water Distribution Systems Using Hydraulic Interval State Estimation", + year = "2018", + volume = "", + number = "", + pages = "565--570", + doi = "10.1109/CCTA.2018.8511516" +} + +@phdthesis{wille2019, + author = "Wille, Dominik", + school = "Naval Postgraduate School", + address = "Monterey, CA", + title = "Simulation-optimization for operational resilience of interdependent water-power systems in the {US} {Virgin} {Islands}", + year = "2019", + type = "Doctoral dissertation", + url = "https://hdl.handle.net/10945/64098", +} + +@article{xing2020, + author = "Xing, Lu and Sela, Lina", + title = "Transient simulations in water distribution networks: {TSNet} python package", + journal = "Advances in Engineering Software", + volume = "149", + pages = "102884", + year = "2020", + issn = "0965-9978", + doi = "10.1016/j.advengsoft.2020.102884", + keywords = "Transient simulation, Python, Open source software, Water distribution networks" +} diff --git a/documentation/conf.py b/documentation/conf.py index 38819bec8..0fc5bf7c2 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -40,15 +40,51 @@ 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', -] + 'sphinx_design', + 'sphinxcontrib.bibtex' +] + +add_function_parentheses = True +add_module_names = False +python_display_short_literal_types = True + +toc_object_entries = True +toc_object_entries_show_parents = 'hide' + +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = False +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = True +napoleon_preprocess_types = False +napoleon_use_ivar = True +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_use_keyword = False +napoleon_custom_sections = ['Read-only Simulation Attributes', 'Class Methods', 'Enum Members'] + +# viewcode_import = False + +autodoc_default_options = { + 'undoc-members': True, + 'private-members': False, + 'special-members': False, + 'inherited-members': True, + 'show-inheritance': True, + 'member-order': 'groupwise', +} + +autodoc_class_signature = 'separated' +autodoc_typehints = 'description' +autodoc_typehints_format = 'short' +autodoc_typehints_description_target = 'documented' +autodoc_type_aliases = {'DataFrame': 'pandas DataFrame',} + +autoclass_content = 'class' -napoleon_use_rtype = False -viewcode_import = True -numpydoc_show_class_members = True -numpydoc_show_inherited_class_members = False -numpydoc_class_members_toctree = False -autodoc_member_order = 'bysource' -autoclass_content = 'both' numfig=True numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s'} @@ -56,7 +92,8 @@ templates_path = ['_templates'] import glob -autosummary_generate = glob.glob("apidoc/*.rst") +autosummary_generate = ["wntr-api.rst",] + glob.glob("apidoc/*.rst") +autosummary_generate_overwrite = True # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -74,6 +111,10 @@ copyright = u'2023 National Technology & Engineering Solutions of Sandia, LLC (NTESS)' author = u'WNTR Developers' +bibtex_bibfiles = ['references.bib', 'citations.bib'] +bibtex_default_style = 'plain' +bibtex_reference_style = 'label' + # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. @@ -90,6 +131,13 @@ # Usually you set "language" from the command line for these cases. language = 'en' +intersphinx_mapping = { + "python": ("https://docs.python.org/3", (None, "_local/python-objects.inv")), + "matplotlib": ("https://matplotlib.org/stable/", (None, "_local/matplotlib-objects.inv")), + "numpy": ("https://numpy.org/doc/stable/", (None, "_local/numpy-objects.inv")), + "pandas": ("https://pandas.pydata.org/docs/", (None, "_local/pandas-objects.inv")), +} + # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' @@ -134,26 +182,53 @@ # a list of builtin themes. #html_theme = 'sphinx_rtd_theme' -def setup(app): - app.add_css_file( "wntr.css") on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - html_style = 'wntr.css' + html_theme = 'pydata_sphinx_theme' + else: + def setup(app): + app.add_css_file( "wntr.css") html_theme = 'default' # html_context = { # 'css_files': ['_static/wntr.css'], # } - + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} - +html_theme_options = { + "icon_links": [ + { + # Label for this link + "name": "GitHub", + # URL where the link will redirect + "url": "https://github.com/USEPA/WNTR", # required + # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local") + "icon": "fa-brands fa-github", + # The type of image to be used (see below for details) + "type": "fontawesome", + }, + { + "name": "Sandia National Laboratories", + "url": "https://sandia.gov", # required + "icon": "_static/snl_logo.png", + "type": "local", + }, + { + "name": "U.S. Environmental Protection Agency", + "url": "https://epa.gov", # required + "icon": "_static/epa_logo.png", + "type": "local", + }, + ], + "use_edit_page_button": False, + "primary_sidebar_end": ["indices.html"], + "show_toc_level": 2, + # "secondary_sidebar_items": ["page-toc"], #["page-toc", "edit-this-page", "sourcelink"], + "navbar_end": [ "theme-switcher.html", "navbar-icon-links.html",], +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -166,12 +241,12 @@ def setup(app): # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = 'figures/wntr.png' +html_logo = '_static/logo.jpg' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +html_favicon = "_static/wntr-favicon.svg" # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths @@ -186,7 +261,7 @@ def setup(app): # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +html_extra_path = ['_data'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/documentation/controls.rst b/documentation/controls.rst index d943a172b..239c3e98b 100644 --- a/documentation/controls.rst +++ b/documentation/controls.rst @@ -6,7 +6,7 @@ Water network controls ====================================== One of the key features of water network models is the ability to control pipes, pumps, and valves using simple and complex conditions. -EPANET uses "controls" and "rules" to define conditions [Ross00]_. WNTR replicates EPANET functionality, and includes additional options, as described below. The EPANET user manual provides more information on simple controls and rule-based controls (controls and rules, respectively in WNTR) [Ross00]_. +EPANET uses "controls" and "rules" to define conditions :cite:p:`ross00`. WNTR replicates EPANET functionality, and includes additional options, as described below. The EPANET user manual provides more information on simple controls and rule-based controls (controls and rules, respectively in WNTR) :cite:p:`ross00`. **Controls** are defined using an "IF condition; THEN action" format. Controls use a single action (i.e., closing/opening a link or changing the setting) based on a single condition (i.e., time based or tank level based). diff --git a/documentation/criticality.rst b/documentation/criticality.rst index ccc996c40..e37fad9b9 100644 --- a/documentation/criticality.rst +++ b/documentation/criticality.rst @@ -13,7 +13,7 @@ In threat agnostic analysis, the cause of the disruption is not modeled directly Rather, a series of simulations can be used to perform N-k contingency analysis, where N is the number of elements and k elements fail. -In water distribution systems analysis, N-1 contingency analysis is commonly called criticality analysis [WaWC06]_. +In water distribution systems analysis, N-1 contingency analysis is commonly called criticality analysis :cite:p:`wawc06`. WNTR is commonly used to run criticality analysis, where a series of simulations are run to determine the impact of individual failures on the system. This framework can be expanded to include analysis where two or more elements fail at one time or in succession. diff --git a/documentation/disaster_models.rst b/documentation/disaster_models.rst index 8e86fdaa5..4d57e3128 100644 --- a/documentation/disaster_models.rst +++ b/documentation/disaster_models.rst @@ -30,14 +30,14 @@ and change demands for fire conditions, as described in the sections below. The :class:`~wntr.scenario.earthquake.Earthquake` class includes methods to compute peak ground acceleration, peak ground velocity, and repair rate based on the earthquake location and magnitude. -Alternatively, external earthquake models or databases (e.g., ShakeMap [WWQP06]_) can be used to compute earthquake properties and +Alternatively, external earthquake models or databases (e.g., ShakeMap :cite:p:`wwqp06`) can be used to compute earthquake properties and those properties can be loaded into Python for analysis in WNTR. When simulating the effects of an earthquake, fragility curves are commonly used to define the probability that a component is damaged with respect to peak ground acceleration, peak ground velocity, or repair rate. -The American Lifelines Alliance report [ALA01]_ includes seismic fragility curves +The American Lifelines Alliance report :cite:p:`ala01` includes seismic fragility curves for water system components. See :ref:`fragility_curves` for more information. @@ -131,7 +131,7 @@ Power outage ------------- Power outages can be small and brief, or they can also span over several days and affect whole regions as seen in the 2003 Northeast Blackout. -While the Northeast Blackout was an extreme case, a 2012 Lawrence Berkeley National Laboratory study [ELLT12]_ +While the Northeast Blackout was an extreme case, a 2012 Lawrence Berkeley National Laboratory study :cite:p:`ellt12` showed the frequency and duration of power outages are increasing domestically by a rate of two percent annually. In water distribution systems, a power outage can cause pump stations to shut down and result in @@ -163,7 +163,7 @@ Fires WNTR can be used to simulate damage caused to system components due to fire and/or to simulate water usage due to fighting fires. To fight fires, additional water is drawn from the system. Fire codes vary by state. Minimum required fire flow and duration are generally based on the building's area and purpose. While small residential fires might require 1500 gallons/minute for 2 hours, large commercial -spaces might require 8000 gallons/minute for 4 hours [ICC12]_. This additional demand can +spaces might require 8000 gallons/minute for 4 hours :cite:p:`icc12`. This additional demand can have a large impact on water pressure in the system. WNTR can be used to simulate firefighting conditions in the system. diff --git a/documentation/environment.yml b/documentation/environment.yml index 5214169d3..f86e79869 100644 --- a/documentation/environment.yml +++ b/documentation/environment.yml @@ -9,3 +9,6 @@ dependencies: - sphinx - numpydoc - docutils<0.17 + - sphinx_design + - pydata_sphinx_theme + - sphinxcontrib-bibtex diff --git a/documentation/fragility.rst b/documentation/fragility.rst index 693f89a91..81255ec2c 100644 --- a/documentation/fragility.rst +++ b/documentation/fragility.rst @@ -11,7 +11,7 @@ of exceeding a given damage state as a function of environmental change. Fragility curves are closely related to survival curves, which are used to define the probability of component failure due to age. For example, to estimate earthquake damage, fragility curves are defined as a function of peak ground acceleration, peak ground velocity, or repair rate. -The American Lifelines Alliance report [ALA01]_ +The American Lifelines Alliance report :cite:p:`ala01` includes seismic fragility curves for water network components. Fragility curves can also be defined as a function of flood stage, wind speed, and temperature for other diff --git a/documentation/framework.rst b/documentation/framework.rst index d74d080fb..0221fc78b 100644 --- a/documentation/framework.rst +++ b/documentation/framework.rst @@ -82,7 +82,7 @@ These classes are listed in :numref:`table-sim-subpackage`. ================================================= ============================================================================================================================================================================================================================================================================= Class Description ================================================= ============================================================================================================================================================================================================================================================================= - :class:`~wntr.sim.epanet.EpanetSimulator` The EpanetSimulator can run both the EPANET 2.00.12 Programmer's Toolkit [Ross00]_ and EPANET 2.2.0 Programmer's Toolkit [RWTS20]_ to run hydraulic and water quality simulations. + :class:`~wntr.sim.epanet.EpanetSimulator` The EpanetSimulator can run both the EPANET 2.00.12 Programmer's Toolkit :cite:p:`ross00` and EPANET 2.2.0 Programmer's Toolkit :cite:p:`rwts20` to run hydraulic and water quality simulations. EPANET 2.2.0 (which is used by default) includes both demand-driven and pressure dependent analysis, while EPANET 2.00.12 includes only demand-driven analysis. When using the EpanetSimulator, the water network model is written to an EPANET INP file which is used to run an EPANET simulation. This allows the user to run EPANET simulations, while taking advantage of additional analysis options in WNTR. diff --git a/documentation/gis.rst b/documentation/gis.rst index dd5cfe884..7592c5615 100644 --- a/documentation/gis.rst +++ b/documentation/gis.rst @@ -46,8 +46,8 @@ Open source GIS platforms include QGIS and GRASS GIS. The following section describes capabilities in WTNR that use GeoPandas GeoDataFrames. .. note:: - Functions that use GeoDataFrames require the Python package **geopandas** [JVFM21]_ - and **rtree** [rtree]_. Both are optional dependencies of WNTR. + Functions that use GeoDataFrames require the Python package **geopandas** :cite:p:`jvfm21` + and **rtree** :cite:p:`rtree`. Both are optional dependencies of WNTR. Note that **shapely** is installed with geopandas. The following examples use a water network generated from Net1.inp. diff --git a/documentation/graphics.rst b/documentation/graphics.rst index c6f0dad30..256d59861 100644 --- a/documentation/graphics.rst +++ b/documentation/graphics.rst @@ -137,7 +137,7 @@ As with basic network graphics, a wide range of plotting options can be supplied However, link attributes currently cannot be displayed on the graphic. .. note:: - This function requires the Python package **plotly** [SPHC16]_, which is an optional dependency of WNTR. + This function requires the Python package **plotly** :cite:p:`sphc16`, which is an optional dependency of WNTR. The following example plots the network along with node population (:numref:`fig-plotly`). @@ -164,10 +164,10 @@ See :ref:`modify_node_coords` for more information on converting node coordinate As with basic network graphics, a wide range of plotting options can be supplied. .. note:: - This function requires the Python package **folium** [Folium]_, which is an optional dependency of WNTR. + This function requires the Python package **folium** :cite:p:`folium`, which is an optional dependency of WNTR. The following example using EPANET Example Network 3 (Net3) converts node coordinates to longitude/latitude and plots the network along -with pipe length over the city of Albuquerque (for demonstration purposes only) (:numref:`fig-leaflet`). The longitude and latitude for two locations are needed to plot the network. For the EPANET Example Network 3, these locations are the reservoir 'Lake' and node '219'. This example requires the Python package **utm** [Bieni19]_ to convert the node coordinates. +with pipe length over the city of Albuquerque (for demonstration purposes only) (:numref:`fig-leaflet`). The longitude and latitude for two locations are needed to plot the network. For the EPANET Example Network 3, these locations are the reservoir 'Lake' and node '219'. This example requires the Python package **utm** :cite:p:`bieni19` to convert the node coordinates. .. doctest:: @@ -246,7 +246,7 @@ Interactive time series graphics are useful when visualizing large datasets. Basic time series graphics can be converted to interactive time series graphics using the ``plotly.express`` module. .. note:: - This functionality requires the Python package **plotly** [SPHC16]_, which is an optional dependency of WNTR. + This functionality requires the Python package **plotly** :cite:p:`sphc16`, which is an optional dependency of WNTR. The following example uses simulation results from above, and converts the graphic to an interactive graphic (:numref:`fig-interactive-timeseries`). diff --git a/documentation/hydraulics.rst b/documentation/hydraulics.rst index 0c755bda5..56243a2ad 100644 --- a/documentation/hydraulics.rst +++ b/documentation/hydraulics.rst @@ -12,7 +12,7 @@ See :ref:`software_framework` for more information on features and limitations o EpanetSimulator ----------------- -The EpanetSimulator can be used to run EPANET 2.00.12 Programmer's Toolkit [Ross00]_ or EPANET 2.2.0 Programmer's Toolkit [RWTS20]_. +The EpanetSimulator can be used to run EPANET 2.00.12 Programmer's Toolkit :cite:p:`ross00` or EPANET 2.2.0 Programmer's Toolkit :cite:p:`rwts20`. EPANET 2.2.0 is used by default and runs demand-driven and pressure dependent hydraulic analysis. EPANET 2.00.12 runs demand-driven hydraulic analysis only. Both versions can also run water quality simulations, as described in :ref:`water_quality_simulation`. @@ -111,7 +111,7 @@ More information on water network options can be found in :ref:`options`. Mass balance at nodes ------------------------- -Both simulators use the mass balance equations from EPANET [Ross00]_: +Both simulators use the mass balance equations from EPANET :cite:p:`ross00`: .. math:: @@ -127,7 +127,7 @@ If water is flowing out of node :math:`n` and into pipe :math:`p`, then Headloss in pipes ------------------------- -Both simulators use conservation of energy formulas from EPANET [Ross00]_. +Both simulators use conservation of energy formulas from EPANET :cite:p:`ross00`. While the EpanetSimulator can use the Hazen-Williams and Chezy-Manning pipe head loss formulas, the WNTRSimulator uses only the Hazen-Williams head loss formula, shown below. @@ -225,7 +225,7 @@ The mass balance and headloss equations described above are solved by simultaneously determining demand along with the network pressures and flow rates. Both simulators can run hydraulics using a pressure dependent demand simulation -according to the following pressure-demand relationship [WaSM88]_: +according to the following pressure-demand relationship :cite:p:`wasm88`: .. math:: @@ -308,7 +308,7 @@ Users interested in using the EpanetSimulator to model leaks can still do so by emitter coefficients. When using the WNTRSimulator, leaks are modeled with a general form of the equation proposed by Crowl and Louvar -[CrLo02]_ where the mass flow rate of fluid through the hole is expressed as: +:cite:p:`crlo02` where the mass flow rate of fluid through the hole is expressed as: .. math:: @@ -328,9 +328,9 @@ where :math:`g` is the acceleration of gravity (m/s²), and :math:`\rho` is the density of the fluid (kg/m³). -The default discharge coefficient is 0.75 (assuming turbulent flow) [Lamb01]_, but +The default discharge coefficient is 0.75 (assuming turbulent flow) :cite:p:`lamb01`, but the user can specify other values if needed. -The value of :math:`\alpha` is set to 0.5 (assuming large leaks out of steel pipes) [Lamb01]_ and currently cannot be changed by the user. +The value of :math:`\alpha` is set to 0.5 (assuming large leaks out of steel pipes) :cite:p:`lamb01` and currently cannot be changed by the user. Leaks can be added to junctions and tanks. A pipe break is modeled using a leak area large enough to drain the pipe. diff --git a/documentation/index.rst b/documentation/index.rst index 5ef2fdd51..b7ba52ee4 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -1,45 +1,28 @@ -.. figure:: figures/logo.jpg +.. figure:: _static/logo.jpg :scale: 10 % :alt: Logo +======================================== +Water Network Tool for Resilience (WNTR) +======================================== + The Water Network Tool for Resilience (WNTR) is an EPANET compatible Python package designed to simulate and analyze resilience of water distribution networks. +The official WNTR software repository is in the U.S. EPA's GitHub repository +(https://github.com/USEPA/WNTR); releases are also made available via PyPI and conda-forge +(see :ref:`installation`). + .. toctree:: :maxdepth: 1 + :hidden: - overview - installation - framework - units - getting_started - waternetworkmodel - model_io - controls - networkxgraph - layers - options - hydraulics - waterquality - resultsobject - disaster_models - criticality - resilience - fragility - morph - graphics - gis - advancedsim - license - whatsnew - developers + userguide + wntr-api users - API documentation - acronyms - reference - + Citing WNTR ------------------ +=========== To cite WNTR, use one of the following references: * Klise, K.A., Hart, D.B., Bynum, M., Hogge, J., Haxton, T., Murray, R., Burkhardt, J. (2020). Water Network Tool for Resilience (WNTR) User Manual: Version 0.2.3. U.S. EPA Office of Research and Development, Washington, DC, EPA/600/R-20/185, 82p. @@ -48,8 +31,9 @@ To cite WNTR, use one of the following references: * Klise, K.A., Bynum, M., Moriarty, D., Murray, R. (2017). A software framework for assessing the resilience of drinking water systems to disasters with an example earthquake case study, Environmental Modelling and Software, 95, 420-431, doi: 10.1016/j.envsoft.2017.06.022 + US EPA Disclaimer ---------------------- +================= The U.S. Environmental Protection Agency through its Office of Research and Development funded and collaborated in the research described here under an Interagency Agreement with the Department of Energy's Sandia National Laboratories. @@ -58,17 +42,9 @@ the contents necessarily reflect the views of the Agency. Mention of trade names EPA approval, endorsement, or recommendation. Sandia Funding Statement --------------------------------- +======================== Sandia National Laboratories is a multimission laboratory managed and operated by National Technology and Engineering Solutions of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the U.S. Department of Energy's National Nuclear Security Administration under contract DE-NA-0003525. -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - diff --git a/documentation/index_latex.rst b/documentation/index_latex.rst index 6101da9a4..a54756660 100644 --- a/documentation/index_latex.rst +++ b/documentation/index_latex.rst @@ -1,3 +1,6 @@ +:orphan: + + WNTR documentation ================================== diff --git a/documentation/installation.rst b/documentation/installation.rst index da39dd135..bad11de5a 100644 --- a/documentation/installation.rst +++ b/documentation/installation.rst @@ -2,6 +2,8 @@ \clearpage +.. _installation: + Installation ====================================== .. include:: @@ -237,15 +239,15 @@ Requirements Requirements for WNTR include 64-bit Python (tested on versions 3.7, 3.8, 3.9, and 3.10) along with several Python packages. Users should have experience using Python (https://www.python.org/), including the installation of additional Python packages. The following Python packages are required: -* NumPy [VaCV11]_: used to support large, multi-dimensional arrays and matrices, +* NumPy :cite:p:`vacv11`: used to support large, multi-dimensional arrays and matrices, http://www.numpy.org/ -* SciPy [VaCV11]_: used to support efficient routines for numerical integration, +* SciPy :cite:p:`vacv11`: used to support efficient routines for numerical integration, http://www.scipy.org/ -* NetworkX [HaSS08]_: used to create and analyze complex networks, +* NetworkX :cite:p:`hass08`: used to create and analyze complex networks, https://networkx.github.io/ -* pandas [Mcki13]_: used to analyze and store time series data, +* pandas :cite:p:`mcki13`: used to analyze and store time series data, http://pandas.pydata.org/ -* Matplotlib [Hunt07]_: used to produce graphics, +* Matplotlib :cite:p:`hunt07`: used to produce graphics, http://matplotlib.org/ These packages are included in the Anaconda Python distribution. @@ -257,17 +259,17 @@ Optional dependencies The following Python packages are optional: -* plotly [SPHC16]_: used to produce interactive scalable graphics, +* plotly :cite:p:`sphc16`: used to produce interactive scalable graphics, https://plot.ly/ -* folium [Folium]_: used to produce Leaflet maps, +* folium :cite:p:`folium`: used to produce Leaflet maps, http://python-visualization.github.io/folium/ -* utm [Bieni19]_: used to translate node coordinates to utm and lat/long, +* utm :cite:p:`bieni19`: used to translate node coordinates to utm and lat/long, https://pypi.org/project/utm/ -* geopandas [JVFM21]_: used to work with geospatial data, +* geopandas :cite:p:`jvfm21`: used to work with geospatial data, https://geopandas.org/ -* rtree [rtree]_: used for overlay operations in geopandas, +* rtree :cite:p:`rtree`: used for overlay operations in geopandas, https://rtree.readthedocs.io/ -* openpyxl [GaCl18]_: used to read/write to Microsoft® Excel® spreadsheets, +* openpyxl :cite:p:`gacl18`: used to read/write to Microsoft® Excel® spreadsheets, https://openpyxl.readthedocs.io All of these packages **except geopandas** are included in the Anaconda Python distribution. diff --git a/documentation/layers.rst b/documentation/layers.rst index 4c6457682..ac9a59292 100644 --- a/documentation/layers.rst +++ b/documentation/layers.rst @@ -89,7 +89,7 @@ The valve layer can be included in water network graphics (:numref:`fig-random-v Valve layer using random placement. The **strategic** placement specifies the number of pipes (n) from each node that do NOT contain a valve. -In this case, n is generally 0, 1, or 2 (i.e., N, N-1, or N-2 valve placement) [WaWC06]_ [LWFZ17]_. +In this case, n is generally 0, 1, or 2 (i.e., N, N-1, or N-2 valve placement) :cite:p:`wawc06` :cite:p:`lwfz17`. For example, if three pipes connect to a node and n = 2, then two of those pipes will not contain a valve and one pipe will contain a valve. The following example generates a strategic N-2 valve placement. The valve layer can be included in water network graphics (:numref:`fig-strategic-valve-layer`). diff --git a/documentation/morph.rst b/documentation/morph.rst index 88b503b43..9400d3700 100644 --- a/documentation/morph.rst +++ b/documentation/morph.rst @@ -13,7 +13,7 @@ splitting or breaking pipes. Network skeletonization ---------------------------- The goal of network skeletonization is to reduce the size of a water network model with minimal impact on system behavior. -Network skeletonization in WNTR follows the procedure outlined in [WCSG03]_. +Network skeletonization in WNTR follows the procedure outlined in :cite:p:`wcsg03`. The skeletonization process retains all tanks, reservoirs, valves, and pumps, along with all junctions and pipes that are associated with controls. Junction demands and demand patterns are retained in the skeletonized model, as described below. Merged pipes are assigned equivalent properties for diameter, length, and roughness to approximate the updated system behavior. @@ -241,7 +241,7 @@ WNTR includes several options to modify node coordinates, denoted as :math:`(x, the nodes could be in the upper right and lower left). .. note:: - Functions that convert coordinates to UTM and longitude/latitude require the Python package **utm** [Bieni19]_, which is an optional dependency of WNTR. + Functions that convert coordinates to UTM and longitude/latitude require the Python package **utm** :cite:p:`bieni19`, which is an optional dependency of WNTR. The following example returns a copy of the water network model with node coordinates scaled by 100 m. diff --git a/documentation/overview.rst b/documentation/overview.rst index 87bfb9561..ac945db58 100644 --- a/documentation/overview.rst +++ b/documentation/overview.rst @@ -24,13 +24,13 @@ is a national priority. The National Infrastructure Advisory Council defined infrastructure resilience as “the ability to reduce the magnitude and/or duration of disruptive events. The effectiveness of a resilient infrastructure or enterprise depends upon its ability to anticipate, absorb, adapt to, and/or -rapidly recover from a potentially disruptive event” [NIAC09]_. +rapidly recover from a potentially disruptive event” :cite:p:`niac09`. Being able to predict how drinking water systems will perform during disruptive incidents and understanding how to best absorb, recover from, and more successfully adapt to such incidents can help enhance resilience. Simulation and analysis tools can help water utilities to explore the capacity of their systems to handle disruptive -incidents and guide the planning necessary to make systems more resilient over time [USEPA14]_. +incidents and guide the planning necessary to make systems more resilient over time :cite:p:`usepa14`. The Water Network Tool for Resilience (WNTR, pronounced *winter*) is a Python package designed to simulate and analyze resilience of water distribution networks. @@ -44,7 +44,7 @@ constituents within distribution systems. Users are encouraged to be familiar wi EPANET and/or should have background knowledge in hydraulics and pressurized pipe network modeling before using WNTR. EPANET has a graphical user interface that might be a useful tool to facilitate the visualization of the network and the associated analysis results. Information on EPANET can be found at https://www.epa.gov/water-research/epanet. -**WNTR is compatible with EPANET 2.00.12** [Ross00]_ **and EPANET 2.2** [RWTS20]_. In addition, users should have +**WNTR is compatible with EPANET 2.00.12** :cite:p:`ross00` **and EPANET 2.2** :cite:p:`rwts20`. In addition, users should have experience using Python, including the installation of additional Python packages. General information on Python can be found at https://www.python.org/. @@ -63,7 +63,7 @@ generated by WNTR. WNTR includes capabilities to: -* **Generate water network models** from scratch or from existing EPANET-formatted water network model input (EPANET INP) files [Ross00]_ [RWTS20]_. See EPANET documentation on `INP file format `_ for more details. +* **Generate water network models** from scratch or from existing EPANET-formatted water network model input (EPANET INP) files :cite:p:`ross00` :cite:p:`rwts20`. See EPANET documentation on `INP file format `_ for more details. * **Modify network structure** by adding/removing components or changing component characteristics @@ -97,7 +97,7 @@ WNTR was developed to greatly extend these capabilities. WNTR provides a flexible platform for modeling a wide range of disruptive incidents and repair strategies, and includes an extensible hydraulic simulator. Furthermore, WNTR is compatible with widely used scientific computing packages for Python, -including NetworkX [HaSS08]_, pandas [Mcki13]_, NumPy [VaCV11]_, SciPy [VaCV11]_, and Matplotlib [Hunt07]_. +including NetworkX :cite:p:`hass08`, pandas :cite:p:`mcki13`, NumPy :cite:p:`vacv11`, SciPy :cite:p:`vacv11`, and Matplotlib :cite:p:`hunt07`. These packages allow the user to build custom analysis directly in Python, and gain access to tools that analyze the structure of complex water distribution networks, analyze time-series data from simulation results, diff --git a/documentation/reference.rst b/documentation/reference.rst index 15f12a23d..d365df535 100644 --- a/documentation/reference.rst +++ b/documentation/reference.rst @@ -2,87 +2,123 @@ \clearpage -References -==================== - .. only:: html - Due to limitations with cross referenced citations in reStructuredText (e.g., commas and spaces are not supported), - citations are cross referenced using a 6 digit notation [*]_. + References + ========== + + +.. raw:: latex + + \begingroup + \def\section#1#2{} + \def\chapter#1#2{} + \begin{thebibliography}{1234} + +.. + [ALA01] American Lifelines Alliance. (2001). Seismic Fragility Formulations for Water Systems, Part 1 and 2. Report for the American Lifelines Alliance, ASCE (Ed.) Reston, VA: American Society of Civil Engineers. April 2001. + +.. + [AwGB90] Awumah, K., Goulter, I., and Bhatt, S.K. (1990). Assessment of reliability in water distribution networks using entropy based measures. Stochastic Hydrology and Hydraulics, 4(4), 309-320. + +.. + [BaRR13] Barker, K., Ramirez-Marquez, J.E., and Rocco, C.M. (2013). Resilience-based network component importance measures. Reliability Engineering and System Safety, 117, 89-97. + +.. + [Bieni19] Bieniek, T., van Andel, B., and Bø, T.I. (2019). Bidirectional UTM-WGS84 converter for python, Retrieved on February 5, 2019 from https://github.com/Turbo87/utm. -.. [ALA01] American Lifelines Alliance. (2001). Seismic Fragility Formulations for Water Systems, Part 1 and 2. Report for the American Lifelines Alliance, ASCE (Ed.) Reston, VA: American Society of Civil Engineers. April 2001. +.. + [CrLo02] Crowl, D.A., and Louvar, J.F. (2011). Chemical Process Safety: Fundamentals with Applications, 3 edition. Upper Saddle River, NJ: Prentice Hall, 720p. -.. [AwGB90] Awumah, K., Goulter, I., and Bhatt, S.K. (1990). Assessment of reliability in water distribution networks using entropy based measures. Stochastic Hydrology and Hydraulics, 4(4), 309-320. +.. + [ELLT12] Eto, J.H., LaCommare, K.H., Larsen, P.H., Todd, A., and Fisher, E. (2012). An Examination of Temporal Trends in Electricity Reliability Based on Reports from U.S. Electric Utilities. Lawrence Berkeley National Laboratory Report Number LBNL-5268E. Berkeley, CA: Ernest Orlando Lawrence Berkeley National Laboratory, 68p. -.. [BaRR13] Barker, K., Ramirez-Marquez, J.E., and Rocco, C.M. (2013). Resilience-based network component importance measures. Reliability Engineering and System Safety, 117, 89-97. +.. + [JVFM21] Jordahl, K., Van den Bossche, J., Fleischmann, M, McBride, J. and others (2021) geopandas, 10.5281/zenodo.5573592. -.. [Bieni19] Bieniek, T., van Andel, B., and Bø, T.I. (2019). Bidirectional UTM-WGS84 converter for python, Retrieved on February 5, 2019 from https://github.com/Turbo87/utm. +.. + [Folium] python-visualization/folium. (n.d.). Retrieved on February 5, 2019 from https://github.com/python-visualization/folium. -.. [CrLo02] Crowl, D.A., and Louvar, J.F. (2011). Chemical Process Safety: Fundamentals with Applications, 3 edition. Upper Saddle River, NJ: Prentice Hall, 720p. +.. + [GaCl18] Gazoni, E. and Clark, C. (2018) openpyxl - A Python library to read/write Excel 2010 xlsx/xlsm files, Retrieved on May 4, 2018 from https://openpyxl.readthedocs.io. -.. [ELLT12] Eto, J.H., LaCommare, K.H., Larsen, P.H., Todd, A., and Fisher, E. (2012). An Examination of Temporal Trends in Electricity Reliability Based on Reports from U.S. Electric Utilities. Lawrence Berkeley National Laboratory Report Number LBNL-5268E. Berkeley, CA: Ernest Orlando Lawrence Berkeley National Laboratory, 68p. +.. + [HaSS08] Hagberg, A.A., Schult, D.A., and Swart, P.J. (2008). Exploring network structure, dynamics, and function using NetworkX. In Proceedings of the 7th Python in Science Conference (SciPy2008), August 19-24, Pasadena, CA, USA. -.. [JVFM21] Jordahl, K., Van den Bossche, J., Fleischmann, M, McBride, J. and others (2021) geopandas, 10.5281/zenodo.5573592. +.. + [Hunt07] Hunter, J.D. (2007). Matplotlib: A 2D graphics environment. Computing in Science and Engineering, 9(3), 90-95. -.. [Folium] python-visualization/folium. (n.d.). Retrieved on February 5, 2019 from https://github.com/python-visualization/folium. +.. + [ICC12] International Code Council. (2011). 2012 International Fire Code, Appendix B - Fire-Flow Requirements for Buildings. Country Club Hills, IL: International Code Council, ISBN: 978-1-60983-046-5. -.. [GaCl18] Gazoni, E. and Clark, C. (2018) openpyxl - A Python library to read/write Excel 2010 xlsx/xlsm files, Retrieved on May 4, 2018 from https://openpyxl.readthedocs.io. +.. + [JaSr08] Jayaram, N. and Srinivasan, K. (2008). Performance-based optimal design and rehabilitation of water distribution networks using life cycle costing. Water resources research, 44(1). -.. [HaSS08] Hagberg, A.A., Schult, D.A., and Swart, P.J. (2008). Exploring network structure, dynamics, and function using NetworkX. In Proceedings of the 7th Python in Science Conference (SciPy2008), August 19-24, Pasadena, CA, USA. +.. + [JCMG11] Joyner, D., Certik, O., Meurer, A., and Granger, B.E. (2012). Open source computer algebra systems, SymPy. ACM Communications in Computer Algebra, 45(4), 225-234. -.. [Hunt07] Hunter, J.D. (2007). Matplotlib: A 2D graphics environment. Computing in Science and Engineering, 9(3), 90-95. +.. + [Lamb01] Lambert, A. (2001). What do we know about pressure-leakage relationships in distribution systems. Proceedings of the IWA Specialised Conference ‘System Approach to Leakage Control and Water Distribution Systems Management’, Brno, Czech Republic, 2001, May 16-18, 89-96. -.. [ICC12] International Code Council. (2011). 2012 International Fire Code, Appendix B - Fire-Flow Requirements for Buildings. Country Club Hills, IL: International Code Council, ISBN: 978-1-60983-046-5. +.. + [LWFZ17] Liu, H., Walski, T., Fu, G., Zhang, C. (2017). Failure Impact Analysis of Isolation Valves in a Water Distribution Network. Journal of Water Resources Planning and Management 143(7): 04017019. -.. [JaSr08] Jayaram, N. and Srinivasan, K. (2008). Performance-based optimal design and rehabilitation of water distribution networks using life cycle costing. Water resources research, 44(1). +.. + [Mcki13] McKinney, W. (2013). Python for Data Analysis: Data Wrangling with Pandas, NumPy, and IPython. Sebastopal, CA: O'Reilly Media, 1 edition, 466p. -.. [JCMG11] Joyner, D., Certik, O., Meurer, A., and Granger, B.E. (2012). Open source computer algebra systems, SymPy. ACM Communications in Computer Algebra, 45(4), 225-234. +.. + [NIAC09] National Infrastructure Advisory Council (NIAC). (2009). Critical Infrastructure Resilience, Final Report and Recommendations, U.S. Department of Homeland Security, Washington, D.C., Accessed September 20, 2014. http://www.dhs.gov/xlibrary/assets/niac/niac_critical_infrastructure_resilience.pdf. -.. [Lamb01] Lambert, A. (2001). What do we know about pressure-leakage relationships in distribution systems. Proceedings of the IWA Specialised Conference ‘System Approach to Leakage Control and Water Distribution Systems Management’, Brno, Czech Republic, 2001, May 16-18, 89-96. +.. + [OsKS02] Ostfeld, A., Kogan, D., and Shamir, U. (2002). Reliability simulation of water distribution systems - single and multiquality. Urban Water, 4(1), 53-61. -.. [LWFZ17] Liu, H., Walski, T., Fu, G., Zhang, C. (2017). Failure Impact Analysis of Isolation Valves in a Water Distribution Network. Journal of Water Resources Planning and Management 143(7): 04017019. +.. + [Ross00] Rossman, L.A. (2000). EPANET 2 Users Manual. Cincinnati, OH: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA/600/R--00/057, 200p. -.. [Mcki13] McKinney, W. (2013). Python for Data Analysis: Data Wrangling with Pandas, NumPy, and IPython. Sebastopal, CA: O'Reilly Media, 1 edition, 466p. +.. + [rtree] Toblerity/rtree. (n.d.). Retrieved on March 17, 2022 from https://github.com/Toblerity/rtree. -.. [NIAC09] National Infrastructure Advisory Council (NIAC). (2009). Critical Infrastructure Resilience, Final Report and Recommendations, U.S. Department of Homeland Security, Washington, D.C., Accessed September 20, 2014. http://www.dhs.gov/xlibrary/assets/niac/niac_critical_infrastructure_resilience.pdf. +.. + [RWTS20] Rossman, L., Woo, H., Tryby M., Shang, F., Janke, R., and Haxton, T. (2020) EPANET 2.2 User Manual. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/133. -.. [OsKS02] Ostfeld, A., Kogan, D., and Shamir, U. (2002). Reliability simulation of water distribution systems - single and multiquality. Urban Water, 4(1), 53-61. +.. + [SOKZ12] Salomons, E., Ostfeld, A., Kapelan, Z., Zecchin, A., Marchi, A., and Simpson, A. (2012). The battle of the water networks II - Problem description. Water Distribution Systems Analysis Conference 2012, September 24-27, Adelaide, South Australia, Australia. Retrieved on May 23, 2017 from https://emps.exeter.ac.uk/media/universityofexeter/emps/research/cws/downloads/WDSA2012-BWNII-ProblemDescription.pdf. -.. [Ross00] Rossman, L.A. (2000). EPANET 2 Users Manual. Cincinnati, OH: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA/600/R--00/057, 200p. +.. + [SPHC16] Sievert, C., Parmer, C., Hocking, T., Chamberlain, S., Ram, K., Corvellec, M., and Despouy, P. (2016). plotly: Create interactive web graphics via Plotly’s JavaScript graphing library [Software]. -.. [rtree] Toblerity/rtree. (n.d.). Retrieved on March 17, 2022 from https://github.com/Toblerity/rtree. +.. + [Todi00] Todini, E. (2000). Looped water distribution networks design using a resilience index based heuristic approach. Urban Water, 2(2), 115-122. -.. [RWTS20] Rossman, L., Woo, H., Tryby M., Shang, F., Janke, R., and Haxton, T. (2020) EPANET 2.2 User Manual. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/133. +.. + [USEPA14] United States Environmental Protection Agency. (2014). Systems Measures of Water Distribution System Resilience. Washington DC: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA 600/R--14/383, 58p. -.. [SOKZ12] Salomons, E., Ostfeld, A., Kapelan, Z., Zecchin, A., Marchi, A., and Simpson, A. (2012). The battle of the water networks II - Problem description. Water Distribution Systems Analysis Conference 2012, September 24-27, Adelaide, South Australia, Australia. Retrieved on May 23, 2017 from https://emps.exeter.ac.uk/media/universityofexeter/emps/research/cws/downloads/WDSA2012-BWNII-ProblemDescription.pdf. +.. + [USEPA15] United States Environmental Protection Agency. (2015). Water Security Toolkit User Manual. Washington DC: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA/600/R-14/338, 187p. -.. [SPHC16] Sievert, C., Parmer, C., Hocking, T., Chamberlain, S., Ram, K., Corvellec, M., and Despouy, P. (2016). plotly: Create interactive web graphics via Plotly’s JavaScript graphing library [Software]. +.. + [VaCV11] van der Walt, S., Colbert, S.C., and Varoquaux, G. (2011). The NumPy array: A structure for efficient numerical computation. Computing in Science and Engineering, 13, 22-30. -.. [Todi00] Todini, E. (2000). Looped water distribution networks design using a resilience index based heuristic approach. Urban Water, 2(2), 115-122. +.. + [WaSM88] Wagner, J.M., Shamir, U., and Marks, D.H. (1988). Water distribution reliability: Simulation methods. Journal of Water Resources Planning and Management, 114(3), 276-294. -.. [USEPA14] United States Environmental Protection Agency. (2014). Systems Measures of Water Distribution System Resilience. Washington DC: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA 600/R--14/383, 58p. +.. + [WaWC06] Walski, T., Weiler, J. Culver, T. (2006). Using Criticality Analysis to Identify Impact of Valve Location. Water Distribution Systems Analysis Symposium. Cincinnati, OH, American Society of Civil Engineers: 1-9. -.. [USEPA15] United States Environmental Protection Agency. (2015). Water Security Toolkit User Manual. Washington DC: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA/600/R-14/338, 187p. +.. + [WWQP06] Wald, D.J., Worden, B.C., Quitoriano, V., and Pankow, K.L. (2006). ShakeMap manual: Technical manual, user's guide, and software guide. United States Geologic Survey, Retrieved on April 25, 2017 from http://pubs.usgs.gov/tm/2005/12A01/. -.. [VaCV11] van der Walt, S., Colbert, S.C., and Varoquaux, G. (2011). The NumPy array: A structure for efficient numerical computation. Computing in Science and Engineering, 13, 22-30. +.. + [WCSG03] Walski, T.M., Chase, D.V., Savic, D.A., Grayman, W., Beckwith, S. (2003). Advanced Water Distribution Modeling and Management. HAESTAD Press, Waterbury, CT, 800. -.. [WaSM88] Wagner, J.M., Shamir, U., and Marks, D.H. (1988). Water distribution reliability: Simulation methods. Journal of Water Resources Planning and Management, 114(3), 276-294. +.. raw:: html -.. [WaWC06] Walski, T., Weiler, J. Culver, T. (2006). Using Criticality Analysis to Identify Impact of Valve Location. Water Distribution Systems Analysis Symposium. Cincinnati, OH, American Society of Civil Engineers: 1-9. +
-.. [WWQP06] Wald, D.J., Worden, B.C., Quitoriano, V., and Pankow, K.L. (2006). ShakeMap manual: Technical manual, user's guide, and software guide. United States Geologic Survey, Retrieved on April 25, 2017 from http://pubs.usgs.gov/tm/2005/12A01/. +.. bibliography:: -.. [WCSG03] Walski, T.M., Chase, D.V., Savic, D.A., Grayman, W., Beckwith, S. (2003). Advanced Water Distribution Modeling and Management. HAESTAD Press, Waterbury, CT, 693p. -.. [*] Cross reference labels begins with 4 letters: +.. raw:: latex - * If the citation has one author, the first 4 letters of name are used - * If the citation has two authors, the first 2 letters of author 1 and first 2 letters of author 2 are used - * If the citation has three authors, the first 2 letters of author 1, first letter of author 2, and first letter of author 3 are used - * If the citation has four authors, the first letter of each author is used - * If the citation has more than four authors, the first letter of first four authors is used - * Exceptions are made for American Lifelines Alliance (ALA) and United States Environmental Protection Agency (USEPA) - - The next two digits are the year (century ignored). - If the 6 digits match another citation, a lower case letter (a, b, ...) is added. - Cross reference notation will be updated to a standard format when better options come available. + \end{thebibliography} + \endgroup diff --git a/documentation/references.bib b/documentation/references.bib new file mode 100644 index 000000000..40f09982c --- /dev/null +++ b/documentation/references.bib @@ -0,0 +1,337 @@ +@book{ala01, + author = "American Lifelines Alliance, (ALA)", + editor = "ASCE", + address = "Reston, VA", + publisher = "American Society of Civil Engineers", + title = "Seismic Fragility Formulations for Water Systems, Part 1 and 2. Report for the American Lifelines Alliance", + year = "2001" +} + +@article{awgb90, + author = "Awumah, K. and Goulter, I. and Bhatt, S. K.", + doi = "10.1007/BF01544084", + journal = "Stochastic Hydrology and Hydraulics", + pages = "309--320", + publisher = "Springer", + title = "Assessment of reliability in water distribution networks using entropy based measures", + volume = "4", + number = "4", + year = "1990" +} + +@article{barr13, + author = "Barker, Kash and Ramirez-Marquez, Jose Emmanuel and Rocco, Claudio M.", + doi = "10.1016/j.ress.2013.03.012", + issn = "0951-8320", + journal = "Reliability Engineering \\& System Safety", + pages = "89--97", + title = "Resilience-based network component importance measures", + volume = "117", + year = "2013" +} + +@misc{bieni19, + author = "Bieniek, T. and van Andel, B. and B{\o}, T.I.", + howpublished = "Software", + title = "Bidirectional {UTM}-{WGS84} converter for python", + url = "https://github.com/Turbo87/utm", + urldate = "2019-02-05", + year = "2019" +} + +@book{crlo02, + author = "Crowl, D.A. and Louvar, J.F.", + address = "Upper Saddle River, NJ", + edition = "3", + isbn = "0-13-138226-8", + pagetotal = "720", + publisher = "Prentice Hall", + title = "Chemical Process Safety: Fundamentals with Applications", + year = "2011" +} + +@techreport{ellt12, + author = "Eto, Joseph H and LaCommare, Kristina Hamachi and Larsen, Peter and Todd, Annika and Fisher, Emily", + doi = "10.2172/1055706", + institution = "Lawrence Berkeley National Laboratory", + number = "LBNL-5268E", + pagetotal = "68", + place = "Berkeley, CA", + title = "An Examination of Temporal Trends in Electricity Reliability Based on Reports from {U.S.} Electric Utilities", + year = "2012" +} + +@misc{folium, + author = "python-visualization", + howpublished = "Software", + title = "folium", + url = "https://github.com/python-visualization/folium", + urldate = "2019-02-05", + year = "2019" +} + +@misc{gacl18, + author = "Gazoni, E. and Clark, C.", + howpublished = "Software", + title = "openpyxl - A Python library to read/write {Excel} 2010 xlsx/xlsm files", + url = "https://openpyxl.readthedocs.io", + urldate = "2018-05-04", + year = "2018" +} + +@inproceedings{hass08, + author = "Hagberg, Aric A. and Schult, Daniel A. and Swart, Pieter J.", + booktitle = "Proceedings of the 7th {Python} in Science Conference ({SciPy2008}), August 19-24, Pasadena, CA, USA", + opteditor = {Ga\"el Varoquaux and Travis Vaught and Jarrod Millman}, + pages = "11--15", + title = "Exploring Network Structure, Dynamics, and Function using {NetworkX}", + url = "https://www.osti.gov/biblio/960616", + year = "2008" +} + +@article{hunt07, + author = "Hunter, John D. and others", + doi = "10.1109/MCSE.2007.55", + journal = "Computing in Science \\& Engineering", + number = "3", + pages = "90--95", + title = "Matplotlib: A {2D} Graphics Environment", + volume = "9", + year = "2007" +} + +@book{icc12, + author = "International Code Council, (ICC)", + address = "Country Club Hills, IL", + isbn = "978-1-60983-046-5", + publisher = "International Code Council", + title = "2012 International Fire Code, Appendix {B} - Fire-Flow Requirements for Buildings", + year = "2011" +} + +@article{jasr08, + author = "Jayaram, Nirmal and Srinivasan, K.", + doi = "10.1029/2006WR005316", + journal = "Water Resources Research", + number = "1", + volume = "44", + pages = "n.p.", + title = "Performance-based optimal design and rehabilitation of water distribution networks using life cycle costing", + year = "2008" +} + +@misc{jvfm21, + author = "Jordahl, K. and Van den Bossche, J. and Fleischmann, M. and McBride, J. and others", + doi = "10.5281/zenodo.5573592", + howpublished = "Software", + title = "geopandas", + year = "2021" +} + +@article{jcmg11, + author = "Joyner, David and \v{C}ert\'{i}k, Ond\v{r}ej and Meurer, Aaron and Granger, Brian E.", + address = "New York, NY, USA", + doi = "10.1145/2110170.2110185", + issn = "1932-2240", + issue_date = "September/December 2011", + journal = "{ACM} Communications in Computer Algebra", + number = "3/4", + numpages = "10", + pages = "225--234", + publisher = "Association for Computing Machinery", + title = "Open Source Computer Algebra Systems: SymPy", + volume = "45", + year = "2012" +} + +@inproceedings{lamb01, + author = "Lambert, Allan", + booktitle = "Proceedings of the {IWA} International Specialised Conference: System Approach to Leakage Control and Water Distribution Systems Management, May 16-18, 2001, Brno, Czech Republic", + opteditor = "Tuhov{\v{c}}{\'a}k, L.", + isbn = "9788072041978", + title = "What do we know about pressure-leakage relationships in distribution systems", + year = "2001", + pages = "89--96", + publisher = "CERM" +} + +@article{lwfz17, + author = "Liu, Haixing and Walski, Tom and Fu, Guangtao and Zhang, Chi", + doi = "10.1061/(ASCE)WR.1943-5452.0000766", + journal = "Journal of Water Resources Planning and Management", + number = "7", + pages = "04017019", + title = "Failure Impact Analysis of Isolation Valves in a Water Distribution Network", + volume = "143", + year = "2017" +} + +@book{mcki13, + author = "McKinney, Wes", + publisher = "O'Reilly Media, Inc.", + title = "Python for data analysis: Data wrangling with {Pandas}, {NumPy}, and {IPython}", + year = "2012", + address = "Sebastopal, CA", + edition = "1", + pagetotal = "463", + isbn = "978-1449319793" +} + +@techreport{niac09, + author = "National Infrastructure Advisory Council, (NIAC)", + address = "Washington, D.C.", + institution = "U.S. Department of Homeland Security", + title = "Critical Infrastructure Resilience, Final Report and Recommendations", + opturl = "http://www.dhs.gov/xlibrary/assets/niac/niac\_critical\_infrastructure\_resilience.pdf", + opturldate = "2014-09-20", + year = "2009", + url = "https://www.cisa.gov/resources-tools/resources/niac-critical-infrastructure-resilience-final-report-and-recommendations", + urldate = "2023-11-14" +} + +@article{osks02, + author = "Ostfeld, Avi and Kogan, Dimitri and Shamir, Uri", + doi = "10.1016/S1462-0758(01)00055-3", + issn = "1462-0758", + journal = "Urban Water", + number = "1", + pages = "53--61", + title = "Reliability simulation of water distribution systems - single and multiquality", + volume = "4", + year = "2002" +} + +@techreport{ross00, + author = "Rossman, L. A.", + address = "Cincinnati, OH", + institution = "U.S. Environmental Protection Agency", + number = "EPA/600/R--00/057", + title = "{EPANET} 2 User Manual", + year = "2000", + pagetotal = "200" +} + +@misc{rtree, + author = "Toblerity", + howpublished = "Software", + title = "rtree", + url = "https://github.com/Toblerity/rtree", + urldate = "2022-03-17", + year = "2022" +} + +@techreport{rwts20, + author = "Rossman, L. and Woo, H. and M., Tryby and Shang, F. and Janke, R. and and Haxton, T.", + institution = "U.S. Environmental Protection Agency", + address = "Washington, DC", + number = "EPA/600/R-20/133", + title = "{EPANET} 2.2 User Manual", + year = "2020" +} + +@inproceedings{sokz12, + author = "Salomons, E. and Ostfeld, A. and Kapelan, Z. and Zecchin, A. and Marchi, A. and Simpson, A.", + booktitle = "Water Distribution Systems Analysis Conference 2012, September 24-27, Adelaide, South Australia, Australia", + url = "https://emps.exeter.ac.uk/media/universityofexeter/emps/research/cws/downloads/WDSA2012-BWNII-ProblemDescription.pdf", + publisher = "American Society of Civil Engineers", + title = "The battle of the water networks {II} - Problem description", + urldate = "2017-05-23", + year = "2012" +} + +@misc{sphc16, + author = "Sievert, C. and Parmer, C. and Hocking, T. and Chamberlain, S. and Ram, K. and Corvellec, M. and Despouy, P.", + howpublished = "Software", + title = "plotly: Create interactive web graphics via {Plotly}'s {JavaScript} graphing library", + year = "2016", + url = "https://plot.ly", + publisher = "Plotly Technologies Inc.", + address = "Montreal, QC", + optcomment = "modified from below preferred citation, per Plotly" +} + +@article{todi00, + author = "Todini, Ezio", + doi = "10.1016/S1462-0758(00)00049-2", + issn = "1462-0758", + journal = "Urban Water", + optnote = "Developments in water distribution systems", + number = "2", + pages = "115--122", + title = "Looped water distribution networks design using a resilience index based heuristic approach", + volume = "2", + year = "2000" +} + +@techreport{usepa14, + author = "U.S. Environmental Protection Agency, (U.S. EPA)", + address = "Washington DC", + institution = "U.S. Environmental Protection Agency", + number = "EPA 600/R--14/383", + pagetotal = "58", + title = "Systems Measures of Water Distribution System Resilience", + year = "2014" +} + +@techreport{usepa15, + author = "U.S. Environmental Protection Agency, (U.S. EPA)", + address = "Washington DC", + institution = "U.S. Environmental Protection Agency", + number = "EPA/600/R--14/338", + pagetotal = "187", + title = "{Water} {Security} {Toolkit} User Manual", + year = "2015" +} + +@article{vacv11, + author = "van der Walt, Stefan and Colbert, S. Chris and Varoquaux, Gael", + doi = "10.1109/MCSE.2011.37", + journal = "Computing in Science and Engineering", + number = "2", + pages = "22--30", + title = "The {NumPy} Array: A Structure for Efficient Numerical Computation", + volume = "13", + year = "2011" +} + +@article{wasm88, + author = "Wagner, Janet M. and Shamir, Uri and Marks, David H.", + doi = "10.1061/(ASCE)0733-9496(1988)114:3(276)", + journal = "Journal of Water Resources Planning and Management", + number = "3", + pages = "276--294", + title = "Water Distribution Reliability: Simulation Methods", + volume = "114", + year = "1988" +} + +@inproceedings{wawc06, + author = "Walski, Thomas M. and Weiler, Justin Sterling and Culver, Teresa", + booktitle = "Proceedings of the Eighth Annual Water Distribution Systems Analysis ({WDSA}) Symposium, August 27-30, 2006, Cincinnati, OH", + opteditor = "Steven G. Buchberger and Robert M. Clark and Walter M. Grayman and James G. Uber", + publisher = "American Society of Civil Engineers", + doi = "10.1061/40941(247)31", + isbn = "9780784409411", + pages = "1--9", + title = "Using Criticality Analysis to Identify Impact of Valve Location", + year = "2008" +} + +@techreport{wwqp06, + author = "Wald, D.J. and Worden, B.C. and Quitoriano, V. and Pankow, K.L.", + institution = "United States Geologic Survey", + title = "{ShakeMap} manual: Technical manual, user's guide, and software guide", + url = "http://pubs.usgs.gov/tm/2005/12A01/", + urldate = "2017-04-25", + year = "2006" +} + +@book{wcsg03, + author = "Walski, T.M. and Chase, D.V. and Savic, D.A. and Grayman, W. and Beckwith, S.", + address = "Waterbury, CT", + isbn = "978-0971414129", + pagetotal = "800", + publisher = "Haestad Press", + title = "Advanced Water Distribution Modeling and Management", + year = "2003" +} diff --git a/documentation/resilience.rst b/documentation/resilience.rst index 9cdd28e4a..08ec942f8 100644 --- a/documentation/resilience.rst +++ b/documentation/resilience.rst @@ -9,8 +9,8 @@ Resilience of water distribution systems refers to the design, maintenance, and operations of that system. All these aspects must work together to limit the effects of disasters and enable rapid return to normal delivery of safe water to customers. -Numerous resilience metrics have been suggested [USEPA14]_. -These metrics generally fall into five categories: topographic, hydraulic, water quality, water security, and economic [USEPA14]_. +Numerous resilience metrics have been suggested :cite:p:`usepa14`. +These metrics generally fall into five categories: topographic, hydraulic, water quality, water security, and economic :cite:p:`usepa14`. When quantifying resilience, it is important to understand which metric best defines resilience for a particular scenario. WNTR includes many metrics to help @@ -30,7 +30,7 @@ The following sections outline metrics that can be computed using WNTR, includin While some metrics define resilience as a single system-wide quantity, other metrics define quantities that are a function of time, space, or both. -For this reason, state transition plots [BaRR13]_ and network graphics +For this reason, state transition plots :cite:p:`barr13` and network graphics are useful ways to visualize resilience and compare metrics, as shown in :numref:`fig-metrics`. In the state transition plot, the x-axis represents time (before, during, and after a disruptive incident). The y-axis represents performance. This can be any time varying resilience metric that responds to the disruptive state. @@ -279,19 +279,19 @@ Hydraulic metrics included in WNTR are listed in :numref:`table-hydraulic-metri Demand To determine the number of node-time pairs above or below a specified demand threshold, use the :class:`~wntr.metrics.misc.query` method on results.node['demand']. - This method can be used to compute the fraction of delivered demand, from [OsKS02]_. + This method can be used to compute the fraction of delivered demand, from :cite:p:`osks02`. Water service availability Water service availability is the ratio of delivered demand to the expected demand. This metric can be computed as a function of time or space using the :class:`~wntr.metrics.hydraulic.water_service_availability` method. - This method can be used to compute the fraction of delivered volume, from [OsKS02]_. + This method can be used to compute the fraction of delivered volume, from :cite:p:`osks02`. - Todini index The Todini index [Todi00]_ is related to the capability of a system to overcome + Todini index The Todini index :cite:p:`todi00` is related to the capability of a system to overcome failures while still meeting demands and pressures at nodes. The Todini index defines resilience at a specific time as a measure of surplus power at each node. The Todini index can be computed using the :class:`~wntr.metrics.hydraulic.todini_index` method. - Modified resilience index The modified resilience index [JaSr08]_ is similar to the Todini index, but is only computed at junctions. + Modified resilience index The modified resilience index :cite:p:`jasr08` is similar to the Todini index, but is only computed at junctions. The metric defines resilience at a specific time as a measure of surplus power at each junction or as a system average. The modified resilience index can be computed using the :class:`~wntr.metrics.hydraulic.modified_resilience_index` method. @@ -301,7 +301,7 @@ Hydraulic metrics included in WNTR are listed in :numref:`table-hydraulic-metri A value of 1 indicates that tank storage is maximized, while a value of 0 means there is no water stored in the tank. Tank capacity can be computed using the :class:`~wntr.metrics.hydraulic.tank_capacity` method. - Entropy Entropy [AwGB90]_ is a measure of uncertainty in a random variable. + Entropy Entropy :cite:p:`awgb90` is a measure of uncertainty in a random variable. In a water distribution network model, the random variable is flow in the pipes and entropy can be used to measure alternate flow paths when a network component fails. A network that carries maximum entropy @@ -310,11 +310,11 @@ Hydraulic metrics included in WNTR are listed in :numref:`table-hydraulic-metri The :class:`~wntr.network.model.WaterNetworkModel.to_graph` method can be used to generate a weighted graph. Entropy can be computed using the :class:`~wntr.metrics.hydraulic.entropy` method. - Expected demand Expected demand is computed at each node and timestep based on node demand, demand pattern, and demand multiplier [USEPA15]_. + Expected demand Expected demand is computed at each node and timestep based on node demand, demand pattern, and demand multiplier :cite:p:`usepa15`. The metric can be computed using the :class:`~wntr.metrics.hydraulic.expected_demand` method. This method does not require running a hydraulic simulation. - Average expected demand Average expected demand per day is computed at each node based on node demand, demand pattern, and demand multiplier [USEPA15]_. + Average expected demand Average expected demand per day is computed at each node based on node demand, demand pattern, and demand multiplier :cite:p:`usepa15`. The metric can be computed using the :class:`~wntr.metrics.hydraulic.average_expected_demand` method. This method does not require running a hydraulic simulation. @@ -385,7 +385,7 @@ Water quality metrics included in WNTR are listed in :numref:`table-water-quali Concentration To determine the number of node-time pairs above or below a specified concentration threshold, use the :class:`~wntr.metrics.misc.query` method on results.node['quality'] after a simulation using CHEM or TRACE. - This method can be used to compute the fraction of delivered quality, from [OsKS02]_. + This method can be used to compute the fraction of delivered quality, from :cite:p:`osks02`. Population impacted As stated above, population that is impacted by a specific quantity can be computed using the :class:`~wntr.metrics.misc.population_impacted` method. This can be applied to water quality metrics. @@ -434,7 +434,7 @@ The following examples compute water quality metrics, including: Water security metrics ----------------------- -Water security metrics quantify potential consequences of contamination scenarios. These metrics are documented in [USEPA15]_. +Water security metrics quantify potential consequences of contamination scenarios. These metrics are documented in :cite:p:`usepa15`. Water security metrics included in WNTR are listed in :numref:`table-water-security-metrics`. .. _table-water-security-metrics: @@ -443,13 +443,13 @@ Water security metrics included in WNTR are listed in :numref:`table-water-secu ===================================== ================================================================================================================================================ Metric Description ===================================== ================================================================================================================================================ - Mass consumed Mass consumed is the mass of a contaminant that exits the network via node demand at each node-time pair [USEPA15]_. + Mass consumed Mass consumed is the mass of a contaminant that exits the network via node demand at each node-time pair :cite:p:`usepa15`. The metric can be computed using the :class:`~wntr.metrics.water_security.mass_contaminant_consumed` method. - Volume consumed Volume consumed is the volume of a contaminant that exits the network via node demand at each node-time pair [USEPA15]_. + Volume consumed Volume consumed is the volume of a contaminant that exits the network via node demand at each node-time pair :cite:p:`usepa15`. The metric can be computed using the :class:`~wntr.metrics.water_security.volume_contaminant_consumed` method. - Extent of contamination Extent of contamination is the length of contaminated pipe at each node-time pair [USEPA15]_. + Extent of contamination Extent of contamination is the length of contaminated pipe at each node-time pair :cite:p:`usepa15`. The metric can be computed using the :class:`~wntr.metrics.water_security.extent_contaminant` method. Population impacted As stated above, population that is impacted by a specific quantity can be computed using the @@ -510,12 +510,12 @@ Economic metrics included in WNTR are listed in :numref:`table-economic-metrics Metric Description ===================================== ================================================================================================================================================ Network cost Network cost is the annual maintenance and operations cost of tanks, pipes, valves, and pumps based on the equations from the Battle of - Water Networks II [SOKZ12]_. + Water Networks II :cite:p:`sokz12`. Default values can be included in the calculation. Network cost can be computed using the :class:`~wntr.metrics.economic.annual_network_cost` method. - Greenhouse gas emissions Greenhouse gas emissions is the annual emissions associated with pipes based on equations from the Battle of Water Networks II [SOKZ12]_. + Greenhouse gas emissions Greenhouse gas emissions is the annual emissions associated with pipes based on equations from the Battle of Water Networks II :cite:p:`sokz12`. Default values can be included in the calculation. Greenhouse gas emissions can be computed using the :class:`~wntr.metrics.economic.annual_ghg_emissions` method. diff --git a/documentation/resultsobject.rst b/documentation/resultsobject.rst index 76480a7a4..7ba089176 100644 --- a/documentation/resultsobject.rst +++ b/documentation/resultsobject.rst @@ -194,7 +194,7 @@ Network and time series graphics can be customized to add titles, legends, axis Pandas includes methods to write DataFrames to the following file formats: -* Excel +* Microsoft Excel (xlsx) * Comma-separated values (CSV) * Hierarchical Data Format (HDF) * JavaScript Object Notation (JSON) @@ -205,4 +205,4 @@ For example, DataFrames can be saved to Excel files using: >>> pressure.to_excel('pressure.xlsx') .. note:: - The Pandas method ``to_excel`` requires the Python package **openpyxl** [GaCl18]_, which is an optional dependency of WNTR. + The Pandas method ``to_excel`` requires the Python package **openpyxl** :cite:p:`gacl18`, which is an optional dependency of WNTR. diff --git a/documentation/units.rst b/documentation/units.rst index 3c55d6337..fbfc172f6 100644 --- a/documentation/units.rst +++ b/documentation/units.rst @@ -7,27 +7,27 @@ Units All data in WNTR is stored in the following SI (International System) units: -* Acceleration = :math:`g` (1 :math:`g` = 9.81 :math:`m/s^2`) -* Concentration = :math:`kg/m^3` -* Demand = :math:`m^3/s` -* Diameter = :math:`m` -* Elevation = :math:`m` -* Energy = :math:`J` -* Flow rate = :math:`m^3/s` -* Head = :math:`m` -* Headloss = :math:`m` -* Length = :math:`m` -* Mass = :math:`kg` -* Mass injection = :math:`kg/s` -* Power = :math:`W` -* Pressure head = :math:`m` (this assumes a fluid density of 1000 :math:`kg/m^3`) -* Time = :math:`s` -* Velocity = :math:`m/s` -* Volume = :math:`m^3` +* Acceleration = :math:`\rm g` (:math:`\rm g \equiv 9.80665 m/s^2`) +* Concentration = :math:`\rm kg/m^3` +* Demand = :math:`\rm m^3/s` +* Diameter = :math:`\rm m` +* Elevation = :math:`\rm m` +* Energy = :math:`\rm J` +* Flow rate = :math:`\rm m^3/s` +* Head = :math:`\rm m` +* Headloss = :math:`\rm m` +* Length = :math:`\rm m` +* Mass = :math:`\rm kg` +* Mass injection = :math:`\rm kg/s` +* Power = :math:`\rm W` +* Pressure head = :math:`\rm m` (assumes a fluid density of 1000 :math:`\rm kg/m^3`) +* Time = :math:`\rm s` +* Velocity = :math:`\rm m/s` +* Volume = :math:`\rm m^3` When setting up analysis in WNTR, all input values should be specified in SI units. All simulation results are also stored in SI units and can be converted to other units if desired, -for instance by using the SymPy Python package [JCMG11]_. +for instance by using the SymPy Python package :cite:p:`jcmg11`. EPANET unit conventions ------------------------ @@ -40,7 +40,7 @@ These options define the mass and flow units used in the file. Some units also depend on the equation used for pipe roughness headloss and on the reaction order specified. -For reference, :numref:`table-epanet-units` includes EPANET unit conventions [Ross00]_. +For reference, :numref:`table-epanet-units` includes EPANET unit conventions :cite:p:`ross00`. .. _table-epanet-units: .. table:: EPANET INP File Unit Conventions @@ -90,7 +90,7 @@ For reference, :numref:`table-epanet-units` includes EPANET unit conventions [Ro | Reaction | - *mass* /ft/day (0-order) | - *mass* /m/day (0-order) | | coefficient (Wall) | - ft/day (1st-order) | - m/day (1st-order) | +----------------------+-------------------------------------+------------------------------------+ - | Roughness | - 10 :sup:`-3` ft (Darcy-Weisbach) | - mm (Darcy-Weisbach) | + | Roughness | - 0.001 ft (Darcy-Weisbach) | - mm (Darcy-Weisbach) | | coefficient | - unitless (otherwise) | - unitless (otherwise) | +----------------------+-------------------------------------+------------------------------------+ | Source mass | *mass* /min | *mass* /min | diff --git a/documentation/userguide.rst b/documentation/userguide.rst new file mode 100644 index 000000000..6e31a2128 --- /dev/null +++ b/documentation/userguide.rst @@ -0,0 +1,94 @@ +.. figure:: _static/logo.jpg + :scale: 10 % + :alt: Logo + +User Guide +========== + +The Water Network Tool for Resilience (WNTR) is an EPANET compatible Python package +designed to simulate and analyze resilience of water distribution networks. + +US EPA Disclaimer +----------------- + +The U.S. Environmental Protection Agency through its Office of Research and Development funded and collaborated +in the research described here under an Interagency Agreement with the Department of Energy's Sandia National Laboratories. +It has been subjected to the Agency's review and has been approved for publication. Note that approval does not signify that +the contents necessarily reflect the views of the Agency. Mention of trade names products, or services does not convey official +EPA approval, endorsement, or recommendation. + + +Sandia Funding Statement +------------------------ + +Sandia National Laboratories is a multimission laboratory managed and operated by National Technology and +Engineering Solutions of Sandia, LLC., a wholly owned subsidiary of Honeywell International, Inc., for the +U.S. Department of Energy's National Nuclear Security Administration under contract DE-NA-0003525. + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Introduction + + overview + installation + framework + units + getting_started + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Model building + + waternetworkmodel + model_io + controls + networkxgraph + layers + options + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Simulation + + hydraulics + waterquality + resultsobject + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Analysis + + disaster_models + criticality + resilience + fragility + morph + graphics + gis + advancedsim + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Backmatter + + license + whatsnew + developers + acronyms + reference + + +Citing WNTR +----------------- +To cite WNTR, use one of the following references: + +* Klise, K.A., Hart, D.B., Bynum, M., Hogge, J., Haxton, T., Murray, R., Burkhardt, J. (2020). Water Network Tool for Resilience (WNTR) User Manual: Version 0.2.3. U.S. EPA Office of Research and Development, Washington, DC, EPA/600/R-20/185, 82p. + +* Klise, K.A., Murray, R., Haxton, T. (2018). An overview of the Water Network Tool for Resilience (WNTR), In Proceedings of the 1st International WDSA/CCWI Joint Conference, Kingston, Ontario, Canada, July 23-25, 075, 8p. + +* Klise, K.A., Bynum, M., Moriarty, D., Murray, R. (2017). A software framework for assessing the resilience of drinking water systems to disasters with an example earthquake case study, Environmental Modelling and Software, 95, 420-431, doi: 10.1016/j.envsoft.2017.06.022 diff --git a/documentation/users.rst b/documentation/users.rst index 2d1c5e9c5..0fa282b46 100644 --- a/documentation/users.rst +++ b/documentation/users.rst @@ -36,76 +36,83 @@ Related software * VisWaterNet: https://github.com/tylertrimble/viswaternet Publications ------------------ +------------ + +.. + - Abdel-Mottaleb, N., Ghasemi Saghand, P., Charkhgard, H., & Zhang, Q. (2019). An exact multiobjective optimization approach for evaluating water distribution infrastructure criticality and geospatial interdependence. Water Resources Research, 55(7), 5255-5276. + + - Antonowicz, A., Bałut, A., Urbaniak, A., & Zakrzewski, P. (2019). Algorithm for Early Warning System for Contamination in Water Network. In 2019 20th International Carpathian Control Conference (ICCC) (pp. 1-5). IEEE. + + - Antonowicz, A., & Urbaniak, A. (2022). Optimization of the process of restoring the continuity of the WDS based on the matrix and genetic algorithm approach. Bulletin of the Polish Academy of Sciences: Technical Sciences, e141594-e141594. -* Abdel-Mottaleb, N., Ghasemi Saghand, P., Charkhgard, H., & Zhang, Q. (2019). An exact multiobjective optimization approach for evaluating water distribution infrastructure criticality and geospatial interdependence. Water Resources Research, 55(7), 5255-5276. + - Bjerke, M. (2019). Leak Detection in Water Distribution Networks using Gated Recurrent Neural Networks, Master's thesis, Norwegian University of Science and Technology (NTNU). -* Antonowicz, A., Bałut, A., Urbaniak, A., & Zakrzewski, P. (2019). Algorithm for Early Warning System for Contamination in Water Network. In 2019 20th International Carpathian Control Conference (ICCC) (pp. 1-5). IEEE. + - Bunn, B. B. (2018). An operational model of interdependent water and power distribution infrastructure systems. Naval Postgraduate School, Monterey, CA. -* Antonowicz, A., & Urbaniak, A. (2022). Optimization of the process of restoring the continuity of the WDS based on the matrix and genetic algorithm approach. Bulletin of the Polish Academy of Sciences: Technical Sciences, e141594-e141594. + - Fan, X., Zhang, X., & Yu, X. B. (2021). Machine learning model and strategy for fast and accurate detection of leaks in water supply network. Journal of Infrastructure Preservation and Resilience, 2(1), 1-21. -* Bjerke, M. (2019). Leak Detection in Water Distribution Networks using Gated Recurrent Neural Networks, Master's thesis, Norwegian University of Science and Technology (NTNU). + - Han, Q., Eguchi, R., Mehrotra, S., & Venkatasubramanian, N. (2018). Enabling state estimation for fault identification in water distribution systems under large disasters. In 2018 IEEE 37th Symposium on Reliable Distributed Systems (SRDS) (pp. 161-170). IEEE. -* Bunn, B. B. (2018). An operational model of interdependent water and power distribution infrastructure systems. Naval Postgraduate School, Monterey, CA. + - Han, Q., Mehrotra, S., & Venkatasubramanian, N. (2019). Aquaeis: Middleware support for event identification in community water infrastructures. In Proceedings of the 20th International Middleware Conference (pp. 293-305). -* Fan, X., Zhang, X., & Yu, X. B. (2021). Machine learning model and strategy for fast and accurate detection of leaks in water supply network. Journal of Infrastructure Preservation and Resilience, 2(1), 1-21. + - Huang, H., & Burton, H. V. (2022). Dynamic seismic damage assessment of distributed infrastructure systems using graph neural networks and semi-supervised machine learning. Advances in Engineering Software, 168, 103113. -* Han, Q., Eguchi, R., Mehrotra, S., & Venkatasubramanian, N. (2018). Enabling state estimation for fault identification in water distribution systems under large disasters. In 2018 IEEE 37th Symposium on Reliable Distributed Systems (SRDS) (pp. 161-170). IEEE. + - Iannacone, L., Sharma, N., Tabandeh, A., & Gardoni, P. (2022). Modeling time-varying reliability and resilience of deteriorating infrastructure. Reliability Engineering & System Safety, 217, 108074. -* Han, Q., Mehrotra, S., & Venkatasubramanian, N. (2019). Aquaeis: Middleware support for event identification in community water infrastructures. In Proceedings of the 20th International Middleware Conference (pp. 293-305). + - Kammoun, M., Kammoun, A., & Abid, M. (2022). Experiments based comparative evaluations of machine learning techniques for leak detection in water distribution systems. Water Supply, 22(1), 628-642. -* Huang, H., & Burton, H. V. (2022). Dynamic seismic damage assessment of distributed infrastructure systems using graph neural networks and semi-supervised machine learning. Advances in Engineering Software, 168, 103113. + - Liu, J., & Kang, Y. (2022). Segment-based resilience response and intervention evaluation of water distribution systems. AQUA—Water Infrastructure, Ecosystems and Society, 71(1), 100-119. -* Iannacone, L., Sharma, N., Tabandeh, A., & Gardoni, P. (2022). Modeling time-varying reliability and resilience of deteriorating infrastructure. Reliability Engineering & System Safety, 217, 108074. + - Liu, Y., Barrows, C., Macknick, J., & Mauter, M. (2020). Optimization Framework to Assess the Demand Response Capacity of a Water Distribution System. Journal of Water Resources Planning and Management, 146(8), 04020063. -* Kammoun, M., Kammoun, A., & Abid, M. (2022). Experiments based comparative evaluations of machine learning techniques for leak detection in water distribution systems. Water Supply, 22(1), 628-642. + - Logan, K. T., Lestakova, M., Thiessen, N., Engels, J. I., & Pelz, P. F. (2021). Water Distribution in a Socio-Technical System: Resilience Assessment for Critical Events Causing Demand Relocation. Water, 13(15), 2062. -* Liu, J., & Kang, Y. (2022). Segment-based resilience response and intervention evaluation of water distribution systems. AQUA—Water Infrastructure, Ecosystems and Society, 71(1), 100-119. + - Lorenz, I. S., & Pelz, P. F. (2020). Optimal resilience enhancement of water distribution systems. Water, 12(9), 2602. -* Liu, Y., Barrows, C., Macknick, J., & Mauter, M. (2020). Optimization Framework to Assess the Demand Response Capacity of a Water Distribution System. Journal of Water Resources Planning and Management, 146(8), 04020063. + - Marlim, M. S., & Kang, D. (2022). Contaminant Flushing in Water Distribution Networks Incorporating Customer Faucet Control. Sustainability, 14(4), 2249. -* Logan, K. T., Lestakova, M., Thiessen, N., Engels, J. I., & Pelz, P. F. (2021). Water Distribution in a Socio-Technical System: Resilience Assessment for Critical Events Causing Demand Relocation. Water, 13(15), 2062. + - Mazumder, R. K., Salman, A. M., Li, Y., & Yu, X. (2019). A Decision-making Framework for Water Distribution Systems using Fuzzy Inference and Centrality Analysis. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, Seoul, South Korea, May 26-30, 2019. -* Lorenz, I. S., & Pelz, P. F. (2020). Optimal resilience enhancement of water distribution systems. Water, 12(9), 2602. + - Mazumder, R. K., Salman, A. M., & Li, Y. (2020). Post-disaster sequential recovery planning for water distribution systems using topological and hydraulic metrics. Structure and Infrastructure Engineering, 1-16. -* Marlim, M. S., & Kang, D. (2022). Contaminant Flushing in Water Distribution Networks Incorporating Customer Faucet Control. Sustainability, 14(4), 2249. + - Murillo, A., Taormina, R., Tippenhauer, N., & Galelli, S. (2020). Co-Simulating Physical Processes and Network Data for High-Fidelity Cyber-Security Experiments. In Sixth Annual Industrial Control System Security (ICSS) Workshop (pp. 13-20). -* Mazumder, R. K., Salman, A. M., Li, Y., & Yu, X. (2019). A Decision-making Framework for Water Distribution Systems using Fuzzy Inference and Centrality Analysis. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, Seoul, South Korea, May 26-30, 2019. + - Nikolopoulos, D., Moraitis, G., Bouziotas, D., Lykou, A., Karavokiros, G., & Makropoulos, C. (2020). Cyber-physical stress-testing platform for water distribution networks. Journal of Environmental Engineering, 146(7), 04020061. -* Mazumder, R. K., Salman, A. M., & Li, Y. (2020). Post-disaster sequential recovery planning for water distribution systems using topological and hydraulic metrics. Structure and Infrastructure Engineering, 1-16. + - Nikolopoulos, D., Ostfeld, A., Salomons, E., & Makropoulos, C. (2021). Resilience Assessment of Water Quality Sensor Designs under Cyber-Physical Attacks. Water, 13(5), 647. -* Murillo, A., Taormina, R., Tippenhauer, N., & Galelli, S. (2020). Co-Simulating Physical Processes and Network Data for High-Fidelity Cyber-Security Experiments. In Sixth Annual Industrial Control System Security (ICSS) Workshop (pp. 13-20). + - Nikolopoulos, D., Kossieris, P., Tsoukalas, I., & Makropoulos, C. (2022). Stress-testing framework for urban water systems: A source to tap approach for stochastic resilience assessment. Water, 14(2), 154. -* Nikolopoulos, D., Moraitis, G., Bouziotas, D., Lykou, A., Karavokiros, G., & Makropoulos, C. (2020). Cyber-physical stress-testing platform for water distribution networks. Journal of Environmental Engineering, 146(7), 04020061. + - Nikolopoulos, D., & Makropoulos, C. (2022). Stress-testing water distribution networks for cyber-physical attacks on water quality. Urban Water Journal, 19(3), 256-270. -* Nikolopoulos, D., Ostfeld, A., Salomons, E., & Makropoulos, C. (2021). Resilience Assessment of Water Quality Sensor Designs under Cyber-Physical Attacks. Water, 13(5), 647. + - Nyahora, P. P., Babel, M. S., Ferras, D., & Emen, A. (2020). Multi-objective optimization for improving equity and reliability in intermittent water supply systems. Water Supply, 20(5), 1592-1603. -* Nikolopoulos, D., Kossieris, P., Tsoukalas, I., & Makropoulos, C. (2022). Stress-testing framework for urban water systems: A source to tap approach for stochastic resilience assessment. Water, 14(2), 154. + - Pagani, A., Wei, Z., Silva, R., & Guo, W. (2020). Neural Network Approximation of Graph Fourier Transforms for Sparse Sampling of Networked Flow Dynamics. arXiv preprint arXiv:2002.05508. -* Nikolopoulos, D., & Makropoulos, C. (2022). Stress-testing water distribution networks for cyber-physical attacks on water quality. Urban Water Journal, 19(3), 256-270. + - Rahimi-Golkhandan, A., Aslani, B., & Mohebbi, S. (2022). Predictive resilience of interdependent water and transportation infrastructures: A sociotechnical approach. Socio-Economic Planning Sciences, 80, 101166. -* Nyahora, P. P., Babel, M. S., Ferras, D., & Emen, A. (2020). Multi-objective optimization for improving equity and reliability in intermittent water supply systems. Water Supply, 20(5), 1592-1603. + - Randeniya, A., Radhakrishnan, M., Sirisena, T. A. J. G., Maish, I., & Pathirana, A. (2022). Equity-performance trade-off in water rationing regimes with domestic storage. Water Supply, 22(5), 4781-4797. -* Pagani, A., Wei, Z., Silva, R., & Guo, W. (2020). Neural Network Approximation of Graph Fourier Transforms for Sparse Sampling of Networked Flow Dynamics. arXiv preprint arXiv:2002.05508. + - Sharma, N., Tabandeh, A., & Gardoni, P. (2019). Recovery optimization of interdependent infrastructure: a multi-scale approach. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13. -* Rahimi-Golkhandan, A., Aslani, B., & Mohebbi, S. (2022). Predictive resilience of interdependent water and transportation infrastructures: A sociotechnical approach. Socio-Economic Planning Sciences, 80, 101166. + - Sharma, N., Tabandeh, A., & Gardoni, P. (2020). Regional resilience analysis: A multiscale approach to optimize the resilience of interdependent infrastructure. Computer-Aided Civil and Infrastructure Engineering, 35(12), 1315-1330. -* Randeniya, A., Radhakrishnan, M., Sirisena, T. A. J. G., Maish, I., & Pathirana, A. (2022). Equity–performance trade-off in water rationing regimes with domestic storage. Water Supply, 22(5), 4781-4797. + - Tabandeh, S. (2018). Societal risk and resilience analysis: A multi-scale approach to model the dynamics of infrastructure-social systems (Doctoral dissertation, University of Illinois at Urbana-Champaign). -* Sharma, N., Tabandeh, A., & Gardoni, P. (2019). Recovery optimization of interdependent infrastructure: a multi-scale approach. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13. + - Tabandeh, A., Sharma, N., & Gardoni, P. (2022). Uncertainty propagation in risk and resilience analysis of hierarchical systems. Reliability Engineering & System Safety, 219, 108208. -* Sharma, N., Tabandeh, A., & Gardoni, P. (2020). Regional resilience analysis: A multiscale approach to optimize the resilience of interdependent infrastructure. Computer-Aided Civil and Infrastructure Engineering, 35(12), 1315-1330. + - Tomar, A., Burton, H. V., Mosleh, A., & Yun Lee, J. (2020). Hindcasting the Functional Loss and Restoration of the Napa Water System Following the 2014 Earthquake Using Discrete-Event Simulation. Journal of Infrastructure Systems, 26(4), 04020035. -* Tabandeh, S. (2018). Societal risk and resilience analysis: A multi-scale approach to model the dynamics of infrastructure-social systems (Doctoral dissertation, University of Illinois at Urbana-Champaign). + - Vrachimis, S. G., & Kyriakou, M. S. (2018). LeakDB: A benchmark dataset for leakage diagnosis in water distribution networks. In WDSA/CCWI Joint Conference Proceedings (Vol. 1). -* Tabandeh, A., Sharma, N., & Gardoni, P. (2022). Uncertainty propagation in risk and resilience analysis of hierarchical systems. Reliability Engineering & System Safety, 219, 108208. + - Vrachimis, S. G., Eliades, D. G., & Polycarpou, M. M. (2018). Leak detection in water distribution systems using hydraulic interval state estimation. In 2018 IEEE Conference on Control Technology and Applications (CCTA) (pp. 565-570). IEEE. -* Tomar, A., Burton, H. V., Mosleh, A., & Yun Lee, J. (2020). Hindcasting the Functional Loss and Restoration of the Napa Water System Following the 2014 Earthquake Using Discrete-Event Simulation. Journal of Infrastructure Systems, 26(4), 04020035. + - Wille, D. (2019). Simulation-optimization for operational resilience of interdependent water-power systems in the US Virgin Islands (Doctoral dissertation, Monterey, CA; Naval Postgraduate School). -* Vrachimis, S. G., & Kyriakou, M. S. (2018). LeakDB: A benchmark dataset for leakage diagnosis in water distribution networks. In WDSA/CCWI Joint Conference Proceedings (Vol. 1). + - Xing, L., & Sela, L. (2020). Transient simulations in water distribution networks: TSNet python package. Advances in Engineering Software, 149, 102884. -* Vrachimis, S. G., Eliades, D. G., & Polycarpou, M. M. (2018). Leak detection in water distribution systems using hydraulic interval state estimation. In 2018 IEEE Conference on Control Technology and Applications (CCTA) (pp. 565-570). IEEE. -* Wille, D. (2019). Simulation-optimization for operational resilience of interdependent water-power systems in the US Virgin Islands (Doctoral dissertation, Monterey, CA; Naval Postgraduate School). +.. bibliography:: + :notcited: + :list: bullet -* Xing, L., & Sela, L. (2020). Transient simulations in water distribution networks: TSNet python package. Advances in Engineering Software, 149, 102884. diff --git a/documentation/wntr-api.rst b/documentation/wntr-api.rst new file mode 100644 index 000000000..f3fc7c4c1 --- /dev/null +++ b/documentation/wntr-api.rst @@ -0,0 +1,27 @@ +.. _api_documentation: + +================= +API documentation +================= + +.. automodule:: wntr + :no-members: + :no-undoc-members: + :no-inherited-members: + + .. rubric:: Submodules + + .. autosummary:: + :toctree: apidoc + :recursive: + :template: autosummary/module.rst + + wntr.epanet + wntr.gis + wntr.graphics + wntr.metrics + wntr.morph + wntr.network + wntr.scenario + wntr.sim + wntr.utils diff --git a/requirements.txt b/requirements.txt index 77fd539c5..b719f3ed8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -15,7 +15,10 @@ rtree; sys_platform == "darwin" or sys_platform == "linux" # Documentation sphinx +sphinx_design sphinx_rtd_theme +pydata_sphinx_theme +sphinxcontrib-bibtex # Testing pytest diff --git a/wntr/epanet/__init__.py b/wntr/epanet/__init__.py index 272572d1c..a923a440d 100644 --- a/wntr/epanet/__init__.py +++ b/wntr/epanet/__init__.py @@ -3,5 +3,4 @@ """ from .io import InpFile #, BinFile, HydFile, RptFile from .util import FlowUnits, MassUnits, HydParam, QualParam, EN -import wntr.epanet.toolkit - +from . import toolkit, io, util diff --git a/wntr/epanet/io.py b/wntr/epanet/io.py index 27936ba3c..696a8e1e9 100644 --- a/wntr/epanet/io.py +++ b/wntr/epanet/io.py @@ -1,13 +1,5 @@ """ The wntr.epanet.io module contains methods for reading/writing EPANET input and output files. - -.. rubric:: Contents - -.. autosummary:: - - InpFile - BinFile - """ from __future__ import absolute_import @@ -259,7 +251,7 @@ def read(self, inp_files, wn=None): Returns ------- - :class:`~wntr.network.model.WaterNetworkModel` + WaterNetworkModel A water network model object """ @@ -2451,34 +2443,33 @@ def generate_control(self, model): class BinFile(object): - """ - EPANET binary output file reader. + """EPANET binary output file reader. This class provides read functionality for EPANET binary output files. Parameters ---------- - results_type : list of :class:`~wntr.epanet.util.ResultType`, default=None + results_type : list of ResultType, optional This parameter is *only* active when using a subclass of the BinFile that implements - a custom reader or writer. - If ``None``, then all results will be saved (node quality, demand, link flow, etc.). - Otherwise, a list of result types can be passed to limit the memory used. - network : bool, default=False - Save a new WaterNetworkModel from the description in the output binary file. Certain + a custom reader or writer, by default None. If None, then all results will be saved (node quality, + demand, link flow, etc.). Otherwise, a list of result types can be passed to limit the memory used. + network : bool, optional + Save a new WaterNetworkModel from the description in the output binary file, by default None. Certain elements may be missing, such as patterns and curves, if this is done. - energy : bool, default=False - Save the pump energy results. - statistics : bool, default=False + energy : bool, optional + Save the pump energy results, by default False. + statistics : bool, optional Save the statistics lines (different from the stats flag in the inp file) that are - automatically calculated regarding hydraulic conditions. - convert_status : bool, default=True - Convert the EPANET link status (8 values) to simpler WNTR status (3 values). By - default, this is done, and the encoded-cause status values are converted simple state + automatically calculated regarding hydraulic conditions, by default False. + convert_status : bool, optional + Convert the EPANET link status (8 values) to simpler WNTR status (3 values), by default True. + When this is done, the encoded-cause status values are converted simple stat values, instead. + Returns - ---------- - :class:`~wntr.sim.results.SimulationResults` + ------- + SimulationResults A WNTR results object will be created and added to the instance after read. """ diff --git a/wntr/epanet/toolkit.py b/wntr/epanet/toolkit.py index 8afbb7578..7e9ef1c9e 100644 --- a/wntr/epanet/toolkit.py +++ b/wntr/epanet/toolkit.py @@ -1,16 +1,6 @@ """ The wntr.epanet.toolkit module is a Python extension for the EPANET Programmers Toolkit DLLs. - -.. rubric:: Contents - -.. autosummary:: - - runepanet - ENepanet - EpanetException - ENgetwarning - """ import ctypes import os diff --git a/wntr/epanet/util.py b/wntr/epanet/util.py index 24673b2d5..5a1939bda 100644 --- a/wntr/epanet/util.py +++ b/wntr/epanet/util.py @@ -1,27 +1,5 @@ """ The wntr.epanet.util module contains unit conversion utilities based on EPANET units. - -.. rubric:: Contents - -.. autosummary:: - - FlowUnits - MassUnits - QualParam - HydParam - to_si - from_si - StatisticsType - QualType - SourceType - PressureUnits - FormulaType - ControlType - LinkTankStatus - MixType - ResultType - EN - """ import enum import logging @@ -331,11 +309,11 @@ def _to_si(self, flow_units, data, mass_units=MassUnits.mg, reaction_order=0): Parameters ---------- - flow_units : ~FlowUnits + flow_units : FlowUnits The EPANET flow units to use in the conversion data : array-like The data to be converted (scalar, array or dictionary) - mass_units : ~MassUnits + mass_units : MassUnits The EPANET mass units to use in the conversion (mg or ug) reaction_order : int The reaction order for use converting reaction coefficients @@ -404,11 +382,11 @@ def _from_si(self, flow_units, data, mass_units=MassUnits.mg, reaction_order=0): Parameters ---------- - flow_units : ~FlowUnits + flow_units : FlowUnits The EPANET flow units to use in the conversion data : array-like The SI unit data to be converted (scalar, array or dictionary) - mass_units : ~MassUnits + mass_units : MassUnits The EPANET mass units to use in the conversion (mg or ug) reaction_order : int The reaction order for use converting reaction coefficients @@ -481,21 +459,21 @@ class HydParam(enum.Enum): .. rubric:: Enum Members ========================== =================================================================== - :attr:`~Elevation` Nodal elevation - :attr:`~Demand` Nodal demand - :attr:`~HydraulicHead` Nodal head - :attr:`~Pressure` Nodal pressure - :attr:`~EmitterCoeff` Emitter coefficient - :attr:`~TankDiameter` Tank diameter - :attr:`~Volume` Tank volume - :attr:`~Length` Link length - :attr:`~PipeDiameter` Pipe diameter - :attr:`~Flow` Link flow - :attr:`~Velocity` Link velocity - :attr:`~HeadLoss` Link headloss (from start node to end node) - :attr:`~RoughnessCoeff` Link roughness (requires `darcy_weisbach` setting for conversion) - :attr:`~Energy` Pump energy - :attr:`~Power` Pump power + :attr:`Elevation` Nodal elevation + :attr:`Demand` Nodal demand + :attr:`HydraulicHead` Nodal head + :attr:`Pressure` Nodal pressure + :attr:`EmitterCoeff` Emitter coefficient + :attr:`TankDiameter` Tank diameter + :attr:`Volume` Tank volume + :attr:`Length` Link length + :attr:`PipeDiameter` Pipe diameter + :attr:`Flow` Link flow + :attr:`Velocity` Link velocity + :attr:`HeadLoss` Link headloss (from start node to end node) + :attr:`RoughnessCoeff` Link roughness (requires `darcy_weisbach` setting for conversion) + :attr:`Energy` Pump energy + :attr:`Power` Pump power ========================== =================================================================== @@ -548,7 +526,7 @@ def _to_si(self, flow_units, data, darcy_weisbach=False): Parameters ---------- - flow_units : ~FlowUnits + flow_units : FlowUnits The flow units to use in the conversion data : array-like The EPANET-units data to be converted (scalar, array or dictionary) @@ -649,7 +627,7 @@ def _from_si(self, flow_units, data, darcy_weisbach=False): Parameters ---------- - flow_units : :class:`~FlowUnits` + flow_units : FlowUnits The flow units to use in the conversion data : array-like The SI unit data to be converted (scalar, array or dictionary) diff --git a/wntr/metrics/economic.py b/wntr/metrics/economic.py index 38434aa46..db5bfac4a 100644 --- a/wntr/metrics/economic.py +++ b/wntr/metrics/economic.py @@ -1,17 +1,5 @@ """ The wntr.metrics.economic module contains economic metrics. - -.. rubric:: Contents - -.. autosummary:: - - annual_network_cost - annual_ghg_emissions - pump_power - pump_energy - pump_cost - - """ from wntr.network import Tank, Pipe, Pump, Valve import numpy as np @@ -24,7 +12,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, pump_cost=None): """ - Compute annual network cost [SOKZ12]_. + Compute annual network cost :cite:p:`sokz12`. Use the closest value from the lookup tables to compute annual cost for each component in the network. @@ -37,7 +25,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, tank_cost : pandas Series, optional Annual tank cost indexed by volume - (default values below, from [SOKZ12]_). + (default values below, from :cite:p:`sokz12`). ============= ================================ Volume (m3) Annual Cost ($/yr) @@ -52,7 +40,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, pipe_cost : pandas Series, optional Annual pipe cost per pipe length indexed by diameter - (default values below, from [SOKZ12]_). + (default values below, from :cite:p:`sokz12`). ============= ============= ================================ Diameter (in) Diameter (m) Annual Cost ($/m/yr) @@ -73,7 +61,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, prv_cost : pandas Series, optional Annual PRV valve cost indexed by diameter - (default values below, from [SOKZ12]_). + (default values below, from :cite:p:`sokz12`). ============= ============= ================================ Diameter (in) Diameter (m) Annual Cost ($/m/yr) @@ -94,7 +82,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, pump_cost : pd.Series, optional Annual pump cost indexed by maximum power input to pump - (default values below, from [SOKZ12]_). + (default values below, from :cite:p:`sokz12`). Maximum Power for a HeadPump is computed from the pump curve as follows: @@ -205,7 +193,7 @@ def annual_network_cost(wn, tank_cost=None, pipe_cost=None, prv_cost=None, def annual_ghg_emissions(wn, pipe_ghg=None): """ - Compute annual greenhouse gas emissions [SOKZ12]_. + Compute annual greenhouse gas emissions :cite:p:`sokz12`. Use the closest value in the lookup table to compute annual GHG emissions for each pipe in the network. @@ -218,7 +206,7 @@ def annual_ghg_emissions(wn, pipe_ghg=None): pipe_ghg : pandas Series, optional Annual GHG emissions indexed by pipe diameter - (default values below, from [SOKZ12]_). + (default values below, from :cite:p:`sokz12`). ============= ================================ Diameter (mm) Annualized EE (kg-CO2-e/m/yr) diff --git a/wntr/metrics/hydraulic.py b/wntr/metrics/hydraulic.py index 3d273e7fa..5b54ec8b9 100644 --- a/wntr/metrics/hydraulic.py +++ b/wntr/metrics/hydraulic.py @@ -1,18 +1,5 @@ """ The wntr.metrics.hydraulic module contains hydraulic metrics. - -.. rubric:: Contents - -.. autosummary:: - - expected_demand - average_expected_demand - water_service_availability - todini_index - modified_resilience_index - tank_capacity - entropy - """ import wntr.network import numpy as np @@ -181,7 +168,7 @@ def water_service_availability(expected_demand, demand): def todini_index(head, pressure, demand, flowrate, wn, Pstar): """ - Compute Todini index, equations from [Todi00]_. + Compute Todini index, equations from :cite:p:`todi00`. The Todini index is related to the capability of a system to overcome failures while still meeting demands and pressures at the nodes. The @@ -241,7 +228,7 @@ def todini_index(head, pressure, demand, flowrate, wn, Pstar): def modified_resilience_index(pressure, elevation, Pstar, demand=None, per_junction=True): """ - Compute the modified resilience index, equations from [JaSr08]_. + Compute the modified resilience index, equations from :cite:p:`jasr08`. The modified resilience index is the total surplus power available at demand junctions as a percentage of the total minimum required power at @@ -331,7 +318,7 @@ def tank_capacity(pressure, wn): def entropy(G, sources=None, sinks=None): """ - Compute entropy, equations from [AwGB90]_. + Compute entropy, equations from :cite:p:`awgb90`. Entropy is a measure of uncertainty in a random variable. In a water distribution network model, the random variable is diff --git a/wntr/metrics/misc.py b/wntr/metrics/misc.py index 5326e15c5..006b2e12c 100644 --- a/wntr/metrics/misc.py +++ b/wntr/metrics/misc.py @@ -1,15 +1,6 @@ """ The wntr.metrics.misc module contains metrics that do not fall into the topographic, hydraulic, water quality, water security, or economic categories. - -.. rubric:: Contents - -.. autosummary:: - - query - population - population_impacted - """ from wntr.metrics.hydraulic import average_expected_demand import logging @@ -47,7 +38,7 @@ def query(arg1, operation, arg2): def population(wn, R=0.00000876157): r""" - Compute population per node, rounded to the nearest integer [USEPA15]_. + Compute population per node, rounded to the nearest integer :cite:p:`usepa15`. .. math:: pop=\dfrac{Average\ expected\ demand}{R} diff --git a/wntr/metrics/topographic.py b/wntr/metrics/topographic.py index ef9a5d525..452cd0b2b 100644 --- a/wntr/metrics/topographic.py +++ b/wntr/metrics/topographic.py @@ -2,20 +2,6 @@ The wntr.metrics.topographic module contains topographic metrics that are not available directly with NetworkX. Functions in this module operate on a NetworkX MultiDiGraph, which can be created by calling ``G = wn.to_graph()`` - -.. rubric:: Contents - -.. autosummary:: - - terminal_nodes - bridges - central_point_dominance - spectral_gap - algebraic_connectivity - critical_ratio_defrag - valve_segments - valve_segment_attributes - """ import networkx as nx import numpy as np diff --git a/wntr/metrics/water_security.py b/wntr/metrics/water_security.py index dcef2d89c..e69073add 100644 --- a/wntr/metrics/water_security.py +++ b/wntr/metrics/water_security.py @@ -1,14 +1,5 @@ """ The wntr.metrics.water_security module contains water security metrics. - -.. rubric:: Contents - -.. autosummary:: - - mass_contaminant_consumed - volume_contaminant_consumed - extent_contaminant - """ import numpy as np import wntr.network @@ -18,7 +9,7 @@ logger = logging.getLogger(__name__) def mass_contaminant_consumed(demand, quality, detection_limit=0): - """ Mass of contaminant consumed [USEPA15]_. + """ Mass of contaminant consumed :cite:p:`usepa15`. Parameters ---------- @@ -46,7 +37,7 @@ def mass_contaminant_consumed(demand, quality, detection_limit=0): return MC def volume_contaminant_consumed(demand, quality, detection_limit=0): - """ Volume of contaminant consumed [USEPA15]_. + """ Volume of contaminant consumed :cite:p:`usepa15`. Parameters ---------- @@ -75,7 +66,7 @@ def volume_contaminant_consumed(demand, quality, detection_limit=0): def extent_contaminant(quality, flowrate, wn, detection_limit=0): """ - Extent of contaminant in the pipes [USEPA15]_. + Extent of contaminant in the pipes :cite:p:`usepa15`. Parameters ---------- diff --git a/wntr/network/base.py b/wntr/network/base.py index a7fc59cbb..c2229469f 100644 --- a/wntr/network/base.py +++ b/wntr/network/base.py @@ -1,22 +1,6 @@ """ The wntr.network.base module includes base classes for network elements and the network model. - -.. rubric:: Contents - -.. autosummary:: - - Node - Link - Registry - NodeType - LinkType - LinkStatus - AbstractModel - Subject - Observer - - """ import logging import six diff --git a/wntr/network/controls.py b/wntr/network/controls.py index 77fef95db..7838acd08 100644 --- a/wntr/network/controls.py +++ b/wntr/network/controls.py @@ -2,28 +2,6 @@ The wntr.network.controls module includes methods to define network controls and control actions. These controls modify parameters in the network during simulation. - -.. rubric:: Contents - -.. autosummary:: - - Subject - Observer - Comparison - ControlPriority - ControlCondition - TimeOfDayCondition - SimTimeCondition - ValueCondition - TankLevelCondition - RelativeCondition - OrCondition - AndCondition - BaseControlAction - ControlAction - ControlBase - Control - """ import math import enum diff --git a/wntr/network/elements.py b/wntr/network/elements.py index 63588ae8a..28e3e7fe8 100644 --- a/wntr/network/elements.py +++ b/wntr/network/elements.py @@ -2,31 +2,6 @@ The wntr.network.elements module includes elements of a water network model, including junction, tank, reservoir, pipe, pump, valve, pattern, timeseries, demands, curves, and sources. - -.. rubric:: Contents - -.. autosummary:: - - Junction - Tank - Reservoir - Pipe - Pump - HeadPump - PowerPump - Valve - PRValve - PSValve - PBValve - FCValve - TCValve - GPValve - Pattern - TimeSeries - Demands - Curve - Source - """ import numpy as np import sys diff --git a/wntr/network/io.py b/wntr/network/io.py index b8d009937..83bca2cf0 100644 --- a/wntr/network/io.py +++ b/wntr/network/io.py @@ -4,25 +4,6 @@ The wntr.network.io module includes functions that convert the water network model to other data formats, create a water network model from file, and write the water network model to a file. - -.. rubric:: Contents - -.. autosummary:: - - to_dict - from_dict - to_gis - from_gis - to_graph - write_json - read_json - write_inpfile - read_inpfile - write_geojson - read_geojson - write_shapefile - read_shapefile - """ import logging import json diff --git a/wntr/network/layer.py b/wntr/network/layer.py index 81fee23ca..cc5217f5b 100644 --- a/wntr/network/layer.py +++ b/wntr/network/layer.py @@ -1,12 +1,6 @@ """ The wntr.network.layer module includes methods to generate network layers (information that is not stored in the water network model or the graph). - -.. rubric:: Contents - -.. autosummary:: - - generate_valve_layer """ import numpy as np import pandas as pd diff --git a/wntr/network/model.py b/wntr/network/model.py index 938da1421..2e5869778 100644 --- a/wntr/network/model.py +++ b/wntr/network/model.py @@ -1,18 +1,6 @@ """ The wntr.network.model module includes methods to build a water network model. - -.. rubric:: Contents - -.. autosummary:: - - WaterNetworkModel - PatternRegistry - CurveRegistry - SourceRegistry - NodeRegistry - LinkRegistry - """ import logging from collections import OrderedDict diff --git a/wntr/network/options.py b/wntr/network/options.py index a63127675..3d1d086a5 100644 --- a/wntr/network/options.py +++ b/wntr/network/options.py @@ -7,22 +7,6 @@ that EPANET 2.2 requires. It also reorganizes certain options to better align with EPANET nomenclature. This change is not backwards compatible, particularly when trying to use pickle files with older options. - -.. rubric:: Classes - -.. autosummary:: - :nosignatures: - - Options - TimeOptions - GraphicsOptions - HydraulicOptions - ReportOptions - ReactionOptions - QualityOptions - EnergyOptions - UserOptions - """ import re import logging diff --git a/wntr/sim/aml/__init__.py b/wntr/sim/aml/__init__.py index 5a21ab6d6..287b3247d 100644 --- a/wntr/sim/aml/__init__.py +++ b/wntr/sim/aml/__init__.py @@ -1,3 +1,5 @@ +"""WNTR's algebraic modeling language module (SWIG).""" + from .expr import Var, Param, exp, log, sin, cos, tan, asin, acos, atan, inequality, sign, abs, value, ConditionalExpression from .aml import Model, ParamDict, VarDict, ConstraintDict, Constraint diff --git a/wntr/sim/aml/aml.py b/wntr/sim/aml/aml.py index 9dd442972..04e2bae60 100644 --- a/wntr/sim/aml/aml.py +++ b/wntr/sim/aml/aml.py @@ -1,3 +1,5 @@ +"""WNTR AML base classes.""" + import sys import scipy from .evaluator import Evaluator diff --git a/wntr/sim/core.py b/wntr/sim/core.py index 663b5e5a0..d0d9b30c7 100644 --- a/wntr/sim/core.py +++ b/wntr/sim/core.py @@ -1,3 +1,6 @@ +"""The core abstract and base classes for WNTR simulations. +""" + import wntr.sim.hydraulics from wntr.sim.solvers import NewtonSolver, SolverStatus import wntr.sim.results diff --git a/wntr/sim/epanet.py b/wntr/sim/epanet.py index 934324578..2fe6b9f87 100644 --- a/wntr/sim/epanet.py +++ b/wntr/sim/epanet.py @@ -1,3 +1,6 @@ +"""The EPANET simulator. +""" + from wntr.sim.core import WaterNetworkSimulator from wntr.network.io import write_inpfile import wntr.epanet.io diff --git a/wntr/sim/hydraulics.py b/wntr/sim/hydraulics.py index ca4eeb866..11c8b18a2 100644 --- a/wntr/sim/hydraulics.py +++ b/wntr/sim/hydraulics.py @@ -1,3 +1,5 @@ +"""WNTR Simulator hydraulics model.""" + import pandas as pd import numpy as np import scipy.sparse as sparse diff --git a/wntr/sim/models/__init__.py b/wntr/sim/models/__init__.py index 70ecf6a4a..c38a50956 100644 --- a/wntr/sim/models/__init__.py +++ b/wntr/sim/models/__init__.py @@ -1 +1,3 @@ +"""Elements of the WNTRSimulator model.""" + from wntr.sim.models import constants, param, var, constraint diff --git a/wntr/sim/models/constants.py b/wntr/sim/models/constants.py index a70ae966d..e7fff5d79 100644 --- a/wntr/sim/models/constants.py +++ b/wntr/sim/models/constants.py @@ -1,3 +1,5 @@ +"""Contant values used by WNTRSimulator.""" + import logging from wntr.utils.polynomial_interpolation import cubic_spline diff --git a/wntr/sim/models/constraint.py b/wntr/sim/models/constraint.py index 7ac4edf18..fc9913598 100644 --- a/wntr/sim/models/constraint.py +++ b/wntr/sim/models/constraint.py @@ -1,3 +1,5 @@ +"""Modeling constraints for the WNTRSimulator.""" + import logging from wntr.sim import aml import wntr.network diff --git a/wntr/sim/models/param.py b/wntr/sim/models/param.py index 0a2fd86dd..6aadbac71 100644 --- a/wntr/sim/models/param.py +++ b/wntr/sim/models/param.py @@ -1,3 +1,5 @@ +"""Model parameters for the WNTRSimulator.""" + import logging from wntr.sim import aml from wntr.utils.polynomial_interpolation import cubic_spline diff --git a/wntr/sim/models/utils.py b/wntr/sim/models/utils.py index c9c937582..0aec0489c 100644 --- a/wntr/sim/models/utils.py +++ b/wntr/sim/models/utils.py @@ -1,3 +1,5 @@ +"""Utilities for the WNTRSimulator model.""" + from wntr.utils.ordered_set import OrderedDict, OrderedSet from six import with_metaclass import abc diff --git a/wntr/sim/models/var.py b/wntr/sim/models/var.py index 7413f5ecd..c4b050b36 100644 --- a/wntr/sim/models/var.py +++ b/wntr/sim/models/var.py @@ -1,3 +1,5 @@ +"""Functions to add variables to the WNTRSimulator model.""" + import logging from wntr.sim import aml diff --git a/wntr/sim/network_isolation/__init__.py b/wntr/sim/network_isolation/__init__.py index 2e54f0019..159f0652a 100644 --- a/wntr/sim/network_isolation/__init__.py +++ b/wntr/sim/network_isolation/__init__.py @@ -1 +1,3 @@ +"""The network isolation package (SWIG).""" + from wntr.sim.network_isolation.network_isolation import check_for_isolated_junctions, get_long_size diff --git a/wntr/sim/results.py b/wntr/sim/results.py index 12a863988..9c9127654 100644 --- a/wntr/sim/results.py +++ b/wntr/sim/results.py @@ -1,3 +1,5 @@ +"""Simulation results.""" + import datetime import enum diff --git a/wntr/sim/solvers.py b/wntr/sim/solvers.py index 29a88ab51..bc220d0c8 100644 --- a/wntr/sim/solvers.py +++ b/wntr/sim/solvers.py @@ -1,3 +1,5 @@ +"""Generic mathematical solver classes. +""" import numpy as np import scipy.sparse as sp import warnings diff --git a/wntr/utils/doc_inheritor.py b/wntr/utils/doc_inheritor.py index b2a088b0f..372fea7f3 100644 --- a/wntr/utils/doc_inheritor.py +++ b/wntr/utils/doc_inheritor.py @@ -1,3 +1,5 @@ +"""Utilitiy for inheriting docstrings.""" + import inspect diff --git a/wntr/utils/logger.py b/wntr/utils/logger.py index afc2066f5..c81a338eb 100644 --- a/wntr/utils/logger.py +++ b/wntr/utils/logger.py @@ -1,3 +1,5 @@ +"""Fuctions to set up a default handler for WNTR that will output to the console and to wntr.log.""" + import logging logging.getLogger('wntr').addHandler(logging.NullHandler()) diff --git a/wntr/utils/ordered_set.py b/wntr/utils/ordered_set.py index 35da772a5..80079438d 100644 --- a/wntr/utils/ordered_set.py +++ b/wntr/utils/ordered_set.py @@ -1,3 +1,5 @@ +"""An ordered set implementation (like an ordered dict).""" + import sys from collections.abc import MutableSet from collections import OrderedDict diff --git a/wntr/utils/polynomial_interpolation.py b/wntr/utils/polynomial_interpolation.py index 1cf17e0a6..d78573cab 100644 --- a/wntr/utils/polynomial_interpolation.py +++ b/wntr/utils/polynomial_interpolation.py @@ -1,3 +1,5 @@ +"""Functions for a polynomial interpolation using cubic spline.""" + def cubic_spline(x1, x2, f1, f2, df1, df2): """ Method to compute the coefficients of a smoothing polynomial.