phenomxpy.fft

Utilities for Fourier transform.

phenomxpy.fft.ConditioningParams(f_min=10.0, mass1=30.0, mass2=20.0, s1z=0, s2z=0)

Compute the conditioning parameters.

The most important one is the new minimum frequency to start the waveform at. - original_f_min: this is the input f_min - f_min0: f_min if it is lower than a fisco frequency, otherwise set to fisco. It is used in time_array_condition_stage2. - f_min: the new f_min to start the waveform after adding extra cycles and time. - fisco: the frequency at which the innermost stable circular orbit occurs. - extra_time_fraction: the fraction of the total chirp time to add as extra time. - extra_cycles: the number of extra cycles to add. - tchirp: bound to chirp time. - s: the final spin of the black hole. - tmerge: bound to merger time. - textra: the extra time added.

Parameters:

• f_min (float) – The lower frequency bound in Hz.

• mass1 (float) – The mass of the first component in solar masses.

• mass2 (float) – The mass of the second component in solar masses.

• s1z (float) – The z-component of the dimensionless spin of body 1.

• s2z (float) – The z-component of the dimensionless spin of body 2.

Returns:

Containing the conditioning parameters.

Return type:

dict

phenomxpy.fft.FFT(h, delta_t, f_min_fd=None, real=True)

Compute the Fast Fourier Transform (FFT) of a complex or real time series.

Parameters:

• h (1D ndarray) – complex/real time series. It should be properly conditioned to produce sensible results.

• delta_t (float) – Time spacing of input time series.

• delta_f (float) – Frequency spacing of output frequency series.

• f_min_fd (float) – Starting frequency of frequency series.

• real (bool) – If time series is real or complex.

Returns:

h(f), f: Frequency series y and x values. For complex time series the frequencies will spand also the negative frequency range, while real series only return positive frequencies since h(-f)=h*(f).

Return type:

Tuple with 2 1D ndarrays

phenomxpy.fft.FFT_polarizations(hp, hc, delta_t, f_min_fd=None)

Compute the Fast Fourier Transform (FFT) of the two (real) time domain polarizations.

Parameters:

• hp (1D ndarrays) – Real time series for the two polarizations. The should be properly conditioned to produce sensible results.

• hc (1D ndarrays) – Real time series for the two polarizations. The should be properly conditioned to produce sensible results.

• delta_t (float) – Time spacing of input time series.

• delta_f (float) – Frequency spacing of output frequency series.

• f_min_fd (float) – Starting frequency of frequency series.

Returns:

hp(f), hc(f), f: Polarizations in Fourier domain and frequency array. Since the time series are real, the output frequencies only span the positive range, h(-f)=h*(f).

Return type:

Tuple with 3 1D arrays

phenomxpy.fft.SimInspiralChirpStartFrequencyBound(tchirp, m1, m2)

Adapted from XLALSimInspiralChirpStartFrequencyBound.

Routine to compute an underestimate of the starting frequency for a given chirp time.

This routine estimates a start frequency for a binary inspiral from which the actual inspiral chirp time will be shorter than the specified chirp time. To obtain this estimate, only the leading order Newtonian coefficient is used. The frequency returned by this routine is guaranteed to be less than the frequency passed to XLALSimInspiralChirpTimeBound() if the returned value of that routine is passed to this routine as tchirp.

Parameters:

• tchirp (float) – The chirp time of post-Newtonian inspiral s.

• m1 (float) – The mass of the first component in kg.

• m2 (float) – The mass of the second component in kg.

Returns:

Lower bound on the starting frequency of a post-Newtonian inspiral in Hz.

Return type:

float

phenomxpy.fft.SimInspiralChirpTimeBound(fstart, m1, m2, s1z, s2z)

Adapted from XLALSimInspiralChirpTimeBound.

Routine to compute an overestimate of the inspiral time from a given frequency.

This routine estimates the time it will take for point-particle inspiral from a specified frequency to infinite frequency. The estimate is intended to be an over-estimate, so that the true inspiral time is always smaller than the time this routine returns. To obtain this estimate, the 2PN chirp time is used where all negative contributions are discarded.

Parameters:

• fstart (float) – The starting frequency in Hz.

• m1 (float) – The mass of the first component in kg.

• m2 (float) – The mass of the second component in kg.

• s1z (float) – The z-component of the dimensionless spin of body 1.

• s2z (float) – The z-component of the dimensionless spin of body 2.

Returns:

Upper bound on chirp time of post-Newtonian inspiral in seconds

Return type:

float

phenomxpy.fft.SimInspiralFinalBlackHoleSpinBound(s1z, s2z)

” Adapted from XLALSimInspiralFinalBlackHoleSpinBound.

Routine to compute an overestimate of a final black hole dimensionless spin.

This routine provides an upper bound on the dimensionless spin of a black hole produced in a compact binary merger. Uses the formula in Tichy and Marronetti, Physical Review D 78 081501 (2008), Eq. (1) and Table 1, for equal mass black holes, or the larger of the two spins (which covers the extreme mass case). If the result is larger than a maximum realistic black hole spin, truncate at this maximum value.

See Tichy and Marronetti, Physical Review D 78 081501 (2008). TODO: It has been suggested that Barausse, Rezzolla (arXiv: 0904.2577) is more accurate.

Parameters:

• s1z (float) – The z-component of the dimensionless spin of body 1.

• s2z (float) – The z-component of the dimensionless spin of body 2.

Returns:

Upper bound on final black hole dimensionless spin.

Return type:

float

phenomxpy.fft.SimInspiralMergeTimeBound(m1, m2)

Adapted from XLALSimInspiralMergeTimeBound.

Routine to compute an overestimate of the merger time.

This routine provides an upper bound on the time it will take for compact binaries to plunge and merge at the end of the quasi-stationary inspiral. This is quite vague since the notion of a innermost stable circular orbit is ill-defined except in a test mass limit. Nevertheless, this routine assumes (i) that the innermost stable circular orbit occurs at v = c / 3, or r = 9 G M / c^3 (in Boyer-Lindquist coordinates), which is roughly right for an extreme Kerr black hole counter-rotating with a test particle, and (ii) the plunge lasts for a shorter period than one cycle at this innermost stable circular orbit.

Parameters:

• m1 (float) – The mass of the first component in kg.

• m2 (float) – The mass of the second component in kg.

Returns:

Upper bound on the merger time in seconds.

Return type:

float

phenomxpy.fft.SimInspiralRingdownTimeBound(M, s)

Adapted from XLALSimInspiralRingdownTimeBound.

Routine to compute an overestimate of the ringdown time.

This routine provides an upper bound on the time it will take for a black hole produced by compact binary merger to ring down through quasinormal mode radiation. An approximate formula for the frequency and quality of the longest-lived fundamental (n=0) dominant (l=m=2) quasinormal mode * is given by Eqs. (E1) and (E2) along with Table VIII of Berti, Cardoso, and Will, Physical Review D (2006) 064030. Waveform generators produce 10 e-folds of ringdown radiation, so this routine goes up to 11 to provide an over-estimate of the ringdown time.

See Emanuele Berti, Vitor Cardoso, and Clifford M. Will, Physical Review D 73, 064030 (2006) DOI: 10.1103/PhysRevD.73.064030

Parameters:

• M (float) – The mass of the final black hole in kg.

• s (float) – The dimensionless spin of the final black hole.

Returns:

Upper bound on the merger time in seconds.

Return type:

float

phenomxpy.fft.check_pow_of_2(n)

Return the next highest power of 2 given number n. For example: if n = 7; exponent will be 3 (2**3=8)

phenomxpy.fft.high_pass_time_series(time_series, dt, fmin, attenuation, N, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/phenomxpy/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>)

Adapted from gwsignal.

High-pass filter a time series.

Parameters:

• time_series (1D ndarray) – Time series to filter

• dt (float) – Time spacing of input time series

• fmin (float) – Minimum frequency for high-pass

• attenuation (float) – Attenuation value at low-freq cut-off

• N (int) – Order of butterworth filter

• xp (np/cp) – Module to use for cpu/gpu

Returns:

filtered time series

Return type:

1D ndarray

phenomxpy.fft.resize_timeseries(h, dt, start_id, new_length, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/phenomxpy/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>)

Adapted from gwsignal.

Resize a given gwpy TimeSeries which has a given length and starts at a point specified by start_id. If start_id is negative, the timeseries will be padded on the left with that amount.

Parameters:

• h (1d ndarray) – Time series that needs to be resized

• dt (float) – Time spacing

• start_id (int) – If positive, index at which TimeSeries will now start from. If negative, TimeSeries will be zero padded with that length on the left.

• new_length (int) – Final length of output array. This will be done by clippling the end of the TimeSeries, if new_length is larger than len(hp[start_id:]); otherwise zero_pad on right

• xp (np/cp) – Module to use for cpu/gpu

Returns:

Resized time series array.

Return type:

1d ndarray

phenomxpy.fft.time_array_condition_stage1(hp, hc, dt, t_extra, fmin, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/phenomxpy/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>, high_pass_filter_lal=False)

Adapted from gwsignal.

Stage 1 of time-series conditioning - add taper and high-pass the time-series.

Parameters:

• hp (1d ndarray) – Plus polarization time series

• hc (1d ndarray) – Cross polarization time series

• dt (float) – Sampling value of time series

• t_extra (float) – Initial extra time for conditioning

• fmin (float) – Minimum frequency for high-pass

• xp (np/cp) – Module to use for cpu/gpu

• high_pass_filter_lal (bool) – Use lal functions for filter or not. lal functions recover machine precision.

Returns:

Stage1 conditioned time series

Return type:

1D ndarray

phenomxpy.fft.time_array_condition_stage2(hp, hc, dt, fmin, fmax, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/phenomxpy/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>)

Adapted from gwsignal.

Stage 2 of time-series conditioning - taper end of waveform based off maximum frequency

Parameters:

• hp (1d ndarray) – Plus polarization time series

• hc (1d ndarray) – Cross polarization time series

• dt (float) – Sampling value of time series

• fmin (float) – Minimum frequency for high-pass

• fmax (float) – Minimum frequency for high-pass

• xp (np/cp) – Module to use for cpu/gpu

Returns:

Stage2 conditioned time series

Return type:

1D ndarray

phenomxpy.utils

phenomxpy.utils.AmpNRtoSI(ampNR, distance, total_mass)

Transform amplitude from NR units to SI units.

Parameters:

• ampNR (float or 1D ndarray) – amplitude value in NR units.

• distance (float) – distance in megaparsecs.

• total_mass (float) – total mass in solar masses.

Returns:

amplitude in SI units.

Return type:

float or 1D ndarray

phenomxpy.utils.AmpSItoNR(ampSI, distance, total_mass)

Transform amplitude from SI units to NR units.

Parameters:

• ampSI (float or 1D ndarray) – amplitude value in SI units.

• distance (float) – distance in megaparsecs.

• total_mass (float) – total mass in solar masses.

Returns:

amplitude in NR units.

Return type:

float or 1D ndarray

phenomxpy.utils.DistanceToSeconds(dMpc)

Transform distance in megaparsecs to seconds.

Parameters:

dMpc (float or 1D ndarray) – distance in megaparsecs

Returns:

distance in seconds

Return type:

float or 1D ndarray

phenomxpy.utils.HztoMf(Hz, total_mass)

Transform frequency in Hz to NR units.

Parameters:

• Hz (float or 1D ndarray) – frequency in Hz.

• total_mass (float) – total mass in solar masses.

Returns:

frequency in NR units.

Return type:

float or 1D ndarray

phenomxpy.utils.MasstoSecond(mass, total_mass=1)

Transform (NR) time in masses to seconds.

Parameters:

• mass (float or 1D ndarray) – time in units of mass

• total_mass (float) – mass in solar masses

Returns:

time in seconds

Return type:

float or 1D ndarray

phenomxpy.utils.MftoHz(Mf, total_mass)

Transform frequency in NR units to SI (Hz) units.

Parameters:

• Mf (float or 1D ndarray) – frequency in NR units.

• total_mass (float) – total mass in solar masses.

Returns:

frequency in Hz.

Return type:

float or 1D ndarray

phenomxpy.utils.ModeListToString(mode_array)

Transform mode_array in format [[l,m], [l2,m2], …] to a string “lm l2m2 …”

phenomxpy.utils.ModeToString(mode)

Convert mode [l,m] to string “lm”

phenomxpy.utils.PolarToCartesian(norm, theta, phi)

Transform polar coordinates to cartesian.

Parameters:

• norm (float) – vector norm

• theta (float) – polar angle (rad).

• phi (float) – azimuthal angle (rad).

Returns:

Vector in cartesian coordinates

Return type:

(3,) ndarray

phenomxpy.utils.SecondtoMass(seconds, total_mass)

Transform time in seconds to time in mass.

Parameters:

• seconds (float or 1D ndarray) – time in seconds

• total_mass (float) – mass in solar masses

Returns:

time in units of mass

Return type:

float or 1D ndarray

phenomxpy.utils.SpinWeightedSphericalHarmonic(theta, phi, l, m, s=-2)

Computes the \({}_{-2}Y_{lm}\) spin-weighted spherical harmonic.

Implements Equations (II.9)-(II.13) of D. A. Brown, S. Fairhurst, B. Krishnan, R. A. Mercer, R. K. Kopparapu, L. Santamaria, and J. T. Whelan, “Data formats for numerical relativity waves”, arXiv:0709.0093v1 (2007). Currently only supports s=-2, l=2,3,4,5 modes.

Adapted from XLALSpinWeightedSphericalHarmonic.

Parameters:

• theta (float) – polar angle (rad).

• phi (float) – azimuthal angle (rad).

• l (int) – spherical harmonic indices.

• m (int) – spherical harmonic indices.

• s (int) – spin value.

Returns:

Ylm(theta, phi)

Return type:

complex value

phenomxpy.utils.ToComponentMassesCartesianSpins(params, use_spin_vectors=True)

phenomxpy.utils.check_equal_blackholes(pWF)

Check if the black holes are equal by checking if eta is 0.25 and s1z == s2z.

Parameters:

pWF (pWFHM) – pWFHM object with the parameters of the waveform.

Returns:

True if black holes are equal, False otherwise

Return type:

bool

phenomxpy.utils.chi_eff(eta, s1, s2)

chi_effective spin from symmetric mass ratio and spin-z components.

chi_effective = m1 s1 + m2 s2

phenomxpy.utils.convert_params(params)

Transform input dictionary to (eta, total_mass) and spins in cartesian coordintaes.

phenomxpy.utils.custom_swsh(cosbeta, gamma, mode_array, lmax, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/phenomxpy/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>)

Function to compute the spin-weighted spherical harmonics necessary to compute the polarizations in the inertial frame from the co-precessing frame modes [(2,|2|),(2,|1|),(3,|3|),(3,|2|),(4,|4|),(4,|3|),(5,|5|)].

Parameters:

• beta (float, 1D ndarray) – Euler angle beta between the co-precessing frame and the inertial frame

• gamma (float, 1D ndarray) – Euler angle gamma between the co-precessing frame and the inertial frame

• lmax (int) – Maximum ell to use

Returns:

Dictionary containing the Ylm (for v5 method) for each spin-weighted spherical harmonic

Return type:

dict

phenomxpy.utils.etaofq(q)

Compute symmetric mass ratio from mass ratio.

phenomxpy.utils.extra_options_from_string(approximant)

Parse extra options from approximant name. E.g. IMRPhenomTPHM_NNLO_FS2.

Parameters:

approximant (str) – Approximant name with extra options separated by underscores. E.g. IMRPhenomTPHM_NNLO_FS2.

Returns:

clean approximant name, dictionary with extra options

Return type:

Tuple with string and dict

phenomxpy.utils.lookup_mass1(params)

Compute mass1 from any possible combination of 2 mass parameters inserted in the LALDict. If the combination does not allow to distinguish the largest object then it assumes m1 > m2. mass_ratio is defined as q = m2/m1 and mass_difference as m1 - m2.

Adapted from XLALSimInspiralWaveformParamsLookupMass1

Parameters:

params (dict) – Waveform parameters

Returns:

Component mass1

Return type:

float

phenomxpy.utils.lookup_mass2(params)

Compute mass2 from any possible combination of 2 mass parameters inserted in the LALDict. If the combination does not allow to distinguish the largest object then it assumes m1 > m2. mass_ratio is defined as q = m2/m1 and mass_difference as m1 - m2.

Adapted from XLALSimInspiralWaveformParamsLookupMass2

Parameters:

params (dict) – Waveform parameters

Returns:

Component mass2

Return type:

float

phenomxpy.utils.m1ofeta(eta, total_mass=1)

Compute component mass1 from symmetric mass ratio (eta) and total mass. Assumes m1 >= m2.

phenomxpy.utils.m1ofq(q, total_mass=1)

Compute component mass1 from mass ratio and total mass. If q > 1 then m1 > m2.

phenomxpy.utils.m2ofeta(eta, total_mass=1)

Compute component mass2 from symmetric mass ratio (eta) and total mass. Assumes m1 >= m2.

phenomxpy.utils.m2ofq(q, total_mass=1)

Compute component mass2 from mass ratio and total mass. If q > 1 then m1 > m2.

phenomxpy.utils.mass_ratio_from_chirp_mass_component_mass1(chirp_mass, component_mass)

Compute mass ratio from chirp mass and component mass1.

phenomxpy.utils.mass_ratio_from_chirp_mass_component_mass2(chirp_mass, component_mass)

Compute mass ratio from chirp mass and component mass2.

phenomxpy.utils.move_to_front(array, target)

Find element in an array and put it at the beginning of the array.

Parameters:

• array (list) – input array to modify

• target (same as array) – Element to move

Returns:

Array with target in the first position.

Return type:

list

phenomxpy.utils.parse_options_from_approximant_name(params_dict)

Update input dictionary with extra options taken from the approximant name.

Some options can be indicated in the approximant name, e.g. IMRPhenomTPHM_NNLO_FS2 will add prec_version = ‘nnlo’ and final_spin_version = 2 to the input dictionary.

Parameters:

params_dict (dictionary, it includes the approximant name with extra options)

Returns:

Clean approximant name, e.g. IMRPhenomTPHM.

Return type:

string

phenomxpy.utils.qofeta(eta)

Compute mass ratio from symmetric mass ratio. q >= 1

phenomxpy.utils.read_pickle(filename)

Read pickle file

phenomxpy.utils.remove_duplicates(lst)

Remove duplicates from a list with format [[l,m], [,], …]

phenomxpy.utils.replace_instances_with_value(array, mask, value, xp)

Replace instances in an array with a given value.

Basically it does array[mask], but this is very slow for cupy arrays, so for that case we use cp.where.

Parameters:

• array (ndarray) – array to modify.

• mask (array of booleans) – Array where the instances happen.

• value (value or array to replace the instances with.)

• xp (np/cp) – module for the cpu/gpu

Returns:

With instances replaced.

Return type:

array

phenomxpy.utils.rotate_by_polarization_angle(hp, hc, polarization_angle)

Rotate hp, hc by polarization_angle.

Eq. 36 [11].

hp’ = hp cos(2 psi) - hc sin(2 psi) hc’ = hp sin(2 psi) + hc cos(2 psi)

Returns:

Rotated hp’, hc’

Return type:

Tuple with 2 1D ndarrays

phenomxpy.utils.sTotR(eta, s1, s2)

sTotR spin from symmetric mass ratio and spin-z components.

sTotR = \(\frac{m_1^2 s1 + m_2^2 s2}{m_1^2 + m_2^2}\).

phenomxpy.utils.save_pickle(obj, filename)

Save object into pickle file