PyNucleus is a finite element code that specifically targets nonlocal operators of the form
\int_{\mathbb{R}^d} [u(x)-u(y)] \gamma(x, y) dy
for nonlocal kernels \gamma with finite or infinite horizon and of integrable or fractional type. Specific examples of such operators include the integral and regional fractional Laplacians, their truncated and tempered variants, and operators arising from peridynamics.
The package aims to provide efficient discretization and assembly routines with O(N \log N) quasi-optimal complexity. The resulting sets of equations can be solved using optimal linear solvers. The code is fully NumPy/SciPy compatible, allowing easy integration into application codes.
- Simplical meshes in 1D, 2D, 3D
- Finite Elements:
- continuous P1, P2, P3 spaces,
- discontinuous P0 space
- Assembly of local operators
- Nonlocal kernels:
- Finite and infinite horizon
- Singularities: fractional, peridynamic, constant, Gaussian kernel
- spatially variable kernels: variable fractional order and variable coefficients
- Nonlocal assembly (1D and 2D) into dense, sparse and hierarchical matrices
- Solvers/preconditioners:
- LU,
- Cholesky,
- incomplete LU & Cholesky,
- Jacobi,
- CG,
- BiCGStab,
- GMRES,
- geometric multigrid
- Distributed computing using MPI
- Computationally expensive parts of the code are compiled via Cython.
- Partitioning using METIS / ParMETIS
The documentation is available here.
To generate the Sphinx documentation locally, run
make docs
and open docs/build/index.html
in your browser.
There are several ways to install and run PyNucleus:
- JupyterHub cloud instance
- container image
- Spack installation
- manual installation
The easiest way to get up and running is probably to run it in the cloud. For a local installation we recommend the container image.
PyNucleus can be run directly for free from the browser on a JupyterHub server hosted at mybinder.org.
Just click here to launch a notebook server:
The simplest way to use PyNucleus is to pull a container image from the GitHub Container Registry. This requires an installation of either
- podman and podman-compose or
- Docker and Docker Compose.
For many Linux distributions these can be installed from the package repositories. In what follows we will assume that we are using podman. All commands for Docker should be identical up to the substitution of podman with docker.
For example, on Ubuntu podman and podman-compose can be installed with
sudo apt-get install podman podman-compose
Instructions for other platforms can be found here.
Once podman is installed, we download a copy of compose.yaml and save it to an empty directory.
Warning
Please do not copy this file to your home directory and launch the container from there. The container keeps its state in the directory where it is launched from.
In that directory we then run
podman-compose run pynucleus
podman will download a container image for PyNucleus and then launch a shell in the container.
Note
The download of the image will only happen once, but it could be several GB in size.
A simple way to test if things work is to run
drivers/runFractional.py
This should print some information about the solution of a fractional Laplacian problem and show several plots.
For development using PyNucleus there is the Jupyter notebook interface that is available while the container is running at https://localhost:8889 on the host system.
In order to install Spack itself, follow the instructions at https://github.com/spack/spack.
Install PyNucleus and all its dependencies with the command
spack install py-pynucleus
To then load PyNucleus
spack load py-pynucleus
The examples can be found in the install directory. In order to get there:
spack cd -i py-pynucleus
In order to install PyNucleus, you will need
- Python 3,
- MPI,
- METIS,
- ParMETIS,
- SuiteSparse,
- make.
On Debian, Ubuntu etc, the required dependencies can be installed with
sudo apt-get install python3 mpi-default-bin mpi-default-dev libmetis-dev libparmetis-dev libsuitesparse-dev
On MacOS the required dependencies can be installed with
brew install python open-mpi
brew tap brewsci/num
brew install brewsci-metis brewsci-parmetis brewsci-suite-sparse
After cloning the source code, PyNucleus is installed via
make
The compilation of PyNucleus can be configured by modifying the file config.yaml in the root folder. This allows for example to set paths for libraries that are installed in non-standard directories.
If you want to easily modify the source code without re-installing the package every time, and editable install is available as
make dev
PyNucleus depends on other Python packages that will be installed automatically:
- NumPy
- SciPy
- Matplotlib
- Cython
- mpi4py
- tabulate
- PyYAML
- H5py
- modepy
- meshpy
- scikit-sparse
PyNucleus' development is funded through the FOMSI project (PI: Christian Glusa, FY23-FY25) of the LDRD program at Sandia National Laboratories.
PyNucleus' development was previously funded through the MATNIP project (PI: Marta D'Elia, FY20-22).
The MATNIP project develops for the first time a rigorous nonlocal interface theory based on physical principles that is consistent with the classical theory of partial differential equations when the nonlocality vanishes and is mathematically well-posed. This will improve the predictive capability of nonlocal models and increase their usability at Sandia and, more in general, in the computational-science and engineering community. Furthermore, this theory will provide the groundwork for the development of nonlocal solvers, reducing the burden of prohibitively expensive computations.