Volumential (VOLUME poteNTIAL) evaluates volume potentials over box-shaped domains with the Fast Multipole Method: the far field is an ordinary particle FMM over the volume quadrature nodes, while the near field — where the integrand is singular or near-singular and point quadrature will not resolve it at a usable order — is read from precomputed, symmetry-reduced interaction tables. Laplace, Helmholtz and Yukawa are supported in 2D and 3D, for potential and target gradient, on uniform and adaptively refined 2:1-balanced trees.
A release is a Git tag, installed from GitHub with pip or uv. The first is
2026.1:
pip install "volumential @ git+https://github.com/xywei/volumential@v2026.1"
uv pip install "volumential @ git+https://github.com/xywei/volumential@v2026.1"@main or @<commit> installs the same way. Either brings in the inducer
packages Volumential is built on (arraycontext, boxtree, loopy,
meshmode, modepy, pymbolic, pytential, pytools, sumpy) at the Git
commits pyproject.toml pins, which are the ones CI tests, and everything
else from PyPI, pyopencl 2026.1.4 or later among it. It needs git, a C
compiler for the extension pytential builds, and an OpenCL runtime:
conda-forge's pocl as below, or a vendor ICD. PyPI's pyopencl wheel finds
conda-forge's PoCL through OCL_ICD_VENDORS, as below; on macOS it cannot
load PoCL at all (Installation has the way around that).
The fmmlib extra, "volumential[fmmlib] @ git+...", adds the FMMLib
far-field backend. It builds pyfmmlib from Git, at the commit of its
v2026.1 tag, so it needs a Fortran compiler with OpenMP. Without one, leave
the extra out and install pyfmmlib 2026.1 or later from PyPI's wheels
(Linux x86_64) or conda-forge instead.
Releases are not on PyPI, which rejects any package that names a Git
dependency, and the pins have to be Git dependencies: pytential has no
installable release there, and sumpy, boxtree, meshmode and
arraycontext only years-old ones (#211).
To work on Volumential, clone it and sync the environment from uv.lock:
micromamba create -n volumential-dev -c conda-forge -c nodefaults \
python=3.12 pocl scipy numpy
eval "$(micromamba shell hook -s bash)" && micromamba activate volumential-dev
export UV_PROJECT_ENVIRONMENT="$CONDA_PREFIX"
export OCL_ICD_VENDORS="$CONDA_PREFIX/etc/OpenCL/vendors"
git clone https://github.com/xywei/volumential.git && cd volumential
uv sync --extra test(micromamba activate is a shell function, hence the hook;
UV_PROJECT_ENVIRONMENT is what points uv at the conda environment, without
which uv builds a .venv with no OpenCL runtime; OCL_ICD_VENDORS is what
points the ICD loader of PyPI's pyopencl wheel, which uv sync installs, at
the environment's PoCL. See Installation.)
Released wheels of the inducer stack have shipped defects that corrupt
adaptive-tree results silently, which is another reason those dependencies
are pinned to Git commits. Run the traversal sanity check before trusting a
fresh environment — see Installation.
export PYOPENCL_CTX=portable:0 # otherwise the device is picked for you
uv run python examples/laplace2d.pyThat evaluates a 2D Laplace volume potential against a manufactured Gaussian
solution and prints the error. VOLUMENTIAL_EXAMPLE_SMOKE=1 runs the same
thing in seconds at reduced order, as a setup check rather than an accuracy
result. The first tutorial shows the computed result and explains
each stage of the program.
The site is published at https://xywei.github.io/volumential/, built from
doc/source and deployed from main by the Docs Pages
workflow on every merge. Every pull request against main gets a strict build
and a downloadable HTML preview from the Documentation CI job. The earlier
mirror at xiaoyu-wei.com is superseded by this site.
- Getting started — install, a first volume potential, device selection
- Examples — visual gallery first, then run/cost/cache details
- User guide — the volume-FMM workflow, near-field tables and their symmetry reduction, table build routing, derivatives, the Helmholtz split, what is validated
- Design notes — windowed singular channels and certified assembly, ORBIT canonicalization
- Benchmarks and reproducibility — what a measurement of this library must record to be worth quoting
- API reference — one page per module
- Development — contributing, tests and markers, CI and the review bots, release and versioning
- Changelog
Build it locally with uv sync --extra test --extra doc and
sphinx-build -W --keep-going -b html doc/source doc/build/html.
volumential/— library sourcetest/— pytest suite (tiers and markers)examples/— maintained end-to-end examplesdoc/— this documentationDEVELOPMENT.md— environment provisioning and day-to-day workflowruff.toml— the single lint configuration
Parts of this codebase, its tests and documentation were written or revised with AI assistance, and pull requests are reviewed by the maintainer and by automated code-review services. The full statement is AI-assisted development in the documentation.
Volumential is developed and released under the terms of the MIT license, though it also makes use of third-party packages under their own licensing terms. See the LICENSE file for details.
We would like to thank people and organizations that contributed to or supported the Volumential project, without whom the project would not have been possible.
The research that started the Volumential project was supported by the National Science Foundation under grant DMS-1654756, and by the Department of Computer Science at the University of Illinois at Urbana-Champaign. Part of the work was performed while the authors were participating in the HKUST-ICERM workshop "Integral Equation Methods, Fast Algorithms and Their Applications to Fluid Dynamics and Materials Science" held in 2017.
Thanks very much to the Department of Mathematics at Hong Kong University of Science and Technology for funding Xiaoyu Wei to work on the project as a PhD student under the Postgraduate Studentship and the Overseas Research Award.
The project's name volumential courtesy of Andreas Klöckner.