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.
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.
This thorn provides, for each surface, a two-dimensional grid array sf_radius and grid scalars sf_origin_x, sf_origin_y, and sf_origin_z. The number of surfaces is determined by the parameter nsurfaces, which has to be set in the parameter file.
sf_radius should contain the radius of the surface as measured from its origin, where the arrays indices vary in the \(\theta \) and \(\phi \) 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. the grid origin and spacing in the \(\theta \) and \(\phi \) directions, is available from the grid scalars sf_origin_theta, sf_origin_phi, sf_delta_theta, and sf_delta_phi. These grid scalars are set by the thorn SphericalSurface in the basegrid bin, and are meant to be read-only for other thorns.
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}\).
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.
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.
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 \).
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.
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.
| origin_x | Scope: private | REAL |
| Description: Origin for surface
| ||
| Range | Default: 0.0 | |
| * | origin
| |
| origin_y | Scope: private | REAL |
| Description: Origin for surface
| ||
| Range | Default: 0.0 | |
| * | origin
| |
| origin_z | Scope: private | REAL |
| Description: Origin for surface
| ||
| Range | Default: 0.0 | |
| * | origin
| |
| radius | Scope: private | REAL |
| Description: Radius for surface
| ||
| Range | Default: 0.0 | |
| * | radius
| |
| radius_x | Scope: private | REAL |
| Description: Radius for surface
| ||
| Range | Default: 0.0 | |
| * | radius
| |
| radius_y | Scope: private | REAL |
| Description: Radius for surface
| ||
| Range | Default: 0.0 | |
| * | radius
| |
| radius_z | Scope: private | REAL |
| Description: Radius for surface
| ||
| Range | Default: 0.0 | |
| * | radius
| |
| set_elliptic | Scope: private | BOOLEAN |
| Description: Place surface at a certain radius
| ||
| Default: no | ||
| set_spherical | Scope: private | BOOLEAN |
| Description: Place surface at a certain radius
| ||
| Default: no | ||
| auto_res | Scope: restricted | BOOLEAN |
| Description: Automatically determine resolution according to radius and Cartesian resolution
| ||
| Default: no | ||
| auto_res_grid | Scope: restricted | KEYWORD |
| Description: Choose resolution according to how grids overlap
| ||
| Range | Default: fully contained | |
| fully contained | SF must be fully contained in Cartesian grid
| |
| overlap | SF overlaps with grid
| |
| multipatch | SF potentially overlaps with a spherical mutipatch grid
| |
| auto_res_ratio | Scope: restricted | REAL |
| Description: Multiplicative factor by which we want to scale the resolution with respect to
Cartesian resolution
| ||
| Range | Default: 2.0 | |
| 0:* | ||
| maxnphi | Scope: restricted | INT |
| Description: Maximum number of grid points in the phi direction
| ||
| Range | Default: 38 | |
| 0:* | ||
| maxntheta | Scope: restricted | INT |
| Description: Maximum number of grid points in the theta direction
| ||
| Range | Default: 19 | |
| 0:* | ||
| name | Scope: restricted | STRING |
| Description: User friendly name of spherical surface
| ||
| Range | Default: (none) | |
| none set
| ||
| .* | any string
| |
| nghostsphi | Scope: restricted | INT |
| Description: Number of ghost zones in the phi direction
| ||
| Range | Default: 2 | |
| 0:* | ||
| nghoststheta | Scope: restricted | INT |
| Description: Number of ghost zones in the theta direction
| ||
| Range | Default: 2 | |
| 0:* | ||
| nphi | Scope: restricted | INT |
| Description: Number of grid points in the phi direction
| ||
| Range | Default: 38 | |
| 0:* | must be at least 3*nghostsphi
| |
| nsurfaces | Scope: restricted | INT |
| Description: Number of surfaces
| ||
| Range | Default: (none) | |
| 0:42 | ||
| ntheta | Scope: restricted | INT |
| Description: Number of grid points in the theta direction
| ||
| Range | Default: 19 | |
| 0:* | must be at least 3*nghoststheta
| |
| symmetric_x | Scope: restricted | BOOLEAN |
| Description: Reflection symmetry in the x direction
| ||
| Default: no | ||
| symmetric_y | Scope: restricted | BOOLEAN |
| Description: Reflection symmetry in the y direction
| ||
| Default: no | ||
| symmetric_z | Scope: restricted | BOOLEAN |
| Description: Reflection symmetry in the z direction
| ||
| Default: no | ||
| verbose | Scope: restricted | BOOLEAN |
| Description: Shall I be verbose?
| ||
| Default: no | ||
Implements:
sphericalsurface
Inherits:
grid
| Group Names | Variable Names | Details | |
| sf_coordinate_estimators | compact | 0 | |
| sf_delta_theta_estimate | description | Surface coordinate estimators | |
| sf_delta_phi_estimate | dimensions | 0 | |
| distribution | CONSTANT | ||
| group type | SCALAR | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | REAL | ||
| Group Names | Variable Names | Details | |
| sf_active | sf_active | compact | 0 |
| dimensions | 0 | ||
| distribution | CONSTANT | ||
| group type | SCALAR | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | INT | ||
| sf_valid | sf_valid | compact | 0 |
| dimensions | 0 | ||
| distribution | CONSTANT | ||
| group type | SCALAR | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | INT | ||
| sf_info | compact | 0 | |
| sf_area | description | Surface information | |
| sf_mean_radius | dimensions | 0 | |
| sf_centroid_x | distribution | CONSTANT | |
| sf_centroid_y | group type | SCALAR | |
| sf_centroid_z | timelevels | 1 | |
| sf_quadrupole_xx | vararray_size | nsurfaces | |
| sf_quadrupole_xy | variable type | REAL | |
| sf_minreflevel | sf_minreflevel | compact | 0 |
| dimensions | 0 | ||
| distribution | CONSTANT | ||
| group type | SCALAR | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | INT | ||
| sf_maxreflevel | sf_maxreflevel | compact | 0 |
| dimensions | 0 | ||
| distribution | CONSTANT | ||
| group type | SCALAR | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | INT | ||
| sf_radius | sf_radius | compact | 0 |
| dimensions | 2 | ||
| distribution | CONSTANT | ||
| group type | ARRAY | ||
| size | MAXNTHETA | ||
| size | MAXNPHI | ||
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | REAL | ||
| Group Names | Variable Names | Details | |
| sf_origin | compact | 0 | |
| sf_origin_x | dimensions | 0 | |
| sf_origin_y | distribution | CONSTANT | |
| sf_origin_z | group type | SCALAR | |
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | REAL | ||
| sf_coordinate_descriptors | compact | 0 | |
| sf_origin_theta | description | Surface coordinate descriptors | |
| sf_origin_phi | dimensions | 0 | |
| sf_delta_theta | distribution | CONSTANT | |
| sf_delta_phi | group type | SCALAR | |
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | REAL | ||
| sf_shape_descriptors | compact | 0 | |
| sf_ntheta | description | Surface shape descriptors | |
| sf_nphi | dimensions | 0 | |
| sf_nghoststheta | distribution | CONSTANT | |
| sf_nghostsphi | group type | SCALAR | |
| timelevels | 1 | ||
| vararray_size | nsurfaces | ||
| variable type | INT | ||
Provides:
sf_IdFromName to
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.
| Always: | |
| sf_active | |
| sf_valid | |
| sf_info | |
| sf_radius sf_origin | |
| sf_coordinate_descriptors | |
| sf_coordinate_estimators | |
| sf_shape_descriptors | |
| sf_minreflevel | |
| sf_maxreflevel | |
CCTK_BASEGRID
sphericalsurface_setupres
set surface resolution automatically
| After: | spatialcoordinates | |
| correctcoordinates | ||
| Before: | sphericalsurface_setup | |
| Language: | c | |
| Options: | global | |
| loop-local | ||
| Type: | function | |
| Writes: | sphericalsurface::sf_coordinate_estimators(everywhere) | |
| sphericalsurface::sf_minreflevel(everywhere) | ||
| sphericalsurface::sf_maxreflevel(everywhere) | ||
CCTK_BASEGRID
sphericalsurface_setup
calculate surface coordinate descriptors
| Language: | c | |
| Options: | global | |
| Reads: | sphericalsurface::sf_coordinate_estimators | |
| sphericalsurface::sf_minreflevel | ||
| sphericalsurface::sf_maxreflevel | ||
| Type: | function | |
| Writes: | sphericalsurface::sf_shape_descriptors(everywhere) | |
| sphericalsurface::sf_coordinate_descriptors(everywhere) | ||
| sphericalsurface::sf_active(everywhere) | ||
| sphericalsurface::sf_valid(everywhere) | ||
CCTK_BASEGRID
sphericalsurface_set
set surface radii to be used for initial setup in other thorns
| Before: | sphericalsurface_hasbeenset | |
| Language: | c | |
| Options: | global | |
| Reads: | sphericalsurface::sf_shape_descriptors | |
| sphericalsurface::sf_coordinate_descriptors | ||
| Type: | function | |
| Writes: | sphericalsurface::sf_active(everywhere) | |
| sphericalsurface::sf_valid(everywhere) | ||
| sphericalsurface::sf_info(everywhere) | ||
| sphericalsurface::sf_origin(everywhere) | ||
| sphericalsurface::sf_radius(everywhere) | ||
CCTK_BASEGRID
sphericalsurface_hasbeenset
set the spherical surfaces before this group, and use it afterwards
| Type: | group | |
CCTK_POSTSTEP
sphericalsurface_set
set surface radii
| Before: | sphericalsurface_hasbeenset | |
| Language: | c | |
| Options: | global | |
| Type: | function | |
CCTK_POSTSTEP
sphericalsurface_hasbeenset
set the spherical surfaces before this group, and use it afterwards
| Type: | group | |
SphericalSurface_HasBeenSet
sphericalsurface_checkstate
test the state of the spherical surfaces
| Language: | c | |
| Options: | global | |
| Reads: | sphericalsurface::sf_valid | |
| sphericalsurface::sf_active | ||
| Type: | function | |
CCTK_PARAMCHECK
sphericalsurface_paramcheck
check that all surface names are unique
| Language: | c | |
| Options: | global | |
| Type: | function | |