Upload
others
View
9
Download
0
Embed Size (px)
Citation preview
Spectral Ewald DocumentationRelease 0.1
Ludvig af Klinteberg, Davoud Saffar Shamshirgar, Dag Lindbo
Sep 10, 2018
Contents
1 Contents 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Mathematical background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3 Function reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 C interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 Indices 13
MATLAB Module Index 15
i
ii
Spectral Ewald Documentation, Release 0.1
This is the documentation for the unified Spectral Ewald package, available on GitHub at https://github.com/ludvigak/SE_unified . To obtain the lastest version simply execute
git clone https://github.com/ludvigak/SE_unified.git
Contents 1
Spectral Ewald Documentation, Release 0.1
2 Contents
CHAPTER 1
Contents
1.1 Introduction
The package provides a Matlab implementation of the Spectral Ewald method (SE) for fast Ewald summation relatedto six different kernels:
• SE: 3-periodic Laplace (electrostatics)
• SE2P: 2-periodic Laplace (electrostatics)
• SE1P: 1-periodic Laplace (electrostatics)
• SE0P: 0-periodic Laplace-Stokeslet-Stresslet-Rotlet (electrostatics and viscous flow)
• SE_Stokes: 3-periodic Stokeslet (viscous flow)
• SE2P_Stokes: 2-periodic Stokeslet (viscous flow)
• SE_Stresslet: 3-periodic Stresslet (viscous flow)
• SE_Rotlet: 3-periodic Rotlet (viscous flow)
The aim of this package is to provide fast routines for computing the Fourier space sums for the above kernels.Routines for the real space sums are provided for some kernels.
Most of the computational kernels are written in C, and quite some time has been spent optimizing them using explicitSIMD instructions and OpenMP shared-memory parallelism. The interfacing MEX layer is generally kept thin, sointerfacing to another language than Matlab should be quite straightforward.
1.1.1 Building
Most of the C/MEX code is now built with CMake. To build it open a terminal and do
cd buildcmake ..make
3
Spectral Ewald Documentation, Release 0.1
To run the test suite:
make test
Some of the C/MEX code is not yet integrated into CMake, and has to be built using Matlab build script. The buildscript is then called make.m and is located in the base folder for that kernel.
1.1.2 Getting started
Each directory contains the m-files related to that specific kernel. From any of these directories do
init % sets up paths
then depending on directory you can do
demo % Runs demo of spectral convergence + error estimates% for both real and Fourier space sums.
or
make % build C/MEX code for this directorytest_accuracy % should display plot of spectral convergence
Example (in Matlab):
cd SE_Rotletinitdemo
Most recent development has focused on 3P Stokes flow, so the directories related to that (SE_Stokes, SE_Rotlet,SE_Stresslet) are more developed.
Code examples for various are kernels can be found by looking at the tests, located in the folder mfile_tests ortests in the folder for the respective kernel.
1.1.3 Testing
Some directories contain a tests folder with unit tests. To run that test suite simply execute
initrun_unit_tests
To run the full suite, go to the root directory and run
run_unit_tests
This is recommended to do after building or before committing changes.
1.1.4 Additional files
The package also contains:
• util: Common functions
• SE_fast_gridding: C implementation of fast Gaussian gridding and fast Kaiser gridding
4 Chapter 1. Contents
Spectral Ewald Documentation, Release 0.1
• SE_direct: C-code for direct Ewald sums for Laplace 2P/3P
• SE_Stokes_direct: C-code for direct Ewald sums for Stokes 2P/P3
• SE_leftovers: Spectral Ewald, fast real-space and k=0 codes for Laplace and Stokes. These are unmain-tained, but might prove useful.
1.2 Mathematical background
The Spectral Ewald method for the kernels included in this package is described in the below publications.
Electrostatics:
• . D. Lindbo and A.-K. Tornberg, Spectral accuracy in fast Ewald-based methods for particle simulations,http://dx.doi.org/10.1016/j.jcp.2011.08.022
• . D. Lindbo and A.-K. Tornberg, Fast and spectrally accurate Ewald summation for 2-periodic electrostaticsystems, http://dx.doi.org/10.1063/1.4704177
• . A.-K. Tornberg, The Ewald sums for singly, doubly and triply periodic electrostatic systems, https://doi.org/10.1007/s10444-015-9422-3
• . D. S. Shamshirgar and A.-K. Tornberg, The Spectral Ewald method for singly periodic domains, https://doi.org/10.1016/j.jcp.2017.07.001
• . D. S. Shamshirgar and A.-K. Tornberg, Fast Ewald summation for electrostatic potentials with arbitraryperiodicity, https://arxiv.org/abs/1712.04732
Stokes:
• . D. Lindbo and A.-K. Tornberg, Spectrally accurate fast summation for periodic Stokes potentials, http://dx.doi.org/10.1016/j.jcp.2010.08.026
• . D. Lindbo and A.-K. Tornberg, Fast and spectrally accurate summation of 2-periodic Stokes potentials, http://arxiv.org/abs/1111.1815
• . L. af Klinteberg and A.-K. Tornberg, Fast Ewald summation for Stokesian particle suspensions, http://dx.doi.org/10.1002/fld.3953
• . L. af Klinteberg and D. S. Shamshirgar and A.-K. Tornberg, Fast Ewald summation for free-space Stokespotentials, https://doi.org/10.1186/s40687-016-0092-7
1.3 Function reference
Throughout this document the sum∑︀
𝜏 implies the periodic sum∑︀
𝑝∈Z3 with 𝜏 = (𝑝1𝐿1, 𝑝2𝐿2, 𝑝3𝐿3).
1.3.1 SE
Ewald summation for the 3-periodic electrostatic potential
𝑢(𝑥) =∑︁𝜏
𝑁∑︁𝑛=1
𝑞𝑛|𝑥− 𝑥𝑛 + 𝜏 |
.
SE.se3p_fourier_space(x, f, opt)initialize time array
1.2. Mathematical background 5
Spectral Ewald Documentation, Release 0.1
SE.se3p_precomp(x, opt)SPECTRAL EWALD 3P, pre-computation of FGG vectors Fast Ewald method for electrostatic potential calcu-lation, k-space part.
SE.spectral_ewald(eval_idx, x, q, xi, opt)SPECTRAL EWALD Fast Ewald method for electrostatic potential calculation, k-space part.
phi = spectral_ewald(idx, x, q, xi, box, opt)
Returns phi – k-space part of periodic potential
Parameters
• idx – evaluation indices (particle indices)
• x – particle positions (N-by-3)
• q – particle charge (N-by-1)
• xi – Ewald parameter
• opt – Options:
• opt.M – grid size, eg. [31 31 31] (required)
• opt.P – Gaussian support (required)
• opt.box – Periodic cell, eg. [1 1 1]
• opt.m – Gaussian shape function (default: m=m(P))
• opt.w – Gaussian width (default: w=h*P/2)
1.3.2 SE2P
Ewald summation for the 2-periodic electrostatic potential.
1.3.3 SE1P
Ewald summation for the 1-periodic electrostatic potential.
1.3.4 SE0P
Ewald summation for the free-space electrostatic (stokeslet, stresslet, rotlet) potential.
1.3.5 SE_kaiser
Ewald summation for the electrostatic potential with arbitrary periodicity using Barnett-Magland kernel.
1.3.6 SE2P_Stokes
Ewald summation for the 2-periodic stokeslet potential.
SE2P_Stokes.SE2P_Stokes(eval_idx, x, f, xi, opt)SPECTRAL EWALD 2DP Fast Ewald method for electrostatic potential calculation, k-space part.
phi = spectral_ewald_2dp(idx, x, q, xi, opt)
6 Chapter 1. Contents
Spectral Ewald Documentation, Release 0.1
Dag Lindbo, [email protected], Jul. 2011
SE2P_Stokes.SE2P_Stokes_pre(x, xi, opt)SPECTRAL EWALD 2DP, pre-computation of FGG vectors
Dag Lindbo, [email protected], Jul. 2011
SE2P_Stokes.parse_params(opt)check that we have all mandatory options
1.3.7 SE_fast_gridding
Routines for fast gaussian gridding (FGG) and fast Kaiser gridding (FKG), which is central to Spectral Ewald.
SE_fast_gridding.SE_FGG_precomp(x, xi, opt)SPECTRAL EWALD 3P, pre-computation of FGG vectors Fast Ewald method for electrostatic potential calcu-lation, k-space part.
SE_fast_gridding.SE_fg_extend_fcn(F, opt)parameters and constants
SE_fast_gridding.SE_fg_int(x, U, opt)
u = SE_fg_int(x, U, opt) Return integration at x of on-grid values U
u = SE_fg_int(x, {U1, . . . , UN}, opt) Return integration at x of on-grid values U1,. . . ,UN u has N columns
SE_fast_gridding.SE_fg_int_extended(x, U, opt)parameters and constants
SE_fast_gridding.parse_params(opt)Parse parameter struct for fast Gaussian gridding
Mandatory parameters:
Parameters
• opt.M – grid size (1 x 3)
• opt.P – Gaussian width
• opt.box – box size (1 x 3)
1.3.8 SE_Rotlet
Ewald summation for the 3-periodic rotlet potential
𝑢(𝑥) =∑︁𝜏
𝑁∑︁𝑛=1
𝑅(𝑥− 𝑥𝑛 + 𝜏)𝑡𝑛
where
𝑅𝑖𝑗(𝑟) = 𝜖𝑖𝑗𝑘𝑟𝑘|𝑟|3
.
SE_Rotlet.SE_Rotlet(xe, x, f, xi, opt)
u = SE_Rotlet(x_targets, x_sources, f_sources, xi, opt) Returns the rotlet potential
[U1, U2, U3] = SE_Rotlet(x_targets, x_sources, f_sources, xi, opt) Returns the grid with Fourier coeffi-cients, 𝑈𝑖 ∈ C𝑀1×𝑀2×𝑀3
1.3. Function reference 7
Spectral Ewald Documentation, Release 0.1
To compute u from U1,U2,U3:
F{1} = real( ifftn( ifftshift( U1 )));F{2} = real( ifftn( ifftshift( U2 )));F{3} = real( ifftn( ifftshift( U3 )));u = SE_fg_int(xe, F, opt);
opt must be identical to that passed to SE_Rotlet
TODO: Add possibility of passing precomputed structures
SE_Rotlet.rotlet_direct_fd(xe, x, f, xi, L, kmax)Direct summation of rotlet k-space part.
Parameters
• xe – target positions, M-by-3
• x – source positions, N-by-3
• f – source strengths, N-by-3
• xi – Ewald parameter,
• L – box size, 1-by-3
• kmax – k-space truncation
SE_Rotlet.rotlet_direct_real(idx, x, f, xi, L, varargin)Direct summation of rotlet real space part
phi = rotlet_direct_real(idx, x, t, xi, box, ‘layers’, M, ‘tol’, TOL); Compute interactions from all particleswithin M layers, stop at tolerance TOL.
phi = rotlet_direct_real(idx, x, t, xi, box, ‘mode’,’cutoff’, ‘rc’, rc); Compute interactions from all particleswithin cutoff radius rc.
SE_Rotlet.rotlet_direct_rsrc(xe, x, t, opt)Rotlet real space direct summation with cutoff radius, MEX implementation.
Parameters
• xe – target locations
• x – source locaitons
• t – source strengths
• opt – Ewald options
• opt.box – box size
• opt.xi – Ewald parameter 𝜉
• opt.rc – Cutoff radius
SE_Rotlet.rotlet_ewald_sum(xe, x, t, opt)Ewald summation for 3P rotlet.
Parameters
• xe – target locations
• x – source locaitons
• t – source strengths
• opt – Ewald options
8 Chapter 1. Contents
Spectral Ewald Documentation, Release 0.1
• opt.box – box size
• opt.xi – Ewald parameter 𝜉
• opt.M – Fourier space grid size
• opt.P – Gaussian width
• opt.rc – Real space cutoff radius
1.3.9 SE_Stokes
Ewald summation for the 3-periodic stokeslet potential
𝑢(𝑥) =∑︁𝜏
𝑁∑︁𝑛=1
𝑆(𝑥− 𝑥𝑛 + 𝜏)𝑓𝑛,
where
𝑆(𝑟) =𝐼
|𝑟|+
𝑟 ⊗ 𝑟
|𝑟|3.
SE_Stokes.SE_Stokes(eval_idx, x, f, xi, opt)Compute Fourier space part of Ewald sum for periodic stokeslet potential.
u = SE_Stokes(eval_idx,x,f,xi,opt) Return potential
[U1, U2, U3] = SE_Stokes(eval_idx,x,f,xi,opt) Return Fourier coefficients
Parameters
• eval_idx – index of source locations where potential should be evaluated
• x – source locations (Nx3)
• f – source strengths (Nx3)
• xi – Ewald paramter
• opt – Ewald options
• opt.M – grid size (M1, M2, M3)
• opt.P – Gaussian width
• opt.box – Box size (L1, L2, L3)
Returns phi – Fourier space potential
Returns U1,U2,U3 – Fourier space potential
SE_Stokes.SE_Stokes_ext(xe, xs, f, xi, opt)Evaluate Stokeslet at external points
SE_Stokes.SE_Stokes_par(eval_idx, x, f, xi, opt)parfor:ed version
1.3. Function reference 9
Spectral Ewald Documentation, Release 0.1
1.3.10 SE_Stresslet
Ewald summation for the 3-periodic stresslet potential
𝑢(𝑥) =∑︁𝜏
𝑁∑︁𝑚=1
𝑞𝑚𝑇 (𝑥− 𝑥𝑚 + 𝜏)�̂�𝑚,
where
𝑇𝑖𝑗𝑘(𝑟) = −6𝑟𝑖𝑟𝑗𝑟𝑘|𝑟|5
.
SE_Stresslet.SE_Stresslet(eval_idx, x, f, n, xi, opt, varargin)Compute Fourier space part of Ewald sum for periodic stresslet potential.
phi = SE_Stresslet(eval_idx,x,f,n,xi,opt) Return potential
[U1, U2, U3] = SE_Stresslet(eval_idx,x,f,n,xi,opt) Return Fourier coefficients
Parameters
• eval_idx – index of source locations where potential should be evaluated
• x – source locations (Nx3)
• f – source strengths (Nx3)
• n – source normals (Nx3)
• xi – Ewald paramter
• opt – Ewald options:
• opt.M – grid size (M1, M2, M3)
• opt.P – Gaussian width
• opt.box – Box size (L1, L2, L3)
• varargin=SE_static – Precomputations from SE_Stresslet_pre() to use SIMD FGGcode.
Returns phi – Fourier space potential
Returns U1,U2,U3 – Fourier space coefficients
SE_Stresslet.SE_Stresslet_pre(x, xi, opt)Precompute data for fast Gaussian gridding to enable optimized kernels
Returns SE_static
SE_Stresslet.generate_state(N, L, varargin)Returning x: Nx3 matrix with coords inside box L, f: Nx3 matrix with point forces. nvec: Nx3 matrix withassociated normal vectors.
SE_Stresslet.stresslet_direct_fd(idx, x, f, nvec, xi, L, kmax)Fourier space Ewald sum for stresslet, using (very slow) direct summation.
Parameters kmax – Fourier space truncation
SE_Stresslet.stresslet_direct_fd_zero(idx, xvec, fvec, nvec, L)Component for 𝑘 = 0 of stresslet Fourier sum.
Parameters
10 Chapter 1. Contents
Spectral Ewald Documentation, Release 0.1
• idx – index of target positions (Nx1)
• xvec – source positions (Nx3)
• fvec – source strengths (Nx3)
• nvec – normal vectors (Nx3)
• L – box size (1x3)
Returns phi_k0 – (Nx3)
SE_Stresslet.stresslet_direct_real(idx, x, f, nvec, xi, L, nbox, TOL, varargin)Real space Ewald sum for stresslet, using (very slow) direct summation.
Parameters
• nbox – Number of periodic replications in each direction.
• TOL – Break when truncation error < TOL.
• varargin=eval_x – Evaluate at eval_x instead of x(idx,:)
SE_Stresslet.stresslet_direct_real_fast(idx, x, f, nvec, xi, L, nbox, rc, varargin)Ewald summation for the stresslet – Real space part. Fast in the sense that it saves interactions as matrix forsubsequent iterations Sums over layers
• [phi A] = stresslet_direct_real_fast( idx, x, f, nvec, xi, L, nbox, rc, [A, sing_sub, ns_quad_mtrx])
Parameters
• x – positions :param (N-by-3)
• f – source strengths (N-by-3)
• nvec – normal vectors (N-by-3)
• xi – Ewald parameter
• L – Box size (3)
• nbox – periodic replications
• rc – cutoff radius
• A – Precomputed matrix
• sing_sub – Use singularity subtraction
• ns_quad_mtrx – Correction matrices for nearly singular quadrature
SE_Stresslet.stresslet_op_fd(k, xi)Returns imaginary part of Bi(k, xi) ie B = 1i*Bi;
SE_Stresslet.stresslet_real_rc(x, q, nvec, xi, box, rc, varargin)Stresslet real space summation with truncation radius rc
Usage:
• [res] = stresslet_real_rc( x, f, nvec, xi, box, rc);
• [res AMAT] = stresslet_real_rc( x, f, nvec, xi, box, rc, [], sing_sub, ns_quad_mtrx);
• [res AMAT] = stresslet_real_rc( x, f, nvec, xi, box, rc, AMAT, sing_sub, ns_quad_mtrx);
• [res AMAT R C V PER] = stresslet_real_rc( x, f, nvec, xi, box, rc);
Parameters
1.3. Function reference 11
Spectral Ewald Documentation, Release 0.1
• sing_sub – singularity subtraction, default 0. Only for matrix comp.
• rc – cutoff radius, must be <= min(box)/2
1.4 C interface
TBD
12 Chapter 1. Contents
CHAPTER 2
Indices
• genindex
• modindex
13
Spectral Ewald Documentation, Release 0.1
14 Chapter 2. Indices
MATLAB Module Index
sSE, 5SE0P, 6SE1P, 6SE2P, 6SE2P_Stokes, 6SE_fast_gridding, 7SE_kaiser, 6SE_Rotlet, 7SE_Stokes, 9SE_Stresslet, 10
15
Spectral Ewald Documentation, Release 0.1
16 MATLAB Module Index
Index
Ggenerate_state() (in module SE_Stresslet), 10
Pparse_params() (in module SE2P_Stokes), 7parse_params() (in module SE_fast_gridding), 7
Rrotlet_direct_fd() (in module SE_Rotlet), 8rotlet_direct_real() (in module SE_Rotlet), 8rotlet_direct_rsrc() (in module SE_Rotlet), 8rotlet_ewald_sum() (in module SE_Rotlet), 8
SSE (module), 5SE0P (module), 6SE1P (module), 6SE2P (module), 6SE2P_Stokes (module), 6SE2P_Stokes() (in module SE2P_Stokes), 6SE2P_Stokes_pre() (in module SE2P_Stokes), 7se3p_fourier_space() (in module SE), 5se3p_precomp() (in module SE), 5SE_fast_gridding (module), 7SE_fg_extend_fcn() (in module SE_fast_gridding), 7SE_fg_int() (in module SE_fast_gridding), 7SE_fg_int_extended() (in module SE_fast_gridding), 7SE_FGG_precomp() (in module SE_fast_gridding), 7SE_kaiser (module), 6SE_Rotlet (module), 7SE_Rotlet() (in module SE_Rotlet), 7SE_Stokes (module), 9SE_Stokes() (in module SE_Stokes), 9SE_Stokes_ext() (in module SE_Stokes), 9SE_Stokes_par() (in module SE_Stokes), 9SE_Stresslet (module), 10SE_Stresslet() (in module SE_Stresslet), 10SE_Stresslet_pre() (in module SE_Stresslet), 10spectral_ewald() (in module SE), 6
stresslet_direct_fd() (in module SE_Stresslet), 10stresslet_direct_fd_zero() (in module SE_Stresslet), 10stresslet_direct_real() (in module SE_Stresslet), 11stresslet_direct_real_fast() (in module SE_Stresslet), 11stresslet_op_fd() (in module SE_Stresslet), 11stresslet_real_rc() (in module SE_Stresslet), 11
17