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 byCarpetIOHDF5
orCarpetIOASCII
, or in OpenPMD format.Work with horizon data from (
cactus_horizons
) as output byQuasiLocalMeasures
andAHFinderDirect
.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.