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

The module contains also functions to work with horizons:

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

Parameters
Returns

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

Return type

TimeSeries