Numerical Relativity

Introduction

AthenaK includes a Z4c numerical relativity module for evolving dynamical spacetimes. This page describes how to enable the Z4c solver and run a binary black hole (BBH) problem. For GRMHD in dynamical spacetimes, see GRMHD in Dynamical Spacetimes.

For details on the Z4c formalism as used in AthenaK, please refer to arXiv:2101.08289 and arXiv:2409.10383. The description is quite lengthy, so it will not be included here.

Enabling the Z4c solver

To enable Z4c, add a <z4c> block to the input file. <z4c> currently takes the following parameters to control the Z4c equations:

  • chi_psi_power: Sets the exponent in \(\psi^4 = \chi^{4/p}\) (default: -4)

  • chi_div_floor: Minimum value of \(\chi\) allowed inside division (default: -1000.0))

  • chi_min_floor: Minimum value of \(\chi\) when floor_chi is enabled (default: 1e-12)

  • floor_chi: Force \(\chi\) to stay above chi_min_floor (default: false)

  • diss: Strength of Kreiss-Oliger dissipation (default: 0.0)

  • damp_kappa1: Constraint-damping parameter \(\kappa_1\) (default: 0.0)

  • damp_kappa2: Constraint-damping parameter \(\kappa_2\) (default: 0.0)

  • use_z4c: Whether or not to use Z4c; setting this to false forces \(\Theta = 0\), which effectively reduces the equations to the BSSN system instead (default: true)

The following parameters control the standard lapse condition:

  • lapse_harmonicf: Enables the \(\alpha\) term (default: 1.0)

  • lapse_harmonic: Enable the \(\alpha^2\) term (default: 0.0)

  • lapse_oplog: Controls the weight of the \(\alpha\) term (default: 2.0)

  • lapse_advect: Enable the advection/Lie derivative term (default: 1.0)

AthenaK also supports a slow-start lapse (see arXiv:2404.01137) controlled with the following parameters:

  • slow_start_lapse: Enable SSL (default: false)

  • ssl_damping_amp: The strength of the gauge-damping (default: 0.6)

  • ssl_damping_time: The characteristic decay time for the gauge-damping (default: 20.0)

  • ssl_damping_index: The power scaling for the \(W = \chi^{1/2}\) factor (default: 1.0)

The shift gauge contains both gamma-driver and harmonic gauge terms. The gamma-driver terms are enabled by default. The parameters are as follows:

  • shift_Gamma: Enable the \(\Gamma^i\) term (default: 1.0)

  • shift_advect: Enable the advection/Lie derivative term (default: 1.0)

  • shift_eta: Coefficient for decay term (default: 2.0)

  • shift_alpha2Gamma: Enable the \(\alpha^2 \Gamma^i\) harmonic gauge term (default: 0.0)

  • shift_H: Enable the \(\alpha\chi\left(\alpha\partial_i \chi/2 - \partial_i \alpha\right)\tilde{\gamma}^{ij}\) harmonic gauge term (default: 0.0)

There are also the following miscellaneous parameters:

  • user_Sbc: Whether or not custom user boundaries should use a Sommerfeld condition (default: false)

  • excise_chi: Excise regions where \(\chi\) falls below this in the history output. This is useful for excluding punctures, which tend to dominate errors in the solution, from constraint violation calculations. (default: 0.0625)

  • extrap_order: The extrapolation order used for outflow boundaries (can be set to 2 for linear , 3 for quadratic, and 4 for cubic extrapolation, default: 2)

Wave extraction

AthenaK can compute the Weyl scalar \(\Psi_4\), which encodes the outgoing gravitational radiation, over spherical surfaces at finite radii. This can then be used to compute the gravitational wave strain in post-processing. Waveform extraction is controlled by the following parameters:

  • nrad_wave_extraction: The number of extraction surfaces. Setting to 0 disables wave extraction (default: 0)

  • extraction_nlev: The subdivision level for the spherical surfaces used to compute \(\Psi_4\) (default: 10)

  • extraction_radius_?: The extraction radius for surface ? (zero-indexed) (default: 10)

  • waveform_dt: The time between waveform outputs in code units (default: 1)

Alternatively, AthenaK can also write out the data needed for Cauchy-characteristic extraction (CCE) in the format expected by the SpECTRE CCE module.

Note

Instructions on performing CCE output are forthcoming.

Outputs

Z4c variables (included in output z4c):

  • \(\chi\): z4c_chi

  • \(\tilde{\gamma}_{ij}\): z4c_gxx, z4c_gxy, z4c_gxz, z4c_gyy, z4c_gyz, and z4c_gzz

  • \(\hat{K}\): z4c_Khat

  • \(\tilde{A}_{ij}\): z4c_Axx, Z4c_Axy, Z4c_Axz, Z4c_Ayy, Z4c_Ayz, Z4c_Azz

  • \(\tilde{\Gamma}^i\): z4c_Gamx, z4c_Gamy, z4c_Gamz

  • \(\Theta\): z4c_Theta

  • \(\alpha\): z4c_alpha

  • \(\beta^i\): z4c_betax, z4c_betay, and z4c_betaz

ADM constraints (included in output con):

  • \(\mathcal{C}^2\): con_C

  • \(\mathcal{H}\): con_H

  • \(\mathcal{M}_i\mathcal{M}^i\): con_M

  • \(\breve{Z}^i\breve{Z}_i\): con_Z

  • \(\mathcal{M}_i\): con_Mx, con_My, and con_Mz

The ADM variables (included in output adm):

  • \(g_{ij}\): adm_gxx, adm_gxy, adm_gxz, adm_gyy, adm_gyz, and adm_gzz

  • \(K_{ij}\): adm_Kxx, adm_Kxy, adm_Kxz, adm_Kyy, adm_Kyz, and adm_Kzz

  • \(\psi^4\): adm_psi4

The Weyl scalar (included in output weyl):

  • \(\mathrm{Re}(\Psi_4)\): weyl_rpsi4

  • \(\mathrm{Im}(\Psi_4)\): weyl_ipsi4

As discussed in GRMHD in Dynamical Spacetimes, the ADM variables can exist independently of Z4c. In this case, they will also include \(\alpha\) and \(\beta^i\).

The history output (jobname.z4c.user.hst) will output 2-norms of various constraints: \(||\mathrm{C}||_2\), \(||\mathrm{H}||_2\), \(||\sqrt{\mathcal{M}_i\mathcal{M}^i}||_2\), \(||\mathcal{M_i}||_2\), and \(||\Theta||_2\). The history output will also contain the total integrated spatial volume \(\int_\Omega \sqrt{\gamma} dx dy dz\).

Example: Single puncture black hole

The puncture problem initializes a Schwarzschild black hole in isotropic coordinates with a “pre-collapsed” lapse and allows it to evolve in the puncture gauge. After some initial gauge dynamics, it should relax to a steady-state. There is an included input file for a puncture problem in inputs/z4c/onepuncture/z4c_onepuncture.athinput that can be used.

1. Build. The single puncture problem is described by the pgen z4c/z4c_one_puncture.cpp:

cmake -DPROBLEM=z4c/z4c_one_puncture -B build
cmake --build build -j

  1. Input file. The provided input file should have the following parameters:

<z4c>
diss = 1    # Add Kreiss-Oliger dissipation

<problem>
punc_ADM_mass = 1.  # ADM mass of black hole

The resolution in this input file is insufficient and will cause the puncture to disintegrate. Let’s modify the input file to something more reasonable:

<mesh>
...
nx1 = 64
...
nx2 = 64
...
nx3 = 64
...

<meshblock>
nx1 = 16
nx2 = 16
nx3 = 16

<mesh_refinement>
refinement = static

# Add four levels of refinement around the region +/- 1
<refined_region1>
x1min = -1.0
x1max =  1.0
x2min = -1.0
x2max =  1.0
x3min = -1.0
x3max =  1.0
level = 4

<time>
...
nlim = -1
tlim = 1.0
...

...

<output3>
...
slice_x2 = 0
slice_x3 = 0

Note that we also change the time limit and the slice location for one of the outputs.

  1. Run and visualize

This should produce a simple plot of the lapse along the \(x\) axis like the following:

Single puncture lapse

Running binary black holes

Warning

This tutorial is deprecated.

AthenaK requires external modules to provide Cauchy initial data for the binary black hole problems. Currently, we can read in initial data from the TwoPunctures and SpECTRE codes. The TwoPunctures initial data is calculated on the fly at the start of the evolution, while SpECTRE initial data needs to be pre-computed. Below is a tutorial for evolving the TwoPunctures initial data.

TwoPunctures initial data

Two external libraries are required for building the z4c_two_puncture problem, namely GSL and the TwoPunctures initial data solver. GSL should be discoverable by CMake. TwoPunctures needs to be compiled and linked separately. Because many external initial data libraries do not have CMake linkages, the preferred method in AthenaK for linking most of these libraries is by cloning and compiling the library separately, then providing a symbolic link to the library’s base directory directly in the AthenaK base directory. For TwoPunctures, this looks like the following:

cd $HOME && cd usr
git clone https://github.com/computationalrelativity/TwoPuncturesC.git
cd TwoPuncturesC
make -j8

# link twopuncturesc into athenak
ln -s $HOME/usr/TwoPuncturesC ${path_to_athenak}

Now create a build directory, then configure and build AthenaK with CMake:

mkdir build_z4c_twopunc && cd build_z4c_twopunc
cmake ../ -DPROBLEM=z4c/two_punctures/z4c_two_puncture

Note

A tutorial for using SpECTRE initial data is forthcoming.