MSX updates

* Move library to new directory
* Updates to documentation
* New ipynb demo
* various bug fixes

MANIFEST.in

@@ -8,5 +8,5 @@ include wntr/sim/aml/numpy.i
 include wntr/sim/network_isolation/network_isolation*
 include wntr/sim/network_isolation/numpy.i
 include wntr/tests/networks_for_testing/*.inp
-include wntr/msx/_library_data/*.json
-include wntr/msx/_library_data/*.msx
+include wntr/library/msx/*.json
+include wntr/library/msx/*.msx

documentation/advancedsim.rst

@@ -252,15 +252,17 @@ The solution for :math:`u` and :math:`v` is then returned and printed to four si
 Building MSX models
 -------------------
 
-The following two examples illustrate how to build :class:`~wntr.msx.model.MsxModel` objects in WNTR
+The following two examples illustrate how to build :class:`~wntr.msx.model.MsxModel` objects in WNTR.
+There is also a jupyter notebook in the examples/demos source directory called multisource-cl-decay.ipynb
+that demonstrates this process with Net3.
 
 .. _msx_example1_lead:
 
 Plumbosolvency of lead
 ^^^^^^^^^^^^^^^^^^^^^^
 
 The following example builds the plumbosolvency of lead model 
-described in [BWMS20]_. The model represents plumbosolvency 
+described in :cite:p:`bwms20`. The model represents plumbosolvency 
 in lead pipes within a dwelling.
 The MSX model is built without a specific water network model in mind.
 
@@ -332,7 +334,7 @@ Type             Name             Value            Units
 ---------------  ---------------  ---------------  ---------------------------------  ------------------------
 constant         :math:`M`        0.117            :math:`\mathrm{μg~m^{-2}~s^{-1}}`  desorption rate
 constant         :math:`E`        140.0            :math:`\mathrm{μg~L^{-1}}`         saturation level
-parameter        :math:`F`        0                `n/a`                              is pipe made of lead?
+parameter        :math:`F`        0                `flag`                             is pipe made of lead?
 ===============  ===============  ===============  =================================  ========================
 
 These are added to the MsxModel using the using the 
@@ -344,7 +346,18 @@ methods.
 
     >>> msx.add_constant("M", value=0.117, note="Desorption rate (ug/m^2/s)", units="ug * m^(-2) * s^(-1)")
     >>> msx.add_constant("E", value=140.0, note="saturation/plumbosolvency level (ug/L)", units="ug/L")
-    >>> msx.add_parameter("F", global_value=0, note="determines which pipes have reactions")
+    >>> msx.add_parameter("F", global_value=0, note="determines which pipes are made of lead")
+
+If the value of one of these needs to be modified, then it can be accessed and modified as an object
+in the same manner as other WNTR objects.
+
+.. doctest::
+
+  >>> M = msx.reaction_system.constants['M']
+  >>> M.value = 0.118
+  >>> M
+  Constant(name='M', value=0.118, units='ug * m^(-2) * s^(-1)', note='Desorption rate (ug/m^2/s)')
+
 
 Note that all models must include both pipe and tank reactions.
 Since the model only has reactions within 
@@ -374,16 +387,23 @@ method.
 .. doctest::
 
     >>> msx.add_reaction("PB2", "pipe", "RATE", expression="F * Av * M * (E - PB2) / E")
+
+
+If the species is saved as an object, as was done above, then it can be passed instead of the species name.
+
+.. doctest::
+
     >>> msx.add_reaction(PB2, "tank", "rate", expression="0")
 
+
 Arsenic oxidation and adsorption
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This example models monochloramine oxidation of arsenite/arsenate and wall
-adsorption/desorption, as given in section 3 of the EPANET-MSX user manual [SRU23]_.
+adsorption/desorption, as given in section 3 of the EPANET-MSX user manual :cite:p:`shang2023`.
 
 The system of equations for the reaction in pipes is given in Eq. (2.4) through (2.7)
-in [SRU23]_. This is a simplified model, taken from [GSCL94]_. 
+in :cite:p:`shang2023`. This is a simplified model, taken from :cite:p:`gscl94`. 
 
 .. math::
 

documentation/references.bib

@@ -39,6 +39,18 @@ @misc{bieni19
     year = "2019"
 }
 
+@article{bwms20,
+    author="Burkhardt, J. B. and Woo, J. and Mason, J. and Shang, F. and Triantafyllidou, S. and Schock, M.R., and Lytle, D., and Murray, R." ,
+    year = 2020,
+    title="Framework for Modeling Lead in Premise Plumbing Systems Using EPANET",
+    journal="Journal of Water Resources Planning and Management", 
+    volume=146,
+    number=12,
+    doi="10.1061/(asce)wr.1943-5452.0001304",
+    eprint="33627937",
+    eprintclass="PMID"
+}
+
 @book{crlo02,
     author = "Crowl, D.A. and Louvar, J.F.",
     address = "Upper Saddle River, NJ",
@@ -79,6 +91,15 @@ @misc{gacl18
     year = "2018"
 }
 
+@article{gscl94,
+    author = "Gu, B. and Schmitt, J. and Chen, Z. and Liang, L. and McCarthy, J.F.",
+    title = "Adsorption and desorption of natural organic matter on iron oxide: mechanisms and models",
+    year = "1994",
+    journal = "Environmental Science and Technology",
+    volume = "28",
+    pages = "38--46"
+}
+
 @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",

documentation/resultsobject.rst

@@ -206,3 +206,19 @@ For example, DataFrames can be saved to Excel files using:
 
 .. note:: 
    The Pandas method ``to_excel`` requires the Python package **openpyxl** :cite:p:`gacl18`, which is an optional dependency of WNTR.
+
+
+Water quality results
+---------------------
+Water quality metrics are stored under the 'quality' key of the node and link results
+if the EpanetSimulator is used. The units of the quality results depend on the quality
+parameter that is used (see :ref:`_water_quality_simulation`) and can be the age,
+concentration, or the fraction of water that belongs to a tracer. If the parameter
+is set to 'NONE', then the quality results will be zero. 
+
+The quality of a link is equal to the average across the length of the link. The quality
+at a node is the instantaneous value.
+
+When using the EPANET-MSX water quality model, each species is given its own key in the
+node and link results objects, and the 'quality' results still references the EPANET
+water quality results.

documentation/waterquality.rst

@@ -18,10 +18,10 @@ Water quality simulation
 
 Water quality simulations can only be run using the EpanetSimulator. 
 This includes the ability to run 
-EPANET 2.00.12 Programmer's Toolkit [Ross00]_ or
-EPANET 2.2.0 Programmer's Toolkit [RWTS20]_ for single species, water age, and tracer analysis.
+EPANET 2.00.12 Programmer's Toolkit :cite:p:`ross00` or
+EPANET 2.2.0 Programmer's Toolkit :cite:p:`rwts20` for single species, water age, and tracer analysis.
 
-WNTR also includes the ability to run EPANET-MSX 2.0 [SRU23]_, see :ref:`msx_water_quality` for more information.
+WNTR also includes the ability to run EPANET-MSX 2.0 :cite:p:`shang2023`, see :ref:`msx_water_quality` for more information.
 
 After defining water quality options and sources (described in the :ref:`wq_options` and :ref:`sources` sections below), a hydraulic and water quality simulation 
 using the EpanetSimulator is run using the following code:

documentation/waterquality_msx.rst

@@ -18,13 +18,13 @@
 Multi-species water quality simulation
 =======================================
 
-The EpanetSimulator can use EPANET-MSX 2.0 [SRU23]_ to run 
+The EpanetSimulator can use EPANET-MSX 2.0 :cite:p:`shang2023` to run 
 multi-species water quality simulations.
 Additional multi-species simulation options are discussed in :ref:`advanced_simulation`.
 
 A multi-species analysis is run if a :class:`~wntr.msx.model.MsxModel` is added to the 
 :class:`~wntr.network.model.WaterNetworkModel`, as shown below.
-In this example, the MsxModel is created from a MSX file (see [SRU23]_ for more information on file format).
+In this example, the MsxModel is created from a MSX file (see :cite:p:`shang2023` for more information on file format).
 
 .. doctest::
 
@@ -80,9 +80,9 @@ WNTR also contains a library of MSX models that are accessed through the
 :class:`~wntr.msx.library.ReactionLibrary`.
 This includes the following models:
 
-* `Arsenic oxidation/adsorption <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/arsenic_chloramine.json>`_ [SRU23]_
+* `Arsenic oxidation/adsorption <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/arsenic_chloramine.json>`_ :cite:p:`shang2023`
 * `Batch chloramine decay <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/batch_chloramine_decay.json>`_ 
-* `Lead plumbosolvency <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/lead_ppm.json>`_ [BWMS20]_
+* `Lead plumbosolvency <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/lead_ppm.json>`_ :cite:p:`bwms20`
 * `Nicotine/chlorine reaction <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/nicotine.json>`_ 
 * `Nicotine/chlorine reaction with reactive intermediate <https://github.com/dbhart/WNTR/blob/msx/wntr/msx/_library_data/nicotine_ri.json>`_ 
 

examples/data/Net3_arsenic.msx

@@ -48,6 +48,7 @@ Arsenic Oxidation/Adsorption Example
   ;Initial conditions (= 0 if not specified here)
   NODE    River AS3   10.0
   NODE    River NH2CL 2.5
+  NODE    Lake  NH2CL 2.5
 
 [REPORT]
   NODES   All                ;Report results for nodes C and D