# 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`

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

## Usage¶

- First steps with
`kuibit`

- Getting started with SimDir
- Time and frequency series
- Scalar data
- Working with multipolar decompositions
- Working with horizons
- Gravitational waves
- TwoPunctures metadata
- Masking invalid data
- Gravitational-wave utilities
- Mismatch between gravitational waves
- Grid functions
- Horizon utilities
- Sensitivity (power spectral noise) curves of known detectors
- Working with timers
- Working with tensors
- Unit conversion and constants
- Visualizing data with matplotlib
- Building command-line scripts
- A quick introduction to motionpicture

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

### Scripts¶

- describe_simdir.py
- interactive_timertree.py
- picklify.py
- plot_1d_slice.py
- plot_1d_vars.py
- plot_ah_coordinate_velocity.py
- plot_ah_found.py
- plot_ah_radius.py
- plot_ah_separation.py
- plot_ah_trajectories.py
- plot_binary_ah_angular_velocity.py
- plot_binary_ah_period.py
- plot_charge_phi1.py
- plot_constraints.py
- plot_em_energy.py
- plot_grid_var.py
- plot_grid_expr.py
- plot_gw_energy.py
- plot_gw_angular_momentum.py
- plot_gw_linear_momentum.py
- plot_phi_time_averaged.py
- plot_phi_lm.py
- plot_physical_time_per_hour.py
- plot_psi4_lm.py
- plot_strain_lm.py
- plot_timeseries.py
- plot_total_luminosity.py
- print_ah_formation_time.py
- print_available_iterations.py
- print_available_timeseries.py
- print_grid_point_minmax.py
- print_qlm_properties_at_time.py
- save_resampled_grid_data.py

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

## Reference material (classes, functions, …)¶

- Recommendations on how to use the examples
- What users say about kuibit
- List of features implemented in kuibit
- Frequently Asked Questions
- Papers citing this software
- Reference on kuibit.simdir
- Reference on kuibit.series
- Reference on kuibit.timeseries
- Reference on kuibit.frequencyseries
- Reference on kuibit.cactus_grid_functions
- Reference on kuibit.cactus_scalars
- Reference on kuibit.cactus_multipoles
- Reference on kuibit.cactus_waves
- Reference on kuibit.cactus_horizons
- Reference on kuibit.cactus_twopunctures
- Reference on kuibit.cactus_timers
- Reference on kuibit.gw_utils
- Reference on kuibit.gw_mismatch
- Reference on kuibit.grid_data
- Reference on kuibit.hor_utils
- Reference on kuibit.masks
- Reference on kuibit.sensitivity_curves
- Reference on kuibit.unitconv
- Reference on kuibit.visualize_matplotlib
- Reference on kuibit.argparse_helper
- Reference on kuibit.tree
- Reference on kuibit.tensor

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