Overview

The CosmoTransitions package is a set of python modules for calculating properties of effective potentials with one or more scalar fields. Most importantly, it can be used to find the instanton solutions which interpolate between different vacua in a given theory, allowing one to determine the probability for a vacuum transition.

Installation

The easiest way to install CosmoTransitions is to download it from the Python Package Index using pip install cosmoTransitions (pip comes standard with Python 3 and many Python 2 distributions. It can also generally be installed with easy_install pip.). If you want to install it manually, just download source code and put the ‘cosmoTransitions’ folder somewhere in your path. Then from a python prompt one should be able to import cosmoTransitions and run the code. For examples, look in the examples folder.

CosmoTransitions makes extensive use of numpy and scipy, and the plotting functions use matplotlib. It is recommended that users also install IPython for easier interactive use (IPython also contains an excellent html-based python notebook, which is very handy for organizing computational and scientific work). These packages can be installed separately (using e.g. easy_install), or as part of a bundle (see the Anaconda distribution or the Enthought Canopy distribution).

CosmoTransitions was built and tested with Python v2.7.6, numpy v1.8.0, scipy v0.11.0, and matplotlib v1.2.0.

Module overview

There are four core modules in the package, with each subsequent module relying upon the ones that preceed it. However, the reverse is not true: lower-level modules do not rely on higher-level modules. For example, tunneling1D can be used independently of all the functions which calculate instantons in multiple field dimensions and the functions which determine finite-temperature effects. The core modules are:

• tunneling1D: Calculates instantons in a single field dimension using the overshoot / undershoot method.
• pathDeformation: Calculates instantons in multiple field dimensions by first guessing a tunneling path, solving for the one-dimensional instanton constrained to that path, and then iteratively deforming the path so that it satisfies the multi-dimensional instanton equations of motion. The algorithm used here was the core insight around which CosmoTransitions took shape.
• transitionFinder: Calculates the phase structure of a potential at finite temperature (that is, the position of the minima as a function of temperature), and finds the bubble nucleation temperature(s) to transition between phases.
• generic_potential: Contains an abstract class generic_potential.generic_potential which can be easily subclassed to model potentials in physically interesting theories. Also contains convenience functions for interacting with transitionFinder and for plotting the potential and its phases.

In addition, there a few auxiliary modules which do not rely upon any of the core modules:

• helper_functions: A collection of (mostly) stand-alone functions which are used by the core modules. This module is new.
• finiteT: Contains functions for calculates the finite-temperature contributions exactly and in different approximation regimes. Used by generic_potential.
• multi_field_plotting: Contains a class to ease visualization of potentials with three or more fields. This module is new.

Change log

Version 2.0.3

Version 2.0.3 fixes a small bug in SingleFieldInstanton.findRScale(). See issue #6.

Version 2.0.2

Version 2.0.2 updates CosmoTransitions to work with Python 3. It also marks the first version that’s been uploaded to the Python Package Index, so installation can now be as easy as pip install cosmoTransitions. Numerous formatting changes were made to bring the code into closer compliance with PEP 8 (the official python style guide), although all of the original un-pythonic naming conventions remain as they were.

Version 2.0

CosmoTransitions version 2 is a major update from version 1.0.2. The basic structure and computational strategy of the program remain the same, but many of the functions have changed to be more modular and extensible, and new functions have been added. Therefore, version 2 is not strictly backwards-compatible with version 1, and scripts that were written to use version 1 may need some minor revision to work with version 2.

The overall changes are:

• Much better documentation. Almost all functions now have detailed docstrings which describe their use. These can be examined interactively by running help(function) at the python prompt, or by simply looking them up on this website. This website is built using the sphinx documentation tool, so any future changes to the code should be automatically updated here.

• More transparent return types. Unless otherwise noted, any function with multiple named return values returns a named tuple. This should make interactive use easier and scripts clearer to read. For example, the findProfile() method returns a Profile1D named tuple, so the field values along the profile can be retrieved using profile = instanton.findProfile(); field_vals = profile.Phi.

• More rational nested calling structure. Because of it’s onion-like structure, CosmoTransitions often calls functions which call functions which call functions which might have some parameter that the user wants to tweak. Previously this was handled by passing extra keyword arguments to the top level function (like this: foo(**kwargs)), which often meant that the top-level function needed to know about the arguments in the bottom-level function. This is now generally handled by passing in whole dictionaries to the top-level function (without the two asterisks). For example, if when calling findAllTransitions(), one wishes to change the accuracy in the field phi used to calculate the instantons, one can call

  >>> model.findAllTransitions(tunnelFromPhase_args=dict(
  ...                          fullTunneling_params=dict(
  ...                          tunneling_findProfile_params=dict(
  ...                          phitol=new_phitol_value))))
  

  This is verbose, granted, but relatively unambiguous.

• More pythonic use of exceptions. Exceptions are much better than error codes for both debugging and general code readability. When the code encounters an unexpected value (for example, when the metastable minimum is lower than the supposedly stable minimum), it should now report an error immediately rather than producing a seemingly unrelated error later on.

• Syntax style changes. All tabs have been converted to spaces in keeping with the official python style guide, and lines have for the most part been shortened to 80 or fewer characters.

What follows are some of the more notable specific changes, organized by module:

• tunneling1D
  • The bubbleProfile class has been renamed SingleFieldInstanton, and a new class WallWithConstFriction has been added.
  • The radial scale is now set in its own function, and is set by the frequency of oscillations about the barrier’s maximum.
  • Derivatives are now calculated to fourth order in phi_eps.
  • The initial guess for the overshoot / undershoot method now defaults to the bottom of the potential barrier, rather than half way between the minima (this can be important for thick-walled bubbles).
  • The exactSolution() method now finds the exact solution about the point of interest (considering both dV and d2V), rather than always about the stable minimum.
• pathDeformation
  • The Deformation class has been renamed Deformation_Spline, and a new Deformation_Points class has been added. The latter does not use a spline to approximate the path, and may be faster in certain circumstances (but slower in others). It is a simpler implementation, in any case.
  • Fixed a bug in the step() method which caused errors for thick-walled bubbles.
  • Added a SplinePath class which encapsulates information about the tunneling path between deformation steps. This is used to describe the potential along the path for use in tunneling1D.
  • fullTunneling() is now a function, not a class.
  • The criticalTunneling and secondOrderTransition classes have been removed. The functionality of both are now in transitionFinder.
• transitionFinder
  • Added a Phase class which encapsulates information about a single temperature-dependent phase.
  • The traceMultiMin() function now returns a dictionary of phases, with each phase defined by a unique key.
  • The findTransitionRegions function has been removed.
  • The class fullTransitions has been replaced with the function findAllTransitions(), which has a somewhat more streamlined algorithm and interface.
• generic_potential
  • Derivatives now default to fourth-order error in x_eps, and are calculated using classes gradientFunction and hessianFunction.
  • The temperature scale is now set solely by self.Tmax. This avoids errors when there is a tree-level barrier and self.T0 == 0.
  • forbidPhaseCrit() is now a proper class method rather than a lambda function.
  • findAllTransitions() has somewhat different output matching the changes in transitionFinder.

To-do list

Still need to do a better job of testing the whole package, particularly the transitionFinder code. I haven’t tested any edge cases there yet.

Additionally:

Todo

Implement new versions of Jf and Jb that return zero when m=0, only adding in the field-independent piece later if include_radiation == True. This should reduce floating point errors when taking derivatives at very high temperature, where the field-independent contribution is much larger than the field-dependent contribution.

(The original entry is located in /Users/maxwain/programming/CosmoTransitions_v2/cosmoTransitions/generic_potential.py:docstring of cosmoTransitions.generic_potential.generic_potential.V1T, line 14.)

Todo

Add an example plot. Make documentation for the other plotting functions.

(The original entry is located in /Users/maxwain/programming/CosmoTransitions_v2/cosmoTransitions/generic_potential.py:docstring of cosmoTransitions.generic_potential.generic_potential.plot2d, line 25.)

Todo

Make sure to test removeRedundantPhases().

(The original entry is located in /Users/maxwain/programming/CosmoTransitions_v2/cosmoTransitions/transitionFinder.py:docstring of cosmoTransitions.transitionFinder.removeRedundantPhases, line 25.)

Todo

Possibly add extra logic to account for phases which coinincide at one end but not the other.

(The original entry is located in /Users/maxwain/programming/CosmoTransitions_v2/cosmoTransitions/transitionFinder.py:docstring of cosmoTransitions.transitionFinder.removeRedundantPhases, line 26.)

Todo

Create and document a CDL_Instanton class for tunneling with gravity.

(The original entry is located in /Users/maxwain/programming/CosmoTransitions_v2/cosmoTransitions/tunneling1D.py:docstring of cosmoTransitions.tunneling1D, line 11.)