.. raw:: html
<img src="https://github.com/meghnathomas/MAGNets/blob/master/logo/MAGNets_logo.png" align="center" alt="MAGNets">
A Python package to aggregate and reduce water distribution network models
.. image:: https://img.shields.io/pypi/v/magnets.svg
:target: https://pypi.python.org/pypi/magnets
.. image:: https://pepy.tech/badge/magnets
:target: https://pepy.tech/project/magnets
:alt: PyPI - Downloads
Overview
--------
MAGNets (Model AGgregation and reduction of water distribution Networks) is a Python package designed to perform the reduction and aggregation of water distribution network models. The software is capable of reducing a network around an optional operating point and allows the user to customize which junctions they would like retained in the reduced model. MAGNets' reduction approach is based on the variable elimination method proposed by `Ulanicki et al (1996)`_.
.. _`Ulanicki et al (1996)`: https://www.researchgate.net/profile/Fernando-Martinez-Alzamora/publication/273796660_Simplification_of_Water_Distribution_Network_Models/links/550dca050cf2128741674d57/Simplification-of-Water-Distribution-Network-Models.pdf
Requirements
------------
MAGNets has been tested on Python version **3.6**, **3.7**, and **3.8**. A list of its dependencies can be found `here`_.
.. _`here`: https://github.com/meghnathomas/MAGNets/blob/master/requirements.txt
Installation: Stable release
----------------------------
Python distributions, such as Anaconda, are recommended to manage the Python environment as they already contain (or easily support the installation of) many Python packages (such as SciPy and NumPy) that are used in the MAGNets package. Instructions to download and install the Anaconda distribution can be found `at this link`_, and Anaconda for specific versions of Python can be found in the `Anaconda distribution archive`_. This `blog post`_ demonstrates how to easily change the Anaconda Python version to a version compatible with MAGNets using the command prompt.
.. _`at this link`: https://www.anaconda.com/products/distribution
.. _`Anaconda distribution archive`: https://repo.anaconda.com/archive/
.. _`blog post`: https://chris35wills.github.io/conda_python_version/
To install MAGNets, run this command in your terminal:
.. code:: python
pip install magnets
This is the preferred method to install MAGNets, as it will always install the most recent stable release.
If you don’t have pip installed, this `Python installation guide`_ can guide you through the process.
.. _`Python installation guide`: https://docs.python-guide.org/starting/installation/
Installation: From sources
--------------------------
The sources for MAGNets can be downloaded from the Github repo.
You can either clone the public repository:
.. code:: python
git clone https://github.com/meghnathomas/MAGNets
Or download the tarball:
.. code:: python
curl -OJL https://github.com/meghnathomas/magnets/tarball/master
Once you have a copy of the source, you can install it with:
.. code:: python
python setup.py install
Getting Started
---------------
Use this `jupyter notebook`_ to run some useful examples of MAGNets. Additional example codes and 12 test networks can be found in the `examples`_ and `publications`_ folders.
.. _`jupyter notebook`: https://github.com/meghnathomas/MAGNets/blob/master/examples/MAGNets_Demo.ipynb
.. _`examples`: https://github.com/meghnathomas/MAGNets/tree/master/examples
.. _`publications`: https://github.com/meghnathomas/MAGNets/tree/master/publications
**********************
Once MAGNets is installed on the system, it can be used in a projet through the means of a Python IDE. For example, to use MAGNets on Spyder, open Spyder either through the Anaconda GUI or by typing the following command in the command prompt:
.. code:: python
spyder
Open a new script and import MAGNets using the following command:
.. code:: python
import magnets as mg
The user can then call on the following function to reduce a hydraulic model of a water distribution network.
.. code:: python
wn2 = mg.reduction.reduce_model(inp_file, op_pt, nodes_to_keep, max_nodal_degree)
The parameters of the :code:`reduce_model` function are described as follows:
#. :code:`inp_file`: the EPANET-compatible .inp file of the water distribution network model.
#. :code:`op_pt`: (optional, default = 0) the operating point, or the reporting time step of the hydraulic simulation at which the non-linear headloss equations are linearized.
#. :code:`nodes_to_keep`: (optional, default = []) a list of nodes the user wishes to retain in the reduced model.
#. :code:`max_nodal_degree`: (optional, default = None) the maximum nodal degree of nodes being removed from the model. The nodal degree of a node is equal to the number of pipes incident to the node.
:code:`wn2` contains the water network model object of the reduced model. A .inp file of the reduced model is also written into the directory that contains the .inp file of the original network.
Cite Us
-------
To cite MAGNets, please use the following publication: `MAGNets: Model Reduction and Aggregation of Water Networks`_
.. _`MAGNets: Model Reduction and Aggregation of Water Networks`: https://ascelibrary.org/doi/full/10.1061/JWRMD5.WRENG-5486
::
@article{doi:10.1061/JWRMD5.WRENG-5486,
author = {Meghna Thomas and Lina Sela },
title = {MAGNets: Model Reduction and Aggregation of Water Networks},
journal = {Journal of Water Resources Planning and Management},
volume = {149},
number = {2},
pages = {06022006},
year = {2023},
doi = {10.1061/JWRMD5.WRENG-5486},
URL = {https://ascelibrary.org/doi/abs/10.1061/JWRMD5.WRENG-5486},
}
Contact
-------
Meghna Thomas - meghnathomas@utexas.edu
Lina Sela - linasela@utexas.edu
Credits
-------
This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
=======
History
=======
0.1.0 (2021-05-13)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/meghnathomas/magnets",
"name": "magnets",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "magnets",
"author": "Meghna Sarah Thomas",
"author_email": "meghnathomas@utexas.edu",
"download_url": "https://files.pythonhosted.org/packages/b5/1a/02e4b7f83693bffe68adc5de1433888099ffd1581b354e4ffb945870070a/magnets-0.1.10.tar.gz",
"platform": null,
"description": ".. raw:: html\r\n\r\n <img src=\"https://github.com/meghnathomas/MAGNets/blob/master/logo/MAGNets_logo.png\" align=\"center\" alt=\"MAGNets\">\r\n\r\nA Python package to aggregate and reduce water distribution network models\r\n\r\n.. image:: https://img.shields.io/pypi/v/magnets.svg\r\n :target: https://pypi.python.org/pypi/magnets\r\n \r\n.. image:: https://pepy.tech/badge/magnets\r\n :target: https://pepy.tech/project/magnets\r\n :alt: PyPI - Downloads\r\n\r\n\r\nOverview\r\n--------\r\n\r\nMAGNets (Model AGgregation and reduction of water distribution Networks) is a Python package designed to perform the reduction and aggregation of water distribution network models. The software is capable of reducing a network around an optional operating point and allows the user to customize which junctions they would like retained in the reduced model. MAGNets' reduction approach is based on the variable elimination method proposed by `Ulanicki et al (1996)`_.\r\n\r\n.. _`Ulanicki et al (1996)`: https://www.researchgate.net/profile/Fernando-Martinez-Alzamora/publication/273796660_Simplification_of_Water_Distribution_Network_Models/links/550dca050cf2128741674d57/Simplification-of-Water-Distribution-Network-Models.pdf\r\n\r\nRequirements\r\n------------\r\n\r\nMAGNets has been tested on Python version **3.6**, **3.7**, and **3.8**. A list of its dependencies can be found `here`_.\r\n\r\n.. _`here`: https://github.com/meghnathomas/MAGNets/blob/master/requirements.txt\r\n\r\nInstallation: Stable release\r\n----------------------------\r\n\r\nPython distributions, such as Anaconda, are recommended to manage the Python environment as they already contain (or easily support the installation of) many Python packages (such as SciPy and NumPy) that are used in the MAGNets package. Instructions to download and install the Anaconda distribution can be found `at this link`_, and Anaconda for specific versions of Python can be found in the `Anaconda distribution archive`_. This `blog post`_ demonstrates how to easily change the Anaconda Python version to a version compatible with MAGNets using the command prompt.\r\n\r\n.. _`at this link`: https://www.anaconda.com/products/distribution\r\n\r\n.. _`Anaconda distribution archive`: https://repo.anaconda.com/archive/\r\n\r\n.. _`blog post`: https://chris35wills.github.io/conda_python_version/\r\n\r\nTo install MAGNets, run this command in your terminal:\r\n\r\n.. code:: python\r\n\r\n pip install magnets\r\n\r\nThis is the preferred method to install MAGNets, as it will always install the most recent stable release.\r\n\r\nIf you don\u00e2\u20ac\u2122t have pip installed, this `Python installation guide`_ can guide you through the process.\r\n\r\n.. _`Python installation guide`: https://docs.python-guide.org/starting/installation/\r\n\r\n\r\nInstallation: From sources\r\n--------------------------\r\n\r\nThe sources for MAGNets can be downloaded from the Github repo.\r\n\r\nYou can either clone the public repository:\r\n\r\n.. code:: python\r\n\r\n git clone https://github.com/meghnathomas/MAGNets\r\n \r\nOr download the tarball:\r\n\r\n.. code:: python\r\n\r\n curl -OJL https://github.com/meghnathomas/magnets/tarball/master\r\n \r\nOnce you have a copy of the source, you can install it with:\r\n\r\n.. code:: python\r\n\r\n python setup.py install\r\n \r\n\r\nGetting Started\r\n---------------\r\n\r\nUse this `jupyter notebook`_ to run some useful examples of MAGNets. Additional example codes and 12 test networks can be found in the `examples`_ and `publications`_ folders.\r\n\r\n.. _`jupyter notebook`: https://github.com/meghnathomas/MAGNets/blob/master/examples/MAGNets_Demo.ipynb\r\n.. _`examples`: https://github.com/meghnathomas/MAGNets/tree/master/examples\r\n.. _`publications`: https://github.com/meghnathomas/MAGNets/tree/master/publications\r\n\r\n**********************\r\n\r\nOnce MAGNets is installed on the system, it can be used in a projet through the means of a Python IDE. For example, to use MAGNets on Spyder, open Spyder either through the Anaconda GUI or by typing the following command in the command prompt:\r\n\r\n.. code:: python\r\n\r\n spyder\r\n \r\nOpen a new script and import MAGNets using the following command:\r\n\r\n.. code:: python\r\n\r\n import magnets as mg\r\n\r\nThe user can then call on the following function to reduce a hydraulic model of a water distribution network. \r\n\r\n.. code:: python\r\n\r\n wn2 = mg.reduction.reduce_model(inp_file, op_pt, nodes_to_keep, max_nodal_degree)\r\n\r\nThe parameters of the :code:`reduce_model` function are described as follows:\r\n\r\n#. :code:`inp_file`: the EPANET-compatible .inp file of the water distribution network model.\r\n\r\n#. :code:`op_pt`: (optional, default = 0) the operating point, or the reporting time step of the hydraulic simulation at which the non-linear headloss equations are linearized.\r\n\r\n#. :code:`nodes_to_keep`: (optional, default = []) a list of nodes the user wishes to retain in the reduced model.\r\n\r\n#. :code:`max_nodal_degree`: (optional, default = None) the maximum nodal degree of nodes being removed from the model. The nodal degree of a node is equal to the number of pipes incident to the node.\r\n\r\n:code:`wn2` contains the water network model object of the reduced model. A .inp file of the reduced model is also written into the directory that contains the .inp file of the original network.\r\n\r\nCite Us\r\n-------\r\nTo cite MAGNets, please use the following publication: `MAGNets: Model Reduction and Aggregation of Water Networks`_\r\n\r\n.. _`MAGNets: Model Reduction and Aggregation of Water Networks`: https://ascelibrary.org/doi/full/10.1061/JWRMD5.WRENG-5486\r\n\r\n::\r\n\r\n @article{doi:10.1061/JWRMD5.WRENG-5486,\r\n author = {Meghna Thomas and Lina Sela },\r\n title = {MAGNets: Model Reduction and Aggregation of Water Networks},\r\n journal = {Journal of Water Resources Planning and Management},\r\n volume = {149},\r\n number = {2},\r\n pages = {06022006},\r\n year = {2023},\r\n doi = {10.1061/JWRMD5.WRENG-5486},\r\n URL = {https://ascelibrary.org/doi/abs/10.1061/JWRMD5.WRENG-5486},\r\n }\r\n\r\nContact\r\n-------\r\nMeghna Thomas - meghnathomas@utexas.edu\r\n\r\nLina Sela - linasela@utexas.edu\r\n\r\nCredits\r\n-------\r\n\r\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\r\n\r\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\r\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\r\n\r\n\r\n=======\r\nHistory\r\n=======\r\n\r\n0.1.0 (2021-05-13)\r\n------------------\r\n\r\n* First release on PyPI.\r\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "A Python package to aggregate and reduce water distribution network models",
"version": "0.1.10",
"project_urls": {
"Homepage": "https://github.com/meghnathomas/magnets"
},
"split_keywords": [
"magnets"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b51a02e4b7f83693bffe68adc5de1433888099ffd1581b354e4ffb945870070a",
"md5": "fb67d4be2ff48b5d04cfd175c4703abc",
"sha256": "7a2bf662c4826664ecdb432cf8ebd2bde83474425d812f88f4cc771170c4b909"
},
"downloads": -1,
"filename": "magnets-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "fb67d4be2ff48b5d04cfd175c4703abc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19561,
"upload_time": "2024-04-26T22:04:01",
"upload_time_iso_8601": "2024-04-26T22:04:01.362019Z",
"url": "https://files.pythonhosted.org/packages/b5/1a/02e4b7f83693bffe68adc5de1433888099ffd1581b354e4ffb945870070a/magnets-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 22:04:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "meghnathomas",
"github_project": "magnets",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "magnets"
}
JSON
