TransitionListener API

TransitionListener package providing tools to analyze cosmological phase transitions.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

Interface

Interface entry points for TransitionListener scans.

This module exposes the main functions and classes for performing scans and single-point evaluations using TransitionListener. It also manages global state variables such as debug mode, timeout settings, and logging configurations.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.interface.Logger(file_name)

Bases: object

Very small helper that mirrors stdout logging to a file.

close()

Close the on-disk log file.

log(message)

Write message to the backing file and flush immediately.

class transitionlistener.interface.ScanConfig(file)

Bases: object

Read and store all settings required for a TransitionListener scan.

display()

Pretty-print the loaded configuration to the console.

transitionlistener.interface.call_by_sampler(potential, inputparams_dict, errorlogger, resultlogger, timeout, verbose=False, include_smbhb=False)

Evaluate TransitionListener for external samplers and return the result dictionary.

transitionlistener.interface.create_grid(xminmax, yminmax, N, xscale, yscale)

Create a regular grid of x/y coordinates.

Return type:

tuple[ndarray]

transitionlistener.interface.extract_parameters(res, derived_params, mainPTA='NG15_14bins')

Extract the parameters from the result dictionary.

Return type:

Dict[str, float]

transitionlistener.interface.grid_scan(conf, n_jobs)

2D grid scan.

transitionlistener.interface.line_scan(conf, n_jobs)

1D scan over only one parameter.

transitionlistener.interface.log_likelihood(args)

Evaluate the nested-sampling log-likelihood for a given parameter vector.

transitionlistener.interface.main()

Console entry point.

transitionlistener.interface.plot_results_1d(results_dict, conf, xrange, outpath)

Generate line scan plots.

transitionlistener.interface.plot_results_2d(results_dict, conf, xrange, yrange, outpath)

Make the grid plots.

transitionlistener.interface.prior_transform(cube)

Transforms the unit cube to the prior space.

transitionlistener.interface.random_scan(conf, n_jobs)

Random parameter scan.

transitionlistener.interface.run_TL(inputparams_dict, potential, errorlogger, resultlogger, timeout, verbose=False, call_from_sampler=False, include_smbhb=False, return_context=False)

Core execution pipeline that evaluates observables for a single parameter point.

transitionlistener.interface.sample_and_export_to_csv(args)

Evaluate a single parameter point and append the outcome to output_table.csv.

transitionlistener.interface.save_results_1d(res_dict, N, xrange, outpath, outnames, format, line_param, other_params)

Save the result list to a hdf5 or txt file.

transitionlistener.interface.save_results_2d(res_dict, N, xrange, yrange, outpath, outnames, format, grid_names, other_params)

Save the result list to a hdf5 or txt file.

transitionlistener.interface.scanfunc(input, verbose=False)

Wrapper used by worker processes to execute a single scan point.

Return type:

dict

transitionlistener.interface.single(conf, verbose=False)

Evaluate a single parameter point and generate the requested plots.

transitionlistener.interface.table(conf, n_jobs)

Evaluate points specified in a CSV table.

transitionlistener.interface.ultranest(conf)

Run the Ultranest sampler.

Phases and phase tracing

This module contains the phases object. It contains an interface to the phase tracing routines, stores the phase information of the potential and provides interpolated functions.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.phases.PhaseComparison(phase1, phase2, tmin, tmax, x1_min, x2_min, x1_max, x2_max, same_at_tmin, same_at_tmax)

Bases: object

Summary information about the overlap between two phases.

The object stores the temperature interval where the phases overlap and the corresponding positions of the minima. This allows helper routines to decide whether phases should be merged or kept separate without re-running the minimiser.

phase1: PhaseInfo

phase2: PhaseInfo

same_at_tmax: bool

same_at_tmin: bool

tmax: float

tmin: float

x1_max: ndarray

x1_min: ndarray

x2_max: ndarray

x2_min: ndarray

class transitionlistener.phases.PhaseInfo(key, X, T, dXdT)

Bases: object

Describes a temperature-dependent minimum, plus second-order transitions to and from that minimum.

key

A unique identifier for the phase (usually an int).

Type:

hashable

X, T, dXdT

The minima and its derivative at different temperatures.

Type:

array_like

interpolator

The minima against temperature. It is shape preserving: between two traced temperatures each field component stays between the two values traced there. Past the ends of the trace it extrapolates, as the B-spline it replaced did.

Type:

scipy.interpolate.PchipInterpolator

low_trans

Phases (identified by keys) which are joined by a second-order transition to this phase.

Type:

set

high_trans

Phases (identified by keys) which are joined by a second-order transition to this phase.

Type:

set

addLinkFrom(other_phase)

Add a link from other_phase to this phase, checking to see if there is a second-order transition.

Parameters:

other_phase (PhaseInfo) – Information of the other phase

Return type:

None.

replaceTrace(X, dXdT)

Replace the minima and their derivatives at the traced temperatures and rebuild the interpolation. The temperatures, the key and the links are kept.

Return type:

None

valAt(T, deriv=0)

Find the minimum at the value T from the interpolated trace.

Parameters:

• T (float | np.ndarray) – The temperature at which to eval the minimum. Outside the traced range the interpolation is extrapolated rather than refused.

• deriv (int) – If deriv > 0, return that derivative of the minimum with respect to T instead of its value. The interpolant is a piecewise cubic whatever the length of the trace, so every order is available; the second and third jump at the traced temperatures, and orders above the third are zero.

Returns:

The minimum at the temperature T: one field vector for a scalar T, and otherwise the shape of T with the field components as the last axis.

Return type:

np.ndarray

class transitionlistener.phases.PhaseSegment(index, phase_key, phase, entry_temperature, exit_temperature)

Bases: object

Piecewise representation of the thermal history across a single phase.

bounds()

Return the temperature interval for which this phase is active.

Return type:

tuple[float, float]

entry_temperature: float

exit_temperature: float

index: int

phase: PhaseInfo

phase_key: int | str

temperature_grid(lower=None, upper=None, min_points=50)

Create a temperature grid within the active interval for evaluation.

Return type:

ndarray

class transitionlistener.phases.Phases(pot, verbose=False)

Bases: object

This class contains the phase tracing routines and stores the phase information.

buildPhaseGraph(in_phases, V)

Construct a tree of the phase history starting from the high temperature phase.

Parameters:

• in_phases (list[PhaseInfo]) – List of phases

• V (callable) – The temperature dependent effective potential V(X, T)

Return type:

None.

findPhases(genMirrorPhases=True)

Find different phases as functions of temperature

Parameters:

genMirrorPhases (bool, optional) – If true, generate phases by applying the symmetry transformations of the potential to the existing phases.

Returns:

Each item in the returned dictionary is an instance of transitionFinder.Phase, and each phase is identified by a unique key. This value is also stored in self.phases.

Return type:

list[PhaseInfo]

getStartPhase(phases, V=None)

Find the key for the high-T phase.

Parameters:

• phases (dict) – Output from traceMultiMin().

• V (callable) – The potential V(x,T). Only necessary if there are multiple phases with the same Tmax.

Returns:

The key of the high-T phase.

Return type:

int | str

getT0Phase(phases, V)

Find the stable phase at T = 0.

Parameters:

• phases (list[PhaseInfo]) – List of the phases

• V (callable) – The effective potential as V(X, T)

Returns:

The key of the stable phase at T = 0.

Return type:

int | str

keys()

Expose the keys of the internally stored phases.

Return type:

list[str]

phase_alias(key)

Return a short user-facing alias such as P1 for one phase key.

Return type:

str

printPhaseTree()

description

resolve_phase_key(key_or_alias)

Resolve a user-facing alias such as P1 back to the internal key.

Return type:

int | str

testTmax()

Test that there is only one phase with Tmax = self.Tmax

Raises:

ValueError – If more than one phase has Tmax = self.Tmax

class transitionlistener.phases.TransitionHistory(segments)

Bases: object

Ordered collection of PhaseSegment objects describing the evolution.

items()

Yield (index, PhaseSegment) pairs in order.

keys()

Expose indices for iteration, matching list semantics.

phase_keys()

Return the ordered phase identifiers along the history.

Return type:

list[int | str]

property temperature_span: tuple[float, float]

Return the overall minimum and maximum temperature that are covered.

values()

Return the ordered list of segments.

transitionlistener.phases.findApproxLocalMin(f, x1, x2, args=(), n=100, edge=0.05)

Find minima on a straight line between two points.

When jumping between phases, we want to make sure that we don’t jump over an intermediate phase. This function does a rough calculation to find any such intermediate phases.

Parameters:

• f (callable) – The function f(x) to minimize.

• x1 (array_like) – The points between which to find minima.

• x2 (array_like) – The points between which to find minima.

• args (tuple, optional) – Extra arguments to pass to f.

• n (int, optional) – Number of points to test for local minima.

• edge (float, optional) – Don’t test for minima directly next to the input points. If edge==0, the minima potentially go all the way to input points. If edge==0.5, the range of tested minima shrinks to a single point at the center of the two points.

Returns:

A list of approximate minima, with each minimum having the same shape as x1 and x2.

Return type:

list

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

Find a nearby local minimum by Newton stepping in field space.

Return type:

ndarray

transitionlistener.phases.generateMirrorPhases(phases, diftol, invGroupElements, fixed_tol=None)

Use the transformations of the potential to generate the mirror phases that have not been traced.

Parameters:

• phases (list[PhaseInfo]) – List of the phases

• diftol (float) – The tolerance in field space for which to consider two phases equal

• invGroupElements (list[np.ndarray]) – Matrix transformations which leave the potential invariant

• fixed_tol (float, optional) – How close to the fixed subspace of a transformation a phase has to stay, at every traced temperature, to count as lying on it and so to be its own image. This is the tolerance the symmetric phases were put on that subspace with, which is finer than diftol: a broken phase can sit nearer to the subspace than two phases have to be to merge, and its image is then a phase of its own. Defaults to diftol.

transitionlistener.phases.reconstructTransitionHistory(phases, transitions)

Construct the ordered thermal history using the traced phase graph.

Parameters:

• phases (Phases) – The traced phases together with their transition graph.

• transitions (Iterable[TransitionInfo]) – The ordered list of realised transitions starting from the high-T phase.

Returns:

An ordered, piecewise representation of the vacuum expectation values that can be evaluated via the individual PhaseSegment objects.

Return type:

TransitionHistory

transitionlistener.phases.removeRedundantPhases(f, df_dx, d2f_dx2, phases, xeps=1e-05, diftol=0.01, verbose=False, conversionFactor=1)

Remove redundant phases from a dictionary output by traceMultiMin().

Although traceMultiMin() attempts to only trace each phase once, there are still instances where a single phase gets traced twice. If a phase is included twice, the routines for finding transition regions and tunnelling get very confused. This routine follows the original CosmoTransitions philosophy while splitting the individual steps into small helpers so they can be tested independently.

Parameters:

• f (callable) – The scalar potential f(x, T) that was passed to traceMultiMin().

• df_dx (np.ndarray) – First and second derivatives of f with respect to the fields.

• d2f_dx2 (np.ndarray) – First and second derivatives of f with respect to the fields.

• phases (dict) – Dictionary of PhaseInfo objects returned by traceMultiMin().

• xeps (float, optional) – Minimisation tolerance in field space when re-minimising at the overlap.

• diftol (float, optional) – Maximum separation between potential minima before they are considered identical.

• verbose (bool, optional) – Emit diagnostic output that mirrors the original implementation.

• conversionFactor (float, optional) – Conversion factor from internal units to GeV for verbose messages.

Notes

If two phases are merged to get rid of redundancy, the resulting phase has a key that is a string combination of the two prior keys.

transitionlistener.phases.symmetrizeInvariantPhases(phases, invGroupElements, tol)

Put every phase that is its own mirror image onto the fixed subspace of that symmetry.

Near a minimum that only the thermal masses hold in place, as the symmetric phase of a classically conformal model, the potential is flat to within the tracing tolerance and the trace drifts off the minimum. fmin (Nelder-Mead, initial simplex 5% of the starting point) leaves every point within about 20 xeps of the origin where it is, the step predictor evaluated there pushes the trace further out as the temperature falls, and the last node, at the lowest tracing temperature, is an extrapolation that is not a minimum. The spline through it puts the false vacuum at an arbitrary field value over the lowest decades in temperature, where an extremely supercooled transition happens: in the conformal U(1) at T/v ~ 1e-6 the dark photon came out several times heavier than T there, and the counted entropy of the false vacuum (bubbledynamics.h_eff_DS) varied with T.

A phase that coincides with its image under an element g of the symmetry group of the potential at every traced temperature, within tol, is invariant under g; its minimum lies exactly on the fixed subspace of g, and it is replaced by its projection (X + X g)/2. Phases that differ from their image anywhere, broken phases and phases that leave the fixed subspace at a second-order transition, are left alone.

Parameters:

• phases (dict) – The traced phases, modified in place.

• invGroupElements (list[np.ndarray]) – Matrix transformations which leave the potential invariant (generic_potential.invGroupElements).

• tol (float) – Largest field-space distance, at any traced temperature, between a phase and its image for the two to count as the same.

Returns:

The keys of the phases that were projected.

Return type:

list

transitionlistener.phases.traceLocalMinimum(f, x, t, df_dx, d2f_dx2, xeps)

transitionlistener.phases.traceMinimum(f, df_dx, d2f_dxdt, d2f_dx2, x0, t0, tstop, dtstart, deltaX_target, dtabsMax=20.0, dtfracMax=0.25, dtmin=0.001, deltaX_tol=1.2, minratio=0.01, verbose=False, conversionFactor=1)

Trace the minimum xmin(t) of the function f(x,t), starting at x0, t0.

Parameters:

• f (callable) – The scalar function f(x,t) which needs to be minimized. The input will be of the same type as (x0,t0).

• d2f_dxdt (callable) – Functions which return returns derivatives of f(x). d2f_dxdt should return the derivative of the gradient of f(x) with respect to t, and d2f_dx2 should return the Hessian matrix of f(x) evaluated at t. Both should take as inputs (x,t).

• d2f_dx2 (callable) – Functions which return returns derivatives of f(x). d2f_dxdt should return the derivative of the gradient of f(x) with respect to t, and d2f_dx2 should return the Hessian matrix of f(x) evaluated at t. Both should take as inputs (x,t).

• x0 (array_like) – The initial starting point. Must be an array even if the potential is one-dimensional (in which case the array should have length 1).

• t0 (float) – The initial starting parameter t.

• tstop (float) – Stop the trace when t reaches tstop.

• dtstart (float) – Initial stepsize.

• deltaX_target (float) – The target error in x at each step. Determines the stepsize in t by extrapolation from last error.

• dtabsMax (float, optional)

• dtfracMax (float, optional) – The largest stepsize in t will be the LARGEST of abs(dtstart)*dtabsMax and t*dtfracMax.

• dtmin (float, optional) – The smallest stepsize we’ll allow before assuming the transition ends, relative to dtstart

• deltaX_tol (float, optional) – deltaX_tol*deltaX_target gives the maximum error in x before we want to shrink the stepsize and recalculate the minimum.

• minratio (float, optional) – The smallest ratio between smallest and largest eigenvalues in the Hessian matrix before treating the smallest eigenvalue as zero (and thus signaling a saddle point and the end of the minimum).

Return type:

traceMinimum_rval

Returns:

X, T, dXdTarray_like

Arrays of the minimum at different values of t, and its derivative with respect to t.

overXarray_like

The point beyond which the phase seems to disappear.

overTfloat

The t-value beyond which the phase seems to disappear.

Notes

In prior versions, d2f_dx2 was optional and called d2f, while d2f_dxdt was calculated from an optional parameter df using finite differences. If Neither of these were supplied, they would be calculated directly from f(x,t) using finite differences. This lead to a messier calling signature, since additional parameters were needed to find the finite differences. By instead requiring that the derivatives be supplied, the task of creating the derivative functions can be delegated to more general purpose routines (see e.g. helper_functions.gradientFunction and helper_functions.hessianFunction).

Also new in this version, dtmin and dtabsMax are now relative to dtstart. The idea here is that there should be some required parameter that sets the scale, and then optional parameters can set the tolerances relative to this scale. deltaX_target is now not optional for the same reasoning.

transitionlistener.phases.traceMultiMin(f, df_dx, d2f_dxdt, d2f_dx2, points, tLow, tHigh, deltaX_target, verbose=False, conversionFactor=1, dtstart=0.001, tjump=0.001, forbidCrit=None, applySymmetries=None, single_trace_args={}, local_min_args={})

Trace multiple minima xmin(t) of the function f(x,t).

This function will trace the minima starting from the initial (x,t) values given in points. When a phase disappears, the function will search for new nearby minima, and trace them as well. In this way, if each minimum corresponds to a different phase, this function can find the (possibly) complete phase structure of the potential.

Parameters:

• f (callable) – The scalar function f(x,t) which needs to be minimized. The input will be of the same type as each entry in the points parameter.

• d2f_dxdt (callable) – Functions which return returns derivatives of f(x). d2f_dxdt should return the derivative of the gradient of f(x) with respect to t, and d2f_dx2 should return the Hessian matrix of f(x) evaluated at t. Both should take as inputs (x,t).

• d2f_dx2 (callable) – Functions which return returns derivatives of f(x). d2f_dxdt should return the derivative of the gradient of f(x) with respect to t, and d2f_dx2 should return the Hessian matrix of f(x) evaluated at t. Both should take as inputs (x,t).

• points (list) – A list of points [(x1,t1), (x2,t2),…] that we want to trace, where x1, x2, etc. are each a one-dimensional array.

• tLow (float) – Lowest and highest temperatures between which to trace.

• tHigh (float) – Lowest and highest temperatures between which to trace.

• deltaX_target (float) – Passed to traceMinimum() and used to set the tolerance in minimization.

• dtstart (float, optional) – The starting stepsize, relative to tHigh-tLow.

• tjump (float, optional) – The jump in t from the end of one phase to the initial tracing point in another. If this is too large, intermediate phases may be skipped. Relative to tHigh-tLow.

• forbidCrit (callable or None, optional) – A function that determines whether or not to forbid a phase with a given starting point. Should take a point x as input, and return True (if the phase should be discarded) or False (if the phase should be kept).

• single_trace_args (dict, optional) – Arguments to pass to traceMinimum().

• local_min_args (dict, optoinal) – Arguments to pass to findApproxLocalMinima().

Returns:

phases – A dictionary of Phase instances. The keys in the dictionary are integers corresponding to the order in which the phases were constructed.

Return type:

list[PhaseInfo]

Phase transition classification

This module contains routines to compute the possible transitions between phases.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.transitions.TransitionInfo(Tcrit, high_vev, high_phase, low_vev, low_phase, type, Tnuc=0.0, Tperc=0.0, action_Tnuc=0.0, step=0, total_steps=0)

Bases: object

Object containing the information about one possible phase transition.

Tcrit: float

Critical temperature where the two minima are degenerate

Tnuc: float = 0.0

Nucleation temperature.

Tperc: float = 0.0

Percolation temperature.

action_Tnuc: float = 0.0

Action at the nucleation.

derived_params = {}

Computed observables.

full_tunneling_info = {}

Save the temperatures and corresponding actions from the nucleation computation.

high_phase: int

Key of the high phase

high_vev: ndarray

Field values in the high phase

instanton = {}

Instanton solution at the nucleation temperature.

low_phase: int

Key of the low phase

low_vev: ndarray

Field values in the low phase

step: int = 0

Ordering number of the possible transitions

total_steps: int = 0

Total number of transitions.

type: int

1 for first order, 2 fo second order (continuous)

Type:

Type of transition

class transitionlistener.transitions.Transitions(phases, pot, verbose=False)

Bases: object

Compute the transition path from the high-T phase to the 0-T phase for a given set of phases.

Class containing the routines to find the transitions between all possible pairs of phases.

Parameters:

• phases (list["PhaseInfo"]) – List of the phases as PhaseInfo objects.

• pot (generic_potential) – The potential.

• verbose (bool, optional) – Set the outputlevel.

evalNucleationCriterion(T, start_phase, end_phase, V, dV, phitol, overlapAngle, nuclCriterion, fullTunneling_params, verbose, outdict)

Find the lowest action tunneling solution.

This functions stores the results in the dict outdict with the temperature as the key.

Parameters:

• T (float) – The temperature.

• start_phase (PhaseInfo) – The starting phase

• end_phase (PhaseInfo) – The end phase

• V (callable) – The effective potential

• dV (callable) – The gradient of the effective potential.

Returns:

Evaluation of nuclCriterion(S,T).

Return type:

float

findAllTransitions()

Find all the possible transitions between coexisting phases by computing the nucleation temperatures.

The phases and the potential are taken from the instance, as self.phases, self.V and self.dV; this method takes no arguments.

Returns:

List with TransitionInfo objects.

Return type:

dict[TransitionInfo]

findPossibleTransitionsFromPhases(verbose=False)

Find all possible transitions between coexisting phases.

Parameters:

verbose (bool) – Set the output level.

Returns:

A list of of transitions sorted in decreasing temperature.

Return type:

list[TranstionInfo]

findTransitionPathFromTnuc(verbose=False)

Find the transition path starting from the high-T phase.

Calculate the nucleation temperature for the transitions starting from the high-T phase. The function constructs a list of transitions with the highest possible nucleation temperatures.

Parameters:

verbose (bool) – Set the output level.

Returns:

A list of of transitions sorted in decreasing temperature.

Return type:

list[TranstionInfo]

getStartPhase(phases, V=None)

Find the key for the high-T phase.

Parameters:

• phases (dict) – Output from traceMultiMin().

• V (callable) – The potential V(x,T). Only necessary if there are multiple phases with the same Tmax.

getUniqueTunnelingPhases(V, phases, startPhase, childPhases)

Check if there are equivalent tunneling paths to different phases.

This functions checks there are two phases which have the same distance to the start phase and the same potential values. If so the tunneling paths are considered equivalent and only one phase is returned.

Parameters:

• V (callable) – The effective potential V(X, T)

• phases (list[PhaseInfo])

• childPhases (list) – List of phase keys

Returns:

List with phase keys.

Return type:

list

keys()

Expose the valid indices for the transition list.

makeSecondOrderDict(transition)

Create a dictionary describing a second-order phase transition.

Return type:

dict

printTransitions(transitions)

Pretty-printing of the transitions

Parameters:

transitions (dict[TransitionInfo]) – List with TransitionInfo objects.

Return type:

None

secondOrderTrans(V, high_phase, low_phase, verbose=False, degeneracyTest=True)

Create the TransitionInfo object for a second order transition.

Parameters:

• V (callable) – The effective potential function.

• high_phase (PhaseInfo) – The phase information for the high-temperature phase

• low_phase (PhaseInfo) – The phase information for the low-temperature phase

• verbose (bool) – Set the output level.

• degeneracyTest (bool, optional) – If true, search for Tcrit, where the to minima are degenerate. Note, that this causes errors for hidden second order transitions

Returns:

The transition information.

Return type:

TransitionInfo

Notes

A second order transition is identified by finding the critical temperature Tcrit where the two phases are degenerate in energy. At this temperature, the potential values of the two phases are equal. If such a temperature is found and the degeneracy check passes, a TransitionInfo object is created to represent the second order transition.

seedlessFirstOrderCandidate(V, high_phase, low_phase, tmin, tmax, verbose=False)

Build a first-order transition candidate without computing Tnuc.

Seedless adaptive step size should not spend CPU finding a nucleation-temperature seed before percolation. It only needs a plausible high/low phase pair and a finite overlap interval; the dynamic support-bank scouts then decide where action evaluations are physically relevant.

Return type:

TransitionInfo | None

sortForSmallestAction(V, phases, startPhase, childPhases)

Estimate the action by computing the action for the linearised potential between the start phase and the child phases. Return a sorted list of the child phases after the smallest action approximation

Return type:

list

Returns:

• .. todo:: implement

Computation of transition observables

Compute thermodynamic and gravitational-wave observables for transitions.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.transitionObservables.PercolationResult(Tperc, TSYM, H, P, TBRO, S, Pint, Sint, Hint, TBROint, logEntropyInt, coolingInt, metadata, successful)

Bases: object

Hold percolation-related outputs and splines when available.

H: ndarray | None

Hint: interp1d | None

P: ndarray | None

Pint: interp1d | None

S: ndarray | None

Sint: interp1d | None

TBRO: ndarray | None

TBROint: interp1d | None

TSYM: ndarray | None

Tperc: float

coolingInt: interp1d | None

logEntropyInt: interp1d | None

metadata: PercolationDiagnostics | None

successful: bool

class transitionlistener.transitionObservables.TransitionContext(tr, pot, phases, GWconfig, PercolationConf, derived_param_names, verbose, derived_params, Tnuc, outdict, phase_symmetric, phase_broken)

Bases: object

Collect shared inputs and outputs for a single transition.

GWconfig: GWConf

PercolationConf: PercolationConf

Tnuc: float | None

derived_param_names: list[str]

derived_params: dict

outdict: dict

phase_broken: PhaseInfo

phase_symmetric: PhaseInfo

phases: list[PhaseInfo]

pot: generic_potential

tr: TransitionInfo

verbose: bool

class transitionlistener.transitionObservables.TransitionObservableInfo(v_wall=nan, c_s=nan, c_s_sym=nan, c_s_bro=nan, Tperc=nan, Tperc_SM_GeV=nan, Tcrit_SM_GeV=nan, xi_crit=nan, Tnuc_SM_GeV=nan, Treh=nan, Treh_SM_GeV=nan, Treh_DS_GeV=nan, alpha=nan, alpha_theta=nan, alpha_thetabar=nan, alpha_p=nan, alpha_e=nan, alpha_hyd=nan, alpha_inf=nan, alpha_eq=nan, RH=nan, g_eff_tot_reh=nan, h_eff_tot_reh=nan, g0=nan, h0=nan, betaH_S3=nan, betaH_RH=nan, Tf_SM_GeV=nan, kappa_phi=nan, kappa_sw=nan, kappa_turb=nan, D=nan, step=nan, total_steps=nan, WARNING_too_weak_to_compute_perc=False, WARNING_no_perc_splines=False, WARNING_betaH_small=False, WARNING_betaH_very_small=False, WARNING_betaH_mismatch=False, WARNING_betaH_nonfinite=False, WARNING_nucleationRate_nonexponential=False, WARNING_not_T0_global_min=False)

Bases: object

Collection of transition observable data.

D: float = nan

RH: float = nan

Tcrit_SM_GeV: float = nan

Tf_SM_GeV: float = nan

Tnuc_SM_GeV: float = nan

Tperc: float = nan

Tperc_SM_GeV: float = nan

Treh: float = nan

Treh_DS_GeV: float = nan

Treh_SM_GeV: float = nan

WARNING_betaH_mismatch: bool = False

WARNING_betaH_nonfinite: bool = False

WARNING_betaH_small: bool = False

WARNING_betaH_very_small: bool = False

WARNING_no_perc_splines: bool = False

WARNING_not_T0_global_min: bool = False

WARNING_nucleationRate_nonexponential: bool = False

WARNING_too_weak_to_compute_perc: bool = False

alpha: float = nan

alpha_e: float = nan

alpha_eq: float = nan

alpha_hyd: float = nan

alpha_inf: float = nan

alpha_p: float = nan

alpha_theta: float = nan

alpha_thetabar: float = nan

betaH_RH: float = nan

betaH_S3: float = nan

c_s: float = nan

c_s_bro: float = nan

c_s_sym: float = nan

g0: float = nan

g_eff_tot_reh: float = nan

h0: float = nan

h_eff_tot_reh: float = nan

kappa_phi: float = nan

kappa_sw: float = nan

kappa_turb: float = nan

step: float = nan

total_steps: float = nan

v_wall: float = nan

xi_crit: float = nan

class transitionlistener.transitionObservables.TransitionObservables(pot, phases, transitions, verbose=False)

Bases: object

Evaluate derived observables for every transition of a potential.

check_T0_global_min()

Check whether the global minimum at T = Tmin is the last minimum. If not, raise an error.

computeTransitionObservables()

Calculate the GW observables for each transition in the transitions_dict. This is done by calling the computeTransitionObservables_one_transition function from the bubbledynamics module.

Raises:

err – Raises an error if GW observables cannot be calculated.

Returns:

transitionObservables – A dictionary with the GW observables for each transition.

Return type:

dict

computeTransitionObservables_one_transition(tr, rtol=0.0001, nAction=50)

Calculate the GW observables after the phase tracing and the computation of the nucleation temperature have been performed. Radiation in pot.kin_coupled_* is in thermal equilibrium with the fields of the potential and reheated with them; radiation in pot.kin_decoupled_* is not reheated and keeps the temperature of the false vacuum (see “Radiation baths” in the usage documentation).

Parameters:

• tr (TransitionInfo) – The transition information for which to compute observables.

• rtol (float, optional) – Relative tolerance for the computation. Default is 1e-4.

• nAction (int, optional) – Number of action points to consider. Default is 50.

Returns:

GWparams – Dictionary with the GW parameters.

Return type:

tuple (float)

items()

Return key/value pairs of the transition observables.

keys()

Expose the transition keys.

printDerivedParams(derived_param_names)

Print a rich-formatted table of the derived parameters per transition.

transitionlistener.transitionObservables.build_action_spline(TSYM, S)

The percolation action spline, bounded so the rate vanishes above the computed range.

Above the hottest temperature whose action was computed there is no nucleation, not a constant action. Holding the action constant lets S/T fall as T rises, so the rate grows towards high temperature, which is backwards: the barrier grows there and the rate has to vanish. Measured on the 2HDM at lambda3 = 5.7727298627, where the action solve failed at the hot end of the support: the action was held at its value at T = 49.28, S3/T fell from 151.0 to 130.2 by T = 57.18, and the bubble number density came out 7340 times too large, which put the mean bubble separation 19 times too low and betaH_RH at 1883 against 99 and 96 at the neighbouring couplings. An infinite action gives a rate of zero there, which is the limit, and is what the estimator’s own spline in percolation_adaptivestepsize already returns.

There is deliberately no _fixedstep twin of this. That backend builds its own Sint as an interp1d over the finite-action temperatures with fill_value=(-inf, +inf), so it already returns an infinite action above its data, and its bubble-number integral runs to the hottest support temperature only because the integrand is identically zero above the last computed action.

transitionlistener.transitionObservables.hottest_known_action_temperature(support_T, support_S)

The upper limit of the bubble-number integral: the hottest temperature with an action.

Not the hottest in the support. A temperature whose solve failed carries no integrand, and taking it as the bound integrates over a stretch the action spline has no data for. The two differ only where a solve failed at the hot end, which was one coupling of the 333 resolved across the validation scans.

The caller’s guard establishes the temperatures, not the actions, and PercolationResult.S is optional and need not line up with TSYM, so anything unusable here falls back to the bound this used before rather than raising.

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

transitionlistener.bubbledynamics.ENTROPY_SCHEME_DEFAULT_THRESHOLD = 0.04

Default for percolation_entropy_scheme_warn_threshold; see config.PercolationConf.

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.PercolationDiagnostics(start_temperature=None, final_active_support_points=0, total_unique_percolation_support_points=0, total_unique_action_temperatures=0, rebuild_count=0, support_bank_temperatures=None, action_temperatures=None, spline_tnuc=None, spline_tnuc_warning=None, spline_tnuc_max_N=nan, spline_tnuc_integral_prefactor=nan, action_jitter_max_residual_oom=nan, action_jitter_temperature=None, action_jitter_probability=None, action_jitter_log10_gamma_h4=None, action_jitter_log10_gamma_h4_smooth=None, action_jitter_rescue_attempts=0, action_jitter_rescue_success=False, action_jitter_rescue_temperatures=None, action_jitter_rescue_discarded_temperatures=None, accuracy_targets_met=None, accuracy_tperc_uncertainty=nan, accuracy_tfinal_uncertainty=nan, accuracy_rh_uncertainty=nan)

Bases: object

Percolation diagnostics returned together with the final support bank.

The solver keeps only diagnostics that are still used by the production adaptive step size percolation workflow and its current validation scripts.

accuracy_rh_uncertainty: float = nan

accuracy_targets_met: bool | None = None

accuracy_tfinal_uncertainty: float = nan

accuracy_tperc_uncertainty: float = nan

action_jitter_log10_gamma_h4: float | None = None

action_jitter_log10_gamma_h4_smooth: float | None = None

action_jitter_max_residual_oom: float = nan

action_jitter_probability: float | None = None

action_jitter_rescue_attempts: int = 0

action_jitter_rescue_discarded_temperatures: list[float] | None = None

action_jitter_rescue_success: bool = False

action_jitter_rescue_temperatures: list[float] | None = None

action_jitter_temperature: float | None = None

action_temperatures: list[float] | None = None

final_active_support_points: int = 0

classmethod from_state(state, grid, jitter_diagnostic, tnuc_estimate)

Build a serialisable diagnostics snapshot from the final solver state.

Return type:

PercolationDiagnostics

rebuild_count: int = 0

spline_tnuc: float | None = None

spline_tnuc_integral_prefactor: float = nan

spline_tnuc_max_N: float = nan

spline_tnuc_warning: str | None = None

start_temperature: float | None = None

support_bank_temperatures: list[float] | None = None

total_unique_action_temperatures: int = 0

total_unique_percolation_support_points: int = 0

class transitionlistener.bubbledynamics.PercolationGrid(TSYM, Tstart, TpercApprox, tmin, tmax, TBROmin, TBROmax, free_support_bank=None)

Bases: object

Initial temperature grid and traced phase-overlap bounds for percolation.

TBROmax: float

TBROmin: float

TSYM: ndarray

TpercApprox: float

Tstart: float

free_support_bank: ndarray | None = None

tmax: float

tmin: float

class transitionlistener.bubbledynamics.PercolationState(TSYM, Sr, Hr, Pr, Tb, explored_tmin=None, rebuild_count=0, rate_refine_points=0, support_bank=None, free_support_bank=None, action_temperatures=None, Sr_computed=None, cold_tail_last_temperature=None, cold_tail_last_probability=None, cold_tail_last_integral=None, cold_tail_last_log_gamma_h4=None, cold_tail_post_peak_streak=0, accuracy_estimate=None)

Bases: object

Current percolation profile plus support-bank diagnostics.

Hr: ndarray

Pr: ndarray

Sr: ndarray

Sr_computed: ndarray | None = None

TSYM: ndarray

Tb: ndarray

accuracy_estimate: dict | None = None

action_temperatures: ndarray | None = None

cold_tail_last_integral: float | None = None

cold_tail_last_log_gamma_h4: float | None = None

cold_tail_last_probability: float | None = None

cold_tail_last_temperature: float | None = None

cold_tail_post_peak_streak: int = 0

explored_tmin: float | None = None

free_support_bank: ndarray | None = None

rate_refine_points: int = 0

rebuild_count: int = 0

support_bank: ndarray | None = None

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.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, return_wall_strength=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. The hydro coupling is read from pot.config.gwConf.coupled_hydrodynamics.

Parameters:

T (float) – Temperature at which to evaluate alpha

Returns:

tuple – (alpha_p, alpha_theta, alpha_thetabar, alpha_e, alpha_hyd, alpha_inf, alpha_eq), and alpha_hyd_wall as an eighth entry if return_wall_strength is true. alpha_theta is the bag-model strength fed to the GW-signal / kappa() pipeline; alpha_thetabar is the beyond-bag pseudo-trace-anomaly definition from arXiv:2004.06995, which divides the pressure of both phases by the sound speed of the broken phase.

Return type:

float

transitionlistener.bubbledynamics.calcApproxPercolation(outdict, pot, 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.

• 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.calcMeanBubbleSeparation(T, Tmax, Sint, Pint, Hint, entropyInt=None, coolingInt=None, verbose=False, *, logEntropyInt=None)

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

• Sint (scipy.interpolate.interp1d object) – The action

• Pint (scipy.interpolate.interp1d object) – The true vacuum fraction.

• Hint (scipy.interpolate.interp1d object) – The Hubble rate

• entropyInt (callable, optional) – Entropy density of the expansion history, entropyInt(T) ~ a(T)^-3. Only its ratios enter, so any normalisation will do. None falls back to the bag relation s ~ T^3, i.e. a ~ 1/T. It is limited to histories of at most about 236 e-folds, beyond which a^-3 underflows; use logEntropyInt there.

• logEntropyInt (callable, keyword only, optional) – ln s(T) = -3 ln a(T), up to an additive constant, in place of entropyInt. The ratio is then formed as a difference of logarithms and stays exact over the whole range _time_temperature_factors allows. This is what expansion_interpolants returns. It takes precedence over entropyInt.

• coolingInt (callable, optional) –

  coolingInt(T) = 3 c_s^2(T), the factor the integrand is divided by, since dt = -dT / (3 c_s^2 H T). It is 3 c_s^2, not 1 / (3 c_s^2). None falls back to the bag relation, 3 c_s^2 = 1.

  Both come from expansion_interpolants, built from the same factors as the percolation integral, so that the separation uses the history that fixed Tperc. With both None the previous bag-limit integration is reproduced exactly, on the same linear temperature grid.

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, return_metadata=False)

Compute the percolation profile with the configured percolation algorithm.

The public return shape is kept for compatibility: Tperc, TSYM, H, P, Tb, S plus optional diagnostics metadata.

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

Compute the symmetric-phase sound speed squared at (X, T).

Decoupled radiation is excluded because it does not participate in the local time-temperature relation of the transitioning plasma.

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.

• Pint (scipy.interpolate.interp1d object) – The true vacuum fraction.

• pot (generic_potential) – The effective potential. Only pot.config.percolationConf.f_final is read.

• verbose (bool) – Print the error message if the solve for the final temperature fails, just before PercolationError is raised. Nothing is printed on success.

Returns:

Tf – Final temperature.

Return type:

float

transitionlistener.bubbledynamics.calc_betaH_S3(T, Sint, outdict, pot, phase_sym, phase_bro, verbose=False, diagnostics=None)

Calculate the phase transition speed from the action derivative.

beta/H = T d(S3/T)/dT at T, estimated by a local least-squares quadratic through the action samples of the percolation support rather than from the slope of an interpolating spline. The adaptive support places samples as close as 1e-6 T apart; an interpolant forced exactly through them converts an irregular 1e-2 error in S3/T (path-deformation noise) into errors of hundreds in beta/H, while a fit over the nearest samples averages it out.

The sample selection is controlled by percolationConf:

• betaH_S3_fit_points nearest samples are used;

• at least betaH_S3_fit_min_per_side of them must lie on each side of T and none further than betaH_S3_fit_max_rel_span in |T'/T - 1|, otherwise five new actions are computed at T (1 + k step), k = -2..2, with step betaH_S3_fallback_rel_step, and the same fit is applied;

• the fit is repeated with the betaH_S3_fit_check_points nearest samples, and a relative difference above betaH_S3_fit_rel_tol, measured against the larger of the two, is reported through diagnostics["fit_unstable"].

Both sample counts are clamped: a quadratic needs three samples, and the check fit uses at most as many as the fit itself, in which case it is skipped.

See the CAUTION note in PercolationConf: the defaults were validated on the 2HDM BSMPT benchmark only.

Parameters:

• T (float) – The temperature at which to evaluate beta/H

• Sint (interpolate.interp1d) – Interpolation of the action; its nodes Sint.x are the support samples

• 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) phase

• diagnostics (dict, optional) – Filled with the samples used, the fallback flag, the check-fit value and fit_unstable.

Returns:

The transition speed beta/H.

Return type:

float

transitionlistener.bubbledynamics.calc_betaH_S3_approx(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.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.entropy_density(pot, phase, T, definition='dof_table')

Entropy density of the plasma of the traced phase, in the chosen scheme.

Only ratios and logarithmic derivatives of this quantity are used, so the constant 2 pi^2/45 is dropped from the counted form and the two schemes are not on a common absolute normalisation.

Both describe the same plasma: the fields of the potential and the coupled radiation bath, without the decoupled one. They differ in how they treat the fields. "dof_table" counts them as free particles at their zero-temperature masses and adds the tabulated entropy degrees of freedom of the coupled bath. "eff_potential" takes -dV/dT, which gives the fields their thermal masses and the Arnold-Espinosa daisy term, and which carries the tabulated bath with its perturbative corrections as well, since the field-independent part of the potential is built from the same tables. What it does not have is those corrections for the fields of the potential themselves. Neither route contains the other; see the entropy_definition setting.

Return type:

float

transitionlistener.bubbledynamics.entropy_scheme_is_sensitive(cs_sq_spread, threshold)

Whether a point’s expansion history depends appreciably on the entropy scheme.

The criterion is the spread of 3 c_s^2 between the two schemes and never the gap in ln a: the spread estimates the relative shift the mean bubble separation takes between them to about thirty per cent, while the gap is biased by a factor that depends on the model. A spread that could not be computed is not a clean point, so it leaves the flag unset and the nan visible beside it rather than raising anything.

Return type:

bool

transitionlistener.bubbledynamics.entropy_scheme_sensitivity(pot, phase_symmetric, T, *, time_temperature_mode=None, entropy_definition=None, configured_history=None)

How much the choice of entropy scheme matters on this percolation support.

The two schemes of ENTROPY_DEFINITIONS are two approximations to one entropy density, and neither contains the other, so the difference between them is a modelling uncertainty of the expansion history rather than a numerical error. It is reported rather than corrected, because nothing in the literature chooses between them.

Two numbers, both on the support that fixed the percolation temperature:

cs_sq_spread

the median relative difference between the two schemes’ 3 c_s^2 over the support. Measured over 91 points of four scan lines against the shift each point’s mean bubble separation actually takes between the schemes, this is an estimate of that shift: the ratio of the two has median 1.06 and lies between 0.88 and 1.29 for eight points in ten, and 93% of points agree within a factor of two. The bias is the same on every line tested, between 1.00 and 1.17.

scale_factor_shift

the gap between the two schemes in |delta ln a| across the support, not the expansion itself. Since d ln a/d ln T = -1/(3 c_s^2) and ln a = -(1/3) ln s up to a constant, this is the difference of the two schemes’ logarithmic entropy ratios over three, and it is the first-order estimate of the relative shift it would produce in the mean bubble separation.

Pass configured_history as the (logEntropyInt, coolingInt) pair already built for the configured scheme, and only the other scheme is evaluated: one further history rather than two, and the comparison is then made against the very history the observables came from. One history is three entropy_density evaluations per support point, at the temperature and at both endpoints of the derivative stencil, so handing the configured one over halves the cost of the comparison.

Returns:

(cs_sq_spread, scale_factor_shift), or (nan, nan) where the comparison cannot be made: in bag mode, on a support of fewer than two temperatures, or where one of the schemes has no usable history.

Return type:

tuple

transitionlistener.bubbledynamics.entropy_scheme_threshold(conf)

The spread above which a point is flagged, for a percolation configuration.

A configuration built before the setting existed does not carry it, and must then get the documented default rather than a second number written out at the call site.

The value is validated here and not only in the run-time overrides, because a model is free to assign config.percolationConf attributes directly and most of them do. A threshold of zero or below would flag every point that has any spread at all, which is not “flag nothing”; a run that should flag nothing switches the comparison off with entropy_scheme_diagnostic.

Return type:

float

transitionlistener.bubbledynamics.estimate_spline_tnuc_from_rate_history(T, H, S, P, vw=1.0)

Estimate Tnuc from the saved rate/P/H splines without new actions.

The diagnostic solves

N(T) = 4*pi/3 * v_w^3 * int_T^Tinit Gamma/H^4 * (1-P) dT/T = 1

on a dense spline grid. It is intentionally warning-only: if the final action bank does not bracket N=1 the caller can still return a valid percolation result and expose the failure category in metadata.

Return type:

dict[str, float | str | None]

transitionlistener.bubbledynamics.expansion_interpolants(pot, phase_symmetric, T, *, time_temperature_mode=None, entropy_definition=None)

Interpolants of the expansion history for calcMeanBubbleSeparation.

Built from the same _time_temperature_factors as the percolation integral, on the temperatures T of the percolation support, so that the mean bubble separation uses the history that fixed Tperc. Adiabatic expansion gives d ln a / dT = -1/(3 c_s^2 T), hence dt = -dT / (3 c_s^2 H T) and an entropy density s ~ a^-3.

Returns:

(logEntropyInt, coolingInt) with logEntropyInt(T) = ln s(T) = -3 ln a(T) up to an additive constant, and coolingInt(T) = 3 c_s^2(T); or (None, None) when the history is the bag limit, s ~ T^3 and 3 c_s^2 = 1.

The logarithm is handed over rather than s itself because _time_temperature_factors allows ln a up to 700, where s ~ a^-3 underflows to zero and the ratio that the separation needs can no longer be recovered from it.

Return type:

tuple

transitionlistener.bubbledynamics.falseVacuumVolumeGrowthRate(TSYM, P, T, cs_sq=0.3333333333333333)

Growth rate of the physical false-vacuum volume, in units of 3H.

The false vacuum occupies a physical volume \(\mathcal{V}_{\rm false} \propto a^3 (1 - P_{\rm true}) = a^3 e^{-I}\), which has to shrink for the transition to complete rather than to inflate forever. This requirement goes back to Turner, Weinberg and Widrow, Phys. Rev. D 46 (1992) 2384; the temperature form used here is eq. (2.26) of Ellis, Lewicki and No, arXiv:1809.08242, and we refer to it as the Lewicki criterion,

\[\frac{1}{\mathcal{V}_{\rm false}} \frac{{\rm d}\mathcal{V}_{\rm false}}{{\rm d}t} = H\left(3 + T\frac{{\rm d}I}{{\rm d}T}\right) < 0 \,.\]

That form assumes the radiation relation \({\rm d}T/{\rm d}t = -HT\). TransitionListener integrates the percolation history with the generalized relation \({\rm d}T/{\rm d}t = -3 c_{\rm s}^2 H T\), for which

\[\frac{1}{\mathcal{V}_{\rm false}} \frac{{\rm d}\mathcal{V}_{\rm false}}{{\rm d}t} = 3H\left(1 + c_{\rm s}^2 T \frac{{\rm d}I}{{\rm d}T}\right) \,,\]

and the returned quantity is the bracket. With \(c_{\rm s}^2 = 1/3\) it reduces to \((3 + T\,{\rm d}I/{\rm d}T)/3\), i.e. to the published criterion divided by three, so the sign is unchanged.

The derivative is taken on a monotonic spline of \(\ln I\) rather than of \(P\), because \(I = -\ln(1 - P_{\rm true})\) spans decades over the sampled range while \(P\) saturates.

Parameters:

• TSYM (array_like) – Symmetric-phase temperatures of the percolation history.

• P (array_like) – True-vacuum fraction at those temperatures.

• T (float) – Temperature at which to evaluate the criterion, typically Tperc.

• cs_sq (float, optional) – Sound speed squared entering the time-temperature relation. Pass 1/3 for the bag limit, which reproduces the published form.

Returns:

1 + cs_sq * T * dI/dT. Negative means the false-vacuum volume is shrinking, i.e. the criterion is fulfilled. np.nan when the percolation history is too sparse to differentiate.

Return type:

float

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

Calculate the effective energy degrees of freedom of the fields of the potential.

Every mode counts, the Goldstone modes included, and the ghosts of the gauge bosons are subtracted, as in radiationEnergyDensity. Fields flagged is_SM (e.g. W, Z, t and h in the 2HDM) count here and are removed from the tabulated bath in turn (thermodynamics.sm_fields_in_potential_geff), so that each of them is counted once.

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 of the fields of the potential.

Every mode counts, the Goldstone modes included, and the ghosts of the gauge bosons are subtracted, as in radiationEnergyDensity. Fields flagged is_SM (e.g. W, Z, t and h in the 2HDM) count here and are removed from the tabulated bath in turn (thermodynamics.sm_fields_in_potential_geff), so that each of them is counted once.

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.h_eff_coupled_radiation(T, pot)

Entropy degrees of freedom of the radiation coupled to the transitioning sector.

That radiation (pot.kin_coupled_*, by default the Standard Model) is reheated inside the bubbles together with the transitioning sector, a decoupled bath is not. For the default Standard Model bath the tabulated entropy degrees of freedom are used; otherwise s = (e + p)/T gives h = (3 g_e + g_p)/4.

Return type:

float

transitionlistener.bubbledynamics.integrate_broken_temperature(pot, phase_symmetric, phase_broken, TSYM, P, T_target, *, p_seed=1e-06, rtol=1e-08, atol=0.0)

Integrate the broken-phase temperature down to T_target.

The step-3 profile obtains the broken-phase temperature by stepping from one support point to the next: an entropy-conserving update followed by an energy correction for the volume fraction converted during the step. Those steps are a first-order discretisation of

\[\frac{dT_b}{dT} = \frac{3\,S(T_b)}{T\,S'(T_b)} + \frac{P'(T)}{P(T)}\,\frac{e_s(T) - E(T_b)}{E'(T_b)} ,\]

with \(S(x) = [h_{\rm ds}(x) + h_{\rm SM}(x)]\,x^3\) proportional to the entropy density of the broken phase and \(E\) its energy density. Reading the reheating temperature off that tabulated trajectory makes it depend on where the support points happen to sit, which shows up as point-to-point scatter along smooth parameter scans. Solving the equation with an error-controlled integrator makes the result depend on a tolerance instead.

The true-vacuum fraction enters through the source term. Its derivative is taken on a spline of \(\ln I\), with \(I = -\ln(1-P)\) the percolation integral, which is smooth and monotone, rather than on a spline of \(P\), which sweeps from 0 to 1 and whose derivative depends strongly on the node placement. The integration starts where the true-vacuum fraction first reaches p_seed, located in the same variable, with the instantaneous-reheating condition as initial value.

Returns the broken-phase temperature at T_target, or None if the integration could not be carried out.

transitionlistener.bubbledynamics.logGamma(T, S)

Calculate the natural logarithm of the bubble nucleation rate.

Parameters:

• T (float | np.ndarray) – Symmetric phase temperature

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

Returns:

logGamma – ln Gamma, i.e. 4 ln T + (3/2) ln(S/2 pi T) - S/T. It is +inf where the action vanishes and not a number where the action is infinite.

Return type:

np.ndarray

transitionlistener.bubbledynamics.percIntegral(T, H, S, vw=1.0, *, entropy_density=None, cooling_factor=None, scale_factor=None)

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)

• entropy_density (np.ndarray, optional) – Entropy density of the expansion history, s ~ a^-3. Only its ratios enter. With both this and scale_factor left at None the bag relation s ~ T^3 is used.

• cooling_factor (np.ndarray, optional) – 3 c_s^2, the divisor of the transport factor, since dt = -dT / (3 c_s^2 H T). None means the bag relation 3 c_s^2 = 1.

• scale_factor (np.ndarray, optional) – a(T) itself, in place of entropy_density; only ratios to a(T[0]) enter. Preferred where the history spans many e-folds, since a^-3 underflows to zero once ln a exceeds about 236 and the ratio then has to be rebuilt from values that no longer carry it, while a stays representable to ln a of 709. Passing both is an error.

Returns:

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

Return type:

float

transitionlistener.bubbledynamics.percIntegralODE(T, H, S, vw=1.0, *, sound_speed_sq=None, scale_factor=None, i_target=None)

Compute I(T_i) at every grid point via the J_n ODE chain.

With i_target the solver additionally records the temperature at which the percolation integral reaches that value, and the return value becomes the pair (I_values, crossing_temperature), where the crossing is None if the target is not reached. Taking the crossing from the integrator avoids reading it back off an interpolation of the sampled I values.

With sound_speed_sq and scale_factor this solves the generalized EOS form using gamma = Gamma a^3 / (H T 3 c_s^2) and nu = 1 / (H T 3 c_s^2 a). Without those arrays it falls back to the historical bag-limit relation, where c_s^2 = 1/3 and a(T) cancels to the simpler transport factor 1/H.

Parameters:

• T (np.ndarray) – Temperatures in descending order (T[0] = hottest).

• H (np.ndarray) – Hubble rate at each temperature.

• S (np.ndarray) – Bounce action S_3 at each temperature.

• vw (float) – Bubble-wall velocity.

Returns:

I(T_i) at each grid point (same length as T). P(T_i) = 1 - exp(-I(T_i)). With i_target, the pair (I_values, crossing_temperature).

Return type:

np.ndarray or tuple

transitionlistener.bubbledynamics.percIntegralODE_full_sweep(T, H, S, vw=1.0, *, pot=None, phase_symmetric=None, time_temperature_mode=None, integral_method=None, entropy_definition=None)

One-shot ODE sweep: compute both I(T_i) and P(T_i) at every grid point.

This replaces the per-point percIntegral calls in the step-2 / step-3 inner loops.

Parameters:

• T (np.ndarray) – Temperatures (descending), Hubble rates, bounce actions.

• H (np.ndarray) – Temperatures (descending), Hubble rates, bounce actions.

• S (np.ndarray) – Temperatures (descending), Hubble rates, bounce actions.

• vw (float) – Bubble-wall velocity.

Return type:

tuple[ndarray, ndarray]

Returns:

• I_values (np.ndarray) – Percolation integral I(T_i) at each grid point.

• P_values (np.ndarray) – True-vacuum fraction P(T_i) = 1 - exp(-I(T_i)).

transitionlistener.bubbledynamics.percolation_sound_speed_sq(pot, phase_symmetric, T, *, time_temperature_mode=None, entropy_definition=None)

Sound speed squared of the time-temperature relation used for the percolation history.

Mirrors percIntegralODE_full_sweep: the bag mode integrates with dT/dt = -H T, i.e. c_s^2 = 1/3; sound_speed mode uses the symmetric-phase value from _time_temperature_factors, including its fallback to 1/3. The integral method no longer enters, both integrate the same relation.

Return type:

float

transitionlistener.bubbledynamics.percolation_temperature_from_ode(T, H, S, *, vw, pot, phase_symmetric, time_temperature_mode, f_perc, entropy_definition=None)

Return the percolation temperature straight from the integrator.

The profile sweep tabulates the true-vacuum fraction on the support grid, and the percolation temperature is normally recovered by interpolating those samples and root-finding on them. That read-off moves when the support points move. Here the same ODE is integrated once more with an event at the target value of the percolation integral, so the crossing is located by the integrator itself. Returns None if it cannot be found.

transitionlistener.bubbledynamics.percolation_uses_sound_speed(time_temperature_mode)

Whether the percolation history uses the sound speed of the plasma.

Both integral methods do in sound_speed mode (the default); the bag mode integrates with dT/dt = -H T, i.e. c_s^2 = 1/3. Every quantity read off that history (Tperc, the mean bubble separation, beta/H) must use the same relation.

Return type:

bool

transitionlistener.bubbledynamics.record_entropy_scheme_diagnostics(derived, pot, phase_symmetric, T, conf, configured_history=None, verbose=False, console=None)

Write the entropy-scheme diagnostics and flag into derived.

All three keys are set on every path. Where the comparison does not apply, because it is switched off, because the time-temperature relation reads no entropy, or because the configured history could not be built, the flag is False and both numbers are nan: the keys are registered for every run, so leaving them unset would have the writer report them as unimplemented and fill all three with nan, the boolean included.

A timeout reaches the caller. Any other failure of the comparison leaves the nan and must not invalidate the point, which was computed before the comparison was asked for.

Return type:

None

transitionlistener.bubbledynamics.validate_entropy_definition(entropy_definition)

Return the entropy definition to use, refusing anything unknown.

Only None means “not given”: an empty string is a value, and a wrong one.

Return type:

str

Model-independent potential definitions

The primary task of the generic_potential module is to define the generic_potential class, from which realistic scalar field models can straightforwardly be constructed. The most important part of any such model is, appropriately, the potential function and its gradient. This present module is not necessary to define a potential, but it does make the process somewhat simpler by automatically calculating one-loop effects from a model-specific mass spectrum, constructing numerical derivative functions, providing a simplified interface to the transitionFinder module, and providing several methods for plotting the potential and its phases.

The generic_potential class has to provide the following information to the rest of the code:

1. Vtot, dVdx, dVdT, d2Vdx (Potential)

2. energyDensity (the total energy density at a given temperature)

3. configuration

4. Tmax, Tmin (range of validitiy of the potential)

5. conversionFactor (conversion between internal units and GeV)

6. X0 (zero temperature global minimum)

7. Mass spectrum of the theory.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.generic_potential.generic_potential(*args, **dargs)

Bases: object

An abstract class from which one can easily create finite-temperature effective potentials.

This class acts as the skeleton around which different scalar field models can be formed. At a bare minimum, subclasses must implement init(), V0(), and they must provide a MassSpectrum instance via self.mass_spectrum. Subclasses will also likely implement approxZeroTMin(). Once the tree-level potential and particle spectrum are defined, the one-loop zero-temperature potential (using MS-bar renormalization) and finite-temperature potential can be used without any further modification.

If one wishes to rewrite the effective potential from scratch (that is, using a different method to calculate one-loop and finite-temperature corrections), this class and its various helper functions can still be used. In that case, one would need to override Vtot() (used by most of the helper functions) and V1T_from_X() (which should only return the temperature-dependent part of Vtot; used in temperature derivative calculations), and possibly override V0() (used by massSqMatrix() and for plotting at tree level).

Such a model must also override V_thermal(), which is the temperature-dependent part of the potential on its own and is what the sound speed, the transition strengths and the wall velocity are taken from. It is a separate hook from V1T_from_X() because the two differ in what they include: V_thermal() carries the radiation bath that its include_decoupled argument selects and the daisy term, while the base V1T_from_X() carries neither. Overriding the potential without it raises errors.PotentialError rather than reconstructing a thermal part from the mass spectrum, which would not be the model’s own.

The __init__ function performs initialization specific for this abstract class. Subclasses should either override this initialization but make sure to call the parent implementation, or, more simply, override the init() method. In the base implementation, the former calls the latter and the latter does nothing. At a bare minimum, subclasses must set the Ndim parameter to the number of dynamic field dimensions in the model.

One of the main jobs of this class is to provide an easy interface for calculating the phase structure and phase transitions. These are given by the methods getPhases(), calcTcTrans(), and findAllTransitions().

The following attributes can (and should!) be set during initialiation:

Ndim

The number of dynamic field dimensions in the model. This must be overridden by subclasses during initialization.

Type:

int

x_eps

The epsilon to use in brute-force evalutations of the gradient and for the second derivatives. May be overridden by subclasses; defaults to 0.001.

Type:

float

T_eps

The epsilon to use in brute-force evalutations of the temperature derivative. May be overridden by subclasses; defaults to 0.001.

Type:

float

deriv_order

Sets the order to which finite difference derivatives are calculated. Must be 2 or 4. May be overridden by subclasses; defaults to 4.

Type:

int

renormScaleSq

The square of the renormalization scale to use in the MS-bar one-loop zero-temp potential. May be overridden by subclasses; defaults to 1000.0**2 in internal units.

Type:

float

Tmax

The maximum temperature to which minima should be followed. No transitions are calculated above this temperature. This is also used as the overall temperature scale in getPhases(). May be overridden by subclasses; defaults to 1000.0 in internal units.

Type:

float

DVtot(X, T)

The finite temperature effective potential, but offset such that V(0, T) = 0.

Parameters:

• X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float or array_like) – The temperature. The shapes of X and T should be such that X.shape[:-1] and T.shape are broadcastable (that is, X[...,0]*T is a valid operation).

Returns:

The effective potential at the given field values and temperatures, offset such that V(0, T) = 0.

Return type:

np.ndarray

V0(X)

Tree level potential. This has to be overwritten by the subclass.

Parameters:

X (np.ndarray) – Field values.

Returns:

Potential values corresponding to the field values.

Return type:

np.ndarray

V1(bosons, fermions)

The one-loop corrections to the zero-temperature potential using MS-bar renormalization.

This is generally not called directly, but is instead used by Vtot().

Return type:

ndarray

V1T(bosons, fermions, T)

The one-loop finite-temperature potential.

This is generally not called directly, but is instead used by Vtot(). :rtype: ndarray

Note

The Jf and Jb functions used here are aliases for finiteT.Jf_spline() and finiteT.Jb_spline(), each of which accept mass over temperature squared as inputs (this allows for negative mass-squared values, which I take to be the real part of the defining integrals.

V1T_from_X(X, T)

Calculates the mass matrix and resulting one-loop finite-T potential.

Useful when calculate temperature derivatives, when the zero-temperature contributions don’t matter.

Return type:

ndarray

V1_from_X(X)

The one-loop corrections to the zero-temperature potential using MS-bar renormalization.

This is generally not called directly, but is instead used by Vtot().

Return type:

ndarray

V1phys(bosons, fermions)

The one-loop corrections to the zero-temperature potential using MS-bar renormalization, without the goldstone bosons.

Return type:

ndarray

V_thermal(X, T, include_decoupled=False)

The temperature-dependent part of the effective potential, on its own.

Vtot is V0 + V1 + Vct plus this. The first three do not depend on the temperature, so they drop out of every temperature derivative analytically, but not numerically: forming the sum first and differencing afterwards subtracts the vacuum energy from itself, and under supercooling the thermal part is ten or more orders of magnitude smaller. On the conformal dark U(1) of examples/example_point.yaml the thermal part is 7e-4 of the vacuum energy at the percolation temperature and 1e-13 of it two decades below, where a second temperature derivative of the whole potential has no significant digits left.

Return type:

float | ndarray

Vct(X)

The one-loop counterterm potential for MS-bar renormalization. This should be overwritten.

Return type:

ndarray

Vdaisy(bosons0, bosonsT, T, Pi=None)

Calculate the daisy resummation term for the Arnold-Espinosa prescription.

Parameters:

• bosons0 (tuple) – Boson mass spectrum at zero temperature.

• bosonsT (tuple) – Boson mass spectrum at finite temperature.

• T (float) – Temperature.

Returns:

Daisy resummation potential correction to V1T.

Return type:

float

Vdaisy_from_X(X, T, realDaisy=False)

Calculate the daisy resummation term for the Arnold-Espinosa prescription.

Parameters:

• bosons0 (tuple) – Boson mass spectrum at zero temperature.

• bosonsT (tuple) – Boson mass spectrum at finite temperature.

• T (float) – Temperature.

• realDaisy (bool) – If True, enforce real-valued calculations.

Returns:

Daisy resummation potential correction to V1T.

Return type:

float

Vtot(X, T, include_radiation=True, include_decoupled=True)

The total finite temperature effective potential is calculated by adding up the tree level potential, the one-loop-zero-T correction, the respective counter terms, and (depending on the daisy resummation scheme) the one-loop- temperature-dependent corrections.

Parameters:

• X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float or array_like) – The temperature. The shapes of X and T should be such that X.shape[:-1] and T.shape are broadcastable (that is, X[...,0]*T is a valid operation).

• include_radiation (bool, optional) – If False, this will drop all field-independent radiation terms from the effective potential. Useful for calculating differences or derivatives.

• include_decoupled (bool, optional) – If True, include radiation terms of the specified decoupled radiation bath, if false, don’t include them. This is important, for e.g. the calculation of alpha for a decoupled SM and DS.

Returns:

Vtot – Total effective potential.

Return type:

array_like

applySymmetries(X)

Check if the point is in the right quadrant of field space and transform it if necessary.

This is done in the fashion of BSMPT with the measure

..math::

M(g phi) = sum_i 2^i theta((g phi)_i)

This measure is maximised for one unique ‘quadrant’ in fieldspace.

Parameters:

X (np.ndarray) – Point in field space.

Returns:

The transformed point.

Return type:

np.ndarray

approxZeroTMin()

Returns approximate values of the zero-temperature minima.

This should be overridden by subclasses, although it is not strictly necessary if there is only one minimum at tree level. The precise values of the minima will later be found using scipy.optimize.fmin().

Returns:

minima – A list of points of the approximate minima.

Return type:

list

boson_massSq(X, T)

Return the bosonic mass spectrum \(m_i^2(\phi, T)\) of the model.

Subclasses typically implement the actual mass matrices through self.mass_spectrum. The returned tuple is forwarded to the one-loop and thermal-potential routines, which use the bosonic contribution

\[V_1^{B}(\phi, T=0) = \sum_i \frac{n_i\,m_i^4(\phi,0)}{64\pi^2} \left[\log\!\left(\frac{m_i^2(\phi,0)}{\mu^2}\right)-c_i\right].\]

Parameters:

• X – Field configuration \(\phi\).

• T – Temperature in internal units.

checkInitialisation()

Check if all the necessary paramters in the subclass initialisation are set.

Return type:

None

check_renorm_conditions(X=None, *, eps=None, order=None)

Return derivatives of V1 + Vct at the given field point.

This provides a quick diagnostic for OS-like counterterm conditions that enforce vanishing first and second derivatives of V1 + Vct at the reference vacuum.

Return type:

dict[str, ndarray]

coleman_weinberg_from_curvatures(tensors, vev, *, scale)

Evaluate Coleman–Weinberg derivatives from curvature tensors.

Parameters:

• tensors (dict[str, ndarray]) – Dictionary containing the Higgs, gauge, and Yukawa curvature tensors in the gauge basis. The expected keys are H2, H3, H4, Gauge, Quark, and Lepton.

• vev (ndarray) – Vacuum expectation value vector expressed in the same field basis as the tensors (typically the eight-dimensional Higgs basis).

• scale (float) – Renormalisation scale \(\mu\) entering the Coleman–Weinberg logarithms.

Returns:

(gradient, hessian) – Coleman–Weinberg first and second derivatives in physical units.

Return type:

np.ndarray

computeConversionFactor(v_stable, v_GeV)

compute the conversionFactor to go from internal units to GeV.

Return type:

float

constantTerms(T, include_decoupled=False)

Add the field-independent, but temperature-dependent terms to the effective potential, i.e. radiation. This allows the calculation of the energy density as

\[\rho = V - \partial_T V\]

This should be computed from the particle definitions in the potential.

Parameters:

• T (float or array_like) – The temperatures

• include_decoupled (bool, optional) – If False, don’t include the contribution of the specified decoupled radiation bath specified in self.kin_decoupled_p_geff.

Returns:

The field-independent but temperature-dependent contribution to the effective potential.

Return type:

array_like

counterterm_derivative_step: float = 0.001

Finite-difference step, in internal field units, for the derivatives of the zero-temperature one-loop potential at the vev that fix the counterterms (dV1atvev, d2V1atvev, dV1physatvev). It is kept separate from the phase-tracing accuracy x_eps on purpose: tightening a tracing tolerance must not change the potential. For the abelian dark Higgs, with |V_CW| of order 1e9 at the vev, steps below 1e-3 are dominated by round-off (1e-4 shifts the second derivative by up to 1.4 %). Above it the second derivative drifts with the logarithm of the step, by 0.05 % to 0.5 % per decade: the tree-level Goldstone mass vanishes at the vacuum, so its Coleman-Weinberg term is infrared divergent there and the step acts as the regulator. The physical cure is the resummation of the Goldstone contributions, m_G^2 -> m_G^2 + (1/phi) dV_1,phys/dphi (arXiv:1406.2652, arXiv:1406.2355). 1e-3 is the step these counterterms have always been computed with in the default setup. Models may override it.

d2V(X, T)

Calculates the Hessian (second derivative) matrix for the finite-temperature effective potential.

This uses helper_functions.hessianFunction() to calculate the matrix using finite differences, with differences given by self.x_eps. Note that self.x_eps is only used directly the first time this function is called, so subsequently changing it will not have an effect.

Parameters:

• X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float or array_like) – The temperature. The shapes of X and T should be such that X.shape[:-1] and T.shape are broadcastable (that is, X[...,0]*T is a valid operation).

Returns:

The Hessian matrix of the effective potential at the given field values and temperatures.

Return type:

np.ndarray

d2V1atvev()

Find the second derivative of the one loop zero temperature potential, evaluated at the vev. Used in the function Vct to calculate the counter term lagrangian

This uses helper_functions.gradientFunction() to calculate the gradient using finite differences, with differences given by self.counterterm_derivative_step, which is independent of the phase-tracing accuracy self.x_eps. The result is cached the first time this function is called, so subsequently changing the step will not have an effect.

Returns:

• np.ndarray – The Hessian of the one-loop zero-temperature potential at the vev.

• .. todo:: – Currently, this function assumes that the vev is a point in one-dimensional field space. Generalize to arbitrary number of dimensions.

d2V_thermal_dT2(X, T, dT, include_decoupled=False)

Second temperature derivative of V_thermal(), by central difference.

d2VdT2(X, T, dT=None, include_radiation=True, include_decoupled=True)

Find the second derivative of the potential with respect to the temperature.

Parameters:

• X (np.ndarray) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float) – The temperature.

• dT (float, optional) – Temperature step for the finite-difference stencil. Defaults to the tracing temperature accuracy.

• include_radiation (bool) – Whether to include radiation contributions.

• include_decoupled (bool) – Whether to include decoupled-radiation contributions.

Returns:

The second derivative of the potential with respect to temperature at the given field values and temperatures.

Return type:

np.ndarray

dV1atvev()

Find the first derivative of the one loop zero temperature potential, evaluated at the vev. Used in the function Vct to calculate the counter term lagrangian

This uses helper_functions.gradientFunction() to calculate the gradient using finite differences, with differences given by self.counterterm_derivative_step, which is independent of the phase-tracing accuracy self.x_eps. The result is cached the first time this function is called, so subsequently changing the step will not have an effect.

Returns:

• np.ndarray – The gradient of the one-loop zero-temperature potential at the vev.

• .. todo:: – Currently, this function assumes that the vev is a point in one-dimensional field space. Generalize to arbitrary number of dimensions.

dV1physatvev()

Find the first derivative of the one loop zero temperature potential without goldstone bosons, evaluated at the vev. Used in the function Vct to calculate the counter term lagrangian

This uses helper_functions.gradientFunction() to calculate the gradient using finite differences, with differences given by self.counterterm_derivative_step, which is independent of the phase-tracing accuracy self.x_eps. The result is cached the first time this function is called, so subsequently changing the step will not have an effect.

Returns:

• np.ndarray – The gradient of the one-loop zero-temperature potential without goldstone bosons at the vev.

• .. todo:: – Currently, this function assumes that the vev is a point in one-dimensional field space. Generalize to arbitrary number of dimensions.

dV_thermal_dT(X, T, dT, include_decoupled=False)

First temperature derivative of V_thermal(), by central difference.

include_decoupled selects the same sector the caller’s other thermodynamics uses; a derivative taken on one plasma and combined with a quantity taken on another is not a thermodynamic identity. The sound speed excludes the decoupled bath, which is the default; the wall velocity follows GWConf.coupled_hydrodynamics.

dVdT(X, T, dT, include_radiation=True, include_decoupled=True)

Find the derivative of the potential with respect to the temperature.

Parameters:

• X (np.ndarray) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float) – The temperature.

• dT (float) – The change in temperature.

• include_radiation (bool) – Whether to include radiation contributions.

• include_decoupled (bool) – Whether to include decoupled-radiation contributions.

Returns:

The derivative of the potential with respect to temperature at the given field values and temperatures.

Return type:

np.ndarray

daisy_outside_validity(X, T)

Whether the daisy resummation is being used where it does not apply.

The Arnold-Espinosa term resums the zero Matsubara mode of the bosons, which is justified where that mode is infrared-enhanced, meaning m << T. Where instead m >> T a mode should be Boltzmann suppressed, and the one-loop thermal integral is: V1T goes to exactly zero. The daisy term does not. With a thermal correction Pi small against m^2 it tends to -(T^3/8 pi) sum n_i c_i m_i, a power law with no exp(-m/T) in it, so it survives where the physics says it should not and eventually exceeds the radiation that is still relativistic.

Measured on the conformal dark U(1) of examples/example_point.yaml: the daisy term is 7% of the field-independent radiation at T/v = 1e-1, equal to it at about 1e-2, thirteen times it at 1e-3 and ten million times it at 1e-9, while the lightest mode runs from m/T = 1.3 to 1.3e8. Where it dominates, the free energy goes as T^3 rather than T^4 and the sound speed of the plasma tends to 1/sqrt(2) instead of the 1/sqrt(3) of the radiation that is actually there. A sound speed above 1/sqrt(3) in a late, cold, heavily supercooled phase is therefore this, and not a property of the plasma.

This is reported and not corrected. Which resummation a model uses is the user’s choice, and a prescription that is Boltzmann suppressed at low temperature is a change to the thermodynamics rather than a guard; it is left to a change of its own.

Returns (outside, ratio) with the ratio of the daisy term to the field-independent radiation. (False, nan) where it cannot be decided, and where the model is not using this resummation at all: with daisy set to "Parwani" or "off" there is no Arnold-Espinosa term in the potential, so building one here and reporting its size would describe a prescription the run does not use.

Return type:

tuple[bool, float]

debye_massSq(X, T)

The thermal part of the boson masses squared, if the model can give it directly.

Returns an array shaped like the boson mass spectrum, or None. None is not the default: the base class measures the thermal part, as described below, and returns None only where that measurement fails its own check. A model that states its Debye masses in closed form should override this; where neither the override nor the measurement is available, the daisy term falls back to the difference of the spectra at T and at zero, which is what it used before.

That difference is badly conditioned, and the daisy term is the one place it matters. On the conformal dark U(1) of examples/example_point.yaml, at an internal temperature of 0.02, the masses squared are about 5e4 while their thermal part is about 5e-5, so the subtraction keeps seven of sixteen digits; by an internal temperature of 1e-7 it keeps none and the thermal part underflows to exactly zero, which silently removes the daisy term altogether. A model that builds its masses as m^2(X) + Pi(T) already holds Pi and can hand it over exactly, and should override this with the closed form.

The default measures it instead of declining. Where the thermal part is Pi = c(X) T^2, which is what the Arnold-Espinosa Debye masses are, the coefficient can be read off at a reference temperature high enough for the subtraction to keep its digits and then evaluated at any temperature. The reference is the model’s own scale v_stable, where Pi is of order the masses themselves.

That the thermal part goes as T^2 is assumed by nothing here: it is checked, at a second reference temperature and at two field points, and the default declines whenever the check fails.

The check is not a formality, and neither is doing it at two field points. Of the eight models shipped in models/, four pass and four fail, and the failures are all the same physics: where the bosonic masses are eigenvalues of a mass matrix whose entries go as T^2, the eigenvalues do not. Measured on models/TL_2HDM.py, the two longitudinal gauge modes move their apparent coefficient by 4.6% and 11% between T and T/2. models/TL_dark_flipflop.py fails only where both of its fields are on: along X0, where the second vanishes and the matrix is diagonal, it looks quadratic to 7e-18, and at a generic point it is off by 5e-3. A check at one field point would have accepted it and handed the daisy term a Pi that is wrong by half a per cent.

For those models there is no Pi to hand over: the daisy term needs the two spectra themselves and the subtraction is the only route, so declining is the correct answer rather than a missing feature.

Returns an array shaped like the boson mass spectrum, or None.

dgradV_dT(X, T)

Find the derivative of the gradient with respect to temperature.

This is useful when trying to follow the minima of the potential as they move with temperature.

This uses helper_functions.gradientFunction() to calculate the gradient using finite differences, with differences given by self.x_eps. Note that self.x_eps is only used directly the first time this function is called, so subsequently changing it will not have an effect.

Parameters:

• X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float or array_like) – The temperature. The shapes of X and T should be such that X.shape[:-1] and T.shape are broadcastable (that is, X[...,0]*T is a valid operation).

Returns:

The derivative of the gradient of the effective potential with respect to temperature at the given field values and temperatures.

Return type:

np.ndarray

energyDensity(X, T, include_decoupled=True)

Calculate the total energy density. It is important that Vtot includes the field independent terms (i.e. radiation terms which are prop to T^4).

\[e = V - T \partial_T V\]

Parameters:

• X (np.ndarray) – The scalar field values

• T (float|np.ndarray) – The temperature at which to compute the energy density

• include_decoupled (bool, optional) – If true, include the energy density of the decoupled radiation bath as well.

Returns:

The energy density at T.

Return type:

float|np.ndarray

energyDensityDaisy(X, T)

Return the daisy-resummation contribution to the energy density.

Subclasses with a non-trivial daisy thermal mass can override this. The default is zero and preserves the previous behaviour.

fermion_massSq(X)

Return the fermionic mass spectrum \(m_f^2(\phi)\) of the model.

The tuple is used in the fermionic one-loop correction

\[V_1^{F}(\phi) = -\sum_f \frac{n_f\,m_f^4(\phi)}{64\pi^2} \left[\log\!\left(\frac{m_f^2(\phi)}{\mu^2}\right)-\tfrac{3}{2}\right].\]

Parameters:

X – Field configuration \(\phi\).

findMinimum(X=None, T=0.0)

Convenience function for finding the nearest minimum to X at temperature T.

Parameters:

• X (np.ndarray, optional) – Starting point for the minimization. If None, use the approximate zero-temperature minimum.

• T (float, optional) – Temperature at which to find the minimum. Default is 0.0.

Returns:

The location of the minimum found.

Return type:

np.ndarray

generateInvGroupElements()

Generate the group elements under which the potential is invariant. The group is

\[G = \Pi_i^N \mathbb{Z}_2\]

representing the discrete symmetries of the potential with scalar field dimension N.

Todo

test, refactor and clean up

Return type:

None.

get_mass_spectrum(X, T)

Evaluate bosonic and fermionic spectra at (X, T).

Return type:

SpectrumSnapshot

get_mass_spectrum_T0()

description

get_zero_temperature_mass_spectrum()

Return the T=0 mass spectrum in GeV for bosons and fermions.

Return type:

list[dict[str, object]]

gradV(X, T)

Find the gradient of the full effective potential.

This uses helper_functions.gradientFunction() to calculate the gradient using finite differences, with differences given by self.x_eps. Note that self.x_eps is only used directly the first time this function is called, so subsequently changing it will not have an effect.

Parameters:

• X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

• T (float or array_like) – The temperature. The shapes of X and T should be such that X.shape[:-1] and T.shape are broadcastable (that is, X[...,0]*T is a valid operation).

Returns:

The gradient of the effective potential at the given field values and temperatures.

Return type:

np.ndarray

init(*args, **dargs)

Subclasses should override this method (not __init__) to do all initialization. At a bare minimum, subclasses need to specify the number of dimensions in the potential with self.Ndim.

Return type:

None

makePrettyDictionaryPrint(derived_dict={})

Print the potential information in a nice way.

Parameters:

• input_dict (dict) – Input parameters of the potential

• derived_dict (dict) – Parameters derived from the input

Return type:

None.

massSqMatrix(X)

Calculate the tree-level mass square matrix of the scalar field.

This uses helper_functions.hessianFunction() to calculate the matrix using finite differences, with differences given by self.x_eps. Note that self.x_eps is only used directly the first time this function is called, so subsequently changing it will not have an effect.

The resulting matrix will have rank Ndim. This function may be useful for subclasses in finding the boson particle spectrum.

Parameters:

X (array_like) – Field value(s). Either a single point (with length Ndim), or an array of points.

Returns:

The tree-level mass square matrix at the given field values.

Return type:

np.ndarray

nucleationCriterion(S, T, high_phase, low_phase)

Approximate nucleation criterion

\[\Gamma(T_\mathrm{nuc})/H(T_\mathrm{nuc})^4 = 1\]

Return 0 if nuclation is fulfilled

Parameters:

• S (float) – Action at temperature T

• T (float) – Temperature.

• high_phase (PhaseInfo) – High temperature phase, start of tunneling

• low_phase (PhaseInfo) – Low temperature phase

Returns:

Criterion.

Return type:

float

radiationEnergyDensity(X, T, include_decoupled=True)

Return the energy density in radiation that is not field dependent.

Parameters:

• X (np.ndarray) – The scalar field values

• T (float or np.ndarray) – Temperature. X.shape[:-1] and T.shape must be broadcastable.

• include_decoupled (bool, optional) – If true, include the enery density of the decoupled radiation bath

Returns:

The energy density in pure radiation at temperature T, with shape np.broadcast_shapes(X.shape[:-1], np.shape(T)).

Return type:

float or np.ndarray

setConfigParameters()

Change the default config parameters for tracing, hydrodynamics, and GW computation.

This method should be overwritten by the subclass.

Return type:

None

set_modelparams(inputparam_dict)

Set the model parameters from the inputparam_dict dictionary. Print warnings if some parameters are not set and default values are used instead. Also check if the parameters are in the allowed ranges.

Return type:

dict

set_tracing_params()

Backward-compatible helper to resync cached tracing attributes.

Older model implementations still call this after tweaking the config.

Return type:

None

tachyonTest(X0)

Check if the boson mass matrix has any tachyonic modes at the zero-temperature minimum. This is used to check if the potential is stable at zero temperature.

Parameters:

X0 (array_like) – The zero-temperature minimum of the potential. This should be a single point (with length Ndim).

Raises:

TachyonError – If any of the boson masses are tachyonic.

Return type:

None

Tunneling pathfinding and bubble profiles

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

The basic strategy is an iterative process:

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

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

3. 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.

4. 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.

5. 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].

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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 minimum stepsizes passed to step(), rescaled by sum(|phi[0]-phi[-1]|) / (num_points * max(dV)), the first and last points of the path rather than the first two. minstep is the lower bound on the stepsize; step() takes no upper bound, and only ever divides the stepsize by step_decrease, while deformPath() multiplies it by step_increase after each step.

• minstep (float, optional) – Starting and minimum stepsizes passed to step(), rescaled by sum(|phi[0]-phi[-1]|) / (num_points * max(dV)), the first and last points of the path rather than the first two. minstep is the lower bound on the stepsize; step() takes no upper bound, and only ever divides the stepsize by step_decrease, while deformPath() multiplies it by step_increase after each 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 (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={})

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 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:

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

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

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

4. 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:

1. Fit a spline to the path given by path_pts.

2. Calculate the one-dimensional tunneling along this path.

3. Deform the path to satisfy the transverse equations of motion.

4. 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.

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).

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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 stems from the original 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)\]

is

\[\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. The shooting stops once the bracket xmax - xmin falls below xtol * min(max(|x|, |xmin|), 1), so xtol is a fraction of the x the bracket holds while that x is below one, and an absolute window on x where it is not.

• phitol (float, optional) – Fractional error tolerance in integration. It scales both tolerances the profile integration is held to: epsfrac directly, and epsabs as phitol times the bounce’s own field excursion, |phi(0) - phi_metaMin|. Through epsabs it also sets the radius, 3*epsabs, inside which integrateProfile() counts a trial profile as having reached phi_metaMin, so it is 3*phitol of the excursion.

• 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:

• phimeta (float) – The metastable minimum of the potential

• phi0 (float) – The field release point

• instance (The potential and the friction coefficient are read off the)

• self.V (as)

• the (and self.alpha; neither is an argument. self.alpha is the coefficient of)

• equation (solution to the)

• dimensions (which is the number of spacetime)

• one (minus)

• itself. (not the number of dimensions)

• analytic (The)

• equation

• 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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

transitionlistener.thermodynamics.Sfit(x)

Auxiliary suppression factor appearing in the low-temperature SM fits.

transitionlistener.thermodynamics.br(x)

Low-temperature bosonic energy-density kernel used in the tabulated SM fit.

transitionlistener.thermodynamics.bs(x)

Low-temperature bosonic entropy-density kernel used in the tabulated SM fit.

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)

Low-temperature fermionic energy-density kernel used in the tabulated SM fit.

transitionlistener.thermodynamics.fs(x)

Low-temperature fermionic entropy-density kernel used in the tabulated SM fit.

transitionlistener.thermodynamics.geff_rho_h(T)

High-temperature fit for the SM energy-density degrees of freedom.

The fit approximates \(g_{\mathrm{eff},\rho}^{\mathrm{SM}}(T)\) defined by

\[\rho_{\mathrm{SM}}(T) = \frac{\pi^2}{30}\, g_{\mathrm{eff},\rho}^{\mathrm{SM}}(T)\, T^4.\]

It uses the rational approximation of Saikawa and Shirai (arXiv:1803.01038) above the QCD crossover.

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

Low-temperature fit for \(g_{\mathrm{eff},\rho}^{\mathrm{SM}}\).

Below the QCD crossover the fit is written as a sum of hadronic and leptonic threshold functions and still satisfies

\[\rho_{\mathrm{SM}}(T) = \frac{\pi^2}{30}\, g_{\mathrm{eff},\rho}^{\mathrm{SM}}(T)\, T^4.\]

transitionlistener.thermodynamics.geff_s_h(T)

High-temperature fit for the SM entropy degrees of freedom.

The quantity is defined by

\[s_{\mathrm{SM}}(T) = \frac{2\pi^2}{45}\, g_{\mathrm{eff},s}^{\mathrm{SM}}(T)\, T^3.\]

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

Low-temperature fit for \(g_{\mathrm{eff},s}^{\mathrm{SM}}\).

The fit is defined through

\[s_{\mathrm{SM}}(T) = \frac{2\pi^2}{45}\, g_{\mathrm{eff},s}^{\mathrm{SM}}(T)\, T^3.\]

transitionlistener.thermodynamics.h_eff_radiation(e_geff_fn, p_geff_fn, T, CF)

Entropy degrees of freedom of a radiation bath given by its energy and pressure degrees of freedom.

The Standard Model has its own entropy table; for any other bath s = (e + p)/T gives h = (3 g_e + g_p)/4.

Return type:

float

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.

At exactly T = 0 a massless mode returns its full count, as e_geff does, since that is the limit of the coefficient; the pressure itself still vanishes, because every caller multiplies by T**4. A massive mode returns zero there.

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.potential_fields_geff(mSq_bosons, mSq_fermions, T, kind='e', mask=None)

Degrees of freedom of the fields of a potential, in the Landau gauge counting.

Every mode counts, the Goldstone modes included; the ghosts are subtracted by the caller, as in generic_potential.radiationEnergyDensity. Tachyonic modes count as massless, as they do in e_geffDS, on the grounds that the plasma gives them a thermal mass.

kind selects energy ("e"), pressure ("p") or entropy ("s") degrees of freedom; mask restricts the sum to a subset of the fields, as a pair of boolean arrays for bosons and fermions.

transitionlistener.thermodynamics.ratio(T)

Return the fitted ratio \(g_{\mathrm{eff},\rho}/g_{\mathrm{eff},s}\).

This auxiliary fit is combined with geff_rho_h() to reconstruct the entropy degrees of freedom according to

\[g_{\mathrm{eff},s}(T) = \frac{g_{\mathrm{eff},\rho}(T)} {g_{\mathrm{eff},\rho}(T)/g_{\mathrm{eff},s}(T)}.\]

This function implements the ratio in the denominator.

transitionlistener.thermodynamics.reheating_geff(pot, X_broken, T_DS, T_dec)

Energy and entropy degrees of freedom right after reheating, referred to the SM bath.

Three baths contribute: the fields of the potential (the transitioning sector, “DS”) in the broken phase at X_broken, reheated to T_DS; the coupled bath, reheated with them; and the decoupled bath, still at T_dec. Each enters with its temperature ratio to the bath that holds the Standard Model, g = sum g_i (T_i/T_SM)^4 and h = sum h_i (T_i/T_SM)^3 (arXiv:2109.06208, 2311.06346). Returns (g, h, T_SM).

The fields of the potential count in the Landau gauge counting, every mode including the Goldstone modes and the ghosts of the gauge bosons subtracted, as in radiationEnergyDensity. Fields flagged is_SM count there and are removed from the tabulated bath by sm_fields_in_potential_geff, so that each is counted once.

Return type:

tuple[float, float, float]

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.sm_bath(pot)

Radiation bath that holds the Standard Model: "coupled" or "decoupled".

pot.SM_bath decides if set; otherwise the bath whose energy degrees of freedom are the Standard Model table e_geffSM, and the coupled one if neither is.

Return type:

str

transitionlistener.thermodynamics.sm_fields_in_potential_geff(pot, T, kind='e')

Tabulated degrees of freedom of the Standard Model fields that the potential contains.

The tables e_geffSM, p_geffSM and s_geffSM describe the whole Standard Model. A model that puts Standard Model fields into its potential (flagged is_SM, e.g. W, Z, t and h in the 2HDM) counts those fields there, with their field- and temperature-dependent masses, so their tabulated contribution has to be removed once. It is evaluated at the masses the fields have in the zero-temperature vacuum of the model, where they are the Standard Model masses, and their ghosts are removed with them, so that the ghosts the potential subtracts are not counted twice.

transitionlistener.thermodynamics.sm_fields_in_potential_geff_uncached(pot, T, kind='e')

sm_fields_in_potential_geff without the tabulation, for one-off checks.

The tabulated version is built for the whole temperature range at once, which is wasted work when a caller needs the value at a handful of temperatures, as the validation of the radiation baths does.

Bubble wall velocity and hydrodynamics

This module contains routines to compute the hydrodynamics of the expanding bubbles.

Based on the code snippet provided in arxiv:2303.10171.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors of the wrapper:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

Authors of the hydrodynamics routines:

Wen-Yuan Ai <wenyuanai@sjtu.edu.cn> Benoit Laurent <blaurent@perimeterinstitute.ca> Jorinde van de Vis <jorinde.van.de.vis@cern.ch>

class transitionlistener.hydrodynamics.Hydrodynamics(pot, high_phase, low_phase, verbose=False)

Bases: object

Provide hydrodynamic solutions for expanding first-order phase transition bubbles.

calcWallVelocityLTE(Tn)

Calculate the wall velocity in local thermal equilibrium (LTE). This is done by solving the matching conditions across the bubble wall. It is based on the method described in arxiv:2303.10171.

Whether the species directly coupled to the scalar undergoing the phase transition and the rest of the heat bath behave as a single fluid or as two fluids is read from pot.config.gwConf.coupled_hydrodynamics. The bubble wall always does work on the species coupled to the transitioning scalar; the rest of the heat bath is only directly coupled to the wall when this flag is True. (When it is False, the two sectors can still be in thermal contact through indirect, slower processes; this switch only controls whether they are treated as a single hydrodynamic fluid in the matching conditions.)

Parameters:

Tn (float) – Temperature, typically at nucleation

Returns:

wall velocity in local thermal equilibrium.

Return type:

float

calc_cs(T, sym)

Calculate the speed of sound in the broken phase.

Parameters:

• T (float) – Temperature, typically at nucleation

• sym (bool) – Whether to use symmetric or broken phase

Returns:

speed of sound in the broken phase.

Return type:

float

detonation(alN, cb2, psiN)

Return the detonation wall velocity if a solution exists.

Parameters:

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Speed of sound squared in the broken phase.

• psiN (float) – Ratio of enthalpies at nucleation.

Returns:

The detonation wall velocity if a solution exists, otherwise 0.

Return type:

float

dfdv(v, X, cs2)

Compute the derivatives for the hydrodynamic equations.

Parameters:

• v (float) – Velocity of the fluid.

• X (np.ndarray) – Array containing the variables [xi, w].

• cs2 (float) – Speed of sound squared.

Returns:

The derivatives [dXidv, dwdv].

Return type:

list[float]

eqWall(al, alN, vm, nu, mu, psiN, solution=-1)

Parameters:

• al (float) – Strength of the phase transition at the wall.

• alN (float) – Strength of the phase transition at nucleation.

• vm (float) – Velocity of the fluid at the wall.

• nu (float) – Parameter depending on the speed of sound in the broken phase.

• mu (float) – Parameter depending on the speed of sound in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

• solution (int) – Choose the branch of the solution, either -1 or +1.

Returns:

The value of the matching condition equation.

Return type:

float

find_kappa(alN, cb2, cs2, psiN, vw=None)

Compute the hydrodynamic efficiency factor for given plasma parameters.

Parameters:

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Speed of sound squared in the broken phase.

• cs2 (float) – Speed of sound squared in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

• vw (float, optional) – Wall velocity. If not provided, it will be computed.

Returns:

The hydrodynamic efficiency factor.

Return type:

float

find_vJ(alN, cb2)

Calculate the Jouguet velocity, i.e. the smallest wall velocity a physically consistent detonation solution is allowed to have from the PT strength α and sound speed.

Parameters:

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Sound speed squared in the broken phase.

Returns:

The Jouguet velocity.

Return type:

float

find_vw(alN, cb2, cs2, psiN)

Solve for the wall velocity consistent with matching conditions.

Parameters:

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Speed of sound squared in the broken phase.

• cs2 (float) – Speed of sound squared in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

Returns:

The wall velocity consistent with matching conditions.

Return type:

float

get_vp(vm, al, cb2, branch=-1)

Find the veloity outside the bubble using the matching conditions.

Parameters:

• vm (float) – The plasma velocity in the wall frame inside the bubble.

• al (float) – Strength of the phase transition at nucleation.

• cb2 (float) – The speed of sound squared in the broken phase.

• branch (int) – Choose the branch of the solution, either -1 or +1.

Returns:

The plasma velocity in the wall frame outside the bubble.

Return type:

float

integrate_plasma(v0, vw, w0, c2, shock_wave=True)

Integrate the hydrodynamic equations for the plasma profile.

Parameters:

• v0 (float) – Initial velocity of the fluid.

• vw (float) – Velocity of the fluid at the wall.

• w0 (float) – Initial value of w.

• c2 (float) – Speed of sound squared.

• shock_wave (bool) – Whether to include shock wave effects.

Returns:

The result of the integration containing the plasma profile.

Return type:

OdeResult

max_al(cb2, cs2, psiN, upper_limit=1)

Return the maximal nucleation-strength compatible with subsonic solutions.

Parameters:

• cb2 (float) – Speed of sound squared in the broken phase.

• cs2 (float) – Speed of sound squared in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

• upper_limit (float) – Upper limit for the search of maximal alpha.

Returns:

The maximal nucleation-strength compatible with subsonic solutions.

Return type:

float

shooting(vw, alN, cb2, cs2, psiN)

Shooting method to find the wall velocity consistent with matching conditions.

Parameters:

• vw (float) – Velocity of the fluid at the wall.

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Speed of sound squared in the broken phase.

• cs2 (float) – Speed of sound squared in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

Returns:

The value of the shooting function.

Return type:

float

solve_alpha(vw, alN, cb2, cs2, psiN)

Find the strength of the phase transition at the wall.

Parameters:

• vw (float) – Velocity of the fluid at the wall.

• alN (float) – Strength of the phase transition at nucleation.

• cb2 (float) – Speed of sound squared in the broken phase.

• cs2 (float) – Speed of sound squared in the symmetric phase.

• psiN (float) – Ratio of enthalpies at nucleation.

Returns:

The strength of the phase transition at the wall.

Return type:

float

sound_speed_is_step_dependent(T, sym)

Whether the sound speed at T changes when the derivative step is changed.

A value can be round-off and still be a speed, so no test on the value itself can find it. Under extreme supercooling the thermal part of the potential sits far below the vacuum energy and the finite differences lose their significant digits; what comes back is then a number that moves when the step moves. Measured on the conformal dark U(1), at a temperature where the thermal part is 2.8e-16 of the vacuum energy, c_s comes out as 0.82 while c_s^2 ranges over -0.001 to 0.89 across steps from dT/T = 1e-3 to 2e-1: perfectly subluminal, and meaningless.

Returns (noisy, relative_change), the change being the larger of the two the step variation produces.

A value that is refused at one step and not at another is noisy: it has stopped being a speed somewhere inside the step range, which no single step can show. A value that is refused at every step is not: it is not a speed, but it does not depend on the step, and the refusal already reports what is wrong with it. Refused values are compared like any others, so one that is refused everywhere and also moves is noisy too. A value that cannot be computed at the base step is not called noisy; it is already reported as not-a-number.

Return type:

tuple[bool, float]

w_from_alpha(al, alN, nu, mu)

Compute the enthalpy from alpha

Parameters:

• al (float) – Strength of the phase transition at the wall.

• alN (float) – Strength of the phase transition at nucleation.

• nu (float) – Parameter depending on the speed of sound in the broken phase.

• mu (float) – Parameter depending on the speed of sound in the symmetric phase.

Returns:

The enthalpy in the wall frame.

Return type:

float

transitionlistener.hydrodynamics.SOUND_SPEED_JUMP_TOLERANCE = 0.05

Relative change of c_s under that step change above which the value is called noisy.

transitionlistener.hydrodynamics.SOUND_SPEED_STEP_RATIO = 10.0

Factor by which the derivative step is varied to test a sound speed for step dependence.

transitionlistener.hydrodynamics.calc_kappas(alphaN, alpha_inf, alpha_eq, vw, cs, Rsep, R0, config, alpha_wall=None)

Calculate the kappa parameters kappa_phi, kappa_sw and kappa_turb. These parameters quantify the amount of energy that is available for gravitational wave production in the broken phase due to bubble collisions, sound waves and turbulence.

Parameters:

• alphaN (float) – The strength of the phase transition that drives the sound waves (alpha_hyd of calcAlphas).

• alpha_inf (float) – The critical strength of the phase transition at which bubbles would run away if there was only leading order friction.

• alpha_eq (float) – The critical strength of the phase transition at which the next-to-leading order friction is compensated by a high bubble wall velocity.

• vw (float) – The bubble wall velocity.

• cs (float) – The speed of sound in the broken phase.

• Rsep (float) – The mean bubble separation at the time of percolation.

• R0 (float) – The critical bubble radius at which the phase transition starts at nucleation.

• config (object) – The configuration object containing for instance the epsilon parameter determining the importance of turbulence in the broken phase.

• alpha_wall (float, optional) – The strength that drives the bubble wall, normalised to the transitioning sector only (alpha_hyd_wall of calcAlphas). It enters gamma_eq and the bubble-collision efficiency. Defaults to alphaN.

Return type:

tuple

Returns:

• kappa_bw (float) – The kappa parameter for bubble wall collisions.

• kappa_sw (float) – The kappa parameter for sound waves.

• kappa_turb (float) – The kappa parameter for turbulence.

transitionlistener.hydrodynamics.kappa_sw(alpha, vw, cs)

Approximate the sound-wave efficiency factor using fit formulas from 1004.4187 by Jose R. Espinosa, Thomas Konstandin, Jose M. No & Geraldine Servant

Parameters:

• alpha (float) – The strength of the phase transition at nucleation.

• vw (float) – The bubble wall velocity.

• cs (float) – The speed of sound in the broken phase.

Returns:

The sound-wave efficiency factor.

Return type:

float

transitionlistener.hydrodynamics.resolve_configured_sound_speed(setting)

Turn a non-"compute" GWconfig.sound_speed setting into a speed.

"1/3" names c_s^2 = 1/3, the massless plasma, and gives 1/sqrt(3). Anything else is read as c_s itself. The two solvers historically accepted different halves of this, the adaptive one only the label and the fixed-step one only a number, so the value the sound-speed refusal in errors.SuperluminalSoundSpeedError recommends was rejected by one of them. Both go through here now.

The result is strictly between zero and one: the spectrum divides by v_wall - c_s, so a configured value of exactly one with a runaway wall is a division by zero, and the guard on the computed value calls one not a speed.

Return type:

float

Gravitational wave spectra

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

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.gwfopt.FOPTspectrum(gwparams_dict, astroparams_dict={'A': 0.0, 'gamma': 0.0}, 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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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

Minimal PTArcade-style configuration container used by the PTA likelihood wrappers.

class transitionlistener.observability.PTAModel(spectrum)

Bases: object

Adapter exposing a TransitionListener spectrum in the format expected by PTArcade.

class transitionlistener.observability.PTAModel_SMBHB(spectrum)

Bases: object

PTArcade adapter including the nuisance parameters for an SMBHB foreground.

Utilities and helpers

A collection of (mostly) stand alone helper functions.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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.

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].

[1]

W. H. Press, et. al. “Numerical Recipes in C: The Art of Scientific Computing. Second Edition.” Cambridge, 1992.

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!

transitionlistener.helper_functions.temperatureDerivativeStep(pot, T, X=None, include_decoupled=False, two_point=False)

Finite-difference step for temperature derivatives of the potential.

The stencils in generic_potential.dVdT() and generic_potential.d2VdT2() difference the full effective potential, which in the broken phase can carry a large temperature-independent vacuum piece. Cancelling that offset leaves a round-off error of order \(\epsilon |V| / \Delta T^2\) in the second derivative, while the five-point stencils truncate at order \(\Delta T^4\). Balancing the two gives

\[\frac{\Delta T}{T} \simeq \left(\epsilon \frac{|V|}{\rho_{\rm rad}}\right)^{1/6} \,,\]

for the five-point stencils. A two-point central difference of a first derivative balances a round-off of order \(\epsilon |V| / \Delta T\) against a truncation of order \(\Delta T^2\), which gives the cube root of the same ratio instead; pass two_point=True for those. The cube root is much smaller than the sixth root whenever the ratio is large, so using the five-point step for a two-point derivative costs truncation error: 2e-4 on the potential difference of the conformal benchmark.

where the radiation energy density stands in for the thermal scale that sets the size of the temperature derivatives. Both are taken for the sector the derivative itself uses, selected by include_decoupled. A radiation-dominated phase has \(V = -p = -\rho/3\), so the ratio cannot fall much below one third and the step stays above \((\epsilon/3)^{1/6} \simeq 2\times10^{-3}\); the lower clip is a guard, not a working bound. The two regimes this has to serve differ by orders of magnitude: for the conformal dark U(1)’ benchmark \(|V| \sim 3\times10^8\) against a thermal scale of order one, so the step has to be about a per cent of T or the sound speed in the broken phase picks up a 0.1 % scatter and a 0.3 % bias; for the abelian dark Higgs the vacuum offset is comparable to the thermal scale, no cancellation occurs, and a per-cent step already costs 0.4 % of truncation error in alpha. The rule above lands on the accurate plateau in both, and is clipped to \([10^{-4}, 3\times10^{-2}]\).

Without X the field-independent fallback of 1e-2 is used.

Parameters:

• pot (generic_potential) – Effective potential; used for Vtot, radiationEnergyDensity and the T_eps fallback.

• T (float) – Temperature at which the derivative is taken.

• X (np.ndarray, optional) – Field value at which the derivative is taken. The step depends on it, because the vacuum offset does.

• include_decoupled (bool, optional) – Whether the decoupled radiation bath counts towards the offset and the thermal scale. Pass what the derivative this step serves uses.

• two_point (bool, optional) – True for a two-point central difference of a first derivative, False (the default) for the five-point stencils of dVdT and d2VdT2.

Returns:

Temperature step, capped at 0.25 * T so the stencil stays at positive temperature.

Return type:

float

transitionlistener.helper_functions.thermalDerivativeStep(pot, T, X=None)

Finite-difference step for temperature derivatives of the thermal potential.

temperatureDerivativeStep() cannot serve generic_potential.dV_thermal_dT() and generic_potential.d2V_thermal_dT2(). It sizes the step from \(|V_{\rm tot}|\), whose vacuum offset is exactly what those two do not carry, and its sixth-root balance is derived for five-point stencils where they are two- and three-point ones. Applied to them it saturates its own \(3\times10^{-2}\) ceiling below \(T/v = 10^{-3}\), which costs accuracy in the fourth digit of the sound speed.

What binds for the ratio \(c_s^2 = \partial_T V_{\rm th}/(T\,\partial_T^2 V_{\rm th})\) is the round-off of the second difference against the truncation of the first:

\[\frac{4\epsilon |V_{\rm th}|}{\Delta T^2\, |\partial_T^2 V_{\rm th}|} \;\simeq\; \frac{\Delta T^2 |\partial_T^3 V_{\rm th}|}{6\, |\partial_T V_{\rm th}|} \,.\]

The pairing is not the obvious one. The second difference is the noisier of the two, by a factor \(1/\Delta T\), so it sets the round-off; the fourth derivative that would set its truncation nearly vanishes wherever the daisy term dominates, because there \(V_{\rm th} \propto T^3\) and \(n(n-1)(n-2)(n-3) = 0\) at \(n = 3\). The third derivative does not vanish, so the first difference sets the truncation.

For \(V_{\rm th} \propto T^n\) this gives

\[\frac{\Delta T}{T} \simeq \left(\frac{24\,\epsilon}{n(n-1)^2(n-2)}\right)^{1/4} \,,\]

and the magnitude \(|V_{\rm th}|\) cancels out of it, because round-off and truncation both scale with it. So the step is a pure number, and sizing it on whichever contribution dominates the thermal part is the derivation of that number rather than a reason for it to vary: radiation, \(n = 4\), gives \((\epsilon/3)^{1/4} = 9.3\times10^{-5}\), and a daisy-dominated \(n = 3\) gives \((2\epsilon)^{1/4} = 1.45\times10^{-4}\). The two differ by 50 %, the optimum is flat, and the radiation value is used for both.

Verified on the conformal dark U(1) at g = 0.455, 0.7 and 0.95, at internal temperatures from \(10^{-1}\) to \(10^{-9}\) of the scale: c_s at this step agrees with the plateau measured over \(\Delta T/T \in [3\times10^{-5}, 10^{-3}]\) to \(4\times10^{-8}\) or better everywhere, and at \(T/v = 10^{-9}\) returns 0.70710672 against the analytic daisy limit \(1/\sqrt{2} = 0.70710678\). Round-off takes over below \(\Delta T/T \sim 10^{-5}\) and truncation above \(3\times10^{-3}\).

Parameters:

• pot (generic_potential) – Effective potential; used only for the T_eps fallback at zero temperature.

• T (float) – Temperature at which the derivative is taken.

• X (np.ndarray, optional) – Field value. Accepted for symmetry with temperatureDerivativeStep() and unused: that the step does not depend on it is the result derived above.

Returns:

Temperature step, capped at 0.25 * T so the stencil stays at positive temperature.

Return type:

float

Configuration handling

This module contains the configurations.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.config.Configuration

Bases: object

Container holding one independent configuration object per subsystem.

class transitionlistener.config.GWConf

Bases: object

Settings for calculating the gravitational-wave signal.

bw_collisions = 'off'

check_if_T0_global_min = False

coupled_hydrodynamics = True

dilution = False

epsilon_turbulence = 0.1

equilibrium_DS = True

sound_speed = 'compute'

turbulence = 'off'

use_mean_bubble_separation = True

wall_velocity = 'LTE'

class transitionlistener.config.PercolationConf

Bases: object

Settings for the percolation solver.

acc_rh = 0.01

acc_tfinal = 0.01

acc_tperc = 0.01

algorithm_mode = 'adaptive_step_size'

betaH_S3_fallback_rel_step = 0.002

betaH_S3_fit_check_points = 7

betaH_S3_fit_max_rel_span = 0.02

betaH_S3_fit_min_per_side = 2

betaH_S3_fit_points = 11

betaH_S3_fit_rel_tol = 0.03

betaH_S3_fit_rescue = True

entropy_definition = 'dof_table'

entropy_scheme_diagnostic = True

entropy_scheme_warn_threshold = 0.04

f_final = 0.99

f_perc = 0.28957

f_start = 0.001

integral_method = 'ode'

jitter_GH4_threshold = 1.0

jitter_rescue = True

large_delta_p_refine_threshold = 0.1

large_delta_p_success_threshold = 0.2

max_action_temperatures = 100

max_boundary_ratio = 0.45

max_log10_rate_step = 12.0

maxit = 20

n_action = 30

n_action_increment = 5

n_action_max = 60

n_action_min = 15

n_jitter_save = 20

rel_increment = 0.1

time_temperature_mode = 'sound_speed'

weak_threshold = 0.0001

weight = 0.6666666666666666

class transitionlistener.config.TracingConf

Bases: object

Phase-tracing and tunneling computation parameters.

Tmax_factor = 2.5

Z2_cutof_factor = -5

approx_strength_threshold = 0.0001

diftol = 1

do_high_T_phase_check = True

do_tachyon_test = True

gen_mirror_phases = False

internal_scale = 1000

nucleation_Ttol = 1e-08

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}

Arguments forwarded to the phase-tracing routines.

tracing_derivative_order = 4

tracing_field_accuracy = 0.001

tracing_temp_accuracy = 0.001

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': 1e-06, 'rscale': None}}

Arguments forwarded to the bounce-action / tunneling routines.

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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.SOUND_SPEED_JUMP_TOLERANCE = 0.05

Relative change of c_s under a factor-ten step change above which it is called noisy.

Here rather than in hydrodynamics because errors.SuperluminalSoundSpeedError phrases its message around the same threshold, and a message that decided “stable” by one number while the flag decided “noisy” by another would be worse than no message.

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.h_eff_today = 3.9309363

1803.01038).

Type:

Entropy degrees of freedom today (Saikawa and Shirai, arXiv

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

exception transitionlistener.errors.ActionRateJitterError(message='Detected a large non-smooth jitter in Gamma/H^4 across the active percolation band. This indicates an instability of the bounce computation or a wrong tunnelling branch.')

Bases: Exception

Raised when the sampled bounce action implies a non-smooth nucleation rate.

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.', *, Pint_max=None, Tperc=None, Tlow=None, f_final=None)

Bases: Exception

Raised when the eternal-inflation criterion is fulfilled.

calcTf also raises it when the true vacuum fraction never reaches f_final, which is a different statement and the far more common one on a strongly supercooled line: the transition percolated and then stalled. Measured on the 2HDM marginal line, the 29-point zoom at the no-percolation edge from lambda3 = 5.8193 to 5.8222, all 14 such points reached Pint between 0.3215 and 0.7640, every one above f_perc = 0.28957, so each had a well-defined percolation temperature at the moment it was refused. Tperc, Pint_max, Tlow and f_final carry those numbers, because the alternative is running the point again to recover what the solver already had. Tperc and Tlow are in the solver’s internal temperature units, as the raising code holds them; multiply by the model’s conversionFactor for GeV. All four default to None, so a bare raise EternalInflationError() keeps working and a consumer must treat None as “not reported” rather than as a value.

A transition that stalls at Pint well below one leaves a mixture of phases, so Tperc is meaningful there while Treh and the spectrum are not ordinary predictions.

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.NoViablePhasePairError(message='No pair of phases below the current one was a viable tunnelling candidate, so no nucleation calculation was attempted.')

Bases: Exception

Raised when no phase pair below the current phase was ever a tunnelling candidate.

Every claim here is about one step of the chain, the phase the walk had reached, and about the candidates offered below it. The transitions already found are counted in the message, because this error discards them, and nothing here reassesses them or says how they were obtained. In particular they need not have been solved: a second-order step records a transition with no nucleation solve, and in the adaptive backend seedlessFirstOrderCandidate accepts a pair without computing a nucleation temperature at all, leaving that to percolation.

Distinct from TooMuchSupercoolingError, which at this same point means a candidate did reach the nucleation solver and the solve did not succeed, and which is also raised from a later stage, where percolation found no temperature at which the true vacuum fraction reaches f_perc. The test is reaching the solver, not what the solver concluded: a failed solve may mean the transition is genuinely too supercooled, or that the solve failed numerically, and the raise does not tell those two apart. This class is the narrower statement, that no candidate below this phase reached the solver at all, so nothing about the rate at this step was computed either way.

Two reasons a child never becomes a candidate at all, which is what this error reports: it duplicates a child already offered, so getUniqueTunnelingPhases drops it, or the two phases do not overlap in temperature. The counts in the message keep those apart from a pair that was evaluated and then refused, which in the adaptive backend happens when the starting phase is already the deeper minimum at the cold end of the overlap, when it does not exist to a higher temperature than the target, or when the potential difference could not be evaluated there. On the fixed-step path an evaluated pair can instead fail the nucleation solve, counted separately again. Run with verbose=True for the individual decisions.

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.SuperluminalSoundSpeedError(c_s, T, message=None, phase='broken', step_change=None, daisy_ratio=None, daisy_outside=None, source='sound_speed')

Bases: Exception

The effective potential gave a sound speed of one or more.

c_s^2 = (dV/dT)/(T d2V/dT2) sets the speed at which the bubbles grow, max(v_wall, c_s), the efficiency factors and the spectrum. A value of one or more is not a speed, so nothing downstream of it has a meaning: for a runaway wall it replaces the wall velocity and multiplies (beta/H)_RH by c_s, and the spectrum divides by v_wall - c_s. Rather than substitute a number the model did not give, the point is refused and the computation that produced it is reported.

Which phase it came from is part of the report. Both are refused: the symmetric-phase value is what the hydrodynamic matching across the wall is solved with, so a value of one or more there is no more usable than in the broken phase.

step_change, daisy_ratio and daisy_outside, where the caller has them, say which of the two known mechanisms produced it. Neither is a property of the physics.

A large step_change means the finite differences have lost their significant digits and the number is round-off.

daisy_ratio is a size and daisy_outside is the verdict; the size alone does not imply the verdict. Where the Arnold-Espinosa resummation is used outside its range of validity, m << T, the resummed term falls as a power of the temperature where the mode it stands for should be Boltzmann suppressed, it comes to dominate the thermal potential, and c_s^2 drifts towards the 1/2 of a T^3 potential rather than the 1/3 of radiation. But a daisy term larger than the radiation is not by itself that failure: at high temperature it legitimately exceeds the radiation while every mode is still lighter than the temperature. daisy_outside is generic_potential.daisy_outside_validity(), which requires both, and it is what the message draws its conclusion from.

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 with CLI error code 8 from either of two stages, and the message says which.

At the transition-chain walk it means a candidate below the current phase did reach the nucleation solver and the solve did not succeed. That test is reaching the solver, not what the solver concluded: the transition may be genuinely too supercooled, or the solve may have failed numerically, and the raise does not tell those two apart. The claim is about the one step the walk had reached; steps already completed are not implicated.

At percolation it means the true vacuum fraction never reaches f_perc, so no percolation temperature exists on the temperature range that was searched.

Distinct from NoViablePhasePairError, code 19, which comes only from the first stage and means no candidate was ever offered to the solver, so nothing about the rate was measured at that step.

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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

Bases: object

Evaluated bosonic spectrum together with particle metadata.

as_tuple()

Return the legacy tuple representation used by older callers.

Return type:

Tuple[ndarray, ...]

c: ndarray

dof: ndarray

gauge_coupling: ndarray

is_bsm: ndarray

is_physical: ndarray

property latex_labels: List[str]

LaTeX labels for each bosonic degree of freedom.

masses_sq: ndarray

particles: Sequence[BaseParticle]

property text_labels: List[str]

Plain-text labels for each bosonic degree of freedom.

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

Evaluated fermionic spectrum together with particle metadata.

as_tuple()

Return the legacy tuple representation used by older callers.

Return type:

Tuple[ndarray, ...]

dof: ndarray

is_bsm: ndarray

property latex_labels: List[str]

LaTeX labels for each fermionic degree of freedom.

masses_sq: ndarray

particles: Sequence[BaseParticle]

property text_labels: List[str]

Plain-text labels for each fermionic degree of freedom.

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

Group of particles sharing one mass function and, optionally, one thermal correction.

evaluate(X, T)

Evaluate the block mass function and align its trailing axis with particles.

Return type:

ndarray

evaluate_thermal(X, T)

Evaluate hard thermal masses or c_i T^2-style prefactors for the block.

When no explicit thermal-mass callback is provided, the function falls back to per-particle prefactors and returns :rtype: Optional[ndarray]

\[\Pi_i(\phi, T) = c_i(\phi)\, T^2.\]

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

Bosonic/fermionic statistic shared by every particle in the block.

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

Bases: object

Container describing the particle content and mass functions of a model.

The class keeps the legacy CosmoTransitions-style tuple interface used throughout TransitionListener. It stores particle metadata such as degrees of freedom and renormalisation constants alongside callables returning the field- and temperature-dependent mass eigenvalues.

boson_labels(type)

Return boson names either in plain text or in LaTeX form.

bosons_massSq(X, T)

Return the bosonic masses entering the one-loop effective potential.

The returned tuple is interpreted as (m_i^2, n_i, c_i, physical_i), where \(m_i^2(\phi, T)\) are the bosonic mass eigenvalues, \(n_i\) their degrees of freedom, and \(c_i\) the renormalisation constants used in

\[V_1^{B}(\phi, T=0) = \sum_i \frac{n_i\, m_i^4(\phi, 0)}{64\pi^2} \left[\log\!\left(\frac{m_i^2(\phi, 0)}{\mu^2}\right) - c_i\right].\]

Parameters:

• X (ndarray) – Field configuration \(\phi\).

• T (float) – Temperature in the internal TransitionListener units.

Returns:

(masses_sq, dof, c_constants, is_physical).

Return type:

tuple

calc_N_gauge_bosons(gaugeBosons)

Infer the number of vector bosons from the total bosonic degrees of freedom.

fermion_labels(type)

Return fermion names either in plain text or in LaTeX form.

fermion_massSq(X)

Return the fermionic masses entering the one-loop effective potential.

The returned tuple is interpreted as (m_f^2, n_f) and is used in

\[V_1^{F}(\phi) = -\sum_f \frac{n_f\, m_f^4(\phi)}{64\pi^2} \left[\log\!\left(\frac{m_f^2(\phi)}{\mu^2}\right) - \tfrac{3}{2}\right].\]

Parameters:

X (ndarray) – Field configuration \(\phi\).

Returns:

(masses_sq, dof).

Return type:

tuple

get_gauge_coupling()

Return the per-boson gauge couplings associated with the stored spectrum.

set_bmass_fn(bmass_fn)

Normalise the bosonic mass callback and supply a massless default when absent.

set_fmass_fn(fmass_fn)

Normalise the fermionic mass callback and supply a massless default when absent.

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

Simultaneous bosonic and fermionic spectrum evaluation at a given state.

bosons: BosonSector

fermions: FermionSector

Plotting utilities

Helpers to visualise grid scans of TransitionListener observables.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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

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}$'), figsize=None)

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.

Visualization utilities for TransitionListener potentials, spectra and scans.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

class transitionlistener.plots.TLPlots(inputparam_dict, modelfile, potential_name, output_folder_name='', plot_description='', potential=None, phases=None, transitions=None, transition_observables=None, verbose=False)

Bases: object

Collection of high-level plotting routines for a single potential instance.

plotAction(Tmin_GeV, Tmax_GeV, phase_indices, n=100, show=False, save=True, savetxt=True)

Visualise the Euclidean action and nucleation criterion across temperatures.

Parameters:

• Tmin_GeV (float) – Minimum temperature in GeV.

• Tmax_GeV (float) – Maximum temperature in GeV.

• phase_indices (list) – List of phase indices to consider.

• n (int, optional) – Number of points to sample in the temperature range.

• show (bool, optional) – Whether to show the plot.

• save (bool, optional) – Whether to save the plot.

plotDOFs(Tmin_GeV=nan, Tmax_GeV=nan)

Plot the effective degrees of freedom in the SM and dark sector.

Parameters:

• Tmin_GeV (float, optional) – Minimum temperature in GeV for the x-axis.

• Tmax_GeV (float, optional) – Maximum temperature in GeV for the x-axis.

plotEnergyDensity(Tmin_GeV=nan, Tmax_GeV=nan, show_plot=False)

Plot the energy density evolution for each phase.

Parameters:

• Tmin_GeV (float, optional) – Minimum temperature in GeV for the x-axis.

• Tmax_GeV (float, optional) – Maximum temperature in GeV for the x-axis.

plotPercolation(show=False, Tmin_GeV=nan, Tmax_GeV=nan, n_action=None)

Plot the true-vacuum fraction to illustrate percolation.

plotPhases(Tmin_GeV=nan, Tmax_GeV=nan, include_transitions=True, save=True, show=False, plot_squaresum=True)

Plot the traced phase trajectories and optionally their transitions.

plot_squaresum only matters in multi-field models; when False the panel for sqrt(sum_i phi_i^2) is omitted, giving a 2-panel figure that matches the 1-field default layout.

plotPotential(plot_T_GeV, phi_ranges_GeV, n=100, show=False, save=True, log=False)

Plot the potential energy landscape at a fixed temperature.

Parameters:

• plot_T_GeV (float) – Temperature in GeV at which to plot the potential.

• phi_ranges_GeV (list) – List defining the plotting ranges for each field dimension in GeV.

• n (int, optional) – Number of points to use for the plot.

• show (bool, optional) – Whether to show the plot.

• save (bool, optional) – Whether to save the plot.

• log (bool, optional) – Whether to use a logarithmic color scale (only for 2D plots).

plotProfile()

Plot bounce profiles along the tunnelling path for all FOPTs.

plotProfileV(phi1, phi2)

Show the potential along the tunnelling path between two field values.

Parameters:

• phi1 (int) – Index of the first field dimension to plot.

• phi2 (int) – Index of the second field dimension to plot.

transitionlistener.plots.add_NeffHatch(ax, Neffcolor=(0.0, 0.41568627450980394, 0.5215686274509804), h2OmegaNeff=2.48e-07)

Overlay a hatched region indicating the \(\Delta N_\mathrm{eff}\) bound.

Parameters:

• ax (matplotlib.axes.Axes) – The axes to add the hatch to.

• Neffcolor (str, optional) – The color of the hatch.

• h2OmegaNeff (float, optional) – The upper bound on \(h^2 \Omega_\mathrm{GW}\) from \(\Delta N_\mathrm{eff}\). Default is 2.48e-7.

transitionlistener.plots.add_violins(ax, violincolor=(0.6, 0.0, 0.0), nfreq=14)

Add stylistic violin markers to highlight PTA frequency bins.

Parameters:

• ax (plt.Axes) – The axes to add the violins to.

• violincolor (str, optional) – The color of the violins.

• nfreq (int, optional) – Number of frequency bins for the violins. Default is 14.

transitionlistener.plots.plot1d(pot, x1, x2, ax=None, T=0, treelevel=False, subtract=True, n=500, **plotParams)

Plot the 1D projection of the potential between two field values.

Parameters:

• x1 (float) – The starting field value.

• x2 (float) – The ending field value.

• T (float, optional) – The temperature.

• treelevel (bool, optional) – Whether to plot the tree-level potential or the full one-loop potential including thermal corrections.

• subtract (bool, optional) – Whether to subtract the potential at zero field value.

• n (int, optional) – Number of points to evaluate.

• plotParams – Any extra parameters to be passed to plt.plot().

transitionlistener.plots.plot2d(pot, box, ax=None, T=0, treelevel=False, offset=0, xaxis=0, yaxis=1, n=50, clevs=200, cfrac=0.8, log=False, **contourParams)

Makes a countour plot of the potential.

Parameters:

• box (tuple) – The bounding box for the plot, (xlow, xhigh, ylow, yhigh).

• T (float, optional) – The temperature

• offset (array_like) – A constant to add to all coordinates. Especially helpful if Ndim > 2.

• xaxis (int, optional) – The integers of the axes that we want to plot.

• yaxis (int, optional) – The integers of the axes that we want to plot.

• n (int) – Number of points evaluated in each direction.

• clevs (int) – Number of contour levels to draw.

• cfrac (float) – The lowest contour is always at min(V), while the highest is at min(V) + cfrac*(max(V)-min(V)). If cfrac < 1, only part of the plot will be covered. Useful when the minima are more important to resolve than the maximum.

• log (bool, optional) – Log scale of the colorbar.

• contourParams – Any extra parameters to be passed to plt.contour().

transitionlistener.plots.plotGWSpectrum(gwparams_dict, showplot=False, saveplot=True, foldername='', filename='', fig=None, ax=None, legendfontsize=8)

Build the spectrum from parameters and plot it for the core detectors.

Parameters:

• gwparams_dict (dict) – Dictionary containing the parameters for the GW spectrum.

• showplot (bool, optional) – Whether to display the plot.

• foldername (str, optional) – Folder to save the plot if showplot is False.

• filename (str, optional) – Filename to save the plot if showplot is False.

transitionlistener.plots.plotProfile2(transitions, conversionFactor)

Standalone function to plot the bubble profile.

Parameters:

• transitions (list[TransitionInfo]) – List of the transition objects

• conversionFactor (float) – Conversion factor to go from internal units to GeV

Return type:

None.

transitionlistener.plots.plotSensitivities(gw, showplot=False, call_from_spectrum=False, nfreq=5, fig=None, ax=None)

Plot ground- and space-based detector sensitivities alongside the spectrum.

Parameters:

• gw (GWSpectrum) – The GWSpectrum object containing the sensitivity data.

• showplot (bool, optional) – Whether to display the plot.

• call_from_spectrum (bool, optional) – Whether the function is called from within a spectrum plot. If True, the function returns the figure and axis objects instead of showing or saving the plot.

• nfreq (int, optional) – Number of frequency bins for the PTA violins.

transitionlistener.plots.plotSensitivitiesPTA(gw, showplot=False, call_from_spectrum=False, nfreq=5)

Plot PTA sensitivity curves alongside the spectrum.

Parameters:

• gw (GWSpectrum) – The GWSpectrum object containing the sensitivity data.

• showplot (bool, optional) – Whether to display the plot.

• call_from_spectrum (bool, optional) – Whether the function is called from within a spectrum plot. If True, the function returns the figure and axis objects instead of showing or saving the plot.

• nfreq (int, optional) – Number of frequency bins for the PTA violins.

transitionlistener.plots.plotSpectrum(gw, showplot=True)

Plot the total spectrum and its components together with sensitivities.

Parameters:

• gw (GWSpectrum) – The GWSpectrum object containing the spectrum data.

• showplot (bool, optional) – Whether to display the plot.

transitionlistener.plots.plotSpectrum2PTA(gwparams_dict, showplot=True, foldername='', filename='', title='')

Build the spectrum and plot it together with PTA sensitivities.

Matplotlib defaults and helper utilities for rendering TransitionListener plots.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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.

transitionlistener.plot_settings.save_figure(fig, path)

Save fig to path without ever leaving a truncated file behind.

The PDF backend streams objects to disk while drawing, so an exception during savefig leaves a PDF without xref table that no reader opens. Writing to a temporary file in the same directory and renaming it only after a successful save keeps either the complete new file or nothing. A path without extension gets the default format and its extension, as savefig does.

Return type:

None

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.

Part of TransitionListener v2.0 Documentation: https://tasillo.de/TransitionListener/

Authors:

Jonas Matuszak <jonas.matuszak@kit.edu> Carlo Tasillo <carlo.tasillo@ific.uv.es>

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]

Installation checks

Entry point for tl --check.

All check logic lives in tests/check_installation.py in the repository. For pip installs, hatchling bundles that file as transitionlistener/check_installation.py so it is always reachable.

transitionlistener.interface.check.run_checks()

Locate and run the packaged installation checks.

The helper first prefers the repository-local tests/check_installation.py file and falls back to the copy bundled into wheel installs.

Return type:

int