mesas 2.0.0a1__tar.gz

mesas-2.0.0a1/.gitignore

@@ -0,0 +1,41 @@
+# Build artifacts
+build/
+builddir/
+dist/
+mesas.egg-info/
+*.so
+*.pyc
+__pycache__/
+
+# Editor/IDE
+*.swo
+*.swp
+/.idea/
+/.vscode/
+/.claude/
+
+# Project-specific excludes
+misc/
+/mesas/junk/
+/mesas/dev/
+/doc/_build/
+*/_build/*
+examples/benchmark/Ciaran/
+examples/miniLEO
+debug/
+
+# Generated files
+*.log
+test/test.log
+test/*.pdf
+examples/Archive.zip
+examples/data_with_results.csv
+test/MESASct.py
+.coverage
+*.egg-info/
+.pytest_cache/
+
+# Hypothesis property-testing cache
+.hypothesis/
+.ruff_cache/
+.DS_Store

mesas-2.0.0a1/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file, and cite the accompanying paper (see preferred-citation)."
+type: software
+title: "mesas.py: Multiscale Estimation of StorAge Selection"
+authors:
+  - family-names: "Harman"
+    given-names: "Ciaran J."
+    orcid: "https://orcid.org/0000-0002-3185-002X"
+    affiliation: "Johns Hopkins University"
+  - family-names: "Xu Fei"
+    given-names: "Esther"
+    affiliation: "Johns Hopkins University"
+repository-code: "https://github.com/charman2/mesas"
+url: "https://mesas.readthedocs.io/"
+license: MIT
+preferred-citation:
+  type: article
+  title: "mesas.py v1.0: a flexible Python package for modeling solute transport and transit times using StorAge Selection functions"
+  authors:
+    - family-names: "Harman"
+      given-names: "Ciaran J."
+      orcid: "https://orcid.org/0000-0002-3185-002X"
+      affiliation: "Johns Hopkins University"
+    - family-names: "Xu Fei"
+      given-names: "Esther"
+      affiliation: "Johns Hopkins University"
+  journal: "Geoscientific Model Development"
+  volume: 17
+  start: 477
+  end: 495
+  year: 2024
+  doi: "10.5194/gmd-17-477-2024"

mesas-2.0.0a1/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ciaran J. Harman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

mesas-2.0.0a1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: mesas
+Version: 2.0.0a1
+Summary: MESAS - Multiscale Estimation of StorAge Selection.
+Project-URL: homepage, https://mesas.readthedocs.io/
+Project-URL: documentation, https://mesas.readthedocs.io/
+Project-URL: repository, https://github.com/charman2/mesas
+Author: Ciaran J. Harman
+Author-email: charman1@jhu.edu
+Maintainer: Ciaran J. Harman
+Maintainer-email: charman1@jhu.edu
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: SAS,Storage selection functions,hydrology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: matplotlib
+Requires-Dist: numba
+Requires-Dist: numpy>1.22
+Requires-Dist: pandas
+Requires-Dist: scipy
+Provides-Extra: docs
+Requires-Dist: sphinx-copybutton; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: estimation
+Requires-Dist: scikit-learn; extra == 'estimation'
+Provides-Extra: test
+Requires-Dist: hypothesis; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: scikit-learn; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mesas.py
+
+StorAge Selection is a theoretical framework for modeling transport through control volumes. It is appropriate if you are interested a system that can be treated as a single control volume (or a collection of such), and wish to make minimal assumptions about the internal organization of the transport. SAS assumes that the material leaving a system is some combination of the material that entered at earlier times. This can be useful for constructing simple models of very complicated flow systems, and for inferring the emergent transport properties of a system from tracer data.
+
+For more information see the free HydroLearn course: [Tracers and transit times in time-variable hydrologic systems: A gentle introduction to the StorAge Selection (SAS) approach](https://edx.hydrolearn.org/courses/course-v1:JHU+570.412+Sp2020)
+
+## Installation
+
+### Stable release (v1.0, Fortran)
+
+The current stable release on conda-forge is the older Fortran-based v1.0:
+
+    conda install -c conda-forge mesas
+
+This installs any additional dependencies at the same time.
+
+### v2.0 (pure Python, in beta)
+
+Version 2.0 is a pure Python reimplementation whose numerical solver is
+JIT-compiled with [Numba](https://numba.pydata.org/) -- no Fortran compiler
+needed. It is currently in beta. Install the latest development version from
+source:
+
+    git clone https://github.com/charman2/mesas.git
+    cd mesas
+    pip install -e .
+
+Further instructions can be found here: https://mesas.readthedocs.io/en/latest/installation.html
+
+## Documentation
+
+Documentation for the code is available here: https://mesas.readthedocs.io/en/latest/
+
+## Citation
+
+If you use mesas.py in your research, please cite:
+
+Harman, C. J. and Xu Fei, E.: mesas.py v1.0: a flexible Python package for modeling solute transport and transit times using StorAge Selection functions, Geosci. Model Dev., 17, 477-495, https://doi.org/10.5194/gmd-17-477-2024, 2024.
+
+[![DOI](https://zenodo.org/badge/183813641.svg)](https://zenodo.org/badge/latestdoi/183813641)

mesas-2.0.0a1/README.md

@@ -0,0 +1,40 @@
+# mesas.py
+
+StorAge Selection is a theoretical framework for modeling transport through control volumes. It is appropriate if you are interested a system that can be treated as a single control volume (or a collection of such), and wish to make minimal assumptions about the internal organization of the transport. SAS assumes that the material leaving a system is some combination of the material that entered at earlier times. This can be useful for constructing simple models of very complicated flow systems, and for inferring the emergent transport properties of a system from tracer data.
+
+For more information see the free HydroLearn course: [Tracers and transit times in time-variable hydrologic systems: A gentle introduction to the StorAge Selection (SAS) approach](https://edx.hydrolearn.org/courses/course-v1:JHU+570.412+Sp2020)
+
+## Installation
+
+### Stable release (v1.0, Fortran)
+
+The current stable release on conda-forge is the older Fortran-based v1.0:
+
+    conda install -c conda-forge mesas
+
+This installs any additional dependencies at the same time.
+
+### v2.0 (pure Python, in beta)
+
+Version 2.0 is a pure Python reimplementation whose numerical solver is
+JIT-compiled with [Numba](https://numba.pydata.org/) -- no Fortran compiler
+needed. It is currently in beta. Install the latest development version from
+source:
+
+    git clone https://github.com/charman2/mesas.git
+    cd mesas
+    pip install -e .
+
+Further instructions can be found here: https://mesas.readthedocs.io/en/latest/installation.html
+
+## Documentation
+
+Documentation for the code is available here: https://mesas.readthedocs.io/en/latest/
+
+## Citation
+
+If you use mesas.py in your research, please cite:
+
+Harman, C. J. and Xu Fei, E.: mesas.py v1.0: a flexible Python package for modeling solute transport and transit times using StorAge Selection functions, Geosci. Model Dev., 17, 477-495, https://doi.org/10.5194/gmd-17-477-2024, 2024.
+
+[![DOI](https://zenodo.org/badge/183813641.svg)](https://zenodo.org/badge/latestdoi/183813641)

mesas-2.0.0a1/doc/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

mesas-2.0.0a1/doc/concepts.rst

@@ -0,0 +1,128 @@
+.. _concepts:
+
+========
+Concepts
+========
+
+This page introduces the StorAge Selection (SAS) framework at a level
+appropriate for users of the package. For the full mathematical
+treatment, see `Harman (2015) <https://doi.org/10.1002/2014WR015707>`_
+and `Benettin et al. (2022) <https://doi.org/10.5194/gmd-15-3881-2022>`_
+and `Harman and Xu Fei (2024) <https://gmd.copernicus.org/articles/17/477/2024/>`_.
+
+What is StorAge Selection?
+==========================
+
+StorAge Selection (SAS) is a framework for modeling transport through a
+control volume — a catchment, a soil column, a lake, or any system
+where fluid enters, is stored, and eventually leaves.
+
+The key idea is simple: **at each moment in time, the water leaving a
+system is a mixture of water that entered at different times in the
+past.** The SAS function describes *which ages of water are
+preferentially selected for discharge*.
+
+Age-ranked storage
+==================
+
+The foundation of SAS is the concept of **age-ranked storage**. At any
+time :math:`t`, the water in storage can be sorted by how long it has been
+in the system. We define:
+
+.. math::
+
+    S_T(T, t) = \int_0^T s_T(\tau, t)\, d\tau
+
+where :math:`s_T(\tau, t)` is the density of water of age :math:`\tau`
+in storage at time :math:`t`, and :math:`S_T(T, t)` is the cumulative
+storage up to age :math:`T`. The total storage is
+:math:`S(t) = S_T(\infty, t)`.
+
+The SAS function
+================
+
+The **SAS function** :math:`\Omega_Q(S_T, t)` is a cumulative
+distribution function that maps age-ranked storage to cumulative
+probability:
+
+.. math::
+
+    \Omega_Q(S_T, t) = P(\text{discharged water has age-ranked storage} \leq S_T)
+
+When :math:`\Omega_Q` is a straight line from 0 to :math:`S(t)`, all
+ages of water are equally likely to be discharged — this is the
+**well-mixed** case. When :math:`\Omega_Q` rises steeply at small
+:math:`S_T`, young water is preferentially discharged. When it rises
+steeply near :math:`S(t)`, old water is preferred.
+
+The backward transit time distribution for outflow :math:`Q` is:
+
+.. math::
+
+    p_Q(T, t) = \frac{\partial \Omega_Q}{\partial S_T} \cdot s_T(T, t)
+
+Types of SAS functions
+======================
+
+MESAS supports several types of SAS functions:
+
+**Piecewise-linear**
+    Defined by breakpoints in :math:`(S_T, P)` space. The simplest is a
+    uniform distribution: ``"ST": [0, S_max]``. Adding more breakpoints
+    creates more complex shapes.
+
+**Gamma distribution**
+    A flexible one-parameter family. The shape parameter :math:`a`
+    controls whether young water (:math:`a < 1`) or intermediate-aged
+    water (:math:`a > 1`) is preferentially discharged.
+    Specified with ``"func": "gamma"``.
+
+**Beta distribution**
+    Defined over a finite interval, useful when total storage volume is
+    known. Has two shape parameters :math:`a` and :math:`b`.
+    Specified with ``"func": "beta"``.
+
+**Kumaraswamy distribution**
+    Similar to the beta but with a closed-form CDF, making it
+    computationally efficient.
+    Specified with ``"func": "kumaraswamy"``.
+
+All distribution-based SAS functions accept ``loc`` and ``scale``
+parameters that shift and stretch the distribution along the
+:math:`S_T` axis.
+
+Solute transport
+================
+
+Once the water fluxes are solved, solute transport follows
+directly. The concentration of water of a given age in storage
+determines the concentration of the outflow:
+
+.. math::
+
+    C_Q(t) = \int_0^\infty \frac{m_T(T,t)}{s_T(T,t)} \, p_Q(T,t) \, dT
+
+where :math:`m_T(T,t)` is the age-ranked solute mass in storage.
+
+MESAS also supports:
+
+- **First-order reactions** via ``k1`` and ``C_eq`` parameters
+- **Evapoconcentration** via the ``alpha`` parameter
+- **Multiple solutes** tracked simultaneously
+
+Time-varying parameters
+========================
+
+Any SAS function or solute parameter can be made time-varying by
+setting its value to a string that names a column in the input
+DataFrame. For example, setting ``"scale": "S_0"`` in a gamma
+specification causes the scale parameter to be read from the ``"S_0"``
+column at each timestep.
+
+Further reading
+===============
+
+- `Harman (2015) <https://doi.org/10.1002/2014WR015707>`_ — Original SAS theory paper
+- `Harman and Xu Fei (2024) <https://gmd.copernicus.org/articles/17/477/2024/>`_ — Unified framework for age and transit time distributions
+- `Benettin et al. (2022) <https://doi.org/10.5194/gmd-15-3881-2022>`_ — MESAS model description paper (GMD)
+- `HydroLearn course <https://edx.hydrolearn.org/courses/course-v1:JHU+570.412+Sp2020>`_ — Free online course on SAS theory

mesas-2.0.0a1/doc/conf.py

@@ -0,0 +1,80 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+
+# Make the package importable for autodoc
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -----------------------------------------------------
+
+project = "MESAS"
+copyright = "2019–2026, Ciaran J. Harman"
+author = "Ciaran J. Harman"
+
+# Pull version from pyproject.toml metadata
+try:
+    from importlib.metadata import version as _get_version
+
+    release = _get_version("mesas")
+except Exception:
+    release = "dev"
+version = release
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+pygments_style = "sphinx"
+
+# -- Autodoc configuration ---------------------------------------------------
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+}
+
+# -- Napoleon (NumPy docstring) configuration --------------------------------
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "logo_only": False,
+    "prev_next_buttons_location": "bottom",
+    "style_nav_header_background": "#1E74AE",
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": False,
+    "titles_only": False,
+}
+html_static_path = ["_static"]
+
+# -- Options for intersphinx -------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+}

mesas-2.0.0a1/doc/config.rst

@@ -0,0 +1,55 @@
+.. _config:
+
+=====================
+Configuring the model
+=====================
+
+To run `mesas.py` the user must provide some information about how the model is to be configured. First, at least one SAS function must be specified. In addition you may wish to provide information about solutes to be transported through the system, and/or modify the default model options.
+
+The recommended way of providing configuration data is in a text file formatted using the `JSON standard <https://www.json.org/json-en.html>`_. Typically this file is called something like ``config.json``. The contents look very much like a python ``dict``, with some differences. A minimal example of a configuration file is a text file containing the following text:
+
+.. code-block:: json
+
+    {
+    "sas_specs":{
+        "Flux out":{
+            "SAS fun":{
+                "ST": [0, 100]
+                }
+            }
+        }
+    }
+
+
+This specifies a single uniform SAS function between 0 and 100 associated with the flux named ``"Flux out"``.
+
+`mesas.py` looks for three top-level entries in the file:
+
+* ``"sas_specs"``: spcification of the SAS functions (see :ref:`sasspec`)
+* ``"solute_parameters"``: information about solutes to be transported through the system (see :ref:`solspec`)
+* ``"options"``: optional arguments for customizing the model run (see :ref:`options`)
+
+For more information click the links above. Here is an example of the contents of a ``config.json`` file that uses all three of these top-level fields.
+
+.. code-block:: json
+
+    {
+    "sas_specs":{
+        "Flux out":{
+            "SAS fun":{
+                "ST": [0, 100]
+                }
+            }
+        },
+
+    "solute_parameters":{
+        "solute A":{
+            "C_old": 0.5
+            }
+        },
+
+    "options":{
+        "dt": 3600
+        }
+    }
+

mesas-2.0.0a1/doc/functions.rst

@@ -0,0 +1,6 @@
+SAS Functions
+=============
+
+.. automodule:: mesas.sas.functions
+    :members:
+    :exclude-members: kumaraswamy_gen, kumaraswamy

mesas-2.0.0a1/doc/index.rst

@@ -0,0 +1,77 @@
+.. MESAS documentation master file, created by sphinx-quickstart on Thu Sep 12 19:57:56 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
+
+=====
+MESAS
+=====
+Multiscale Estimation of StorAge Selection functions
+
+
+What are StorAge Selection functions?
+-------------------------------------
+
+StorAge Selection is a theoretical framework for modeling transport through control volumes. It is appropriate if you are interested a system that can be treated as a single control volume (or a collection of such), and wish to make minimal assumptions about the internal organization of the transport. SAS assumes that the material leaving a system is some combination of the material that entered at earlier times. This can be useful for constructing simple models of very complicated flow systems, and for inferring the emergent transport properties of a system from tracer data.
+
+SAS is a very general framework -- at heart, it is composed of two parts: a way of keeping track of changes in the age structure of the 'population' of fluid parcels in a system, and a rule (or rules) that determines how that age structure changes. By using tracers to investigate what rule best mimics the behaviour of a given system, we can learn important information about that system -- most directly, something about the volume of tracer-transporting fluid that is actively 'turning over'. SAS is a generalization of commonly-used transit time theory to the case where fluxes vary in time, and there may be more than one outflow (e.g. discharge and ET).
+
+For more information see the free HydroLearn course: `Tracers and transit times in time-variable hydrologic systems: A gentle introduction to the StorAge Selection (SAS) approach <https://edx.hydrolearn.org/courses/course-v1:JHU+570.412+Sp2020>`_
+
+What is mesas.py?
+-----------------
+
+The package will eventually include a number of component tools for building SAS models and using them to analyze tracer data.
+
+Currently the main repository codebase includes three submodules:
+
+mesas.sas
+     The main submodule for building and running SAS models
+mesas.utils
+     Tools for manipulating SAS model input data and results
+mesas.utils.vis
+     Visualization of SAS model results
+
+I hope to expand these in the future, and welcome contributors through the `GitHub repository <https://github.com/charman2/mesas>`_
+
+Support, bugs, suggestions, etc.
+--------------------------------
+If you find a bug please open an issue on GitHub here: https://github.com/charman2/mesas/issues
+
+You can also use the issue tracer to make suggestions to improve the code.
+
+If you need further help using the code or interpreting the results, please get in touch: charman1 at jhu dot edu
+
+
+Table of contents
+-----------------
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started
+
+   installation
+   quickstart
+   concepts
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User guide
+
+   inputs
+   config
+   sasspec
+   solspec
+   options
+   results
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   functions.rst
+   specs.rst
+   model.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`