*********Installing HXMTsoftV2.05 with HEASoft - Ubuntu (/Debian based Linux)***********
******************************************************************
This document is a guide to installing HXMTsoftV2.05 with HEASOFT6.29 from the source code, available for download at:
HEASoft(https://heasarc.gsfc.nasa.gov/lheasoft/download.html)
HXMTsoft(http://hxmtweb.ihep.ac.cn/software.jhtml)
HEASOFT is the generalized term for the full set of software distributed from the HEASARC, incorporating all of the newly-developed software in the HEADAS environment (e.g. NICER) as well as all of the legacy HEASARC software (FTOOLS, XANADU, XSTAR, etc.).
***********************Contact Information**********************
* For more information, please see:
http://hxmtweb.ihep.ac.cn/software.jhtml
https://heasarc.gsfc.nasa.gov/ftools (FTOOLS)
https://heasarc.gsfc.nasa.gov/xanadu (XSPEC, XIMAGE, XRONOS)
https://heasarc.gsfc.nasa.gov/ftools/fv (FV)
*For this document, please contact:
buqc@ihep.ac.cn
****************************************************************
>SOURCE CODE INSTALLATION (Recommended):
Installations from the source code are recommended over the pre-compiled binaries due to the lack of portability of pre-compiled Perl libraries and other potential portability issues. Note that installations from the source code distribution are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).
The instructions below assume that you have already acquired HEASoft(https://heasarc.gsfc.nasa.gov/lheasoft/download.html) and HXMTsoft(http://hxmtweb.ihep.ac.cn/software.jhtml) tar files and have unpacked them (using e.g. "tar zxf [tar file]") on your machine.
The selected location for installation should have a space of more than 50 GB, and is highly recommended to choose a different location from your source files!
*****************************************************************
1. Prerequisite packages:
If they aren't installed already, you will need to install (using the "apt-get" package manager) a few other packages which are needed in order to build HEASoft from the source code distribution:
$ sudo apt-get -y install libreadline-dev
$ sudo apt-get -y install libncurses5-dev
$ sudo apt-get -y install ncurses-dev
$ sudo apt-get -y install curl
$ sudo apt-get -y install libcurl4
$ sudo apt-get -y install libcurl4-gnutls-dev
$ sudo apt-get -y install xorg-dev
$ sudo apt-get -y install make
$ sudo apt-get -y install gcc g++ gfortran
$ sudo apt-get -y install perl-modules
$ sudo apt-get -y install python3-dev [or python-dev]
$ sudo apt-get -y install numpy [only needed for the HEASP Python interface]
>Install anaconda3:
Download the latest "Anaconda installer for Linux" from https://www.anaconda.com/products/individual#linux, for example,
$cd ~/Downloads
$wget https://repo.anaconda.com/archive/Anaconda3-2021.11-Linux-x86_64.sh
$bash Anaconda3-***-Linux-x86_64.sh
>Install Python modules: astropy numpy matplotlib time scipy argparse xlrd xlwt
$conda install astropy numpy matplotlib time scipy argparse xlrd xlwt
2. Building the software:
Copy the hxmt/ folder under hxmtsoftv2.05/ to heasoft-6.29/
$cp -r hxmtsoftv2.05/hxmt heasoft-6.29/.
Edit the 'configure' file (use vim or gedit) under the heasoft-6.29/BUILD_DIR/, and change 'mpfit_required=no’ to ‘mpfit_required=yes’ and save.
$cd heasoft-6.29/BUILD_DIR/
$gedit configure &
After installing the prerequisite packages above, most users should just follow the basic GNU-like build procedure outlined in the HEASoft installation guide, i.e.:
Make sure that the configure script will choose the correct set of compatible compilers for the build, for example, In Bourne shell variants (bash/sh/zsh), use the entire gcc@11 package::
$export CXX=$(which gcc-11)
$export CXX=$(which g++-11)
$export FC=$(which gfortran-11)
$export PERL=$(which perl)
$export PYTHON=$(which python3)
$export PATH="/usr/bin:$PATH"
****NOTE, the version of C-libraries (Here I use 11 on my machine) could be different on your machine, change to the number your own version by checking "gcc --version"****
External packages (e.g. Anaconda) may set compiler flags in the environment which can break a HEASoft build, so users are also advised to unset all "FLAGS" variables:
$unset CFLAGS CXXFLAGS FFLAGS LDFLAGS
Next, configure and build the software:
$./configure --prefix=/path/to/selected/location/for/installation --with-components="heacore tcltk attitude heasptools heatools heagen demo swift Xspec integral maxi nicer nustar ftools heasim hxmt"
$make
$sudo make install
Note that you should let each step finish before proceeding to the next. The installation guide contains descriptions of optional configuration flags that more advanced users may wish to utilize.
****Lastly, please also note that the compiler settings described above will NOT pass to a sudo shell, so if you want to install HEASoft in a location which requires su write privileges, we recommend that you configure and build the software in a location writeable by you, and only when doing the final install step should you use sudo ***
3. Initialization:
For users of Bourne Shell (sh, ash, ksh, bash, zsh):
$sudo gedit ~/.bashrc
Attach the following lines to the ~/.bashrc file:
export HEADAS=/path/to/your/installed/heasoft-6.29/(PLATFORM)
source $HEADAS/headas-init.sh
$source ~/.bashrc
***********Installing HXMTsoft with HEASoft - MacOS(intel) *****************
>SOURCE CODE INSTALLATION:
Installations from the source code are generally recommended over the pre-compiled binaries to avoid any potential portability issues. Note also that source code builds are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).
The instructions below assume that you have already acquired a HEASoft and HXMTsoft tar files and have unpacked them (using e.g. "tar zxf [tar file]") on your machine.
1. Prerequisite packages:
In order to build HEASoft from the source code distribution, you will need some additional software:
>X11: We recommend XQuartz but X11 is also available via the various Mac package managers.
>Apple XCode: Before attempting to install any of the third-party compiler suites below, you will need to install the Apple XCode Command Line Tools (CLT) and make sure that they are up-to-date with your OS:
$xcode-select --install
>Compilers: Use a complete set of third-party compilers, i.e. C, C++, and Fortran. Multiple options are available via Mac package managers such as those listed below.
Homebrew
Use for example the entire gcc@11 package:
$brew install gcc
NOTE: For the M1/ARM architecture, you must use the Rosetta2 Intel binary translation to install your Homebrew compilers for use with HEASoft, see https://heasarc.gsfc.nasa.gov/lheasoft/macos.html#SOURCE.
>Install anaconda3:
Download the latest "Anaconda installer for MacOS" from https://www.anaconda.com/products/individual#macos, for example:
$cd ~/Downloads
$wget https://repo.anaconda.com/archive/Anaconda3-2021.1-MacOSX-x86_64.sh
$bash Anaconda3-2021.1-MacOSX-x86_64.sh
>Install Python modules: astropy numpy matplotlib time scipy argparse xlrd xlwt
$conda install astropy numpy matplotlib time scipy argparse xlrd xlwt
2. Building the software:
Copy the hxmt/ folder under hxmtsoftvxx/ to heasoft-6.xx/
$cp -r hxmtsoftv2.05/hxmt heasoft-6.29/.
Edit the 'configure' file (use vim or open) under the heasoft-6.**/BUILD_DIR/ and change 'mpfit_required=no’ to ‘mpfit_required=yes’ and save.
$cd heasoft-6.29/BUILD_DIR/
$open configure
After installing the prerequisite packages above, most users should just follow the basic GNU-like build procedure outlined in the HEASoft installation guide, i.e.:
As described above - make sure that the configure script will choose the correct set of compatible compilers for the build, use for example the entire gcc@11 package::
In Bourne shell variants (bash/sh/zsh):
$ export CC=$(which gcc-11)
$ export CXX=$(which g++-11)
$ export FC=$(which gfortran-11)
$ export PERL=$(which perl)
$ export PYTHON=$which python3$
****NOTE, the version of C-libraries (Here I use @11 on my machine) could be different on your machine, change to the number your own version by checking "gcc --version"***
Users are also advised to put /usr/bin ahead of other paths (such as those used by MacPorts, Anaconda, etc.) in their PATH in order to avoid potential errors.
$ export PATH="/usr/bin:$PATH"
External packages (e.g. Anaconda) may set compiler flags in the environment which can break a HEASoft build, so users are advised to unset all "FLAGS" variables:
$ unset CFLAGS CXXFLAGS FFLAGS LDFLAGS
Next, configure and build the software:
$./configure --prefix=/path/to/selected/location/for/installation --with-components="heacore tcltk attitude heasptools heatools heagen demo swift Xspec integral maxi nicer nustar ftools heasim hxmt"
$make
$sudo make install
Note that you should let each step finish before proceeding to the next. The installation guide contains descriptions of optional configuration flags that more advanced users may wish to utilize.
**Lastly, please also note that the compiler settings described above will NOT pass to a sudo shell, so if you want to install HEASoft in a location which requires su write privileges, we recommend that you configure and build the software in a location writeable by you, and only when doing the final install step should you use sudo***
3. Initialization:
To initialize the software, add the following lines to your ~/.bash_profile(or ~/.zshrc):
>For users of Bourne Shell (sh, ash, ksh, bash, zsh):
export HEADAS=/path/to/your/installed/heasoft-6.29/(PLATFORM)
source $HEADAS/headas-init.sh
********Calibration database (CALDB) Installation********************
This document describes the steps required to install and build a local Calibration Database (CALDB) system: construction of the filesystem, transfer of the desired calibration files from the HXMT and HEASARC calibration database and installation of the calibration files into the `Calibration Index Files' (CIFs).
**************************************************************************
1.Setting up the CALDB Environment
If you already have a CALDB defined in your machine, please skip to step 2.
>Define the environment variable $CALDB to point to the directory where the calibration data will be located (we'll call this the top-level CALDB directory). For example, if the CALDB is being installed under the directory /opt/caldb you need to define the $CALDB environment variable as:
$export CALDB=/opt/caldb
>Downloading and Installing CALDB setup files
Change your current working directory to $CALDB and download the file https://heasarc.gsfc.nasa.gov/FTP/caldb/software/tools/caldb_setup_files.tar.Z either using your web browser or using a download utility like wget or curl. Then uncompress and untar the file in your $CALDB directory. For example:
$cd $CALDB
$wget https://heasarc.gsfc.nasa.gov/FTP/caldb/software/tools/caldb_setup_files.tar.Z
$tar -zxvf caldb_setup_files.tar.Z
This will create two $CALDB configuration files, which are:
$CALDB/software/tools/alias_config.fits
$CALDB/software/tools/caldb.config
and a CALDB initialization file, $CALDB/software/tools/caldbinit.csh (for unix C-shell users) or $CALDB/software/tools/caldbinit.sh (for unix Bourne shell users).
Open the appropriate intialization file (caldbinit.csh or caldbinit.sh, depending respectively on whether you are using C-shell or Bourne shell) in an editor (like vim or gedit for example), and edit the definition of the $CALDB environment variable to point to your top-level CALDB directory. In our example the first line of caldbinit.sh should read:
export CALDB=/opt/caldb
>CALDB Setup
Before accessing calibration data (using the HEAsoft analysis tools, for example) you need to set up the CALDB environment variables by sourcing the appropriate CALDB initialization file:
$source $CALDB/software/tools/caldbinit.sh
for B-shell users, for example. If you include this line in your ~/.bashrc file, then the CALDB will be available to you every time you log in.
2. Downloading and Installing CALDB Calibration Data from the HXMT CALDB
This section describes how to download calibration data from the HXMT website, and how to store the data so the CALDB software tools can access it.
$cd $CALDB
$wget http://hxmtweb.ihep.ac.cn/u/cms/www/202201/CALDB2.06.tar.gz
$tar -xvf CALDB2.06.tar.gz
$cat CALDB2.06/caldb.config >> $CALDB/software/tools/caldb.config
$rm CALDB2.06.tar.gz
$cp -r CALDB2.06/data/hxmt ./data/
Run the FTOOL caldbinfo to check that your installation for this mission and instrument is correct. Use the command-line syntax
$caldbinfo INST HXMT LE
... using gpcaldbinfo 1.0.0
** caldbinfo 1.0.2
... using infocaldb 1.0.1
...... environ-var/logical CALDB defined
......... CALDB path = /opt/CALDB
... environ-var/logical CALDBCONFIG defined
... CALDBCONFIG file = /opt/CALDB/software/tools/caldb.config
...... environ-var/logical CALDBALIAS defined
......... CALDBALIAS file = /opt/CALDB/software/tools/alias_config.fits
...... CALDB is configured for the LE instrument onboard HXMT
......... Cal Index File: /opt/CALDB/data/hxmt/le/caldb.indx
......... Instrument directory: /opt/CALDB/data/hxmt/le
... CALDB appears to be set-up & accessible
** caldbinfo 1.0.2 completed successfully
3. Including HEASARC-Supported Missions in your CALDB
This section is for users who have set up the CALDB structure as described above, and who want to add their own missions and instruments to their CALDB.
>Change directory to $CALDB. If you haven't defined the environment variable $CALDB, you should do so, as specified above.
$cd $CALDB
For each < mission > / < instrument > combination (for example the nicer/xti) download the tar files listed on https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_supported_missions.html. CALDB tar files are usually single files of the form
goodfiles_<mission>_<instrument>_tar.Z
Although this single file may be split into multiple compressed tar files if the total volume of calibration files is large (typically more than a few gigabytes). You should refer to the CALDB Supported Mission web page, https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_supported_missions.html, for the list of CALDB tar files for each mission and instrument.
You can download the tar files via web access from https://heasarc.gsfc.nasa.gov/FTP/caldb/data. For example, if you want to install the CALDB for the NICER XTI, you should download the file /caldb/data/nicer/xti/
>Uncompress and untar each tar file you downloaded to $CALDB. This will create the
$CALDB/data/< mission>/< instrument>
directory tree. For example:
$ cd $CALDB
$ tar -zxvf goodfiles_nicer_xti.tar.gz
$ tar -zxvf goodfiles_nicer_xti_*.tar.gz
$ rm -i goodfiles_nicer_*.tar.gz
This will create the CALDB directory structure for each mission and instrument with the currently-available calibration data
>Run the FTOOL caldbinfo to check that your installation for this mission and instrument is correct. Use the command-line syntax
$caldbinfo INST NICER XTI
... using gpcaldbinfo 1.0.0
** caldbinfo 1.0.2
... using infocaldb 1.0.1
...... environ-var/logical CALDB defined
......... CALDB path = /opt/CALDB
... environ-var/logical CALDBCONFIG defined
... CALDBCONFIG file = /opt/CALDB/software/tools/caldb.config
...... environ-var/logical CALDBALIAS defined
......... CALDBALIAS file = /opt/CALDB/software/tools/alias_config.fits
...... CALDB is configured for the XTI instrument onboard NICER
......... Cal Index File: /opt/CALDB/data/nicer/xti/caldb.indx
......... Instrument directory: /opt/CALDB/data/nicer/xti
... CALDB appears to be set-up & accessible
** caldbinfo 1.0.2 completed successfully
-------------------------------------------------------------------