Overview¶

kuibit is a set of openly developed. 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 (a tutorial is also available) The YouTube series Using kuibit contains video tutorials on kuibit.

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

New to kuibit? Read First steps with 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.
Represent objects as mathematical vectors, matrices, and tensors (tensor).
Work with 1D, 2D, and 3D grid functions (grid_data, cactus_grid_functions) as output by CarpetIOHDF5 or CarpetIOASCII, or in OpenPMD format.
Work with horizon data from (cactus_horizons) as output by QuasiLocalMeasures and AHFinderDirect.
Perform common operations with horizons (hor_utils).
Work with timers produced by Carpet (cactus_timers).
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.7. kuibit follows NEP29.

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.

Tutorials¶

The YouTube series Using kuibit contains video tutorials on kuibit. Each video is focused on a single topic.

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.

grid_var

Reference material (classes, functions, …)¶

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

kuibit is built with NumPy, SciPy, and h5py, and optionally uses matplotlib, mayavi, and numba. Consider citing these packages too.

For a list of papers that cite kuibit, see Papers citing this software.

Disclaimer¶

kuibit is developed as professional tool that can be used for research to be published in peer-reviewed journals. As such, kuibit is tested to ensure that results are scientifically sound. However, we do not guarantee that the entirety of the software is correct and does what it is intended to do. Hence, users are strongly recommended to perform their independent validations and to report any problem.