mantis-rtm 0.1.1.dev0__tar.gz → 0.2.0__tar.gz

mantis_rtm-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,47 @@
+name: Build and Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build distribution and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mantis-rtm
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publishing (OIDC)
+      contents: read   # Required to checkout repository
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for setuptools_scm to extract version from tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build source distribution and wheel
+        run: python -m build
+
+      - name: Verify distribution archives
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # PyPI Trusted Publishing (OIDC) is used automatically when permissions.id-token is set.
+        # If you prefer using a classic PyPI API token instead of Trusted Publishing,
+        # add a repository secret named PYPI_API_TOKEN and uncomment the line below:
+        # with:
+        #   password: ${{ secrets.PYPI_API_TOKEN }}

mantis_rtm-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main, staging]
+
+jobs:
+  test:
+    name: Run test suite (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Run pytest
+        run: pytest

{mantis_rtm-0.1.1.dev0/src/mantis_rtm.egg-info → mantis_rtm-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mantis-rtm
-Version: 0.1.1.dev0
+Version: 0.2.0
 Summary: MANTIS: A Monolithic Assembly of Nonlinear Transport Interactions Solver
 Author-email: Uli Wortmann <uli.wortmann@utoronto.ca>
 License-Expression: AGPL-3.0-or-later
@@ -41,20 +41,21 @@ Dynamic: license-file
 
 # MANTIS: A *M*onolithic *A*ssembly of *N*onlinear *T*ransport *I*nteractions *S*olver
 
-**MANTIS** is a high-performance 1D reactive-transport modeling (RTM) framework written in Python, designed to simulate stiff, tightly coupled advection-diffusion-reaction networks.
+[![Build Status](https://github.com/uliw/mantis/actions/workflows/tests.yml/badge.svg)](https://github.com/uliw/mantis/actions/workflows/tests.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/mantis-rtm.svg)](https://pypi.org/project/mantis-rtm/)
+[![Python Versions](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://pypi.org/project/mantis-rtm/)
+[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL_3.0--or--later-blue.svg)](https://github.com/uliw/mantis/blob/main/LICENSE)
 
----
+**MANTIS** is a high-performance 1D reactive-transport modeling (RTM) framework written in Python, designed to simulate stiff, tightly coupled advection-diffusion-reaction networks, by building a fully coupled monolithic equation system. Mantis stands for   *M*onolithic *A*ssembly of *N*onlinear *T*ransport *I*nteraction*S*
 
-## What is MANTIS?
 
-Reactive-transport systems in natural environments—such as marine sediments, groundwater aquifers, and geochemical reactors—involve simultaneous transport (advection, molecular diffusion, bio-irrigation, and bioturbation) coupled with complex networks of nonlinear chemical, mineral, and biological reactions.
 
 MANTIS provides:
-- **Declarative Geochemical Model Definition**: Define chemical species, phases, reaction stoichiometries, and kinetic limiters (Monod, inhibition, threshold laws) in intuitive, human-readable Python configuration files.
+- **Declarative Geochemical Model Definition**: Define chemical species, phases, reaction stoichiometries, and kinetic limiters (Monod, inhibition, threshold laws), and isotope effects using  intuitive, human-readable Python configuration files.
 - **Automated Symbolic Jacobian Generation**: Automatically parses reaction networks and compiles analytical chemical Jacobians using symbolic computer algebra (`SymPy`), eliminating error-prone manual differentiation.
 - **Monolithic Block Newton-Raphson Solver**: Solves all chemical species and transport equations simultaneously in a coupled block-tridiagonal system using a Numba-accelerated Block Thomas algorithm.
 - **Adaptive Time Stepping**: Features PID-controlled adaptive time stepping with automatic step rejection and convergence recovery.
-- **Unified Declarative Interface**: Configure and run simulations through `DiageneticModel`, complete with automatic CLI argument handling, checkpointing, publication-ready summary plots, and asynchronous time-lapse video generation.
+- **Unified Declarative Interface**: Configure and run simulations through `DiageneticModel`, complete with automatic CLI argument handling, and an integrated plotting system that supports asynchronous time-lapse video generation.
 
 ---
 
@@ -99,7 +100,7 @@ While MANTIS provides robust and unconditionally stable solutions for stiff reac
 2. **Time-Invariant Porosity**:
    - The porosity profile $\phi(z)$ is stationary in time (steady-state compaction). Transient sediment compaction or compaction-driven dynamic fluid expulsion over time is not currently modeled.
 3. **Time-Invariant Temperature**:
-   - The temperature profile $T(z)$ is steady-state. Dynamic thermal evolution and time-dependent diffusion coefficients or rate constants driven by non-isothermal thermal transients are not currently supported.
+   - The temperature profile of $T(z)$ is steady-state. Dynamic thermal evolution and time-dependent diffusion coefficients or rate constants driven by non-isothermal thermal transients are not currently supported.
 
 ---
 
@@ -118,47 +119,7 @@ Dependencies include `numpy`, `pandas`, `matplotlib`, `numba`, `sympy`, `chempy`
 ---
 
 ## Quick Start Example
-
-A typical simulation directory contains declarative configuration files defining species, reactions, rate constants, and plot layouts:
-
-```python
-from mantis import DiageneticModel
-
-# 1. Initialize the model (auto-detects species.py, reactions, constants in the directory)
-model = DiageneticModel(
-    reactions="fes_reactions.py",
-    constants="kinetic_constants_slow.py",
-    layout="plot_layout.py",
-    experiment="marine_diagenesis",
-)
-
-# 2. Configure environmental and grid parameters
-model.configure(
-    max_depth="0.5 m",
-    t_end="2 kyr",
-    dt_init="1 day",
-    dt_max="1 year",
-    w="0.2 cm/yr",
-    phi=0.8,
-    bioturbation={
-        "BT0": "4 cm^2/year",
-        "depth": "6 cm",
-        "attenuation": "2 cm",
-    },
-)
-
-# 3. Enable CLI flag overrides (--video, --solver-tol, --t-end, etc.)
-model.parse_cli_args()
-
-# 4. Run the simulation
-result = model.run()
-
-# 5. Export results and summary plots
-df, csv_path = result.save_csv()
-result.plot_summary()
-```
-
----
+A quick-start tutorial is available in the `./docs` folder
 
 ## Running Tests
 

{mantis_rtm-0.1.1.dev0 → mantis_rtm-0.2.0}/README.md

@@ -1,19 +1,20 @@
 # MANTIS: A *M*onolithic *A*ssembly of *N*onlinear *T*ransport *I*nteractions *S*olver
 
-**MANTIS** is a high-performance 1D reactive-transport modeling (RTM) framework written in Python, designed to simulate stiff, tightly coupled advection-diffusion-reaction networks.
+[![Build Status](https://github.com/uliw/mantis/actions/workflows/tests.yml/badge.svg)](https://github.com/uliw/mantis/actions/workflows/tests.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/mantis-rtm.svg)](https://pypi.org/project/mantis-rtm/)
+[![Python Versions](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://pypi.org/project/mantis-rtm/)
+[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL_3.0--or--later-blue.svg)](https://github.com/uliw/mantis/blob/main/LICENSE)
 
----
+**MANTIS** is a high-performance 1D reactive-transport modeling (RTM) framework written in Python, designed to simulate stiff, tightly coupled advection-diffusion-reaction networks, by building a fully coupled monolithic equation system. Mantis stands for   *M*onolithic *A*ssembly of *N*onlinear *T*ransport *I*nteraction*S*
 
-## What is MANTIS?
 
-Reactive-transport systems in natural environments—such as marine sediments, groundwater aquifers, and geochemical reactors—involve simultaneous transport (advection, molecular diffusion, bio-irrigation, and bioturbation) coupled with complex networks of nonlinear chemical, mineral, and biological reactions.
 
 MANTIS provides:
-- **Declarative Geochemical Model Definition**: Define chemical species, phases, reaction stoichiometries, and kinetic limiters (Monod, inhibition, threshold laws) in intuitive, human-readable Python configuration files.
+- **Declarative Geochemical Model Definition**: Define chemical species, phases, reaction stoichiometries, and kinetic limiters (Monod, inhibition, threshold laws), and isotope effects using  intuitive, human-readable Python configuration files.
 - **Automated Symbolic Jacobian Generation**: Automatically parses reaction networks and compiles analytical chemical Jacobians using symbolic computer algebra (`SymPy`), eliminating error-prone manual differentiation.
 - **Monolithic Block Newton-Raphson Solver**: Solves all chemical species and transport equations simultaneously in a coupled block-tridiagonal system using a Numba-accelerated Block Thomas algorithm.
 - **Adaptive Time Stepping**: Features PID-controlled adaptive time stepping with automatic step rejection and convergence recovery.
-- **Unified Declarative Interface**: Configure and run simulations through `DiageneticModel`, complete with automatic CLI argument handling, checkpointing, publication-ready summary plots, and asynchronous time-lapse video generation.
+- **Unified Declarative Interface**: Configure and run simulations through `DiageneticModel`, complete with automatic CLI argument handling, and an integrated plotting system that supports asynchronous time-lapse video generation.
 
 ---
 
@@ -58,7 +59,7 @@ While MANTIS provides robust and unconditionally stable solutions for stiff reac
 2. **Time-Invariant Porosity**:
    - The porosity profile $\phi(z)$ is stationary in time (steady-state compaction). Transient sediment compaction or compaction-driven dynamic fluid expulsion over time is not currently modeled.
 3. **Time-Invariant Temperature**:
-   - The temperature profile $T(z)$ is steady-state. Dynamic thermal evolution and time-dependent diffusion coefficients or rate constants driven by non-isothermal thermal transients are not currently supported.
+   - The temperature profile of $T(z)$ is steady-state. Dynamic thermal evolution and time-dependent diffusion coefficients or rate constants driven by non-isothermal thermal transients are not currently supported.
 
 ---
 
@@ -77,47 +78,7 @@ Dependencies include `numpy`, `pandas`, `matplotlib`, `numba`, `sympy`, `chempy`
 ---
 
 ## Quick Start Example
-
-A typical simulation directory contains declarative configuration files defining species, reactions, rate constants, and plot layouts:
-
-```python
-from mantis import DiageneticModel
-
-# 1. Initialize the model (auto-detects species.py, reactions, constants in the directory)
-model = DiageneticModel(
-    reactions="fes_reactions.py",
-    constants="kinetic_constants_slow.py",
-    layout="plot_layout.py",
-    experiment="marine_diagenesis",
-)
-
-# 2. Configure environmental and grid parameters
-model.configure(
-    max_depth="0.5 m",
-    t_end="2 kyr",
-    dt_init="1 day",
-    dt_max="1 year",
-    w="0.2 cm/yr",
-    phi=0.8,
-    bioturbation={
-        "BT0": "4 cm^2/year",
-        "depth": "6 cm",
-        "attenuation": "2 cm",
-    },
-)
-
-# 3. Enable CLI flag overrides (--video, --solver-tol, --t-end, etc.)
-model.parse_cli_args()
-
-# 4. Run the simulation
-result = model.run()
-
-# 5. Export results and summary plots
-df, csv_path = result.save_csv()
-result.plot_summary()
-```
-
----
+A quick-start tutorial is available in the `./docs` folder
 
 ## Running Tests
 
@@ -131,4 +92,4 @@ pytest
 
 ## License
 
-This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.

mantis_rtm-0.2.0/changelog.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- **Generalized Isotope Modeling & Standards Framework**:
+  - Dynamically handle all isotope companion species across `diff_lib.py` and `live_plot_lib.py` instead of relying on hardcoded mappings.
+  - Added support for explicit isotope reference standards (e.g., `VCDT` for sulfur) with custom standard ratios and metadata-defined `delta_name`.
+  - Added support for species without explicit stoichiometry (defaulting to 1.0) and maintained backwards compatibility for legacy `d_<base>` column names alongside `d34S_<species>`.
+  - Updated isotope unit representations from per mil (`permil` / `‰`) to milli Urey (`mUr`) per IUPAC conventions across documentation, examples, and plot exports.
+ 
+- **Equation System Generation & Dynamic Limiters**:
+  - Dynamic extraction of Monod half-saturation constants from rate expressions with phase-aware (solid vs. fluid phase) scaling based on sediment porosity.
+  - Implemented dynamic limiter inclusion based on actual reactant and inhibition usage, eliminating unused terms and redundant code in generated equation scripts.
+  - Added `force_regen` and `rebuild_equations` options in `generate_equation_system` and added the `--force-regen` CLI argument to bypass cached equations and rebuild.
+  - Added automatic equation regeneration checks comparing file modification timestamps of generator and reaction scripts.
+- **Model Configuration & Video Controls**:
+  - Added strict pH validation during `DiageneticModel` initialization with descriptive error guidance.
+  - Enhanced `configure()` with generic Pint-based unit conversions for geometric, environmental, transport, and grid parameters.
+- **CI/CD & Documentation**:
+  - Added Python 3.14 to GitHub Actions test matrix across Linux environments.
+  - Added status, PyPI version, Python versions (3.12–3.14), and AGPL license badges to `README.md`.
+  - Expanded tutorial documentation (`docs/tutorial.md`) with isotope delta boundary condition examples, updated geochemical constants, and equation regeneration options.
+  - Added comprehensive test coverage in `tests/test_diagenetic_model.py` for isotope standards, delta columns, and missing file diagnostics.
+
+### Changed
+
+- **Examples**:
+  - Streamlined `examples/velde_et_al_2016/run_velde_fast.py` by removing unnecessary manual time stepping parameters (`dt_init`, `dt_min`, `dt_tolerance`).
+  - Simplified limiter calculation logic in `velde_et_al_2016` by consolidating phase scaling into a unified block.
+- **Plotting**:
+  - Refactored `plot_data_new.py` to dynamically detect and plot isotope delta columns.
+
+### Removed
+
+- Removed obsolete `docs/tutorial.org` file.
+- Removed deprecated default parameter assignments for `Fe2_diss`, `Fe2_sorb`, `hs_frac`, and `h2s_frac`.
+
+## [0.1.2] - 2026-10-12
+
+### Added
+
+- **File Path Resolution & Diagnostic Error Handling**:
+  - Enhanced file path resolution in `DiageneticModel` (`_resolve`), searching the current working directory, the model script directory (`base_dir`), and fallback naming patterns (such as `<experiment>_reactions.py`).
+  - Implemented early file validation (`validate_simulation_files()`) during `DiageneticModel` initialization and setup to catch missing simulation files before simulation execution.
+  - Added informative error diagnostics (`[MANTIS ERROR]`) detailing exact search locations and resolution guidance when species, reactions, constants, limiters, or plot layout files are missing.
+  - Improved plot layout file resolution in `plot_data_new.load_layout_from_file` and `plot_summary` with clear error reporting and search path feedback.
+  - Added unit test suite in `tests/test_diagenetic_model.py` testing missing file scenarios, exit behavior, and directory resolution from both CWD and model base directories.
+
+## [0.1.1] - 2026-10-12
+
+### Added
+
+- **Steady-State Detection & Convergence**:
+  - Implemented a grid-independent spatial $L_2$ steady-state convergence check in `run_non_steady_state_solver_monolithic`. Computes a volume-weighted root-mean-square (RMS) change across grid cells per species and checks against `steady_state_tolerance` (or falls back to `dt_tolerance` if set).
+  - Added a minimum step requirement (step > 5) to prevent premature steady-state termination.
+- **Model Parameters & Unit Conversions**:
+  - Added support for grid spacing parameters with unit conversion in `DiageneticModel`: `initial_spacing`, `reaction_zone_spacing`, and `max_spacing`.
+  - Added support for the `reaction_zone` tuple/list interval parameter with unit conversion.
+  - Added support for `steady_state_tolerance` and `dt_tolerance` solver tolerance parameters.
+  - Added `check_reactant_coexistence` boolean option and enabled the post-simulation reactant coexistence diagnostic by default.
+- **Examples**:
+  - Added fast and slow simulation setups for the Velde et al. (2016) sediment diagenesis benchmark:
+    - `examples/velde_et_al_2016/run_velde_fast.py` & `kinetic_constants_fast.py`: fast configuration with pyrite precipitation.
+    - `examples/velde_et_al_2016/run_velde_slow.py` & `kinetic_constants_slow.py`: slow configuration tracking sulfur isotopes.
+- **CI/CD & Automation**:
+  - Added GitHub Actions workflow `.github/workflows/tests.yml` to run automated test suites across Python 3.12, 3.13, and 3.14.
+  - Added GitHub Actions workflow `.github/workflows/publish-pypi.yml` for automated PyPI package publishing upon GitHub releases.
+- **Documentation**:
+  - Added comprehensive documentation on physical units (`pint` integration) and non-uniform grid generation to `docs/tutorial.md` and `docs/tutorial.org`.
+
+### Changed
+
+- **Rate Laws & Equation System Generation**:
+  - Simplified particulate organic carbon (POC) respiration rate equations by removing redundant coefficient calculations.
+  - Simplified FeS precipitation and dissolution rate formulation by removing unnecessary Michaelis-Menten terms.
+  - Adjusted default smoothing parameter `fes_smooth_epsilon` from `0.05` to `0.01` for sharper, smoother reaction transitions.
+  - Dynamically extract and handle active POC species and kinetic parameter pairs instead of using hardcoded POC fast/slow loops.
+- **Differential Operators Library (`diff_lib`)**:
+  - Added type annotations across numerical and differential operator functions.
+  - Improved formatting, line wrapping, indentation, and visual structure.
+- **Project Packaging & Metadata**:
+  - Updated package distribution name to `mantis-rtm` and enabled dynamic versioning using `setuptools_scm`.
+  - Added `pint` as an explicit core dependency in `pyproject.toml` and `requirements.txt`.
+  - Added AGPL-3.0-or-later license configuration and classifiers.
+  - Configured project URLs (Homepage, Repository, Issues) and updated build ignore patterns in `.gitignore`.
+- **Examples**:
+  - Corrected FeS dissolution rate constant in `examples/velde_et_al_2016/kinetic_constants_slow.py`.
+  - Adjusted broken axis limits in `examples/velde_et_al_2016/plot_layout.py` for clearer concentration profile visualization.
+
+### Removed
+
+- Removed obsolete `examples/velde_et_al_2016/run_velde_model.py` script.
+- Removed legacy table of contents from tutorial documentation.
+
+## [0.1.0] - 2026-10-11
+
+- Initial tagged release with core MANTIS reactive transport solver and tutorial documentation.