Reference on kuibit.cactus_horizons

The cactus_horizons module provides classes to access the information about apparent horizons from QuasiLocalMeasures and AHFinderDirect (including shape files).

The main class is HorizonsDir which collects all available data from a SimDir. This is a dictionary-like object whose values can be accessed providing two integers. The first is the QuasiLocalMeasures index, the second is the AHFinderDirect (we need two indices because at the moment we have no way to connect the two indexing systems). If only one of the two is available, the other index can be a dummy.

Once an horizon is selected with a combination of QLM and AHFinderDirect indices, the resulting object is a OneHorizon. OneHorizon contains as attributes all the QLM variables. Similarly, the attribute ah contains all the variables read from AHFinderDirect. All of these are represented as TimeSeries. OneHorizon also contains the shapes of the horizons (if the files are found), which can be accessed with the methods shape_at_iteration() and shape_outline_at_iteration(). If VTK data is available (in .vtk files), it is processed and stored in the vtk attribute. :py:func:~.vtk_at_it` is a function that takes an iteration and returns a dictionary that contains the variables defined on the horizon (seen as a 3D mesh).

class kuibit.cactus_horizons.HorizonsDir(sd)[source]

Class to collect information on apparent horizons available from thorns AHFinderDirect and QuasiLocalMeasures.

Variables:

found_any – True if at least one horizon was found.

AHFinderDirect and QuasiLocalMeasures have different indexing. You must provide both when accessing a file. In the future, the map between the two indexing systems will be inferred from the paramter file.

Constructor.

Parameters:

sd (SimDir) – SimDir object providing access to data directory.

property available_apparent_horizons

Horizons in AH indexing with associated data.

Returns:

Indices of the AH horizons found in the data.

Return type:

list

property available_qlm_horizons

Horizons in QLM indexing with associated data.

Returns:

Indices of the QLM horizons found in the data.

Return type:

list

get_apparent_horizon(ah)[source]

Return a OneHorizon() corresponding to an horizon as found by AHFinderDirect.

Parameters:

ah (int) – AHFinderDirect index.

Returns:

Apparent horizon.

Return type:

OneHorizon()

get_qlm_horizon(qlm)[source]

Return a OneHorizon() corresponding to an horizon as analyzed by QuasiLocalMeasures.

Parameters:

qlm (int) – QuasiLocalMeasures index.

Returns:

QuasiLocalMeasures horizon.

Return type:

OneHorizon()

class kuibit.cactus_horizons.OneHorizon(qlm_vars, ah_vars, shape_files, vtk_files)[source]

This class represents properties of an apparent horizon computed from the quasi-isolated horizon formalism.

All the variables from QuasiLocalMeasures are available as TimeSeries as attributes. All the ones from AHFinderDirect are attributes of the attribute ah.

Variables:

  • formation_time – First time at which the horizon has been found (as from AHFinderDirect).

  • mass_final – QLM mass at the last iteration available.

  • spin_final – QLM spin (angular momentum) at the last iteration available.

  • dimensionless_spin_final – Dimensionless spin computed from QLM variables at the last iteration available.

  • shape_available – Whether the shape files are available.

  • shape_iterations – Iterations at which the shape is available.

  • shape_iterations_min – First iteration at which the shape is available.

  • shape_iterations_max – Last iteration at which the shape is available.

  • shape_times – Times at which the shape is available.

  • shape_times_min – First time at which the shape is available.

  • shape_times_max – Last time at which the shape is available.

  • vtk_available – Whether VTK files are available.

  • ah – All the variables from AHFinderDirect as TimeSeries.

Constructor.

Parameters:

  • qlm_vars (dict) – Dictionary that maps the name of the QLM variable with the associated TimeSeries.

  • ah_vars (dict) – Dictionary that maps the name of the AH variable with the associated TimeSeries.

  • shape_files (dict) – Dictionary that maps the iteration to the files where to find the shape at that iteration.

  • vtk_files (dict) – Dictionary that maps the iteration to the files where to find the vtk information at that iteration.

ah_origin_at_iteration(iteration)[source]

Return the AH origin at the given iteration.

Parameters:

iteration (int) – Iteration number.

Returns:

Origin of the horizon as from AHFinderDirect.

Return type:

3D NumPy array

available_vtk_variables_at_iteration(iteration)[source]

Return the variables available in the VTK file at the given iteration.

Most VTK variables are 1D arrays defined on the vertices of the horizon mesh (as in QuasiLocalMeasures). The only two special VTK variables are coordiantes, which is essentially a list of 3D coordinates of the vertices, and connectivity, which describes how the various faces are formed.

The connectivity variables is a list of indices of the form 4 i1 i2 i3 i4, which means that the four vertices with indices i1 i2 i3 i4 are connected by a face. In QuasiLocalMeasures, faces are always quadrilateral, so the first value of each element in connectivity will always be 4.

Parameters:

iteration (int) – Desired iteration

Returns:

List of variables available

Return type:

list

get_ah_property(key)[source]

Return a property from AHFinderDirect as timeseries.

Parameters:

key (str) – AH property.

Returns:

AH property as a function of time.

Return type:

TimeSeries

shape_at_iteration(iteration)[source]

Return the shape of the horizon as 3 arrays with the coordinates of the points.

Parameters:

iteration (int) – Iteration number.

Returns:

Shape of the horizon.

Return type:

three lists of 2D NumPy arrays, one for each coordinate. The list is over the different patches.

shape_at_time(time, tolerance=1e-10)[source]

Return the shape of the horizon as 3 arrays with the coordinates of the points.

Parameters:

  • time (float) – Time.

  • tolerance (float) – Tolerance in determining the time.

Returns:

Shape of the horizon.

Return type:

three lists of 2D NumPy arrays, one for each coordinate. The list is over the different patches.

shape_outline_at_iteration(iteration, cut)[source]

Return the cut of the 3D shape on a specified plane.

cut has to be a 3D tuple or list with None on the dimensions you want to keep, and the value of the other coordinates. For example, if you want the outline at z = 3 on the xy plane, cut has to be (None, None, 3).

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.

Parameters:

  • iteration (int) – Iteration number.

  • cut (3D tuple) – How should the horizon be sliced?

Returns:

Coordinates of AH outline.

Return type:

tuple of two 1D NumPy arrays.

shape_outline_at_time(time, cut, tolerance=1e-10)[source]

Return the cut of the 3D shape on a specified plane.

cut has to be a 3D tuple or list with None on the dimensions you want to keep, and the value of the other coordinates. For example, if you want the outline at z = 3 on the xy plane, cut has to be (None, None, 3).

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.

Parameters:

  • time (float) – Time.

  • tolerance (float) – Tolerance in determining the time.

  • cut (3D tuple) – How should the horizon be sliced?

Returns:

Coordinates of AH outline.

Return type:

tuple of two 1D NumPy arrays.

shape_time_at_iteration(iteration)[source]

Return the time corresponding to the given iteration using the information from the shape files.

Parameters:

iteration (int) – Iteration number.

Returns:

Time at the given iteration.

Return type:

float

vtk_at_it(iteration)

Return a dictionary-like object containing all the VTK variables at the given iteration.

Parameters:

iteration (int) – Desired iteration

Returns:

Dictionary-like object with all the VTK variables.

Return type:

AttributeDictionary

vtk_at_iteration(iteration)[source]

Return a dictionary-like object containing all the VTK variables at the given iteration.

Parameters:

iteration (int) – Desired iteration

Returns:

Dictionary-like object with all the VTK variables.

Return type:

AttributeDictionary

property vtk_available_iterations: List[int]

Return the list of iterations at which VTK data is available.

Returns:

List of iteration with associated VTK data

Return type:

list

vtk_variable_at_iteration(key, iteration)[source]

Return a variable from the VTK file at the given iteration.

See also docstring in available_vtk_variables_at_iteration().

Parameters:

  • iteration (int) – Desired variable

  • iteration – Desired iteration

Returns:

Variable

Return type:

NumPy array

kuibit.cactus_horizons.compute_horizons_separation(horizon1, horizon2, resample=True)[source]

Compute the coordinate separation between the centroids of two horizons.

The information from the apparent horizons is used (contained in the BHDiagnostics files).

Deprecated in favor of compute_separation().

Parameters:
Returns:

Coordinate distance between the two centroids, sampled over both the horizons are available.

Return type:

TimeSeries