Metadata-Version: 2.1
Name: gw_remnant
Version: 0.2.0
Summary: Python package to extract remnant black hole properties from gravitational waveforms
Home-page: https://github.com/tousifislam/gw_remnant
Author: Tousif Islam, Scott Field, Gaurav Khanna
Author-email: tousifislam24@gmail.com
Maintainer: Tousif Islam
Maintainer-email: tousifislam24@gmail.com
License: MIT
Project-URL: Bug Reports, https://github.com/tousifislam/gw_remnant/issues
Project-URL: Source, https://github.com/tousifislam/gw_remnant
Keywords: gravitational waves,black holes,numerical relativity,remnant properties
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Other Audience
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: gwtools
Provides-Extra: surrogates
Requires-Dist: gwsurrogate; extra == "surrogates"
Requires-Dist: surfinBH; extra == "surrogates"
Provides-Extra: lal
Requires-Dist: lal; extra == "lal"
Requires-Dist: lalsimulation; extra == "lal"
Provides-Extra: all
Requires-Dist: gwsurrogate; extra == "all"
Requires-Dist: surfinBH; extra == "all"
Requires-Dist: lal; extra == "all"
Requires-Dist: lalsimulation; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: jupyter; extra == "dev"

# gw_remnant

During binary-black-hole (BBH) mergers, energy and momenta are carried away from the binary system as gravitational radiation. Access to the radiated energy and momenta allows us to accurately predict the properties of the remnant black hole. 

```gw_remnant``` is an easy-to-use python package to efficiently extract the remnant mass, remnant spin, peak luminosity and the final kick imparted on the remnant black hole directly from the gravitational radiation.

Github repo for this project is : ```https://github.com/tousifislam/gw_remnant```

Currently it has the ability to generate waveforms from ```NRHybSur3dq8``` and ```BHPTNRSur1dq1e4```. However, it can take waveforms generated by other methods by the user too. 

## Repository Structure
```
gw_remnant/
├── gw_remnant/                        # Main package directory
│   ├── __init__.py                    # Package initialization
│   ├── gw_remnant_calculator.py       # Main calculator class
│   ├── gw_waveform_generator.py       # Waveform generation utilities
│   │
│   ├── gw_utils/                      # Utility functions
│   │   ├── __init__.py
│   │   ├── waveform_generator.py      # Waveform generation helpers
│   │   └── gw_plotter.py              # Plotting utilities
│   │
│   └── remnant_calculators/           # Remnant property calculators
│       ├── __init__.py
│       ├── remnant_mass_calculator.py
│       ├── remnant_spin_calculator.py
│       ├── kick_velocity_calculator.py
│       ├── peak_luminosity_calculator.py
│       └── initial_energy_momenta.py
│
├── tutorials/                         # Example notebooks and tutorials
├── tests/                             # Unit tests (if added)
├── setup.py                           # Package installation configuration
├── README.md                          # This file
├── LICENSE                            # License information
└── .gitignore                         # Git ignore rules
```

## Tutorials

Example notebook is provided in ```https://github.com/tousifislam/gw_remnant/tutorials``` directory.

You can find examples with deafult waveforms (BHPTNRSur1dq1e4 and NRHybSur3dq8) here : [https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_default_waveforms.ipynb](https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_default_waveforms.ipynb)

**If you do not already have gwsurrogate and BHPTNRSurrogate(s) installed, you can use the example with customed waveforms for now**

Examples with custom waveforms are given here : [https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_customized_waveform.ipynb](https://github.com/tousifislam/gw_remnant/blob/main/tutorials/example_with_customized_waveform.ipynb)


## BHPTNRremnant

```gw_remnant``` package has been used in developing NR-tuned perturbation based remnant model that can provide faithful estimates of the remnant properties for binaries with mass ratios ranging from ```q=3``` to ```q=1000```.

## Citation guideline

If you make use of any module from the Toolkit in your research please acknowledge using:

> This work makes use of the Black Hole Perturbation Toolkit.

If you make use of the ```gw_remnnat``` package or ```BHPTNRremnant``` surrogate models please cite the following paper:

```
@article{Islam:2022laz,
    author = "Islam, Tousif and Field, Scott E. and Khanna, Gaurav.",
    title = "{Remnant black hole properties from numerical-relativity-informed perturbation theory and implications for waveform modelling}",
    eprint = "https://arxiv.org/abs/2301.07215",
    archivePrefix = "arXiv",
    primaryClass = "gr-qc",
    month = "1",
    year = "2023"
}
```
