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

tck

Spline knots and coefficients, used in interpolate.splev.

Type:

tuple

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.

valAt(T, deriv=0)

Find the minimum at the value T using a spline.

Parameters:

• T (float | np.ndarray) – The temperature at which to eval the minimum

• deriv (int) – If deriv > 0, instead return the derivative of the minimum with respect to T. Can return up to the third derivative for cubic splines (when len(X) > 3) or first derivative for linear splines.

Returns:

The minimum at the temperature T.

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)

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

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

Parameters:

• phases (list[PhaseInfo])

• V (func)

• dV (func)

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, entropyInt, 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

entropyInt: 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, 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_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. This function assumes kinetic equilibrium between the dark sector and the SM.

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.

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

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.

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_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, support_bank=None, free_support_bank=None, action_temperatures=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)

Bases: object

Current percolation profile plus support-bank diagnostics.

Hr: ndarray

Pr: ndarray

Sr: ndarray

TSYM: ndarray

Tb: ndarray

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

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)

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

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)

Calculate the mean bubble separation at temperature T.

Parameters:

• T (float) – Symmetric phase temperature

• Tmax (float) – Upper limit of the integral, usually the nucleation temperature

• phase_sym (scipy.interpolate.interp1d object) – The symmetric phase

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

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

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

Returns:

R – Mean bubble separation.

Return type:

float

transitionlistener.bubbledynamics.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.

• phase_sym (scipy.interpolate.interp1d object) – The symmetric phase

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

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

Returns:

Tf – Final temperature.

Return type:

float

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

Calculate the phase transition speed from the action derivative.

Parameters:

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

• Sint (interpolate.interp1d) – Interpolation function of the action

• outdict (dict) – Dictionary storing the action evaluations, key is T

• pot (generic_potential) – The effective potential object

• phase_sym (PhaseInfo) – Information about the high temperature (symmetric) phase

• phase_bro (PhaseInfo) – Information about the low temperature (broken) phaes

Returns:

The transition speed beta/H.

Return type:

float

transitionlistener.bubbledynamics.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.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.g_eff_DS(T_DS, pot, phase)

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

Parameters:

• T (float) – Temperature at which to evaluate g_eff

• pot (generic_potential) – The effetive potential object

• phase (PhaseInfo) – The phase of the system, either symmetric or broken.

Returns:

Effective degrees of freedom in the dark sector.

Return type:

float

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

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

Parameters:

• T (float) – Temperature at which to evaluate g_eff

• pot (generic_potential) – The effetive potential object

• phase (PhaseInfo) – The phase of the system, either symmetric or broken.

Returns:

geff – Effective degrees of freedom in the dark sector.

Return type:

float

transitionlistener.bubbledynamics.logGamma(T, S)

Calculate the log10 of the bubble nucleation rate.

Parameters:

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

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

Returns:

Gamma – The bubble nucleation rate.

Return type:

np.ndarray

transitionlistener.bubbledynamics.percIntegral(T, H, S, vw=1.0, *, entropy_density=None, cooling_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)

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)

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

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

Return type:

np.ndarray

transitionlistener.bubbledynamics.percIntegralODE_full_sweep(T, H, S, vw=1.0, *, pot=None, phase_symmetric=None, time_temperature_mode=None, integral_method=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)).

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

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

Vct(X)

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

Return type:

ndarray

Vdaisy(bosons0, bosonsT, T)

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:

• X (array_like) – The field values

• 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

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

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.

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

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

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.

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

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:

• pot (generic_potential) – Effective potential

• 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) – Temperature

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

Return type:

float

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 maximum stepsizes used in step(), rescaled by |phi[0]-phi[1]| / (max(dV)*num_points).

• maxstep (float, optional) – Starting and maximum stepsizes used in step(), rescaled by |phi[0]-phi[1]| / (max(dV)*num_points).

• fRatioConv (float, optional) – The routine will stop when the maximum normal force on the path divided by the maximum potential gradient is less than this.

• converge_0 (float, optional) – On the first step, use a different convergence criterion. Check if fRatio < convergence_0 * fRatioConv.

• fRatioIncrease (float, optional) – The maximum fractional amount that fRatio can increase before raising an error.

• maxiter (int, optional) – Maximum number of steps to take (ignoring reversed steps).

• verbose (int, optional) – If verbose >= 1, print the ending condition. If verbose >= 2, print fRatio and stepsize at each step.

• callback (callable, optional) – Called after each step. Should accept an instance of this class as a parameter, and return False if deformation should stop.

• step_params (dict, optional) – Parameters to pass to step().

Returns:

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

Return type:

bool

forces(phi=None)

Calculate the normal force and potential gradient on the path.

Returns:

F_norm, dV

Return type:

array_like

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

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

Parameters:

• stepsize (float) – Determines change in phi: phi += F_norm*stepsize.

• minstep (float) – The smallest the stepsize is allowed to be.

• diff_check (float, optional) – The stepsize is chosen such that difference between the forces at beginning of the step and halfway through the step is small compared to the force itself: max(F2-F1) < diff_check * max(F1), where max here really means the maximum absolute value of the force in each direction.

• step_decrease (float, optional) – Amount by which to decrease the stepsize if the step is too big.

Returns:

• stepsize (float) – The stepsize used for this step.

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

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

Bases: object

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

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

Parameters:

• phi (array_like) – The list of points that constitutes the original path. Should have shape (n_points, n_dimensions).

• dphidr (array_like) – The ‘speed’ along the path at the initial points. This does not change as the path deforms. Should have shape (n_points,). Gets saved into the attribute v2 as v2 = dphidr[:,np.newaxis]**2.

• dV (callable) – The potential gradient as a function of phi. The output shape should be the same as the input shape, which will be (..., n_dimensions).

• nb (int, optional) – Number of basis splines to use.

• kb (int, optional) – Order of basis splines.

• v2min (float, optional) – The smallest the square of dphidr is allowed to be, relative to the characteristic force exterted by F_ext. Note that the self-correcting nature of the deformation goes away when dphidr=0.

• fix_start (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.

• fix_end (bool, optional) – If True, the force on the first/last point along the path is set to zero, so the point will not change in the deformation step.

• save_all_steps (bool, optional) – If True, each step gets saved into self.phi_list and self.F_list.

phi

Set during initialization, and then rewritten at each step.

Type:

array_like

num_steps

Total number of steps taken.

Type:

int

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

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.

• phitol (float, optional) – Fractional error tolerance in integration.

• thinCutoff (float, optional) – Equal to delta_phi_cutoff / (phi_metaMin - phi_absMin), where delta_phi_cutoff is used in initialConditions().

• npoints (int) – Number of points to return in the profile.

• rmin (float) – Relative to self.rscale. Sets the smallest starting radius, the starting stepsize, and the smallest allowed stepsize (0.01*rmin).

• rmax (float) – Relative self.rscale. Sets the maximum allowed integration distance.

• max_interior_pts (int) – Maximum number of points to place between r=0 and the start of integration. If None, max_interior_pts=npoints/2. If zero, no points are added to the bubble interior.

Returns:

• R, Phi, dPhi (array_like) – Radii and field values which make up the bubble profile. Note that R[0] can be much bigger than zero for thin-walled bubbles.

• Rerr (float or None) – The first value of r at which dr < drmin, or None if dr >= drmin always.

Notes

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

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

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

findRScale()

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

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

Raises:

PotentialError – when the barrier is non-existent.

findRscaleNew(phimeta, phi0)

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

Parameters:

• V (function) – Returns the potential at V(phi)

• phi0 (float) – The field release point

• phimeta (float) – The meta stable minimum of the potential

• ndim (int) – Number of dimensions.

• analytic (The)

• equation (solution to the)

• math:: (..)

• b (frac{d^2phi}{dr^2} + frac{nu}{r}frac{dphi}{dr} =)

• is

• math::

• r^2 (phi(r) = phi_0 + frac{b}{2(1+nu)})

• down (Get the time that takes the field to roll)

• potential. (a linear)

initialConditions(delta_phi0, rmin, delta_phi_cutoff)

Finds the initial conditions for integration.

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

Parameters:

• delta_phi0 (float) – delta_phi0 = phi(r=0) - phi_absMin

• rmin (float) – The smallest acceptable radius at which to start integration.

• delta_phi_cutoff (float) – The desired value for phi(r0). delta_phi_cutoff = phi(r0) - phi_absMin.

Returns:

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

Return type:

float

Notes

The field values are calculated using exactSolution().

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

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

Parameters:

• R (array_like) – The array of points at which we want to save the profile.

• y0 (float) – The starting values [phi(r0), dphi(r0)].

• dr (float) – Starting stepsize.

• epsfrac (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs().

• epsabs (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs().

• drmin (float) – The smallest allowed stepsize.

• eqn_args (tuple) – Extra arguments to pass to equationOfMotion(). Useful for subclasses.

Returns:

• R, Phi, dPhi (array_like) – Radii and field values which make up the bubble profile.

• Rerr (float or None) – The first value of r at which dr < drmin, or None if dr >= drmin always.

Notes

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

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

Integrate the bubble wall equation:

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

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

Parameters:

• r0 (float) – The starting radius for the integration.

• y0 (array_like) – The starting values [phi(r0), dphi(r0)].

• dr0 (float) – The starting integration stepsize.

• epsfrac (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs() and is used to test for convergence.

• epsabs (float) – The error tolerances used for integration. This is fed into helper_functions.rkqs() and is used to test for convergence.

• drmin (float) – The minimum allowed value of dr before raising an error.

• rmax (float) – The maximum allowed value of r-r0 before raising an error.

• eqn_args (tuple) – Extra arguments to pass to equationOfMotion(). Useful for subclasses.

Returns:

• r (float) – The final radius.

• y (array_like) – The final field values [phi, dphi]

• convergence_type (str) – Either ‘overshoot’, ‘undershoot’, or ‘converged’.

Raises:

helper_functions.IntegrationError –

profile_rval

alias of Profile1D

Finite temperature effective potentials

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

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

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

Call them by:

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

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

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.nDensity(m, T, g, ptype)

Numberdensity from tabulated values.

transitionlistener.thermodynamics.p_geff(m, T, g, ptype)

Pressure degrees of freedom, supports scalar or vector inputs for m and T.

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

Effective pressure degress of freedom for the SM.

Parameters:

• TSM (float or np.ndarray) – Temperature in internal energy units.

• CF (float) – Conversion factor to put everything in GeV.

• mode (str, optional) – Either “fit”, “smooth” or “data”.

Return type:

float | ndarray

transitionlistener.thermodynamics.p_geffSM_fit(TSM, CF)

Effective pressure degress of freedom for the SM.

Parameters:

• TSM (float or np.ndarray) – Temperature in internal energy units.

• CF (float) – Conversion factor to put everything in GeV.

Return type:

float | ndarray

transitionlistener.thermodynamics.ratio(T)

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.s_geff(m, T, g, ptype)

Entropy degrees of freedom, supports scalar or vector inputs for m and T.

transitionlistener.thermodynamics.s_geffDS(mSq_bosons, mSq_fermions, T)

Entropy degrees of freedom of the dark sector

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

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

Parameters:

• TSM (float or np.ndarray) – Temperature in internal energy units.

• CF (float) – Conversion factor to put everything in GeV.

• mode (str, optional) – “fit”, “smooth” or “data”.

Return type:

float | ndarray

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

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

Parameters:

• CF (float) – Conversion factor to GeV.

• mSq_bosons (tuple, optional) – Spectra evaluated at the true vacuum.

• mSq_fermions (tuple, optional) – Spectra evaluated at the true vacuum.

• verbose (bool, optional) – Print a warning containing the lightest SM mass when saturation is applied.

Return type:

float | None

Bubble wall velocity and hydrodynamics

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:

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

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

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.calc_kappas(alphaN, alpha_inf, alpha_eq, vw, cs, Rsep, R0, config)

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 at nucleation.

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

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

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!

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'

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

maxit = 10

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.T0_SM_GeV = 2.35253655e-13

CMB temperature \(T_0 = 2.725\,\\mathrm{K}\) in GeV.

transitionlistener.constants.fyr_Hz = 3.168808781402895e-08

Frequency corresponding to one inverse year in Hz.

transitionlistener.constants.yr = 31557600.0

One Julian year in seconds (\(365.25\) days).

Error handling

Custom exception hierarchy that exposes user-friendly error messages.

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

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

Bases: Exception

Raised when the eternal-inflation criterion is fulfilled.

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

Bases: Exception

Raised when the gravitational wave parameters are inconsistent or incomplete.

exception transitionlistener.errors.InfiniteActionError

Bases: Exception

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

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

Bases: Exception

Used when there is a problem creating the potential

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

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

Bases: Exception

Raised when the configuration file is missing or unreadable.

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

Bases: Exception

Raised when logging cannot be initialised.

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

Bases: Exception

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

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

Bases: Exception

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

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

Bases: Exception

Raised when no viable transition is found between identified phases.

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

Bases: Exception

Raised when the nucleation temperature could not be identified.

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

Bases: Exception

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

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

Bases: Exception

Raised when the scan identifies only second-order transitions.

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

Bases: Exception

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

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

Bases: Exception

Raised when the percolation temperature approximation fails to converge.

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

Bases: Exception

Raised when the percolation temperature could not be determined.

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

Bases: Exception

Used when the potential does not have the expected characteristics.

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

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

Bases: Exception

Raised when constructing a spline along the tunnelling path fails.

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

Bases: Exception

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

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

Bases: Exception

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

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

Bases: Exception

Raised when excessive supercooling prevents bubble nucleation within Hubble time.

exception transitionlistener.errors.TooSmalldVError

Bases: Exception

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

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

Bases: Exception

Raised when tunnelling fails to produce an action.

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

Bases: Exception

Raised when an unclassified failure occurs in the CLI.

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

Bases: Exception

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

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

Bases: Exception

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

exception transitionlistener.errors.ZeroActionError

Bases: Exception

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

Particle content definitions

Particle and mass spectrum utilities with concrete particle species.

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.

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