Detailed Description

Routines to generate black hole ringdown waveforms.

Author: Jolien Creighton

These routines generate black hole quasinormal modes, spin-weighted spheroidal harmonics, and ringdown gravitational waveforms.

Low-Level Routines
Attention The variables are represented in Leaver's conventions in which G = c = 2M = 1. In particular this means, \|a\| < 0.5.
int	XLALSimBlackHoleRingdownModeEigenvaluesLeaver (COMPLEX16 A, COMPLEX16 omega, double a, int l, int m, int s)
	Low-level routine that computes the black hole quasinormal mode eigenefrequency, omega, and angular separation constant A for a given (l,m) mode and spin-weight s (s=-2 for gravitational perturbations). More...

COMPLEX16	XLALSimBlackHoleRingdownSpheroidalWaveFunctionLeaver (double mu, double a, int l, int m, int s, COMPLEX16 A, COMPLEX16 omega)
	Low-level routine that evaluates the spheroidal wave function at a specified value of mu = cos(theta) for a given (l,m) mode and spin-weight s (s=-2 for gravitational perturbations). More...

High-Level Routines
int	XLALSimBlackHoleRingdownMode (double frequency, double quality, double mass, double dimensionless_spin, int l, int m, int s)
	Computes the frequency and quality factor of a specified quasinormal mode (l,m) of spin weight s perturbations (s=-2 for gravitational perturbations) of a black hole of a specified mass and spin. More...

COMPLEX16	XLALSimBlackHoleRingdownSpheroidalWaveFunction (double theta, double dimensionless_spin, int l, int m, int s)
	Evaluates the value of spheroidal wave function at a given polar angle theta for a specified mode (l,m) and spin weight s (s=-2 for gravitational perturbations) and dimensionless spin parameter. More...

int	XLALSimBlackHoleRingdown (REAL8TimeSeries hplus, REAL8TimeSeries hcross, const LIGOTimeGPS *t0, double phi0, double deltaT, double mass, double dimensionless_spin, double fractional_mass_loss, double distance, double inclination, int l, int m)
	Computes the waveform for the ringdown of a black hole quasinormal mode (l,m). More...

REAL8	XLALSimRadiusKerrISCO (REAL8 a)

REAL8	XLALSimEnergyKerrISCO (REAL8 rISCO)

REAL8	XLALSimAngMomKerrISCO (REAL8 rISCO)

INT4	XLALSimIMREOBFinalMassSpin (REAL8 finalMass, REAL8 finalSpin, const REAL8 mass1, const REAL8 mass2, const REAL8 spin1[3], const REAL8 spin2[3], Approximant approximant)
	Computes the final mass and spin of the black hole resulting from merger. More...

INT4	XLALSimIMREOBGenerateQNMFreqV2 (COMPLEX16Vector *modefreqs, const REAL8 mass1, const REAL8 mass2, const REAL8 spin1[3], const REAL8 spin2[3], UINT4 l, INT4 m, UINT4 nmodes, Approximant approximant)
	These functions generate the quasinormal mode frequencies for a black hole ringdown. More...

INT4	XLALSimIMREOBGenerateQNMFreqV2fromFinal (COMPLEX16Vector *modefreqs, const REAL8 finalMass, const REAL8 finalSpin, UINT4 l, INT4 m, UINT4 nmodes)

Function Documentation

◆ XLALSimBlackHoleRingdownModeEigenvaluesLeaver()

int XLALSimBlackHoleRingdownModeEigenvaluesLeaver	(	COMPLEX16 *	A,
		COMPLEX16 *	omega,
		double	a,
		int	l,
		int	m,
		int	s
	)

Low-level routine that computes the black hole quasinormal mode eigenefrequency, omega, and angular separation constant A for a given (l,m) mode and spin-weight s (s=-2 for gravitational perturbations).

Implements Leaver's method by simultaneously solving the continued fraction equations Eq. (21) and Eq. (27) of Leaver (1985): E. W. Leaver "An analyitic representation for the quasi-normal modes of Kerr black holes", Proc. R. Soc. Lond. A 402 285-298 (1985).

Attention: The variables are represented in Leaver's conventions in which G = c = 2M = 1. In particular this means, |a| < 0.5.

Todo:: Extend so that overtones can be computed too.

Parameters

A	angular separation constant [returned]
omega	eigenfrequency [returned]
a	spin parameter (note: \|a\| < 0.5)
l	mode value l
m	mode value m
s	spin weight (s = -2 for gravitational perturbations)

Definition at line 434 of file LALSimBlackHoleRingdown.c.

◆ XLALSimBlackHoleRingdownSpheroidalWaveFunctionLeaver()

COMPLEX16 XLALSimBlackHoleRingdownSpheroidalWaveFunctionLeaver	(	double	mu,
		double	a,
		int	l,
		int	m,
		int	s,
		COMPLEX16	A,
		COMPLEX16	omega
	)

Low-level routine that evaluates the spheroidal wave function at a specified value of mu = cos(theta) for a given (l,m) mode and spin-weight s (s=-2 for gravitational perturbations).

Also requires the angular separation constant A and eigenvalue omega for that mode, which are calculated by the routine XLALSimBlackHoleRingdownModeEigenvaluesLeaver().

Implements Leaver's method by simultaneously solving the continued fraction equations Eq. (21) and Eq. (27) of Leaver (1985): E. W. Leaver "An analyitic representation for the quasi-normal modes of Kerr black holes", Proc. R. Soc. Lond. A 402 285-298 (1985).

Attention: The variables are represented in Leaver's conventions in which G = c = 2M = 1. In particular this means, |a| < 0.5.

Todo:: Extend so that overtones can be computed too.

Parameters

mu	cosine of polar angle
a	spin parameter (note: \|a\| < 0.5)
l	mode value l
m	mode value m
s	spin weight (s = -2 for gravitational perturbations)
A	angular separation constant
omega	eigenfrequency

Definition at line 503 of file LALSimBlackHoleRingdown.c.

◆ XLALSimBlackHoleRingdownMode()

int XLALSimBlackHoleRingdownMode	(	double *	frequency,
		double *	quality,
		double	mass,
		double	dimensionless_spin,
		int	l,
		int	m,
		int	s
	)

Computes the frequency and quality factor of a specified quasinormal mode (l,m) of spin weight s perturbations (s=-2 for gravitational perturbations) of a black hole of a specified mass and spin.

Uses the method of Leaver (1985): E. W. Leaver "An analyitic representation for the quasi-normal modes of Kerr black holes", Proc. R. Soc. Lond. A 402 285-298 (1985).

Note: The dimensionless spin assumes values between -1 and 1.

Todo:: Extend so that overtones can be computed too.

Parameters

frequency	mode frequency (Hz) [returned]
quality	mode quality factor [returned]
mass	black hole mass (kg)
dimensionless_spin	black hole dimensionless spin parameter (-1,+1)
l	polar mode number
m	azimuthal mode number
s	spin weight (s=-2 for gravitational radiation)

Definition at line 551 of file LALSimBlackHoleRingdown.c.

◆ XLALSimBlackHoleRingdownSpheroidalWaveFunction()

COMPLEX16 XLALSimBlackHoleRingdownSpheroidalWaveFunction	(	double	theta,
		double	dimensionless_spin,
		int	l,
		int	m,
		int	s
	)

Evaluates the value of spheroidal wave function at a given polar angle theta for a specified mode (l,m) and spin weight s (s=-2 for gravitational perturbations) and dimensionless spin parameter.

Uses the method of Leaver (1985): E. W. Leaver "An analyitic representation for the quasi-normal modes of Kerr black holes", Proc. R. Soc. Lond. A 402 285-298 (1985).

Note: The dimensionless spin assumes values between -1 and 1.

Todo:: Extend so that overtones can be computed too.

Parameters

theta	polar angle (radians)
dimensionless_spin	black hole dimensionless spin parameter
l	polar mode number
m	azimuthal mode number
s	spin weight (s=-2 for gravitational radiation)

Definition at line 585 of file LALSimBlackHoleRingdown.c.

◆ XLALSimBlackHoleRingdown()

int XLALSimBlackHoleRingdown	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		const LIGOTimeGPS *	t0,
		double	phi0,
		double	deltaT,
		double	mass,
		double	dimensionless_spin,
		double	fractional_mass_loss,
		double	distance,
		double	inclination,
		int	l,
		int	m
	)

Computes the waveform for the ringdown of a black hole quasinormal mode (l,m).

Note: The dimensionless spin assumes values between -1 and 1.

Todo:: Extend so that overtones can be computed too.

Parameters

hplus	plus-polarization waveform [returned]
hcross	cross-polarization waveform [returned]
t0	start time of ringdown
phi0	initial phase of ringdown (rad)
deltaT	sampling interval (s)
mass	black hole mass (kg)
dimensionless_spin	black hole dimensionless spin parameter
fractional_mass_loss	fraction of mass radiated in this mode
distance	distance to source (m)
inclination	inclination of source's spin axis (rad)
l	polar mode number
m	azimuthal mode number

Definition at line 612 of file LALSimBlackHoleRingdown.c.

◆ XLALSimRadiusKerrISCO()

REAL8 XLALSimRadiusKerrISCO ( REAL8 a )

Definition at line 676 of file LALSimBlackHoleRingdown.c.

◆ XLALSimEnergyKerrISCO()

REAL8 XLALSimEnergyKerrISCO ( REAL8 rISCO )

Definition at line 691 of file LALSimBlackHoleRingdown.c.

◆ XLALSimAngMomKerrISCO()

REAL8 XLALSimAngMomKerrISCO ( REAL8 rISCO )

Definition at line 699 of file LALSimBlackHoleRingdown.c.

◆ XLALSimIMREOBFinalMassSpin()

INT4 XLALSimIMREOBFinalMassSpin	(	REAL8 *	finalMass,
		REAL8 *	finalSpin,
		const REAL8	mass1,
		const REAL8	mass2,
		const REAL8	spin1[3],
		const REAL8	spin2[3],
		Approximant	approximant
	)

Computes the final mass and spin of the black hole resulting from merger.

They are given by fittings of NR simulations results. Specifically, for EOBNR, Table I of Buonanno et al. PRD76, 104049; for EOBNRv2 and EOBNRv2HM, Eqs. 29a and 29b of Pan et al. PRD84, 124052; for SEOBNRv1 Eq. 8 of Tichy and Marronetti PRD78, 081501 and Eqs. 1 and 3 of Barausse and Rezzolla ApJ704, L40; for SEOBNRv2 the formulas in Barausse and Rezzolla ApJ704, L40 were refitted to the set of NR wfs used in the calibration of SEOBNRv2; for SEOBNRv4 same mass formula as for SEOBNRv2 and final spin formula from Astrophys.J. 825 (2016) no.2, L19 for SEOBNRv5_ROM final mass formula from Jimenez Forteza et al. https://arxiv.org/abs/1611.00332 and same final spin formula as SEOBNRv4

Parameters

finalMass	< OUTPUT, the final mass (scaled by original total mass)
finalSpin	< OUTPUT, the final spin (scaled by final mass)
mass1	< The mass of the 1st component of the system
mass2	< The mass of the 2nd component of the system
spin1	< The spin of the 1st object; only needed for spin waveforms
spin2	< The spin of the 2nd object; only needed for spin waveforms
approximant	< The waveform approximant being used

Definition at line 721 of file LALSimBlackHoleRingdown.c.

◆ XLALSimIMREOBGenerateQNMFreqV2()

INT4 XLALSimIMREOBGenerateQNMFreqV2	(	COMPLEX16Vector *	modefreqs,
		const REAL8	mass1,
		const REAL8	mass2,
		const REAL8	spin1[3],
		const REAL8	spin2[3],
		UINT4	l,
		INT4	m,
		UINT4	nmodes,
		Approximant	approximant
	)

These functions generate the quasinormal mode frequencies for a black hole ringdown.

At present, this function works for the 22, 21, 33, 44 and 55 modes, and includes 8 overtones. The final frequencies are computed by interpolating the data found on the webpage of Vitor Cardoso, http://centra.ist.utl.pt/~vitor/?page=ringdown In this page, frequecy data are given for positive final spins only. For a negative final spin chi<0 case, the (l,m) mode frequency is given by the (l,-m) mode frequency of the positive final spin -chi case.

Parameters

modefreqs	< OUTPUT, complex freqs of overtones in unit of Hz
mass1	< The mass of the 1st component (in Solar masses)
mass2	< The mass of the 2nd component (in Solar masses)
spin1	< The spin of the 1st object; only needed for spin waveforms
spin2	< The spin of the 2nd object; only needed for spin waveforms
l	< The l value of the mode in question
m	< The m value of the mode in question
nmodes	< The number of overtones that should be included (max 8)
approximant	< The waveform approximant being used

Definition at line 858 of file LALSimBlackHoleRingdown.c.

◆ XLALSimIMREOBGenerateQNMFreqV2fromFinal()

INT4 XLALSimIMREOBGenerateQNMFreqV2fromFinal	(	COMPLEX16Vector *	modefreqs,
		const REAL8	finalMass,
		const REAL8	finalSpin,
		UINT4	l,
		INT4	m,
		UINT4	nmodes
	)

Parameters

modefreqs	< OUTPUT, complex freqs of overtones in unit of Hz
finalMass	< The mass of the final black hole (in Solar masses)
finalSpin	< The spin of the final object; only needed for spin waveforms
l	< The l value of the mode in question
m	< The m value of the mode in question
nmodes	< The number of overtones that should be included (max 8)

Definition at line 895 of file LALSimBlackHoleRingdown.c.

Detailed Description

Low-Level Routines

High-Level Routines

Function Documentation

◆ XLALSimBlackHoleRingdownModeEigenvaluesLeaver()

◆ XLALSimBlackHoleRingdownSpheroidalWaveFunctionLeaver()

◆ XLALSimBlackHoleRingdownMode()

◆ XLALSimBlackHoleRingdownSpheroidalWaveFunction()

◆ XLALSimBlackHoleRingdown()

◆ XLALSimRadiusKerrISCO()

◆ XLALSimEnergyKerrISCO()

◆ XLALSimAngMomKerrISCO()

◆ XLALSimIMREOBFinalMassSpin()

◆ XLALSimIMREOBGenerateQNMFreqV2()

◆ XLALSimIMREOBGenerateQNMFreqV2fromFinal()