xx SphericalSurface

SphericalSurface

Erik Schnetter <schnetter@cct.lsu.edu>

2007-03-06

Abstract

This thorn provides a repository for two-dimensional surfaces with spherical topology. This thorn does not actually do anything with these surfaces, but allows other thorns to store and retrieve the surfaces and some associated information. The exact interpretation of the stored quantities is up to the using thorns, but certain standard definitions are suggested.

1 Introduction

Many thorns work on manifolds that are two-dimensional, closed surfaces. Examples are apparent and event horizons, or the surfaces on which gravitational waves are extracted. Other such surfaces might be excision or outer boundaries (although these are currently not treated as such). There is a need to have a common representation for such surfaces, so that the surface-finding thorns and the thorns working with these surfaces can be independent. A common representation will also facilitate visualisation. This thorn SphericalSurface provides just such a common representation.

This thorn is not meant to do anything else but be a “repository” for surfaces. It is up to the surface-finding and surface-using thorns to agree on the details of the information stored. Of course, standard definitions for the stored quantities are suggested. (For example, there is no exact definition of the quadrupole moment, because this definition will depend on the kind of surface that is stored. However, it is specified that the quadrupole moment should be calculate with respect to the centroid, and that it should not be trace-free.)

This thorn provides storage for several independent surfaces, identified by an index. It is up to the user to specify, probably in the parameter file, which thorns use what surfaces for what purpose.

2 Surface Definition

This thorn provides, for each surface, a two-dimensional grid array sfxradius and grid scalars sfxoriginxx, sfxoriginxy, and sfxoriginxz. The number of surfaces is determined by the parameter nsurfaces, which has to be set in the parameter file.

sfxradius should contain the radius of the surface as measured from its origin, where the arrays indices vary in the and direction, respectively. Both the radius array and the surface origin are supposed to be set when a surface is stored.

The coordinates on the surface, i.e.xthe grid origin and spacing in the and directions, is available from the grid

scalars sfxoriginxtheta, sfxoriginxphi, sfxdeltaxtheta, and sfxdeltaxphi. These grid scalars are

set by the thorn SphericalSurface in the basegrid bin, and are meant to be read-only for other thorns.

A note on vector grid variables A relatively new addition to Cactus (in November 2003) are vector grid variables. These are essentially arrays of grid variables. Thorn SphericalSurface makes use of these by storing the surfaces in such arrays. That means that in order to access data from a single surface, on has to use the corresponding surface index as array index. In a similar manner, thorn SurfaceIndex uses array parameters for its parameters (except certain global ones).

This should be kept in mind when writing source code. C has the unfortunate property of converting arrays into meaningless integers if an array subscript is accidentally omitted. Fortran knows whole-array expressions, meaning that it would act on all surfaces instead of a single one if an array subscript is accidentally omitted.

Each element of a vector grid function is a grid function. (The term “grid function vector” might have been more appropriate.) As such, it has a name, which can be used e.g.xfor output. The name consists of the vector grid function name to which the surface index in square brackets has been appended.

2.1 Global Surface Quantities

In many cases, only some abstract information about the surface is of interest, such as its mean radius or its quadrupole moment. For that purpose there are additional grid scalars that carry this information. These grid scalars are also supposed to be set when a surface is stored. These grid scalars are

sfxmeanxradius

Mean of the surface radius. This should be the arithmetic mean where the radii have been weighted with , or a suitable generalisation thereof. This quantity is also supposed to be a measure of the surface’s monopole moment. One suggested expression is with .

sfxminxradius, sfxmaxxradius

Minimum and maximum of the surface radius.

sfxcentroidxx, sfxcentroidxy, sfxcentroidxz

The centre of the surface. While the quantities sfxoriginx* denote the point from which the radius of the surface is measured, the quantities sfxcentroidx* should contain the point which is “logically” the centre of the surface. This quantity is supposed to be a measure of the dipole moment of the surface. One suggested expression is .

sfxquadrupolexxx, sfxquadrupolexxy, sfxquadrupolexxz, sfxquadrupolexyy, sfxquadrupolexyz, sfxquadrupolexzz

The quadrupole moment of the surface. This should be the full quadrupole moment and not a trace-free quantity. One suggested expression is with .

sfxminxx, sfxminxy, sfxminxz, sfxmaxxx, sfxmaxxy, sfxmaxxz

The bounding box of the surface.

Note that the integral expressions are only suggestions which should be adapted to whatever is natural for the stored surface. The suggested integral expressions also depend on the metric which is used; this should be a “natural” metric for the surface. E.g.xfor apparent horizons, this might be the induced two-metric from the projection of the ADM three-metric .

2.2 Validity of Surface Data

There is also an integer flag valid available. Its definition is up to the surface-providing thorn. The following interpretations are suggested:

zero:

No surface is provided at this time step.

negative:

No surface could be found at this time step.

positive:

The surface data are valid.

Note that, if this flag is used, it is necessary to set this flag at every iteration. This flag is not automatically reset to zero.

3 Surface Array Shape

The number of grid points in the radius array sfxradius is determined by the parameters ntheta and nphi. These arrays exist for each surface. (Internally, thorn SphericalSurface stores all surfaces with the same array shape maxntheta and maxnphi, so that the parameters ntheta and nphi must not be used for index calculations. Use the surfaces lsh instead.) The surface array shape includes ghost or boundary zones at the array edges. These ghost zones have the same size for all surfaces.

Note that because the radius arrays are stored with larger size , the actual radius data (of size elements) is in general not contiguous in memory. If you want to interpolate a SphericalSurface surface radius, you need to either copy the radius data to a contiguous 2-D array of size , or use an interpolator which supports such non-contiguous input arrays. The AEIThorns/AEILocalInterp local interpolation thorn supports these via the inputxarrayxstrides parameter-table option. See the AEILocalInterp thorn guide for details.

4 Surface Symmetries

It is often the case that one uses symmetries to reduce the size of the simulation domain, such as octant or quadrant mode. Whenever a symmetry plane intersects a surface, only part of the surface is actually stored. The user has to define the symmetries of each surface in the parameter file via the parameters sfxsymmetryxx, sfxsymmetryxy, and sfxsymmetryxz. They indicate that a reflection symmetry exists in the corresponding direction. The surface origin is required to lie in the corresponding symmetry planes.

Thorn SphericalSurface takes these symmetries into account when it calculates the grid spacing and the origin of the surface coordinates and .

5 Input and Output

As the surfaces are stored as grid variables, the standard input and output routines will work for them. The standard visualisation tools will be able to visualise them. The surfaces will also automatically be checkpointed and restored.

5.1 Acknowledgements

This thorn was suggested during meetings of the numerical relativity group at the AEI. Jonathan Thornburg provided many detailed and useful suggestions. Ed Evans, Carsten Gundlach, Ian Hawke, and Denis Pollney contributed comments and suggestions.

6 Parameters

11originxx 10Scope: privatex01 REAL

11Description: Origin for surface

11 Range 10 x01 Default: 0.0
11*  10origin

11

11originxy  10Scope: privatex01  REAL

11Description: Origin for surface

11 Range 10 x01 Default: 0.0
11*  10origin

11

11originxz  10Scope: privatex01  REAL

11Description: Origin for surface

11 Range 10 x01 Default: 0.0
11*  10origin

11

11radius  10Scope: privatex01  REAL

11Description: Radius for surface

11 Range 10 x01 Default: 0.0
11*  10radius

11

11radiusxx  10Scope: privatex01  REAL

11Description: Radius for surface

11 Range 10 x01 Default: 0.0
11*  10radius

11

11radiusxy  10Scope: privatex01  REAL

11Description: Radius for surface

11 Range 10 x01 Default: 0.0
11*  10radius

11

11radiusxz  10Scope: privatex01  REAL

11Description: Radius for surface

11 Range 10 x01 Default: 0.0
11*  10radius

11

11setxelliptic 10Scope: privatex01  BOOLEAN

11Description: Place surface at a certain radius

11             10  x01  Default: no

11

11setxspherical 10Scope: privatex01  BOOLEAN

11Description: Place surface at a certain radius

11             10  x01  Default: no

11

11autoxres  10Scope: restrictedx01  BOOLEAN

11Description: Automatically determine resolution according to radius and Cartesian resolution

11             10  x01  Default: no

11autoxresxgrid 10Scope: restrictedx01  KEYWORD

11Description: Choose resolution according to how grids overlap

11 Range 10 x01 Default: fully contained
11fully contained 10SF must be fully contained in Cartesian grid
11overlap  10SF overlaps with grid
11multipatch  10SF potentially overlaps with a spherical mutipatch grid

11

11autoxresxratio 10Scope: restrictedx01  REAL

11Description: Multiplicative factor by which we want to scale the resolution with respect to Cartesian resolution

11 Range 10  x01  Default: 2.0

110:*  10

11

11maxnphi  10Scope: restrictedx01  INT

11Description: Maximum number of grid points in the phi direction

11 Range 10  x01  Default: 38

110:*  10

11

11maxntheta 10Scope: restrictedx01  INT

11Description: Maximum number of grid points in the theta direction

11 Range 10  x01  Default: 19

110:*  10

11

11name  10Scope: restrictedx01  STRING

11Description: User friendly name of spherical surface

11 Range 10 x01 Default: (none)
11             10none set
11.*  10any string

11

11nghostsphi 10Scope: restrictedx01  INT

11Description: Number of ghost zones in the phi direction

11 Range 10  x01  Default: 2

110:*  10

11

11nghoststheta 10Scope: restrictedx01  INT

11Description: Number of ghost zones in the theta direction

11 Range 10  x01  Default: 2

110:*  10

11

11nphi  10Scope: restrictedx01  INT

11Description: Number of grid points in the phi direction

11 Range 10 x01 Default: 38
110:*  10must be at least 3*nghostsphi

11

11nsurfaces  10Scope: restrictedx01  INT

11Description: Number of surfaces

11 Range 10  x01  Default: (none)

110:42  10

11

11ntheta  10Scope: restrictedx01  INT

11Description: Number of grid points in the theta direction

11 Range 10 x01 Default: 19
110:*  10must be at least 3*nghoststheta

11symmetricxx 10Scope: restrictedx01  BOOLEAN

11Description: Reflection symmetry in the x direction

11             10  x01  Default: no

11

11symmetricxy 10Scope: restrictedx01  BOOLEAN

11Description: Reflection symmetry in the y direction

11             10  x01  Default: no

11

11symmetricxz 10Scope: restrictedx01  BOOLEAN

11Description: Reflection symmetry in the z direction

11             10  x01  Default: no

11

11verbose  10Scope: restrictedx01  BOOLEAN

11Description: Shall I be verbose?

11             10  x01  Default: no

11

7 Interfaces

General Implements: sphericalsurface

Inherits: grid

Grid Variables

7.0.1 PRIVATE GROUPS

11 x Group Names x 10 x Variable Names x x01 Details x11x
11sfxcoordinatexestimators10 x01 compact110
11                     10sfxdeltaxthetaxestimatex01 description11Surface coordinate estimators
11                     10 sfxdeltaxphixestimate x01 dimensions110
11                     10  x01 distribution11CONSTANT
11                     10  x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01vararrayxsize11nsurfaces
11                     10  x01variable type11REAL

11

7.0.2 PUBLIC GROUPS

11x Group Names x10x Variable Names xx01 Details x11x
11 sfxactive 10 sfxactive x01 compact110
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01vararrayxsize11nsurfaces
11                 10  x01variable type11INT
11 sfxvalid 10 sfxvalid x01 compact110
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01vararrayxsize11nsurfaces
11                 10  x01variable type11INT
11  sfxinfo  10  x01  compact110
11                 10  sfxarea  x01 description11Surface information
11                 10 sfxmeanxradius x01 dimensions110
11                 10 sfxcentroidxx x01 distribution11CONSTANT
11                 10 sfxcentroidxy x01 group type11SCALAR
11                 10 sfxcentroidxz x01 timelevels111
11                 10 sfxquadrupolexxx x01vararrayxsize11nsurfaces
11                 10 sfxquadrupolexxy x01variable type11REAL
11 sfxminreflevel 10 sfxminreflevel x01  compact110
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01vararrayxsize11nsurfaces
11                 10  x01variable type11INT
11 sfxmaxreflevel 10 sfxmaxreflevel x01  compact110
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01vararrayxsize11nsurfaces
11                 10  x01variable type11INT
11 sfxradius 10 sfxradius x01 compact110
11                 10  x01 dimensions112
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11ARRAY
11                 10  x01  size11MAXNTHETA
11                 10  x  x01  size11MAXNPHI
11                 10  x01 timelevels111
11                 10  x01vararrayxsize11nsurfaces
11                 10  x01variable type11REAL

11 x Group Names x 10x Variable Names xx01 Details x11x
11  sfxorigin  10  x01  compact110
11                     10  sfxoriginxx  x01 dimensions110
11                     10  sfxoriginxy  x01 distribution11CONSTANT
11                     10  sfxoriginxz  x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01vararrayxsize11nsurfaces
11                     10  x01variable type11REAL
11sfxcoordinatexdescriptors10 x01 compact110
11                     10 sfxoriginxtheta x01 description11Surface coordinate descriptors
11 10 sfxoriginxphi x01 dimensions110
11                     10 sfxdeltaxtheta x01 distribution11CONSTANT
11 10 sfxdeltaxphi x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01vararrayxsize11nsurfaces
11                     10  x01variable type11REAL
11 sfxshapexdescriptors 10  x01  compact110
11                     10  sfxntheta  x01 description11Surface shape descriptors
11                     10  sfxnphi  x01 dimensions110
11                     10 sfxnghoststheta x01 distribution11CONSTANT
11                     10 sfxnghostsphi x01 group type11SCALAR
11                     10  x01 timelevels111
11                     10  x01vararrayxsize11nsurfaces
11                     10  x01variable type11INT

11

Provides: sfxIdFromName to

8 Schedule This section lists all the variables which are assigned storage by thorn CactusNumerical/SphericalSurface. 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

11Always:  11x
11sfxactive  11x
11sfxvalid  11x
11sfxinfo  11x
11sfxradius sfxorigin  11x
11sfxcoordinatexdescriptors11x
11sfxcoordinatexestimators 11x
11sfxshapexdescriptors  11x
11sfxminreflevel  11x
11sfxmaxreflevel  11x

11x  11x

Scheduled Functions

CCTKxBASEGRID x sphericalsurfacexsetupres x set surface resolution automatically x

11x11After: 11spatialcoordinates
11 x 11x  11correctcoordinates
11 x 11Before: 11sphericalsurfacexsetup
11 x 11Language:11c
11 x 11Options: 11global
11 x 11x  11loop-local
11 x 11Type: 11function
11 x 11Writes: 11sphericalsurface::sfxcoordinatexestimators(everywhere)
11 x 11x  11sphericalsurface::sfxminreflevel(everywhere)
11 x 11x  11sphericalsurface::sfxmaxreflevel(everywhere)

11

CCTKxBASEGRID x sphericalsurfacexsetup x calculate surface coordinate descriptors x

11x11Language:11c
11 x 11Options: 11global
11 x 11Reads: 11sphericalsurface::sfxcoordinatexestimators
11 x 11x  11sphericalsurface::sfxminreflevel
11 x 11x  11sphericalsurface::sfxmaxreflevel
11 x 11Type: 11function
11 x 11Writes: 11sphericalsurface::sfxshapexdescriptors(everywhere)
11 x 11x  11sphericalsurface::sfxcoordinatexdescriptors(everywhere)
11 x 11x  11sphericalsurface::sfxactive(everywhere)
11 x 11x  11sphericalsurface::sfxvalid(everywhere)

11

CCTKxBASEGRID x sphericalsurfacexset x set surface radii to be used for initial setup in other thorns x

11x11Before: 11sphericalsurfacexhasbeenset
11 x 11Language:11c
11 x 11Options: 11global
11 x 11Reads: 11sphericalsurface::sfxshapexdescriptors
11 x 11x  11sphericalsurface::sfxcoordinatexdescriptors
11 x 11Type: 11function
11 x 11Writes: 11sphericalsurface::sfxactive(everywhere)
11 x 11x  11sphericalsurface::sfxvalid(everywhere)
11 x 11x  11sphericalsurface::sfxinfo(everywhere)
11 x 11x  11sphericalsurface::sfxorigin(everywhere)
11 x 11x  11sphericalsurface::sfxradius(everywhere)

11

CCTKxBASEGRID x sphericalsurfacexhasbeenset x set the spherical surfaces before this group, and use it afterwards

11x11Type:11group

11

CCTKxPOSTSTEP x sphericalsurfacexset x set surface radii x

11x11Before: 11sphericalsurfacexhasbeenset
11 x 11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

CCTKxPOSTSTEP x sphericalsurfacexhasbeenset x set the spherical surfaces before this group, and use it afterwards x

11x11Type:11group

11

SphericalSurfacexHasBeenSet x sphericalsurfacexcheckstate x test the state of the spherical surfaces x

11x11Language:11c
11 x 11Options: 11global
11 x 11Reads: 11sphericalsurface::sfxvalid
11 x 11x  11sphericalsurface::sfxactive
11 x 11Type: 11function

11

CCTKxPARAMCHECK x sphericalsurfacexparamcheck x check that all surface names are unique x

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