CosmoGW v1.0

CosmoGW is a Python package for the analysis and modeling of cosmological gravitational wave (GW) backgrounds from different sources in the early Universe, including analytical models, templates, and data analysis routines.

v1.0 (August 2025) focuses on the production of GWs from sound waves and MHD turbulence from cosmological phase transitions.

Other sources of GWs will be included in future versions, contact me if you are interested in contributing and becoming a developer.

CosmoGW is an extension of GW_turbulence, created in December 2021, used for calculations of GWs produced by MHD turbulence.

Contact

Author: Alberto Roper Pol
Email: alberto.roperpol@unige.ch
GitHub: albertoroperpol

If you use any of the cosmoGW results, please cite this repository, the [manual] (coming soon) and the relevant references listed in the routines.

Feel free to reach out for questions, issues, or collaboration! I would also love to hear about your interest for this project and your work, so feel free to reach out for questions, issues, or collaboration!

Installation

CosmoGW is a Python package that can be installed using pip from PyPI:

pip install cosmoGW

Or directly from GitHub (last version but not necessarily stable):

pip install git+https://github.com/cosmoGW/cosmoGW.git

Requirements:
Python >= 3.8, numpy, scipy, matplotlib, astropy, pandas

To use the plotting routines available in the tutorials and in plot_sets, make sure to install LaTeX for Python:

LaTeX on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y cm-super dvipng texlive-latex-extra texlive-latex-recommended

LaTeX on macOS (using Homebrew):

brew install --cask mactex

File Structure

The main routines of cosmoGW are stored under src/cosmoGW:

• analysis.py: Analysis of GWs detectability with LISA.
• cosmology.py: Cosmological calculations.
• GW_analytical.py: Analytical calculations and mathematical functions.
• GW_back.py: Functions for cosmological GW backgrounds.
• GW_models.py: Theoretical and numerical models for sources of GWs.
• GW_templates.py: Templates for GW backgrounds from different sources.
• hydro_bubbles.py: Fluid perturbations from bubbles in first-order phase transitions.
• interferometry.py: Response and sensitivity functions for GW detectors (LISA, Taiji).
• utils.py: Utility functions and reference values for CosmoGW.
• tests/: Unit tests and example data.
• resources/: Data files used in the code (numerical data, sensitivity curves, ...)
• tutorials/: Tutorials showing how to use CosmoGW for different applications.

Documentation

Comprehensive documentation is available at Read the Docs.

• API Reference: Detailed documentation for all modules and functions.
• Tutorials: Step-by-step guides and example workflows.
• Theory: Background information and mathematical details.

To build the documentation locally:

cd docs
make html

Tutorials

Tutorials and example notebooks are available in the tutorials/ directory:

• GWs_sound-waves: Tutorial showing different templates of GWs from sound waves and non-linear compressional fluid perturbations from first-order phase transitions.
• GWs_MF_from_FOPT: Tutorial showing the analysis of GWs from sound waves and turbulence from first-order phase transitions with LISA in connection to primordial magnetic fields.

These tutorials can be run from Google Colab by loading the notebooks from GitHub.

When using Colab, latex needs to be installed, together with CosmoGW, for plotting routines. For the installation, uncomment and execute the first cell of the tutorials:

pip install cosmoGW
sudo apt-get update
sudo apt-get install -y cm-super dvipng texlive-latex-extra texlive-latex-recommended

Tests

Unit tests are provided in the tests/ directory.

To run all tests (from cosmoGW directory):

pytest

Make sure pytest is installed and that all required test data files are present in the tests directory.

Further test is available using the tutorial notebooks (see [python-package_nbs.yml]). To test the output plots and results from the notebooks run (e.g. from GWs_sound-waves tutorial):

pytest --nbval tutorials/GWs_sound-waves.ipynb

Make sure to have installed pytest, nbval and LaTeX:

LaTeX on Ubuntu/Debian:

pip install pytest nbval
sudo apt-get update
sudo apt-get install -y cm-super dvipng texlive-latex-extra texlive-latex-recommended

LaTeX on macOS (using Homebrew):

pip install pytest nbval
brew install --cask mactex

Resources

Data files are available in cosmoGW that are required by some of the libraries.

They are stored in src/cosmoGW/resources:

• cosmology: Cosmological evolution files and Friedmann equation tutorial.
• interferometry: Space-based GW interferometry calculations and tutorials.
• detector_sensitivity: Sensitivity of various detectors; see the README.
• higgsless: Data sets from Higgsless simulations of phase transitions.

📄 License

This project is licensed under the GNU General Public License v3 (GPLv3).

🚀 Enjoy exploring the early Universe with gravitational waves! 🪐