psdm 0.1.0__tar.gz

psdm-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.xlsx binary

psdm-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+docs/_build/
+docs/api/generated/
+.DS_Store
+~$*.xlsx

psdm-0.1.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    install:
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --group docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

psdm-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-14
+
+First release.
+
+### Added
+
+- `psdm.simulate`: multi-component PSDM with NOM fouling, rewritten from the US EPA code.
+- `psdm.Column` and `psdm.Compound` input objects with unit conversion.
+- `psdm.fit_freundlich` and `psdm.fit_isotherm` for parameter estimation.
+- `psdm.io.read_excel` for the EPA PSDM Excel template.
+- Validation tests against AdDesignS and the original EPA implementation.
+- `scripts/benchmark.py` and `benchmarks/report.html`: case-by-case comparison with the
+  original EPA PSDM code (11 cases).
+- `psdm.estimate_capacity`: Freundlich `K` from breakthrough data for an assumed `1/n`
+  (upstream `__calculate_capacity`), with breakthrough detection and logistic/linear
+  extrapolation. Validated against the EPA code.
+- `psdm.model_uncertainty`: uncertainty bands from ± perturbations of capacity, `K`, `1/n`,
+  influent concentration, mass, flow rate, `kf`, `dp` and `ds` (upstream `model_uncertainty`).
+- `psdm.fit_surface_diffusivity`: grid search plus refinement for `ds` (upstream
+  `run_psdm_dsfit`).
+- `psdm.fullscale`: `mesh_diameter`, `build_large_scale_column`, `rssct_design`,
+  `specific_throughput`, `replacement_interval` (2024 US EPA PFAS MCLs and hazard index) and
+  `staggered_bed_interval` (upstream `PSDM_extra.py` and `PSDM_tools.py`).
+
+### Fixed relative to the EPA code
+
+- The surface-diffusivity reference includes the Freundlich `K` term.
+- The PFBS term is added to the hazard index in the replacement interval.
+- Longer EBCTs in `specific_throughput` enlarge the bed instead of shrinking it.
+- RSSCT particle diameters given with units are converted correctly.
+
+### Still not ported
+
+- Lead–lag configurations (`lead_lag_class.py`, needs the `ixpy` package).
+- The equilibrium column model (`ecm.py`).
+- `run_all_smart` fouling-factor estimates and `break_type='force'` breakthrough input.
+
+[Unreleased]: https://github.com/zohoMatt/psdm/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/zohoMatt/psdm/releases/tag/v0.1.0

psdm-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Development uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                      # create .venv with the package and dev tools
+uv run pytest                # tests
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run --group docs sphinx-build -W -b html docs docs/_build/html   # docs
+```
+
+## Reference data
+
+`tests/data/reference/*.csv` are breakthrough curves computed with the original US EPA code
+(`Water_Treatment_Models` commit `3f514c2`). To regenerate them, check out that repository and
+run
+
+```bash
+uv run --no-project --with numpy --with scipy --with pandas --with openpyxl --with matplotlib \
+    python tests/data/reference/generate.py <Water_Treatment_Models>/PSDM tests/data/reference
+```
+
+`tests/data/addesigns_test.xlsx` holds AdDesignS output for the same case and is the
+independent check.
+
+## Releasing
+
+1. Update `__version__` in `src/psdm/__init__.py` and the changelog.
+2. Commit, tag `vX.Y.Z`, push, and publish a GitHub release for the tag.
+3. The `Release` workflow tests, builds and uploads to PyPI via trusted publishing.

psdm-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Matt Zuo
+
+This project is a rewrite of the Python PSDM code by Jonathan Burkhardt, Levi Haupert,
+Boris Datsov and colleagues at the US Environmental Protection Agency
+(https://github.com/USEPA/Water_Treatment_Models), itself released under the MIT License,
+and is based on the AdDesignS(TM) PSDM by D.R. Hokanson, D.W. Hand, J.C. Crittenden,
+T.N. Rogers and E.J. Oman (Michigan Technological University).
+
+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.

psdm-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: psdm
+Version: 0.1.0
+Summary: Pore and Surface Diffusion Model (PSDM) for fixed-bed granular activated carbon adsorbers
+Project-URL: Documentation, https://psdm.readthedocs.io
+Project-URL: Source, https://github.com/zohoMatt/psdm
+Project-URL: Issues, https://github.com/zohoMatt/psdm/issues
+Project-URL: Changelog, https://github.com/zohoMatt/psdm/blob/main/CHANGELOG.md
+Author: Matt Zuo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: GAC,PFAS,PSDM,activated carbon,adsorption,water treatment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.0; extra == 'excel'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# psdm
+
+[![CI](https://github.com/zohoMatt/psdm/actions/workflows/ci.yml/badge.svg)](https://github.com/zohoMatt/psdm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/psdm.svg)](https://pypi.org/project/psdm/)
+[![Docs](https://readthedocs.org/projects/psdm/badge/?version=latest)](https://psdm.readthedocs.io)
+
+The **Pore and Surface Diffusion Model (PSDM)** for fixed-bed granular activated carbon (GAC)
+adsorbers, as a small, tested and documented Python package.
+
+- Multi-component competitive adsorption (ideal adsorbed solution theory, Freundlich isotherms)
+- Film, pore and surface diffusion with built-in correlations or user-supplied coefficients
+- Natural organic matter fouling for the AdDesignS water types and compound classes, including PFAS
+- Time-varying influent, any time / concentration / flow units
+- Fitting Freundlich `K` and `1/n` to column data; batch isotherm fitting
+- Reader for the US EPA PSDM Excel input template
+
+## Installation
+
+```bash
+pip install psdm            # core
+pip install "psdm[excel]"   # + Excel input files
+pip install "psdm[plot]"    # + plotting
+```
+
+## Quick start
+
+```python
+import pandas as pd
+import psdm
+
+column = psdm.Column.from_units(
+    length=(2.765, "m"), diameter=(10, "ft"), mass=(20000, "lb"), flow_rate=(567, "gpm"),
+    particle_radius=(0.513, "mm"), particle_density=(0.803, "g/mL"), particle_porosity=0.641,
+)
+tce = psdm.Compound("TCE", mw=131.39, molar_volume=102.0, k=5026.04, n_inv=0.43)
+influent = pd.DataFrame({"TCE": [50.0, 50.0]}, index=[0.0, 174.0])  # days, mg/L
+
+result = psdm.simulate(column, tce, influent, conc_unit="mg/L", water="Rhine")
+result.effluent          # DataFrame: effluent concentration vs. time
+result([30, 60, 90])     # interpolated at given times
+```
+
+Reading the EPA Excel template:
+
+```python
+from psdm.io import read_excel
+
+data = read_excel("Example_Multi.xlsx")
+result = data.simulate(nr=4, nz=8, ne=2)
+```
+
+See the [documentation](https://psdm.readthedocs.io) for the model description, the full API
+and more examples.
+
+## Validation
+
+psdm is a rewrite of the original
+[US EPA Python PSDM](https://github.com/USEPA/Water_Treatment_Models/tree/3f514c2/PSDM)
+(commit `3f514c2`). It solves the same model equations: orthogonal-collocation discretisation,
+film, pore and surface diffusion, and the AdDesignS fouling correlations. It integrates them with
+the same ODE method, scipy's BDF solver with the same tolerances and Jacobian sparsity pattern, and
+reproduces the original's results.
+
+- **Against the original EPA code.** The comparison covers 11 cases: 7 single-compound AdDesignS
+  cases (Rhine, Organic Free and Portage water at 5–50 mg/L), 2 multi-component cases from
+  `Example_Multi.xlsx` and 2 time-varying influent cases from `Example_TCE.xlsx`. The largest
+  difference anywhere on a breakthrough curve is **0.33 % of the influent concentration C0**, and
+  the RMS difference is at most 0.06 % of C0.
+- **Against AdDesignS.** For the 7 single-compound cases with AdDesignS output, psdm stays within
+  0.57 % of C0 of AdDesignS. The original EPA code stays within 0.62 %.
+- **Test suite.** The tests check psdm against reference curves generated with the EPA code and
+  against the AdDesignS output, with a tolerance of 0.5 % of C0.
+
+The case-by-case comparison, with overlaid breakthrough curves, is in
+[`benchmarks/report.html`](benchmarks/report.html) (download it and open it in a browser). It
+is generated by [`scripts/benchmark.py`](scripts/benchmark.py).
+
+## Credits
+
+This package is a rewrite of the Python PSDM from the US EPA
+[Water Treatment Models](https://github.com/USEPA/Water_Treatment_Models) repository
+(J. Burkhardt, L. Haupert, B. Datsov et al.), which converted the Fortran PSDM in AdDesignS™
+(D.R. Hokanson, D.W. Hand, J.C. Crittenden, T.N. Rogers, E.J. Oman, Michigan Technological
+University) to Python. It is not affiliated with or endorsed by the US EPA or Michigan
+Technological University.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

psdm-0.1.0/README.md

@@ -0,0 +1,89 @@
+# psdm
+
+[![CI](https://github.com/zohoMatt/psdm/actions/workflows/ci.yml/badge.svg)](https://github.com/zohoMatt/psdm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/psdm.svg)](https://pypi.org/project/psdm/)
+[![Docs](https://readthedocs.org/projects/psdm/badge/?version=latest)](https://psdm.readthedocs.io)
+
+The **Pore and Surface Diffusion Model (PSDM)** for fixed-bed granular activated carbon (GAC)
+adsorbers, as a small, tested and documented Python package.
+
+- Multi-component competitive adsorption (ideal adsorbed solution theory, Freundlich isotherms)
+- Film, pore and surface diffusion with built-in correlations or user-supplied coefficients
+- Natural organic matter fouling for the AdDesignS water types and compound classes, including PFAS
+- Time-varying influent, any time / concentration / flow units
+- Fitting Freundlich `K` and `1/n` to column data; batch isotherm fitting
+- Reader for the US EPA PSDM Excel input template
+
+## Installation
+
+```bash
+pip install psdm            # core
+pip install "psdm[excel]"   # + Excel input files
+pip install "psdm[plot]"    # + plotting
+```
+
+## Quick start
+
+```python
+import pandas as pd
+import psdm
+
+column = psdm.Column.from_units(
+    length=(2.765, "m"), diameter=(10, "ft"), mass=(20000, "lb"), flow_rate=(567, "gpm"),
+    particle_radius=(0.513, "mm"), particle_density=(0.803, "g/mL"), particle_porosity=0.641,
+)
+tce = psdm.Compound("TCE", mw=131.39, molar_volume=102.0, k=5026.04, n_inv=0.43)
+influent = pd.DataFrame({"TCE": [50.0, 50.0]}, index=[0.0, 174.0])  # days, mg/L
+
+result = psdm.simulate(column, tce, influent, conc_unit="mg/L", water="Rhine")
+result.effluent          # DataFrame: effluent concentration vs. time
+result([30, 60, 90])     # interpolated at given times
+```
+
+Reading the EPA Excel template:
+
+```python
+from psdm.io import read_excel
+
+data = read_excel("Example_Multi.xlsx")
+result = data.simulate(nr=4, nz=8, ne=2)
+```
+
+See the [documentation](https://psdm.readthedocs.io) for the model description, the full API
+and more examples.
+
+## Validation
+
+psdm is a rewrite of the original
+[US EPA Python PSDM](https://github.com/USEPA/Water_Treatment_Models/tree/3f514c2/PSDM)
+(commit `3f514c2`). It solves the same model equations: orthogonal-collocation discretisation,
+film, pore and surface diffusion, and the AdDesignS fouling correlations. It integrates them with
+the same ODE method, scipy's BDF solver with the same tolerances and Jacobian sparsity pattern, and
+reproduces the original's results.
+
+- **Against the original EPA code.** The comparison covers 11 cases: 7 single-compound AdDesignS
+  cases (Rhine, Organic Free and Portage water at 5–50 mg/L), 2 multi-component cases from
+  `Example_Multi.xlsx` and 2 time-varying influent cases from `Example_TCE.xlsx`. The largest
+  difference anywhere on a breakthrough curve is **0.33 % of the influent concentration C0**, and
+  the RMS difference is at most 0.06 % of C0.
+- **Against AdDesignS.** For the 7 single-compound cases with AdDesignS output, psdm stays within
+  0.57 % of C0 of AdDesignS. The original EPA code stays within 0.62 %.
+- **Test suite.** The tests check psdm against reference curves generated with the EPA code and
+  against the AdDesignS output, with a tolerance of 0.5 % of C0.
+
+The case-by-case comparison, with overlaid breakthrough curves, is in
+[`benchmarks/report.html`](benchmarks/report.html) (download it and open it in a browser). It
+is generated by [`scripts/benchmark.py`](scripts/benchmark.py).
+
+## Credits
+
+This package is a rewrite of the Python PSDM from the US EPA
+[Water Treatment Models](https://github.com/USEPA/Water_Treatment_Models) repository
+(J. Burkhardt, L. Haupert, B. Datsov et al.), which converted the Fortran PSDM in AdDesignS™
+(D.R. Hokanson, D.W. Hand, J.C. Crittenden, T.N. Rogers, E.J. Oman, Michigan Technological
+University) to Python. It is not affiliated with or endorsed by the US EPA or Michigan
+Technological University.
+
+## License
+
+MIT — see [LICENSE](LICENSE).