Installation

3ML brings together multiple instrument and fitting software packages into a common framework. Thus, installing all the pieces can be a bit of a task for the user. In order to make this a less painless process, we have packaged most of the external dependencies into conda (see below). However, if you want more control over your install, 3ML is also available on PyPI via pip. If you have issues with the installs, first check that you have properly installed all the external dependencies that you plan on using. Are their libraries accessible on you system’s standard paths? If you think that you have everything setup properly and the install does not work for you, please submit an issue and we will do our best to find a solution.

In a nutshell:

Run the following commands if you want to install 3ML and astromodels:

  • with conda without XSPEC

conda install -c threeml -c conda-forge astromodels threeml

  • with conda with XSPEC

conda install -c https://heasarc.gsfc.nasa.gov/FTP/software/conda/ -c conda-forge xspec python=3.11
conda install -c threeml -c conda-forge astromodels threeml

  • with conda with fermitools and fermipy

conda install -c threeml -c fermi -c conda-forge fermitools astromodels threeml fermipy

  • with pip (please take care of dependencies beforehand!)

pip install astromodels threeml

  • in case you want the development versions:

conda install -c threeml/label/dev -c conda-forge astromodels threeml

or

pip install --upgrade --pre astromodels threeml

Conda installation

Conda is a platform independent package manager. It allows to install 3ML (and a lot of other software) without the need to compile anything, and in a completely separate environment from your system and your system python.

For detailed conda installation instructions please checkout the documentation. Usually miniconda is a good start :).

If you are new to conda please stick to these commands and do not change the order of the channels for example, those really do matter.

conda create --name threeML -c conda-forge python=3.11

then activating your environment:

conda activate threeML

Note

Recently a third party has uploaded a version of astromodels to the conda-forge channel. This version is not support and It is important to set your conda channel priority so that the threeml channel has priority over the conda-forge channel. Please verify that the astromodels installed comes from our threeml channel. We are working to resolve this hassle and we apologize to our users.

Before running the next command, conda will list all packages that will be installed and from where they will be installed. Please ensure here that threeml and astromodels both come from something like

The following packages will be downloaded:
package                    |            build
                        ...
astromodels-2.5.1          |  py311h1831ba8_0         2.1 MB  threeml
                        ...
threeml-2.5.0              |          py311_0        50.0 MB  threeml
                        ...

with the important part being the threeml at the end of the line. If it says conda-forge check that the threeml channel has a higher priority than the conda-forge one.

conda install -c threeml -c conda-forge astromodels threeml

If you want to install the dev version add the label dev:

conda install -c threeml/label/dev -c conda-forge astromodels threeml

In case you still run into issues with threeML and astromodels coming from conda-forge you can enforce the origin via

conda install threeml::astromodels threeml::threeml

or in case of the dev versions

conda install threeml/label/dev::astromodels threeml/label/dev::threeml

pip

If you would like to install 3ML and astromodels on their own and have more control over which dependencies you would like to use. Please to the following

  1. It is highly recommended you work within a python virtual environment to keep you base python clean

  2. install astromodels

pip install astromodels

  1. install 3ML

pip install threeml

If you need to build other dependencies such as pagmo, multinest, XSPEC, etc., it is recommended you do this before installing astromodels!

If you want to install the dev version add the --pre option:

pip install --upgrade --pre astromodels threeml

XSPEC models

We allow the ability to use the models provided by XSPEC natively in 3ML. However, before installing astromodels or 3ML, you must already have XSPEC installed by one of two methods.

HEASARC install

If you have XSPEC installed on your computer via the source code, then before installing astromodels, make sure to init your HEASARC environment. Upon installing astromodels, the process will attempt to find the proper libraries on your system if it detects XSPEC and compile the proper extensions. If you have installed your XSPEC in a non-standard directory (e.g. your home directory), the process my not find all the libraries. You can thus export an env variable that provides the explicit path to your XSPEC headers:

export XSPEC_INC_PATH=/path/to/xspec/headers

As XSPEC evolves, various models have different interfaces that depend on the version. To accommodate this, you need to set the version of XSPEC you are using with another env variable, e.g.:

export ASTRO_XSPEC_VERSION='12.15.1'

Other dependencies

You need to set up packages such as AERIE (for HAWC), or the Fermi Science Tools, before running the script, otherwise some of the functionalities will not work.

  • AERIE for HAWC: make sure that this works before running the script:

> liff-PointSourceExpectation --version
INFO [CommandLineConfigurator.cc, ParseCommandLine:137]: 

 liff-PointSourceExpectation
 Aerie version: 2.04.00
 Build type: Debug

If it doesn’t, you need to set up the HAWC environment (refer to the appropriate documentation)

  • fermitools and fermipy for Fermi/LAT analysis: make sure that this works:

> gtirfs ...  P8R2_TRANSIENT100_V6::EDISP0 P8R2_TRANSIENT100_V6::EDISP1 ...

If it doesn’t, you need to install fermitools and fermipy with conda in the same environment:

conda install -c fermi -c conda-forge fermitools fermipy

  • ROOT: ROOT is not required by 3ML, but it provides the Minuit2 minimizer which can be used in 3ML. If you have ROOT, make sure that this works before running the script:

> root-config --version
6.36.06

Note

There is currently a known incompatibility on some systems between ROOT and 3ML, causing the following error while trying to use the ROOT minimizer:

TypeError: no python-side overrides supported (failed to include Python.h)

While this issue is being investigated, we recommend using the minuit minimizer directly.

Install from source (advanced)

Remove any previous installation you might have with:

> pip uninstall threeML
> pip uninstall astromodels

then:

> pip install numpy scipy ipython astropy numba cython
> pip install git+https://github.com/threeML/threeml.git  --upgrade
> pip install git+https://github.com/threeML/astromodels.git --upgrade

Note

If you do not have permission to install packages in your current python environment, you can still install the packages by adding the --user option at the end of each pip command.

Tips for Mac users

The following paths need to be added to you DYLD_LIBRARY path if you have FORTRAN installed via these package managers:

  • Homebrew: DYLD_LIBRARY_PATH=/usr/local/lib/gcc/<version number>:$DYLD_LIBRARY_PATH

  • Fink: DYLD_LIBRARY_PATH=/sw/lib/gcc<version number>/lib:$DYLD_LIBRARY_PATH

Please inform us if you have problems related to your FORTRAN distribution.