xx KadathImporter

KadathImporter

Samuel Tootle <tootle@itp.uni-frankfurt.de>

February 19, 2023

Abstract

This thorn enables the use of initial data solutions computed using the Frankfurt University/KADATH (FUKA) initial data codes

1 Introduction

Accurate time evolution of systems within general relativity require accurate initial data solutions at some initial time-slice. For isolated objects in equilibrium, these solutions can be computed easily either analytically or using efficient 1-2D solvers. Conversely, initial data for binary configurations is considerably more challenging to construct and, as such, has seen considerably fewer codes dedicated to solving this problem especially for mass asymmetric and spinning configurations.

Frankfurt University/KADATH (FUKA) is a collection of initial data codes that are focused on providing a robust suite of solvers capable of computing precise initial data solutions for binary configurations including a black hole or neutron stars. This is currently limited to classical general relativity and with a strict z-symmetry so that component spins can only be (anti-)aligned with the orbital axis. Furthermore, initial data involving neutron stars can be computed using either tabulated equations of state or polytropic. Details of the initial data solvers can be found in the publication[1].

This thorn provides a minimal interface to FUKA’s builtin export routines in order to interpolate an initial data solution generated with FUKA into the EinsteinToolkit. Initial data must be generated independently by a separately compiled version of FUKA. The latest development version can be found under the fuka branch at [2].

2 Using This Thorn

This thorn requires the KadathThorn which handles the (possibly) building and linking of the FUKA library when creating the EinsteinToolkit executable. The FUKA library currently requires a compiler that supports C++17 standards and std::filesystem. However, the library can be compiled separately from the EinsteinToolkit and linked by setting

xxxxKADATH_DIRx=x${HOME_KADATH}

in the build configuration file. Here HOMExKADATHx is a global environment variable which the user should have already set during the installation of FUKA. When linking against a pre-compiled version of FUKA, the ETK can be compiled with a lower C++ standard since FUKA is linked via a statically compiled library.

Note: Linking a previously compiled version of FUKA when building the EinsteinToolkit has been known to provide undefined behavior with the intel MKL library. Specifically, imported solutions will results in garbage for all quantities (e.g. the lapse). FUKA works exceptionally well with MKL, but an ABI issue has been encountered on multiple occasions which has been tied to the order of linking scientific libraries. In the case of intel oneapi, ”-mkl” should appear at the end of the LDFLAGS. If you encounter and resolve such an error, please submit an issue ticket so it can be documented.

2.1 Obtaining This Thorn

This thorn can be obtained from [3]

2.2 Basic Usage

FUKA initial data solutions consist of two files: a configuration file (config) and a data file (dat). In the case of neutron stars, the solution also needs the equation of state file that describes the table or polytropic configuration.

After activating the KadathImporter thorn, one needs to set KadathImporter::filename to the config file, e.g.

xxxxKadathImporter::filenamex=x"<dir>/id.info"

In the ficticious dir, we must ensure the config, dat, and possible EOS files are stored in the same place. Additionally, FUKA will also check for the desired EOS in

xxxx${HOME_KADATH}/eos

However, this requires the HOMExKADATHx environment variable being set in the evolution environment. If FUKA is built during the ETK build procedure, the directory that should be assigned to HOMExKADATHx is listed in the output.

In addition to the filename, the initial data type must also be set such as

xxxxKadathImporter::typex=x"BNS"

where possible types are

xxxxSTRINGxtypex"IDxtype"
xxxx{
xxxx"BBH"x::x"BlackxholexID"
xxxx"BH"xx::x"BinaryxblackxholexID"
xxxx"BNS"x::x"BinaryxneutronxstarxID"
xxxx"NS"xx::x"NeutronxstarxID"
xxxx"BHNS"x::x"BlackxHolexneutronxstarxID"
xxxx}x"BBH"

Excision filling parameters

FUKA computes black hole solutions by excising the interior of the black hole, where the excision surface is defined as an apparent horizon. However, for puncture evolution the interior needs to be filled with smooth junk data. To do so, the FUKA exporter performs 3rd to 7th order Lagrange interpolation on radially equi-spaced grid points outside of the excision region. The interpolated solution is then extrapolated to the requested grid point inside the horizon.

Although the default parameters for filling the excision region have been tuned to be optimal, these settings can be modified by the user in the parfile:

xxxxCCTK_INTxinterp_orderx"Interpolationxorderxforxsmoothxjunk"
xxxx{
xxxxxx3x::x"Parabolic"
xxxxxx5x::x"Quartic"
xxxxxx7x::x"6thxorderxpolynomial"
xxxxxx8x::x"7thxorderxpolynomial"
xxxx}8
xxxxCCTK_REALxinterpolation_offsetx"Interpolationxoffsetx(inxunitsxofxr_AH)"
xxxx{
xxxxxx-1:*x::x"Anythingxgoes"
xxxx}0.
xxxxCCTK_REALxdelta_r_relx"Relativexdrxspacingxforxthexinterpolationxpolynomial"
xxxx{
xxxxxx-1:*x::x"Anythingxgoes"
xxxx}0.3
xxxxBOOLEANxpuncture_lapsex"Setxaxpuncturexlapsexalpx=xpsi^-2xinsidexthexhole"
xxxx{
xxxx}no

3 In the background

This importer interfaces with the initial data exporters that are built into the FUKA library which is where all the actual “work” is done. The source code for these can be found in

xxxx$HOME_KADATH/src/Utilities/Exporters

These exporters provide a simple API to allow one to easily integrate FUKA initial data into a new evolution code. In this way, the KadathImporter passes the filename of the initial data along with vectors of points in which to interpolate the initial data solution on. In return the exporter passes back a vector consisting of the necessary ADMBase and HydroBase quantities, specifically

Shift - beta = 0

Physical 3-Metric -

Extrinsic curvature -

Density -

Internal energy -

Contravariant eulerian fluid 3 velocity -

Note: FUKA initial data involving neutron stars uses cold equations of state. It has no knowledge of temperature or electron fraction. These must be set by another thorn! For an example, see the KadathPizza thorn[3] where these quantities are initialized after initial data import, but before the FreeTHC initial data converter.

3.1 Interaction With Other Thorns The KadathImporter extends the ADMBase and HydroBase thorns to allow for setting ADMBase and HydroBase variables.

To import metric quantities from an initial data solution, the following ADMBase variables need to be set to Kadath:

initialxdata

initialxlapse

initialxshift

initialxdtlapse (can be set to Kadath, none, or zero)

initialxdtshift (can be set to Kadath, none, or zero)

It is important to note that on import

The shift () is always set to zero such that the shift is recomputed by the evolution thorn within the evolution gauge using the extrinsic curvature.

For binary initial data: the coordinates are shifted such that the carpet coordinate (0,0,0) corresponds to the computed center of mass of the binary

In the case of initial data involving a neutron star, HydroBase::initialxhydro must be set to Kadath too.

3.2 Examples

A short test for verifying the importer interface is working is available in the test directory. Examples for a BBH and neutron star are available in the par directory 3.3 Support and Feedback The current active developer and maintainer is

xxxxSamuelxTootlex-xtootle@itp.uni-frankfurt.de

4 History

The pre-ETK inclusion KadathThorn and KadathImporter thorns were developed by L. Jens Papenfort, Samuel Tootle, and Elias Most for binary black hole and binary neutron star initial data. Samuel Tootle later rewrote the thorns to encapsulate all initial data available from FUKA, updated to meet ETK inclusion standards, and wrote the documentation.

4.1 Acknowledgements

The authors are grateful to the continued support by Philippe Grandclement, author of the KADATH spectral library, throughout the development of the FUKA codes.

References

[1]xxx”Papenfort, L. Jens et al”, New public code for initial data of unequal-mass, spinning compact-object binaries, ”10.1103/PhysRevD.104.024057”

[2]xxxFrankfurt University/KADATH (codes), ”https://bitbucket.org/fukaws/fuka” [3]xxxFrankfurt University/KADATH (workspace), ”https://bitbucket.org/fukaws/”

5 Parameters

11 deltaxrxrel 10 Scope: private01 REAL

11 Description: Relative dr spacing for the interpolation polynomial

11 Range 10 01 Default: 0.3
11 -1:*  10 Anything goes

11

11 filename  10 Scope: private01  STRING

11 Description: Input config file name

11  Range  10              01  Default: (none)

11                  10

11

11 interpxorder  10 Scope: private01  INT

11 Description: Interpolation order for smooth junk

11 Range 10 01 Default: 8
11 3  10 Parabolic
11 5  10 Quartic
11 7  10 6th order polynomial
11 8  10 7th order polynomial

11

11 interpolationxoffset10 Scope: private01  REAL

11 Description: Interpolation offset (in units of rxAH)

11 Range 10 01 Default: 0.
11 -1:*  10 Anything goes

11

11 puncturexlapse 10 Scope: private01  BOOLEAN

11 Description: Set a puncture lapse alp = psiˆ- 2 inside the hole

11                  10              01  Default: no

11 type  10 Scope: restricted01  STRING

11 Description: ID type

11 Range 10 01 Default: BBH
11 BBH  10 Black hole ID
11 BH  10 Binary black hole ID
11 BNS  10 Binary neutron star ID
11 NS  10 Neutron star ID
11 BHNS  10 Black Hole neutron star ID

11

11 initialxhydro  10 Scope: shared from HYDROBASE01  KEYWORD

11 Extends ranges:

11 Kadath  10 Kadath Initial Data

11

6 Interfaces

General Implements: kadathimporter

Inherits: grid admbase hydrobase

7 Schedule This section lists all the variables which are assigned storage by thorn Fuka/KadathImporter. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

Storage NONE

Scheduled Functions

CCTKxPARAMCHECK (conditional) x kadathimporterxcheckxparameters x check parameters x

11 x 11 Language: 11 c
11 x 11 Type:  11 function

11

ADMBasexInitialData (conditional) x kadathimporter x set up binary black hole initial data x

11 x 11 Language: 11 c
11 x 11 Type:  11 function

11

ADMBasexInitialData (conditional) x kadathimporter x set up black hole initial data x

11 x 11 Language: 11 c
11 x 11 Type:  11 function

11

HydroBasexInitial (conditional) x kadathimporter x set up binary neutron star initial data x

11 x 11 Before: 11 admbasexpostinitial
11 x 11 Language: 11 c
11 x 11 Type:  11 function

11

HydroBasexInitial (conditional) x kadathimporter x set up neutron star initial data x

11 x 11 Before: 11 admbasexpostinitial
11 x 11 Language: 11 c
11 x 11 Type:  11 function

HydroBasexInitial (conditional) x kadathimporter x set up black hole neutron star initial data x

11 x 11 Before: 11 admbasexpostinitial
11 x 11 Language: 11 c
11 x 11 Type:  11 function