Installing NuRadioMC / NuRadioReco

Requirements

In order to use NuRadioMC / NuRadioReco, please ensure you are using a version of Python >=3.7, and a UNIX operating system (linux or MacOS). If you are using Windows, consider installing the Windows Subsystem for Linux.

Installation using `pip`

As of version 2.0.0, NuRadioReco is now a subpackage of NuRadioMC. Both NuRadioMC and NuRadioReco can therefore be installed using pip:

pip install NuRadioMC

NuRadioMC/NuRadioReco will then be available from Python using import NuRadioMC and import NuRadioReco, respectively. The pip installation will install all core dependencies. Some optional dependencies can be installed by appending [option], i.e. pip install NuRadioMC[option]. One can also use [all] to install all (non-development) dependencies.

Important

Some optional dependencies cannot be installed using pip and have to be installed manually.

Note

This is the release version of NuRadioMC. If you want the latest (development) version, use

pip install git+https://github.com/nu-radio/NuRadioMC.git

instead, or install it manually (see below).

Development version

If you want the most recent, in-development version of NuRadioMC, or intend to contribute to its development, you can get it via the NuRadioMC github:

git clone https://github.com/nu-radio/NuRadioMC.git

If you don’t already have it installed, you should install Git.

Note

We highly recommend installing NuRadioMC inside a virtual environment. You can either use python3 -m venv name_of_venv or use a virtual environment manager like conda.

To install NuRadioMC and its dependencies, use the pip editable install. Navigate to the NuRadioMC folder and run:

cd NuRadioMC/
pip install -e .[dev]
pre-commit install

(note the -e flag!). This will install the core dependencies, as well as the optional dev dependencies (use [dev,all] instead to also install all optional dependencies), and tell python to look for NuRadioMC and NuRadioReco in this folder, so that you can edit and contribute to the codebase while using it. The last line, pre-commit install installs a git hook using pre-commit. This is highly recommended for developers as it helps to keep the repository clean from accidentally added large files. More details are given here.

Manual installation

Pip-installable dependencies

To install all (optional and non-optional) dependencies available in pip at once, use the command

pip install numpy scipy matplotlib astropy tinydb tinydb-serialization aenum h5py mysql-connector-python pymongo dash plotly toml peakutils future radiotools filelock mattak git+https://github.com/telegraphic/pygdsm pylfmap MCEq crflux git+https://github.com/nu-radio/cr-pulse-interpolator

Only for developers, we also recommend

pip install Sphinx sphinx-rtd-theme numpydoc pre-commit

which are used to locally compile the documentation, and to perform some safety checks when contributing new code.

Note that some optional dependencies are not pip-installable and need to be installed manually

Core Dependencies

toml:
```
pip install toml
```
radiotools:
```
pip install radiotools
```
numpy:
```
pip install numpy
```
scipy:
```
pip install scipy
```
matplotlib:
```
pip install matplotlib
```
astropy:
```
pip install astropy
```
tinydb: tinydb version 4.1.1 or newer is required.
```
pip install tinydb tinydb-serialization
```
Advanced enum:
```
pip install aenum
```
h5py to open HDF5 files:
```
pip install h5py
```
filelock:
```
pip install filelock
```
For MongoDB databases install:
```
pip install pymongo
```
To use the Event Display you need plotly and dash:
```
pip install dash
pip install plotly
```

Optional Dependencies

These packages are recommended to be able to use all of NuRadioMC/NuRadioReco’s features. They can be installed by including adding [option] when installing NuRadioMC. Alternatively, use pip install nuradiomc[all] to install all optional dependencies (or [all,dev] to also install development dependencies).

[proposal]

proposal is needed to use NuRadioMC.EvtGen.NuRadioProposal module (simulating secondary particles):
```
pip install proposal==7.6.2
```
Note that the pip installation for this version of proposal may not work on all systems, in particular:
- conda cannot be used on all systems (eg. on Mac), in that case use a python venv, see details here
- if the linux kernel is too old (eg. on some computing clusters), refer to this step-by-step guide
[galacticnoise]

To use the channelGalacticNoiseAdder, you need the PyGDSM package. Some additional galactic noise models used by LOFAR for calibration purposes are provided by pylfmap.
```
pip install git+https://github.com/telegraphic/pygdsm pylfmap
```
[muon-flux]

Needed for some muon flux calculations
```
pip install MCEq crflux
```
[cr-interpolator]

Installs the cosmic-ray interpolator from https://github.com/nu-radio/cr-pulse-interpolator, used to interpolate cosmic-ray air-shower emission from CoREAS star-shaped patterns:
```
pip install cr-pulse-interpolator
```
[dev]

For developers, we use pre-commit to prevent the accidental addition of large files that would clutter the repository, as well as run some simple code formatting checks (see here for more details):
```
pip install pre-commit
```
The documentation is created using Sphinx. We use the readthedocs theme, and the numpydoc format is used in our docstrings. These dependencies are needed only if you want to generate the documentation locally - the online documentation is generated by a Github action automatically. Note that we use the sphinx autodoc feature, which tries to import all modules it documents. So if you are missing some optional dependencies, it will not generate correct documentation for all the code.
```
pip install sphinx sphinx_rtd_theme numpydoc
```
RNO-G-specific dependencies

mattak is required to open RNO-G root files:
```
pip install git+https://github.com/RNO-G/mattak
```
Optionally, to filter RNO-G data (during read in) the RNO-G run table database can be used. Note that this requires membership of the RNO-G Github organisation (not public):
```
pip install git+ssh://git@github.com/RNO-G/rnog-runtable.git
```
Some debug plots need peakutils:
```
pip install peakutils
```
For SQL databases install MySQL and mysql-connector-python:
```
pip install mysql-connector-python
```

Not pip-installable packages

To speed up the analytic ray tracing module, GSL needs to be installed, and $GSL_DIR should point at the correct installation folder. On Linux, GSL can be installed using
```
sudo apt-get install libgsl-dev
```
(On MacOS, use brew install gsl instead - you may have to install homebrew first). With GSL installed, compile the CPP ray tracer by navigating to NuRadioMC/NuRadioMC/SignalProp and running the included install.sh script.
To use the RadioPropa numerical ray tracing module, radiopropa needs to be installed. The radiopropa github, with installation instructions, can be found here.
To read ARIANNA files, Snowshovel needs to be installed.
To read ARA files, ARA ROOT needs to be installed.