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.

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.

Installation using pip

NuRadioReco is a subpackage of NuRadioMC, so both are installed at once using pip:

pip install NuRadioMC

NuRadioMC/NuRadioReco will then be available from Python using import NuRadioMC and import NuRadioReco, respectively. This installs all core dependencies. Some features require additional packages, which are grouped into options and 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.

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.

Note

Users of zsh (the default shell on MacOS) have to wrap the argument in quotes, i.e. pip install -e '.[dev]', as zsh otherwise interprets the square brackets itself.

Optional Dependencies

The core installation of NuRadioMC deliberately stays lightweight: several features rely on additional packages that are not installed by default. These are grouped into options (also called “extras”), which are appended in square brackets when installing NuRadioMC, e.g.

pip install NuRadioMC[proposal]                 # a single option
pip install NuRadioMC[proposal,galacticnoise]   # several options at once
pip install -e .[dev,proposal]                  # the same for a development install

The available options are:

Option	Installs	Needed for
[proposal]	proposal	Propagation of secondary leptons, NuRadioMC.EvtGen.NuRadioProposal
[galacticnoise]	pygdsm, pylfmap, healpy	Adding galactic noise, NuRadioReco.modules.channelGalacticNoiseAdder
[muon-flux]	MCEq, crflux	Atmospheric muon flux calculations, NuRadioMC.utilities.muon_flux
[cr_interpolator]	cr-pulse-interpolator	Interpolation of CoREAS star-shape simulations, NuRadioReco.modules.io.coreas.coreasInterpolator
[minimizers]	iminuit, scikit-optimize, noisyopt	Additional minimizers in NuRadioReco.utilities.minimization
[dev]	pre-commit, Sphinx, sphinx-rtd-theme, numpydoc	Contributing to NuRadioMC and building the documentation locally
[all]	all of the above except [dev]	Convenience option to get all user-facing features

Note that option names are normalised by pip, so [cr_interpolator] and [cr-interpolator] are equivalent. To get everything, including the development dependencies, use pip install NuRadioMC[all,dev]. A few features additionally depend on packages that are not part of any option: they either cannot be installed via pip or are only needed for specific detectors or data formats.

• [proposal]

  PROPOSAL is a lepton propagation code. It is needed to use the NuRadioMC.EvtGen.NuRadioProposal module, which simulates the secondary interactions of muons and taus, i.e. the showers that these leptons induce along their path through the ice. Without it, NuRadioMC only simulates the shower produced at the neutrino interaction vertex itself.

  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]

  The channelGalacticNoiseAdder and efieldGalacticNoiseAdder modules add the diffuse emission of the galaxy to simulated traces. This is the dominant noise source for detectors at frequencies below a few hundred MHz, e.g. for air-shower detection. The sky models are provided by PyGDSM (GSM, GSM2016, LFSM, …); pylfmap provides the additional LFmap model used by LOFAR for calibration purposes, and healpy is used to handle the sky maps.

  pip install pygdsm pylfmap healpy
  

• [muon-flux]

  MCEq solves the cascade equations for the atmosphere and crflux provides parametrisations of the cosmic-ray flux. Together they are used by NuRadioMC.utilities.muon_flux to calculate the flux of atmospheric muons at the surface, which is the main background for in-ice radio detectors at PeV energies.

  pip install MCEq crflux
  

• [cr_interpolator]

  Installs the cosmic-ray pulse interpolator from https://github.com/nu-radio/cr-pulse-interpolator. CoREAS air-shower simulations are usually produced on a star-shaped pattern of observer positions. The coreasInterpolator uses this package to interpolate the simulated pulses to arbitrary positions in between, so that a single CoREAS simulation can be reused for many detector positions or shower cores.

  pip install cr-pulse-interpolator
  

• [minimizers]

  The Minimizer class provides a common interface to different minimization algorithms used in reconstruction. Beyond the scipy minimizers (which are always available), it can use iminuit (MIGRAD/MINOS, including proper uncertainty estimation), scikit-optimize (Bayesian/global optimization) and noisyopt (minimization of noisy objective functions).

  pip install iminuit scikit-optimize noisyopt
  

• [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
  

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.

Other optional packages

These packages can be installed with pip, but are not part of any option because they are only needed for specific detectors or data formats.

• 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
  

• To use a detector description stored in an SQL database (NuRadioReco.detector.detector_sql), install MySQL and mysql-connector-python:

  pip install mysql-connector-python