BSpline Finite Element Exterior Calculus
Loading...
Searching...
No Matches
README

Pipeline Status Coverage Report Benchmarks Doxygen MIT License
Fortran CMake MPI OpenACC PETSc SLEPc VTK
GCC Intel NVIDIA HPC


Logo

B-spline Finite Element Exterior Calculus

A Fortran-based implementation of the Finite Element method for the three-dimensional de Rham sequence based on tensor product B-splines

Read the Tutorial · Read the Documentation · Report an Issue

1. 📝 Table of contents

  • 1. 📝 Table of contents
  • 2. ✨ About the project
  • 3. ⚙️ Getting started
    • 3.1. Prerequisites
    • 3.2. Installation
  • 4. 🚧 Roadmap
  • 5. 📄 License
  • 6. 📚 References

2. ✨ About the project

The key features are:

  • Compatible Finite Element spaces ($m$-form spaces) for the three-dimensional de Rham sequence (using Finite Element Exterior Calculus1)
  • Support for arbitrary coordinate systems by means of pull-back and push-forward operators
  • Support for high-order regularity constraints in case the coordinate transformation has a disc-like singularity (i.e., where the Jacobian vanishes at the origin)2
  • Solution of several linear PDEs (on a mapped domain which can have a tunnel/hole):
    • Compute the $L^2$ projection of a bounded $m$-form $f$: find $\varphi \in V^m$ such that $$ \langle\varphi, \phi\rangle = \langle f, \phi\rangle $$ for all $\phi \in V^m$, where $\langle \cdot , \cdot \rangle$ denotes the $L^2$ inner product
    • Solve the $0$-form Poisson problem: find $\varphi \in V^0$ such that $$ \langle \nabla \varphi, \mathbf{M}^1 \nabla \phi\rangle = \langle f, \phi\rangle $$ for all $\phi \in V^0$, where $f$ is a bounded $0$-form and $\mathbf{M}^1$ is a variable (possibly matrix-valued) coefficient
    • Solve the $1$-form curl-curl problem: find $\bm{\varphi} \in V^1$ such that $$ \langle \nabla \times \bm{\varphi}, \mathbf{M}^2 \nabla \times \bm{\phi}\rangle = \langle \bm{f}, \bm{\phi}\rangle $$ for all $\bm{\phi} \in V^1$, where $\bm{f}$ is a bounded $1$-form and $\mathbf{M}^2$ is a variable (possibly matrix-valued) coefficient
  • Solution of the corresponding eigenvalue problems; for example
    • Solve the $0$-form Laplace eigenvalue problem: for a specific target $\lambda^\star$ find pairs $(\lambda, \varphi) \in \mathbb{C} \times V^0$ such that $$ \langle \nabla \varphi, \mathbf{M}^1 \nabla \phi\rangle = \lambda \langle \varphi, M^0 \phi\rangle $$ for all $\phi \in V^0$, where $M^0$ is a variable coefficient
  • A high-level interface using object-oriented modern Fortran
  • A CI pipeline containing:
  • A flexible hybrid MPI parallelisation (pure MPI, but allows for shared memory parallelism)
  • Interfaces with PETSc for linear solvers and with SLEPc for eigenvalue problems (optional)
  • Visualisation in ParaView via VTKFortran (optional)

We give a brief overview of the mathematics behind the discretisation in the TUTORIAL. More details can be found2.

3. ⚙️ Getting started

To get a local copy up and running follow the following steps.

3.1. Prerequisites

The following are required prerequisites for building this package:

  • Ninja build system
    apt-get install ninja-build
  • Fypp (Fortran preprocessor)
    pip install fypp
  • MPI (for example OpenMPI)
    apt-get install libopenmpi-dev openmpi-bin
  • PETSc (see also this installation tutorial)
    git clone -b release https://gitlab.com/petsc/petsc.git petsc
    cd petsc
    ./configure --download-mumps --download-scalapack --download-hypre --COPTFLAGS="-O3" --CXXOPTFLAGS="-O3" --FOPTFLAGS="-O3"
    make all check

3.2. Installation

Basic installation should be done as follows:

  1. Clone the repo
    git clone https://gitlab.mpcdf.mpg.de/rwr/bspline_feec.git
  2. Run CMake
    cd bspline_feec
    mkdir build
    cd build
    cmake ../ -G Ninja -Dbspline_feec_TESTING=on
  3. Build using Ninja
    ninja
  4. Install as a shared library _(optional)_
    ninja install
  5. Run all tests
    ctest
    A complete example demonstrating the use of the bspline_feec package as a shared library is provided in the examples/external_project directory.
Advanced installation options

Advanced installation options can be passed using CMake flags.

The following CMake flags are available to control the build and features of bspline_feec:

Flag Type Default Description
bspline_feec_PRECISION STRING double_precision Set floating-point precision: single_precision or double_precision
bspline_feec_MAX_COMM_NEIGHBOURS_X STRING 1 Number of neighbouring MPI nodes in the x-direction
bspline_feec_MAX_COMM_NEIGHBOURS_Y STRING 1 Number of neighbouring MPI nodes in the y-direction
bspline_feec_MAX_COMM_NEIGHBOURS_Z STRING 1 Number of neighbouring MPI nodes in the z-direction
bspline_feec_GUARD_LAYER STRING 1 Guard layer size for domain decomposition
bspline_feec_BENCHMARK BOOL OFF Enables the benchmark of the bspline_feec package
bspline_feec_DOXYGEN BOOL OFF Enables generating the documentation of the bspline_feec package
bspline_feec_EIGENVALUES BOOL OFF Enables the eigenvalue solver via SLEPc
bspline_feec_EXAMPLE BOOL OFF Enables a usage example of the bspline_feec package
bspline_feec_PARAVIEW BOOL OFF Enables ParaView output via VTKFortran
bspline_feec_TESTING BOOL OFF Enables testing of the bspline_feec package

You can set these flags when configuring with CMake, for example:

cmake -G Ninja -Dbspline_feec_PRECISION=double_precision -Dbspline_feec_PARAVIEW=ON ..

4. 🚧 Roadmap

  • [ ] Add support for diagnostics
    • [ ] ParaView output
      • [x] Sequential
      • [ ] MPI support
  • [ ] Add support for GVEC mappings
  • [ ] Add support for multiple patches with extraction-based regularity constraints
  • [x] Add support for GPU parallelisation using OpenACC
  • [ ] Add optimal linear solvers (bypassing PETSc)
  • [ ] Add the grad-div problem
  • [ ] Add shifted problems. E.g. $-\nabla^2 \varphi + c \varphi = f$

See the open issues for a full list of proposed features (and known issues).

5. 📄 License

Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

6. 📚 References

1 Arnold DN, Falk RS, Winther R. Finite element exterior calculus, homological techniques, and applications. Acta Numerica. 2006;15:1-155. doi:10.1017/S0962492906210018

2 Remmerswaal R (2025). Higher-order FEEC discretization on a solid toroidal domain. Not yet available

3 De Boor C (1978). A practical guide to splines. Springer-Verlag New York

4 Hiptmair R, Xu J (2007). Nodal auxiliary space preconditioning in $H(\text{curl})$ and $H(\text{div})$ spaces. SIAM Journal on Numerical Analysis, 45(6), 2483-2509. doi:10.1137/060660588