Metadata-Version: 2.2
Name: am3
Version: 1.0.1
Summary: AM³ is a software package for simulating lepto-hadronic interactions in astrophysical environments.
Author-Email: Annika Rudolph <annika.rudolph@desy.de>, Xavier de Sousa Ferreira Rodrigues <xavier.rodrigues@eso.org>, =?utf-8?q?Ga=C3=ABtan_Fichet_de_Clairfontaine?= <gaetan.fichet-de-clairfontaine@physik.uni-wuerzburg.de>, Chengchao Yuan <chengchao.yuan@desy.de>, Marc Klinger <marc.klinger@desy.de>
License: BSD-3-Clause
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Project-URL: repository, https://gitlab.desy.de/am3/am3
Project-URL: documentation, https://am3.readthedocs.io/en/latest/
Requires-Python: >=3.7
Provides-Extra: docs
Requires-Dist: myst_parser; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: rtds_action; extra == "docs"
Requires-Dist: pybind11; extra == "docs"
Requires-Dist: numpy; extra == "docs"
Requires-Dist: sphinx_rtd_dark_mode; extra == "docs"
Requires-Dist: better_apidoc; extra == "docs"
Requires-Dist: sphinx-gallery<0.11; extra == "docs"
Requires-Dist: docutils; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Description-Content-Type: text/markdown

# Welcome to the AM³ (Astrophysical Multi-Messenger Modeling) Software!

<p align="center">
  <img src="docs/media/logo.png" 
     width=30%
     height=auto 
     align="middle"/>
</p>


# Overview

AM³ is a software package for simulating lepto-hadronic interactions in astrophysical environments.
It solves the time-dependent partial differential equations for the energy spectra of electrons, positrons, protons, neutrons, photons, neutrinos as well as charged secondaries (pions and muons), immersed in an isotropic magnetic field. Crucially, it accounts for the fact that photons and charged secondaries emitted in electromagnetic and hadronic interactions feed back into the interaction rates in a time-dependent manner, therefore grasping non-linear effects including electromagnetic cascades. 

AM³ is the most computationally efficient among the state-of-the-art multi-messenger simulation tools [see Cerruti et al (2021)](https://doi.org/10.22323/1.395.0979). This makes it possible to use AM³ to scan vast source parameter scans and fit the observational data. At the time of its first public release, AM³ has been [extensively applied](#list-of-papers-based-on-am3) in studies of blazars, gamma-ray bursts and tidal disruption events.

With this open-source release, we are making AM³ available with all its current features. The solver consists of a C++ library that can be compiled and deployed directly. Alternatively, we provide Python users with an interface that allows to compile a shared library exposing all of AM³'s high-level functions to Python3. This means you can run simulations with AM³ in pure Python without any significant loss of efficiency.


# Documentation

For a detailed user guide, visit the [AM³ Read the Docs webpage](https://am3.readthedocs.io/en/latest/). 

# Citing AM³

If you use AM³ in you project, please cite [Klinger et al. 2023 (arXiv:2312.13371)](https://arxiv.org/abs/2312.13371)


# Collaborating

Do you want to contribute to AM³? Great! You just need to create a DESY GitLab account. Go to [gitlab.desy.de](https://gitlab.desy.de/) and select 'sign in with Helmholtz AAI'. Most international science institutes should be on the list. Alternatively, you can register with your Google account (by selecting 'google' from the list).
Once your account is requested, send an email to [gitlab.service@desy.de](mailto:gitlab.service@desy.de) and ask to enable your account, specifying that you wish to contribute to AM³. If you have issues with this or have any other question, contact us at [contact-am3@desy.de](mailto:contact-am3@desy.de).


# Installation

A detailed description of the installation procedure can be found in [the AM³ Read the Docs page](https://am3.readthedocs.io/en/latest/install_am3.html).

# Usage

The directory `docs/examples` contains Jupyter notebooks with complete source simulation workflows, from setting up the simulation to plotting the results.

# Articles based on AM³ by the time of its first release:

## Blazars
 - [Gao et al., ApJ 843 (2017)](https://doi.org/10.3847/1538-4357/aa7754)
 - [Gao et al., Nature Astron. 3 (2019)](https://doi.org/10.1038/s41550-018-0610-1)
 - [Rodrigues et al., ApJ Lett. 874 (2019)](https://doi.org/10.3847/2041-8213/ab1267)
 - [Rodrigues et al., ApJ 912 (2021)](https://doi.org/10.3847/1538-4357/abe87b)
 - [Rodrigues et al., A&A 681 (2024) A119](https://arxiv.org/abs/2307.13024)

## Gamma-ray bursts
 - [Rudolph et al., ApJL 944 (2023)](https://doi.org/10.3847/2041-8213/acb6d7)
 - [Rudolph et al., ApJ 950 (2023)](https://doi.org/10.3847/1538-4357/acc861)
 - [Rudolph et al., ApJ.Lett. 961 (2024)](https://arxiv.org/abs/2309.08667)
 - [Klinger et al., ApJ 977 (2024)](https://doi.org/10.3847/1538-4357/ad9392)

## Tidal disruption events
 - [Yuan et al., ApJ 956 (2023)](https://doi.org/10.3847/1538-4357/acf615)
 - [Yuan et al., arXiv: 2401.09320 (2024)](https://arxiv.org/abs/2401.09320)
 - [Yuan et al., arXiv: 2406.11513 (2024)](https://arxiv.org/abs/2406.11513)
