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

mantis_rtm-0.1.2/.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.1.2/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run test suite (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    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.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mantis-rtm
-Version: 0.1.1.dev0
+Version: 0.1.2
 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

mantis_rtm-0.1.2/changelog.md

@@ -0,0 +1,67 @@
+# 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.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.

{mantis_rtm-0.1.1.dev0 → mantis_rtm-0.1.2}/docs/tutorial.md

@@ -1,31 +1,3 @@
-- [Introduction: What is MANTIS?](#org5dbc758)
-- [Overall Model Architecture: What is Where?](#org4417d27)
-- [Step 1: Defining Chemical Species (`species.py`)](#orgc16f49a)
-  - [Understanding Phases: Dissolved vs. Solid vs. Mixed](#orgba057ca)
-  - [Example: Standard Species Configuration](#org10d01d0)
-  - [Handling Diffusion Coefficients](#orgd0812cc)
-    - [Custom Diffusion Functions (e.g., Dissolved Oxygen)](#org69559bb)
-- [Step 2: Defining Kinetic Constants (`kinetic_constants_*.py`)](#org809df99)
-  - [Structure of `kinetic_constants_slow.py`](#org3c64ffa)
-- [Step 3: Defining Reactions & Limiters (`fes_reactions.py`)](#org1fecbeb)
-  - [Understanding Limiters & Inhibitors](#org739ad2b)
-  - [Declaring Chemical Reactions](#org5336c1e)
-- [Step 4: The Master Run Script (`run_velde_model.py`)](#org21fe2f4)
-- [Step 5: Designing Plot Layouts (`plot_layout.py`)](#orgf185086)
-  - [Converting Model Units to Geochemical Units](#orgaefde21)
-  - [Defining Multi-Panel Profiles](#orgf5ff558)
-- [Step 6: Running the Model & Producing Time-Lapse Videos](#orge7acd7b)
-  - [Standard Execution](#orgee831e4)
-  - [Generating a Time-Lapse Video](#orgcf4fea3)
-  - [Command-Line Options Reference](#orgf872aa8)
-- [Solver Mechanics & Physical Realism (Geochemist's Alert!)](#orgfeddb58)
-  - [How to Ensure Physical Realism:](#org9a13232)
-- [Summary & Next Steps](#org0cb5c1f)
-
-
-
-<a id="org5dbc758"></a>
-
 # Introduction: What is MANTIS?
 
 Welcome to **MANTIS** (\*M\*onolithic \*A\*ssembly of \*N\*onlinear \*T\*ransport \*I\*nteractions \*S\*olver)! If you are a geochemist, sedimentologist, or marine geologist, you are likely familiar with the classic picture of early diagenesis in marine sediments:
@@ -194,6 +166,85 @@ species = {
 }
 ```
 
+# Concentration Units & Conversions: Inputs, Internal Engine, and Outputs
+
+A common source of confusion in diagenetic modeling is the distinction between porewater solute concentrations, solid sediment mineral concentrations, and geochemical laboratory units (such as $\text{wt}\%$ or $\mu\text{mol/g}$). MANTIS handles physical units transparently while maintaining strict mass conservation across phases.
+
+## 1. Default Input Units
+
+When defining your model setup and boundary conditions:
+
+- **Driver Script Parameters (`run_velde_model.py`)**:
+  MANTIS supports human-readable strings parsed via Python's `pint` physical unit library:
+  - Lengths and depths: `"0.5 m"`, `"50 cm"`
+  - Times and time steps: `"0.5 kyr"`, `"1 year"`, `"24 hours"`
+  - Sedimentation rates: `"0.2 cm/yr"`, `"1 mm/a"`
+  - Bioturbation coefficients: `"4 cm^2/year"`, `"1e-9 m^2/s"`
+
+- **Boundary Conditions (`species.py`)**:
+  - **Dissolved Solutes (`type: "dissolved"`)**:
+    Upper boundary concentrations can be specified as a numeric float or a unit string. The default numeric input is **$\text{mmol/L}$** (which is identical to $\text{mol/m}^3$ or $\text{mM}$).
+    ```text
+    "bc": {"top": 28.2, "type": "dissolved"}         # 28.2 mmol/L (seawater sulfate)
+    "bc": {"top": "280 umol/L", "type": "dissolved"} # parsed automatically to 0.28 mmol/L
+    ```
+  - **Particulate Solids (`type: "particulate"`)**:
+    Deposition at the sediment-water interface is specified as a depositional surface flux:
+    ```text
+    "bc": {"top": "12 umol/(cm^2 * yr)", "type": "particulate"}
+    ```
+    MANTIS automatically converts this to internal flux units ($\text{mol}/(\text{m}^2 \cdot \text{s})$) during initialization.
+
+## 2. How Units Are Handled Internally by the Solver
+
+Under the hood, MANTIS standardizes all transport and reaction PDEs into SI-derived volumetric units:
+$$\text{Internal Concentration Unit} = \mathbf{mol/m^3} \quad (\equiv 1\ \text{mmol/L} \equiv 1\ \text{mM} \equiv 1000\ \mu\text{mol/L} \equiv 1\ \mu\text{mol/cm}^3)$$
+
+Crucially, concentrations are defined **per unit volume of their respective phase**:
+1. **Liquid Solutes**: Expressed per volume of porewater ($\text{mol / m}^3_{\text{liquid}} = \text{mmol / L}_{\text{porewater}}$). The bulk sediment inventory is $\phi \cdot C_{\text{liquid}}$.
+2. **Solid Minerals**: Expressed per volume of pure solid sediment ($\text{mol / m}^3_{\text{solid}} = \text{mmol / L}_{\text{solid}}$). The bulk sediment inventory is $(1 - \phi) \cdot C_{\text{solid}}$.
+3. **Phase Transfer & Reactions**: Whenever a reaction couples a solid phase and a liquid phase (for example, $\text{Fe}^{2+} + \text{HS}^- \to \text{FeS}$), MANTIS scales the source and sink terms with the appropriate phase ratio ($(1-\phi)/\phi$ or $\phi/(1-\phi)$) so that mass is strictly conserved.
+4. **Reaction Rates**: Solved internally in $\text{mol} / (\text{m}^3_{\text{phase}} \cdot \text{s})$.
+5. **Depths and Transport**: Depth $z$ is in meters ($\text{m}$), time $t$ in seconds ($\text{s}$), and diffusion coefficients in $\text{m}^2/\text{s}$.
+
+## 3. Output Units in Result Files (`.csv`)
+
+When the simulation completes or exports data (`<model_name>.csv`):
+- `c_<species>`: Reported directly in **$\text{mmol/L}$** (numerically equivalent to $\text{mol/m}^3$):
+  - Solutes (e.g., `c_SO4`, `c_O2`, `c_TS2`) are in **$\text{mmol / L of porewater}$**.
+  - Solids (e.g., `c_FeS`, `c_Fe3`, `c_POC_slow`) are in **$\text{mmol / L of pure solid}$**.
+- `f_<species>`: Net production/consumption reaction rates in **$\text{mol} / (\text{m}^3 \cdot \text{s})$**.
+- `d_<species>`: Isotope delta values (e.g., `d_SO4`, `d_FeS`) in **$\permil$** (per mil relative to VCDT).
+- `z`: Depth below sediment-water interface in **meters** ($\text{m}$).
+- `phi` and `w`: Porosity (fraction, dimensionless) and burial velocity ($\text{m/s}$).
+
+## 4. Converting Solid Concentrations to Standard Geochemical Units
+
+Geochemists typically report solid mineral abundances as dry-sediment mass fractions ($\text{wt}\%$) or mass-normalized molar concentrations ($\mu\text{mol/g}$). MANTIS includes built-in conversion utilities in `mantis.diff_lib`:
+
+### A. Converting to $\mu\text{mol / g}$ (micromoles per gram of dry sediment)
+To convert a solid concentration $C_{\text{solid}}$ ($\text{mmol/L of solid} = \mu\text{mol/cm}^3_{\text{solid}}$) to $\mu\text{mol/g}$ of dry sediment, divide by the mineral grain density $\rho_{\text{sed}}$ (typically $2.6\ \text{g/cm}^3$ for siliciclastic sediments):
+$$C_{\mu\text{mol/g}} = \frac{C_{\text{solid}}}{\rho_{\text{sed}}}$$
+
+In Python:
+```python
+from mantis.diff_lib import solid_conc_to_umol_per_g
+
+# df.c_FeS is in mmol/L of solid; density in g/cm^3
+c_fes_umol_g = solid_conc_to_umol_per_g(df.c_FeS, d=2.6)
+```
+
+### B. Converting to Dry Weight Percent ($\text{wt}\%$)
+To convert $C_{\text{solid}}$ to weight percent of dry sediment matrix given molecular weight $M_w$ ($\text{g/mol}$):
+$$\text{wt}\% = \frac{C_{\text{solid}} \cdot M_w}{\rho_{\text{sed}} \cdot 10^4}$$
+
+In Python:
+```python
+from mantis.diff_lib import solid_conc_to_wt_percent
+
+# Example: FeS (Mw = 87.91 g/mol, density = 2.6 g/cm^3)
+fes_wt_pct = solid_conc_to_wt_percent(df.c_FeS, mw=87.91, d=2.6, phi=df.phi)
+```
 
 <a id="org809df99"></a>
 
@@ -403,6 +454,12 @@ if __name__ == "__main__":
             "BI0": 0.0,                # Set to 0.0 to disable; or e.g. "20 /year"
             "depth": "0 cm",
         },
+
+        # Spatial grid & reaction zone refinement (optional, defaults provided)
+        initial_spacing="0.1 mm",      # Spacing at sediment-water interface (z=0)
+        reaction_zone=("0.1 cm", "1.0 cm"), # Critical depth window of sharp redox fronts
+        reaction_zone_spacing="0.05 mm",    # Dense, uniform spacing in the reaction zone
+        max_spacing="1.0 cm",          # Coarser spacing in deep sediment
     )
 
     # 3. Allow CLI overrides (e.g. running --video from the terminal)
@@ -423,6 +480,51 @@ if __name__ == "__main__":
 ```
 
 
+## Spatial Grid Configuration & Reaction Zone Resolution
+
+Diagenetic models must resolve spatial scales ranging from sub-millimeter oxygen penetration depths to deep sediment columns spanning decimeters to hundreds of meters. A uniform fine grid across a 50-meter column would require millions of cells and slow down calculations unnecessarily.
+
+MANTIS solves this using an adaptive geometric-mesh builder (`make_grid2`) that refines where steep gradients occur and expands into the deep sediment.
+
+### 1. How Grid Generation Works (`make_grid2`)
+The grid structure is divided into four seamless stages from the sediment surface to depth:
+1. **Surface Section**: Starts at `initial_spacing` and geometrically refines cells downward toward `reaction_zone[0]`.
+2. **Reaction Zone Section**: Maintains a constant, ultra-fine cell size (`reaction_zone_spacing`) across the depth interval `reaction_zone = (z_start, z_end)`.
+3. **Coarsening Section**: Below the reaction zone, cell size expands geometrically by factor $r = 1.05$ per cell.
+4. **Deep Uniform Section**: Once cell size reaches `max_spacing`, the remainder of the domain down to `max_depth` uses uniform large cells.
+
+### 2. The Geochemical Importance of Reaction Zone Resolution
+Why does grid spacing in the reaction zone matter so much?
+Fast bimolecular redox reactions—such as ferrous iron oxidation ($\text{Fe}^{2+} + \text{O}_2 \to \text{Fe}^{3+}$) or sulfide oxidation—occur across exceedingly narrow interfaces. The physical reaction front width $\delta_{\text{phys}}$ is governed by the balance between molecular diffusion and reaction kinetics:
+$$\delta_{\text{phys}} \sim \sqrt{\frac{D_{\text{eff}}}{k \cdot C_{\text{scale}}}}$$
+For transport-controlled reactions with large kinetic constants ($k = 10^7\ \text{M}^{-1}\text{s}^{-1}$), $\delta_{\text{phys}}$ is often **under $0.05\text{ mm}$**.
+
+If your numerical grid cell size $\Delta z$ is larger than $2 \delta_{\text{phys}}$, the local Damköhler number is large ($Da_{II} \gg 1$). The finite-volume discretization cannot resolve the sharp counter-gradients, producing a numerical artifact called **artificial reactant coexistence**:
+- $\text{Fe}^{2+}$ and $\text{O}_2$ artificially overlap in the same cell.
+- Reactants diffuse past each other instead of reacting completely at the interface.
+- Apparent reaction rates become smeared over several millimeters to centimeters.
+
+### 3. Automated Coexistence Diagnostic
+MANTIS automatically runs a post-simulation front diagnostic (`check_reactant_coexistence`) at the end of every run. If any reaction front is under-resolved, MANTIS outputs a clear warning:
+```text
+[WARNING: Numerical Reactant Co-existence Detected]
+  Reaction: 'Fe2 Oxidation by O2' (fe2 + O2)
+  Front location (peak): z = 0.21 cm (depth cell index: 21)
+  Local grid resolution: dz = 0.10 mm
+  Estimated physical front width: 0.01 mm
+  Front cell span (N_cells): 6 cell(s)
+  Reasons: Local grid cell dz (0.10 mm) > 2x physical front width (0.01 mm)
+  --> Action recommended: In make_grid2(), refine the mesh around z = [0.19, 0.23] cm to reaction_zone_spacing <= 0.01 mm.
+```
+
+When you see this warning, simply update your driver script's `model.configure()` with the recommended reaction zone window and spacing:
+```python
+model.configure(
+    reaction_zone=("0.15 cm", "0.30 cm"),
+    reaction_zone_spacing="0.01 mm",
+)
+```
+
 <a id="orgf185086"></a>
 
 # Step 5: Designing Plot Layouts (`plot_layout.py`)

{mantis_rtm-0.1.1.dev0 → mantis_rtm-0.1.2}/docs/tutorial.org

@@ -1,8 +1,7 @@
-#+TITLE: MANTIS: A Geoscientist's Guide to 1D Reactive-Transport Modeling
 #+AUTHOR: MANTIS Development Team
 #+DATE: [2026-10-11]
-#+OPTIONS: toc:3 num:t ^:{}
-#+STARTUP: showeverything
+#+OPTIONS: toc:nil
+
 
 * Introduction: What is MANTIS?
 
@@ -155,6 +154,90 @@ species = {
 }
 #+END_SRC
 
+* Concentration Units & Conversions: Inputs, Internal Engine, and Outputs
+
+A common source of confusion in diagenetic modeling is the distinction between porewater solute concentrations, solid sediment mineral concentrations, and geochemical laboratory units (such as $\text{wt}\%$ or $\mu\text{mol/g}$). MANTIS handles physical units transparently while maintaining strict mass conservation across phases.
+
+** 1. Default Input Units
+
+When defining your model setup and boundary conditions:
+
+- *Driver Script Parameters (=run_velde_model.py=)*:
+  MANTIS supports human-readable strings parsed via Python's =pint= physical unit library:
+  - Lengths and depths: ="0.5 m"=, ="50 cm"=
+  - Times and time steps: ="0.5 kyr"=, ="1 year"=, ="24 hours"=
+  - Sedimentation rates: ="0.2 cm/yr"=, ="1 mm/a"=
+  - Bioturbation coefficients: ="4 cm^2/year"=, ="1e-9 m^2/s"=
+
+- *Boundary Conditions (=species.py=)*:
+  - *Dissolved Solutes (=type: "dissolved"=)*:
+    Upper boundary concentrations can be specified as a numeric float or a unit string. The default numeric input is *$\text{mmol/L}$* (which is identical to $\text{mol/m}^3$ or $\text{mM}$).
+    #+BEGIN_EXAMPLE
+    "bc": {"top": 28.2, "type": "dissolved"}         # 28.2 mmol/L (seawater sulfate)
+    "bc": {"top": "280 umol/L", "type": "dissolved"} # parsed automatically to 0.28 mmol/L
+    #+END_EXAMPLE
+  - *Particulate Solids (=type: "particulate"=)*:
+    Deposition at the sediment-water interface is specified as a depositional surface flux:
+    #+BEGIN_EXAMPLE
+    "bc": {"top": "12 umol/(cm^2 * yr)", "type": "particulate"}
+    #+END_EXAMPLE
+    MANTIS automatically converts this to internal flux units ($\text{mol}/(\text{m}^2 \cdot \text{s})$) during initialization.
+
+** 2. How Units Are Handled Internally by the Solver
+
+Under the hood, MANTIS standardizes all transport and reaction PDEs into SI-derived volumetric units:
+\[
+\text{Internal Concentration Unit} = \mathbf{mol/m^3} \quad (\equiv 1\ \text{mmol/L} \equiv 1\ \text{mM} \equiv 1000\ \mu\text{mol/L} \equiv 1\ \mu\text{mol/cm}^3)
+\]
+
+Crucially, concentrations are defined *per unit volume of their respective phase*:
+1. *Liquid Solutes*: Expressed per volume of porewater ($\text{mol / m}^3_{\text{liquid}} = \text{mmol / L}_{\text{porewater}}$). The bulk sediment inventory is $\phi \cdot C_{\text{liquid}}$.
+2. *Solid Minerals*: Expressed per volume of pure solid sediment ($\text{mol / m}^3_{\text{solid}} = \text{mmol / L}_{\text{solid}}$). The bulk sediment inventory is $(1 - \phi) \cdot C_{\text{solid}}$.
+3. *Phase Transfer & Reactions*: Whenever a reaction couples a solid phase and a liquid phase (for example, $\text{Fe}^{2+} + \text{HS}^- \to \text{FeS}$), MANTIS scales the source and sink terms with the appropriate phase ratio ($(1-\phi)/\phi$ or $\phi/(1-\phi)$) so that mass is strictly conserved.
+4. *Reaction Rates*: Solved internally in $\text{mol} / (\text{m}^3_{\text{phase}} \cdot \text{s})$.
+5. *Depths and Transport*: Depth $z$ is in meters ($\text{m}$), time $t$ in seconds ($\text{s}$), and diffusion coefficients in $\text{m}^2/\text{s}$.
+
+** 3. Output Units in Result Files (=.csv=)
+
+When the simulation completes or exports data (=<model_name>.csv=):
+- =c_<species>=: Reported directly in *$\text{mmol/L}$* (numerically equivalent to $\text{mol/m}^3$):
+  - Solutes (e.g., =c_SO4=, =c_O2=, =c_TS2=) are in *$\text{mmol / L of porewater}$*.
+  - Solids (e.g., =c_FeS=, =c_Fe3=, =c_POC_slow=) are in *$\text{mmol / L of pure solid}$*.
+- =f_<species>=: Net production/consumption reaction rates in *$\text{mol} / (\text{m}^3 \cdot \text{s})$*.
+- =d_<species>=: Isotope delta values (e.g., =d_SO4=, =d_FeS=) in *$\permil$* (per mil relative to VCDT).
+- =z=: Depth below sediment-water interface in *meters* ($\text{m}$).
+- =phi= and =w=: Porosity (fraction, dimensionless) and burial velocity ($\text{m/s}$).
+
+** 4. Converting Solid Concentrations to Standard Geochemical Units
+
+Geochemists typically report solid mineral abundances as dry-sediment mass fractions ($\text{wt}\%$) or mass-normalized molar concentrations ($\mu\text{mol/g}$). MANTIS includes built-in conversion utilities in =mantis.diff_lib=:
+
+*** A. Converting to $\mu\text{mol / g}$ (micromoles per gram of dry sediment)
+To convert a solid concentration $C_{\text{solid}}$ ($\text{mmol/L of solid} = \mu\text{mol/cm}^3_{\text{solid}}$) to $\mu\text{mol/g}$ of dry sediment, divide by the mineral grain density $\rho_{\text{sed}}$ (typically $2.6\ \text{g/cm}^3$ for siliciclastic sediments):
+\[
+C_{\mu\text{mol/g}} = \frac{C_{\text{solid}}}{\rho_{\text{sed}}}
+\]
+In Python:
+#+BEGIN_SRC python
+from mantis.diff_lib import solid_conc_to_umol_per_g
+
+# df.c_FeS is in mmol/L of solid; density in g/cm^3
+c_fes_umol_g = solid_conc_to_umol_per_g(df.c_FeS, d=2.6)
+#+END_SRC
+
+*** B. Converting to Dry Weight Percent ($\text{wt}\%$)
+To convert $C_{\text{solid}}$ to weight percent of dry sediment matrix given molecular weight $M_w$ ($\text{g/mol}$):
+\[
+\text{wt}\% = \frac{C_{\text{solid}} \cdot M_w}{\rho_{\text{sed}} \cdot 10^4}
+\]
+In Python:
+#+BEGIN_SRC python
+from mantis.diff_lib import solid_conc_to_wt_percent
+
+# Example: FeS (Mw = 87.91 g/mol, density = 2.6 g/cm^3)
+fes_wt_pct = solid_conc_to_wt_percent(df.c_FeS, mw=87.91, d=2.6, phi=df.phi)
+#+END_SRC
+
 * Step 2: Defining Kinetic Constants (=kinetic_constants_*.py=)
 
 The kinetic constants file defines how fast reactions occur and the affinity thresholds of microbial communities.
@@ -349,6 +432,12 @@ if __name__ == "__main__":
             "BI0": 0.0,                # Set to 0.0 to disable; or e.g. "20 /year"
             "depth": "0 cm",
         },
+
+        # Spatial grid & reaction zone refinement (optional, defaults provided)
+        initial_spacing="0.1 mm",      # Spacing at sediment-water interface (z=0)
+        reaction_zone=("0.1 cm", "1.0 cm"), # Critical depth window of sharp redox fronts
+        reaction_zone_spacing="0.05 mm",    # Dense, uniform spacing in the reaction zone
+        max_spacing="1.0 cm",          # Coarser spacing in deep sediment
     )
 
     # 3. Allow CLI overrides (e.g. running --video from the terminal)
@@ -368,6 +457,53 @@ if __name__ == "__main__":
     result.plot_summary()
 #+END_SRC
 
+** Spatial Grid Configuration & Reaction Zone Resolution
+
+Diagenetic models must resolve spatial scales ranging from sub-millimeter oxygen penetration depths to deep sediment columns spanning decimeters to hundreds of meters. A uniform fine grid across a 50-meter column would require millions of cells and slow down calculations unnecessarily.
+
+MANTIS solves this using an adaptive geometric-mesh builder (=make_grid2=) that refines where steep gradients occur and expands into the deep sediment.
+
+*** 1. How Grid Generation Works (=make_grid2=)
+The grid structure is divided into four seamless stages from the sediment surface to depth:
+1. *Surface Section*: Starts at =initial_spacing= and geometrically refines cells downward toward =reaction_zone[0]=.
+2. *Reaction Zone Section*: Maintains a constant, ultra-fine cell size (=reaction_zone_spacing=) across the depth interval =reaction_zone = (z_start, z_end)=.
+3. *Coarsening Section*: Below the reaction zone, cell size expands geometrically by factor $r = 1.05$ per cell.
+4. *Deep Uniform Section*: Once cell size reaches =max_spacing=, the remainder of the domain down to =max_depth= uses uniform large cells.
+
+*** 2. The Geochemical Importance of Reaction Zone Resolution
+Why does grid spacing in the reaction zone matter so much?
+Fast bimolecular redox reactions—such as ferrous iron oxidation ($\text{Fe}^{2+} + \text{O}_2 \to \text{Fe}^{3+}$) or sulfide oxidation—occur across exceedingly narrow interfaces. The physical reaction front width $\delta_{\text{phys}}$ is governed by the balance between molecular diffusion and reaction kinetics:
+\[
+\delta_{\text{phys}} \sim \sqrt{\frac{D_{\text{eff}}}{k \cdot C_{\text{scale}}}}
+\]
+For transport-controlled reactions with large kinetic constants ($k = 10^7\ \text{M}^{-1}\text{s}^{-1}$), $\delta_{\text{phys}}$ is often *under $0.05\text{ mm}$*.
+
+If your numerical grid cell size $\Delta z$ is larger than $2 \delta_{\text{phys}}$, the local Damk\ouml{}hler number is large ($Da_{II} \gg 1$). The finite-volume discretization cannot resolve the sharp counter-gradients, producing a numerical artifact called *artificial reactant coexistence*:
+- $\text{Fe}^{2+}$ and $\text{O}_2$ artificially overlap in the same cell.
+- Reactants diffuse past each other instead of reacting completely at the interface.
+- Apparent reaction rates become smeared over several millimeters to centimeters.
+
+*** 3. Automated Coexistence Diagnostic
+MANTIS automatically runs a post-simulation front diagnostic (=check_reactant_coexistence=) at the end of every run. If any reaction front is under-resolved, MANTIS outputs a clear warning:
+#+BEGIN_EXAMPLE
+[WARNING: Numerical Reactant Co-existence Detected]
+  Reaction: 'Fe2 Oxidation by O2' (fe2 + O2)
+  Front location (peak): z = 0.21 cm (depth cell index: 21)
+  Local grid resolution: dz = 0.10 mm
+  Estimated physical front width: 0.01 mm
+  Front cell span (N_cells): 6 cell(s)
+  Reasons: Local grid cell dz (0.10 mm) > 2x physical front width (0.01 mm)
+  --> Action recommended: In make_grid2(), refine the mesh around z = [0.19, 0.23] cm to reaction_zone_spacing <= 0.01 mm.
+#+END_EXAMPLE
+
+When you see this warning, simply update your driver script's =model.configure()= with the recommended reaction zone window and spacing:
+#+BEGIN_SRC python
+model.configure(
+    reaction_zone=("0.15 cm", "0.30 cm"),
+    reaction_zone_spacing="0.01 mm",
+)
+#+END_SRC
+
 * Step 5: Designing Plot Layouts (=plot_layout.py=)
 
 Geochemists usually want to see:

mantis_rtm-0.1.2/examples/velde_et_al_2016/kinetic_constants_fast.py

@@ -0,0 +1,108 @@
+"""Define reaction constants.
+
+Note, Velde et al likely have a typo in the FeS equilibrium constant.
+Rickard (2006) defines two reaction constants, one with Ksp = 3.5
+and the other with Ksp = - 3.5. Here we use the latter since otherwise
+we would never precipitate FeS unless H2S > 1 mmol/l
+"""
+
+from typing import Any
+
+
+def get_reaction_constants(
+    pH: float, phi: float | Any, k_values: dict = {}
+) -> dict:
+    """Convert reaction_constants into model units.
+
+        It is assumed that the reaction constants are in phase specific units.
+        This can be tricky, as Velde et al, state that their k-values are in
+        bulk units, but then they convert it before using (see Table 3). E.g.
+        they write:
+
+       (1−ϕ)⋅kSIR⋅[FeOOH]⋅[HS−]
+    ​
+        which suggests that the (1−ϕ) is used to convert FeOOH from solid
+        phase concentration to bulk concentration. Since this code
+        tracks all concentrations in phase specific units, converting the
+        k-value by deviding by (1−ϕ), would cancel out, and we can use the
+        k-value as published.
+    """
+    import pint
+
+    ureg = pint.UnitRegistry()
+    Q_ = ureg.Quantity
+
+    if hasattr(phi, "value"):
+        phi = phi.value
+
+    velde: dict = {
+        "POC_fast": [10, "1/year", "1/second"],  # highly reactive OM
+        "POC_slow": [0.1, "1/year", "1/second"],  # reactive OM, Velde et al
+        "Fe2_p_eq": [
+            696,
+            "dimensionless",
+            "dimensionless",
+        ],  # sorbed vs Fe2+ Fe2+ liq.
+        "FeS2_O2": [
+            1e-10,
+            "m^3/(mol*second)",
+            "m^3/(mol*second)",
+        ],  # FeS2 + O2 -> SO4, Halevy et al
+        "FeS_S0": [  # FeS + S0 -> FeS2
+            5e-8,
+            "m^3/(mol*second)",
+            "m^3/(mol*second)",
+        ],  # FeS + HS -> FeS2
+        "FeS_TS2": [
+            5e-8,
+            "m^3/(mol*second)",
+            "m^3/(mol*second)",
+        ],  # FeS + H2S -> FeS2, at 10C -> notes.org
+        "Hplus": [10 ** (-pH), "mol/l", "mol/m^3"],
+        # Oxidation reactions after Velde at eal 2016
+        "TS2_O2": [1e7, "cm^3/(umol*year)", "m^3/(mol*second)"],
+        "Fe3_hs": [
+            494,
+            "cm^3/(umol*year)",
+            "m^3/(mol*second)",
+        ],  # check with halevy
+        "FeS_O2": [1e7, "cm^3/(umol*year)", "m^3/(mol*second)"],
+        "Fe2_O2": [1e7, "cm^3/(umol*year)", "m^3/(mol*second)"],
+        # "Fe2p_ox": [1e73, "cm^3/(umol*year)", "m^3/(mol*second)"],
+        "S0_O2": [4e7, "cm^3/(umol*year)", "m^3/(mol*second)"],
+        # Iron sulfide reactions after Velde at eal 2016
+        "FeS_isp": [
+            1e4,
+            "umol/((cm^3*year))",
+            "mol/(m^3 *second)",
+        ],  # FeS precipitation
+        "FeS_isd": [3, "1/year", "1/second"],  # FeS dissolution
+        "FeS_sp": [  # FeS equilibrium constant
+            10**-3.5,
+            "mol/l",
+            "mol/m^3 ",
+        ],
+        # S0 disproportionation rate (first-order in S0)
+        "S0_dispro": [50, "1/year", "1/second"],
+    }
+
+    for k, v in velde.items():
+        k_values[k] = Q_(f"{v[0]} {v[1]}").to(f"{v[2]}").magnitude
+
+    return velde, k_values
+
+
+if __name__ == "__main__":
+    import pint
+
+    ureg = pint.UnitRegistry()
+    Q_ = ureg.Quantity
+
+    velde, k_values = get_reaction_constants(7.5, 0.8)
+    ureg = pint.UnitRegistry()
+    for k, v in velde.items():
+        n = Q_(f"{v[0]} {v[1]}").to(f"{v[2]}")
+        print(f"{k} = {n.magnitude:.2e} [{n.units:~P}]")
+
+    print(f"k.FeS_sp * k.Hplus: {k_values['FeS_sp'] * k_values['Hplus']:.2e}")
+    print(f"k.Hplus: {k_values['Hplus']:.2e}")

{mantis_rtm-0.1.1.dev0 → mantis_rtm-0.1.2}/examples/velde_et_al_2016/kinetic_constants_slow.py

@@ -76,7 +76,7 @@ def get_reaction_constants(
             "umol/((cm^3*year))",
             "mol/(m^3 *second)",
         ],  # FeS precipitation
-        "FeS_isd": [3/10, "1/year", "1/second"],  # FeS dissolution
+        "FeS_isd": [3, "1/year", "1/second"],  # FeS dissolution
         "FeS_sp": [  # FeS equilibrium constant
             10**-3.5,
             "mol/l",

{mantis_rtm-0.1.1.dev0 → mantis_rtm-0.1.2}/examples/velde_et_al_2016/plot_layout.py

@@ -168,7 +168,7 @@ def get_layout(df):
                 "xlim": (1e-4, None),
                 # "ylim": (-15, 75),
                 # "right": [[df.d_h2s, "d_h2s", {"color": "C1"}]],
-                "options-left": ["broken_axis(-45, -40, 20, 25)"],
+                "options-left": ["broken_axis(-45, -37, 20, 30)"],
             },
         })