metrics.cu

This section contains functions defined in the metrics.cu file related to spacetime metric calculations.

Macros

Defines

FIND_GCON_MATRIX_INV (0)

Macro to enable or disable the computation of the inverse metric using LU decomposition.

if set to 1, the code will compute the inverse metric \( g^{\mu\nu} \) through LU decomposition and substitution. if set to 0, the code will use the kerr analytical expressions for the inverse metric.

Functions

Functions

__host__ double gdet_func(double gcov[][NDIM])

Calculates the square root of the absolute determinant of the metric tensor, \( \sqrt{-g} \).

  • General Case: Uses GSL-based LU decomposition to compute the determinant of the covariant metric \( g_{\mu\nu} \).

  • Simplified Case: If SPHERE_TEST is defined, it assumes a diagonal metric for faster computation.

Parameters:

gcov – The covariant metric tensor \( g_{\mu\nu} \).

Returns:

The value of \( \sqrt{| \det(g_{\mu\nu}) |} \).

__host__ __device__ int LU_decompose(double A[][NDIM], int permute[])

Performs in-place LU decomposition with partial pivoting and row-wise normalization.

  • This function factorizes a square matrix \( A \) into a lower triangular matrix \( L \) and an upper triangular matrix \( U \) such that \( PA = LU \). Then it can be used to solve linear systems or invert matrices.

Parameters:

  • A – The \( \rm{NDIM} \times \rm{NDIM} \) matrix to decompose (modified in-place).

  • permute – Array to store the row permutation indices (pivoting history).

Returns:

Returns 0 for success, 1 if the matrix is singular.

__host__ __device__ void LU_substitution(double A[][NDIM], double B[], int permute[])

Solves a linear system \( Ax = B \) using forward and backward substitution.

  • This function takes the results of LU_decompose (an in-place LU matrix and a permutation vector) and solves for the vector \( B \). It is primarily used in the simulation to invert the metric tensor \( g_{\mu\nu} \) to find its contravariant form \( g^{\mu\nu} \).

  • Permutation: Swaps elements of \( B \) to match the partial pivoting order recorded in permute.

  • Forward Substitution: Solves the lower triangular system \( Ly = Pb \). Since the diagonal elements of \( L \) are implicitly 1, no division is required.

  • Backward Substitution: Solves the upper triangular system \( Ux = y \), utilizing the diagonal elements of \( U \) stored in A[i][i].

Parameters:

  • A – The \( \rm{NDIM} \times \rm{NDIM} \) LU-decomposed matrix.

  • B – The right-hand side vector (replaced by the solution vector \( x \) in-place).

  • permute – The permutation array generated by LU_decompose.

Returns:

void

__host__ __device__ int invert_matrix(double Am[][NDIM], double Aminv[][NDIM])

Computes the inverse of a square matrix unifying the usage of LU decomposition and substitution.

This function calculates the inverse of an \( NDIM \times NDIM \) matrix (typically the covariant metric \( g_{\mu\nu} \) to obtain the contravariant metric \( g^{\mu\nu} \)). It solves the matrix equation \( A \cdot A^{-1} = I \) by treating each column of the identity matrix \( I \) as a separate linear system.

Parameters:

  • Am – The input \( NDIM \times NDIM \) matrix to be inverted.

  • Aminv – The output matrix where the calculated inverse is stored.

Returns:

0 for success; 1 if the matrix is singular or contains invalid values.

__host__ __device__ void gcon_func(const double X[4], double gcov[][NDIM], double gcon[][NDIM])

Computes the contravariant metric tensor \( g^{\mu\nu} \) using either numerical inversion or analytical expressions.

  • This function provides the inverse of the metric tensor at a specific 4-position \( X^\mu \). It supports a toggle between a general-purpose numerical solver and optimized analytical formulas for specific spacetimes.

if FIND_GCON_MATRIX_INV is defined:

  • Calls invert_matrix() to perform a full LU decomposition on \( g_{\mu\nu} \). This is the most flexible method and works for any metric, but is computationally more expensive.

Path B: Analytical/Hardcoded (Default):

  • SPHERE_TEST: Returns a simple diagonal inverse for flat space in spherical coordinates.

  • Modified Kerr-Schild (MKS): Computes exact contravariant components for a rotating Kerr black hole.

Parameters:

  • X – The 4-position \( X^\mu \) in code coordinates.

  • gcov – The covariant metric tensor \( g_{\mu\nu} \) (used for numerical inversion or diagonal tests).

  • gcon – Output: The calculated contravariant metric tensor \( g^{\mu\nu} \).

Returns:

void

__device__ void get_connection(const double X[4], double lconn[4][4][4])

Computes the Christoffel symbols (connection coefficients) \( \Gamma^i_{jk} \) at a given 4-position.

Analytically: Computed analytically if SPHERE_TEST is not defined.

Numerically: Computed through Finite Differences if SPHERE_TEST is defined.

Parameters:

  • X – 4-position \( X^\mu \) in code coordinates.

  • lconn – A 3D array [4][4][4] populated with the connection coefficients.

Returns:

void

__host__ __device__ void lower(double *ucon, const double Gcov[NDIM][NDIM], double *ucov)

Lowers the index of a contravariant 4-vector to its covariant form.

  • This function performs the metric mapping \( u_\mu = g_{\mu\nu} u^\nu \). It effectively transforms a vector from the tangent space to the cotangent space (one-form) using the local covariant metric tensor.

Parameters:

  • ucon – Input contravariant 4-vector \( u^\nu \).

  • Gcov – Input covariant metric tensor \( g_{\mu\nu} \).

  • ucov – Output covariant 4-vector \( u_\mu \).

Returns:

void