Abstract
Thorn AHFinderDirect locates apparent horizons (or more generally, closed 2surfaces with ${S}^{2}$ topology having any desired constant expansion) in a numerically computed slice using a direct method, posing the apparent horizon equation as an elliptic PDE on angularcoordinate space. This is very fast and accurate, but requires a “reasonable” initial guess. This thorn guide describes how to use the thorn.
A “marginally trapped surface” is a closed 2surface in a slice whose congruence of futurepointing outgoing null geodesics has zero expansion. There may be several such surfaces, some nested inside others; an “apparent horizon” is an outermost marginally trapped surface. In terms of the usual $3+1$ variables, an apparent horizon satisfies the equation
$$\Theta \equiv {\nabla}_{i}{n}^{i}+{K}_{ij}{n}^{i}{n}^{j}K=0$$  (1) 
where ${n}^{i}$ is the outwardpointing unit normal to the apparent horizon, and ${\nabla}_{i}$ is the covariant derivative operator associated with the 3metric ${g}_{ij}$ in the slice. (See [?] for a derivation of equation $\left(1\right)$.) (Optionally, you can replace the right hand side of $\left(1\right)$ by any specified nonzero constant, i.e. you can find a surface of constant (in general nonzero) expansion.; this is dicsussed in section 4.8.)
Thorn AHFinderDirect finds an apparent horizon by numerically solving equation $\left(1\right)$. It requires as input the usual Cactus 3metric ${g}_{ij}$ and extrinsic curvature ${K}_{ij}$, (and optionally the conformal factor $\psi $ if the StaticConformal metric semantics are used), and produces as output the Cactus $\left(x,y,z\right)$ coordinates of a large number of points on the apparent horizon, together with some auxiliary information like the apparent horizon area and centroid position, and the irreducable mass associated with the area.
Besides this thorn guide, the other main sources of information on AHFinderDirect are the comments in the param.ccl file, the paper [?], and to a lesser extent the paper [?]. As a courtesy, I ask that both these papers be cited in any published research which uses this thorn, or which uses code from this thorn.
There are some restrictions on the spacetime, or more precisely on each slice where you want to find apparent horizons, which are necessary in order for AHFinderDirect to work:
a region in $n$dimensional Euclidean space containing the origin and whose surface, as seen from the origin, exhibits only one point in any direction.
In other words, using polar spherical coordinates relative to the local coordinate origin, the apparent horizon’s shape must be parameterizable as $r=h\left(angle\right)$ for some singlevalued function $h:{S}^{2}\to {\Re}^{+}$. (AHFinderDirect uses precisely this parameterization.)
There are also some restrictions on your Cactus configuration and run; here’s what works and what doesn’t:
AHFinderDirect can pass information to the rest of Cactus in several ways; these are described in detail in section 4.7.
You should be able to obtain the source code for this thorn via the usual procedures for anonymous git checkout; at present it lives in the EinsteinAnalysis arrangement.
This thorn is written primarily in C++, calling C and Fortran 77 numerical libraries.^{2} In theory the code should be quite portable to modern C++ compilers, but in practice I’ve had a number of portability problems with various compilers. See the “Code Notes” and “Compiler Notes” sections in the toplevel README file for details and lists of compilers currently known to be ok or not.
By default AHFinderDirect doesn’t use any external libraries. However, if HAVE_DENSE_JACOBIAN__LAPACK is defined in src/include/config.h, then AHFinderDirect uses the LAPACK library for solving linear equations. In this case you need to configure Cactus with LAPACK=yes. See the toplevel README and README.library files for details on this.
This thorn has lots of parameters, but most of them have reasonable default values which you probably won’t need to change. Here I describe the parameters which you are likely to want to at least look at, and possibly set explicitly.
Note that all of the “[$n$]” parameters are Cactus array parameters, which you need to specify separately in your parameter file for each apparent horizon. IMPORTANT: Apparent horizons are numbered starting at 1, not 0! The example in section 8 should make this clear.
Note that N_horizons sets the number of apparent horizons you want to find in the Cactus 3D numerical grid, not in the whole spacetime. For example, if you are simulating (say) Misner data with Grid::domain = "bitant", with the two throats at (say) roughly $z=\pm 1$, then you should set N_horizons = 1 to find those two apparent horizons, since you’re only finding one apparent horizon within the numerical grid. If you also want to search for a common apparent horizon surrounding both black holes, then you should set N_horizons = 2, since you’re finding at most 2 apparent horizons within the numerical grid.
For each apparent horizon you want to find, you need to specify the Cactus $\left(x,y,z\right)$ coordinates of a local coordinate system origin. As described in section 2, each apparent horizon must be a Strahlkörper with respect to its local coordinate system origin.
You specify the local coordinate system origin for each horizon with the (Cactus array) parameters
origin_x[$n$] 
origin_y[$n$] 
origin_z[$n$] 
At present the local coordinate origin is fixed once you set it; there’s no provision for it to move to track a moving black hole. I hope to add such a provision soon.^{5}
AHFinderDirect requires an initial guess for the apparent horizon’s coordinate position and shape (that is, for the $h\left(angle\right)$ function defined in section 2), for each apparent horizon you want to find. Unlike some other apparent horizon finders (eg. the curvature flow method in AHFinder), for AHFinderDirect there’s no restriction on whether the initial guess is inside, outside, or crossing the actual apparent horizon: the only important thing is that it should be “close”. Just how close the initial guess needs to be for AHFinderDirect to find the (a) apparent horizon depends on the slice and the coordinates, but as a general rule of thumb any initial guess that’s within 1/3 to 1/2 of the mean horizon radius will probably work.
The “initial guess” specification is used the first time we try to find any given apparent horizon, and also any succeeding time when the most recent attempt to find this apparent horizon failed. If we succeed in finding a given apparent horizon, than that apparent horizon position is automatically reused as the initial guess the next time we try to find the same apparent horizon; in this case the explicit “initial guess” specification is ignored.^{6}
There are a number of parameters for specifying the initial guess:
initial_guess__Kerr_Kerr__x_posn[$n$] 
initial_guess__Kerr_Kerr__y_posn[$n$] 
initial_guess__Kerr_Kerr__z_posn[$n$] 
initial_guess__Kerr_Kerr__mass[$n$] 
initial_guess__Kerr_Kerr__spin[$n$] 
initial_guess__Kerr_KerrSchild__x_posn[$n$] 
initial_guess__Kerr_KerrSchild__y_posn[$n$] 
initial_guess__Kerr_KerrSchild__z_posn[$n$] 
initial_guess__Kerr_KerrSchild__mass[$n$] 
initial_guess__Kerr_KerrSchild__spin[$n$] 
initial_guess__coord_sphere__x_center[$n$] 
initial_guess__coord_sphere__y_center[$n$] 
initial_guess__coord_sphere__z_center[$n$] 
initial_guess__coord_ellipsoid__x_center[$n$] 
initial_guess__coord_ellipsoid__y_center[$n$] 
initial_guess__coord_ellipsoid__z_center[$n$] 
initial_guess__coord_ellipsoid__x_radius[$n$] 
initial_guess__coord_ellipsoid__y_radius[$n$] 
initial_guess__coord_ellipsoid__z_radius[$n$] 
The main output of this thorn is the computed horizon shape function $h\left(angle\right)$, and correspondingly the $\left(x,y,z\right)$ coordinate positions of the apparenthorizonsurface (angular) grid points. There are several parameters controlling if, how often, and how these should be written to data files:
See section 6 for a discussion of visualization for these and other AHFinderDirect output files.
As well as the apparent horizon shape files, this thorn can also write files giving time series of various diagnostics. These are controlled by the following parameters:
This thorn can optionally set a mask grid function (or functions) at each point of the Cactus grid, to indicate where that point is with respect to the apparent horizon(s). This is usually used for excision.
set_mask_for_all_horizons 
set_mask_for_individual_horizon[$n$] 
If any of these parameters is set to true, you almost certainly also need to set the Boolean parameter SpaceMask::use_mask to true to to turn on storage for the mask grid function(s)!
If it’s setting a mask(s), AHFinderDirect partitions the Cactus grid into 3 regions: an “inside”, a “buffer”, and an “outside”. Typically the inner region is excised, but AHFinderDirect doesn’t itself do this: It just sets the mask(s); you need to use some other thorn(s) to do the actual excision.
The 3 regions are defined as follows: For a grid point a distance $r\left[i\right]$ from horizon $i$’s local coordinate origin, with horizon $i$’s radius in this same direction (again, measured from its local coordinate origin) being ${r}_{horizon}\left[i\right]$,^{10} the regions are defined by
$$$$  
 

where
$$\begin{array}{ccc}{r}_{r}\hfill & \hfill =\hfill & \hfill \end{array}$$  (4) 
and where ${\Delta x}_{e}$ is the basegrid Cactus grid spacing (more precisely, the geometric mean of the base grid’s $x$, $y$, and $z$ Cactus grid spacings)^{11} .
mask_radius_multiplier 
mask_radius_offset 
mask_buffer_thickness 
Note that the sign convention here is that mask_radius_multiplier is multiplied by the horizon radius, then mask_radius_offset (scaled by the Cactus grid spacing) is added. Thus for use with excision (where the inner region – which will be excised – must be somewhat inside the horizon), mask_radius_multiplier should be a positive real number slightly less than 1.0, and/or mask_radius_offset a negative real number.
The default values for these parameters are
$$ 
if  (mask_is_noshrink && ($$ 
then  { 
# this point was previously inside $\Rightarrow $ noop here 
} 
else  $$ 
if  (mask_is_noshrink && (($$ 
then  { 
# this point was previously inside or buffer $\Rightarrow $ noop here 
} 
else  $$ 
This parameter can be used to avoid this problem: For each apparent horizon that it finds, AHFinderDirect only sets the mask on a given grid if
$${r}_{inner,\mathrm{min}}\ge $$  (5) 
where ${r}_{inner,\mathrm{min}}$ is the minimum over all angles of ${r}_{r}$ as defined by equation $\left(4\right)$, and ${\Delta x}_{current,\mathrm{max}}$ is the maximum of the Cactus $x$, $y$, and $z$ grid spacings on the current Cactus grid.^{12} If this condition isn’t satisfied, then AHFinderDirect skips setting the mask for this apparent horizon, just as if this apparent horizon wasn’t found. (Note that all other processing for an apparent horizon being found is still done, including writing output files, using the apparent horizon shape as the initial guess for the next time step’s apparenthorizon finding, etc.; it’s only the mask processing for this horizon (at this time step) that’s skipped.)
AHFinderDirect supports two types of mask grid functions; the following two Boolean parameters choose which of them you want to set; you can set either or even both of these:
For an oldstyle mask, the following parameters specify the mask grid function and how it should be set:
old_style_mask_inside_value 
old_style_mask_buffer_value 
old_style_mask_outside_value 
For an newstyle mask, the following parameters specify the mask grid function and how it should be set:
new_style_mask_gridfn_name 
new_style_mask_bitfield_name 
new_style_mask_inside_value 
new_style_mask_buffer_value 
new_style_mask_outside_value 
Note that AHFinderDirect doesn’t itself register any bitfields or states with SpaceMask – you must arrange for some other thorn(s) to do this before AHFinderDirect tries to find the horizon(s).
If AHFinderDirect sets a mask or masks, this happens in the same schedule bin(s) as the horizon finding. More precisely, AHFinderDirect creates two schedule groups for this purpose:
Thorn PreviousMask uses these schedule groups to keep a “previous” as well as a “current” mask. See that thorn’s thorn guide for further details.
Besides the data files it writes, AHFinderDirect currently has three ways to communicate with other Cactus thorns:
AHFinderDirect’s mask features are described in section 4.6; the other communication mechanisms are described in the following subsections.
This thorn can optionally announce the centroid of a specified apparent horizon to another thorn (typically DriftCorrect) each time that apparent horizon is found. This is controlled by the following parameter:
AHFinderDirect provides the following aliased functions to allow other thorns to find out about the horizons. Each function returns a status code which is $\ge 0$ for ok, or negative for an error.
SphericalSurface (in the AEIThorns arrangement) defines a set of generic grid arrays which describe “spherical surfaces”. AHFinderDirect can optionally store information about the horizons it finds in the SphericalSurface variables. This is controlled by the following parameters:
Note that SphericalSurface numbers surfaces starting from 0, whereas AHFinderDirect numbers horizons starting from 1!
At present, if multiple AHFinderDirect horizons specify the same SphericalSurface surface, the highestnumbered horizon will “win”, i.e. it will overwrite the data from any lowernumbered horizons.
run_at_CCTK_ANALYSIS 
run_at_CCTK_POSTSTEP 
run_at_CCTK_POSTINITIAL 
run_at_CCTK_POST_RECOVER_VARIABLES 
In general we need to run at CCTK_POST_RECOVER_VARIABLES, since
Therefore the run_at_CCTK_POST_RECOVER_VARIABLES parameter should probably be left at its default setting of true.
geometry_interpolator_name 
geometry_interpolator_pars 
If you want to get very high accuracy from AHFinderDirect, then you should use a cubic Hermite geometry interpolator, by setting
Assuming perfectly accurate geometry variables in the 3D Cactus grid, this will make
AHFinderDirect (very) roughly an order of magnitude more accurate. However, the larger
molecule size will make it about a factor of 2–3 slower, and will also require that you set
$$
For any horizon which is close to spherical about its local coordinate origin, you can lower this parameter to make AHFinderDirect run faster (typical runtimes scale roughly as the cube of this parameter); 6 is about the minimum reasonable value.
For any horizon which is highly nonspherical about its local coordinate origin, you can raise this parameter to get better resolution; 30 should be enough for even a highly nonspherical horizon.
This parameter defaults to $1{0}^{10}$ (effectively $+\infty $) for each apparent horizon. You can set it to a smaller value to make AHFinderDirect a bit more efficient, or (probably more important in practice) to stop AHFinderDirect from iterating off the edge of the grid if this causes problems with interpolation or boundary conditions.
To help in choosing the value(s) of the surface_expansion[$n$] parameter, figure 1 (from [?]), shows the expansion of $r=constant$ surfaces in an EddingtonFinkelsteon slice of the unitmass Schwarzschild spacetime.
There are two primary ways of monitoring what AHFinderDirect is doing during a Cactus run: the BH_diagnostics files and the CCTK_INFO messages written to the Cactus standard output:
The BH_diagnostics files are described in detail in section 4.5. These files are written and “flushed” at each time step, so they’re always uptodate.
During the apparenthorizon–finding process, AHFinderDirect writes various CCTK_INFO messages describing the convergence of the iterative solution of the apparent horizon equation 1 on each processor. In particular, if verbose_level is set to "algorithm highlights" or a more verbose setting (cf. section 4.1), then AHFinderDirect writes CCTK_INFO messages like these:
Here r_grid is a rough estimate of the mean radius of the trial surface at each iteration, and Theta is the infinitynorm of $\Theta $, the left hand side of the apparent horizon equation 1 over the surface. Once the apparent horizon has been found (Theta is sufficiently small), then AHFinderDirect prints its mean radius,^{15} centroid position, area, and irreducible mass.
There are several ways to visualize AHFinderDirect’s output:
The simplest is to plot various quantities from the BH_diagnostics files (described in detail in section 4.5). For example, using gnuplot (http://www.gnuplot.info), you can plot a graph of the surface area of horizon #4 as a function of coordinate time, with the command
ygraph (http://www.aei.mpg.de/~pollney/ygraph/) may also be able to directly plot the BH_diagnostics files.
Given a horizonshape data file h.t105.h4.gp, the gnuplot command
will plot the $h\left(angle\right)$ function, with the $x$ and $y$ axes of the plot being the two “unwrapped” angular coordinates on ${S}^{2}$, in degrees, and the $z$ axis being $h\left(angle\right)$. However, in practice this usually isn’t very informative. Instead, you probably want the gnuplot command
which will plot the 3D shape of the apparent horizon surface.
The src/misc directory of the AHFinderDirect source code contains several perl scripts which are useful in visualizing AHFinderDirect output. In particular, the script select.plane selects a particular 2D plane. If you put this in your Unix path, it can be used with a gnuplot command like
to show the shape of an apparent horizon in the xy plane.^{16}
Another Visualization option is OpenDX (http://www.opendx.org/). Thomas Radke’s has written some OpenDX macros ImportAHFinderDirectGnuplot.net and ImportAHFinderDirectGnuplotPatch.net to import AHFinderDirect horizonshape data files. These macros use a set of “control files” named *.dx, one per horizon, which AHFinderDirect (by default) writes into the same directory as the main horizon–shape output files. You can get these macros by anonymous CVS with the command
Another Visualization option is to produce files in the standard Xdmf [?] file format which can be visualized for example using VisIt [?]. Frank Löffler has written a python script AH2xdmf.py, which is included in this thorn’s code repository, which generates such files from AHFinderDirect’s output from horizon shape files h.t%d.ah%d.gp\. Please see its help text for details.
The apparent horizon positions are typically computed very accurately; tests on Kerr spacetimes give typical errors of $1{0}^{4}m$ to $1{0}^{5}m$.
The various diagnostics printed to standard output and written to the black hole diagnostics file(s), are typically computed to accuracies on the order of a part per million or so.
Note, however, that the irreducible mass ${m}_{e}$ may differ considerably from the black hole’s local mass or its contribution to the slice’s ADM mass. For example, for Kerr spacetime in KerrSchild coordinates, ${m}_{e}\u2215{m}_{M}=0.949$, $0.894$, and $0.723$ for spin parameters $a\equiv J\u2215{m}^{2}=0.6$, $0.8$, and $0.999$, respectively. It would be better to (also) use the “isolated horizons” formalism of [?]; at some point this thorn may be enhanced to do this.
There are a few example parameter files in the par/ directory, including Kerr initial data, Misner initial data, and Misner timeevolution tests. The Kerrtiny.par parameter file is close to a minimal AHFinderDirect example:
Surfaces of Constant Expansion (CE surfaces) are introduced in [?] as a generalisation of apparent horizons (AH). On an AH surface, the expansion is zero everywhere. On a CE surfaces, the expansion is still everywhere the same, but it need not be zero. CE surfaces are also a generalisation of Constant Mean Curvature surfaces (CMC surfaces); both are identical when the extrinsic curvature vanishes. As described in [?], it is likely that CE surfaces foliate the spacelike hypersurface outside of some interior region. This interior region is inside the common apparent horizon, if it exists.
CE surfaces can give some insight into the spacetime, because they can be used to analyse the part of the spacelike hypersurface “between the horizons and infinity”. Most notably, they can be used to look at the region where a common horizon is about to (or believed to) form. Similarly, one can use them for collapsing stars where an apparent horizon has not yet formed.
Apparent horizon pretracking is introduced in [?]. This is an application of CE surfaces. Even when there is no common horizon, there are still common CE surfaces surrounding multiple black holes. Pretracking consists of tracking in time the smallest common CE surface that can be found. It is reasonable to believe that this surface will evolve into the common horizon at the time where this common horizon begins to exist. The expansion of this smallest CE surface is also an indication of how close the spacelike hypersurface is to having a common apparent horizon.
AHFinderDirect uses the apparent horizon (henceforth “horizon”) finding algorithm of [?], modified slightly to work with ${g}_{ij}$ and ${K}_{ij}$ on a Cartesian ($xyz$) grid. The algorithm is described in detail in [?].
As described above, I parameterizes the horizon shape by $r=h\left(angle\right)$ for some singlevalue function $h:{S}^{2}\to {\Re}^{+}$. The apparent horizon equation $\left(1\right)$ then becomes a 2D elliptic PDE on ${S}^{2}$ for the function $h$. I finite difference this in angle to obtain a system of simultaneous nonlinear algebraic equations for $h$ at the angular grid points, and solve this system of equations by a global Newton’s method (or a variant with improved convergence).
Computationally, this algorithm has 3 main parts:
By default only the sparsematrix code is configured, so LAPACK isn’t used and there’s no need to link with the LAPACK library.
Perhaps the most unusual feature of AHFinderDirect is the “multipatch” system used to cover ${S}^{2}$ without coordinate singularities. In general there are 6 patches, one each covering a neighborhood of the $\pm z$, $\pm x$, and $\pm y$ axes, but this may be reduced in the presence of suitable symmetries. For example, figure 2 on page 40 shows a system of 3 patches covering the $+xyz$ octant of ${S}^{2}$. This would be suitable for finding an apparent horizon with mirror symmetry about the (local) $z=0$ plane, and either 90 degree periodic rotation symmetry about the (local) $z$ axis, or mirror symmetry about each of the (local) $x$ and $y$ axes.
To allow easy angular finite differencing within the patch system, each patch is extended beyond its nominal extent by a “ghost zone”^{17} (2 grid points wide in figure 2). Angular grid function values in the ghost zone can be obtained by interpatch interpolation^{18} or by applying symmetry operations. Once this is done, then angular finite differencing within the nominal extent of each patch can proceed normally, ignoring the patch boundaries. AHFinderDirect can be configured at compile time to use either 2nd order or 4th order angular finite differencing (3 point or 5 point angular molecules); the default is 4th order (5 point). This is configured at compile time in src/include/config.h.
By default AHFinderDirect will automagically choose a patch system type for each apparent horizon searched for, based on the local coordinate origin and the symmetries implicit in the Cactus grid type. This generally works well, but if desired you can instead manually specify the patch system type, the angular resolution, the width of the ghost zones, etc. See the param.ccl file for details.
AHFinderDirect’s src/sparsematrix/ directory contains various sparsematrix libraries, which have their own copyrights and licensing terms:
The src/sparsematrix/umfpack/ directory contains a subset of the files in UMFPACK version 4.0 (11.Apr.2002). This code is copyright (©) 2002 by Timothy A. Davis, and is subect to the UMFPACK License:
If you’re interested in AHFinderDirect, you might also be interested in some other related thorns:
I thank Peter Diener, Ian Hawke, and Erik Schnetter for many valuable conversations. I think Thomas Radke for his work on the new interpolators. I thank the whole Cactus crew for a great infrastructure!
Erik Schnetter originally implemented a number of improvements to this thorn, notably the SphericalSurface interface and the new features in the Erik branch.
I thank the Alexander von Humboldt foundation and the AEI visitors’ and postdoctoral fellowships programs for financial support.
ascii_gnuplot_file_name_extension  Scope: private  STRING 
Description: extension for ASCII (gnuplot) data files
 
Range  Default: gp  
.+  any nonempty string
 
bh_diagnostics_base_file_name  Scope: private  STRING 
Description: base file name for BH diagnostics output file(s)
 
Range  Default: BH_diagnostics  
.+  any nonempty string
 
bh_diagnostics_directory  Scope: private  STRING 
Description: directory for BH diagnostics output file(s)
 
Range  Default: (none)  
.+  any nonempty string
 
$̂  an empty string to default to IO::out_dir
 
bh_diagnostics_file_name_extension  Scope: private  STRING 
Description: extension for BH diagnostics data files
 
Range  Default: gp  
.+  any nonempty string
 
check_that_geometry_is_finite  Scope: private  BOOLEAN 
Description: should we check the interpolated geometry variables are finite?
 
Default: true  
check_that_h_is_finite  Scope: private  BOOLEAN 
Description: should we check that horizon shape function h is finite?
 
Default: true  
coordinate_system_name  Scope: private  STRING 
Description: name under which the coordinate system is registered in Cactus
 
Range  Default: cart3d  
.+  any nonempty string
 
debugging_output_at_each_newton_iteration  Scope: private  BOOLEAN 
Description: should we output {h, Theta, delta_h}at each Newton iteration?
 
Default: false  
delta_h_base_file_name  Scope: private  STRING 
Description: base file name for horizonshapeupdate Delta_h output file(s)
 
Range  Default: Delta_h  
.+  any nonempty string
 
depends_on  Scope: private  INT 
Description: the other horizon that this horizon depends on
 
Range  Default: (none)  
the horizon is independent
 
1:100  horizon index
 
desired_value  Scope: private  REAL 
Description: search for a surface with this (constant) value
 
Range  Default: 0.0  
*:*  any real number
 
desired_value_factor  Scope: private  REAL 
Description: factor between this horizon’s and the other horizon’s desired value, applied before
the offset
 
Range  Default: 1.0  
*:*  
desired_value_offset  Scope: private  REAL 
Description: difference between this horizon’s and the other horizon’s desired value, applied after
the factor
 
Range  Default: 0.0  
*:*  
disable_horizon  Scope: private  BOOLEAN 
Description: should this horizon be disabled?
 
Default: false  
dont_find_after_individual  Scope: private  INT 
Description: when should we stop finding individual apparent horizons?
 
Range  Default: 1  
0:*  after this iteration (exclusively)
 
1  do not use this parameter
 
dont_find_after_individual_time  Scope: private  REAL 
Description: when should we stop finding individual apparent horizons?
 
Range  Default: 0.0  
*:*  ”after this time (exclusively); ignore this value
if it is less than or equal to find_after_individua
l_time”
 
find_after_individual  Scope: private  INT 
Description: when should we start to find individual apparent horizons?
 
Range  Default: (none)  
0:*  after this iteration (inclusively)
 
find_after_individual_time  Scope: private  REAL 
Description: when should we start to find individual apparent horizons?
 
Range  Default: 0.0  
*:*  after this time (inclusively)
 
find_every  Scope: private  INT 
Description: how often should we try to find apparent horizons?
 
Range  Default: 1  
don’t find AHs at all (this thorn is a noop)
 
1:*  any integer >= 1
 
find_every_individual  Scope: private  INT 
Description: how often should we try to find individual apparent horizons? (overrides find_every)
 
Range  Default: 1  
1  use the value of find_every
 
don’t find this AH at all
 
1:*  any integer >= 1
 
geometry__schwarzschild_ef__delta_xyz  Scope: private  REAL 
Description: finite diff pseuogrid spacing for computing partial_k g_ij
 
Range  Default: 1.0e6  
(0.0:*  any real number > 0
 
geometry__schwarzschild_ef__epsilon  Scope: private  REAL 
Description: threshold for sin2̂ theta = (x2̂+y2̂)/r2̂ below which we use z axis limits
 
Range  Default: 1.0e9  
(0.0:*  this should be somewhat above the
floatingpoint roundoff level
 
geometry__schwarzschild_ef__mass  Scope: private  REAL 
Description: mass of Schwarzschild BH
 
Range  Default: 1.0  
(0.0:*  BH mass = any real number > 0
 
geometry__schwarzschild_ef__x_posn  Scope: private  REAL 
Description: x coordinate of Schwarzschild BH
 
Range  Default: 0.0  
*:*  any real number
 
geometry__schwarzschild_ef__y_posn  Scope: private  REAL 
Description: y coordinate of Schwarzschild BH
 
Range  Default: 0.0  
*:*  any real number
 
geometry__schwarzschild_ef__z_posn  Scope: private  REAL 
Description: z coordinate of Schwarzschild BH
 
Range  Default: 0.0  
*:*  any real number
 
geometry_interpolator_name  Scope: private  STRING 
Description: name under which the geometry interpolation operator is registered in Cactus
 
Range  Default: Hermite polynomial interpolation  
.+  any nonempty string
 
geometry_interpolator_pars  Scope: private  STRING 
Description: parameters for the geometry interpolator
 
Range  Default: order=2 boundary_off_centering_tolerance={1.0e10 1.0e10 1.0e10 1.0e10 1.0e10 1.0e10} boundary_extrapolation_tolerance={0.0 0.0 0.0 0.0 0.0 0.0}  
.*  ”any string
acceptable to Util_TableSetFromStr ing() and
to the interpolator”
 
ghost_zone_width  Scope: private  INT 
Description: number of ghost zones on each side of a patch
 
Range  Default: 2  
0:*  any integer >= 0
 
h_base_file_name  Scope: private  STRING 
Description: base file name for horizon shape h input/output file(s)
 
Range  Default: h  
.+  any nonempty string
 
h_directory  Scope: private  STRING 
Description: directory for horizon shape and other similar output (or input) file(s)
 
Range  Default: (none)  
.+  any nonempty string
 
$̂  an empty string to default to IO::out_dir
 
h_min_digits  Scope: private  INT 
Description: minimum number of digits for the iteration number in the file name
 
Range  Default: (none)  
0:*  
hardwire_schwarzschild_ef_geometry  Scope: private  BOOLEAN 
Description: should we hardwire the geometry to Schwarzschild/EF instead of interpolating from
the Cactus grid?
 
Default: false  
hdf5_file_name_extension  Scope: private  STRING 
Description: extension for HDF5 data files
 
Range  Default: h5  
.+  any nonempty string
 
ilucg__error_tolerance  Scope: private  REAL 
Description: error tolerance for conjugate gradient iteration
 
Range  Default: 1.0e10  
(*:0.0)  negative ==> scale the absolute value by the
floating point roundoff threshold, e.g. 256.0
means to allow the last 8 bits of the solution to
be in error
 
(0.0:*)  positive ==> error tolerance
 
ilucg__limit_cg_iterations  Scope: private  BOOLEAN 
Description: should we limit the maximum number of conjugate gradient iterations allowed?
 
Range  Default: true  
false  no limit on CG iterations
 
true  limit to Neqns CG iterations
 
initial_guess__coord_ellipsoid__x_center  Scope: private  REAL 
Description: x coordinate of ellipsoid center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__coord_ellipsoid__x_radius  Scope: private  REAL 
Description: x radius of ellipsoid
 
Range  Default: 2.0  
(0.0:*  any real number > 0.0
 
initial_guess__coord_ellipsoid__y_center  Scope: private  REAL 
Description: y coordinate of ellipsoid center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__coord_ellipsoid__y_radius  Scope: private  REAL 
Description: y radius of ellipsoid
 
Range  Default: 2.0  
(0.0:*  any real number > 0.0
 
initial_guess__coord_ellipsoid__z_center  Scope: private  REAL 
Description: z coordinate of ellipsoid center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__coord_ellipsoid__z_radius  Scope: private  REAL 
Description: z radius of ellipsoid
 
Range  Default: 2.0  
(0.0:*  any real number > 0.0
 
initial_guess__coord_sphere__radius  Scope: private  REAL 
Description: radius of sphere
 
Range  Default: 2.0  
(0.0:*  any real number > 0.0
 
initial_guess__coord_sphere__x_center  Scope: private  REAL 
Description: x coordinate of sphere center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__coord_sphere__y_center  Scope: private  REAL 
Description: y coordinate of sphere center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__coord_sphere__z_center  Scope: private  REAL 
Description: z coordinate of sphere center
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerr__mass  Scope: private  REAL 
Description: mass of Kerr BH
 
Range  Default: 1.0  
(0.0:*  BH mass = any real number > 0
 
initial_guess__kerr_kerr__spin  Scope: private  REAL 
Description: dimensionless spin a=J/m2̂ of Kerr BH
 
Range  Default: 0.6  
(1.0:1.0)  dimensionless BH spin = J/m2̂ = any real
number with absolute value < 1
 
initial_guess__kerr_kerr__x_posn  Scope: private  REAL 
Description: x coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerr__y_posn  Scope: private  REAL 
Description: y coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerr__z_posn  Scope: private  REAL 
Description: z coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerrschild__mass  Scope: private  REAL 
Description: mass of Kerr BH
 
Range  Default: 1.0  
(0.0:*  BH mass = any real number > 0
 
initial_guess__kerr_kerrschild__spin  Scope: private  REAL 
Description: dimensionless spin a=J/m2̂ of Kerr BH
 
Range  Default: 0.6  
(1.0:1.0)  dimensionless BH spin = J/m2̂ = any real
number with absolute value < 1
 
initial_guess__kerr_kerrschild__x_posn  Scope: private  REAL 
Description: x coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerrschild__y_posn  Scope: private  REAL 
Description: y coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__kerr_kerrschild__z_posn  Scope: private  REAL 
Description: z coordinate of Kerr BH
 
Range  Default: 0.0  
*:*  any real number
 
initial_guess__read_from_named_file__file_name  Scope: private  STRING 
Description: file name to read initial guess from
 
Range  Default: h.gp  
.+  file name to read initial guess from
 
initial_guess_method  Scope: private  KEYWORD 
Description: method used to set up initial guess for apparent horizon shape
 
Range  Default: coordinate sphere  
read from named file  read from explicitlynamed input file
 
read from h file  read from input file named the same as the
(later) h output file
 
Kerr/Kerr  set
to the (analytical) horizon of Kerr spacetime in
Kerr coordinates (n.b. Schwarzschild/EF is the
special case spin=0 of this)
 
Kerr/KerrSchild  set to the (analytical) horizon of Kerr
spacetime in KerrSchild coordinates
 
coordinate sphere  set to a coordinate sphere
 
coordinate ellipsoid  set to a coordinate ellipsoid
 
integral_method  Scope: private  KEYWORD 
Description: how do we compute integrals over the horizon?
 
Range  Default: automatic choice  
trapezoid  alternate name for trapezoid rule
 
trapezoid rule  trapezoid rule (2nd order for smooth functions)
 
Simpson  alternate name for Simpson’s rule
 
Simpson’s rule  Simpson’s rule (4th order for smooth fns,
requires N to be even)
 
Simpson (variant)  alternate name for Simpson’s rule variant
 
see [1] below  Simpson’s rule variant (4th order for smooth
fns, requires N >= 7)
 
automatic choice  choose Simpson’s rule or variant if applicable,
otherwise trapezoid rule
 
[1]
interpatch_interpolator_name  Scope: private  STRING 
Description: name under which the interpatch interpolation operator is registered in Cactus
 
Range  Default: Lagrange polynomial interpolation  
.+  any string (in practice it should be nonempty)
 
interpatch_interpolator_pars  Scope: private  STRING 
Description: parameters for the interpatch interpolator
 
Range  Default: order=5  
.*  ”any string
acceptable to Util_TableSetFromStr ing() and
to the interpolator”
 
jacobian_base_file_name  Scope: private  STRING 
Description: base file name for Jacobian output file(s)
 
Range  Default: Jacobian.dat  
.+  any valid file name
 
jacobian_compute_method  Scope: private  KEYWORD 
Description: how do we compute the Jacobian matrix?
 
Range  Default: symbolic differentiation with finite diff d/dr  
see [1] below  n.b. this is *very* slow
 
see [1] below  fast, tricky programming, uses only gij, dx gij,
Kij
 
see [1] below  fast, tricky programming, uses gij, dx gij, dxx
gij, Kij, dx Kij
 
[1]
[1]
[1]
jacobian_perturbation_amplitude  Scope: private  REAL 
Description: perturbation amplitude for 1sided finite differencing for Jacobians
 
Range  Default: 1.0e6  
(0.0:*  any real number > 0
 
jacobian_store_solve_method  Scope: private  KEYWORD 
Description: how do we store/linearsolve the Jacobian matrix?
 
Range  Default: roworiented sparse matrix/UMFPACK  
dense matrix/LAPACK  store as (Fortran) dense matrix, solve with
LAPACK routines
 
see [1] below  store as sparse matrix (roworiented storage
format), solve with ILUCG (incomplete LU
decomposition  conjugate gradient) method
 
see [1] below  store as sparse matrix (roworiented storage
format), solve with UMFPACK (sparse LU
decomposition) method
 
[1]
[1]
mask_buffer_thickness  Scope: private  REAL 
Description: thickness (in Cactus base grid spacings) of the ’buffer’ mask region
 
Range  Default: 5.0  
*:*  any real number; typically this will be positive
 
mask_is_noshrink  Scope: private  BOOLEAN 
Description: should we prevent the inside & buffer regions from ever shrinking?
 
Default: true  
mask_radius_multiplier  Scope: private  REAL 
Description: radius multiplier to define the ’inside’ mask region
 
Range  Default: 0.8  
(0:*)  any positive real number; typically this will be
slightly less than 1.0
 
mask_radius_offset  Scope: private  REAL 
Description: radius offset (in Cactus base grid spacings) to define the ’inside’ mask region
 
Range  Default: 5.0  
*:*  any real number; typically this will be negative
 
max_allowable_delta_h_over_h  Scope: private  REAL 
Description: don’t let horizon move > this fraction of mean radius in a Newton iteration
 
Range  Default: 0.1  
(0.0:*  any positive real number
 
max_allowable_horizon_radius  Scope: private  REAL 
Description: max meancoordinateradius allowed for any trial surface before we give up and say
we can’t find this horizon
 
Range  Default: 1.0e10  
(0.0:*  any positive real number
 
max_allowable_theta  Scope: private  REAL 
Description: max ——Theta——_infinity allowed for any trial surface before we give up and say
we can’t find this horizon
 
Range  Default: 1.0e10  
(0.0:*  any positive real number
 
max_allowable_theta_growth_iterations  Scope: private  INT 
Description: max number of consecutive iterations during which ——Theta——_infinity is
allowed to grow before we give up and say we can’t find this horizon
 
Range  Default: (none)  
infinitly many
 
1:*  that many
 
max_allowable_theta_nonshrink_iterations  Scope: private  INT 
Description: max number of consecutive iterations during which ——Theta——_infinity is
allowed to oscillate without shrinking before we give up and say we can’t find this horizon
 
Range  Default: (none)  
infinitly many
 
1:*  that many
 
max_n_zones_per_right_angle  Scope: private  INT 
Description: the maximum of all N_zones_per_right_angle
 
Range  Default: 18  
1:*  ”must be at least the maximum of all
N_zones_per_right_an gle”
 
max_newton_iterations__initial  Scope: private  INT 
Description: maximum number of Newton iterations before giving up when initially finding a
given horizon
 
Range  Default: 20  
(0:*  any positive integer
 
max_newton_iterations__subsequent  Scope: private  INT 
Description: maximum number of Newton iterations before giving up when refinding a given
horizon after finding it before
 
Range  Default: 10  
(0:*  any positive integer
 
mean_curvature_base_file_name  Scope: private  STRING 
Description: base file name for mean_curvature(h) output file(s)
 
Range  Default: mean_curvature  
.+  any nonempty string
 
method  Scope: private  KEYWORD 
Description: what should this thorn do for each apparent horizon?
 
Range  Default: find horizons  
evaluate expansions  evaluate the LHS function Theta(h)
 
see [1] below  ”compute/print horizon 1’s J[Theta(h)]
Jacobian matrix (possibly in multiple ways,
depending on the test_all_Jacobian_me thods
parameter)”
 
find horizons  find the apparent horizon
 
[1]
min_horizon_radius_points_for_mask  Scope: private  REAL 
Description: only set mask if min r_inner >= this number of local grid spacings
 
Range  Default: 1.0e10  
*:*  any real number
 
move_origins  Scope: private  BOOLEAN 
Description: move the origins with the horizons
 
Default: no  
n_horizons  Scope: private  INT 
Description: number of apparent horizons to search for
 
Range  Default: 1  
turn this thorn into a fancy noop :)
 
1:100  search for this many apparent horizons
 
n_zones_per_right_angle  Scope: private  INT 
Description: sets angular resolution of patch systems
 
Range  Default: 18  
1:*  any integer >= 1; must be even for patch
systems other than fullsphere
 
new_style_mask_bitfield_name  Scope: private  STRING 
Description: name of the newstyle mask bit field (’type’) as registered with SpaceMask
 
Range  Default: mask  
.+  any valid bit field (’type’) name registered with
the SpaceMask thorn
 
new_style_mask_buffer_value  Scope: private  STRING 
Description: set the specified bit field of the newstyle mask to this named state at grid points in
the ’buffer’ region
 
Range  Default: buffer  
.+  any state name registered with the SpaceMask
thorn
 
new_style_mask_gridfn_name  Scope: private  STRING 
Description: name of the newstyle mask grid function
 
Range  Default: SpaceMask::space_mask  
.+  any valid Cactus grid function name
 
new_style_mask_inside_value  Scope: private  STRING 
Description: set the specified bit field of the newstyle mask to this named state at grid points in
the ’inside’ region
 
Range  Default: inside  
.+  any state name registered with the SpaceMask
thorn
 
new_style_mask_outside_value  Scope: private  STRING 
Description: set the specified bit field of the newstyle mask to this named state at grid points in
the ’outside’ region
 
Range  Default: outside  
.+  any state name registered with the SpaceMask
thorn
 
old_style_mask_buffer_value  Scope: private  REAL 
Description: set the oldstyle mask to this value in the ’buffer’ region
 
Range  Default: 0.5  
*:*  any real number
 
old_style_mask_gridfn_name  Scope: private  STRING 
Description: name of the oldstyle mask grid function
 
Range  Default: SpaceMask::emask  
.+  any valid Cactus grid function name
 
old_style_mask_inside_value  Scope: private  REAL 
Description: set the oldstyle mask to this value in the ’inside’ region
 
Range  Default: 0.0  
*:*  any real number
 
old_style_mask_outside_value  Scope: private  REAL 
Description: set the oldstyle mask to this value in the ’outside’ region
 
Range  Default: 1.0  
*:*  any real number
 
opendx_control_file_name_extension  Scope: private  STRING 
Description: file name extension for OpenDX control files
 
Range  Default: dx  
.+  any nonempty string
 
origin_x  Scope: private  REAL 
Description: global x coordinate of patch system origin
 
Range  Default: 0.0  
*:*  any real number
 
origin_y  Scope: private  REAL 
Description: global y coordinate of patch system origin
 
Range  Default: 0.0  
*:*  any real number
 
origin_z  Scope: private  REAL 
Description: global z coordinate of patch system origin
 
Range  Default: 0.0  
*:*  any real number
 
output_ascii_files  Scope: private  BOOLEAN 
Description: output h and Theta(h) as ASCII files
 
Default: yes  
output_bh_diagnostics  Scope: private  BOOLEAN 
Description: should we output BH diagnostics to a data file for each AH found?
 
Default: true  
output_ghost_zones_for_h  Scope: private  BOOLEAN 
Description: should we include the patch system (angular) interpatch ghost zones in h data files?
 
Default: false  
output_h_every  Scope: private  INT 
Description: how often (in Cactus time steps) should we output h (0 to disable)?
 
Range  Default: 1  
don’t output h at all
 
1:*  any integer >= 1
 
output_hdf5_files  Scope: private  BOOLEAN 
Description: output h and Theta(h) as HDF5 files
 
Default: no  
output_initial_guess  Scope: private  BOOLEAN 
Description: should we output the initial guess back to the h data file?
 
Default: false  
output_mean_curvature_every  Scope: private  INT 
Description: how often (in Cactus time steps) should we output the mean_curvature(h) functions?
 
Range  Default: (none)  
don’t output mean_curvature(h) at all
 
1:*  any integer >= 1
 
output_opendx_control_files  Scope: private  BOOLEAN 
Description: should we output OpenDX control files to allow reading of AHFinderDirect ’ASCII
(gnuplot)’ format data files?
 
Default: true  
output_theta_every  Scope: private  INT 
Description: how often (in Cactus time steps) should we output the Theta(h) functions?
 
Range  Default: (none)  
don’t output Theta(h) at all
 
1:*  any integer >= 1
 
patch_overlap_width  Scope: private  INT 
Description: number of grid points that nominallyjusttouching patches should overlap
 
Range  Default: 1  
1:*:2  any integer >= 0; current implementation
requires that it be odd
 
patch_system_type  Scope: private  KEYWORD 
Description: what type of patch system should we use?
 
Range  Default: match Cactus grid symmetry  
see [1] below  choose automagically based on grid symmetries
and the patch system’s origin
 
full sphere  full sphere, no symmetries
 
+z hemisphere  mirror symmetry across z=0 plane
 
see [1] below  90 degree periodic rotation symmetry about z
axis
 
see [1] below  mirror symmetry across x=0 and y=0 planes
 
see [1] below  mirror symmetry across x=0 and z=0 planes
 
see [1] below  180 degree periodic rotation symmetry about z
axis and mirror symmetry across z=0 plane
 
see [1] below  90 degree periodic rotation symmetry about z
axis and mirror symmetry across z=0 plane
 
see [1] below  mirror symmetry across x=0 and y=0 and z=0
planes
 
[1]
[1]
[1]
[1]
[1]
[1]
[1]
predict_origin_movement  Scope: private  BOOLEAN 
Description: predict origin movement when moving the origins
 
Default: no  
pretracking_delta  Scope: private  REAL 
Description: step size for value
 
Range  Default: 1.0  
(0.0:*  
pretracking_max_iterations  Scope: private  INT 
Description: maximum number of pretracking iterations
 
Range  Default: 100  
0:*  
pretracking_maximum_delta  Scope: private  REAL 
Description: maximum step size for value
 
Range  Default: 1.0  
(0.0:*  
pretracking_maximum_value  Scope: private  REAL 
Description: maximum pretracking value (should be near the outer boundary)
 
Range  Default: 10.0  
*:*  
pretracking_minimum_delta  Scope: private  REAL 
Description: minimum step size for value
 
Range  Default: 1.0e4  
(0.0:*  
pretracking_minimum_value  Scope: private  REAL 
Description: minimum pretracking value
 
Range  Default: 0.0  
*:*  
pretracking_value  Scope: private  REAL 
Description: initial pretracking value
 
Range  Default: 1.0  
*:*  
print_timing_stats  Scope: private  BOOLEAN 
Description: should we print timing stats for the whole apparenthorizonfinding process?
 
Default: false  
reset_horizon_after_not_finding  Scope: private  BOOLEAN 
Description: reset the horizon shape to the initial data if a horizon was not found
 
Default: yes  
reshape_while_moving  Scope: private  BOOLEAN 
Description: reshape the horizons when moving them
 
Default: no  
run_at_cctk_analysis  Scope: private  BOOLEAN 
Description: should we run at CCTK_ANALYSIS?
 
Default: false  
run_at_cctk_post_recover_variables  Scope: private  BOOLEAN 
Description: should we run at CCTK_POST_RECOVER_VARIABLES?
 
Default: false  
run_at_cctk_postinitial  Scope: private  BOOLEAN 
Description: should we run at CCTK_POSTINITIAL?
 
Default: false  
run_at_cctk_postpostinitial  Scope: private  BOOLEAN 
Description: should we run at CCTK_POSTPOSTINITIAL?
 
Default: false  
run_at_cctk_poststep  Scope: private  BOOLEAN 
Description: should we run at CCTK_POSTSTEP?
 
Default: true  
set_mask_for_all_horizons  Scope: private  BOOLEAN 
Description: should we set a mask grid function (or functions) for all horizons?
 
Default: false  
set_mask_for_individual_horizon  Scope: private  BOOLEAN 
Description: should we set a mask grid function (or functions) for *this* horizon?
 
Default: false  
set_new_style_mask  Scope: private  BOOLEAN 
Description: if we’re setting a mask, should we set an newstyle (CCTK_INT) mask gridfn?
 
Default: false  
set_old_style_mask  Scope: private  BOOLEAN 
Description: if we’re setting a mask, should we set an oldstyle (CCTK_REAL) mask gridfn?
 
Default: true  
shiftout_factor  Scope: private  REAL 
Description: enlarge the surface initial guess before finding
 
Range  Default: 1.0  
(0:*  choose 1 for doing nothing, larger for enlarging,
smaller for shrinking
 
smoothing_factor  Scope: private  REAL 
Description: smoothen (remove higher multipole moments) the surface initial guess before finding
 
Range  Default: 0.0  
*:*  choose 0 for no smoothing, 1 for complete
smoothing, larger for oversmoothing, negative
for roughening
 
surface_definition  Scope: private  KEYWORD 
Description: search for what kind of surface?
 
Range  Default: expansion  
expansion  Theta_(l) (apparent horizons etc.)
 
inner expansion  Theta_(n) (expansion of ingoing null normal)
 
mean curvature  for CMC surfaces
 
expansion product  Theta_(l) Theta_(n) (product of the
expansions)
 
surface_interpolator_name  Scope: private  STRING 
Description: name under which the surface interpolation operator is registered in Cactus
 
Range  Default: Lagrange polynomial interpolation  
$̂  the empty string if this interpolator isn’t going
to be used
 
.+  any string (in practice it should be nonempty)
 
surface_interpolator_pars  Scope: private  STRING 
Description: parameters for the surface interpolator
 
Range  Default: order=2 boundary_off_centering_tolerance={1.0e10 1.0e10 1.0e10 1.0e10} boundary_extrapolation_tolerance={0.0 0.0 0.0 0.0}  
.*  ”any string
acceptable to Util_TableSetFromStr ing() and
to the interpolator”
 
surface_modification  Scope: private  KEYWORD 
Description: how to modify the surface definition
 
Range  Default: none  
none  no modification  
radius  multiply with the coordinate radius
 
radius2̂  multiply with the square of the coordinate
radius
 
mean radius  multiply with the mean coordinate radius
 
areal radius  multiply with the areal radius (does not
converge nicely, because the Jacobian is only
approximate)
 
surface_selection  Scope: private  KEYWORD 
Description: search for a surface with this areal radius
 
Range  Default: definition  
definition  ”look for a surface as defined by
’surface_definition’ ”
 
see [1] below  look for a surface with a certain mean
coordinate radius (not covariant, but fast)
 
areal radius  look for a surface with a certain areal radius
 
see [1] below  look for a surface with a certain product of
expansion and mean coordiante radius
 
see [1] below  look for a surface with a certain product of
expansion and areal radius
 
[1]
[1]
[1]
test_all_jacobian_compute_methods  Scope: private  BOOLEAN 
Description: should we test all Jacobian computation methods, or just NP?
 
Default: true  
theta_base_file_name  Scope: private  STRING 
Description: base file name for Theta(h) output file(s)
 
Range  Default: Theta  
.+  any nonempty string
 
theta_norm_for_convergence  Scope: private  REAL 
Description: we declare the horizon to be found if ——Theta——_infinity <= this
 
Range  Default: 1.0e8  
(0.0:*  any positive real number
 
track_origin_from_grid_scalar  Scope: private  BOOLEAN 
Description: track horizon origin from given grid scalars
 
Default: no  
track_origin_source_x  Scope: private  STRING 
Description: grid scalar containing the x component of the origin estimate
 
Range  Default: (none)  
don’t use this feature
 
see [1] below  name of a grid scalar
 
[1]
track_origin_source_y  Scope: private  STRING 
Description: grid scalar containing the x component of the origin estimate
 
Range  Default: (none)  
don’t use this feature
 
see [1] below  name of a grid scalar
 
[1]
track_origin_source_z  Scope: private  STRING 
Description: grid scalar containing the x component of the origin estimate
 
Range  Default: (none)  
don’t use this feature
 
see [1] below  name of a grid scalar
 
[1]
umfpack__n_ii_iterations  Scope: private  INT 
Description: number of iterativeimprovement iterations to do inside UMFPACK after the sparse
LU decompose/solve, each time we solve a linear system
 
Range  Default: (none)  
1  use the UMFPACK default
 
don’t do iterative improvement
 
1:*  any positive integer (in practice a few iterations
give almost all the benefit)
 
use_pretracking  Scope: private  BOOLEAN 
Description: search for an outermost apparent horizon
 
Default: no  
verbose_level  Scope: private  KEYWORD 
Description: controls which (how many) messages to print describing AH finding
 
Range  Default: physics details  
physics highlights  just a few physics messages
 
physics details  more detailed physics messages
 
algorithm highlights  physics details + a few messages about the
AHfinding algorithm
 
algorithm details  physics details + lots of messages about the
AHfinding algorithm
 
algorithm debug  physics details + lots and lots of messages
about the AHfinding algorithm
 
want_expansion_gradients  Scope: private  BOOLEAN 
Description: should we print the gradients of the expansions?
 
Default: false  
warn_level__gij_not_positive_definite__initial  Scope: private  INT 
Description: warning level if the interpolated g_{ij} isn’t positive definite (usually this means
we’re too close to a singularity) (error occurs on first Newton iteration)
 
Range  Default: 2  
1:*  any valid Cactus warning level
 
warn_level__gij_not_positive_definite__subsequent  Scope: private  INT 
Description: warning level if the interpolated g_{ij} isn’t positive definite (usually this means
we’re too close to a singularity) (error occurs on subsequent Newton iteration)
 
Range  Default: 2  
1:*  any valid Cactus warning level
 
warn_level__nonfinite_geometry  Scope: private  INT 
Description: warning level if we find infinity and/or NaN in the interpolated geometry values
{g_ij, partial_k g_ij, K_ij}
 
Range  Default: 1  
1:*  any valid Cactus warning level
 
warn_level__point_outside__initial  Scope: private  INT 
Description: warning level for point outside (or too close to boundary of) Cactus grid (error
occurs on first Newton iteration)
 
Range  Default: 1  
1:*  any valid Cactus warning level
 
warn_level__point_outside__subsequent  Scope: private  INT 
Description: warning level for point outside (or too close to boundary of) Cactus grid (error
occurs on subsequent Newton iteration)
 
Range  Default: 2  
1:*  any valid Cactus warning level
 
warn_level__skipping_finite_check  Scope: private  INT 
Description: warning level if the user sets check_that_geometry_is_finite but the Cactus configure
process doesn’t find a finite() function so we have to skip the finitegeometry check
 
Range  Default: 3  
1:*  any valid Cactus warning level
 
which_horizon_to_announce_centroid  Scope: private  INT 
Description: for which horizon should we announce the centroid?
 
Range  Default: (none)  
don’t announce any centroid(s)
 
1:100  announce this horizon’s centroid each time we
find it
 
which_surface_to_store_info  Scope: private  INT 
Description: into which surface should we store the info?
 
Range  Default: 1  
1  don’t store info
 
0:*  store info into the corresponding surface
 
which_surface_to_store_info_by_name  Scope: private  STRING 
Description: into which surface should we store the info?
 
Range  Default: (none)  
”use which_surface_to_sto re_info”
 
.*  any string
 
maxnphi  Scope: shared from SPHERICALSURFACE  INT 
maxntheta  Scope: shared from SPHERICALSURFACE  INT 
nsurfaces  Scope: shared from SPHERICALSURFACE  INT 
Implements:
ahfinderdirect
Inherits:
grid
admbase
staticconformal
spacemask
sphericalsurface
io
Group Names  Variable Names  Details  
ahmask  ahmask  compact  0 
dimensions  3  
distribution  DEFAULT  
group type  GF  
tags  tensortypealias=”Scalar” Prolongation=”None” InterpNumTimelevels=1  
timelevels  3  
variable type  REAL  
ah_radius  ah_radius  compact  0 
dimensions  3  
distribution  CONSTANT  
group type  ARRAY  
size  MAX_N_ZONES_PER_RIGHT_ANGLE+1  
size  MAX_N_ZONES_PER_RIGHT_ANGLE+1  
size  6  
timelevels  1  
vararray_size  N_horizons  
variable type  REAL  
ah_origin  compact  0  
ah_origin_x  dimensions  0  
ah_origin_y  distribution  CONSTANT  
ah_origin_z  group type  SCALAR  
timelevels  1  
vararray_size  N_horizons  
variable type  REAL  
ah_centroid  compact  0  
ah_centroid_x  dimensions  0  
ah_centroid_y  distribution  CONSTANT  
ah_centroid_z  group type  SCALAR  
ah_centroid_t  timelevels  1  
ah_centroid_x_p  vararray_size  N_horizons  
ah_centroid_y_p  variable type  REAL  
ah_flags  compact  0  
ah_initial_find_flag  dimensions  0  
ah_really_initial_find_flag  distribution  CONSTANT  
ah_search_flag  group type  SCALAR  
ah_found_flag  timelevels  1  
ah_centroid_valid  vararray_size  N_horizons  
ah_centroid_valid_p  variable type  INT  
Uses header:
SpaceMask.h
Provides:
HorizonLocalCoordinateOrigin to
HorizonWasFound to
HorizonCentroid to
HorizonRadiusInDirection to
This section lists all the variables which are assigned storage by thorn EinsteinAnalysis/AHFinderDirect. 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:  
ah_radius ah_origin ah_centroid ah_flags  
ahmask[1]  
CCTK_BASEGRID
ahfinderdirect_setup
setup data structures
After:  spatialcoordinates  
Language:  c  
Options:  global  
Type:  function  
Writes:  ahfinderdirect::ah_centroid(everywhere)  
ah_flags  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_recover
import horizon data from cactus variables
Language:  c  
Options:  global  
Type:  function  
CCTK_ANALYSIS (conditional)
ahfinderdirect_announce
announce horizon position(s) to other thorns
After:  ahfinderdirect_find_horizons  
Before:  driftcorrect  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_ANALYSIS (conditional)
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Type:  function  
CCTK_POSTSTEP (conditional)
ahfinderdirect_import_mask
import the excision mask
Before:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
looplocal  
Reads:  spacemask::emask  
Type:  function  
Writes:  ahfinderdirect::ahmask(everywhere)  
CCTK_POSTSTEP (conditional)
ahfinderdirect_store
store apparent horizon(s) into spherical surface(s)
After:  ahfinderdirect_find_horizons  
Before:  sphericalsurface_hasbeenset  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTSTEP (conditional)
ahfinderdirect_save
save apparent horizon(s) into cactus variables
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTSTEP (conditional)
ahfinderdirect_announce
announce horizon position(s) to other thorns
After:  ahfinderdirect_find_horizons  
Before:  driftcorrect  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTSTEP (conditional)
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Type:  function  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_import_mask
import the excision mask
Before:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
looplocal  
Reads:  spacemask::emask  
Type:  function  
Writes:  ahfinderdirect::ahmask(everywhere)  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_store
store apparent horizon(s) into spherical surface(s)
After:  ahfinderdirect_find_horizons  
Before:  sphericalsurface_hasbeenset  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_save
save apparent horizon(s) into cactus variables
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_ANALYSIS (conditional)
ahfinderdirect_find_horizons
find apparent horizon(s) after this time step
Language:  c  
Options:  globalearly  
Reads:  staticconformal::conformal_state  
Type:  function  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_announce
announce horizon position(s) to other thorns
After:  ahfinderdirect_find_horizons  
Before:  driftcorrect  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Type:  function  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_import_mask
import the excision mask
Before:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
looplocal  
Reads:  spacemask::emask  
Type:  function  
Writes:  ahfinderdirect::ahmask(everywhere)  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_store
store apparent horizon(s) into spherical surface(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_save
save apparent horizon(s) into cactus variables
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_announce
announce horizon position(s) to other thorns
After:  ahfinderdirect_find_horizons  
Before:  driftcorrect  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Type:  function  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_import_mask
import the excision mask
Before:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
looplocal  
Reads:  spacemask::emask  
Type:  function  
Writes:  ahfinderdirect::ahmask(everywhere)  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_store
store apparent horizon(s) into spherical surface(s)
After:  ahfinderdirect_find_horizons  
Before:  sphericalsurface_hasbeenset  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_save
save apparent horizon(s) into cactus variables
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTSTEP (conditional)
ahfinderdirect_find_horizons
find apparent horizon(s) after this time step
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_announce
announce horizon position(s) to other thorns
After:  ahfinderdirect_find_horizons  
Before:  driftcorrect  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  ahfinderdirect_find_horizons  
Language:  c  
Type:  function  
CCTK_POSTREGRIDINITIAL
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  maskone  
maskzero  
Language:  c  
Type:  function  
CCTK_POSTREGRID
ahfinderdirect_maybe_do_masks
set mask(s) based on apparent horizon position(s)
After:  maskone  
maskzero  
Language:  c  
Type:  function  
CCTK_POSTINITIAL (conditional)
ahfinderdirect_find_horizons
find apparent horizon(s) after this time step
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POSTPOSTINITIAL (conditional)
ahfinderdirect_find_horizons
find apparent horizon(s) after this time step
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_POST_RECOVER_VARIABLES (conditional)
ahfinderdirect_find_horizons
find apparent horizon(s) after this time step
After:  mol_poststep  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_ANALYSIS (conditional)
ahfinderdirect_import_mask
import the excision mask
Before:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
looplocal  
Reads:  spacemask::emask  
Type:  function  
Writes:  ahfinderdirect::ahmask(everywhere)  
CCTK_ANALYSIS (conditional)
ahfinderdirect_store
store apparent horizon(s) into spherical surface(s)
After:  ahfinderdirect_find_horizons  
Before:  sphericalsurface_hasbeenset  
Language:  c  
Options:  globalearly  
Type:  function  
CCTK_ANALYSIS (conditional)
ahfinderdirect_save
save apparent horizon(s) into cactus variables
After:  ahfinderdirect_find_horizons  
Language:  c  
Options:  globalearly  
Type:  function  