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, dag@kth.se, Jul. 2011

SE2P_Stokes.SE2P_Stokes_pre(x, xi, opt)SPECTRAL EWALD 2DP, pre-computation of FGG vectors

Dag Lindbo, dag@kth.se, 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