# Working with horizons¶

The module `cactus_horizon`

(Reference on kuibit.cactus_horizons) can read output data produced by `AHFinderDirect`

and `QuasiLocalMeasures`

.

The simplest way to access horizon data is via `SimDir`

with the
attribute `horizons()`

, which returns an object of type
`HorizonsDir`

. `HorizonsDir`

collects all the
information available from the `AHFinderDirect`

and `QuasiLocalMeasures`

thorns, including the shape of the horizons.

Note

`AHFinderDirect`

and `QuasiLocalMeasures`

use different indexing systems.
At the moment, `kuibit`

cannot connect the two automatically, so an
horizon is identified by both the numbers.

To access horizon information, use the bracket notation, for example, if `sim`

is a `SimDir`

, `sim.horizons[0, 1]`

will return the horizon with
QLM index 0 and AH index 1. The result of this operation is a
`OneHorizon`

object. This contains all the variables from both
`QuasiLocalMeasures`

and `AHFinderDirect`

(the `BHdiagnostics`

files) as
`TimeSeries`

. To access the QLM variables, you canuse the bracket
notation (e.g., `hor['mass']`

), to access the AH ones you can access them via
the `ah`

attribute (e.g., `hor.ah.area`

, or `hor.ah['area']`

).

If you only need (or have) one of the two, you can access the relevant
information with `get_apparent_horizon()`

or
`get_qlm_horizon()`

.

You can access the shape of an horizon from `OneHorizon`

with the
the method `shape_at_iteration()`

. This returns three lists of
with the various 3D patches that form each horizon. In case you are only
interested in a project of the shape on a 2D plane or 1D axis, you
can use `shape_outline_at_iteration()`

and specify the `cut`

.
For example, if you want to look at the equatiorial plane, you would
set `cut=(None, None, 0)`

.

Warning

No interpolation is performed, so results are not accurate when the cut is not along one of the major directions centered in the origin of the horizon.

## VT data¶

`QuasiLocalMeasures`

can optionally output `.vtk`

files which contain the
horizon mesh and some internal variables defined on such meshes (when the option
`QuasiLocalMeasures::output_vtk_every`

is positive). `kuibit`

can parse
these files and represent variables defined on the horizons. The attribute
`vtk_available_iterations()`

returns a list with the iterations at
which VTK data is available and the method
`available_vtk_variables_at_iteration()`

returns a list with which
variables are available at the given iteration.

Note

As a design choice, `.vtk`

parsing in `kuibit`

was developed with
flexibility as opposed to speed. `kuibit`

will always scan all the various
files without assuming much about them. `.vtk`

can be large, so if this turns
out to be a performance bottleneck, please open an issue on the bug tracker.

You can access the variables with the methods `vtk_at_iteration()`

, which
returns a dictionary-like object with all the variables at the given iteration, or
with `vtk_variable_at_iteration()`

, which returns a specific variable.

There are two special variables, `coordinates`

, which is a list of the 3D
coordinates of each vertex that form the horizon mesh, and `connectivity`

,
which describes the faces of the horizon. The `connectivity`

list is formed by
NumPy arrays of the form `4 i1 i2 i3 i4`

. The first number (4) indicates that
the mesh is formed by polygons with four sides. The other four numbers mean that
the vertices identified by those four numbers are joined together. For example,
`4 0 1 2 3`

means that the `coordinates[0]`

, `coordinates[1]`

,
`coordinates[2]`

, and `coordinates[3]`

form a face of the mesh. Then, each
variable is defined as 1D NumPy array with one value for each vertex.