FFT Poisson Solver: Neumann and Dirichlet Boundaries

Add support for Neumann and Dirichlet boundaries in the FFT based Poisson
solver. This requires cosine and sine transforms. For CPU builds, we use
FFTW for these transforms. But GPU builds, we have implemented cosine and
sine transforms using the real-to-complex transform provided by cuFFT,
rocFFT and oneMKL.

Author: WeiqunZhang

Docs/sphinx_documentation/source/FFT.rst

@@ -64,8 +64,42 @@ object. Therefore, one should cache it for reuse if possible.
 Poisson Solver
 ==============
 
-AMReX provides FFT based Poisson solvers. :cpp:`FFT::Poisson` supports all
-periodic boundaries using purely FFT. :cpp:`FFT::PoissonHybrid` is a 3D only
-solver that supports periodic boundaries in the first two dimensions and
-Neumann boundary in the last dimension. Similar to :cpp:`FFT::R2C`, the
-Poisson solvers should be cached for reuse.
+AMReX provides FFT based Poisson solvers. :cpp:`FFT::Poisson` supports
+periodic (:cpp:`FFT::Boundary::periodic`), homogeneous Neumann
+(:cpp:`FFT::Boundary::even`), and homogeneous Dirichlet
+(:cpp:`FFT::Boundary::odd`) boundaries using FFT. Below is an example of
+using the solver.
+
+.. highlight:: c++
+
+::
+
+    Geometry geom(...);
+    MultiFab soln(...);
+    MultiFab rhs(...);
+
+    Array<std::pair<FFT::Boundary,FFT::Boundary>,AMREX_SPACEDIM>
+            fft_bc{...};
+
+    bool has_dirichlet = false;
+    for (int idim = 0; idim < AMREX_SPACEDIM; ++idim) {
+        has_dirichlet = has_dirichlet ||
+            fft_bc[idim].first == FFT::Boundary::odd ||
+            fft_bc[idim].second == FFT::Boundary::odd;
+    }
+    if (! has_dirichlet) {
+        // Shift rhs so that its sum is zero.
+        auto rhosum = rhs.sum(0);
+        rhs.plus(-rhosum/geom.Domain().d_numPts(), 0, 1);
+    }
+
+    FFT::Poisson fft_poisson(geom, fft_bc);
+    fft_poisson.solve(soln, rhs);
+
+:cpp:`FFT::PoissonHybrid` is a 3D only solver that supports periodic
+boundaries in the first two dimensions and Neumann boundary in the last
+dimension. The last dimension is solved with a tridiagonal solver that can
+support non-uniform cell size in the z-direction. For most applications,
+:cpp:`FFT::Poisson` should be used.
+
+Similar to :cpp:`FFT::R2C`, the Poisson solvers should be cached for reuse.