TransitionListener package¶

TransitionListener package providing tools to analyze cosmological phase transitions.

Interface¶

Phases and phase tracing¶

Phase transition classification¶

Computation of transition observables¶

Bubble dynamics¶

This module is used to calculate the bubble dynamics in the dark sector. It contains functions to calculate the energy density, effective degrees of freedom, the Hubble parameter, the bubble nucleation rate, and from this the nucleation and percolation temperature.

Authors: Jonas Matuszak <jonas.matuszak@kit.edu>, 2025 Carlo Tasillo <carlo.tasillo@physics.uu.se>, 2025

transitionlistener.bubbledynamics.ApproxPercCritSecondOrder(T, Tnuc, outdict, pot, phase_sym, phase_bro, Tmax, Tmin, vw, verbose=False)¶

Calculate a an approximation of the percolation temperature. This uses the saddlepoint approximation of

\[\Gamma = \Gamma_p e^{\beta (t - t_p) - \alpha^2 / 2 (t - t_p)^2}\]

Important: The criterion returns a value < 0 if the temperature is too high and a value > 0 if the temperature is too small. It returns 0 if the criterion is met.

If the action becomes inf at a temperature, this has to be because the S/T function is u-shaped and must occur at the Tmin end, since at Tnuc the action is finite. Therefore also return np.inf for S/T = inf.

Parameters:

T (float) – The temperature.
Tnuc (float) – The nucleation temperature
outdict (dict) – Dictionary storing the action evaluation
pot (generic_potential) – The effective potential object
phase_sym (PhaseInfo) – The high temperature phase information
phase_bro (PhaseInfo) – The low temperature phase information
Tmax (float) – The maximal temperature, where to compute the nucleation criterion (usually Tnuc)
Tmin (float) – The minimal temperature where to compute the nucleation criterion, usually the minimal temp. of coexistence of the phases.
vw (float) – The bubble wall velocity.
verbose (bool, optional) – Set the output level

Returns:

Zero if the criterion is met for T; negative if T is too large, positive if it is too small.

Return type:

float

transitionlistener.bubbledynamics.ApproxPercolCriterion(T, outdict, pot, phase_sym, phase_bro, Tmax, Tmin, vw, verbose=False)¶

Calculate a rough approximation of the percolation temperature. This uses the saddlepoint approximation of

\[\Gamma = \Gamma_0 \exp\bigl[-\beta (t - t_0)\bigr]\]

Important: The criterion returns a value < 0 if the temperature is too high and a value > 0 if the temperature is too small. It returns 0 if the criterion is met.

Parameters:

T (float) – The temperature.
outdict (dict) – Dictionary storing the action evaluation
pot (generic_potential) – The effective potential object
phase_sym (PhaseInfo) – The high temperature phase information
phase_bro (PhaseInfo) – The low temperature phase information
Tmax (float) – The maximal temperature, where to compute the nucleation criterion (usually Tnuc)
Tmin (float) – The minimal temperature where to compute the nucleation criterion, usually the minimal temp. of coexistence of the phases.
vw (float) – The bubble wall velocity.
verbose (bool, optional) – Set the output level

Returns:

Zero if the criterion is met for T; negative if T is too large, positive if it is too small.

Return type:

float

transitionlistener.bubbledynamics.ApproxPercolCriterion2(T, outdict, pot, phase_sym, phase_bro, Tmax, Tmin, vw, verbose=False)¶

Alternative method to estimate the percolation criterion. This uses a smaller dT for the derivatives and computes betaH from the action not the nucleation rate.

Parameters:

T (float) – The temperature.
outdict (dict) – Dictionary storing the action evaluation
pot (generic_potential) – The effective potential object
phase_sym (PhaseInfo) – The high temperature phase information
phase_bro (PhaseInfo) – The low temperature phase information
Tmax (float) – The maximal temperature, where to compute the nucleation criterion (usually Tnuc)
Tmin (float) – The minimal temperature where to compute the nucleation criterion, usually the minimal temp. of coexistence of the phases.
vw (float) – The bubble wall velocity.
verbose (bool, optional) – Set the output level

Returns:

0 if the criterion is met for T, < 0 if T is to large, > 0 if T is to small.

Return type:

float

transitionlistener.bubbledynamics.Gamma(T, S)¶

Calculate the bubble nucleation rate.

Parameters:

T (float | np.ndarray) – Symmetric phase temperature
S (float | np.ndarray) – The action at temperature T

Returns:

Gamma – The bubble nucleation rate.

Return type:

np.ndarray

transitionlistener.bubbledynamics.HubbleParameter(rho, CF)¶

Hubble parameter.

Parameters:

rho (float) – The energy density of the unverse.
CF (float) – Conversion factor to convert internal units to GeV.

Returns:

The Hubble parameter.

Return type:

float

class transitionlistener.bubbledynamics.PercolationGrid(TSYM, TpercApprox, tmin, tmax, TBROmin, TBROmax)¶

Bases: object

Shared inputs needed throughout the percolation workflow.

TBROmax: float¶

TBROmin: float¶

TSYM: ndarray¶

TpercApprox: float¶

tmax: float¶

tmin: float¶

class transitionlistener.bubbledynamics.PercolationSettings(f_perc, f_start, f_final, weight, maxit, rel_increment, max_boundary_n)¶

Bases: object

Container for frequently used percolation configuration parameters.

f_final: float¶

f_perc: float¶

f_start: float¶

max_boundary_n: int¶

maxit: int¶

rel_increment: float¶

weight: float¶

class transitionlistener.bubbledynamics.PercolationState(TSYM, Sr, Hr, Pr, Pr_exp, scalef_ratio, soundSpSq, Tb)¶

Bases: object

Mutable arrays updated during the percolation iterations.

Hr: ndarray¶

Pr: ndarray¶

Pr_exp: ndarray¶

Sr: ndarray¶

TSYM: ndarray¶

Tb: ndarray¶

scalef_ratio: ndarray¶

soundSpSq: ndarray¶

transitionlistener.bubbledynamics.Tb_criterion(TBRO, TSYM, phase_sym, phase_broken, pot)¶

Criterion to find the broken phase temperature, it uses energy conservation. Reheat to SM + DS in the broken phase. Assume instant heating.

Parameters:

TBRO (float) – Broken phase temperature to solve for
TSYM (float) – Temperature in the symmetric phase
phase_sym (PhaseInfo) – Field value in the broken phase as a function of temperature
phase_broken (PhaseInfo) – Field value in the broken phase as a function of temperature
pot (generic_potential) – The effective potential object

Returns:

Criterion: 0 if TBRO is the correct broken phase temperature.

Return type:

float

transitionlistener.bubbledynamics.approxNucleationCriterion(T_DS, S, pot, phase_sym, phase_bro)¶

Calculate the nucleation criterion for a given temperature and action. This function computes the nucleation criterion based on the following equation:

\[\frac{\Gamma}{H^4} = 1\]

where $\Gamma$ denotes the bubble nucleation rate and $H$ is the Hubble parameter during radiation domination.

Parameters:

T_DS (float) – Temperature of the DS.
S (float) – Action at temperature TDS
pot (generic_potential) – The effective potential object
phase_sym (PhaseInfo) – The information about the high temperature phase
phase_bro (PhaseInfo) – The information about the low temperature phase

Returns:

Result of the nucleation criterion, 0 if fulfilled.

Return type:

float

transitionlistener.bubbledynamics.approxPercIntegral(Tperc, logG, Tnuc, beta, alphasq, pot, phase, verbose=False)¶

Calculate the percolation integral up to the gaussian approximation.

\[I = \int_{-\infty}^{t_p} d t (t_p - t) \Gamma_p \exp(\beta (t - t_p) - a^2/2(t - t_p)^2)\]

Parameters:

Tperc (float,) – The percolation temperature
logG (float) – $\log(\Gamma_p)$, the log of the nucleation rate
Tnuc (float) – The nucleation temperature
beta (float) – First derivative of the action w.r.t. time: $d/dt (S_3/T)$
alphasq (float) – Second derivative of the action w.r.t. time $d^2/dt^2 (S_3/T)$
pot ("generic_potential") – The effective potential
phase (PhaseInfo) – The current phase
verbose (bool, optional) – Set the output level

Returns:

The percolation interal.

Return type:

float

transitionlistener.bubbledynamics.calcAction(pot, T, start_phase, end_phase, outdict, verbose=False, phitol=1e-06)¶

Calculate the action at temperature T

Parameters:

pot (generic_potential) – The effective potential object
T (float) – The temperature
start_phase (PhaseInfo) – The information about the high temperature phase
end_phase (PhaseInfo) – The information about the low temperature phase
outdict (dict) – The dictionary storing the action evaluations with the key T.
verbose (bool, optional) – Set the output level
phitol (float, optional) – Set the accuracy of the minimisation of the potential minima.

Returns:

The action at temperature T.

Return type:

float

transitionlistener.bubbledynamics.calcAlphas(T, pot, high_phase, low_phase, verbose=False)¶

Calculate the total transition strenght of the PT. Use several definitions.

The last 3 alphas are normalised to the radiation energy density of only the relevant sector for the bubble expansion. I.e. when pot.kin_coupled_e/p_geff = 0, they are normalised to radiation energy density in the PT sector only.

Parameters:

T (float) – Temperature at which to evaluate alpha
pot (generic_potential) – Effective potential
high_phase (phaseInfo) – Phase info of the initial phase
low_phase (phaseInfo) – Phase info of the end phase

Returns:

tuple – Tuple of floats, the 3 definitions of alpha and the alphas used for the calculation the efficency factors kappa.

Return type:

float

transitionlistener.bubbledynamics.calcApproxPercolation(outdict, pot, Tnuc, phase_sym, phase_bro, vw, verbose=True, tmin=None, tmax=None)¶

Estimate the percolation temperature assuming equal SM/DS temperatures.

Parameters:

outdict (dict) – Dictionary storing the action evaluation.
pot (generic_potential) – The effective potential object.
Tnuc (float) – The nucleation temperature.
phase_sym (PhaseInfo) – High-temperature phase information.
phase_bro (PhaseInfo) – Low-temperature phase information.
vw (float) – Bubble wall velocity.
verbose (bool, optional) – Whether to emit diagnostic messages.

Returns:

The approximate percolation temperature.

Return type:

float

transitionlistener.bubbledynamics.calcBetaH(T, Sint, outdict, pot, phase_sym, phase_bro, verbose=False)¶

Calculate the phase transition speed from the action derivative.

Parameters:

T (float) – The temperature at which to evaluate beta/H
Sint (interpolate.interp1d) – Interpolation function of the action
outdict (dict) – Dictionary storing the action evaluations, key is T
pot (generic_potential) – The effective potential object
phase_sym (PhaseInfo) – Information about the high temperature (symmetric) phase
phase_bro (PhaseInfo) – Information about the low temperature (broken) phaes

Returns:

The transition speed beta/H.

Return type:

float

transitionlistener.bubbledynamics.calcBetaHapprox(T, outdict, pot, phase_sym, phase_bro, tmin, tmax, verbose=False)¶: Calculate the betaH parameter at temperature T using the derivative of the bounce action with respect to the temperature.

transitionlistener.bubbledynamics.calcMeanBubbleSeparation(T, Tmax, Sint, Pint, Hint)¶

Calculate the mean bubble separation at temperature T.

Parameters:

T (float) – Symmetric phase temperature
Tmax (float) – Upper limit of the integral, usually the nucleation temperature
phase_sym (scipy.interpolate.interp1d object) – The symmetric phase
Sint (scipy.interpolate.interp1d object) – The action
Pint (scipy.interpolate.interp1d object) – The true vacuum fraction.
Hint (scipy.interpolate.interp1d object) – The Hubble rate

Returns:

R – Mean bubble separation.

Return type:

float

transitionlistener.bubbledynamics.calcMeanBubbleSeparationwExp(T, Tmax, Sint, Pint, Hint, CSint, SFRint)¶

Calculate the mean bubble separation at temperature T. Include the effect of cosmic expansion.

Parameters:

T (float) – Symmetric phase temperature
Tmax (float) – Upper limit of the integral, usually the nucleation temperature
phase_sym (scipy.interpolate.interp1d object) – The symmetric phase
Sint (scipy.interpolate.interp1d object) – The action
Pint (scipy.interpolate.interp1d object) – The true vacuum fraction.
Hint (scipy.interpolate.interp1d object) – The Hubble rate
CSint (scipy.interpolate.interp1d object) – The sound speed squared
SRFint (scipy.interpolate.interp1d object) – The scale factor ratio

Returns:

R – Mean bubble separation.

Return type:

float

transitionlistener.bubbledynamics.calcPercAndEvolve(outdict, Tnuc, phase_symmetric, phase_broken, pot, vw=1.0, rtol=0.0001, nAction=50, verbose=False)¶

Calculate the percolation temperature iteratively. The function assumes that the dark sector and the SM are in thermal equilibrium during the phase transition. First, the function calculates the approximate percolation temperature using the function calcApproxPercolation assuming P = 0 in the computation of the Hubble parameter and using the saddlepoint approximation, i.e. assuming a quickly growing bubble nucleation rate. Then, it computes the percolation temperature by actually solving the percolation integral, assuming that P = 0 at all times, such that the computation of the Hubble rate is simplified. Next, the function refines the percolation temperature by solving the percolation integral with the Hubble rate with the previously calculated P. The function returns the percolation temperature, if it converged, the symmetric phase temperature, the Hubble parameter, the true vacuum fraction, the broken phase temperature, and the action.

Parameters:

outdict (dict) – Dict storing the tunneling information.
Tnuc (float) – Nucleation temperature of the dark sector
phase_symmetric (PhaseInfo) – Phi of the broken phase as function of TDS
phase_broken (PhaseInfo) – Phi of the broken phase as function of TDS
pot (generic_potential) – The effective potential object
vw (float, optional) – The bubble wall velocity
rtol (float, optional) – Desired relative error in the percolation temperature
nAction (int, optional) – Number of action evaluations
verbose (bool, optional) – Set the output level.

Returns:

Tperc (float) – The percolation temperature in the DS.
TSYM (ndarray) – The symmetric phase temperature from Tnuc til Tperc
Hr (ndarray) – The Hubble parameter from Tnuc til Tperc
Pr (ndarray) – The true vacuum fraction from Tnuc til Tperc
Tb (ndarray) – The broken phase temperature (also SM temperature)
Sr (ndarray) – The action from Tnuc til Tperc

transitionlistener.bubbledynamics.calcSoundSpeedSq(pot, X, T)¶

Compute the sound speed squared.

Note: Decoupled degrees of freedom do not enter here.

Return type:: float

transitionlistener.bubbledynamics.calcTf(Tperc, Tlow, Pint, pot, verbose=False)¶

Calculate the final temperature at which the transition ends.

Parameters:

Tperc (float) – Symmetric phase percolation temperature, i.e. maximally possible value of the final temperature
Tlow (float) – Lowest temperature considered in the percolation computation. At this temperature, the true vacuum fraction Pint is >= f_final ~ 0.99. The final temperature must thus be <= Tlow.
phase_sym (scipy.interpolate.interp1d object) – The symmetric phase
Sint (scipy.interpolate.interp1d object) – The action
Pint (scipy.interpolate.interp1d object) – The true vacuum fraction.

Returns:

Tf – Final temperature.

Return type:

float

transitionlistener.bubbledynamics.checkNucleationPossibility(Tmin, Tmax, args, outdict, V, dV, start_phase, end_phase, conversionFactor, apprx_strength_thr, verbose)¶

Do some checks to see if tunneling is possible.

Parameters:: tr (TransitionInfo) – The transition information
Returns:: (True, {}) if possible otherwise, (False, {returndict}).
Return type:: tuple[bool, dict]

transitionlistener.bubbledynamics.computeNucleationTemperature(V, dV, d2V, start_phase, end_phase, CF, Ttol=1e-08, maxiter=100, phitol=1e-08, overlapAngle=45.0, nuclCriterion=<function <lambda>>, approximate_strength_threshold=0.0001, verbose=False, fullTunneling_params={})¶

Find the instanton and nucleation temperature for tunneling from start_phase to end_phase.

Parameters:

V (callable) – The potential V(x,T) and its gradient.
dV (callable) – The potential V(x,T) and its gradient.
start_phase (PhaseInfo) – The metastable phase from which tunneling occurs.
end_phase (PhaesInfo) – The destination phase.
Tmax (float) – The highest temperature at which to try tunneling.
Ttol (float, optional) – Tolerance for finding the nucleation temperature.
maxiter (int, optional) – Maximum number of times to try tunneling.
phitol (float, optional) – Tolerance for finding the minima.
overlapAngle (float, optional) – If two phases are in the same direction, only try tunneling to the closer one. Set to zero to always try tunneling to all available phases.
nuclCriterion (callable) – Function of the action S and temperature T. Should return 0 for the correct nucleation rate, > 0 for a low rate and < 0 for a high rate. Defaults to S/T - 140.
verbose (bool) – If true, print a message before each attempted tunneling.
fullTunneling_params (dict) – Parameters to pass to pathDeformation.fullTunneling().

Returns:

dict or None
A description of the tunneling solution at the nucleation temperature,
or None if there is no found solution. Has the following keys
- *Tnuc* (the nucleation temperature)
- *low_vev, high_vev* (vevs for the low-T phase (the phase that the) – instanton tunnels to) and high-T phase (the phase that the instanton tunnels from).
- *low_phase, high_phase* (identifier keys for the low-T and high-T) – phases.
- *action* (The Euclidean action of the instanton.)
- *instanton* (Output from pathDeformation.fullTunneling(), or) – None for a second-order transition.
- *trantype* (1 or 2 for first or second-order transitions.)

transitionlistener.bubbledynamics.computeNucleationTemperature2(tr, V, dV, d2V, start_phase, end_phase, Tmax, conversionFactor, Ttol=1e-08, maxiter=100, phitol=1e-08, overlapAngle=45.0, nuclCriterion=<function <lambda>>, approximate_strength_threshold=0.0001, verbose=False, fullTunneling_params={})¶

Refactored version of computeNucleationTemperature Find the instanton and nucleation temeprature for tunneling from start_phase to end_phase.

Parameters:

tr (TransitionInfo) – Object containing the transition informations
V (callable) – The potential V(x,T) and its gradient.
dV (callable) – The potential V(x,T) and its gradient.
d2V (callable) – The potential V(x,T) and its gradient.
start_phase (PhaseInfo) – The metastable phase from which tunneling occurs.
end_phase (PhaesInfo) – The destination phase.
Tmax (float) – The highest temperature at which to try tunneling.
Ttol (float, optional) – Tolerance for finding the nucleation temperature.
maxiter (int, optional) – Maximum number of times to try tunneling.
phitol (float, optional) – Tolerance for finding the minima.
overlapAngle (float, optional) – If two phases are in the same direction, only try tunneling to the closer one. Set to zero to always try tunneling to all available phases.
nuclCriterion (callable) – Function of the action S and temperature T. Should return 0 for the correct nucleation rate, > 0 for a low rate and < 0 for a high rate. Defaults to S/T - 140.
verbose (bool) – If true, print a message before each attempted tunneling.
fullTunneling_params (dict) – Parameters to pass to pathDeformation.fullTunneling().

Returns:

dict or None
A description of the tunneling solution at the nucleation temperature,
or None if there is no found solution. Has the following keys
- *Tnuc* (the nucleation temperature)
- *low_vev, high_vev* (vevs for the low-T phase (the phase that the) – instanton tunnels to) and high-T phase (the phase that the instanton tunnels from).
- *low_phase, high_phase* (identifier keys for the low-T and high-T) – phases.
- *action* (The Euclidean action of the instanton.)
- *instanton* (Output from pathDeformation.fullTunneling(), or) – None for a second-order transition.
- *trantype* (1 or 2 for first or second-order transitions.)

transitionlistener.bubbledynamics.energyDensity(pot, phase, T, include_decoupled=True)¶

This function calls the implementation in the effective potential.

Parameters:

pot (generic_potential) – Effective potential
phase (PhaseInfo) – The phase information
T (float|np.ndarray) – The temperature at which to compute the energy density
include_decoupled (bool, optional) – If true, also account for the energy density in a decoupled sector

Returns:

The energy density at T.

Return type:

float|np.ndarray

transitionlistener.bubbledynamics.energy_criterion_BRO(TBRO, eSYM, eBRO_start, P, dP, phase_broken, pot)¶

Calculate the temperature in the broken phase that results from the reheating by converting dP of the false vacuum into true vacuum.

Parameters:

TBRO (float) – Temperature to solve for.
eSYM (float) – Energy density in the symmetric phase
eBRO_start (float) – Initial energy density in broken phase
P (float) – True vacuum fraction
dP (float) – Change in the true vacuum fraction
phase_broken (PhaseInfo) – Information about the end phase.
pot (generic_potential)

Returns:

Zero when the criterion is fulfilled.

Return type:

float

transitionlistener.bubbledynamics.entropy_criterion_SYM_BRO(Tb, TBRO_ref, TSYM, TSYM_ref, phase_broken, pot)¶

Calculate the temperature of the dark sector broken phase in terms of the symmetric phase temperature. Only valid when entropy is conserved between reference temperature and TSYM.

Parameters:

Tb (float) – Temperature in the broken phase.
TBRO_ref (float) – Reference temperature of DS from which on entropy is conserved.
TSYM (float) – SYM temperature for which we want to know TDS(TSM).
TSYM_ref (float) – Reference temperature of SYM from which on entropy is conserved.
phase_broken (PhaseInfo) – Phase information about the end (broken) phase.
pot (generic_potential)

Returns:

Zero when the condition is met.

Return type:

float

transitionlistener.bubbledynamics.evalNucleationCriterion(T, start_phase, end_phase, V, dV, d2V, phitol, overlapAngle, nuclCriterion, fullTunneling_params, verbose, outdict, conversionFactor)¶

Find the lowest action tunneling solution.

Return nuclCriterion(S,T), and store a dictionary describing the transition in outdict for key T.

transitionlistener.bubbledynamics.findLocalMinimum(X, T, dV, d2V, phitol=1e-06, step_size=0.1)¶

Find the local minimum with the algorithm developed in BSMPT

\[ \begin{align}\begin{aligned}\vec{\epsilon} = H^{-1}\nabla V\\\vec{\phi}_{min}^{i+1} = \vec{\phi}_{min}^i - \vec{\epsilon}\end{aligned}\end{align} \]

Parameters:

X (np.ndarray) – The initial guess for the location of the minimum
T (float) – Temperature
dV (callable) – Gradient of the potenital $\nabla V(X, T)$
d2V (callable) – Hessian matrix of the potenital $\partial^2 V(X,T)/\partial \phi_i\partial\phi_j$
phitol (float) – The desired accuracy of the minimum
step_size (float) – The multiplyier controlling the step size in the direction of the minimum.

Returns:

The minimum.

Return type:

np.ndarray

transitionlistener.bubbledynamics.findTminFromUShapedNucl(Tmin, Tmax, args, start_phase, end_phase, outdict, Ttol, maxiter, CF, verbose, nuclCriterion)¶

Find the minimum of the nucleation criterion between Tmin and Tmax

Returns:: Temperature of the minimum of the nucleation criterion. If it is a hidden second order transition, return None
Return type:: float | None

transitionlistener.bubbledynamics.findTunnelingTmax(DV, Tmin, Tmax, tol=1e-15, maxiter=100)¶

Finds the largest temperature Tmax in [Tmin, Tmax] such that V(start_phase.valAt(T), T) > V(end_phase.valAt(T), T).

Important: tol=1e-15 is required to to find the right Tmax,: tol=1e-8 is not enough!

Parameters:

DV (callable)
Tmin (float)
Tmax (float)
tol (float, optional)
maxiter (int, optional)

Returns:

The maximal temperature where V(start_phase, Tmax) > V(end_phase, Tmax).

Return type:

float

transitionlistener.bubbledynamics.g_eff_DS(T_DS, pot, phase)¶

Calculate the effective energy degrees of freedom in the dark sector.

Parameters:

T (float) – Temperature at which to evaluate g_eff
pot (generic_potential) – The effetive potential object
phase (PhaseInfo) – The phase of the system, either symmetric or broken.

Returns:

Effective degrees of freedom in the dark sector.

Return type:

float

transitionlistener.bubbledynamics.h_eff_DS(T_DS, pot, phase)¶

Calculate the effective entropy degrees of freedom in the dark sector.

Parameters:

T (float) – Temperature at which to evaluate g_eff
pot (generic_potential) – The effetive potential object
phase (PhaseInfo) – The phase of the system, either symmetric or broken.

Returns:

geff – Effective degrees of freedom in the dark sector.

Return type:

float

transitionlistener.bubbledynamics.logGamma(T, S)¶

Calculate the log10 of the bubble nucleation rate.

Parameters:

T (float | np.ndarray) – Symmetric phase temperature
S (float | np.ndarray) – The action at temperature T

Returns:

Gamma – The bubble nucleation rate.

Return type:

np.ndarray

transitionlistener.bubbledynamics.makeSecondOrderDict(transition, conversionFactor)¶

Create a dictionary describing a second-order phase transition.

Return type:: dict

transitionlistener.bubbledynamics.percIntegral(T, H, S, vw=1.0)¶

Perform the percolation integral beteen Tstart and Tend.

Parameters:

T (np.ndarray) – Temperature of the dark sector symmetric phase. It must start with the nucleation temperature and go down to the percolation temp.
H (np.ndarray) – Hubble rate evaluated at T
S (np.ndarray) – S3 Euclidian bounce action evaluated at T
vw (float)

Returns:

The integral evaluated at the last temperature T[-1].

Return type:

float

transitionlistener.bubbledynamics.percIntegralwExp(T, H, S, scaleF_ratio, soundSpeedSq, vw=1.0)¶

Perform the percolation integral beteen Tstart and Tend. Take the expansion of the universe into account.

Parameters:

T (np.ndarray) – Temperature of the dark sector symmetric phase. It must start with the nucleation temperature and go down to the percolation temp.
H (np.ndarray) – Hubble rate evaluated at T
S (np.ndarray) – S3 Euclidian bounce action evaluated at T
vw (float)

Returns:

The integral evaluated at the last temperature T[-1].

Return type:

float

transitionlistener.bubbledynamics.scalefactorRatio(pot, T1, T2, X)¶

Compute the scalefactor ratio a(T1)/a(T2)

Return type:: float

Model-independent potential definitions¶

Tunneling pathfinding and bubble profiles¶

A module for finding instantons between vacua in multiple field dimensions.

The basic strategy is an iterative process:

Make an ansatz for the path along which the field will travel.

Split up the equations of motion into components that are parallel and perpendicular to the direction of travel along the path.

The direction of motion parallel to the path reduces to a one-dimensional equation of motion, which can be solved using the overshoot / undershoot techniques in tunneling1D. Solve it.

Treating the motion of the field as a classical particle moving in an inverted potential, calculate the normal forces that would need to act on the particle to keep it on the path. If this forces are (close enough to) zero, the ansatz was correctly. Otherwise iteratively deform the path in the direction of the normal forces, stopping when the forces go to zero.

Loop back to step 3 until no further deformation is necessary.

The classes Deformation_Spline and Deformation_Points will perform step 3, while fullTunneling() will run the entire loop.

For more explicit details, see the original paper Comput. Phys. Commun. 183 (2012) [arXiv:1109.4189].

class transitionlistener.pathDeformation.Deformation_Points(phi, dphidr, dV, fix_start=False, fix_end=False, save_all_steps=False)¶

Bases: object

Deform a path in the presence of a potential such that the normal forces along the path are zero.

Unlike Deformation_Spline, this class changes the points themselves rather than fitting a spline to the points. It is a more straightforward implementation, and when run with comparable inputs (i.e., the number of basis splines is about the same as the number of points), this method tends to be somewhat faster. The individual stepsizes here change with the total number of points, whereas in the spline implementation they mostly depend on the number of basis functions. However, as long as the path is fairly smooth, the total number of splines in that class can probably be smaller than the total number of points in this class, so this class will tend to be somewhat slower.

The two implementations should converge upon the same answer when the number of points and basis functions get large.

Parameters:

phi (array_like) – The list of points that constitutes the original path. Should have shape (n_points, n_dimensions).
dphidr (array_like) – The ‘speed’ along the path at the initial points. This does not change as the path deforms. Should have shape (n_points,). Gets saved into the attribute self.v2 as v2 = dphidr[:,np.newaxis]**2.
dV (callable) – The potential gradient as a function of phi. The output shape should be the same as the input shape, which will be (..., n_dimensions).
fix_start (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.
fix_end (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.
save_all_steps (bool, optional) – If True, each step gets saved into self.phi_list and self.F_list.

phi¶

Set during initialization, and then rewritten at each step.

Type:: array_like

num_steps¶

Total number of steps taken.

Type:: int

deformPath(startstep=0.1, minstep=1e-06, step_increase=1.5, fRatioConv=0.02, converge_0=5.0, fRatioIncrease=20.0, maxiter=500, verbose=0, callback=None, step_params={})¶

Deform the path many individual steps, stopping either when the convergence criterium is reached, when the maximum number of iterations is reached, or when the path appears to be running away from convergence.

Parameters:

startstep (float, optional) – Starting and maximum stepsizes used in step(), rescaled by |phi[0]-phi[1]| / (max(dV)*num_points).
maxstep (float, optional) – Starting and maximum stepsizes used in step(), rescaled by |phi[0]-phi[1]| / (max(dV)*num_points).
fRatioConv (float, optional) – The routine will stop when the maximum normal force on the path divided by the maximum potential gradient is less than this.
converge_0 (float, optional) – On the first step, use a different convergence criterion. Check if fRatio < convergence_0 * fRatioConv.
fRatioIncrease (float, optional) – The maximum fractional amount that fRatio can increase before raising an error.
maxiter (int, optional) – Maximum number of steps to take (ignoring reversed steps).
verbose (int, optional) – If verbose >= 1, print the ending condition. If verbose >= 2, print fRatio and stepsize at each step.
callback (callable, optional) – Called after each step. Should accept an instance of this class as a parameter, and return False if deformation should stop.
step_params (dict, optional) – Parameters to pass to step().

Returns:

deformation_converged – True if the routine stopped because it converged (as determined by fRatioConv), False otherwise.

Return type:

bool

forces(phi=None)¶

Calculate the normal force and potential gradient on the path.

Returns:: F_norm, dV
Return type:: array_like

step(stepsize, minstep, diff_check=0.1, step_decrease=2.0)¶

Take two half-steps in the direction of the normal force.

Parameters:

stepsize (float) – Determines change in phi: phi += F_norm*stepsize.
minstep (float) – The smallest the stepsize is allowed to be.
diff_check (float, optional) – The stepsize is chosen such that difference between the forces at beginning of the step and halfway through the step is small compared to the force itself: max(F2-F1) < diff_check * max(F1), where max here really means the maximum absolute value of the force in each direction.
step_decrease (float, optional) – Amount by which to decrease the stepsize if the step is too big.

Returns:

stepsize (float) – The stepsize used for this step.
fRatio (float) – The ratio of the maximum normal force to the maximum potential gradient. When the path is a perfect fit, this should go to zero.

class transitionlistener.pathDeformation.Deformation_Spline(phi, dphidr, dV, nb=10, kb=3, v2min=0.0, fix_start=False, fix_end=False, save_all_steps=False)¶

Bases: object

Deform a path in the presence of a potential such that the normal forces along the path are zero.

This class fits a spline to the points, and does the actual deformation on the spline rather than on the points themselves. This make the path somewhat smoother than it would otherwise be (which is generally desirable), but it does make it difficult to resolve sharp turns in the path.

Parameters:

phi (array_like) – The list of points that constitutes the original path. Should have shape (n_points, n_dimensions).
dphidr (array_like) – The ‘speed’ along the path at the initial points. This does not change as the path deforms. Should have shape (n_points,). Gets saved into the attribute v2 as v2 = dphidr[:,np.newaxis]**2.
dV (callable) – The potential gradient as a function of phi. The output shape should be the same as the input shape, which will be (..., n_dimensions).
nb (int, optional) – Number of basis splines to use.
kb (int, optional) – Order of basis splines.
v2min (float, optional) – The smallest the square of dphidr is allowed to be, relative to the characteristic force exterted by F_ext. Note that the self-correcting nature of the deformation goes away when dphidr=0.
fix_start (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.
fix_end (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.
save_all_steps (bool, optional) – If True, each step gets saved into self.phi_list and self.F_list.

phi¶

Set during initialization, and then rewritten at each step.

Type:: array_like

num_steps¶

Total number of steps taken.

Type:: int

deformPath(startstep=0.002, fRatioConv=0.02, converge_0=5.0, fRatioIncrease=5.0, maxiter=500, verbose=False, callback=None, step_params={})¶

Parameters:

startstep (float, optional) – Starting stepsize used in step().
fRatioConv (float, optional) – The routine will stop when the maximum normal force on the path divided by the maximum potential gradient is less than this.
converge_0 (float, optional) – On the first step, use a different convergence criterion. Check if fRatio < convergence_0 * fRatioConv.
fRatioIncrease (float, optional) – The maximum fractional amount that fRatio can increase before raising an error.
maxiter (int, optional) – Maximum number of steps to take (ignoring reversed steps).
verbose (bool, optional) – If True, print the ending condition.
callback (callable, optional) – Called after each step. Should accept an instance of this class as a parameter, and return False if deformation should stop.
step_params (dict, optional) – Parameters to pass to step().

Returns:

deformation_converged – True if the routine stopped because it converged (as determined by fRatioConv), False otherwise.

Return type:

bool

forces()¶

Calculate the normal force and potential gradient on the path.

Returns:: F_norm, dV
Return type:: array_like

step(lastStep, maxstep=0.1, minstep=0.0001, reverseCheck=0.15, stepIncrease=1.5, stepDecrease=5.0, checkAfterFit=True, verbose=False)¶

Deform the path one step.

Each point is pushed in the direction of the normal force - the force that the path exerts on a classical particle moving with speed dphidr in a potential with gradient dV such that the particle stays on the path. A stepsize of 1 corresponds to moving the path an amount L*N/(dV_max), where L is the length of the (original) path, N is the normal force, and dV_max is the maximum force exerted by the potential along the path.

Parameters:

lastStep (float) – Size of the last step.
maxstep (float, optional)
minstep (float, optional)
reverseCheck (float, optional) – Percentage of points for which the force can reverse direcitons (relative to the last step) before the stepsize is decreased. If reverseCheck >= 1, the stepsize is kept at lastStep.
stepIncrease (float, optional) – The amount to increase or decrease stepsize over the last step. Both should be bigger than 1.
stepDecrease (float, optional) – The amount to increase or decrease stepsize over the last step. Both should be bigger than 1.
checkAfterFit (bool, optional) – If True, the convergence test is performed after the points are fit to a spline. If False, it’s done beforehand.
verbose (bool, optional) – If True, output is printed at each step.

Returns:

stepsize (float) – The stepsize used for this step.
step_reversed (bool) – True if this step was reversed, otherwise False
fRatio (float) – The ratio of the maximum normal force to the maximum potential gradient. When the path is a perfect fit, this should go to zero. If checkAfterFit == True, the normal force in this ratio is defined by the change in phi this step after being fit to a spline. Note that if the spline does a poor job of fitting the points after the deformation in this step (which might be the case if there are not enough basis functions), and if checkAfterFit == False, this ratio can be non-zero or large even if there is no change in phi.

Notes

In prior versions of this function (CosmoTransitions v1.0.2 and earlier), the start and end points of the path were effectively held fixed during the main deformation. This was because the line phi_lin = phi[:1] + ... was calculated before the line phi = phi+F*stepsize. Since the spline basis functions are zero at the start and end points (the spline is added on top of the straight line between the end points), when the points were later taken from the spline the end points wouldn’t move. This was by design, since for thin-walled bubbles the endpoints should stay fixed at the two vacua. However, this caused problems for thick-walled bubbles where the end points should move.

To get around this, prior versions added an extra block of code to move the end points before the main deformation. However, this was unnecessarily complicated and led to error-prone code. In this version, the end points are always allowed to move if the force F is non-zero. In the thin-walled case, the force should be almost exactly zero at the end points anyways (there is zero potential gradient and dphidr is zero), so they should stay fixed on their own.

class transitionlistener.pathDeformation.SplinePath(pts, V, dV=None, V_spline_samples=100, extend_to_minima=False, reeval_distances=True, verbose=False)¶

Bases: object

Fit a spline to a path in field space, and find the potential on that path.

The spline-fitting happens in several steps:

The derivatives of the input points are found, and used to determine the path length and direction at each point.

If extend_to_minima is True, additional points are added at each end of the path such that ends lie on local minima.

The points are fit to a spline, with the knots given by the path distances from the first point.

If reeval_distances is True, the distances to each point are re-evaluated using the spline. A new spline is fit with more accurate knots.

The potential as a function of distance can be defined in one of two ways. If V_spline_samples is None, the potential as a function of distance x along the path is given by V[pts(x)], where pts(x) is the spline function that defines the path. If V_spline_samples is not None, the potential is first evaluated V_spline_samples times along the path, and another spline is fit to the output. In other words, when V_spline_samples is None, the input potential V is evaluated for every value x passed to to the class method V(), whereas if V_spline_samples is not None, the input potential is only evaluated during initialization.

Parameters:

pts (array_like) – The points that describe the path, with shape (num_points, N_dim).
V (callable) – The potential function. Input arrays will be shape (npts, N_dim) and output should have shape (npts,). Can be None.
dV (callable, optional.) – The gradient of the potential. Input arrays will be shape (npts, N_dim) and output should have shape (npts, N_dim). Only used if V_spline_samples=None.
V_spline_samples (int or None, optional) – Number of samples to take along the path to create the spline interpolation functions. If None, the potential is evaluated directly from V given in the input. If not None, V_spline_samples should be large enough to resolve the smallest features in the potential. For example, the potential may have a very narrow potential barrier over which multiple samples should be taken.
extend_to_minima (bool, optional) – If True, the input path is extended at each end until it hits local minima.
reeval_distances (bool, optional) – If True, get more accurate distances to each knot by integrating along the spline.

L¶

The total length of the path.

Type:: float

V(x)¶: The potential as a function of the distance x along the path.

d2V(x)¶: d^2V/dx^2 as a function of the distance x along the path.

dV(x)¶: dV/dx as a function of the distance x along the path.

pts(x)¶: Returns the path points as a function of the distance x along the path. Return value is an array with shape (len(x), N_dim).

class transitionlistener.pathDeformation.TunnelingOutputs(path, tobj, profile1D, phi, dphi, pts, deform_obj, converged)¶

Bases: object

Intermediate data collected during a single deformation iteration.

converged: bool¶

deform_obj: Deformation_Spline¶

dphi: ndarray¶

path: SplinePath¶

phi: ndarray¶

profile1D: object¶

pts: ndarray¶

tobj: object¶

class transitionlistener.pathDeformation.TunnelingSettings(V_spline_samples, tunneling_class, tunneling_init_params, tunneling_findProfile_params, deformation_class, deformation_init_params, deformation_deform_params, save_all_steps, verbose, callback, callback_data)¶

Bases: object

Configuration bundle passed around the full tunnelling workflow.

V_spline_samples: int | None¶

callback: Optional[Callable]¶

callback_data: object¶

deformation_class: type¶

deformation_deform_params: dict¶

deformation_init_params: dict¶

save_all_steps: bool¶

tunneling_class: type¶

tunneling_findProfile_params: dict¶

tunneling_init_params: dict¶

verbose: bool¶

transitionlistener.pathDeformation.bounceAction(T, V, dV, outdict, tdict, verbose=False, conversionFactor=1.0, **fullTunneling_params)¶

Compute the 1D bounce action and update the tunnelling dictionaries.

Parameters:

T (float) – Temperature at which to compute the bounce action.
V (callable) – Potential function. Input arrays have shape (num_points, N_dim) and the output should have shape (num_points,).
dV (callable) – Gradient of the potential with the same input shape as V. The output should have shape (num_points, N_dim).
outdict (dict) – A dictionary mapping temperatures to tunnelling results. If the result for temperature T is already in this dictionary, it is returned immediately.
tdict (dict) – Dictionary describing the tunnelling phase at temperature T. Must contain the keys 'low_vev' and 'high_vev' for the field values of the two minima.
verbose (bool, optional) – If True, print diagnostic messages while computing the bounce action.
conversionFactor (float, optional) – Factor to convert the temperature from internal units to GeV when printing messages.
fullTunneling_params (dict, optional) – Extra parameters to pass to fullTunneling(). The function accepts them via **fullTunneling_params and forwards the dictionary.

Returns:

outdict – The updated output dictionary, with the result for temperature T stored under that key.

Return type:

dict

transitionlistener.pathDeformation.bounceSolution(pot, T, xstart, xend, verbose=False)¶

Compute the instanton solution for tunneling from xstart to xend. Return the action and the instanton solution (bubble profile).

Parameters:

pot (generic_potential) – Effective potential
T (float) – Temperature at which to compute the bounce action.
xstart (np.ndarray) – high temperature minimum
xend (np.ndarray) – low temperature minimum
verbose (bool, optional) – If True, print diagnostic messages while computing the bounce action.

Returns:

profile1D (namedtuple) – The return value from tunneling_class.findProfile().
Phi (array_like) – The points that constitute the final deformed path. They are in one-to-one correspondence with the points in profile1D.
action (float) – The Euclidean action of the instanton.
fRatio (float) – A ratio of the largest transverse force on the final path relative to the largest potential gradient. This would be zero if the solution were perfect.
saved_steps (list) – A list of lists, with each sub-list containing the saved steps for each deformation. Only written to if save_all_steps is True.

transitionlistener.pathDeformation.fullTunneling(path_pts, V, dV, maxiter=20, save_all_steps=False, verbose=False, callback=None, callback_data=None, V_spline_samples=100, tunneling_class=<class 'transitionlistener.tunneling1D.SingleFieldInstanton'>, tunneling_init_params=None, tunneling_findProfile_params=None, deformation_class=<class 'transitionlistener.pathDeformation.Deformation_Spline'>, deformation_init_params=None, deformation_deform_params=None)¶

Calculate the instanton solution in multiple field dimensions.

This function works by looping four steps:

Fit a spline to the path given by path_pts.

Calculate the one-dimensional tunneling along this path.

Deform the path to satisfy the transverse equations of motion.

Check for convergence, and then go back to step 1.

Parameters:

path_pts (array_like) – An array of points that constitute the initial guess for the tunneling path, with shape (num_points, N_dim). The first point should be at (or near) the lower minimum (the minimum to which the field is tunneling), and the last point should be at the metastable minimum.
V (callable) – The potential function and its gradient. Both should accept input of shape (num_points, N_dim) or (N_dim,).
dV (callable) – The potential function and its gradient. Both should accept input of shape (num_points, N_dim) or (N_dim,).
maxiter (int, optional) – Maximum number of allowed deformation / tunneling iterations.
save_all_steps (bool, optional) – If True, additionally output every single deformation sub-step.
verbose (bool, optional) – If True, print a message at the start of each step.
callback (callable, optional) – User supplied function that is evaluated just prior to deforming the path. Should return True if the path should be deformed, and False if the deformation should be aborted. Should accept 4 arguments: a SplinePath instance which describes the tunneling path, a tunneling object (instance of tunneling_class), the profile found by the tunneling object, and extra callback data.
callback_data (any type, optional) – Extra data to pass to the callback function if there is one.
V_spline_samples (int, optional) – Passed to SplinePath. If None, no second derivative will be passed to the tunneling class, and it will instead be evaluated using finite differences.
tunneling_class (class, optional) – Either tunneling1D.SingleFieldInstanton or a subclass.
tunneling_init_params (dict, optional) – Extra parameters to pass to the tunneling class.
tunneling_findProfile_params (dict, optional) – Extra parameters to pass to tunneling_class.findProfile().
deformation_class (class, optional) – Either Deformation_Spline or Deformation_Points, or some other object that exposes the same interface.
deformation_init_params (dict, optional) – Extra parameters to pass to the deformation class.
deformation_deform_params (dict, optional) – Extra parameters to pass to deformation_class.deformPath().

Returns:

profile1D (namedtuple) – The return value from tunneling_class.findProfile().
Phi (array_like) – The points that constitute the final deformed path. They are in one-to-one correspondence with the points in profile1D.
action (float) – The Euclidean action of the instanton.
fRatio (float) – A ratio of the largest transverse force on the final path relative to the largest potential gradient. This would be zero if the solution were perfect.
saved_steps (list) – A list of lists, with each sub-list containing the saved steps for each deformation. Only written to if save_all_steps is True.

Examples

The following code shows typical usage for fullTunneling(). Most of the code is in setting up the potentials and plotting; it only takes one line to actually calculate each instanton:

from transitionlistener.pathDeformation import fullTunneling
# ... set up potentials and phases ...
result = fullTunneling(
    path_pts,
    V,
    dV,
    save_all_steps=True,
    callback_data=Tnuc,
)
action = result.action
profile = result.profile1D
f_ratio = result.fRatio
steps = result.saved_steps

The callback function can be useful when this function is run from transitionFinder.findAllTransitions(). In that case, one does not need to accurately calculate the tunneling path when one knows that the action is already below some threshold. For example, the following callback function will abort the deformation when action / T <= 120:

def callback(path, tobj, profile, T):
    action = tobj.findAction(profile)
    return action / T > 120

Single-field bounce action calculations¶

This module (along with a few functions in helper_functions) contains everything that is needed to calculate instantons in one field dimension. The primary class is SingleFieldInstanton, which can calculate the instanton solution in any number of spatial dimensions using the overshoot / undershoot method. Additional classes inherit common functionality from this one, and can be used to calculate the bubble wall profile with constant friction (WallWithConstFriction) instead of radius-dependent friction, or to calculate the instanton in the presence of gravity (not yet implemented).

Todo

Create and document a CDL_Instanton class for tunneling with gravity.

class transitionlistener.tunneling1D.SingleFieldInstanton(phi_absMin, phi_metaMin, V, dV=None, d2V=None, phi_eps=0.001, alpha=2, phi_bar=None, rscale=None)¶

Bases: object

This class will calculate properties of an instanton with a single scalar Field without gravity using the overshoot/undershoot method.

Most users will probably be primarily interested in the functions findProfile() and findAction().

Note

When the bubble is thin-walled (due to nearly degenerate minima), an approximate solution is found to the equations of motion and integration starts close to the wall itself (instead of always starting at the center of the bubble). This way the overshoot/undershoot method runs just as fast for extremely thin-walled bubbles as it does for thick-walled bubbles.

Parameters:

phi_absMin (float) – The field value at the stable vacuum to which the instanton tunnels. Nowhere in the code is it required that there actually be a minimum at phi_absMin, but the findProfile() function will only use initial conditions between phi_absMin and phi_metaMin, and the code is optimized for thin-walled bubbles when the center of the instanton is close to phi_absMin.
phi_metaMin (float) – The field value in the metastable vacuum.
V (callable) – The potential function. It should take as its single parameter the field value phi.
dV (callable, optional) – The potential’s first and second derivatives. If not None, these override the methods dV() and d2V().
d2V (callable, optional) – The potential’s first and second derivatives. If not None, these override the methods dV() and d2V().
phi_eps (float, optional) – A small value used to calculate derivatives (if not overriden by the user) and in the function dV_from_absMin(). The input should be unitless; it is later rescaled by abs(phi_absMin - phi_metaMin).
alpha (int or float, optional) – The coefficient for the friction term in the ODE. This is also the number of spacetime dimensions minus 1.
phi_bar (float, optional) – The field value at the edge of the barrier. If None, it is found by findBarrierLocation().
rscale (float, optional) – The approximate radial scale of the instanton. If None it is found by findRScale().

Raises:

PotentialError – when the barrier is non-existent or when the presumably stable minimum has a higher energy that the metastable minimum.

Examples

The snippet below illustrates how to compute thin- and thick-walled instanton profiles. It depends on the optional cosmoTransitions package:

from cosmoTransitions.tunneling1D import SingleFieldInstanton
import matplotlib.pyplot as plt

# Thin-walled example
def V1(phi):
    return 0.25 * phi**4 - 0.49 * phi**3 + 0.235 * phi**2

def dV1(phi):
    return phi * (phi - 0.47) * (phi - 1.0)

profile = SingleFieldInstanton(1.0, 0.0, V1, dV1).findProfile()
plt.plot(profile.R, profile.Phi, label="Thin-walled")

# Thick-walled example
def V2(phi):
    return 0.25 * phi**4 - 0.4 * phi**3 + 0.1 * phi**2

def dV2(phi):
    return phi * (phi - 0.2) * (phi - 1.0)

profile = SingleFieldInstanton(1.0, 0.0, V2, dV2).findProfile()
plt.plot(profile.R, profile.Phi, label="Thick-walled")

plt.xlabel(r"Radius $r$")
plt.ylabel(r"Field $\phi$")
plt.legend()
plt.show()

d2V(phi)¶

Calculates d^2V/dphi^2 using finite differences.

The finite difference is given by self.phi_eps, and the derivative is calculated to fourth order.

dV(phi)¶

Calculates dV/dphi using finite differences.

The finite difference is given by self.phi_eps, and the derivative is calculated to fourth order.

dV_from_absMin(delta_phi)¶

Calculates dV/dphi at phi = phi_absMin + delta_phi.

It is sometimes helpful to find dV/dphi extremely close to the minimum. In this case, floating-point error can be significant. To get increased accuracy, this function expands about the minimum in a Taylor series and uses that for nearby values. That is, $V'(\phi) \approx V''(\phi_{\rm absMin})(\phi-\phi_{\rm absMin})$. For values that are farther away, it instead uses dV(). It blends the two methods so that there are no numerical discontinuities.

This uses self.phi_eps to determine whether the field is considered nearby or not.

equationOfMotion(y, r)¶: Used to integrate the bubble wall.

evenlySpacedPhi(phi, dphi, npoints=100, k=1, fixAbs=True)¶

This method takes phi and dphi as input, which will probably come from the output of findProfile(), and returns a different set of arrays phi2 and dphi2 such that phi2 is linearly spaced (instead of r).

Parameters:

phi (array_like)
dphi (array_like)
npoints (int) – The number of points to output.
k (int) – The degree of spline fitting. k=1 means linear interpolation.
fixAbs (bool) – If true, make phi go all the way to phi_absMin.

exactSolution(r, phi0, dV, d2V)¶

Find phi(r) given phi(r=0), assuming a quadratic potential.

Parameters:

r (float) – The radius at which the solution should be calculated.
phi0 (float) – The field at r=0.
dV (float) – The potential’s first and second derivatives evaluated at phi0.
d2V (float) – The potential’s first and second derivatives evaluated at phi0.

Returns:

phi, dphi – The field and its derivative evaluated at r.

Return type:

float

Notes

If the potential at the point $\phi_0$ is a simple quadratic, the solution to the instanton equation of motion can be determined exactly. The non-singular solution to

\[\frac{d^2\phi}{dr^2} + \frac{\alpha}{r}\frac{d\phi}{dr} = V'(\phi_0) + V''(\phi_0) (\phi-\phi_0)\]

\[\phi(r)-\phi_0 = \frac{V'}{V''}\left[ \Gamma(\nu+1)\left(\frac{\beta r}{2}\right)^{-\nu} I_\nu(\beta r) - 1 \right]\]

where $\nu = \frac{\alpha-1}{2}$, $I_\nu$ is the modified Bessel function, and $\beta^2 = V''(\phi_0) > 0$. If instead $-\beta^2 = V''(\phi_0) < 0$, the solution is the same but with $I_\nu \rightarrow J_\nu$.

findAction(profile)¶

Calculate the Euclidean action for the instanton:

\[S = \int [(d\phi/dr)^2 + V(\phi)] r^\alpha dr d\Omega_\alpha\]

Parameters:: profile – Output from findProfile().
Returns:: The Euclidean action.
Return type:: float

findBarrierLocation()¶

Find edge of the potential barrier.

Returns:: phi_barrier – The value such that V(phi_barrier) = V(phi_metaMin)
Return type:: float

findProfile(xguess=None, xtol=0.0001, phitol=0.0001, thinCutoff=0.01, npoints=500, rmin=0.0001, rmax=10000.0, max_interior_pts=None)¶

Calculate the bubble profile by iteratively over/undershooting.

This will call integrateProfile() many times, trying to find the correct initial condition phi(r=0) such that the field ends up in the metastable vacuum at infinity. Once the correct initial condition is found, it calls integrateAndSaveProfile() to find the profile along the length of the wall.

Parameters:

xguess (float, optional) – The initial guess for x. If None, xguess is set such that phi_guess = self.phi_bar.
xtol (float, optional) – Target accuracy in x.
phitol (float, optional) – Fractional error tolerance in integration.
thinCutoff (float, optional) – Equal to delta_phi_cutoff / (phi_metaMin - phi_absMin), where delta_phi_cutoff is used in initialConditions().
npoints (int) – Number of points to return in the profile.
rmin (float) – Relative to self.rscale. Sets the smallest starting radius, the starting stepsize, and the smallest allowed stepsize (0.01*rmin).
rmax (float) – Relative self.rscale. Sets the maximum allowed integration distance.
max_interior_pts (int) – Maximum number of points to place between r=0 and the start of integration. If None, max_interior_pts=npoints/2. If zero, no points are added to the bubble interior.

Returns:

R, Phi, dPhi (array_like) – Radii and field values which make up the bubble profile. Note that R[0] can be much bigger than zero for thin-walled bubbles.
Rerr (float or None) – The first value of r at which dr < drmin, or None if dr >= drmin always.

Notes

For very thin-walled bubbles, the initial value of phi can be extremely close to the stable minimum and small variations in phi can cause large variations in the integration. Rather than varying phi(r=0) directly, it is easier to vary a parameter x defined by

\[\phi(r=0) = \phi_{\rm absMin} + e^{-x}(\phi_{\rm metaMin}-\phi_{\rm absMin})\]

This way, phi = phi_metaMin when x is zero and phi = phi_absMin when x is infinity.

findRScale()¶

Find the characteristic length scale for tunneling over the potential barrier.

The characteristic length scale should formally be given by the period of oscillations about the top of the potential barrier. However, it is perfectly acceptable for the potential barrier to have a flat top, in which case a naive calculation of the length scale would be infinite. Instead, this function finds the top of the barrier along with a cubic function that has a maximum at the barrier top and a minimum at the metastable minimum. The returned length scale is then the period of oscillations about this cubic maximum.

Raises:: PotentialError – when the barrier is non-existent.

findRscaleNew(phimeta, phi0)¶

This estimates the time the field needs to roll down to the minimum by assuming a linear potential between phi0 and phimeta.

Parameters:

V (function) – Returns the potential at V(phi)
phi0 (float) – The field release point
phimeta (float) – The meta stable minimum of the potential
ndim (int) – Number of dimensions.
analytic (The)
equation (solution to the)
math:: (..)
b (frac{d^2phi}{dr^2} + frac{nu}{r}frac{dphi}{dr} =)
is
math::
r^2 (phi(r) = phi_0 + frac{b}{2(1+nu)})
down (Get the time that takes the field to roll)
potential. (a linear)

initialConditions(delta_phi0, rmin, delta_phi_cutoff)¶

Finds the initial conditions for integration.

The instanton equations of motion are singular at r=0, so we need to start the integration at some larger radius. This function finds the value r0 such that phi(r0) = phi_cutoff. If there is no such value, it returns the intial conditions at rmin.

Parameters:

delta_phi0 (float) – delta_phi0 = phi(r=0) - phi_absMin
rmin (float) – The smallest acceptable radius at which to start integration.
delta_phi_cutoff (float) – The desired value for phi(r0). delta_phi_cutoff = phi(r0) - phi_absMin.

Returns:

r0, phi, dphi – The initial radius and the field and its derivative at that radius.

Return type:

float

Notes

The field values are calculated using exactSolution().

integrateAndSaveProfile(R, y0, dr, epsfrac, epsabs, drmin, *eqn_args)¶

Integrate the bubble profile, saving the output in an array.

Parameters:

R (array_like) – The array of points at which we want to save the profile.
y0 (float) – The starting values [phi(r0), dphi(r0)].
dr (float) – Starting stepsize.
epsfrac (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs().
epsabs (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs().
drmin (float) – The smallest allowed stepsize.
eqn_args (tuple) – Extra arguments to pass to equationOfMotion(). Useful for subclasses.

Returns:

R, Phi, dPhi (array_like) – Radii and field values which make up the bubble profile.
Rerr (float or None) – The first value of r at which dr < drmin, or None if dr >= drmin always.

Notes

Subclasses can use this function without overriding it even if the subclass uses more fields/values in its equation of motion (i.e., len(y0) > 2). This is accomplished by setting the class variable profile_rval to a different named tuple type with more than four inputs. The first three should always be R, Phi, dPhi, and the last one should be Rerr, but additional values can be stuck in between.

integrateProfile(r0, y0, dr0, epsfrac, epsabs, drmin, rmax, *eqn_args)¶

Integrate the bubble wall equation:

\[\frac{d^2\phi}{dr^2} + \frac{\alpha}{r}\frac{d\phi}{dr} = \frac{dV}{d\phi}.\]

The integration will stop when it either overshoots or undershoots the false vacuum minimum, or when it converges upon the false vacuum minimum.

Parameters:

r0 (float) – The starting radius for the integration.
y0 (array_like) – The starting values [phi(r0), dphi(r0)].
dr0 (float) – The starting integration stepsize.
epsfrac (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs() and is used to test for convergence.
epsabs (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs() and is used to test for convergence.
drmin (float) – The minimum allowed value of dr before raising an error.
rmax (float) – The maximum allowed value of r-r0 before raising an error.
eqn_args (tuple) – Extra arguments to pass to equationOfMotion(). Useful for subclasses.

Returns:

r (float) – The final radius.
y (array_like) – The final field values [phi, dphi]
convergence_type (str) – Either ‘overshoot’, ‘undershoot’, or ‘converged’.

Raises:

helper_functions.IntegrationError –

profile_rval¶: alias of Profile1D

Finite temperature effective potentials¶

This module provides the functions for the one-loop finite temperature corrections to a potential in QFT. The two basic functions are:

Jb(x) = int[0->inf] dy +y^2 log( 1 - exp(-sqrt(x^2 + y^2)) )

Jf(x) = int[0->inf] dy -y^2 log( 1 + exp(-sqrt(x^2 + y^2)) )

Call them by:

Jb(x, approx=’high’, deriv=0, n = 8)

Here, approx can either be ‘exact’, ‘spline’, ‘high’, or ‘low’. Exact calculates the integral numerically, while high and low calculate the high and low x expansions of J to order n. Specify the derivative with the deriv parameter.

transitionlistener.finiteT.Jb(x, approx='high', deriv=0, n=8)¶

A shorthand for calling one of the Jb functions above.

Parameters:

approx (str, optional) – One of ‘exact’, ‘high’, ‘low’, or ‘spline’.
deriv (int, optional) – The order of the derivative (0 for no derivative). Must be <= (1, 3, 0, 3) for approx = (exact, high, low, spline).
n (int, optional) – Number of terms to use in the low and high-T approximations.

Return type:

float | ndarray

transitionlistener.finiteT.Jb_exact(x)¶

Jb calculated directly from the integral.

Return type:: complex | float

transitionlistener.finiteT.Jb_exact2(theta)¶

Jb calculated directly from the integral; input is theta = x^2.

Return type:: float

transitionlistener.finiteT.Jb_high(x, deriv=0, n=8)¶

Jb calculated using the high-x (low-T) expansion.

Return type:: float | ndarray

transitionlistener.finiteT.Jb_low(x, n=20)¶

Jb calculated using the low-x (high-T) expansion.

Return type:: complex | float

transitionlistener.finiteT.Jb_spline(X, n=0)¶

Jb interpolated from a saved spline. Input is (m/T)^2.

Return type:: float | ndarray

transitionlistener.finiteT.Jf(x, approx='high', deriv=0, n=8)¶

A shorthand for calling one of the Jf functions above.

Parameters:

approx (str, optional) – One of ‘exact’, ‘high’, ‘low’, or ‘spline’.
deriv (int, optional) – The order of the derivative (0 for no derivative). Must be <= (1, 3, 0, 3) for approx = (exact, high, low, spline).
n (int, optional) – Number of terms to use in the low and high-T approximations.

Return type:

float | ndarray

transitionlistener.finiteT.Jf_exact(x)¶

Jf calculated directly from the integral.

Return type:: complex | float

transitionlistener.finiteT.Jf_exact2(theta)¶

Jf calculated directly from the integral; input is theta = x^2.

Return type:: float

transitionlistener.finiteT.Jf_high(x, deriv=0, n=8)¶

Jf calculated using the high-x (low-T) expansion.

Return type:: float | ndarray

transitionlistener.finiteT.Jf_low(x, n=20)¶

Jf calculated using the low-x (high-T) expansion.

Return type:: complex | float

transitionlistener.finiteT.Jf_spline(X, n=0)¶: Jf interpolated from a saved spline. Input is (m/T)^2.

transitionlistener.finiteT.arrayFunc(f, x, typ=<class 'float'>)¶

Vectorise a scalar integrand helper so it accepts scalar or 1D arrays.

Parameters:

f (Callable[[float], float]) – Function that accepts and returns scalar values.
x (float | array-like) – Input argument. Arrays are handled element-wise, scalars are forwarded directly.
typ (type, optional) – Data type of the output array. Defaults to float.

Returns:

Array of evaluated values or the scalar return of f(x).

Return type:

numpy.ndarray | float

transitionlistener.finiteT.d2x2K2(k, x)¶

Return the second derivative of x2K2() with respect to x.

Return type:: float | ndarray

transitionlistener.finiteT.d3x2K2(k, x)¶

Return the third derivative of x2K2() with respect to x.

Return type:: float | ndarray

transitionlistener.finiteT.dJb_exact(x)¶

dJb/dx calculated directly from the integral.

Return type:: complex | float

transitionlistener.finiteT.dJf_exact(x)¶

dJf/dx calculated directly from the integral.

Return type:: complex | float

transitionlistener.finiteT.dx2K2(k, x)¶

Return the first derivative of x2K2() with respect to x.

Return type:: float | ndarray

transitionlistener.finiteT.x2K2(k, x)¶

Return -x^2 K_2(k x) / k^2 with analytic behaviour enforced at the origin, where K_2 is the modified Bessel function of the second kind.

Parameters:

k (int) – Positive integer
x (float | numpy.ndarray) – Dimensionless argument. Arrays are handled element-wise.

Returns:

Evaluated expression with the x -> 0 limit patched in.

Return type:

float | numpy.ndarray

Thermodynamics¶

Module containing routines to calculate thermodynamic quantities like the numberdensity, energy density, pressure and entropy density.

Author: Jonas Matuszak <jonas.matuszak@kit.edu>, 2024.

transitionlistener.thermodynamics.Sfit(x)¶

transitionlistener.thermodynamics.br(x)¶

transitionlistener.thermodynamics.bs(x)¶

transitionlistener.thermodynamics.calcEnergydensityIntegrals()¶: Tabulate geff for the energydensity

transitionlistener.thermodynamics.calcNumberdensityIntegrals()¶: Calculate geff for numberdensity

transitionlistener.thermodynamics.calcPressureIntegrals()¶: Pre-compute spline approximations of the pressure integrals.

transitionlistener.thermodynamics.e_geff(m, T, g, ptype)¶: Energy degrees of freedom, supports scalar or vector inputs for m and T.

transitionlistener.thermodynamics.e_geffDS(mSq_bosons, mSq_fermions, T)¶: Energy degrees of freedom of the dark sector, supports vectorized T.

transitionlistener.thermodynamics.e_geffSM(TSM, CF, mode='smooth')¶

Effective energy degrees of freedom of the SM at a given temperature.

Parameters:

TSM (float or np.ndarray) – Temperature in internal energy units.
CF (float) – Conversion factor to put everything in GeV.
mode (str, optional) – “smooth”, “fit” or “data”

Return type:

float | ndarray

transitionlistener.thermodynamics.fr(x)¶

transitionlistener.thermodynamics.fs(x)¶

transitionlistener.thermodynamics.geff_rho_h(T)¶

transitionlistener.thermodynamics.geff_rho_l(T, p1=1, p2=1)¶

transitionlistener.thermodynamics.geff_s_h(T)¶

transitionlistener.thermodynamics.geff_s_l(T, p1=1, p2=1)¶

transitionlistener.thermodynamics.nDensity(m, T, g, ptype)¶: Numberdensity from tabulated values.

transitionlistener.thermodynamics.p_geff(m, T, g, ptype)¶: Pressure degrees of freedom, supports scalar or vector inputs for m and T.

transitionlistener.thermodynamics.p_geffSM(TSM, CF, mode='smooth')¶

Effective pressure degress of freedom for the SM.

Parameters:

TSM (float or np.ndarray) – Temperature in internal energy units.
CF (float) – Conversion factor to put everything in GeV.
mode (str, optional) – Either “fit”, “smooth” or “data”.

Return type:

float | ndarray

transitionlistener.thermodynamics.p_geffSM_fit(TSM, CF)¶

Effective pressure degress of freedom for the SM.

Parameters:

TSM (float or np.ndarray) – Temperature in internal energy units.
CF (float) – Conversion factor to put everything in GeV.

Return type:

float | ndarray

transitionlistener.thermodynamics.ratio(T)¶

transitionlistener.thermodynamics.s_geff(m, T, g, ptype)¶: Entropy degrees of freedom, supports scalar or vector inputs for m and T.

transitionlistener.thermodynamics.s_geffDS(mSq_bosons, mSq_fermions, T)¶: Entropy degrees of freedom of the dark sector

transitionlistener.thermodynamics.s_geffSM(TSM, CF, mode='smooth')¶

Effective entropy degrees of freedom of the SM at a given temperature.

Parameters:

TSM (float or np.ndarray) – Temperature in internal energy units.
CF (float) – Conversion factor to put everything in GeV.
mode (str, optional) – “fit”, “smooth” or “data”.

Return type:

float | ndarray

transitionlistener.thermodynamics.set_sm_temperature_cap(CF, mSq_bosons=None, boson_is_SM=None, mSq_fermions=None, fermion_is_SM=None, verbose=False)¶

Initialise the SM temperature cap from the spectrum at the true minimum.

Parameters:

CF (float) – Conversion factor to GeV.
mSq_bosons (tuple, optional) – Spectra evaluated at the true vacuum.
mSq_fermions (tuple, optional) – Spectra evaluated at the true vacuum.
verbose (bool, optional) – Print a warning containing the lightest SM mass when saturation is applied.

Return type:

float | None

Bubble wall velocity and hydrodynamics¶

Gravitational wave spectra¶

Module to calculate the GW energy spectrum from the phase transition parameters.

class transitionlistener.gwfopt.FOPTspectrum(gwparams_dict, astroparams_dict, verbose=False)¶

Bases: object

Class to compute the gravitational wave spectrum from a first order phase transition.

BPL(f, fb, Omegab, n1, n2, a1)¶

A broken power law function, see 2403.03723 eq. (2.4)

Parameters:

f (float) – Frequency in Hz
fb (float) – Break frequency in Hz
Omegab (float) – Amplitude at fb
n1 (float) – Exponent before the break
n2 (float) – Exponent after the break
a1 (float) – Transition parameter at the break

Returns:

Broken power law function value at frequency f.

Return type:

float

DBPL(f, f1, f2, Omega2, n1, n2, n3, a1, a2)¶

A double broken power law function, see 2403.03723 eq. (2.8)

Parameters:

f (float) – Frequency in Hz
f1 (float) – First break frequency in Hz
f2 (float) – Second break frequency in Hz
Omega2 (float) – Amplitude at f2
n1 (float) – Exponent before the first break
n2 (float) – Exponent between the first and second break
n3 (float) – Exponent after the second break
a1 (float) – Transition parameter at the first break
a2 (float) – Transition parameter at the second break

Returns:

Double broken power law function value at frequency f.

Return type:

float

additional_spec_info(source='all', f_pivot_Hz=1e-08)¶

Calculate summary information about the GW spectrum.

Parameters:

source (str) – Source to consider for the GW spectrum. Options are "all", "Wall collisions", "Sound waves", "Turbulence".
f_pivot_Hz (float) – Pivot frequency in Hz to evaluate the spectral amplitude.

Returns:

Ordered dictionary containing linear, logarithmic and LaTeX labelled representations of each quantity describing the spectrum.

Return type:

OrderedDict[str, dict[str, float | str]]

h2Omega_0_sum(f_Hz, source='all')¶

State-of-the-art model for the GW spectrum from a FOPT.

Parameters:

f_Hz (float) – Frequency in Hz
source (str) – Source to consider for the GW spectrum. Options are “all”, “Wall collisions”, “Sound waves”, “Turbulence”.

Returns:

GW energy density spectrum value at frequency f_Hz.

Return type:

float

h2Omega_0_sum_old(f_Hz, source='all')¶

Alternative SW model as used in sub-gev paper and presented in LISA update paper. The remaining sources are described as in 1903.09642.

Parameters:

f_Hz (float) – Frequency in Hz
source (str) – Source to consider for the GW spectrum. Options are “all”, “Wall collisions”, “Sound waves”, “Turbulence”.

Returns:

GW energy density spectrum value at frequency f_Hz.

Return type:

float

h2Omega_PT_and_astro(f_Hz)¶

Calculate the total GW energy density spectrum from a first order phase transition and an astrophysical background.

Parameters:: f_Hz (float) – Frequency in Hz
Returns:: Total GW energy density spectrum value.
Return type:: float

h2Omega_astro_noise(f_Hz)¶

Calculate the astrophysical background noise spectrum in the power-law approximation, e.g. for supermassive black hole mergers in the nHz frequency range. Note that the below parameterization is specific to the PTA band and should not be used for other frequencies.

Parameters:: f_Hz (float) – Frequency in Hz
Returns:: Astrophysical noise spectrum value.
Return type:: float

keys()¶: Return the keys of the spectrum dictionary.

print_params()¶: Render a table with the gravitational wave and astrophysical parameters.

Observability at gravitational wave detectors¶

Sensitivity curves and observability metrics for gravitational wave experiments.

class transitionlistener.observability.GW_Sensitivity_Data¶

Bases: object

Class used to import the sensitivity data curves of GW observaories.

self.det_f¶

Frequencies from the detector data

Type:: float array

self.det_data¶

Detector sensitivity curves

Type:: float array

self.det_names¶

Deterctor names, ordered as in input file

Type:: string tuple

self.det_colors¶

Colors for the detector sensitivities in plots, ordered as in input file

Type:: string tuple

self.det¶

Dicitonary for the sensitivitie with the detector name as key

Type:: dictionary

self.det_thr¶

Expected detector threshold SNRs

Type:: float tuple

self.det_tobs¶

Expected detector observation times

Type:: float tuple

class transitionlistener.observability.Observability(gwspec_dict, verbose=False, include_smbhb=False)¶

Bases: GW_Sensitivity_Data

Compute SNRs, PTA likelihoods and derived quantities for a GW spectrum.

calc_DNeff_GW()¶: Compute the contribution to the effective number of relativistic species from GWs.

calc_PTA_logL()¶: Evaluate PTA log-likelihoods using PTArcade for the stored spectrum.

calc_PTA_logL_with_astronoise(A, gamma)¶: Evaluate PTA log-likelihoods including an astrophysical background.

calc_SNR()¶: Compute the signal-to-noise ratio for each detector sensitivity curve.

initialise_gw_info_dict()¶: Initialise an empty return object.

keys()¶: Expose the keys present in the observability dictionary.

print_additional_spec_info()¶: Render a table summarising derived GW spectrum properties.

return_gw_info_dict()¶: Collect SNRs, likelihoods and auxiliary info into a result dictionary.

class transitionlistener.observability.PTAConfig(nfreqBins=14, PTA='NG15')¶: Bases: object

class transitionlistener.observability.PTAModel(spectrum)¶: Bases: object

class transitionlistener.observability.PTAModel_SMBHB(spectrum)¶: Bases: object

Utilities and helpers¶

A collection of (mostly) stand alone helper functions.

exception transitionlistener.helper_functions.IntegrationError¶

Bases: Exception

Used to indicate an integration error, primarily in rkqs().

transitionlistener.helper_functions.Nbspl(t, x, k=3)¶

Calculate the B-spline basis functions for the knots t evaluated at the points x.

Parameters:

t (array_like) – An array of knots which define the basis functions.
x (array_like) – The different values at which to calculate the functions.
k (int, optional) – The order of the spline. Must satisfy k <= len(t)-2.

Returns:

Has shape (len(x), len(t)-k-1).

Return type:

array_like

Notes

This is fairly speedy, although it does spend a fair amount of time calculating things that will end up being zero. On a 2.5Ghz machine, it takes a few milliseconds to calculate when len(x) == 500; len(t) == 20; k == 3.

For more info on basis splines, see e.g. http://en.wikipedia.org/wiki/B-spline.

Examples

The example below demonstrates the bases for a cubic spline:

from transitionlistener.helper_functions import Nbspl
import numpy as np
import matplotlib.pyplot as plt

t = [-1, -1, -1, -1, -0.5, 0, 0.5, 1, 1, 1, 1]
x = np.linspace(-1, 1, 500)
y = Nbspl(t, x, k=3)
plt.plot(x, y)
plt.xlabel(r"$x$")
plt.ylabel(r"$y_i(x)$")
plt.show()

transitionlistener.helper_functions.Nbspld1(t, x, k=3)¶: Same as Nbspl(), but returns the first derivative too.

transitionlistener.helper_functions.Nbspld2(t, x, k=3)¶: Same as Nbspl(), but returns first and second derivatives too.

transitionlistener.helper_functions.clampVal(x, a, b)¶

Clamp the value x to be between a and b.

Parameters:

x (array_like) – Must have the same shape or be broadcastable.
a (array_like) – Must have the same shape or be broadcastable.
b (array_like) – Must have the same shape or be broadcastable.

Return type:

array_like

class transitionlistener.helper_functions.cubicInterpFunction(y0, dy0, y1, dy1)¶

Bases: object

Create an interpolating function between two points with a cubic polynomial.

Like makeInterpFuncs(), but only uses the first derivatives.

transitionlistener.helper_functions.deriv14(y, x)¶

Calculates $dy/dx$ to fourth-order in $\Delta x$ using finite differences. The derivative is taken along the last dimension of y.

Both y and x should be numpy arrays. The derivatives are centered in the interior of the array, but not at the edges. The spacing in x does not need to be uniform.

transitionlistener.helper_functions.deriv14_const_dx(y, dx=1.0)¶

Calculates $dy/dx$ to fourth-order in $\Delta x$ using finite differences. The derivative is taken along the last dimension of y.

The output of this function should be identical to deriv14() when the spacing in x is constant, but this will be faster.

Parameters:

y (array_like)
dx (float, optional)

transitionlistener.helper_functions.deriv1n(y, x, n)¶

Calculates $dy/dx$ to nth-order in $\Delta x$ using finite differences. The derivative is taken along the last dimension of y.

Both y and x should be numpy arrays. The derivatives are centered in the interior of the array, but not at the edges. The spacing in x does not need to be uniform.

transitionlistener.helper_functions.deriv23(y, x)¶

Calculates $d^2y/dx^2$ to third-order in $\Delta x$ using finite differences. The derivative is taken along the last dimension of y.

Both y and x should be numpy arrays. The derivatives are centered in the interior of the array, but not at the edges. The spacing in x does not need to be uniform. The accuracy increases to fourth-order if the spacing is uniform.

transitionlistener.helper_functions.deriv23_const_dx(y, dx=1.0)¶

Calculates $d^2y/dx^2$ to third-order in $\Delta x$ using finite differences. The derivative is taken along the last dimension of y.

The output of this function should be identical to deriv23() when the spacing in x is constant, but this will be faster.

Parameters:

y (array_like)
dx (float, optional)

transitionlistener.helper_functions.derivative(f, x, dx)¶

Calculate the derivative of f at x using a centered finite difference with step size dx. The derivative is calculated to 4th order in dx.

Parameters:

f (callable) – The function to differentiate. The first argument should be x.
x (array_like) – The point at which to evaluate the derivative.
dx (float) – The step size to use in the finite difference.

Returns:

The derivative of f at x.

Return type:

array_like

transitionlistener.helper_functions.eigenvalues_2x2(a, b, c)¶

Return the eigenvalues (small, large) of a 2x2 symmetric matrix.

The matrix has the form

\[\begin{split}\begin{pmatrix} a & b \\ b & c \end{pmatrix}\end{split}\]

Parameters:

a (array_like) – The elements of the matrix.
b (array_like) – The elements of the matrix.
c (array_like) – The elements of the matrix.

Returns:

(small, large) eigenvalues of the matrix.

Return type:

tuple[array_like, array_like]

class transitionlistener.helper_functions.gradientFunction(f, eps, Ndim, order=4)¶

Bases: object

Make a function which returns the gradient of some scalar function.

Parameters:

f (callable) – The first argument x should either be a single point with length Ndim or an array (or matrix, etc.) of points with shape (..., Ndim), where ... is some arbitrary shape. The return shape should be the same as the input shape, but with the last axis stripped off (i.e., it should be a scalar function). Additional required or optional arguments are allowed.
eps (float or array_like) – The small change in x used to calculate the finite differences. Can either be a scalar or have length Ndim.
Ndim (int) – Number of dimensions for each point.
order (2 or 4) – Calculate the derivatives to either 2nd or 4th order in eps.

Example

>>> def f(X):
...     x,y = np.asarray(X).T
...     return (x*x + x*y +3.*y*y*y).T
>>> df = gradientFunction(f, eps=.01, Ndim=2, order=4)
>>> x = np.array([[0,0],[0,1],[1,0],[1,1]])
>>> print df(x)
    array([[ 0.,  0.], [ 1.,  9.], [ 2.,  1.], [ 3., 10.]])

class transitionlistener.helper_functions.hessianFunction(f, eps, Ndim, order=4)¶

Bases: object

Make a function which returns the Hessian (second derivative) matrix of some scalar function.

Parameters:

f (callable) – The first argument x should either be a single point with length Ndim or an array (or matrix, etc.) of points with shape (..., Ndim), where ... is some arbitrary shape. The return shape should be the same as the input shape, but with the last axis stripped off (i.e., it should be a scalar function). Additional required or optional arguments are allowed.
eps (float or array_like) – The small change in x used to calculate the finite differences. Can either be a scalar or have length Ndim.
Ndim (int) – Number of dimensions for each point.
order (2 or 4) – Calculate the derivatives to either 2nd or 4th order in eps.

transitionlistener.helper_functions.import_file(filename)¶

Import a module from an arbitrary path and return the loaded module object.

Parameters:: filename (str | pathlib.Path) – Absolute or relative path to a Python file containing module-level code.
Returns:: The imported, ready-to-use module object.
Return type:: ModuleType

transitionlistener.helper_functions.load_potential(file, pot_name)¶

Load a potential class from the specified file

Parameters:

file (str) – Name of the file with path
pot_name (str) – Name of the potential

Returns:

Child of the generic_potential class.

Return type:

object

transitionlistener.helper_functions.makeInterpFuncs(y0, dy0, d2y0, y1, dy1, d2y1)¶

Create interpolating functions between two points with a quintic polynomial.

If we’re given the first and second derivatives of a function at x=0 and x=1, we can make a 5th-order interpolation between the two.

transitionlistener.helper_functions.monotonicIndices(x)¶: Returns the indices of x such that x[i] is purely increasing.

transitionlistener.helper_functions.product(*iterables, repeat=1)¶: Cartesian product with __len__ support.

transitionlistener.helper_functions.rkqs(y, dydt, t, f, dt_try, epsfrac, epsabs, args=())¶

Take a single 5th order Runge-Kutta step with error monitoring.

This function is adapted from Numerical Recipes in C.

The step size dynamically changes such that the error in y is smaller than the larger of epsfrac and epsabs. That way, if one wants to disregard the fractional error, set epsfrac to zero but keep epsabs non-zero.

Parameters:

y (array_like) – The initial value and its derivative at the start of the step. They should satisfy dydt = f(y,t). dydt is included here for efficiency (in case the calling function already calculated it).
dydt (array_like) – The initial value and its derivative at the start of the step. They should satisfy dydt = f(y,t). dydt is included here for efficiency (in case the calling function already calculated it).
t (float) – The integration variable.
f (callable) – The derivative function.
dt_try (float) – An initial guess for the step size.
epsfrac (array_like) – The maximual fractional and absolute errors. Should be either length 1 or the same size as y.
epsabs (array_like) – The maximual fractional and absolute errors. Should be either length 1 or the same size as y.
args (tuple) – Optional arguments for f.

Returns:

Delta_y (array_like) – Change in y during this step.
Delta_t (float) – Change in t during this step.
dtnext (float) – Best guess for next step size.

Raises:

IntegrationError – If the step size gets smaller than the floating point error.

References

Based on algorithms described in [1].

transitionlistener.helper_functions.rkqs2(y, dydt, t, f, dt_try, inv_epsabs, args=())¶: Same as rkqs(), but inv_epsabs = 1/epsabs and epsfrac is not used.

transitionlistener.helper_functions.setDefaultArgs(func, **kwargs)¶

Changes the default args in func to match kwargs.

This can be useful when dealing with deeply nested functions for which the default parameters cannot be set directly in the top-level function.

Raises:: ValueError – if func does not have default arguments that match kwargs.

Example

>>> def foo(bar="Hello world!"):
...     print bar
>>> setDefaultArgs(foo, bar="The world has changed!")
>>> foo()
The world has changed!

Configuration handling¶

This module contains the configurations.

Authors: Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@physics.uu.se>

class transitionlistener.config.Configuration¶

Bases: object

Namespace-style container that exposes default configuration dataclasses.

class transitionlistener.config.GWConf¶

Bases: object

Settings for calculating the gravitational wave signal.

bw_collisions = 'NLO'¶: If “off”, the bubble wall collision contribution is not included in the GW spectrum. If “full”, the bubble wall collision contribution is dominant with kappa_phi = 1. If “NLO”, the bubble wall collision contribution is included with NLO friction scaling propto gamma.

check_if_T0_global_min = False¶: If True, it is checked whether the global minimum at T = 0 is the last minimum.

dilution = False¶: If True, the dilution factor is computed (to be implemented). If False, the dilution factor is not computed.

epsilon_turbulence = 0¶: The fraction of energy density in the turbulence contribution to the GW spectrum. If 0, the turbulence contribution is not included in the GW spectrum.

sound_speed = 'compute'¶: If “compute”, the sound speed is computed using the speed of sound in the broken phase. Can also be set to a float “0 < sound_speed <= 1.

use_mean_bubble_separation = True¶: If True, the mean bubble separation is used to compute the GW signal. If False, the PT speed beta/H is used.

wall_velocity = 'LTE'¶: If “LTE”, the wall velocity is computed in the local thermal equilibrium approximation. Or can be set to any float 0 < wall_velocity <= 1.0

weak_threshold = 0.0001¶: below this value, the percolation computation could become invalid. Use it to set the minimum value for the percolation temperature computation.

class transitionlistener.config.PercolationConf¶

Bases: object

Settings for the computation of the percolation temperature.

f_final = 0.99¶: minimum final true vacuum fraction (for a completed percolation): If it is smaller, increase temperature interval for increased precision the true vacuum fraction at percolation is 1 - fperc = 0.71, which corresponds to a percolation integral of 0.34

f_perc = 0.29¶: false vacuum fraction at percolation

f_start = 0.001¶

If it is larger, increase temperature interval for increased precision

Type:: maximal initial true vacuum fraction

max_boundary_ratio = 0.45¶: maximum ratio of the the temperature range in which P_true = 0 or P_true = 1 is allowed. If P_true increases from 0 to 1 only in a couple of steps, the temperature range is too small, likely leading to numerical instabilities.

maxit = 10¶: maximum number of iterations in step 2 and 3 each

n_action = 25¶: Number of points of support to compute the percolation temperature. The higher the number, the more accurate the computation, but also the longer the computation time.

rel_increment = 0.1¶: relative increment of the temperature range in case the temperature range was initially set too small

weight = 0.6666666666666666¶: weight for the first part of the temperature interval, i.e. fraction of total points to evaluate between Tnuc and Tperc.

class transitionlistener.config.TracingConf¶

Bases: object

This contains the phase tracing and tunneling computation parameters

Tmax_factor = 2.5¶: Tmax_factor x internal_scale = Maximal temperature for the phase tracing

Z2_cutof_factor = -5¶: If the potential is Z2-symmetric, this cutoff factor is used to throw away phases that are too far in the negative direction of the field space (in units of the above diftol)

approx_strength_threshold = 0.0001¶: The threshold below which the transition is considered a second-order transition. If the approximate strength DV / T**4 of the transition is below this value, the transition is considered a second-order transition.

diftol = 1¶: Maximal difference between to phases in field space, relative to the vev in internal units, before they are considered the same phase.

do_high_T_phase_check = True¶: This is only a hotfix to avoid the high-temperature phase checks, required in the vev flip flop model

do_tachyon_test = True¶: If True, the tachyon test is performed to check if the potential is stable at T = 0. If False, the tachyon test is not performed.

gen_mirror_phases = False¶: If true, generate phases by applying the mirror transformations of the potential. Not tested yet.

internal_scale = 1000¶: The position of the tree-level true minimum in internal energy units

nucleation_Ttol = 1e-08¶: Tolerance for nucleation temperature computation (in internal units)

tracing_args = {'deltaX_tol': 1.2, 'dtabsMax': 20.0, 'dtfracMax': 0.25, 'dtmin': 1e-06, 'dtstart': 0.0001, 'local_min_args': {'edge': 0.05, 'n': 100}, 'minratio': 0.0001, 'tjump': 1e-05}¶

tracing_derivative_order = 4¶

either 2 or 4

Type:: Derivative order

tracing_field_accuracy = 0.001¶: field accuracy during phase tracing, 1e-3 seems to work well.

tracing_temp_accuracy = 0.001¶: temperature accuracy during phase tracing

tunneling_params = {'V_spline_samples': 1000, 'deformation_deform_params': {'converge_0': 5.0, 'fRatioConv': 0.02, 'fRatioIncrease': 5.0, 'maxiter': 500, 'startstep': 0.002, 'verbose': False}, 'tunneling_findProfile_params': {'npoints': 500, 'phitol': 1e-10, 'rmax': 10000.0, 'rmin': 0.0001, 'xtol': 1e-10}, 'tunneling_init_params': {'phi_eps': 0.001, 'rscale': None}}¶

Physical and mathematical constants¶

Particle physics and cosmological quantities used across TransitionListener.

The numerical values listed here follow the PDG conventions and are expressed in natural units whenever possible. Additional model-specific inputs (SM fermion masses, gauge boson pole masses, Wolfenstein CKM parameters, …) are collected in dedicated containers so that individual models can reuse them.

transitionlistener.constants.CW_CONSTANTS = {'fermion': 1.5, 'gauge': 0.8333333333333334, 'scalar': 1.5}¶: Coleman–Weinberg subtraction constants for scalars, fermions, and vectors.

transitionlistener.constants.GeV_Hz = 1.5192675793312154e+24¶: Conversion between GeV and Hz.

transitionlistener.constants.H100_Hz = 3.2407557442395568e-18¶: Hubble constant $H_0 = 100\,\\mathrm{km/s/Mpc}$ in Hz.

transitionlistener.constants.Lambda = 2.533e-47¶: Dark-energy density $\\rho_\\Lambda$ in GeV^4.

transitionlistener.constants.Mpl_GeV = 1.22091e+19¶: Planck mass in GeV.

transitionlistener.constants.Omega_gamma_h2 = 2.473e-05¶: Photon energy density today in units of $h^2$.

transitionlistener.constants.SM_FERMION_MASSES_GEV = {'m_b': 4.92, 'm_c': 1.51, 'm_d': 0.1, 'm_e': 0.000510998928, 'm_mu': 0.1056583715, 'm_s': 0.1, 'm_t': 172.5, 'm_tau': 1.77682, 'm_u': 0.1}¶

Pole masses of the Standard Model fermions in GeV.

These values serve as the central inputs for all Yukawa couplings appearing in TransitionListener models. They are provided as a plain dictionary so that models can access them directly or feed them into symbolic pipelines.

transitionlistener.constants.SM_GAUGE_MASSES_GEV = {'mW': 80.385, 'mZ': 91.1876}¶: Pole masses of the electroweak gauge bosons in GeV.

transitionlistener.constants.T0_SM_GeV = 2.35253655e-13¶: CMB temperature $T_0 = 2.725\,\\mathrm{K}$ in GeV.

transitionlistener.constants.fyr_Hz = 3.168808781402895e-08¶: Frequency corresponding to one inverse year in Hz.

transitionlistener.constants.yr = 31557600.0¶: One Julian year in seconds ($365.25$ days).

Error handling¶

Custom exception hierarchy that exposes user-friendly error messages.

The exceptions defined here are tailored to the various subsystems of TransitionListener. They encapsulate common failure modes (configuration, phase reconstruction, tunnelling, percolation, hydrodynamics) and attach error codes where the command-line interface needs to surface diagnostic information to end users.

exception transitionlistener.errors.DeformationError(message="Deformation doesn't appear to be converging. Stopping at the point of best convergence.")¶

Bases: Exception

Raised when the path deformation algorithm fails to converge.

exception transitionlistener.errors.EternalInflationError(message='Eternal inflation criterion is fulfilled.')¶

Bases: Exception

Raised when the eternal-inflation criterion is fulfilled.

exception transitionlistener.errors.GWParamsError(message='The given GW params do not match the required ones.')¶

Bases: Exception

Raised when the gravitational wave parameters are inconsistent or incomplete.

exception transitionlistener.errors.InfiniteActionError¶

Bases: Exception

This is a hot fix for the infinite action error: When this error is raised, the action is actually not infinite, but so large that the numerical integration of the bubble profile fails.

exception transitionlistener.errors.InitPotentialError(message='There was an error with the initialisation of the potential.', error_type='unbounded from below')¶

Bases: Exception

Used when there is a problem creating the potential

The error message should be something like "potential unbounded from below" or "unphysical Lagrangian parameters".

exception transitionlistener.errors.NoConfigError(message='No config file found. Please check the config file path.')¶

Bases: Exception

Raised when the configuration file is missing or unreadable.

exception transitionlistener.errors.NoLoggerError(message='Could not create logger.')¶

Bases: Exception

Raised when logging cannot be initialised.

exception transitionlistener.errors.NoModelError(message='No model found. Please check the model file path.')¶

Bases: Exception

Raised when the model file is not found or cannot be loaded.

exception transitionlistener.errors.NoPhases(message='')¶

Bases: Exception

Raised when the phase tracing routine cannot identify any phases or the user tries to compute transitions without tracing first.

exception transitionlistener.errors.NoTransitionFound(message='No transition was found.')¶

Bases: Exception

Raised when no viable transition is found between identified phases.

exception transitionlistener.errors.NucleationError(message='Nucleation temperature not found.')¶

Bases: Exception

Raised when the nucleation temperature could not be identified.

exception transitionlistener.errors.OnlyOnePhase(message='Only one phase has been found.')¶

Bases: Exception

Raised when phase tracing yields only a single phase. In that case, no transitions can be computed.

exception transitionlistener.errors.OnlySecondOrderTransitionsError(message='Only second-order transition(s) found. No first-order transitions.')¶

Bases: Exception

Raised when the scan identifies only second-order transitions.

exception transitionlistener.errors.ParamNamesError(message='Parameter names do not match the model parameters.')¶

Bases: Exception

Raised when the parameter names do not match the model definition.

exception transitionlistener.errors.PercolationApproximation1Error(message='Percolation temperature using approximation 1 could not be found.')¶

Bases: Exception

Raised when the percolation temperature approximation fails to converge.

exception transitionlistener.errors.PercolationError(message='Percolation temperature could not be found.')¶

Bases: Exception

Raised when the percolation temperature could not be determined.

exception transitionlistener.errors.PotentialError(message='There was an error with the potential. It could be that there is no barrier for instance.', error_type='no barrier')¶

Bases: Exception

Used when the potential does not have the expected characteristics.

The error messages should be tuples, with the second item being one of ("no barrier", "stable, not metastable").

exception transitionlistener.errors.SplineError(message='A spline error occurred.')¶

Bases: Exception

Raised when constructing a spline along the tunnelling path fails.

exception transitionlistener.errors.TachyonError(message='Tachyonic boson mass at zero temperature minimum.')¶

Bases: Exception

Raised when a tachyonic mass is detected at the zero-temperature minimum.

exception transitionlistener.errors.Timeout(message='The calculation timed out.')¶

Bases: Exception

Raised when a long-running calculation exceeds the allowed runtime.

exception transitionlistener.errors.TooMuchSupercoolingError(message='No transition found because the high-temperature phase is too supercooled to allow for the nucleation of one bubble per Hubble volume until today.')¶

Bases: Exception

Raised when excessive supercooling prevents bubble nucleation within Hubble time.

exception transitionlistener.errors.TooSmalldVError¶

Bases: Exception

Used when the potential is too flat to be integrated. This means that the bounce solution would be an extreme thin wall bubble with low latent heat, likely not giving rise to any gravitational waves.

exception transitionlistener.errors.TunnelingError(message='Tunneling action not found.')¶

Bases: Exception

Raised when tunnelling fails to produce an action.

exception transitionlistener.errors.UnexpectedError(message='An unexpected error occurred.')¶

Bases: Exception

Raised when an unclassified failure occurs in the CLI.

exception transitionlistener.errors.WrongHighTPhaseError(message='The high-temperature phase does not match the expected one.')¶

Bases: Exception

Raised when the high-temperature phase differs from the expected one.

exception transitionlistener.errors.WrongT0MinimumError(message='Expected T = 0 minimum does not match found last minimum.')¶

Bases: Exception

Raised when the expected T = 0 minimum does not match the last minimum.

exception transitionlistener.errors.ZeroActionError¶

Bases: Exception

This is a hot fix for the zero action error: When this error is raised, the action is actually not zero, but so small that the numerical integration of the bubble profile fails.

Particle content definitions¶

Particle and mass spectrum utilities with concrete particle species.

class transitionlistener.particles.BosonSector(masses_sq, dof, c, is_physical, gauge_coupling, is_bsm, particles, thermal_masses_sq=None)¶

Bases: object

as_tuple()¶

Return type:: Tuple[ndarray, ...]

c: ndarray¶

dof: ndarray¶

gauge_coupling: ndarray¶

is_bsm: ndarray¶

is_physical: ndarray¶

property latex_labels: List[str]¶

masses_sq: ndarray¶

particles: Sequence[BaseParticle]¶

property text_labels: List[str]¶

thermal_masses_sq: Optional[ndarray] = None¶

class transitionlistener.particles.Fermion(name, latex_name, dof, is_SM, c=1.5)¶

Bases: object

Structure to represent fermions.

c: float = 1.5¶

dof: float¶

is_SM: bool¶

latex_name: str¶

name: str¶

class transitionlistener.particles.FermionSector(masses_sq, dof, is_bsm, particles)¶

Bases: object

as_tuple()¶

Return type:: Tuple[ndarray, ...]

dof: ndarray¶

is_bsm: ndarray¶

property latex_labels: List[str]¶

masses_sq: ndarray¶

particles: Sequence[BaseParticle]¶

property text_labels: List[str]¶

class transitionlistener.particles.GaugeBoson(name, latex_name, dof, is_SM, gauge_coupling=0.0, c=0.8333333333333334)¶

Bases: object

Structure to represent gauge bosons

c: float = 0.8333333333333334¶

dof: float¶

gauge_coupling: float = 0.0¶

is_SM: bool¶

is_physical = True¶

latex_name: str¶

name: str¶

class transitionlistener.particles.Goldstone(name, latex_name, dof, is_SM, gauge_coupling=0.0, is_physical=False, c=1.5)¶

Bases: object

Structure to represent Golstone bosons

c: float = 1.5¶

dof: float¶

gauge_coupling: float = 0.0¶

is_SM: bool¶

is_physical: bool = False¶

latex_name: str¶

name: str¶

class transitionlistener.particles.MassBlock(particles, mass_function, hard_thermal_mass_function=None, label=None)¶

Bases: object

evaluate(X, T)¶

Return type:: ndarray

evaluate_thermal(X, T)¶

Return type:: Optional[ndarray]

hard_thermal_mass_function: Optional[Callable[[ndarray, float], ndarray]] = None¶

label: Optional[str] = None¶

mass_function: Callable[[ndarray, float], ndarray]¶

particles: Sequence[BaseParticle]¶

property statistic: str¶

class transitionlistener.particles.MassSpectrum(scalars, gaugeBosons=[], fermions=[], boson_massSq_fn=None, fermion_massSq_fn=None)¶

Bases: object

Containts all the information about the mass spectrum.

boson_labels(type)¶

bosons_massSq(X, T)¶

Return the boson spectrum.

It returns a sequence of mass squared, dof, c, is_physical

calc_N_gauge_bosons(gaugeBosons)¶

fermion_labels(type)¶

fermion_massSq(X)¶

Return the fermion spectrum.

It returns a sequence of mass squared, dof

get_gauge_coupling()¶: description

set_bmass_fn(bmass_fn)¶

set_fmass_fn(fmass_fn)¶

class transitionlistener.particles.Scalar(name, latex_name, dof, is_SM, gauge_coupling=0.0, is_physical=True, c=1.5)¶

Bases: object

Structure to represent scalars

c: float = 1.5¶

dof: float¶

gauge_coupling: float = 0.0¶

is_SM: bool¶

is_physical: bool = True¶

latex_name: str¶

name: str¶

class transitionlistener.particles.SpectrumSnapshot(bosons, fermions)¶

Bases: object

bosons: BosonSector¶

fermions: FermionSector¶

Plotting utilities¶

Helpers to visualise grid scans of TransitionListener observables.

class transitionlistener.gridplots.plot2dData(data_dict_array, x, y, scale, xy_plot_names, foldername, derived_params_names, derived_params_plot_names, overview_title)¶

Bases: GW_Sensitivity_Data

Render two-dimensional scan outputs as heatmaps and diagnostic plots.

plot_SNRs()¶: Save heatmaps of the signal-to-noise ratio for every detector.

plot_add_infos()¶: Visualise any auxiliary observability fields that were stored.

plot_errors()¶: Plot the error-code grid released by the CLI.

plot_lin_params()¶: Plot the linear-scale version of every derived parameter.

plot_logLs()¶: Save heatmaps of the PTA log-likelihood for every pulsar collaboration.

plot_log_params()¶: Plot the logarithmic version of every derived parameter.

plot_mass_spectrum()¶: Render the zero-temperature mass spectrum as per-particle grids.

plot_overview(overview_detector_name='LISA', overview_param_names=('alpha', 'RH', 'Treh_SM_GeV'), overview_param_plot_names=('$\\alpha_\\mathrm{tot}$', '$RH_\\mathrm{perc}$', '$T^{\\mathrm{reh}}_{\\mathrm{SM}}$ / $\\mathrm{GeV}$'))¶: Create a four-panel summary containing three observables and one SNR.

retrieve_add_spec_info()¶: Gather additional observability metadata that is not an SNR or log-likelihood.

retrieve_derived_params()¶: Collect derived parameters and error codes from the scan output.

retrieve_observability_data()¶: Extract detector SNRs, detectability flags and PTA log-likelihoods.

save_SNRs()¶: Export the log10 SNR grids as plain-text tables.

save_add_infos()¶: Save the additional observability information as plain-text tables.

save_logLs()¶: Export the PTA log-likelihood grids as plain-text tables.

Matplotlib defaults and helper utilities for rendering TransitionListener plots.

transitionlistener.plot_settings.add_TL_logo(loc, magnification=1, ax=None, zorder=3, size=0.27, small_logo=True)¶

Inset the TransitionListener logo into a Matplotlib axes.

Parameters:

loc (str) – Where to place the inset ("upper right", "upper left", etc.).
magnification (float, optional) – Scale factor applied to the default logo size.
ax (matplotlib.axes.Axes, optional) – Target axes. Defaults to plt.gca() if omitted.
zorder (int, optional) – Drawing order for the inset axes.
size (float, optional) – Baseline inset size expressed as a fraction of the parent axes.
small_logo (bool, optional) – Choose between the small horizontal logo and the large square variant.

transitionlistener.plot_settings.load_large_logo()¶: Return the large TransitionListener logo as an RGBA array.

transitionlistener.plot_settings.load_small_logo()¶: Return the small TransitionListener logo as an RGBA array.

Color palettes and Matplotlib helpers used across TransitionListener plots.

The constants exposed here encode the corporate identity color palettes that the project uses for plots in the documentation as well as publication-quality figures. A couple of helper utilities are provided to make it easy to size figures consistently and to configure Matplotlib’s global font settings.

transitionlistener.colors.set_font()¶

Update Matplotlib’s global rcParams with the project’s stylistic defaults.

The configuration mirrors the publication layout used in the documentation: LaTeX-rendered text, a sans-serif font family, harmonised font sizes for titles and axis labels, and a colour cycle based on the DESY palette defined in this module. Calling this function is idempotent and affects figures created afterwards.

transitionlistener.colors.set_size(width, fraction=1, subplots=(1, 1))¶

Return figure dimensions that avoid downstream scaling artefacts.

Parameters:

width (float | str) – Either the Matplotlib figure width in points or a preset identifier such as "JCAP" or "beamer" that maps to a known text width.
fraction (float, optional) – Fraction of the available width the figure should occupy. Defaults to 1 which uses the full width.
subplots (tuple[int, int], optional) – Tuple describing the subplot layout (rows, columns). The information is used to slightly enlarge multi-panel figures so that axis labels do not overlap.

Returns:

fig_dim – Figure width and height in inches.

Return type:

tuple[float, float]

TransitionListener package¶

Interface¶

Phases and phase tracing¶

Phase transition classification¶

Computation of transition observables¶

Bubble dynamics¶

Model-independent potential definitions¶

Tunneling pathfinding and bubble profiles¶

Single-field bounce action calculations¶

Finite temperature effective potentials¶

Thermodynamics¶

Bubble wall velocity and hydrodynamics¶

Gravitational wave spectra¶

Observability at gravitational wave detectors¶

Utilities and helpers¶

Configuration handling¶

Physical and mathematical constants¶

Error handling¶

Particle content definitions¶

Plotting utilities¶

External interfaces¶