MCEq - Matrix cascade equation

This scientific package might be useful fo all who deal with high-energy inclusive atmospheric fluxes of muons and neutrinos. In particular it might be useful for experiments, for example IceCube or MINOS, for calculations of systematic uncertainties and atmospheric backgrounds.

Status

The current development status is alpha. Although the numerical part of the program is rather stable, the parts related to user interaction, installation etc. are not finished, yet. Check the wiki for further items on the ToDo-list. Also feel free to open issues.

Documentation

As mentioned above the project is development. The current state of the documentation is more suited for developers rather than end-users. Mostly it is auto-generated sphinx-docs. Check it out before touching the code. The latest version of the documentation can be found here.

System requirements

• Some kind of modern CPU (Core2Duo++)
• 4GB (currently 8GB of RAM is strongly recommended. The solver is not optimized for memory usage, however there's lots of room for improvement)
• ~1GB of disk space
• a recent Linux or Mac OS X operating system. Windows might be suitable, but was not checked.

Software requirements

The majority of the code consists of pure Python modules. Some functions are accelerated through Just-In-Time (JIT) compilation using numba, which requires the llvmlite package.

Dependencies:

• python-2.7 (Python 3 not compatible yet)
• numpy
• scipy
• matplotlib
• ipython + notebook (optional, but needed for examples)
• numba
• progressbar

Installation

The installation simplest method relies on the Python package manager Anaconda/Miniconda by Continuum Analytics. It doesn't just improve your life, but also provides most of the scientific computing packages by default. It will not spoil your system Python paths and will install itself into a specified directory. The only action which is needed for activation, is to add this directory to your system $PATH variable. To un-install just delete this directory.

1. Download one of the installers for your system architecture from here:

   • Anaconda - larger download, already containing most of the scientific packages and the package manager conda itself
   • Miniconda - minimal download, which contains the minimum requirements for the package manager conda.

2. Run the installer and follow the instructions:

   $ bash your-chosen-conda-distribution.sh

   Open a new terminal window to reload your new $PATH variable.

3. Cd to you desired working directory. And clone this project including submodules:

   $ git clone --recursive https://github.com/afedynitch/MCEq.git

   It will clone this github repository into a folder called MCEq and download all files. Enter this directory.

4. To install all dependencies into you new conda environment

   $ conda install --file conda_req.txt

   This will ask conda to download and install all needed packages into its default environment.

5. (Optional) If you know what a virtualenv is, the corresponding commands to download and install all packages in a newly created environment mceq_env are

   $ conda create -n mceq_env --file conda_req.txt
   $ source activate mceq_env

   To quit this environment just

   $ deactivate

6. (Optional) Acceleration of the integration routines can be achieved using Intel Math Kernel Library (MKL). Anaconda offers MKL-linked numpy binaries free for academic use. It is necessary to register using your .edu mail address to receive a license. The demo period is 30 days. If you want to give it a try

   $ conda install mkl

   Change in mceq_config.py the kernel entry to 'MKL'.

7. Run some example

   $ ipython notebook

   click on the examples directory and select basic_flux.ipynb. Click through the blocks and see what happens.

Troubleshooting

You might run into problems with Anaconda if you have previous Python installations. A workaround is to set the environment variable

$ export PYTHONNOUSERSITE=1

Thanks to F.C. Penha for pointing this out.

Citation

If you are using this code in your scientific work, please cite

Calculation of conventional and prompt lepton fluxes at very high energy

A. Fedynitch, R. Engel, T. K. Gaisser, F. Riehn, T. Stanev,

arXiv:1503.00544

Please, also cite or footnote this Github site and revisit this page from time to time, to get the most up2date information.

The models inside this code need to be cited separately. Please see the documentation for the complete list of references.

Contributers

Anatoli Fedynitch

Copyright and license

Code and documentation copyright 2014-2015 Anatoli Fedynitch. Code released under the MIT license.