mantis-rtm 0.1.1.dev0__py3-none-any.whl

mantis/solvers_numba.py

@@ -0,0 +1,219 @@
+"""
+Numba-accelerated numerical kernels for direct assembled reactive transport solvers.
+"""
+
+from __future__ import annotations
+
+import numba as nb
+import numpy as np
+
+
+@nb.njit(fastmath=True)
+def solve_tridiagonal_thomas(
+    ab: np.ndarray,
+    b: np.ndarray,
+    out: np.ndarray,
+    c_prime: np.ndarray,
+) -> None:
+    """
+    O(N) In-place Thomas algorithm (TDMA) for tridiagonal systems in SciPy banded (1, 1) layout.
+
+    Matrix layout in ab (shape 3, N):
+      - row 0: superdiagonal (ab[0, 1:] contains A[i, i+1] for i = 0..N-2)
+      - row 1: main diagonal  (ab[1, :] contains A[i, i] for i = 0..N-1)
+      - row 2: subdiagonal   (ab[2, :-1] contains A[i+1, i] for i = 0..N-2)
+
+    b:       RHS vector of shape (N,)
+    out:     solution vector of shape (N,), updated in-place
+    c_prime: work scratch array of shape (N - 1,)
+    """
+    n = len(b)
+    denom0 = ab[1, 0]
+    c_prime[0] = ab[0, 1] / denom0
+    out[0] = b[0] / denom0
+
+    # Forward elimination
+    for i in range(1, n - 1):
+        ai = ab[2, i - 1]
+        denom = ab[1, i] - ai * c_prime[i - 1]
+        c_prime[i] = ab[0, i + 1] / denom
+        out[i] = (b[i] - ai * out[i - 1]) / denom
+
+    ai_last = ab[2, n - 2]
+    denom_last = ab[1, n - 1] - ai_last * c_prime[n - 2]
+    out[n - 1] = (b[n - 1] - ai_last * out[n - 2]) / denom_last
+
+    # Back substitution
+    for i in range(n - 2, -1, -1):
+        out[i] -= c_prime[i] * out[i + 1]
+
+
+@nb.njit(fastmath=True)
+def compute_species_residual_wrms(
+    curr_val: np.ndarray,
+    prev_val: np.ndarray,
+    inner_tol: float,
+    atol: float,
+) -> float:
+    """
+    Computes WRMS norm for a single species:
+        sqrt( (1/N) * sum( ( |c_curr - c_prev| / (inner_tol * |c_curr| + atol) )^2 ) )
+    """
+    n = len(curr_val)
+    sum_sq = 0.0
+    for i in range(n):
+        c = curr_val[i]
+        diff = abs(c - prev_val[i])
+        scale = inner_tol * abs(c) + atol
+        ratio = diff / scale
+        if np.isnan(ratio) or np.isinf(ratio):
+            return np.inf
+        sum_sq += ratio * ratio
+    return np.sqrt(sum_sq / n)
+
+
+@nb.njit(fastmath=True)
+def compute_species_residual_linf(
+    curr_val: np.ndarray,
+    prev_val: np.ndarray,
+    inner_tol: float,
+    atol: float,
+) -> float:
+    """
+    Computes L-infinity norm for a single species:
+        max( |c_curr - c_prev| / (inner_tol * |c_curr| + atol) )
+    """
+    n = len(curr_val)
+    max_ratio = 0.0
+    for i in range(n):
+        c = curr_val[i]
+        diff = abs(c - prev_val[i])
+        scale = inner_tol * abs(c) + atol
+        ratio = diff / scale
+        if np.isnan(ratio) or np.isinf(ratio):
+            return np.inf
+        if ratio > max_ratio:
+            max_ratio = ratio
+    return max_ratio
+
+
+@nb.njit(fastmath=True)
+def solve_block_tridiagonal_thomas(
+    A: np.ndarray,
+    B: np.ndarray,
+    C: np.ndarray,
+    D: np.ndarray,
+    out: np.ndarray,
+    C_prime: np.ndarray,
+    D_prime: np.ndarray,
+) -> None:
+    """
+    O(N * S^3) In-place Block Tridiagonal Matrix Algorithm (Block TDMA) for 1D monolithic systems.
+
+    Solves the block-tridiagonal linear system:
+        A_i * U_{i-1} + B_i * U_i + C_i * U_{i+1} = D_i   for i = 0 .. N-1
+
+    where:
+      - N is the number of 1D spatial cells
+      - S is the number of coupled chemical species
+      - A has shape (N, S): diagonal elements of subdiagonal spatial block A_i (coupling to cell i-1)
+      - B has shape (N, S, S): dense diagonal block for cell i (transport + chemical Jacobian)
+      - C has shape (N, S): diagonal elements of superdiagonal spatial block C_i (coupling to cell i+1)
+      - D has shape (N, S): RHS / residual vector at each cell
+      - out has shape (N, S): solution vector, updated in-place
+      - C_prime has shape (N, S, S): scratch array for forward block elimination
+      - D_prime has shape (N, S): scratch array for forward RHS elimination
+    """
+    N, S = D.shape
+    M = np.empty((S, S), dtype=np.float64)
+    piv = np.empty(S, dtype=np.int64)
+    y = np.empty(S, dtype=np.float64)
+    rhs = np.empty(S, dtype=np.float64)
+
+    # Forward elimination sweep
+    for i in range(N):
+        # 1. Form M_i = B_i - A_i * C'_{i-1}
+        for r in range(S):
+            for c in range(S):
+                M[r, c] = B[i, r, c]
+        if i > 0:
+            for r in range(S):
+                ar = A[i, r]
+                for c in range(S):
+                    M[r, c] -= ar * C_prime[i - 1, r, c]
+
+        # 2. Form rhs = D_i - A_i * D'_{i-1}
+        for r in range(S):
+            rhs[r] = D[i, r]
+        if i > 0:
+            for r in range(S):
+                rhs[r] -= A[i, r] * D_prime[i - 1, r]
+
+        # 3. LU factorization of M with partial pivoting
+        for k in range(S):
+            piv[k] = k
+        for k in range(S):
+            max_r = k
+            max_v = abs(M[k, k])
+            for r in range(k + 1, S):
+                v = abs(M[r, k])
+                if v > max_v:
+                    max_v = v
+                    max_r = r
+            if max_r != k:
+                tmp_p = piv[k]
+                piv[k] = piv[max_r]
+                piv[max_r] = tmp_p
+                for col in range(S):
+                    tmp = M[k, col]
+                    M[k, col] = M[max_r, col]
+                    M[max_r, col] = tmp
+            diag = M[k, k]
+            if abs(diag) > 1e-30:
+                for r in range(k + 1, S):
+                    M[r, k] /= diag
+                    f = M[r, k]
+                    for col in range(k + 1, S):
+                        M[r, col] -= f * M[k, col]
+
+        # 4. Solve M * D'_i = rhs
+        # Forward substitution Ly = P * rhs
+        for r in range(S):
+            val = rhs[piv[r]]
+            for col in range(r):
+                val -= M[r, col] * y[col]
+            y[r] = val
+        # Back substitution Ux = y
+        for r in range(S - 1, -1, -1):
+            val = y[r]
+            for col in range(r + 1, S):
+                val -= M[r, col] * D_prime[i, col]
+            D_prime[i, r] = val / (M[r, r] if abs(M[r, r]) > 1e-30 else 1e-30)
+
+        # 5. If i < N - 1, solve M * C'_i[:, j] = C[i, j] * e_j for each column j
+        if i < N - 1:
+            for j in range(S):
+                cj = C[i, j]
+                # Forward Ly = P * (cj * e_j)
+                for r in range(S):
+                    val = cj if piv[r] == j else 0.0
+                    for col in range(r):
+                        val -= M[r, col] * y[col]
+                    y[r] = val
+                # Back Ux = y
+                for r in range(S - 1, -1, -1):
+                    val = y[r]
+                    for col in range(r + 1, S):
+                        val -= M[r, col] * C_prime[i, col, j]
+                    C_prime[i, r, j] = val / (M[r, r] if abs(M[r, r]) > 1e-30 else 1e-30)
+
+    # Back substitution sweep
+    for r in range(S):
+        out[N - 1, r] = D_prime[N - 1, r]
+    for i in range(N - 2, -1, -1):
+        for r in range(S):
+            val = D_prime[i, r]
+            for col in range(S):
+                val -= C_prime[i, r, col] * out[i + 1, col]
+            out[i, r] = val
+

mantis_rtm-0.1.1.dev0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: mantis-rtm
+Version: 0.1.1.dev0
+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
+Project-URL: Homepage, https://github.com/uliw/mantis
+Project-URL: Repository, https://github.com/uliw/mantis
+Project-URL: Issues, https://github.com/uliw/mantis/issues
+Keywords: reactive transport modeling,reaction transport modeling,geochemistry,monolithic solver,diagenesis,block newton,advection diffusion reaction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: numba
+Requires-Dist: pint
+Requires-Dist: watchdog
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == "doc"
+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.
+
+---
+
+## 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.
+- **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.
+
+---
+
+## How is MANTIS Different from Other Python RTM Packages?
+
+Most existing Python and geochemical reactive-transport modeling packages rely on **operator splitting** (such as Sequential Non-Iterative Approach [SNIA] or Sequential Iterative Approach [SIA]) or **decoupled Picard (Gauss-Seidel) iterations**:
+
+1. **Monolithic Coupling vs. Operator Splitting**:
+   - *Operator splitting* alternates between solving pure transport and pure batch chemistry over a time step. While simple, it introduces splitting errors and often requires tiny time steps ($\Delta t$ on the order of seconds or hours) to avoid artificial oscillations or numerical divergence when reactions are fast and stiff.
+   - *Picard iterations* solve each chemical species sequentially, lagging cross-species couplings from the previous iteration. At sharp reaction fronts (e.g., where sulfide meets oxygen or ferric iron), this decoupling frequently causes severe numerical lag oscillations.
+   - **MANTIS solves the entire system monolithically**: Transport and reactions for all species are assembled into a single unified block-tridiagonal linear system at each Newton step. This achieves true simultaneous coupling and quadratic Newton convergence.
+
+2. **Exact Symbolic Jacobians vs. Finite Differences**:
+   - Rather than approximating derivatives via costly numerical perturbations (finite differences) or requiring users to manually code and maintain hundreds of lines of Jacobian terms, MANTIS computes exact analytical Jacobians symbolically via `SymPy` ahead of time and compiles them to optimized machine code.
+
+3. **High-Performance Native Numba Engine**:
+   - The core block-tridiagonal solver and residual evaluations run directly in compiled machine code via Numba. This delivers C-like performance without external heavy PDE framework dependencies.
+
+4. **Unconditional Numerical Stability**:
+   - Thanks to its fully implicit monolithic formulation, MANTIS does not suffer from Courant-Friedrichs-Lewy (CFL) or diffusion time step stability restrictions, enabling long-term simulations (centuries to millennia) with large time steps.
+
+---
+
+## Scope and General Applicability
+
+While the bundled examples and default templates are geared toward **marine sediment early diagenesis** (e.g., organic matter mineralization cascades, dissimilatory iron and sulfate reduction, iron sulfide and pyrite precipitation, and stable sulfur isotope fractionation $\delta^{34}\text{S}$), **the underlying numerical formulation is domain-agnostic**.
+
+The monolithic advection-diffusion-reaction solver can be directly applied to any 1D reactive transport problem involving:
+- Stiff, multi-species nonlinear reaction networks
+- Combined particulate (solid) and solute (porewater/fluid) phases
+- Advection, molecular and eddy diffusion, and nonlocal exchange processes
+- Stable isotope fractionation and multi-isotope tracking
+
+---
+
+## Current Limitations
+
+While MANTIS provides robust and unconditionally stable solutions for stiff reactive transport, the current release has the following limitations:
+
+1. **Time-Invariant Spatial Mesh**:
+   - The spatial grid $z$ is static throughout the simulation. Dynamic grid adaptation, moving boundaries, or expanding domains (e.g., physical sediment column growth over time) are not currently supported.
+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.
+
+---
+
+## Installation
+
+MANTIS requires Python 3.12 or newer. Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/uliw/mantis.git
+cd mantis
+pip install -e .
+```
+
+Dependencies include `numpy`, `pandas`, `matplotlib`, `numba`, `sympy`, `chempy`, and `watchdog`.
+
+---
+
+## 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()
+```
+
+---
+
+## Running Tests
+
+Run the unit test suite using `pytest`:
+
+```bash
+pytest
+```
+
+---
+
+## License
+
+This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.

mantis_rtm-0.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mantis/__init__.py,sha256=Pkpwm4bu1o2hEdFHQL65jl8DSV71rTm2BrrfUYzmIbs,201
+mantis/_version.py,sha256=C7_2xyONPOLOpAzR9m7Juwyz8wzzwt9M7TtjzKDO_so,533
+mantis/diff_lib.py,sha256=qTTH11q01uSVYKIK9a8F8KQ8juX1IOFhC2Co1Y9QuD8,66362
+mantis/generate_equation_system.py,sha256=Ke_lgkCdz-4Jvjdj7l6rK9H-S7KbhJSYo2u8Ft2LXDU,109938
+mantis/live_plot_lib.py,sha256=kSTzb6wHNUzLt5p16mjJW-Ro3JphQ08hmtzyfHQuRS4,21827
+mantis/model.py,sha256=Um0Z4mBfMDERl3oRNHHhokwofD24dYqtnNiQucC3O3w,40771
+mantis/monitor_plots.py,sha256=Thm0PVeZJSQI4FdYWnixKpAaoEL4i0aX1uS6xiydb8Y,5408
+mantis/monolithic_solver.py,sha256=Rbk7rFYIuX-DCY_WcTxPh4L6WF9CVHGzkHka1u4r-xM,37019
+mantis/parallel_video.py,sha256=82hDPUJmzyF1QjmXkIExjGxepeTc8lKA3tSBJh9BuAE,16964
+mantis/plot_data_new.py,sha256=dzM9ZKv_kM16Qp6Y43NfRF2Kmqg7cc-v_6CNsctJiiA,45232
+mantis/solvers_numba.py,sha256=cDUX-tD_SX6OiJ8e4pNQrN6lS9dBw2nnS7qC-np6KQw,7057
+mantis_rtm-0.1.1.dev0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mantis_rtm-0.1.1.dev0.dist-info/METADATA,sha256=XhBZoVB3XbeVrwMDErCApFsyu0HhiQVJ82HpZOAPDPs,8554
+mantis_rtm-0.1.1.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mantis_rtm-0.1.1.dev0.dist-info/entry_points.txt,sha256=XKk3i1AqyWf20_zgSsECVGLewZVW7c_qEf6L37IyvkY,304
+mantis_rtm-0.1.1.dev0.dist-info/top_level.txt,sha256=pHGQmbUmUmGR68I95aUwKhubm_r957NOoGxwoGHlRbI,7
+mantis_rtm-0.1.1.dev0.dist-info/RECORD,,

mantis_rtm-0.1.1.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mantis_rtm-0.1.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+generate-equation-system = mantis.generate_equation_system:main
+generate-equations = mantis.generate_equation_system:main
+generate_equation_system = mantis.generate_equation_system:main
+generate_equations = mantis.generate_equation_system:main
+plot_data_new = mantis.plot_data_new:main