Skip to main content

MANTIS: A Python framework to solve extremely stiff reaction-transport equations using a Monolithic Assembly of Nonlinear Transport Interactions Solver (MANTIS)

Build Status PyPI Version Python Versions License: AGPL-3.0-or-later

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 provides:

  • 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, and an integrated plotting system that supports 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 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.

Installation

MANTIS requires Python 3.12 or newer. Clone the repository and install in editable mode:

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 quick-start tutorial is available in the ./docs folder

Running Tests

Run the unit test suite using pytest:

pytest

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

Metadata

Release files for mantis-rtm 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mantis-rtm 0.4.0
File Size Uploaded Provenance Actions
mantis_rtm-0.4.0.tar.gz 1.2 MB With provenance Details for mantis_rtm-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mantis-rtm 0.4.0
File Interpreter ABI Platform Actions
mantis_rtm-0.4.0-py3-none-any.whl Python 3 none any Details for mantis_rtm-0.4.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / mantis_rtm-0.4.0.tar.gz

Download URL mantis_rtm-0.4.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
44111c764b8561638217d789774fe0c3c9a5d26d5e7570508256f7cdb087d325
BLAKE2b-256 checksum
How to use checksums
db4978a7e10229a66a397ca4679ce23cf9e638d8d7b077debee1bcf867a53b40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / mantis_rtm-0.4.0-py3-none-any.whl

Download URL mantis_rtm-0.4.0-py3-none-any.whl
Size 142.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0f94c1395b5aa0b5f390f9b52fc52956388ea3879a0a5d8b1c942fa24e98b91a
BLAKE2b-256 checksum
How to use checksums
df40f03e5da4069974d155e1e5048c85a8d2f91ee99777466976f8c10dde4b2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for mantis-rtm 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mantis_rtm-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page