Metadata-Version: 2.4
Name: maggpy
Version: 0.1.0
Summary: Population inference and multimessenger predictions for short gamma-ray bursts.
Project-URL: Homepage, https://github.com/LudoDe/MAGGPY
Project-URL: Repository, https://github.com/LudoDe/MAGGPY
Project-URL: Issues, https://github.com/LudoDe/MAGGPY/issues
Author: Alessio Ludovico De Santis
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: MCMC,gamma-ray bursts,gravitational waves,multimessenger astronomy,population synthesis
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: <3.12,>=3.10
Requires-Dist: astropy<7,>=5.3
Requires-Dist: emcee<4,>=3.1
Requires-Dist: h5py<4,>=3.8
Requires-Dist: numpy<2,>=1.24
Requires-Dist: pandas<3,>=1.5
Requires-Dist: scipy<2,>=1.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: check-wheel-contents>=0.6; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Provides-Extra: fermi
Requires-Dist: astro-gdt-fermi<3,>=2.1; extra == 'fermi'
Provides-Extra: gw
Requires-Dist: cartopy<1,>=0.24; extra == 'gw'
Requires-Dist: gwfish; extra == 'gw'
Requires-Dist: healpy<2,>=1.17; extra == 'gw'
Provides-Extra: notebooks
Requires-Dist: ipykernel<7,>=6; extra == 'notebooks'
Requires-Dist: ipympl<1,>=0.9; extra == 'notebooks'
Requires-Dist: ipywidgets<9,>=8; extra == 'notebooks'
Requires-Dist: jupyterlab<5,>=4; extra == 'notebooks'
Requires-Dist: pyyaml<7,>=6; extra == 'notebooks'
Provides-Extra: plot
Requires-Dist: corner<3,>=2.2; extra == 'plot'
Requires-Dist: ipython<9,>=8; extra == 'plot'
Requires-Dist: matplotlib<4,>=3.7; extra == 'plot'
Description-Content-Type: text/markdown

<p align="center">
  <img src="LOGO.png" alt="MAGGPY logo" width="400">
</p>

<h1 align="center">MAGGPY</h1>

<p align="center">
  <b>Multimessenger Astronomy for GRBs and Gravitational Waves in Python</b>
</p>

## About

MAGGPY is a Python package I developed for simulating populations of short gamma-ray bursts and comparing them with observations from the Fermi/GBM catalogue.

The package uses forward Monte Carlo simulations and MCMC inference to investigate how assumptions about GRB jets, luminosity functions and binary neutron star merger rates affect the observed population. Both top-hat and structured jet models are included.

MAGGPY was originally developed for the analysis presented in [De Santis et al. (2026)](https://doi.org/10.1051/0004-6361/202659597).

## What MAGGPY does

* Simulates short GRB populations and their observable properties
* Fits simulated populations to Fermi/GBM catalogue data
* Supports top-hat and structured jet models
* Includes different binary neutron star merger-rate models
* Runs MCMC inference with `emcee`
* Produces posterior and population-comparison plots
* Supports joint gravitational-wave and electromagnetic predictions through GWFish

MAGGPY is research software and is still under active development.

## Installation

MAGGPY currently supports Python 3.10 and 3.11. I recommend installing it in a clean environment.

Using Conda:

```bash
conda create -n maggpy python=3.10
conda activate maggpy
python -m pip install maggpy
```

Or using Python's built-in virtual environments:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install maggpy
```

On Windows, activate the environment with:

```powershell
.venv\Scripts\activate
```

### Optional dependencies

Plotting support:

```bash
python -m pip install "maggpy[plot]"
```

Gravitational-wave calculations:

```bash
python -m pip install "maggpy[gw]"
```

Fermi catalogue tools:

```bash
python -m pip install "maggpy[fermi]"
```

To install everything used by the tutorial notebooks:

```bash
python -m pip install "maggpy[plot,gw,fermi,notebooks]"
```

## Getting started

Check that MAGGPY is installed correctly:

```python
import maggpy

print(maggpy.__version__)
```

The example notebooks in [`Tutorials`](Tutorials) cover:

1. Preparing Fermi/GBM catalogue data
2. Running the top-hat jet model
3. Running the structured jet model
4. Predicting joint gravitational-wave and gamma-ray detections
5. Estimating gravitational-wave sky localisation

The tutorials are intended to be read in order, but they can also be used as examples for setting up an independent analysis.

## Installing for development

To work on the source code:

```bash
git clone https://github.com/LudoDe/MAGGPY.git
cd MAGGPY
python -m pip install -e ".[plot,gw,fermi,notebooks,dev]"
```

Run the tests with:

```bash
pytest
```

## Citation

If you use MAGGPY in your work, please cite:

> A. L. De Santis, S. Ronchini, F. Santoliquido and M. Branchesi,
> “Constraining binary neutron star population synthesis models using short gamma-ray burst data,”
> *Astronomy & Astrophysics*, 710, A388 (2026).
> https://doi.org/10.1051/0004-6361/202659597

Full citation metadata is available in [`CITATION.cff`](CITATION.cff). GitHub also provides a **Cite this repository** button on the repository page.

## Questions and problems

If you find a bug, have trouble reproducing a result, or have a question about the package, please [open an issue](https://github.com/LudoDe/MAGGPY/issues).

## License

MAGGPY is distributed under the [BSD 3-Clause License](LICENSE).
