## Multipole

01 Jun 2010

### Abstract

The Multipole thorn performs spherical harmonic mode decomposition of Cactus grid functions on coordinate spheres.

### 1 Introduction

This thorn allows the user to compute the coefficients of the spherical harmonic expansion of a field stored in a Cactus grid function on coordinate spheres of given radii. A set of radii for these spheres, as well as the number of angular points to use, can be specified. Complex fields can be used, but they must be stored in pairs of real Cactus grid functions (the CCTK_COMPLEX type is not supported).

### 2 Physical System

The angular dependence of a field $u\left(t,r,𝜃,\phi \right)$ can be expanded in spin-weight $s$ spherical harmonics :

$\begin{array}{rcll}u\left(t,r,𝜃,\phi \right)=\sum _{l=0}^{\infty }\sum _{m=-l}^{l}{C}^{lm}{\left(t,r\right)}_{s}{Y}_{lm}\left(𝜃,\phi \right)& & & \text{(1)}\text{}\text{}\end{array}$

where the coefficients ${C}^{lm}\left(t,r\right)$ are given by

$\begin{array}{rcll}{C}^{lm}\left(t,r\right)={\int }_{s}{Y}_{lm}^{\ast }u\left(t,r,𝜃,\phi \right){r}^{2}d\mathrm{\Omega }& & & \text{(2)}\text{}\text{}\end{array}$

At any given time, $t$, this thorn can compute ${C}^{lm}\left(t,r\right)$ for a number of grid functions on several coordinate spheres with radii ${r}_{i}$. The coordinate system of the Cactus grids must be Cartesian and the coordinates $r$, $𝜃$, $\phi$ are related to $x$, $y$ and $z$ by the usual transformation between Cartesian and spherical polar coordinates ($𝜃$ is the polar angle and $\phi$ is the azimuthal angle).

The spin-weighted spherical harmonics are computed using Eq. 3.1 in Ref. .

### 3 Numerical Implementation

The coordinate sphere on which the multipolar decomposition is performed is represented internally as a 2-dimensional grid evenly spaced in $𝜃$ and $\phi$ with coordinates

$\begin{array}{rcll}{𝜃}_{k}& =& \frac{\pi k}{{n}_{𝜃}}\phantom{\rule{1em}{0ex}}k=0,1,...,{n}_{𝜃}& \text{(3)}\text{}\text{}\\ {\phi }_{k}& =& \frac{2\pi k}{{n}_{\phi }}\phantom{\rule{1em}{0ex}}k=0,1,...,{n}_{\phi },& \text{(4)}\text{}\text{}\end{array}$

so ${n}_{𝜃}$ and ${n}_{\phi }$ count the number of cells (not the number of points). The gridfunction to be decomposed, $u$, is first interpolated from the 3D Cactus grid onto this 2D grid at a given radius, ${r}_{i}$, and the ${C}^{lm}$ are computed by evaluating the integral in Eq. 2 for different values of $l$ and $m$. The interpolation is performed using the Cactus interpolation interface, so any Cactus interpolator can be used. The numerical method used for interpolation should be specified in the documentation for the thorn which provides it. One such thorn is AEILocalInterp. The integration is performed using either the midpoint rule, yielding a result which is second order accurate in the angular spacings $\mathrm{\Delta }𝜃=\pi ∕{n}_{𝜃}$ and $\mathrm{\Delta }\phi =2\pi ∕{n}_{𝜃}$, or Simpson’s rule, which is fourth order accurate.

### 4 Using This Thorn

#### 4.1 Obtaining This Thorn

This thorn is available as part of the Einstein Toolkit via:

svn checkout https://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/Multipole/trunk Multipole

or by using the Einstein Toolkit GetComponents script and thornguide.

#### 4.2 Basic Usage

Suppose that you have a real grid function, $u$, for which you want to compute the spherical harmonic coefficients ${C}^{lm}$. Start by including Multipole and an interpolator (for example AEILocalInterp) in the ActiveThorns line of your parameter file (for interpolation thorns other than AEILocalInterp, you will need to modify the interpolator and interpolator_options accoording to the documentation of the interpolation thorn). Next decide the number and radii of the coordinate spheres on which you want to decompose. Set the number of spheres with the nradii parameter, and the radii themselves with the radius[i] parameters (the indices $i$ are zero-based). For example,

ActiveThorns = ".... AEILocalInterp Multipole"

Multipole::variables    = "MyThorn::u"


The default parameters will compute all $l=2$ modes assuming a spin-weight $s=0$ on every iteration of your simulation. The coefficients ${C}^{lm}$ will be output in the files with names of the form mp_<var>_l<lmode>_m<mmode>_r<rad>.asc, for example

mp_u_l2_m2_r10.00.asc
mp_u_l2_m-1_r20.00.asc


For the filename, the radius is converted to a string with two decimal places, which should be sufficient. These are ASCII files where each line has columns

$t$, $Re\phantom{\rule{0.17em}{0ex}}{C}^{lm}$, $Im\phantom{\rule{0.17em}{0ex}}{C}^{lm}$.

#### 4.3 Special Behaviour

Often it will be necessary to go beyond the basic usage described in the previous section.

##### 4.3.1 Higher modes

By default, Multipole computes only $l=2$ modes. You can choose whether to extract a single mode, or all modes from $l=$ l_min to $l=$ l_mode, with $|m|\le$ m_mode. This is controlled by the mode_type parameter, which can be set to "all_modes" or "specific_mode". The parameters l_min and l_mode specify the lowest and highest modes to compute. The parameter m_mode specifies up to which value of $m$ to compute. When using mode_type = "specific_mode", the mode $l$ and $m$ are given by l_mode and m_mode respectively.

##### 4.3.2 Variable options

Several variable-specific options can be listed as tags in the variables parameter:

Multipole::variables = "<imp>::<var>{<tagname> = <tagvalue> ... } ..."


Valid tags are:

 cmplx A string giving the fully qualified variable name for the imaginary part of a complex field, assuming that :: is the real part. name A string giving an alias to use for the decomposed variable in the output filename, for use in the case of complex variable when otherwise the name of the real part would be used, which might be confusing. sw The integer spin-weight of the spherical harmonic decomposition to use.

Strings should be enclosed in single quotes within the list of tags.

##### 4.3.3 Complex variables

In order to decompose a complex quantity, Multipole currently requires that the field is stored in two separate CCTK_REAL grid functions, one for the real and one for the imaginary part. Suppose the complex function $u$ is stored in two gridfunctions u_re and u_im. In order to correctly decompose $u$, specify the real variable in the variables parameter, and use the tag cmplx to specify the name of its imaginary companion:

Multipole::variables = "MyThorn::u_re{cmplx = ’MyThorn::u_im’}"


##### 4.3.4 Renaming variables

In some cases, you might want the name of the variable in the output filename to be different to the name of the grid function. This can be done by setting the name tag of the variable:

Multipole::variables = "MyThorn::u{name = ’myfunction’}"


For example, in the case of a complex variable where the output file contains the name of the real part, you can rename it as follows:

Multipole::variables = "MyThorn::u_re{cmplx = ’MyThorn::u_im’ name = ’u’}"


##### 4.3.5 Spin weight

Depending on the nature of the field to be decomposed, a spin-weight other than 0 might be required in the spherical harmonic basis. Use the tag sw for this

Multipole::variables = "MyThorn::u_re{cmplx = ’MyThorn::u_im’ name = ’u’ sw = -2}"


##### 4.3.6 Interpolator options

The interpolator to be used can be specified in the interpolator_name parameter, and a string containing interpolator parameters can be specified in the interpolator_pars parameter. See the interpolator (for example AEIThorns/AEILocalInterp) documentation for details of interpolators available and their options.

##### 4.3.7 Output

When used with mesh-refinement, it is common to require mode decomposition less frequently than every iteration. The parameter out_every can be used to control this. 1D and 2D output of the coordinate spheres can be enabled using out_1d_every and out_2d_every.

#### 4.4 Interaction With Other Thorns

This thorn obtains grid function data via the standard Cactus interpolator interface. To use this, one needs the parallel driver (for example PUGHInterp or CarpetInterp) as well as the low-level interpolator (e.g. AEILocalInterp).

#### 4.5 Examples

To use this thorn with WeylScal4 to compute modes of the complex ${\mathrm{\Psi }}_{4}$ variable, one could use the following example:

ActiveThorns = ".... WeylScal4 CarpetInterp AEILocalInterp Multipole"

Multipole::variables = "WeylScal4::Psi4r{sw=-2 cmplx=’WeylScal4::Psi4i’}"
Multipole::l_mode    = 4
Multipole::m_mode    = 4


### 5 History

This thorn was developed in the Penn State Numerical Relativity group and contributed to the Einstein Toolkit.

#### 5.1 Acknowledgements

This thorn was written by Ian Hinder and Andrew Knapp, with contributions from Eloisa Bentivegna and Shaun Wood.

### References

   J. N. Goldberg, A. J. MacFarlane, E. T. Newman, F. Rohrlich, and E. C. G. Sudarshan. Spin s spherical harmonics and edth. J. Math. Phys., 8:2155, 1967.

### 6 Parameters

 coord_system Scope: restricted STRING Description: What is the coord system? Range Default: cart3d .* Any smart string will do

 enable_test Scope: restricted BOOLEAN Description: whether to set a spherical harmonic in the ’harmonic’ grid functions Default: no

 hdf5_chunk_size Scope: restricted INT Description: How many iterations to preallocate in extensible HDF5 datasets Range Default: 200 1:* Any integer

 integration_method Scope: restricted KEYWORD Description: How to do surface integrals Range Default: midpoint midpoint Midpoint rule (2nd order) trapezoidal Trapezoidal rule (2nd order) Simpson Simpson’s rule (4th order) [requires even ntheta and nphi] DriscollHealy Driscoll & Healy (exponentially convergent) [requires even ntheta]

 interpolator_name Scope: restricted STRING Description: Which interpolator should I use Range Default: Hermite polynomial interpolation .+ Any nonempty string

 interpolator_pars Scope: restricted STRING Description: Parameters for the interpolator Range Default: order=3 boundary_off_centering_tolerance={0.0 0.0 0.0 0.0 0.0 0.0} boundary_extrapolation_tolerance={0.0 0.0 0.0 0.0 0.0 0.0} .* ”Any string that Util_TableSetFromStr ing() will take”

 l_max Scope: restricted INT Description: The maximum l mode to extract Range Default: 2 0:* l >= 0

 l_min Scope: restricted INT Description: all modes: above which l mode to calculate/ specific mode: which l mode to extract Range Default: -1 -1:* Deprecated

 l_mode Scope: restricted INT Description: The maximum l mode to extract Range Default: -1 -1:* Deprecated

 m_mode Scope: restricted INT Description: all modes: Up to which m mode to calculate/ specific mode: which m mode to extract Range Default: -100 -100:* Deprecated

 mode_type Scope: restricted KEYWORD Description: Which type of mode extraction do we have Range Default: deprecated all modes Extract all modes up to (l_mode, m_mode). specific mode Select one specific (l_mode, m_mode) mode deprecated Deprecated

 nphi Scope: restricted INT Description: The number of points in the phi direction, minus one. (E.g., if this is set to 100, then 101 points will be chosen.) Range Default: 100 1:*

 nradii Scope: restricted INT Description: How many extraction radii? Range Default: 1 0:100

 ntheta Scope: restricted INT Description: The number of points in the theta direction, minus one. (E.g., if this is set to 50, then 51 points will be chosen.) Range Default: 50 0:* Positive please

 out_1d_every Scope: restricted INT Description: How often to output 1d data Range Default: (none) no output 1:* output every to many iterations

 out_dir Scope: restricted STRING Description: Output directory for Extract’s files, overrides IO::out_dir Range Default: (none) .+ A valid directory name \$^ An empty string to choose the default from IO::out_dir

 out_every Scope: restricted INT Description: How often to output Range Default: 1 no output 1:* output every to many iterations

 output_ascii Scope: restricted BOOLEAN Description: Output a simple ASCII file for each mode at each radius Default: yes

 output_hdf5 Scope: restricted BOOLEAN Description: Output an HDF5 file for each variable containing one dataset per mode at each radius Default: no

 radius Scope: restricted REAL Description: The radii for extraction Range Default: 0.0 0.0:* Please keep it in the grid

 test_l Scope: restricted INT Description: which mode to put into the test variables Range Default: 2 * Any integer

 test_m Scope: restricted INT Description: which mode to put into the test variables Range Default: 2 * Any integer

 test_mode_proportional_to_r Scope: restricted BOOLEAN Description: whether the test spherical harmonic coefficient is proportional to the radial coordinate Default: no

 test_sw Scope: restricted INT Description: which spin weight to put into the test variables Range Default: -2 * Any integer

 variables Scope: restricted STRING Description: What variables to decompose Range Default: (none) .* A list of variables

 verbose Scope: restricted BOOLEAN Description: Output detailed information about what is happening Default: no

 io_out_dir Scope: shared from IO STRING

### 7 Interfaces

Implements:

multipole

Inherits:

grid

#### Grid Variables

##### 7.0.1 PUBLIC GROUPS
 Group Names Variable Names Details harmonics compact 0 harmonic_re description Spherical harmonics harmonic_im dimensions 3 distribution DEFAULT group type GF timelevels 1 variable type REAL test_integration_convergence_orders compact 0 test_midpoint_convergence_order description Test integration convergence orders test_trapezoidal_convergence_order dimensions 0 test_simpson_convergence_order distribution CONSTANT group type SCALAR timelevels 1 variable type REAL test_integration_results compact 0 test_midpoint_result_low description Test integration results test_midpoint_result_high dimensions 0 test_trapezoidal_result_low distribution CONSTANT test_trapezoidal_result_high group type SCALAR test_simpson_result_low timelevels 1 test_simpson_result_high variable type REAL test_integration_symmetries compact 0 test_midpoint_pi_symmetry description Test integration symmetries test_trapezoidal_pi_symmetry dimensions 0 test_simpson_pi_symmetry distribution CONSTANT test_driscollhealy_pi_symmetry group type SCALAR timelevels 1 variable type REAL test_orthonormality test_orthonormality compact 0 description Test orthonormality of spherical harmonics dimensions 2 distribution CONSTANT group type ARRAY size 1 size (10*10)*(10*10+1)/2 timelevels 1 variable type REAL

### 8 Schedule

This section lists all the variables which are assigned storage by thorn EinsteinAnalysis/Multipole. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

#### Storage

 Conditional: harmonics test_integration_convergence_orders test_integration_results test_integration_symmetries test_orthonormality

#### Scheduled Functions

CCTK_ANALYSIS (conditional)

multipole_calc

calculate multipoles

 After: calc_np psikadelia accelerator_copyback Language: c Options: global Type: function

CCTK_INITIAL (conditional)

multipole_setharmonic

populate grid functions with spherical harmonics

 Language: c Reads: grid::coordinates(everywhere) Type: function Writes: multipole::harmonics(interior)

CCTK_INITIAL (conditional)

multipole_testorthonormality

loop over modes and integrate them to check orthonormality

 Language: c Type: function

CCTK_PARAMCHECK (conditional)

multipole_paramcheck

check multipole parameters

 Language: c Options: global Type: function

CCTK_PARAMCHECK (conditional)

multipole_testintegrationconvergence

test convergence of integration

 Language: c Type: function

CCTK_PARAMCHECK (conditional)

multipole_testintegrationsymmetry

test symmetry of integration

 Language: c Type: function