PyMHM

pymhm couples user-defined local and global variational equations through explicitly oriented trace coordinates. Declare the forms, choose a local provider, then call assemble or solve. Scalar, vector and mixed fields use the same interface; a local operator can itself be another multiscale problem. NumPy/SciPy coefficients and optional FEniCS/UFL forms share this contract. Basix supplies finite-element bases and tabulation.

Version 1.0.0 is an official release of PyMHM. Built-in workflows include triangular and polygonal meshes, Cartesian quadrilaterals, tetrahedra, affine prisms, star-shaped polyhedra and mapped hexahedra. Available equations and approximation spaces depend on the geometry; the documentation states each verified scope and distinguishes it from extensions described in the literature.

Installation

Use Python 3.11–3.13 on Linux, macOS or Windows:

python -m pip install pymhm

The base package includes NumPy, SciPy and Basix. Optional extras add CPU AMG, PARDISO, MPI, CUDA solvers, meshing or visualization; for example, python -m pip install "pymhm[amg]" adds PyAMG. The installation guide covers virtual environments, Windows commands, upgrades and native backend requirements.

Quick start

from pymhm import Equation, LocalEquations, MultiscaleProblem, solve

def local(cell):
    return LocalEquations(
        a=[[2.0]], L=[1.0], b=[[1.0]], c=[[-1.0]],
        d=[[1.0]], dofs=[0],
    )

problem = MultiscaleProblem(
    Equation(0, 0), local, items=[0], trace_size=1, coarse_sizes=(0,),
)
solution = solve(problem)
print(solution.trace, solution.fields)  # lambda = u = 1/3

This coefficient example declares $2u+\lambda=1$ and $-u+\lambda=0$. The variational guide shows how local and global UFL forms, retained modes, physical constraints and recursive problems fit this same interface. It states the supported compilation and elimination limits. The vector UFL and three-level hierarchy notebooks provide direct vector forms and recursive coefficient verification.

The introductory scalar, vector and provider tutorials use small executable problems. They cover primal and mixed H(div) locals, explicit interface conventions, physical gauges and custom local solvers.

The wheel contains every pymhm runtime module, typing files and distribution metadata. The source distribution contains src/pymhm, pyproject.toml, README.md, LICENSE, backend-required .gitignore and generated package metadata. Documentation, notebooks, examples, tests, scripts, benchmarks, recipes and environment files remain in the repository and are excluded from both archives. All implemented capabilities ship with the package; optional native backends require their separate dependencies.

The Windows guide describes native portable-core execution, SciPy/PyPardiso selection, process workers and installed-wheel checks. The current native FEM/PETSc profiles use Linux or macOS; WSL2 provides those environments on a Windows host.

Verified discretizations and integrations

The predefined physical formulations live in the private _legacy.models package and are imported from their implementation owners. Their numerical records and stored coefficient contracts document the verified discretizations, materials and boundary data; they do not qualify arbitrary user-defined forms.

• Primal Pk, general triangular RT/BDM and enriched rectangular RT Darcy; anisotropic permeability, mixed boundary data and physical pure-Neumann gauges.
• Cartesian Qk Darcy, discrete point wells, and SPE10 Model 2 slices with explicit units, checked downloads and geometric material-interface integration.
• Taylor–Hood and residual-consistent equal-order USFEM Stokes–Brinkman/Oseen, including spatially variable tensor resistance and prescribed convection.
• Displacement–pressure GaLS elasticity through the incompressible limit, Taylor–Hood elasticity, and weakly symmetric enriched BDM/RT stress elasticity. All local rigid motions, material derivatives and physical constraints are explicit.
• Conservative variable-coefficient RAD with Galerkin or consistent SUPG locals, high-order heat diffusion, backward Euler and Darcy/dispersion coupling.
• Polygonal local partitions and star-shaped polyhedra with original polygonal face spaces; tetrahedral Pk operators, tetrahedral/prismatic mixed H(div) families, and mapped hexahedral RT Darcy fields.
• MHM–MsHHO constructions, recursive local problems, material-fitted integration, moment reconstruction, and equation-specific error estimation and adaptation.
• MH²M pressure traces, Robin-local MH, residual Petrov–Galerkin MHM and unusual reaction–diffusion stabilization, with independent finite element checks.
• Three-dimensional Taylor–Hood/USFEM flow, GaLS elasticity, MsHHO and tetrahedral RT reconstruction with dimension-dependent estimator spaces.
• Full anisotropic mixed stress on polygonal macrocells, arbitrary planar material cuts and independently controlled normal/interior H(div) orders.
• Three-dimensional weakly symmetric AFW stress elasticity, including the incompressible limit, and Newmark MHM elastodynamics with local subcycling.
• Complex Helmholtz waves with absorbing boundaries and perfectly matched layers; transient Maxwell TM and three-dimensional vector fields with explicit CFL controls.
• Independent face partitions and degrees, including continuous subface traces; physical local kernel constraints, source/trace factorization reuse and conservative RT0 flux equilibration.
• User-defined UFL local operators, explicit local/global form descriptions and callable providers; optional mesh import/export with physical tags.
• Basix reference elements, nodal simplex/tensor bases and RT/BDM tabulation, with explicit native basis ordering, transformations and coefficient digests.
• PyVista/VTK export and rendering, including broken finite-element fields and actual macro-mesh overlays (python -m pip install "pymhm[visualization]").
• SciPy, PETSc, PARDISO, CuPy and cuDSS solvers; CPU PyAMG and optional GPU AmgX. AMG local Neumann solves use a compatible SPD complement.
• Deterministic serial/thread/process local execution with bounded batches and native thread limits; the coordinator reduces shared-face contributions in cell order and retains mesh/DOF metadata for reconstruction.
• Distributed PETSc/MPI assembly, reusable offline operators, resident GPU P1 batches and augmented CPU/GPU AMG saddle preconditioners.

The scientific scope maps each article to implemented paths, verification evidence and remaining reproduction limits. The stated geometry, space compatibility and estimator hypotheses are part of each capability. See theory, literature, verification and performance for assumptions and evidence.

The visual case gallery compares computed fields with analytical references, error maps, profiles and convergence expectations. The MSL field comparison checks primal Darcy fields against MSL_MHM with MSL_CG and MSL_Core. The NeoPZ comparison checks RT0/P0 fields against NeoPZ and distinguishes that assembly from Labmec/MHM's higher-order controller. Each case records the actual spaces and boundary conventions used in the comparison. The GaLS elasticity comparison matches MSL fields over five mesh levels and three local polynomial degrees. The SPE10 case identifies the published layers, spaces and boundary conditions and compares pressure profiles directly with article data. The quarter-five-spot case includes point wells, an analytical series, and MSL/NeoPZ comparisons for a low-permeability obstacle.

Reproducible calculations

Git contains sources, scientific JSON records, three compact SPE10 input layers and the selected figures used by the published documentation. Large computed fields and intermediate outputs are generated locally and stay outside Git. An ordinary package installation and core tests require no archived outputs. ROADMAP.md sets implementation and validation priorities, dependencies and acceptance criteria for the next milestones.

Generate only the cases being evaluated, using their documented public commands; then check their numerical acceptance before plotting or reporting reproduction. The notebook catalogue groups examples by physical problem and lists their methods. Start with a small analytical example:

pixi run --locked -e notebooks notebooks-run darcy/primal_galerkin.ipynb
pixi run --locked -e notebooks notebooks-run flow/introductory_methods.ipynb

Executed copies retain the problem folders under build/notebooks. Historical numeric IDs also select their notebooks. Analytical patches introduce the API; they do not replace a published benchmark reproduction.

Before executing a notebook that reads computed fields, inspect its required local inputs and generate the corresponding calculations:

pixi run -e notebooks python scripts/notebook_data.py --notebook 68
pixi run -e notebooks python scripts/notebook_data.py --notebook 68 --check

Missing fields are reported explicitly. Neither notebooks nor documentation automatically download computed results. The publication figures included in Git support documentation builds from a checkout. Regenerating a scientific case or replaying its fields requires its documented calculations and local outputs; package builds and core tests do not depend on those outputs.

Development

pixi run --locked -e test-core lint
pixi run --locked -e test-core typecheck
pixi run --locked -e test-core test-cov
pixi run -e fem test-fem
pixi run -e meshing test-meshing
pixi run -e packaging build
pixi run -e packaging check-dist

After generating and accepting the selected scientific cases, execute their notebooks and run pixi run -e docs docs-check. Inspect the rendered figures and MathJax in the browser. CI checks documentation markup; scientific acquisition, notebook execution and full gallery generation require their separate acceptance.

The portable test-core environment supports Linux, Windows and macOS. The complete test environment includes the native CPU and GPU integrations and requires a Linux CUDA host with two NVIDIA devices. Its pinned AmgX setup and mandatory dependency checks are described in the development guide. Both suites use all available CPU workers and isolate tests marked serial.

CI enforces at least 99% line and branch coverage independently on Linux x86-64, Windows x86-64 and macOS Apple Silicon (ARM64). Executable notebooks and analytical PDE examples are available in the repository. Optional dependency contracts and actual native-backend integrations are reported separately.

Dedicated Tests, Lint and Quality and Docs workflows run independently on pull requests and main-branch pushes. The complete two-GPU suite is opt-in through manual dispatch. On a validated release tag, Publish to PyPI validates metadata and runs Tests, Quality and Docs checks in parallel, then publishes the checked distributions to PyPI, creates the GitHub Release and deploys the documentation to GitHub Pages. The Docs workflow also supports manual publication from main or a release tag by enabling its publish input. Maintainers configure the PyPI trusted publisher for publish-pypi.yml, Pages with GitHub Actions as its source and the github-pages environment to accept release tags; see development.

Prepare release notes and synchronize current versions with pixi run --locked -e release release-prepare VERSION, after running release-fetch in the same environment. The task uses git-cliff and preserves handwritten notes. Official releases use X.Y.Z versions and matching vX.Y.Z tags; for example, prepare 1.1.0 and tag v1.1.0. Use --initial only when no canonical release tag exists in the fetched main-branch history.

Licensed under LGPL-2.1-only. Citation metadata is in CITATION.cff.

Institutional Support

PyMHM is developed by the Innovative Parallel numErical Solvers (IPES) research group and receives institutional support from the Laboratório Nacional de Computação Científica (LNCC), a research unit of the Ministério da Ciência, Tecnologia e Inovação (MCTI), Brazil.