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. for 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

sf_mean_radius

Mean of the surface radius. This should be the arithmetic mean where the radii have been weighted with \(\sin \theta \), or a suitable generalisation thereof. This quantity is also supposed to be a measure of the surface’s monopole moment. One suggested expression is \(M=\sqrt {A}\) with \(A = \int _S d\Omega \, r^2 / \int _S d\Omega \).

sf_min_radius, sf_max_radius

Minimum and maximum of the surface radius.

sf_centroid_x, sf_centroid_y, sf_centroid_z

The centre of the surface. While the quantities sf_origin_* denote the point from which the radius of the surface is measured, the quantities sf_centroid_* 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 \(D^i = \int _S d\Omega \, x^i / A\).

sf_quadrupole_xx, sf_quadrupole_xy, sf_quadrupole_xz, sf_quadrupole_yy, sf_quadrupole_yz, sf_quadrupole_zz

The quadrupole moment of the surface. This should be the full quadrupole moment and not a trace-free quantity. One suggested expression is \(Q^{ij} = \int _S d\Omega \, y^i y^j / A\) with \(y^i = x^i - D^i\).

sf_min_x, sf_min_y, sf_min_z, sf_max_x, sf_max_y, sf_max_z

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. for apparent horizons, this might be the induced two-metric \(q_{ij}\) from the projection of the ADM three-metric \(\gamma _{ij}\).

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 sf_radius 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 \(\code {maxntheta} \times \code {maxnphi}\), the actual radius data (of size \(\code {ntheta[surface\_number]} \times \code {nphi[surface\_number]}\) 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 \(\code {ntheta[surface\_number]} \times \code {nphi[surface\_number]}\), or use an interpolator which supports such non-contiguous input arrays. The AEIThorns/AEILocalInterp local interpolation thorn supports these via the input_array_strides 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 sf_symmetry_x, sf_symmetry_y, and sf_symmetry_z. 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 \(\theta \) and \(\phi \).

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

7 Interfaces

General

Implements:

sphericalsurface

Inherits:

grid

Grid Variables

7.0.1 PRIVATE GROUPS

7.0.2 PUBLIC GROUPS

Provides:

sf_IdFromName 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

 

Scheduled Functions

CCTK_BASEGRID

  sphericalsurface_setupres

  set surface resolution automatically

 

CCTK_BASEGRID

  sphericalsurface_setup

  calculate surface coordinate descriptors

 

CCTK_BASEGRID

  sphericalsurface_set

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

 

CCTK_BASEGRID

  sphericalsurface_hasbeenset

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

 

CCTK_POSTSTEP

  sphericalsurface_set

  set surface radii

 

CCTK_POSTSTEP

  sphericalsurface_hasbeenset

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

 

SphericalSurface_HasBeenSet

  sphericalsurface_checkstate

  test the state of the spherical surfaces

 

CCTK_PARAMCHECK

  sphericalsurface_paramcheck

  check that all surface names are unique