gwaxion package
Contents
gwaxion package#
Submodules#
gwaxion.physics module#
- class gwaxion.physics.Alpha(m_bh=None, m_b=None, alpha=None, msun=True, ev=True, tolerance=1e-10)#
Bases:
object- static compute(m_bh, m_b)#
- fgw#
- m_b_ev#
- m_bh_msun#
- class gwaxion.physics.BlackHole(mass, chi=None, a=None, j=None, msun=False)#
Bases:
object- best_alpha(*args, **kwargs)#
- delta(r)#
Kerr auxiliary length Delta, function of radius in Boyer Lindquist coordinates.
- Parameters
r (float) – BL radius (m)
- Returns
delta – delta (m).
- Return type
float
- ergoshphere(theta, natural=False)#
Innner and outer ergosphere radii for given polar angle.
- fgw(alpha=None, l=1, nr=0, m_b=None, ev=True)#
- h0r_fit(f, **kwargs)#
- omega(r, theta)#
Frame dragging angular frequency (rad) for Boyer-Lindquist radius and polar angle.
- scan_alphas(l=1, m=1, nr=0, delta_alpha=0.001, alpha_min=0.001, alpha_max=None, lgw=None, verbose=False, ncpus=1, **kwargs)#
- sigma(r, theta)#
Kerr auxiliary length Sigma, function of radius and polar angle in Boyer Lindquist coordinates.
- Parameters
r (float) – BL radius (m)
theta (float) – BL polar angle (rad).
- Returns
sigma – sigma (m).
- Return type
float
- class gwaxion.physics.BlackHoleBoson(bh, boson)#
Bases:
object- best_cloud(*args, **kwargs)#
Retrieve (or create) cloud with fastest SR growth-rate.
All arguments passed to growth-rate function.
- Returns
cloud – cloud object for given quantum numbers.
- Return type
Cloud
- cloud(l, m, nr, update_waveform=True)#
Retrieve (or create) cloud of given level.
- Parameters
l (int) – azimuthal quantum number.
m (int) – magnetic quantum number.
nr (int) – radial quantum number.
- Returns
cloud – cloud object for given quantum numbers.
- Return type
Cloud
- create_waveform(lmns=None, lgw_max=None)#
Produce waveform (hp, hc) by adding contributions from clouds with quantum numners lmns, up to GW azimuthal number lgw_max.
If no lmns are specified, will use all clouds present to produce waform. If no lgw_max is specified, will only use the minimum (l_gw=2*l_cloud) for each cloud.
- Parameters
lmns (list) – optional list of tuples with cloud quantum numbers, e.g. [(1,1,0), (2,1,2), …] (def. all precomputed clouds).
lgw_max (int) – maximum GW azimuthal number (2*l_cloud <= l_gw <= lgw_max).
- Returns
hp (function) – plus polarization (function of theta, phi and time)
hc (function) – cross polarization (function of theta, phi and time)
- fgw(n)#
Returns main gravitational-wave frequency for level n.
fgw = 2*fre = 2*(wre/2pi) = wre/pi
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
- Returns
fgw – GW frequency in Hz.
- Return type
float
- classmethod from_parameters(**kwargs)#
Create black-hole boson system from parameters.
Can pass any two of the mass parameters (m_bh, m_b, alpha) and any one of the BH spin parameters (chi_bh, a_bh, j_bh).
The BH mass is assumed to be in units of MSUN, unless msun=False in which case SI units are expected.
The boson mass is assumed to be in units of eV, unless ev=False in which case SI units are expected.
The spin parameters (a_bh, j_bh) are always expected in SI units, while chi_bh is dimensionless.
- Parameters
m_bh (float) – black-hole mass (in MSUN, or SI if msun is False).
chi_bh (float) – dimensionless BH spin.
m_b (float) – boson rest mass (eV, or SI if ev is False).
boson_spin (int) – spin of boson field (0 for scalar, 1 for vector).
alpha (float) – fine-structure constant.
msun (bool) – BH mass provided in solar masses, rather than SI (def True).
ev (bool) – boson mass provided in eV, rather than SI (def True).
- hc(*args, **kwargs)#
- hp(*args, **kwargs)#
- is_superradiant(m)#
- level_energy(n, units='ev')#
Return real part of hydrogenic energy eigenvalues.
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
- level_frequency(n, *args, **kwargs)#
Return real part of hydrogenic energy eigen-frequencies in Hz.
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
- Returns
frequency – frequency of n-th eigenmode in Hz.
- Return type
float
- level_omega_im(l, m, nr, method='detweiler')#
Return imag part of hydrogenic energy eigen-frequencies in rad/s. Importantly, this half of the occupancy number grow rate.
Can be computed in different regimes:
- ‘detweiler’
This is from an analytic approximation in the nonrelativistic limit alpha << 1. References:
Eq. (28) in Detweiler (1980) Eq. (18) in Arvanitaki & Dubovsky (2011) Eq. (8) in Brito et al. (2017)
- ‘zouros’
This is from an analytic approximation in the WKB regime alpha >> 1. References:
Zouros & Eardley (1979) Eq. (27) in Arvanitaki & Dubovsky (2011)
- ‘dolan’
- Numerical method for the intermediate regime alpha ~ 1.
Dolan (2007)
- Parameters
l (int) – azimuthal quantum number.
m (int) – magnetic quantum number.
nr (int) – radial quantum number.
- Returns
omega – angular frequency of nth eigenmode in rad/s.
- Return type
float
- level_omega_natural(n)#
Return dimensionless hydrogenic eigen-frequencies.
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
- Returns
omega_dimless – dimensionless angular frequency of nth eigenmode in rad/s.
- Return type
float
- level_omega_re(n, method='hydrogen')#
Return real part of energy eigen-frequencies in rad/s.
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
- Returns
omega – angular frequency of nth eigenmode in rad/s.
- Return type
float
- max_growth_rate(l_min=0, nr_min=0, l_max=5, nr_max=5, **kwargs)#
Search for level with fastest superradiant growth rate.
- Parameters
l_min (int) – minimum azimuthal quantum number (def. 0).
nr_min (int) – minimum radial quantum number (def. 0).
l_max (int) – maximum azimuthal quantum number (def. 5).
nr_max (int) – maximum radial quantum number (def. 5).
- Returns
l_best (int) – azimuthal quantum number of fastest-growing level.
m_best (int) – magnetic quantum number of fastest-growing level.
nr_best (int) – radial quantum number of fastest-growing level.
rate_best (float) – growth rate (Hz) of fastest-growing level.
- waveform#
- class gwaxion.physics.Boson(mass, spin=0, ev=False)#
Bases:
object
- class gwaxion.physics.BosonCloud(bhb, l, m, nr, evolve=True, evolve_params=None, from_final=False)#
Bases:
object- property amplitude_growth_time#
1/Im(omega).
- Type
Field amplitude superradiant-instability timescale
- property bh_final#
Black-hole left at the end of superradiant cloud growth.
- property bh_initial#
Black-hole before start of superradiant cloud growth.
- property bhb_final#
Black-hole-boson left at the end of superradiant cloud growth.
- property bhb_initial#
Black-hole-boson before start of superradiant cloud growth.
- property fgw#
Gravitational-wave frequency (Hz).
- classmethod from_parameters(l, m, nr, evolve=True, evolve_params=None, from_final=False, **kwargs)#
- get_life_time(lgws=None)#
GW timescale, adding lgws listed in argument (def. just 2*l_cloud) .
- gw(lgw=None)#
- property is_superradiant#
Indicates whether this energy level (l, m, n) is superradiant.
- property mass#
Maximum cloud mass (kg), reached at end of superradiant stage.
- property mass_msun#
Maximum cloud mass (MSUN), reached at end of superradiant stage.
- property number_growth_time#
0.5/Im(omega).
- Type
Occupation number superradiant-instability timescale
- zabs(lgw=None)#
- class gwaxion.physics.GravitationalWaveMode(f, l=2, m=2, h0r=1, r0=1, c=0)#
Bases:
object- hc(*args, **kwargs)#
Cross polarization (unit amplitude).
- Parameters
theta (float) – inclination angle
phi (float) – orbital phase (azimuthal angle)
t (float, array) – times.
r (float) – distance from source in meters (def. 1).
- Returns
hp – cross polarization waveform for given times.
- Return type
array
- hp(*args, **kwargs)#
Plus polarization (unit amplitude).
- Parameters
theta (float) – inclination angle
phi (float) – orbital phase (azimuthal angle)
t (float, array) – times.
r (float) – distance from source in meters (def. 1).
- Returns
hp – plus polarization waveform for given times.
- Return type
array
- property polarizations#
- property swshs#
- gwaxion.physics.Z22fit(a)#
- class gwaxion.physics.Zabs(l, m)#
Bases:
object- property alpha_fit#
- static fast_fit(a, lgw=2, mgw=2)#
- gwaxion.physics.get_alpha_max(chi, m=1)#
- gwaxion.physics.get_final_spin(alpha, m=1)#
- gwaxion.physics.get_gw(alpha, lgw=2, l=1, m=1, nr=0, distance=1, times=False, **kwargs)#
Get amplitude and frequency of GW emission for given alpha, and BH properties determined by kwargs.
- gwaxion.physics.get_sr_cond(x, jx, T0, epsilon, m=1)#
- gwaxion.physics.h0_scalar_approx(alpha, f=None, m_bh=None, m_b=None, d=1, msun=True, ev=True, chi=None)#
Analytic approximation to the peak BHB scalar strain from Arvanitaki+.
- Parameters
alpha (float) – gravitational fine-structure constant.
f (float) – signal frequency
- gwaxion.physics.h0_scalar_brito(m_i, alpha, chi_i=0.9, d=1, l=1, m=1, lgw=None, mgw=None, msun=True)#
GW strain for scalar boson from Brito et al. [PhysRevD.96.064050]
Default GW emission at (lgw=2*l, mgw=2*m).
- Parameters
m_i (float, array) – initial black-hole mass (in solar masses if msun, else kg).
alpha (float, array) – fine-structure constant.
chi_i (float, array) – initial black-hole spin parameter (dimensionless).
d (float, array) – distance to source in meters (def. 1).
msun (bool) – expect black-hole mass in solar masses.
- Returns
h0 (float, array) – gravitational-wave amplitude (strain).
fgw – gravitational-wave frequency (Hz).
- gwaxion.physics.h0_vector_approx(alpha, f=None, m_bh=None, m_b=None, d=3.08567758e+19, msun=True, ev=True)#
Analytic approximation to the peak BHB vector strain from Arvanitaki+.
- Parameters
alpha (float) – gravitational fine-structure constant.
f (float) – signal frequency
- gwaxion.physics.hydrogenic_level(n, alpha)#
Return hydrogenic levels: (En / E0)
- Parameters
n (float) – principal quantum number n = nr + l + 1, for nr the radial and l the azimuthal quantum numbers.
alpha (float) – Fine-structure constant.
- Returns
level – dimensionless level (En / E0).
- Return type
float
- gwaxion.physics.qcd_axion_mass(fa)#
Mass of QCD axion as a function of symmetry breaking scale.
See e.g. Eq. (2) in [arXiv:1004.3558]
- Parameters
fa (float) – Peccei-Quinn axion symmetry breaking scale in eV.
- Returns
mua – QCD axion mass in eV.
- Return type
float
- gwaxion.physics.tgw_approx(m, alpha, chi, msun=True)#
- gwaxion.physics.tinst_approx(m, alpha, chi, msun=True)#
gwaxion.evolve module#
- gwaxion.evolve.evolve_bhb(bhb_0, y_0=1e-08, jy_0=1e-08, l=1, m=1, nr=0, dtau=None, max_steps=1000000.0, pgw=None, tolerance=0.001)#
Solve cloud evolution equations.
- Define dimensionless $(x, y, j^x, j^y, {cal P}, w, au)$ quantities such that
- egin{align}
M &= lpha xM_c &= lpha y J &= eta j^xJ_c &= eta j^yP_{gw} &= gamma {cal P}omega &= w mut &= epsilon au, .
end{align}
- We will make sure these are dimensionless by defining the dimensionful factors
- egin{align}
lpha &= M_0 eta &= M_0 c^2 mu^{-1} gamma &= M_0 c^2 mu epsilon &= mu^{-1}, ,
end{align}
and letting $mu = hbar/(m_b c^2)$ be the Compton frequency associated with the boson rest mass, $m_b$. We will also let $M_0$ be the initial black-hole mass. Note that then we have:
- egin{align}
a &=
- rac{c j_x epsilon}{x}
chi &=
rac{j_x}{x^2} rac{epsilon}{T_0}, ,
end{align}
- where we have defined the time $T_0 = G M_0/c^3$. The SR condition is saturated when
- egin{equation}
left(
rac{2}{m} rac{T_0}{epsilon} ight)^2 =
rac{j_x}{x^2left(mx-j_x ight)}
end{equation}
- With the above notation, the BHB evolution equations become:
- egin{align}
x’ &= -2 w_I yx’ + y’ &= -{cal P}(j^x)’ &= -2 m w_I w_R^{-1} y(j^x)’ + (j^y)’ &= -m w_R^{-1} {cal P}
end{align}
for $m$ the boson magnetic quantum number ($m=1$ for dominant scalar level), and where the prime denotes ${
m d}/{ m d} au$. We may turn these into
- finite-difference equations to obtain:
- egin{align}
x_{i+1} &= x_i -2 w^I_i y_i delta au y_{i+1} &= y_i + 2 w^I_i y_i delta au -{cal P}_i delta au j^x_{i+1} &= j^x_i -2 m (w^I_i/ w^R_i) y_i delta au j^y_{i+1} &= j^y_i + mleft(2 w^I_i y_i - {cal P}_i
- ight)delta au/w^R_i
end{align}
These can be evolved from $(x_0, y_0, j^x_0, j^y_0)$ until the SR spin threshold is reached. The final state can then be converted into physical units using the scalings defined above.
- gwaxion.evolve.evolve_bhb_simple(bhb_0, y_0=1e-08, l=1, m=1, nr=0, dtau=None, max_steps=1000000.0, tolerance=0.001)#
Solve cloud evolution equations, ignoring cloud angular momentum and GW power.
See documentation for evolve_bhb for more information.
- gwaxion.evolve.get_sr_cond(x, jx, T0, epsilon, m=1)#
gwaxion.leavers module#
- class gwaxion.leavers.SpinWeightedSpheroidalHarmonic(c, l, m, s)#
Bases:
object- compute_eigenfunction(nmax=20)#
Compute spheroidal harmonic Slm(x), with x = cos(theta), where theta is the polar angle.
Uses recursive formula from Eq. (18) in Leaver [Eq. (2.5) in Berti]. The function is normalized such that
int_{-1}^{1} |Slm(x)|^2 dx = 1
NOTE: does not include azimuthal dependence (i.e. not spin-weighted).
- Parameters
nmax (int) – iteration depth for sum in Eq. (18), higher for greater accuracy. (default: 20)
- Returns
slm_normed – normalized spheroidal harmonic.
- Return type
funct
- compute_eigenvalue(*args, **kwargs)#
Compute angular separation eigenvalue Alm.
If c=0 returns analytic solution. Otherwise, numerically solve continued fraction equation to find Alm as in Eq. (21) in Leaver.
- Parameters
nmax (int (optional)) – Maximum number of steps in the continued fraction recursion. (More for higher accuracy.)
mode (str (optional)) – Numerical root-finding method (e.g. ‘root’, ‘newton’)
- property eigenfunction#
Spheroidal harmonic function.
- Parameters
x (float) – polar parameter x = cos(theta) for theta the polar angle.
- Returns
Slm – value of spheroidal harmonic at specified value of cos(theta).
- Return type
float
- property eigenvalue#
- sh(theta)#
Spheroidal harmonic (SH), Slm, as a function of polar angle.
- NOTE: this is equivalent to
eigenfunction(np.cos(theta))
- Parameters
theta (float) – polar angle.
- Returns
Slm – value of SH evaluated at theta.
- Return type
float
- swsh(theta, phi)#
Spin-weighted spheroidal harmonic (SWSH), Ylm.
- Parameters
theta (float) – polar angle.
phi (float) – azimuthal angle.
- Returns
Ylm – value of SWSH evaluated at specified values theta and phi.
- Return type
float