Namespaces
namespace	ylm
	Items related to spherical harmonics.

namespace	ylm::Tags
	Holds tags and ComputeItems associated with a `ylm::Strahlkorper`.

namespace	SurfaceFinder
	Contains functions that are used to find contour levels.

namespace	gr::surfaces::Tags
	Holds tags and ComputeItems associated with a `ylm::Strahlkorper` that also need a metric.

Classes
class	ylm::Strahlkorper< Frame >
	A star-shaped surface expanded in spherical harmonics. More...

struct	ylm::OptionTags::Strahlkorper< Frame >
	The input file tag for a Strahlkorper. More...

class	FastFlow
	Fast flow method for finding apparent horizons. More...

Functions
template<typename Frame >
std::vector< ylm::Strahlkorper< Frame > >	ylm::read_surface_ylm (const std::string &file_name, const std::string &surface_subfile_name, size_t requested_number_of_times_from_end)
	Returns a list of `ylm::Strahlkorper`s constructed from reading in spherical harmonic data for a surface at a requested list of times. More...

std::vector< std::optional< double > >	SurfaceFinder::find_radial_surface (const Scalar< DataVector > &data, const double target, const Mesh< 3 > &mesh, const tnsr::I< DataVector, 2, Frame::ElementLogical > &angular_coords, const double relative_tolerance=1e-10, const double absolute_tolerance=1e-10)
	Function that interpolates data onto radial rays in the direction of the logical coordinates \(\xi\) and \(\eta\) and tries to perform a root find of \(\text{data}-\text{target}\). Returns the logical coordinates of the roots found. More...

double	gr::surfaces::irreducible_mass (double area)
	Irreducible mass of a 2D `Strahlkorper`. More...

double	gr::surfaces::christodoulou_mass (double dimensionful_spin_magnitude, double irreducible_mass)
	Christodoulou Mass of a 2D `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::radial_distance (gsl::not_null< Scalar< DataVector > * > radial_distance, const ylm::Strahlkorper< Frame > &strahlkorper_a, const ylm::Strahlkorper< Frame > &strahlkorper_b)
	Radial distance between two `Strahlkorper`s. More...

template<typename MetricDataFrame , typename MeasurementFrame >
void	gr::surfaces::spin_vector (const gsl::not_null< std::array< double, 3 > * > result, double spin_magnitude, const Scalar< DataVector > &area_element, const Scalar< DataVector > &ricci_scalar, const Scalar< DataVector > &spin_function, const ylm::Strahlkorper< MetricDataFrame > &strahlkorper, const tnsr::I< DataVector, 3, MeasurementFrame > &measurement_frame_coords)
	Spin vector of a 2D `Strahlkorper`. More...

template<typename Frame >
double	gr::surfaces::surface_integral_of_scalar (const Scalar< DataVector > &area_element, const Scalar< DataVector > &scalar, const ylm::Strahlkorper< Frame > &strahlkorper)
	Surface integral of a scalar on a 2D `Strahlkorper` More...

template<typename Frame >
double	gr::surfaces::euclidean_surface_integral_of_vector (const Scalar< DataVector > &area_element, const tnsr::I< DataVector, 3, Frame > &vector, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const ylm::Strahlkorper< Frame > &strahlkorper)
	Euclidean surface integral of a vector on a 2D `Strahlkorper` More...

template<typename Frame >
void	gr::surfaces::area_element (gsl::not_null< Scalar< DataVector > * > result, const tnsr::ii< DataVector, 3, Frame > &spatial_metric, const ylm::Tags::aliases::Jacobian< Frame > &jacobian, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &r_hat)
	Area element of a 2D `Strahlkorper`. More...

template<typename Frame >
Scalar< DataVector >	gr::surfaces::area_element (const tnsr::ii< DataVector, 3, Frame > &spatial_metric, const ylm::Tags::aliases::Jacobian< Frame > &jacobian, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &r_hat)
	Area element of a 2D `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::euclidean_area_element (gsl::not_null< Scalar< DataVector > * > result, const ylm::Tags::aliases::Jacobian< Frame > &jacobian, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &r_hat)
	Euclidean area element of a 2D `Strahlkorper`. More...

template<typename Frame >
Scalar< DataVector >	gr::surfaces::euclidean_area_element (const ylm::Tags::aliases::Jacobian< Frame > &jacobian, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &r_hat)
	Euclidean area element of a 2D `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::expansion (gsl::not_null< Scalar< DataVector > * > result, const tnsr::ii< DataVector, 3, Frame > &grad_normal, const tnsr::II< DataVector, 3, Frame > &inverse_surface_metric, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature)
	Expansion of a `Strahlkorper`. Should be zero on apparent horizons. More...

template<typename Frame >
Scalar< DataVector >	gr::surfaces::expansion (const tnsr::ii< DataVector, 3, Frame > &grad_normal, const tnsr::II< DataVector, 3, Frame > &inverse_surface_metric, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature)
	Expansion of a `Strahlkorper`. Should be zero on apparent horizons. More...

template<typename Frame >
void	gr::surfaces::extrinsic_curvature (gsl::not_null< tnsr::ii< DataVector, 3, Frame > * > result, const tnsr::ii< DataVector, 3, Frame > &grad_normal, const tnsr::i< DataVector, 3, Frame > &unit_normal_one_form, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector)
	Extrinsic curvature of a 2D `Strahlkorper` embedded in a 3D space. More...

template<typename Frame >
tnsr::ii< DataVector, 3, Frame >	gr::surfaces::extrinsic_curvature (const tnsr::ii< DataVector, 3, Frame > &grad_normal, const tnsr::i< DataVector, 3, Frame > &unit_normal_one_form, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector)
	Extrinsic curvature of a 2D `Strahlkorper` embedded in a 3D space. More...

template<typename Frame >
void	gr::surfaces::grad_unit_normal_one_form (gsl::not_null< tnsr::ii< DataVector, 3, Frame > * > result, const tnsr::i< DataVector, 3, Frame > &r_hat, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &unit_normal_one_form, const tnsr::ii< DataVector, 3, Frame > &d2x_radius, const DataVector &one_over_one_form_magnitude, const tnsr::Ijj< DataVector, 3, Frame > &christoffel_2nd_kind)
	Computes 3-covariant gradient \(D_i S_j\) of a Strahlkorper's normal. More...

template<typename Frame >
tnsr::ii< DataVector, 3, Frame >	gr::surfaces::grad_unit_normal_one_form (const tnsr::i< DataVector, 3, Frame > &r_hat, const Scalar< DataVector > &radius, const tnsr::i< DataVector, 3, Frame > &unit_normal_one_form, const tnsr::ii< DataVector, 3, Frame > &d2x_radius, const DataVector &one_over_one_form_magnitude, const tnsr::Ijj< DataVector, 3, Frame > &christoffel_2nd_kind)
	Computes 3-covariant gradient \(D_i S_j\) of a Strahlkorper's normal. More...

template<typename Frame >
void	gr::surfaces::inverse_surface_metric (gsl::not_null< tnsr::II< DataVector, 3, Frame > * > result, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const tnsr::II< DataVector, 3, Frame > &upper_spatial_metric)
	Computes inverse 2-metric \(g^{ij}-S^i S^j\) of a Strahlkorper. More...

template<typename Frame >
tnsr::II< DataVector, 3, Frame >	gr::surfaces::inverse_surface_metric (const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const tnsr::II< DataVector, 3, Frame > &upper_spatial_metric)
	Computes inverse 2-metric \(g^{ij}-S^i S^j\) of a Strahlkorper. More...

template<typename Frame >
void	gr::surfaces::ricci_scalar (gsl::not_null< Scalar< DataVector > * > result, const tnsr::ii< DataVector, 3, Frame > &spatial_ricci_tensor, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature, const tnsr::II< DataVector, 3, Frame > &upper_spatial_metric)
	Intrinsic Ricci scalar of a 2D `Strahlkorper`. More...

template<typename Frame >
Scalar< DataVector >	gr::surfaces::ricci_scalar (const tnsr::ii< DataVector, 3, Frame > &spatial_ricci_tensor, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature, const tnsr::II< DataVector, 3, Frame > &upper_spatial_metric)
	Intrinsic Ricci scalar of a 2D `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::spin_function (gsl::not_null< Scalar< DataVector > * > result, const ylm::Tags::aliases::Jacobian< Frame > &tangents, const ylm::Strahlkorper< Frame > &strahlkorper, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const Scalar< DataVector > &area_element, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature)
	Spin function of a 2D `Strahlkorper`. More...

template<typename Frame >
Scalar< DataVector >	gr::surfaces::spin_function (const ylm::Tags::aliases::Jacobian< Frame > &tangents, const ylm::Strahlkorper< Frame > &strahlkorper, const tnsr::I< DataVector, 3, Frame > &unit_normal_vector, const Scalar< DataVector > &area_element, const tnsr::ii< DataVector, 3, Frame > &extrinsic_curvature)
	Spin function of a 2D `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::dimensionful_spin_magnitude (gsl::not_null< double * > result, const Scalar< DataVector > &ricci_scalar, const Scalar< DataVector > &spin_function, const tnsr::ii< DataVector, 3, Frame > &spatial_metric, const ylm::Tags::aliases::Jacobian< Frame > &tangents, const ylm::Strahlkorper< Frame > &strahlkorper, const Scalar< DataVector > &area_element)
	Spin magnitude measured on a 2D `Strahlkorper`. More...

template<typename Frame >
double	gr::surfaces::dimensionful_spin_magnitude (const Scalar< DataVector > &ricci_scalar, const Scalar< DataVector > &spin_function, const tnsr::ii< DataVector, 3, Frame > &spatial_metric, const ylm::Tags::aliases::Jacobian< Frame > &tangents, const ylm::Strahlkorper< Frame > &strahlkorper, const Scalar< DataVector > &area_element)
	Spin magnitude measured on a 2D `Strahlkorper`. More...

void	gr::surfaces::dimensionless_spin_magnitude (const gsl::not_null< double * > result, const double dimensionful_spin_magnitude, const double christodoulou_mass)
	Dimensionless spin magnitude of a `Strahlkorper`. More...

double	gr::surfaces::dimensionless_spin_magnitude (const double dimensionful_spin_magnitude, const double christodoulou_mass)
	Dimensionless spin magnitude of a `Strahlkorper`. More...

template<typename Frame >
void	gr::surfaces::unit_normal_one_form (gsl::not_null< tnsr::i< DataVector, 3, Frame > * > result, const tnsr::i< DataVector, 3, Frame > &normal_one_form, const DataVector &one_over_one_form_magnitude)
	Computes normalized unit normal one-form to a Strahlkorper. More...

template<typename Frame >
tnsr::i< DataVector, 3, Frame >	gr::surfaces::unit_normal_one_form (const tnsr::i< DataVector, 3, Frame > &normal_one_form, const DataVector &one_over_one_form_magnitude)
	Computes normalized unit normal one-form to a Strahlkorper. More...

Detailed Description

Things related to surfaces.

Function Documentation

◆ area_element() [1/2]

template<typename Frame >

Scalar< DataVector > gr::surfaces::area_element	(	const tnsr::ii< DataVector, 3, Frame > &	spatial_metric,
		const ylm::Tags::aliases::Jacobian< Frame > &	jacobian,
		const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	r_hat
	)

Area element of a 2D Strahlkorper.

Details

Implements Eq. (D.13), using Eqs. (D.4) and (D.5), of [14]. Specifically, computes \(\sqrt{(\Theta^i\Theta_i)(\Phi^j\Phi_j)-(\Theta^i\Phi_i)^2}\), \(\Theta^i=\left(n^i(n_j-s_j) r J^j_\theta + r J^i_\theta\right)\), \(\Phi^i=\left(n^i(n_j-s_j)r J^j_\phi + r J^i_\phi\right)\), and \(\Theta^i\) and \(\Phi^i\) are lowered by the 3D spatial metric \(g_{ij}\). Here \(J^i_\alpha\), \(s_j\), \(r\), and \(n^i=n_i\) correspond to the input arguments jacobian, normal_one_form, radius, and r_hat, respectively; these input arguments depend only on the Strahlkorper, not on the metric, and can be computed from a Strahlkorper using ComputeItems in ylm::Tags. Note that this does not include the factor of \(\sin\theta\), i.e., this returns \(r^2\) for a spherical Strahlkorper in flat space. This choice makes the area element returned here compatible with definite_integral defined in YlmSpherePack.hpp.

◆ area_element() [2/2]

template<typename Frame >

void gr::surfaces::area_element	(	gsl::not_null< Scalar< DataVector > * >	result,
		const tnsr::ii< DataVector, 3, Frame > &	spatial_metric,
		const ylm::Tags::aliases::Jacobian< Frame > &	jacobian,
		const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	r_hat
	)

Area element of a 2D Strahlkorper.

Details

Implements Eq. (D.13), using Eqs. (D.4) and (D.5), of [14]. Specifically, computes \(\sqrt{(\Theta^i\Theta_i)(\Phi^j\Phi_j)-(\Theta^i\Phi_i)^2}\), \(\Theta^i=\left(n^i(n_j-s_j) r J^j_\theta + r J^i_\theta\right)\), \(\Phi^i=\left(n^i(n_j-s_j)r J^j_\phi + r J^i_\phi\right)\), and \(\Theta^i\) and \(\Phi^i\) are lowered by the 3D spatial metric \(g_{ij}\). Here \(J^i_\alpha\), \(s_j\), \(r\), and \(n^i=n_i\) correspond to the input arguments jacobian, normal_one_form, radius, and r_hat, respectively; these input arguments depend only on the Strahlkorper, not on the metric, and can be computed from a Strahlkorper using ComputeItems in ylm::Tags. Note that this does not include the factor of \(\sin\theta\), i.e., this returns \(r^2\) for a spherical Strahlkorper in flat space. This choice makes the area element returned here compatible with definite_integral defined in YlmSpherePack.hpp.

◆ christodoulou_mass()

double gr::surfaces::christodoulou_mass	(	double	dimensionful_spin_magnitude,
		double	irreducible_mass
	)

Christodoulou Mass of a 2D Strahlkorper.

Details

See e.g. Eq. (1) of [122]. This function computes the Christodoulou mass from the dimensionful spin angular momentum \(S\) and the irreducible mass \(M_{irr}\) of a black hole horizon. Specifically, computes \(M=\sqrt{M_{irr}^2+\frac{S^2}{4M_{irr}^2}}\)

◆ dimensionful_spin_magnitude() [1/2]

template<typename Frame >

double gr::surfaces::dimensionful_spin_magnitude	(	const Scalar< DataVector > &	ricci_scalar,
		const Scalar< DataVector > &	spin_function,
		const tnsr::ii< DataVector, 3, Frame > &	spatial_metric,
		const ylm::Tags::aliases::Jacobian< Frame > &	tangents,
		const ylm::Strahlkorper< Frame > &	strahlkorper,
		const Scalar< DataVector > &	area_element
	)

Spin magnitude measured on a 2D Strahlkorper.

Details

Measures the quasilocal spin magnitude of a Strahlkorper, by inserting \(\alpha=1\) into Eq. (10) of [143] and dividing by \(8\pi\) to yield the spin magnitude. The spin magnitude is a Euclidean norm of surface integrals over the horizon \(S = \frac{1}{8\pi}\oint z \Omega dA\), where \(\Omega\) is obtained via gr::surfaces::spin_function(), \(dA\) is the area element, and \(z\) (the "spin potential") is a solution of a generalized eigenproblem given by Eq. (9) of [143]. Specifically, \(\nabla^4 z + \nabla \cdot (R\nabla z) = \lambda \nabla^2 z\), where \(R\) is obtained via gr::surfaces::ricci_scalar(). The spin magnitude is the Euclidean norm of the three values of \(S\) obtained from the eigenvectors \(z\) with the 3 smallest-magnitude eigenvalues \(\lambda\). Note that this formulation of the eigenproblem uses the "Owen" normalization, Eq. (A9) and surrounding discussion in [121]. The eigenvectors are normalized with the "Kerr normalization", Eq. (A22) of [121]. The argument spatial_metric is the metric of the 3D spatial slice evaluated on the Strahlkorper. The argument tangents can be obtained from the StrahlkorperDataBox using the ylm::Tags::Tangents tag, and the argument unit_normal_vector can be found by raising the index of the one-form returned by gr::surfaces::unit_normal_one_form. The argument strahlkorper is the surface on which the spin magnitude is computed. The argument area_element can be computed via gr::surfaces::area_element.

◆ dimensionful_spin_magnitude() [2/2]

template<typename Frame >

void gr::surfaces::dimensionful_spin_magnitude	(	gsl::not_null< double * >	result,
		const Scalar< DataVector > &	ricci_scalar,
		const Scalar< DataVector > &	spin_function,
		const tnsr::ii< DataVector, 3, Frame > &	spatial_metric,
		const ylm::Tags::aliases::Jacobian< Frame > &	tangents,
		const ylm::Strahlkorper< Frame > &	strahlkorper,
		const Scalar< DataVector > &	area_element
	)

Spin magnitude measured on a 2D Strahlkorper.

Details

Measures the quasilocal spin magnitude of a Strahlkorper, by inserting \(\alpha=1\) into Eq. (10) of [143] and dividing by \(8\pi\) to yield the spin magnitude. The spin magnitude is a Euclidean norm of surface integrals over the horizon \(S = \frac{1}{8\pi}\oint z \Omega dA\), where \(\Omega\) is obtained via gr::surfaces::spin_function(), \(dA\) is the area element, and \(z\) (the "spin potential") is a solution of a generalized eigenproblem given by Eq. (9) of [143]. Specifically, \(\nabla^4 z + \nabla \cdot (R\nabla z) = \lambda \nabla^2 z\), where \(R\) is obtained via gr::surfaces::ricci_scalar(). The spin magnitude is the Euclidean norm of the three values of \(S\) obtained from the eigenvectors \(z\) with the 3 smallest-magnitude eigenvalues \(\lambda\). Note that this formulation of the eigenproblem uses the "Owen" normalization, Eq. (A9) and surrounding discussion in [121]. The eigenvectors are normalized with the "Kerr normalization", Eq. (A22) of [121]. The argument spatial_metric is the metric of the 3D spatial slice evaluated on the Strahlkorper. The argument tangents can be obtained from the StrahlkorperDataBox using the ylm::Tags::Tangents tag, and the argument unit_normal_vector can be found by raising the index of the one-form returned by gr::surfaces::unit_normal_one_form. The argument strahlkorper is the surface on which the spin magnitude is computed. The argument area_element can be computed via gr::surfaces::area_element.

◆ dimensionless_spin_magnitude() [1/2]

double gr::surfaces::dimensionless_spin_magnitude	(	const double	dimensionful_spin_magnitude,
		const double	christodoulou_mass
	)

Dimensionless spin magnitude of a Strahlkorper.

Details

This function computes the dimensionless spin magnitude \(\chi\) from the dimensionful spin magnitude \(S\) and the christodoulou mass \(M\) of a black hole. Specifically, computes \(\chi = \frac{S}{M^2}\).

◆ dimensionless_spin_magnitude() [2/2]

void gr::surfaces::dimensionless_spin_magnitude	(	const gsl::not_null< double * >	result,
		const double	dimensionful_spin_magnitude,
		const double	christodoulou_mass
	)

Dimensionless spin magnitude of a Strahlkorper.

Details

This function computes the dimensionless spin magnitude \(\chi\) from the dimensionful spin magnitude \(S\) and the christodoulou mass \(M\) of a black hole. Specifically, computes \(\chi = \frac{S}{M^2}\).

◆ euclidean_area_element() [1/2]

template<typename Frame >

Scalar< DataVector > gr::surfaces::euclidean_area_element	(	const ylm::Tags::aliases::Jacobian< Frame > &	jacobian,
		const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	r_hat
	)

Euclidean area element of a 2D Strahlkorper.

This is useful for computing a flat-space integral over an arbitrarily-shaped Strahlkorper.

Details

Implements Eq. (D.13), using Eqs. (D.4) and (D.5), of [14]. Specifically, computes \(\sqrt{(\Theta^i\Theta_i)(\Phi^j\Phi_j)-(\Theta^i\Phi_i)^2}\), \(\Theta^i=\left(n^i(n_j-s_j) r J^j_\theta + r J^i_\theta\right)\), \(\Phi^i=\left(n^i(n_j-s_j)r J^j_\phi + r J^i_\phi\right)\), and \(\Theta^i\) and \(\Phi^i\) are lowered by the Euclidean spatial metric. Here \(J^i_\alpha\), \(s_j\), \(r\), and \(n^i=n_i\) correspond to the input arguments jacobian, normal_one_form, radius, and r_hat, respectively; these input arguments depend only on the Strahlkorper, not on the metric, and can be computed from a Strahlkorper using ComputeItems in ylm::Tags. Note that this does not include the factor of \(\sin\theta\), i.e., this returns \(r^2\) for a spherical Strahlkorper. This choice makes the area element returned here compatible with definite_integral defined in YlmSpherePack.hpp.

◆ euclidean_area_element() [2/2]

template<typename Frame >

void gr::surfaces::euclidean_area_element	(	gsl::not_null< Scalar< DataVector > * >	result,
		const ylm::Tags::aliases::Jacobian< Frame > &	jacobian,
		const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	r_hat
	)

void gr::surfaces::extrinsic_curvature	(	gsl::not_null< tnsr::ii< DataVector, 3, Frame > * >	result,
		const tnsr::ii< DataVector, 3, Frame > &	grad_normal,
		const tnsr::i< DataVector, 3, Frame > &	unit_normal_one_form,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector
	)

Extrinsic curvature of a 2D Strahlkorper embedded in a 3D space.

Details

Implements Eq. (D.43) of Carroll's Spacetime and Geometry text. Specifically, \( K_{ij} = P^k_i P^l_j \nabla_{(k} S_{l)} \), where \( P^k_i = \delta^k_i - S^k S_i \), grad_normal is the quantity \( \nabla_k S_l \) returned by gr::surfaces::grad_unit_normal_one_form, and unit_normal_vector is \(S^i = g^{ij} S_j\) where \(S_j\) is the unit normal one form. Not to be confused with the extrinsic curvature of a 3D spatial slice embedded in 3+1 spacetime. Because gr::surfaces::grad_unit_normal_one_form is symmetric, this can be expanded into \( K_{ij} = \nabla_{i}S_{j} - 2 S^k S_{(i}\nabla_{j)}S_k + S_i S_j S^k S^l \nabla_{k} n_{l}\).

◆ find_radial_surface()

std::vector< std::optional< double > > SurfaceFinder::find_radial_surface	(	const Scalar< DataVector > &	data,
		const double	target,
		const Mesh< 3 > &	mesh,
		const tnsr::I< DataVector, 2, Frame::ElementLogical > &	angular_coords,
		const double	relative_tolerance = `1e-10`,
		const double	absolute_tolerance = `1e-10`
	)

Function that interpolates data onto radial rays in the direction of the logical coordinates \(\xi\) and \(\eta\) and tries to perform a root find of \(\text{data}-\text{target}\). Returns the logical coordinates of the roots found.

Details

We assume the element is part of a wedge block, so that the \(\zeta\) logical coordinate points in the radial direction. Will fail if multiple roots are along a ray. This could be generalized to domains other than a wedge if necessary by passing in which logical direction points radially.

Parameters

data	data to find the contour in.
target	target value for the contour level in the data.
mesh	mesh for the element.
angular_coords	tensor containing the \(\xi\) and \(\eta\) values of the rays extending into \(\zeta\) direction.
relative_tolerance	relative tolerance for toms748 rootfind.
absolute_tolerance	relative tolerance for toms748 rootfind.

◆ grad_unit_normal_one_form() [1/2]

template<typename Frame >

tnsr::ii< DataVector, 3, Frame > gr::surfaces::grad_unit_normal_one_form	(	const tnsr::i< DataVector, 3, Frame > &	r_hat,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	unit_normal_one_form,
		const tnsr::ii< DataVector, 3, Frame > &	d2x_radius,
		const DataVector &	one_over_one_form_magnitude,
		const tnsr::Ijj< DataVector, 3, Frame > &	christoffel_2nd_kind
	)

Computes 3-covariant gradient \(D_i S_j\) of a Strahlkorper's normal.

Details

See Eqs. (1–9) of [14]. Here \(S_j\) is the (normalized) unit one-form to the surface, and \(D_i\) is the spatial covariant derivative. Note that this object is symmetric, even though this is not obvious from the definition. The input arguments r_hat, radius, and d2x_radius depend on the Strahlkorper but not on the metric, and can be computed from a Strahlkorper using ComputeItems in ylm::Tags. The input argument one_over_one_form_magnitude is \(1/\sqrt{g^{ij}n_i n_j}\), where \(n_i\) is ylm::Tags::NormalOneForm (i.e. the unnormalized one-form to the Strahlkorper); it can be computed using (one over) the magnitude function. The input argument unit_normal_one_form is \(S_j\),the normalized one-form.

◆ grad_unit_normal_one_form() [2/2]

template<typename Frame >

void gr::surfaces::grad_unit_normal_one_form	(	gsl::not_null< tnsr::ii< DataVector, 3, Frame > * >	result,
		const tnsr::i< DataVector, 3, Frame > &	r_hat,
		const Scalar< DataVector > &	radius,
		const tnsr::i< DataVector, 3, Frame > &	unit_normal_one_form,
		const tnsr::ii< DataVector, 3, Frame > &	d2x_radius,
		const DataVector &	one_over_one_form_magnitude,
		const tnsr::Ijj< DataVector, 3, Frame > &	christoffel_2nd_kind
	)

Computes 3-covariant gradient \(D_i S_j\) of a Strahlkorper's normal.

Details

See Eqs. (1–9) of [14]. Here \(S_j\) is the (normalized) unit one-form to the surface, and \(D_i\) is the spatial covariant derivative. Note that this object is symmetric, even though this is not obvious from the definition. The input arguments r_hat, radius, and d2x_radius depend on the Strahlkorper but not on the metric, and can be computed from a Strahlkorper using ComputeItems in ylm::Tags. The input argument one_over_one_form_magnitude is \(1/\sqrt{g^{ij}n_i n_j}\), where \(n_i\) is ylm::Tags::NormalOneForm (i.e. the unnormalized one-form to the Strahlkorper); it can be computed using (one over) the magnitude function. The input argument unit_normal_one_form is \(S_j\),the normalized one-form.

◆ inverse_surface_metric() [1/2]

template<typename Frame >

tnsr::II< DataVector, 3, Frame > gr::surfaces::inverse_surface_metric	(	const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const tnsr::II< DataVector, 3, Frame > &	upper_spatial_metric
	)

Computes inverse 2-metric \(g^{ij}-S^i S^j\) of a Strahlkorper.

Details

See Eqs. (1–9) of [14]. Here \(S^i\) is the (normalized) unit vector to the surface, and \(g^{ij}\) is the 3-metric. This object is expressed in the usual 3-d Cartesian basis, so it is written as a 3-dimensional tensor. But because it is orthogonal to \(S_i\), it has only 3 independent degrees of freedom, and could be expressed as a 2-d tensor with an appropriate choice of basis. The input argument unit_normal_vector is \(S^i = g^{ij} S_j\), where \(S_j\) is the unit normal one form.

◆ inverse_surface_metric() [2/2]

template<typename Frame >

void gr::surfaces::inverse_surface_metric	(	gsl::not_null< tnsr::II< DataVector, 3, Frame > * >	result,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const tnsr::II< DataVector, 3, Frame > &	upper_spatial_metric
	)

Computes inverse 2-metric \(g^{ij}-S^i S^j\) of a Strahlkorper.

Details

See Eqs. (1–9) of [14]. Here \(S^i\) is the (normalized) unit vector to the surface, and \(g^{ij}\) is the 3-metric. This object is expressed in the usual 3-d Cartesian basis, so it is written as a 3-dimensional tensor. But because it is orthogonal to \(S_i\), it has only 3 independent degrees of freedom, and could be expressed as a 2-d tensor with an appropriate choice of basis. The input argument unit_normal_vector is \(S^i = g^{ij} S_j\), where \(S_j\) is the unit normal one form.

◆ irreducible_mass()

double gr::surfaces::irreducible_mass ( double area )

Irreducible mass of a 2D Strahlkorper.

Details

See Eqs. (15.38) [84]. This function computes the irreducible mass from the area of a horizon. Specifically, computes \(M_\mathrm{irr}=\sqrt{\frac{A}{16\pi}}\).

◆ radial_distance()

template<typename Frame >

void gr::surfaces::radial_distance	(	gsl::not_null< Scalar< DataVector > * >	radial_distance,
		const ylm::Strahlkorper< Frame > &	strahlkorper_a,
		const ylm::Strahlkorper< Frame > &	strahlkorper_b
	)

Radial distance between two Strahlkorpers.

Details

Computes the pointwise radial distance \(r_a-r_b\) between two Strahlkorpers strahlkorper_a and strahlkorper_b that have the same center, first (if the Strahlkorpers' resolutions are unequal) prolonging the lower-resolution Strahlkorper to the same resolution as the higher-resolution Strahlkorper.

◆ read_surface_ylm()

template<typename Frame >

std::vector< ylm::Strahlkorper< Frame > > ylm::read_surface_ylm	(	const std::string &	file_name,
		const std::string &	surface_subfile_name,
		size_t	requested_number_of_times_from_end
	)

Returns a list of ylm::Strahlkorpers constructed from reading in spherical harmonic data for a surface at a requested list of times.

Details

The ylm::Strahlkorpers are constructed by reading in data from an H5 subfile that is expected to be in the format described by intrp::callbacks::ObserveSurfaceData. It is assumed that \(l_{max} = m_{max}\).

Parameters

file_name	name of the H5 file containing the surface's spherical harmonic data
surface_subfile_name	name of the subfile (with no leading slash nor the `.dat` extension) within `file_name` that contains the surface's spherical harmonic data to read in
requested_number_of_times_from_end	the number of times to read in starting backwards from the final time found in `surface_subfile_name`

◆ ricci_scalar() [1/2]

template<typename Frame >

Scalar< DataVector > gr::surfaces::ricci_scalar	(	const tnsr::ii< DataVector, 3, Frame > &	spatial_ricci_tensor,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const tnsr::ii< DataVector, 3, Frame > &	extrinsic_curvature,
		const tnsr::II< DataVector, 3, Frame > &	upper_spatial_metric
	)

Intrinsic Ricci scalar of a 2D Strahlkorper.

Details

Implements Eq. (D.51) of Sean Carroll's Spacetime and Geometry textbook (except correcting sign errors: both extrinsic curvature terms are off by a minus sign in Carroll's text but correct in Carroll's errata). \( \hat{R}=R - 2 R_{ij} S^i S^j + K^2-K^{ij}K_{ij}.\) Here \(\hat{R}\) is the intrinsic Ricci scalar curvature of the Strahlkorper, \(R\) and \(R_{ij}\) are the Ricci scalar and Ricci tensor of the 3D space that contains the Strahlkorper, \( K_{ij} \) the output of gr::surfaces::extrinsic_curvature, \( K \) is the trace of \(K_{ij}\), and unit_normal_vector is \(S^i = g^{ij} S_j\) where \(S_j\) is the unit normal one form.

◆ ricci_scalar() [2/2]

template<typename Frame >

void gr::surfaces::ricci_scalar	(	gsl::not_null< Scalar< DataVector > * >	result,
		const tnsr::ii< DataVector, 3, Frame > &	spatial_ricci_tensor,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const tnsr::ii< DataVector, 3, Frame > &	extrinsic_curvature,
		const tnsr::II< DataVector, 3, Frame > &	upper_spatial_metric
	)

Intrinsic Ricci scalar of a 2D Strahlkorper.

Details

Implements Eq. (D.51) of Sean Carroll's Spacetime and Geometry textbook (except correcting sign errors: both extrinsic curvature terms are off by a minus sign in Carroll's text but correct in Carroll's errata). \( \hat{R}=R - 2 R_{ij} S^i S^j + K^2-K^{ij}K_{ij}.\) Here \(\hat{R}\) is the intrinsic Ricci scalar curvature of the Strahlkorper, \(R\) and \(R_{ij}\) are the Ricci scalar and Ricci tensor of the 3D space that contains the Strahlkorper, \( K_{ij} \) the output of gr::surfaces::extrinsic_curvature, \( K \) is the trace of \(K_{ij}\), and unit_normal_vector is \(S^i = g^{ij} S_j\) where \(S_j\) is the unit normal one form.

◆ spin_function() [1/2]

template<typename Frame >

Scalar< DataVector > gr::surfaces::spin_function	(	const ylm::Tags::aliases::Jacobian< Frame > &	tangents,
		const ylm::Strahlkorper< Frame > &	strahlkorper,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const Scalar< DataVector > &	area_element,
		const tnsr::ii< DataVector, 3, Frame > &	extrinsic_curvature
	)

Spin function of a 2D Strahlkorper.

Details

See Eqs. (2) and (10) of [142]. This function computes the "spin function," which is an ingredient for horizon surface integrals that measure quasilocal spin. This function is proportional to the imaginary part of the horizon's complex scalar curvature. For Kerr black holes, the spin function is proportional to the horizon vorticity. It is also useful for visualizing the direction of a black hole's spin. Specifically, this function computes \(\Omega = \epsilon^{AB}\nabla_A\omega_B\), where capital indices index the tangent bundle of the surface and where \(\omega_\mu=(K_{\rho\nu}-K g_{\rho\nu})h_\mu^\rho s^\nu\) is the curl of the angular momentum density of the surface, \(h^\rho_\mu = \delta_\mu^\rho + u_\mu u^\rho - s_\mu s^\rho\) is the projector tangent to the 2-surface, \(g_{\rho\nu} = \psi_{\rho\nu} + u_\rho u_\nu\) is the spatial metric of the spatial slice, \(u^\rho\) is the unit normal to the spatial slice, and \(s^\nu\) is the unit normal vector to the surface. Because the tangent basis vectors \(e_A^\mu\) are orthogonal to both \(u^\mu\) and \(s^\mu\), it is straightforward to show that \(\Omega = \epsilon^{AB} \nabla_A K_{B\mu}s^\mu\). This function uses the tangent vectors of the Strahlkorper to compute \(K_{B\mu}s^\mu\) and then numerically computes the components of its gradient. The argument area_element can be computed via gr::surfaces::area_element. The argument unit_normal_vector can be found by raising the index of the one-form returned by gr::surfaces::unit_normal_oneform. The argument tangents is a Tangents that can be obtained from the StrahlkorperDataBox using the ylm::Tags::Tangents tag.

◆ spin_function() [2/2]

template<typename Frame >

void gr::surfaces::spin_function	(	gsl::not_null< Scalar< DataVector > * >	result,
		const ylm::Tags::aliases::Jacobian< Frame > &	tangents,
		const ylm::Strahlkorper< Frame > &	strahlkorper,
		const tnsr::I< DataVector, 3, Frame > &	unit_normal_vector,
		const Scalar< DataVector > &	area_element,
		const tnsr::ii< DataVector, 3, Frame > &	extrinsic_curvature
	)

Spin function of a 2D Strahlkorper.

Details

See Eqs. (2) and (10) of [142]. This function computes the "spin function," which is an ingredient for horizon surface integrals that measure quasilocal spin. This function is proportional to the imaginary part of the horizon's complex scalar curvature. For Kerr black holes, the spin function is proportional to the horizon vorticity. It is also useful for visualizing the direction of a black hole's spin. Specifically, this function computes \(\Omega = \epsilon^{AB}\nabla_A\omega_B\), where capital indices index the tangent bundle of the surface and where \(\omega_\mu=(K_{\rho\nu}-K g_{\rho\nu})h_\mu^\rho s^\nu\) is the curl of the angular momentum density of the surface, \(h^\rho_\mu = \delta_\mu^\rho + u_\mu u^\rho - s_\mu s^\rho\) is the projector tangent to the 2-surface, \(g_{\rho\nu} = \psi_{\rho\nu} + u_\rho u_\nu\) is the spatial metric of the spatial slice, \(u^\rho\) is the unit normal to the spatial slice, and \(s^\nu\) is the unit normal vector to the surface. Because the tangent basis vectors \(e_A^\mu\) are orthogonal to both \(u^\mu\) and \(s^\mu\), it is straightforward to show that \(\Omega = \epsilon^{AB} \nabla_A K_{B\mu}s^\mu\). This function uses the tangent vectors of the Strahlkorper to compute \(K_{B\mu}s^\mu\) and then numerically computes the components of its gradient. The argument area_element can be computed via gr::surfaces::area_element. The argument unit_normal_vector can be found by raising the index of the one-form returned by gr::surfaces::unit_normal_oneform. The argument tangents is a Tangents that can be obtained from the StrahlkorperDataBox using the ylm::Tags::Tangents tag.

◆ spin_vector()

template<typename MetricDataFrame , typename MeasurementFrame >

void gr::surfaces::spin_vector	(	const gsl::not_null< std::array< double, 3 > * >	result,
		double	spin_magnitude,
		const Scalar< DataVector > &	area_element,
		const Scalar< DataVector > &	ricci_scalar,
		const Scalar< DataVector > &	spin_function,
		const ylm::Strahlkorper< MetricDataFrame > &	strahlkorper,
		const tnsr::I< DataVector, 3, MeasurementFrame > &	measurement_frame_coords
	)

Spin vector of a 2D Strahlkorper.

Details

Computes the spin vector of a Strahlkorper in a MeasurementFrame, such as Frame::Inertial. The result is a std::array<double, 3> containing the Cartesian components (in MeasurementFrame) of the spin vector whose magnitude is spin_magnitude. spin_vector will return the dimensionless spin components if spin_magnitude is the dimensionless spin magnitude, and it will return the dimensionful spin components if spin_magnitude is the dimensionful spin magnitude. The spin vector is given by a surface integral over the horizon \(\mathcal{H}\) [Eq. (25) of [142]]: \(S^i = \frac{S}{N} \oint_\mathcal{H} dA \Omega (x^i - x^i_0 - x^i_R) \), where \(S\) is the spin magnitude, \(N\) is a normalization factor enforcing \(\delta_{ij}S^iS^j = S\), \(dA\) is the area element (via gr::surfaces::area_element), \(\Omega\) is the "spin function" (via gr::surfaces::spin_function), \(x^i\) are the MeasurementFrame coordinates of points on the Strahlkorper, \(x^i_0\) are the MeasurementFrame coordinates of the center of the Strahlkorper, \(x^i_R = \frac{1}{8\pi}\oint_\mathcal{H} dA (x^i - x^i_0) R \), and \(R\) is the intrinsic Ricci scalar of the Strahlkorper (via gr::surfaces::ricci_scalar). Note that measuring positions on the horizon relative to \(x^i_0 + x^i_R\) instead of \(x^i_0\) ensures that the mass dipole moment vanishes.

Parameters

result	The computed spin vector in `MeasurementFrame`.
spin_magnitude	The spin magnitude.
area_element	The area element on `strahlkorper`'s collocation points.
ricci_scalar	The intrinsic ricci scalar on `strahlkorper`'s collocation points.
spin_function	The spin function on `strahlkorper`'s collocation points.
strahlkorper	The Strahlkorper in the `MetricDataFrame` frame.
measurement_frame_coords	The Cartesian coordinates of `strahlkorper`'s collocation points, mapped to `MeasurementFrame`.

Note that spin_vector uses two frames: the Strahlkorper and all of the metric quantities are in MetricDataFrame and are used for doing integrals, but the measurement_frame_coordinates are in MeasurementFrame and are used for making sure the result is in the appropriate frame. The two frames MeasurementFrame and MetricDataFrame may or may not be the same. In principle, spin_vector could be written using only a single frame (MeasurementFrame) but that would require that the metric quantities are known on the collocation points of a Strahlkorper in MeasurementFrame, which would involve more interpolation.

◆ surface_integral_of_scalar()

template<typename Frame >

double gr::surfaces::surface_integral_of_scalar	(	const Scalar< DataVector > &	area_element,
		const Scalar< DataVector > &	scalar,
		const ylm::Strahlkorper< Frame > &	strahlkorper
	)

Surface integral of a scalar on a 2D Strahlkorper

Details

Computes the surface integral \(\oint dA f\) for a scalar \(f\) on a Strahlkorper with area element \(dA\). The area element can be computed via gr::surfaces::area_element().

◆ unit_normal_one_form() [1/2]

template<typename Frame >

tnsr::i< DataVector, 3, Frame > gr::surfaces::unit_normal_one_form	(	const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const DataVector &	one_over_one_form_magnitude
	)

Computes normalized unit normal one-form to a Strahlkorper.

Details

The input argument normal_one_form \(n_i\) is the unnormalized surface one-form; it depends on a Strahlkorper but not on a metric. The input argument one_over_one_form_magnitude is \(1/\sqrt{g^{ij}n_i n_j}\), which can be computed using (one over) the magnitude function.

◆ unit_normal_one_form() [2/2]

template<typename Frame >

void gr::surfaces::unit_normal_one_form	(	gsl::not_null< tnsr::i< DataVector, 3, Frame > * >	result,
		const tnsr::i< DataVector, 3, Frame > &	normal_one_form,
		const DataVector &	one_over_one_form_magnitude
	)

Computes normalized unit normal one-form to a Strahlkorper.

Details

The input argument normal_one_form \(n_i\) is the unnormalized surface one-form; it depends on a Strahlkorper but not on a metric. The input argument one_over_one_form_magnitude is \(1/\sqrt{g^{ij}n_i n_j}\), which can be computed using (one over) the magnitude function.

Namespaces

Classes

Functions

Detailed Description

Function Documentation

◆ area_element() [1/2]

Details

◆ area_element() [2/2]

Details

◆ christodoulou_mass()

Details

◆ dimensionful_spin_magnitude() [1/2]

Details

◆ dimensionful_spin_magnitude() [2/2]

Details

◆ dimensionless_spin_magnitude() [1/2]

Details

◆ dimensionless_spin_magnitude() [2/2]

Details

◆ euclidean_area_element() [1/2]

Details

◆ euclidean_area_element() [2/2]

Details

◆ euclidean_surface_integral_of_vector()

Details

◆ expansion() [1/2]

Details

◆ expansion() [2/2]

Details

◆ extrinsic_curvature() [1/2]

Details

◆ extrinsic_curvature() [2/2]

Details

◆ find_radial_surface()

Details

◆ grad_unit_normal_one_form() [1/2]

Details

◆ grad_unit_normal_one_form() [2/2]

Details

◆ inverse_surface_metric() [1/2]

Details

◆ inverse_surface_metric() [2/2]

Details

◆ irreducible_mass()

Details

◆ radial_distance()

Details

◆ read_surface_ylm()

Details

◆ ricci_scalar() [1/2]

Details

◆ ricci_scalar() [2/2]

Details

◆ spin_function() [1/2]

Details

◆ spin_function() [2/2]

Details

◆ spin_vector()

Details

◆ surface_integral_of_scalar()

Details

◆ unit_normal_one_form() [1/2]

Details

◆ unit_normal_one_form() [2/2]

Details