Metadata-Version: 2.1
Name: daemonflux
Version: 0.6.1
Summary: Tabulated representation of a muon-calibrated muon and neutrino flux model
Home-page: https://github.com/mceq-project/daemonflux
Download-URL: https://pypi.python.org/pypi/daemonflux
Author: Anatoli Fedynitch
Maintainer-email: afedynitch@gmail.com
License: BSD 3-Clause License
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Intended Audience :: Science/Research
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: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy (>=1.8.0)
Requires-Dist: rich
Provides-Extra: examples
Requires-Dist: matplotlib ; extra == 'examples'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'

# daemonflux: DAta-drivEn and MuOn-calibrated Neutrino flux

Daemonflux is a tabulated/splined version of the an atmospheric flux model calibrated on muon spectrometer data. For the details about how daemonflux is built and calibrated to muon data [the following publication](https://inspirehep.net/literature/2637710).

```
@article{Yanez:2023lsy,
    author = "Ya\~nez, Juan Pablo and Fedynitch, Anatoli",
    title = "{daemonflux: DAta-drivEn MuOn-calibrated Neutrino Flux}",
    eprint = "2303.00022",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    month = "2",
    year = "2023"
}
```

## Requirements
 * `Python > 3.7`, `numpy`, `scipy`
 * `matplotlib` for examples

## Installation
a) From PyPi: 
    
    pip install daemonflux
    
b) From source in editable mode, so the package gets updated after each `git pull`:
```bash
$ git clone https://github.com/mceq-project/daemonflux
$ cd daemonflux
$ python3 -m pip install -e .
```

## Quickstart

To see more features and a detailed example, refer to the [example](examples/example.ipynb) notebook. In summary, the process of calculating calibrated fluxes from the provided tables is as follows:

    from daemonflux import Flux
    import numpy as np
    import matplotlib.pyplot as plt

    daemonflux = Flux(location='generic')
    egrid = np.logspace(0,5) # Energy in GeV

    fl = daemonflux.flux(egrid, '15', 'numuflux')
    err = daemonflux.error(egrid, '15', 'numuflux')
    plt.loglog(egrid, fl, color='k')
    plt.fill_between(egrid, fl + err, fl - err,
        color='r', alpha=.3, label=r'1$\sigma$ error')
    ...

Resulting in the following figure:

![Muon Neutrino Flux plot](flux_example.png "Muon neutrino flux scaled by $E^3$ for clarity.")


## Explanation of quantities and units

For **neutrinos**, the methods `Flux.flux` and `Flux.error` return values in the units of $(E/\text{GeV})^3/(\text{GeV }\text{s }\text{sr }\text{cm}^2)$, i.e. multiplied by $E^3$. For **muon quantities** are reported as a function of total momentum instead of energy, i.e. the units are  $(p/\text{(GeV/c)})^3/(\text{(GeV/c) } \text{s }\text{sr }\text{cm}^2)$. Natural units $\hbar=c=1$ are used everywhere.

The quantities are: 

- muons: `muflux`, `muratio`, `mu+`, `mu-`,
- muon neutrinos: `numuflux`, `numuratio`, `numu`, `antinumu`, `flavorratio`
- electron neutrinos: `nueflux`, `nueratio`, `nue`, `antinue`, `flavorratio`

Those titled XXXflux are the sum of particle and antiparticle fluxes `numuflux = numu + antinumu`, the ratio is `numuratio = numu/antinumu`, and the is defined as `flavorratio = (numu + antinumu)/(nue + antinue)`.

The `total_` quantities, such as `total_muflux`, represent the total flux, which includes both conventional and prompt atmospheric fluxes. However, unlike the conventional flux, the prompt flux is not calibrated using the daemonflux method, as surface muons are not sensitive to prompt fluxes. As a result, the prompt component does not include correction parameters or errors. It is important to note, however, that the conventional part of the flux remains calibrated, so the total_ flux is simply the sum of the calibrated conventional and uncalibrated prompt fluxes.

## LICENSE

[BSD 3-Clause License](LICENSE)
