Overview

kuibit is a set of tools to post-process simulations performed with the Einstein Toolkit.

The goal of this package is to enable you to pursue your scientific goals without having to worry about computational details (e.g., handling simulation restarts, reading HDF5 files, …). kuibit represent simulation data in a high-level and intuitive way, and provides some commonly used routines in numerical-relativity (e.g., computing the strain of gravitational waves). A video introduction about kuibit can be found on YouTube.

The testimonials page collects short user’s reviews about kuibit.

Summary of Features

For a full list of available features, see the features page.

  • Read and organize simulation data (simdir). Checkpoints and restarts are handled transparently.

  • Work with scalar data as produced by CarpetIOASCII (cactus_scalars).

  • Analyze the multipolar decompositions output by Multipoles (cactus_multipoles).

  • Analyze gravitational waves extracted with the Newman-Penrose formalism (cactus_waves) computing, among the other things, strains, overlaps, energy lost.

  • Work with the power spectral densities of known detectors (sensitivity_curves).

  • Represent and manipulate time series (timeseries). Examples of functions available for time series: integrate, differentiate, resample, to_FrequencySeries (Fourier transform).

  • Represent and manipulate frequency series (frequencyseries), like Fourier transforms of time series. Inverse Fourier transform is available.

  • Manipulate and analyze gravitational-waves (gw_utils, gw_mismatch). For example, compute energies, mismatches, or extrapolate waves to infinity.

  • Work with 1D, 2D, and 3D grid functions (grid_data, cactus_grid_functions) as output by CarpetIOHDF5 or CarpetIOASCII.

  • Work with horizon data from (cactus_horizons) as output by QuasiLocalMeasures and AHFinderDirect.

  • Handle unit conversion, in particular from geometrized to physical (unitconv).

  • Write command-line scripts (argparse_helper).

  • Visualize data with matplotlib (visualize_matplotlib).

  • Make movies with motionpicture.

Installation

kuibit is available in PyPI. To install it with pip

pip3 install kuibit

If they are not already available, pip will install all the necessary dependencies.

The minimum version of Python required is 3.6.

If you intend to extend/develop kuibit, follow the instruction on GitHub.

Help!

Users and developers of kuibit meet in the Telegram group. If you have any problem or suggestion, that’s a good place where to discuss it. Alternatively, you can also open an issue on GitHub.

Frequently asked questions are collected in the page Frequently Asked Questions.

In addition to the tutorials and examples that are presented in this page, real-world examples can be found examples folder of the experimental branch.

Examples

Below you will find a list of examples to perform more or less common analysis. You can immediately start doing science without writing one line of code using these examples. The scripts provided can be used for plotting, extracting gravitational waves, or other useful information. To get the most out of these examples, check out the recommendations on how to use the examples page.

Note that all these examples contain a significant fraction of boilerplate that is needed to keep them general and immediately useful. When learning kuibit, you can ignore all of this.

You can download these examples as archive from the GitHub release page, which is automatically updated with each release.

Movies

motionpicture is a Python library to make animations used by kuibit. To learn more about motionpicture and how to use it, read the quick introduction to motionpicture.

What is a kuibit?

A kuibit (also known as kukuipad harvest pole) is the tool traditionally used by the Tohono O’odham people to reach the fruit of the Saguaro cacti during the harvesting season. In the same way, this package is a tool that you can use to collect the fruit of your Cactus simulations.

Credits

kuibit follows the same design and part of the implementation details of PostCactus, code developed by Wolfgang Kastaun. This fork completely rewrites the original code, adding emphasis on documentation, testing, and extensibility. The logo contains elements designed by freepik.com. We thank kuibit first users, Stamatis Vretinaris and Pedro Espino, for providing comments to improve the code and the documentation.

Citation

kuibit is built and maintained by the dedication of one graduate student. Please, consider citing kuibit if you find the software useful. You can use the following bibtex key.

@article{kuibit,
       author = {{Bozzola}, Gabriele},
        title = "{kuibit: Analyzing Einstein Toolkit simulations with Python}",
      journal = {The Journal of Open Source Software},
     keywords = {numerical relativity, Python, Einstein Toolkit, astrophysics, Cactus, General Relativity and Quantum Cosmology, Astrophysics - High Energy Astrophysical Phenomena},
         year = 2021,
        month = apr,
       volume = {6},
       number = {60},
          eid = {3099},
        pages = {3099},
          doi = {10.21105/joss.03099},
archivePrefix = {arXiv},
       eprint = {2104.06376},
 primaryClass = {gr-qc},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2021JOSS....6.3099B},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}