8000 GitHub - xywei/volumential: Fast volume potential computation via FMM. · GitHub
[go: up one dir, main page]

Skip to content

About

Fast volume potential computation via FMM.

Resources

Stars

5 stars

Watchers

1 watching

Forks

Repository files navigation

Volumential

CI License: MIT Python 3.12

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.

Install

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.

Run

export PYOPENCL_CTX=portable:0        # otherwise the device is picked for you
uv run python examples/laplace2d.py

That 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.

Documentation

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.

Repository layout

  • volumential/ — library source
  • test/ — pytest suite (tiers and markers)
  • examples/ — maintained end-to-end examples
  • doc/ — this documentation
  • DEVELOPMENT.md — environment provisioning and day-to-day workflow
  • ruff.toml — the single lint configuration

AI-assisted development

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.

License

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.

Acknowledgements

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.

About

Fast volume potential computation via FMM.

Resources