MicroPoroChemoMechanics

Julia ecosystem for the coupled chemo-mechanics of porous reactive media

Computational chemistry · Mean-field homogenization · Adaptive cubature · Structured tensors · Reactive transport · Poromechanics

MicroPoroChemoMechanics is a family of Julia packages for the multiscale modelling of porous reactive materials — from molecular-level thermodynamic equilibrium to macroscopic poromechanical response. Every package is ForwardDiff-compatible, dimensionally aware via DynamicQuantities where relevant, and designed to compose cleanly with the SciML ecosystem (Optimization, OrdinaryDiffEq, NonlinearSolve, Integrals, …).

The stack is released through the dedicated MPCM-Registry. Downstream users add the registry once before installing any package:

pkg> registry add https://github.com/MicroPoroChemoMechanics/MPCM-Registry

Formula parsing, species and reaction handling, stoichiometric matrix construction, thermodynamic equilibrium via Gibbs free energy minimisation, dilute-solution / Debye-Hückel / Davies activity models, ideal and Redlich-Kister solid solutions, kinetics (Parrot–Killoh and transition-state theory), and interoperability with ThermoFun JSON and PHREEQC databases. Initially focused on cement chemistry but applicable more broadly.

Structured tensor types (TensISO, TensWalpole, TensOrtho, TensTI, …) with base-1 indexing and symmetry-aware storage. Tensor calculations of any order and dimension in arbitrary coordinate systems, symbolic (SymPy, Symbolics) and numerical. Shared tensor-algebra backbone across the MicroPoroChemoMechanics stack.

Hill polarisation tensors for ellipsoidal inclusions and infinite cylinders, crack-opening-displacement tensors with stress and displacement intensity factors for flat (elliptic and ribbon) cracks, second-order Hill tensors for transport problems, and layered-sphere composite models — under a common abstraction hierarchy and dispatch mechanism. Also ships MeanFieldHom.Elliptic, an internal type-generic submodule for Legendre and Carlson elliptic integrals.

A forthcoming package will integrate the chemistry stack (ChemistryLab.jl + OptimaSolver.jl) with effective-property predictions from mean-field homogenization (MeanFieldHom.jl + TensND.jl) into a coupled reactive-transport / poromechanics framework, suitable for durability and degradation studies of cementitious and geological porous media. Repository to be announced.

Lower-level libraries used internally by the main packages above. They are designed to be reusable in their own right and can be installed and cited standalone from the MPCM-Registry.

Julia-native primal-dual interior-point solver for Gibbs-energy minimisation under linear equality and bound constraints. Used by ChemistryLab.jl as the default equilibrium solver. Schur-complement Newton steps exploit the diagonal Hessian structure; filter-based line search (Wächter & Biegler 2006); implicit differentiation provides post-solve sensitivities (∂n*/∂b, ∂n*/∂(μ⁰/RT)); warm-start support. Julia port of the Optima C++ library by Allan Leal (ETH Zürich).

Pure-Julia port of the DECUHR algorithm (Espelid & Genz, 1994) for automatic adaptive integration of functions with vertex singularities over hyper-rectangular regions. Used by MeanFieldHom.jl as the adaptive-cubature backend for the anisotropic Hill and crack kernels. Exposed as a pluggable algorithm for the SciML Integrals.jl solver stack.

ChemistryLab.jl
  └── OptimaSolver.jl       (weakdep — equilibrium solver backend)

MeanFieldHom.jl
  ├── DECUHR.jl             (adaptive cubature backend)
  └── TensND.jl             (structured tensors)

[future] Reactive transport package
  ├── ChemistryLab.jl       (equilibrium + kinetics)
  └── MeanFieldHom.jl       (effective transport properties)

TensND.jl, DECUHR.jl and OptimaSolver.jl are standalone and can be used outside the MPCM context.

using Pkg
Pkg.Registry.add(RegistrySpec(url="https://github.com/MicroPoroChemoMechanics/MPCM-Registry"))
Pkg.add(["ChemistryLab", "OptimaSolver", "MeanFieldHom", "DECUHR", "TensND"])

# Compute a thermodynamic equilibrium (Portlandite dissolution)
using ChemistryLab, OptimaSolver
# … see ChemistryLab.jl documentation for full examples

# Compute a Hill polarisation tensor for a sphere in an isotropic matrix
using MeanFieldHom, TensND
E, ν = 210e3, 0.3
λ = E * ν / ((1 + ν) * (1 - 2ν));  μ = E / (2 * (1 + ν))
C₀ = TensISO{3}(3 * (λ + 2μ / 3), 2μ)
P  = hill_tensor(Ellipsoid(1.0), C₀)

Developed by Jean-François Barthélémy and Anthony Soive, both researchers at Cerema in the research unit UMR MCD. See each package's CITATION.cff for per-package authorship and contributors.

Parts of this codebase were developed with the assistance of Anthropic's Claude Code, under the authors' review and validation.

See the LICENSE file of each repository.

Main packages:

• ChemistryLab.jl — LGPL-2.1-or-later
• TensND.jl — MIT
• MeanFieldHom.jl — MIT

Backend dependencies:

• OptimaSolver.jl — LGPL-2.1-or-later
• DECUHR.jl — MIT (Julia port; the upstream Fortran routines of Espelid & Genz carry their own copyright — see NOTICE)