xx Multipole

Multipole

Ian Hinder

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 can be expanded in spin-weight spherical harmonics [1]:

where the coefficients are given by

At any given time, , this thorn can compute for a number of grid functions on several coordinate spheres with radii . The coordinate system of the Cactus grids must be Cartesian and the coordinates , , are related to , and by the usual transformation between Cartesian and spherical polar coordinates ( is the polar angle and is the azimuthal angle).

The spin-weighted spherical harmonics are computed using Eq.x3.1 in Ref.x[1].

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 with coordinates

so and count the number of cells (not the number of points). The gridfunction to be decomposed, , is first interpolated from the 3D Cactus grid onto this 2D grid at a given radius, , and the are computed by evaluating the integral in Eq.x?? for different values of and . 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 and , 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, , for which you want to compute the spherical harmonic coefficients . 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 are zero-based). For example,

ActiveThornsx=x"....xAEILocalInterpxMultipole"
Multipole::nradiixxxxxxx=x3
Multipole::radius[0]xxxx=x10
Multipole::radius[1]xxxx=x20
Multipole::radius[2]xxxx=x30
Multipole::variablesxxxx=x"MyThorn::u"

The default parameters will compute all modes assuming a spin-weight on every iteration of your simulation. The coefficients 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

, , .

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 modes. You can choose whether to extract a single mode, or all modes from l_min to l_mode, with 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 to compute.

When using mode_type = "specific_mode", the mode and 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::variablesx=x"<imp>::<var>{<tagname>x=x<tagvalue>x...x}x..."

Valid tags are:

11cmplx11A string giving the fully qualified variable name for the imaginary part of a complex field, assuming that <imp>::<var> is the real part.
11name 11A 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.

11sw 11The 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 is stored in two gridfunctions u_re and u_im. In order to correctly decompose , specify the real variable in the variables parameter, and use the tag cmplx to specify the name of its imaginary companion:

Multipole::variablesx=x"MyThorn::u_re{cmplxx=x'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::variablesx=x"MyThorn::u{namex=x'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::variablesx=x"MyThorn::u_re{cmplxx=x'MyThorn::u_im'xnamex=x'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::variablesx=x"MyThorn::u_re{cmplxx=x'MyThorn::u_im'xnamex=x'u'xswx=x-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 variable, one could use the following example:

ActiveThornsx=x"....xWeylScal4xCarpetInterpxAEILocalInterpxMultipole"
Multipole::nradiixxxx=x3
Multipole::radius[0]x=x10
Multipole::radius[1]x=x20
Multipole::radius[2]x=x30
Multipole::variablesx=x"WeylScal4::Psi4r{sw=-2xcmplx='WeylScal4::Psi4i'}"
Multipole::l_modexxxx=x4
Multipole::m_modexxxx=x4

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 [1]xxxJ.xN. Goldberg, A.xJ. MacFarlane, E.xT. Newman, F.xRohrlich, and E.xC.xG. Sudarshan. Spin

s spherical harmonics and edth. J. Math. Phys., 8:2155, 1967.

6 Parameters

11coordxsystem 10Scope: restrictedx01 STRING

11Description: What is the coord system?

11 Range 10 x01 Default: cart3d
11.*  10Any smart string will do

11

11enablextest  10Scope: restrictedx01  BOOLEAN

11Description: whether to set a spherical harmonic in the ’harmonic’ grid functions

11                     10  x01  Default: no

11

11hdf5xchunkxsize  10Scope: restrictedx01  INT

11Description: How many iterations to preallocate in extensible HDF5 datasets

11 Range 10 x01 Default: 200
111:*  10Any integer

11

11integrationxmethod  10Scope: restrictedx01  KEYWORD

11Description: How to do surface integrals

11 Range 10 x01 Default: midpoint
11midpoint  10Midpoint rule (2nd order)
11trapezoidal  10Trapezoidal rule (2nd order)
11Simpson  10Simpson’s rule (4th order) [requires even ntheta and nphi]
11DriscollHealy  10Driscoll & Healy (exponentially convergent) [requires even ntheta]

11

11interpolatorxname  10Scope: restrictedx01  STRING

11Description: Which interpolator should I use

11 Range 10 x01 Default: Hermite polynomial interpolation
11.+  10Any nonempty string

11

11interpolatorxpars  10Scope: restrictedx01  STRING

11Description: Parameters for the interpolator

11 Range 10 x01Default: order=3 boundaryxoffxcenteringxtolerance={0.0 0.0 0.0 0.0 0.0 0.0} boundaryxextrapolationxtolerance={0.0 0.0 0.0 0.0 0.0 0.0}
11.*  10”Any string that UtilxTableSetFromStr ing() will take”

11

11lxmax  10Scope: restrictedx01  INT

11Description: The maximum l mode to extract

11 Range 10 x01 Default: 2
110:*  10l >= 0 11
11lxmin  10Scope: restrictedx01  INT

11Description: all modes: above which l mode to calculate/ specific mode: which l mode to extract

11 Range 10 x01 Default: -1
11-1:*  10Deprecated

11lxmode  10Scope: restrictedx01  INT

11Description: The maximum l mode to extract

11 Range 10 x01 Default: -1
11-1:*  10Deprecated

11

11mxmode  10Scope: restrictedx01  INT

11Description: all modes: Up to which m mode to calculate/ specific mode: which m mode to extract

11  Range  10  x01  Default: -100
11-100:*  10Deprecated

11

11modextype  10Scope: restrictedx01  KEYWORD

11Description: Which type of mode extraction do we have

11 Range 10 x01 Default: deprecated
11all modes  10Extract all modes up to (lxmode, mxmode).
11specific mode  10Select one specific (lxmode, mxmode) mode
11deprecated  10Deprecated

11

11nphi  10Scope: restrictedx01  INT

11Description: The number of points in the phi direction, minus one. (E.g., if this is set to 100, then 101 points will be chosen.)

11  Range  10  x01  Default: 100

111:*  10

11

11nradii  10Scope: restrictedx01  INT

11Description: How many extraction radii?

11 Range 10 x01 Default: 1
110:100  10

11

11ntheta  10Scope: restrictedx01  INT

11Description: The number of points in the theta direction, minus one. (E.g., if this is set to 50, then 51 points will be chosen.)

11  Range  10  x01  Default: 50
110:*  10Positive please

11

11outx1dxevery  10Scope: restrictedx01  INT

11Description: How often to output 1d data

11 Range 10 x01 Default: (none)
11                     10no output
111:*  10output every to many iterations

11

11outxdir  10Scope: restrictedx01  STRING

11Description: Output directory for Extract’s files, overrides IO::outxdir

11 Range 10 x01 Default: (none)
11.+  10A valid directory name
11ˆ$  10An empty string to choose the default from IO::outxdir

11

11outxevery  10Scope: restrictedx01  INT

11Description: How often to output

11 Range 10 x01 Default: 1
11                     10no output
111:*  10output every to many iterations

11outputxascii  10Scope: restrictedx01  BOOLEAN

11Description: Output a simple ASCII file for each mode at each radius

11                     10  x01  Default: yes

11

11outputxhdf5  10Scope: restrictedx01  BOOLEAN

11Description: Output an HDF5 file for each variable containing one dataset per mode at each radius

11                     10  x01  Default: no

11

11radius  10Scope: restrictedx01  REAL

11Description: The radii for extraction

11 Range 10 x01 Default: 0.0
110.0:*  10Please keep it in the grid

11

11testxl  10Scope: restrictedx01  INT

11Description: which mode to put into the test variables

11 Range 10 x01 Default: 2
11*  10Any integer

11

11testxm  10Scope: restrictedx01  INT

11Description: which mode to put into the test variables

11 Range 10 x01 Default: 2
11*  10Any integer

11

11testxmodexproportionalxtoxr 10Scope: restrictedx01  BOOLEAN

11Description: whether the test spherical harmonic coefficient is proportional to the radial coordinate

11                     10  x01  Default: no

11

11testxsw  10Scope: restrictedx01  INT

11Description: which spin weight to put into the test variables

11 Range 10 x01 Default: -2
11*  10Any integer

11

11variables  10Scope: restrictedx01  STRING

11Description: What variables to decompose

11 Range 10 x01 Default: (none)
11.*  10A list of variables

11

11verbose  10Scope: restrictedx01  BOOLEAN

11Description: Output detailed information about what is happening

11                     10  x01  Default: no

11

11ioxoutxdir  10Scope: shared from IOx01STRING

7 Interfaces

General Implements: multipole

Inherits: grid

Grid Variables

7.0.1 PUBLIC GROUPS

11  x Group Names x  10  x Variable Names x  x01 Details x11x
11  harmonics  10  x01  compact110
11                              10  harmonicxre  x01 description11Spherical harmonics
11                              10  harmonicxim  x01 dimensions113
11                              10  x01 distribution11DEFAULT
11                              10  x01 group type11GF
11                              10  x01 timelevels111
11                              10  x01variable type11REAL
11testxintegrationxconvergencexorders10 x01 compact110
11                              10 testxmidpointxconvergencexorder x01 description11Test integration convergence orders
11                              10testxtrapezoidalxconvergencexorderx01 dimensions110
11                              10 testxsimpsonxconvergencexorder x01 distribution11CONSTANT
11                              10  x01 group type11SCALAR
11                              10  x01 timelevels111
11                              10  x01variable type11REAL
11  testxintegrationxresults  10  x01  compact110
11                              10  testxmidpointxresultxlow  x01 description11Test integration results
11                              10  testxmidpointxresultxhigh  x01 dimensions110
11                              10 testxtrapezoidalxresultxlow x01 distribution11CONSTANT
11                              10 testxtrapezoidalxresultxhigh x01 group type11SCALAR
11                              10  testxsimpsonxresultxlow  x01 timelevels111
11                              10  testxsimpsonxresultxhigh  x01variable type11REAL
11 testxintegrationxsymmetries 10  x01  compact110
11                              10 testxmidpointxpixsymmetry x01 description11Test integration symmetries
11                              10 testxtrapezoidalxpixsymmetry x01 dimensions110
11                              10 testxsimpsonxpixsymmetry x01 distribution11CONSTANT
11                              10 testxdriscollhealyxpixsymmetry x01 group type11SCALAR
11                              10  x01 timelevels111
11                              10  x01variable type11REAL
11 testxorthonormality 10 testxorthonormality x01 compact110
11                              10  x01 description11Test orthonormality of spherical harmonics
11                              10  x01 dimensions112
11                              10  x01 distribution11CONSTANT
11                              10  x01 group type11ARRAY

11                              10  x01  size111

11                              10  x  x01  size11(10*10)*(10*10+1)/2
11                              10  x01 timelevels111
11                              10  x01variable type11REAL

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 x

11x11Conditional:
11x 11harmonics[1]
11x 11testxintegrationxconvergencexorders
11x 11testxintegrationxresults
11x 11testxintegrationxsymmetries
11x 11testxorthonormality

11x 11x

11

Scheduled Functions

CCTKxANALYSIS (conditional) x multipolexcalc x calculate multipoles x

11x11After: 11calcxnp
11 x 11x  11psikadelia
11 x 11x  11acceleratorxcopyback
11 x 11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

CCTKxINITIAL (conditional) x multipolexsetharmonic x populate grid functions with spherical harmonics x

11x11Language:11c
11 x 11Reads: 11grid::coordinates(everywhere)
11 x 11Type: 11function
11 x 11Writes: 11multipole::harmonics(interior)

CCTKxINITIAL (conditional) x multipolextestorthonormality x loop over modes and integrate them to check orthonormality x

11x11Language:11c
11 x 11Type: 11function

11

CCTKxPARAMCHECK (conditional) x multipolexparamcheck x check multipole parameters x

11x11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

CCTKxPARAMCHECK (conditional) x multipolextestintegrationconvergence x test convergence of integration x

11x11Language:11c
11 x 11Type: 11function

11

CCTKxPARAMCHECK (conditional) x multipolextestintegrationsymmetry x test symmetry of integration x

11x11Language:11c
11 x 11Type: 11function