-
Notifications
You must be signed in to change notification settings - Fork 16
Installation Instructions
The current version of the Fermitools is 2.2.0 released on 06/21/2022.
Fermitools have migrated to Python 3. If you are updating a current installation of the tools it is necessary to perform a fresh installation in a new Python 3 environment. Running update on an existing Python 2 based installation has been known to cause problems.
As part of a major development cycle overhaul undertaken by the FSSC and the LAT team at SLAC the Fermitools (formally ScienceTools) are now distributed via the Conda package management system. This decision was made to improve the user experience by allowing Conda to handle the installation and setup of third-party dependencies thereby greatly reducing the library mismatch and version incompatibility errors that make up a significant percentage of technical bug reports. Migrating to Conda also simplifies the Fermitools release process and allows users to update the tools via a simple update command as opposed to re-installing the entire package. Fermitools via Conda will facilitate a quicker software patch/release cycle and a smoother user experience.
Once you have installed the Fermitools, you may want to check the FSSC's documentation for information about how to analyze Fermi data, including detailed tutorials.
If you have trouble with the installation, first check the troubleshooting page for possible solutions. If you continue to have problems please see the error reporting page for instructions on how to report the issue to the Fermitools team.
The Fermitools require a MacOS or Linux system.
We don't support Cygwin use with Microsoft Windows. However, we have had success using the Fermitools with the Windows Subsystem for Linux.
The FSSC has also created a Docker container that will run on Windows, MacOS, and Linux. It pre-loaded with the Fermitools and many other software packages useful for Fermi analysis (see Addtional Software for details). You can find it (with instructions) on github or Docker Hub.
The Fermitools and associated data files are distributed via precompiled packages which are hosted on an Anaconda Cloud channel. In order to obtain the Fermitools the Anaconda distribution of python first needs to be installed. Anaconda is distributed in two different formats: Anaconda and Miniconda. The FSSC recommends using Miniconda, as it is more lightweight, but either version will work.
Launch the downloaded installer and follow the instructions to install Anaconda on your system.
Note that if you are using csh or tcsh (you can echo $SHELL to check), you must append the following to your ~/.cshrc or ~/.tcshrc file:
source </path/to/conda>/etc/profile.d/conda.csh
where </path/to/conda> is replaced with the path to the top level directory of the Anaconda installation (typically named something like "Miniconda3"). The conda.csh script sourced in the above line will allow Conda environments to activate properly when run in (t)csh. You will need to re-source your .cshrc or .tcshrc file to ensure that the change takes effect in your current terminal session.
The Fermitools are hosted on an Anaconda Cloud channel maintained by the Fermi team. They can be downloaded and installed into their own Conda environment via the command:
conda create -n fermi -c conda-forge -c fermi fermitools numpy=1.20
This command will create a conda environment named fermi and will download/install precompiled binaries of the Fermitools and their dependencies into it. conda-forge and fermi are the names of the channels that host the software. Specifying, the numpy version is currently required to avoid a problem with deprecated data types (see Issue 143).
If the Fermitools do not install correctly this way, you can try the following commands:
conda install mamba -n base -c conda-forge
followed by
mamba create -n fermi -c conda-forge -c fermi fermitools numpy=1.20
Once this process is complete, use the following command to activate the environment:
conda activate fermi
This command will activate the fermi environment in your shell with the Fermitools setup and ready to go.
You may get warnings about having PYTHONPATH, LD_LIBRARY_PATH, or DYLD_LIBRARY_PATH set or about a version mismatch between CFITSIO headers. These warnings should not cause any issues with analysis. See Troubleshooting if you encounter problems.
To exit the fermi environment use the following command:
conda deactivate
You can determine what version you are using with the conda list fermi command.
You may want to install additional non-Fermitools software. See Additional Software below.
Standard conda update instructions DO NOT APPLY when updating from Fermitools 1.* to Fermitools 2.*. Fermitools 2.* must be installed in a new Python 3 environment. To perform this update follow the instructions below
To update your environment for use with Fermitools 2.0 take the following steps:
conda activate fermi-
conda env export > fermi_environment.yaml<- Copy this file to a directory for safekeeping. It is a backup of the old environment's configuration. conda deactivateconda env remove --name fermi-
conda create --name fermi -c conda-forge -c fermi fermitools
After the new environment is created, activate it and runconda list fermitoolsto verify that the update ran successfully.
To update an existing Fermitools installation simply activate the environment that the Fermitools are installed in (usually named fermi) and run the following update command:
conda update -c conda-forge -c fermi fermitools
This will grab and install the most recent compatible version of Fermitools from the fermi release channel. After updating re-activate the conda environment to ensure that any changes to the activation script are properly sourced.
conda activate fermi
To update the Fermitools data package to the latest version, run the following update command:
conda update -c conda-forge -c fermi fermitools-data
If you need to install a specific version of the Fermitools, you can specify the version by setting the name of the package equal to the version number, like so:
conda create -n fermi -c conda-forge -c fermi fermitools=<VERSION>
or
conda install -c conda-forge -c fermi fermitools=<VERSION>
Where <VERSION> is whatever version number you need to grab. Note that in order to obtain a specific version of the Fermitools in this manner it MUST be available in the fermi Anaconda Cloud channel.
For some older versions of the tools, you may also need to install specific versions of certain libraries. For instance, if you get an error trying to run the tools like "Library not loaded: @rpath/libCLHEP-2.4.4.1.dylib", you should try adding clhep=2.4.4.1 to the command line.
Note: You can only downgrade to a Fermitools version that is compatible with the python version you are running in your environment.
If for any reason you need to downgrade to an existing installation the tools that uses Python 3 to an earlier version, you can do so with the command
conda install -c conda-forge -c fermi fermitools=2.<version number>
where <version number> is replaced with the version you want to install. For example, if you wish to roll back to the very first Fermitools Python3 release you would use the command
conda install -c conda-forge -c fermi fermitools=2.0.0
You can't downgrade a Fermitools 2.X version to a 1.X version of the tools. If you wish to install a py2 (1.X) version of the tools, you will need to create a new environment (here named "fermi-py2"), e.g.,
conda create -n fermi-py2 -c conda-forge/label/cf201901 -c fermi fermitools=1.2.23
Note the 'cf201901' label is necessary.
To downgrade the Fermitools data package to a previous version, run the following command:
conda install -c fermi fermitools-data=<version number>
Where <version number> is replaced with the version you want to install. For example, if you wish to roll back to the very first Fermitools data release you would use the command
conda install -c fermi fermitools-data=0.13
If you wish, you can remove the Fermitools with the command:
conda remove --name fermi --all
If you want to remove conda completely, you will need to follow the instructions on Uninstalling Anaconda.
Depending on what type of analyses you want to do, you may want or need to install additional software that is not part of the Fermitools.
- Fermipy is a package built on the pyLikelihood interface of the Fermitools and provides a set of high-level tools for performing common analysis tasks.
- In order to use Jupyter notebooks, you will need to install the nb_conda package:
conda install nb_conda - The XML model editor GUI (called by the ModelEditor command) is dependent on the package pyds9. This package is available through the Space Telescope Science Institute's Astroconda Channel. In order to use the modeleditor package you will need to install pyds9 using the command
conda install -c https://ssb.stsci.edu/astroconda pyds9. Once the installation is complete, ModelEditor should start without a problem. - Many of the pulsar tools have been deprecated and removed from the Fermitools. They were not being used by the pulsar community and have not been well supported them for some time. The pulsar community instead uses tools like PINT, the fermi plugin for tempo2 and PRESTO. Please look into using those tools for pulsar analysis.
- make4FGLxml (formerly make4fgl.py) generates an XML model for a given region of interest from the 4FGL catalog.
- GSpec allows analysis of GBM data via a user-interactive GUI and additionally enables users to create their own Python scripts using the included libraries. It provides a seamless interface to XSPEC and allows users to define additional data reduction techniques, such as background fitting/estimation and data binning, as Python-based plugins.
The FermiBottle docker container is pre-loaded with many of the software packages listed above. It includes the Fermitools, Fermipy, the HEASARC FTOOLS, pulsar analysis tools, GSpec, Python 2.7 and associated libraries along with a host of other programs.
The FSSC's User Contributed Software page contains software developed by the scientific community that may be useful. While the FSSC hosts this page and coordinates with developers, maintaining and updating the tool or script remains the responsibility of the developer. If you have questions about software there or would like to make a contribution, please email the FSSC's help desk.
Note that if you install any extra software into the fermi environment via conda install it will be isolated to this environment. For more information, please read the Conda documentation on managing environments.