数据分析软件安装指南v2.02(中文)

Insight-HXMT用户数据分析软件安装指南[v2.02]  [pdf]

本文档分为以下几个部分:

一、安装前的准备

二、软件安装(macOS/Mac OS X、 Ubuntu Linux、Scientific Linux CERN (SLC) ) 

三、安装后的设置

四、标定数据库的安装

五、常见问题及解决办法

注:对安装有任何疑问,可通过网站helpdesk获得技术支持。 

 

有两种安装方式可供选择:

    1. 只安装HXMT用户分析软件。适用于单独安装HXMTDAS,没有安装HEASoft或不与已安装的HEASoft同时使用的用户;

    2. HEASoft 同时安装,可同步安装HEASoft软件包和HXMTDAS数据分析软件

(两种安装方法的优缺点和可能遇到的问题见第五部分“常见问题及解决办法”)。

 

 

一、安装前的准备

 

1.  硬件要求

  • 内存 > 4 G
  • 硬盘容量 > 5 G

2.  软件准备:

  • 下载HXMT用户数据分析软件v2.02源码安装包
  • 如果选择与HEASoft同时安装,还需下载HEASoft源码安装包
  • Python,软件兼容 Python 2.x,推荐使用 Python 3.x。需要安装以下Python 扩展模块:
    • argparse
    • astropy
    • collections
    • datetime
    • glob
    • matplotlib
    • numpy
    • os 
    • scipy
    • sys
    • time
    • xlrd
    • xlwt
  • Linux系统中需要预先安装一些必备的软件包。

        对于Ubuntu 用户,可执行以下安装命令

      • sudo apt-get -y install libreadline6-dev
      • sudo apt-get -y install libcurl4
      • sudo apt-get -y install libcurl4-gnutls-dev
      • sudo apt-get -y install libncurses5-dev
      • sudo apt-get -y install xorg-dev
      • sudo apt-get -y install gcc g++ gfortran
      • sudo apt-get -y install perl-modules
      • sudo apt-get -y install python3-dev

        对于Scientific Linux CERN (SLC)用户(或其他RedHat系的Linux发行版本),可以执行以下安装命令 

      • sudo yum -y install ncurses-devel
      • sudo yum -y install libcurl-devel
      • sudo yum -y install libXt-devel
      • sudo yum -y install readline6-devel
      • sudo yum -y install gcc gcc-c++
      • sudo yum -y install gcc gcc-gfortran
      • sudo yum -y install python-devel
      • sudo yum -y install make
      • sudo yum -y install perl-devel

         注1:安装这些软件包需要具备sudo或者root的权限。如果直接用root用户执行,需要去掉yum命令前的“sudo”

        注2:对于当前系统中已经安装的软件包,apt-get或yum会自动跳过。因此重复安装命令不会对系统产生影响。

 

二、软件安装

        我们提供两种安装方式(两种安装方法的优缺点和可能遇到的问题见第五章“常见问题及解决办法”):

    • 只安装HXMT用户分析软件。适用于单独安装HXMTDAS,没有安装HEASoft或不与已安装的HEASoft同时使用的用户;
    • HEASoft 同步安装。适用于同时使用HEASoft软件包和HXMTDAS数据分析软件的用户。

    1. 只安装HXMT用户分析软件

        (a) 解压源码包:

                gunzip hxmtsoftv2.02.tar.gz

                tar xvf hxmtsoftv2.02.tar

        (b) 安装前配置(configure)

                cd hxmtsoftv2.02/BUILD_DIR

                ./configure

           软件默认会安装到 /usr/local 路径下,因此需要管理员权限。我们建议将HXMT用户分析软件安装至当前用户拥有读、写权限的目录下,这样无需管理员权限也可安装,此时可以使用 --prefix参数指定安装路径(以/path/to/hxmtsoft/ 路径为例):

                ./configure --prefix=/path/to/hxmtsoft/

           如果配置(configure)这一步顺利通过,则可进行下一步编译,如果报错,请先排查错误后重新进行配置(常见错误见第五章“常见问题及解决办法”),直到配置成功才可进行下一步的编译。

        (c) 编译并安装

                make

                make install

            编译过程中可能遇到的问题见第五章“常见问题及解决办法”。如果显示Finished,或期间无Error信息出现,则表示已成功编译并安装软件

 

    2.   与 HEASoft同时安装

        (a) 下载并解压缩HEASoft软件包

          注意需要下载源码安装包。以6.26版本为例,假定解压缩后的安装文件位于/path/to/heasoft-6.26/

        (b) 下载并解压缩HXMT用户数据分析软件安装包

                gunzip hxmtsoftv2.02.tar.gz

                tar xvf hxmtsoftv2.02.tar

        (c) 在解压缩后得到的HXMT分析软件目录中,可以看到如下目录和文件:

                ls  hxmtsoftv2.02

                  BUILD_DIR           HEASOFT-INSTALL.TXT    attitude           ftools             heagen             heatools           tcltk         CMakeLists.txt        Release_Notes_6.26 demo               heacore             heasptools         hxmt

             将该目录下名为“hxmt”的目录项(从HXMT分析软件解压后的路径)拷贝(或移动)到HEASoft 源码目录中 

                cp -r   hxmtsoftv2.02/hxmt   /path/to/heasoft-6.26/

        (d) 修改HEASoft 中的configure文件

                cd /path/to/heasoft-6.26/BUILD_DIR

            使用你熟悉的文本编辑器,将该目录下的configure文件中的mpfit_required=no 修改为 mpfit_required=yes 

        (e) 配置(configure)

                ./configure --with-components="heacore tcltk external attitude heasptools heatools heagen demo ftools GSSC heasim Xspec integral maxi nicer nustar hitomi xmm glast suzaku swift hxmt"

        上述加粗的文字为HEASoft中已有的可供选择安装的各个卫星的模块(可以根据自己需要删减),在最后加入hxmt,即可以将HXMT用户分析软件与其他HEASoft模块一起安装。

        软件会安装到默认的路径下,因此需要管理员权限。我们建议将HXMT用户分析软件安装至当前用户拥有读、写权限的目录下,这样无需管理员权限也可安装,此时可以使用 --prefix参数指定安装路径(以/path/to/hxmtsoft/ 路径为例):

                ./configure --prefix=/path/to/hxmtsoft/  --with-components="heacore ...... hxmt"

           如果配置(configure)这一步顺利通过,则可进行下一步编译,如果报错,请先排查错误后重新进行配置(常见错误见第五章“常见问题及解决办法”),直到配置成功才可进行下一步的编译。

        (c) 编译并安装

                make

                make install            

        编译过程中可能遇到的问题见第五章“常见问题及解决办法”。如果显示Finished,或期间无Error信息出现,则表示已成功编译并安装软件

 

 

三、安装后的设置

        安装后需要设置环境变量

           对于使用C-Shell(csh,tcsh)的用户

                setenv HEADAS /path/to/hxmtsoft/(PLATFORM)

                source $HEADAS/headas-init.csh

          对于使用 Bourne-Shell(sh,ash,ksh,bash)的用户

                export HEADAS=/path/to/hxmtsoft/(PLATFORM)

                source $HEADAS/headas-init.sh

          不同的计算机的 (PLATFORM) 会有所不同,例如 PLATFORM 可能为 x86_64-apple-darwin18.5.0或者x86_64-pc-linux-gnu-libc2.12等类似形式。安装完成后,可在指定的安装路径下查看以“x86”开头的文件夹名称,并用该名称替换上述命令中的PLATFORM部分。

           注:在部分Linux操作系统中,安装后会出现两个 “x86”开头的文件夹(详见第五章”常见问题及解决办法”),需合并这两个文件夹。

 

四、标定数据库的安装

    在成功安装了HXMT用户数据分析软件后,还需安装及配置标定数据库CALDB。两种软件安装方式“只安装 HXMT 用户分析软件”和“与HEASoft同时安装”,对应的标定数据库的安装方式也略有区别。

    1. 只安装HXMT用户数据分析软件

        (a) 下载并解压缩HXMT标定数据库CALDB

            gunzip CALDB2.02.tar.gz

            tar xvf CALDB2.02.tar

        (b) 将标定数据库移动到用户指定的目录

            这一过程中,用户可以自己选择存放标定数据库的目录,我们建议移动到HXMTSoft安装后的目录下。下面以/path/to/caldb/为例)

            cp -r CALDB2.02 /path/to/caldb/

        (c) 设置标定数据库相关的环境变量

            对于使用cshtcsh的用户       

             setenv CALDB /path/to/caldb/CALDB2.02

            setenv CALDBCONF $CALDB/caldb.config

            setenv CALDBALIAS $CALDB/software/tools/alias_config.fits

            对于使用sh,ash,ksh,bash的用户

           export CALDB=/path/to/caldb/CALDB2.02

           export CALDBCONF=$CALDB/caldb.config

           export CALDBALIAS=$CALDB/software/tools/alias_config.fits

 

    2. 同时安装HXMT用户数据分析软件和HEASoft软件的用户

         (a) 下载并解压缩HEASoft软件标定数据库CALDB

            假定上述标定库已经解压缩至/path/to/caldb/目录下

        (b) 下载并解压缩HXMT标定数据库CALDB

            gunzip CALDB2.02.tar.gz

            tar xvf CALDB2.02.tar

        (c) 将HXMT标定数据库的内容拷贝(或移动)到HEASoft的CALDB目录中

            cp -r  CALDB2.02/data/hxmt  /path/to/caldb/CALDB/data/

        (d) 修改CALDB中的caldb.config文件

            需要修改HEASoft软件标定数据库CALDB中的caldb.config文件,将HXMT相关的内容添加到其中:

            cat CALDB2.02/caldb.config >> /path/to/caldb/CALDB/software/tools/caldb.config

        (e) 设置标定数据库相关的环境变量

            对于使用cshtcsh的用户

            setenv CALDB /path/to/caldb/CALDB

            setenv CALDBCONF $CALDB/software/tools/caldb.config

            setenv CALDBALIAS $CALDB/software/tools/alias_config.fits

            对于使用sh,ash,ksh,bash的用户

           export CALDB=/path/to/caldb/CALDB

           export CALDBCONF=$CALDB/software/tools/caldb.config

           export CALDBALIAS=$CALDB/software/tools/alias_config.fits

 

  

五、 常见问题及解决办法

 

     该部分列举了安装过程中常见的问题,如果用户在安装过程中遇到了其他问题,并无法解决,请通过网站helpdesk获得技术支持。

    1. 只安装HXMT分析软件”还是 “与HEASoft同时安装“?

    HXMT分析软件和HEASoft分析软件的框架是一致的,即可以单独安装HXMT分析软件,也可以将HXMT的软件打包至HEASoft,作为一部分进行安装。

    HXMT分析软件单独安装时,除了HXMT分析所需要的软件外,还包含少量ftools,例如fv, fselect等。不包括Xspec, Xronos 等。

    单独安装HXMT分析软件,优点是快捷,但可能存在的问题是,若你的本地已经装有HEASoft,则会在环境变量的设置上产生冲突(HEADAS变量和CALDB等变量名冲突)。你无法在同一个终端中既初始化HEASoft,也初始化HXMT(但你可以在不同终端分别初始化两个软件,分开使用)。

    与HEASoft同时安装,可以解决冲突的问题,在同一终端既使用HXMT分析软件,也使用HEASoft的软件。但请注意,HEASoft的安装源码建议为全新的、未编译安装过的安装源码包,如果利用本机已经安装过的HEASoft代码,在进行安装编译的过程中可能会出现各种编译错误。

 

    2. 为何需要预安装Python及Python模块?

    HXMT分析软件中的背景模块 (HXMTBKG) 会使用到Python的程序。所以你需要预先安装Python,并使用pip, conda等模块管理工具预先安装指定的模块。

 

    3. macOS 10.15: configure 过程中,“ configure: error: cannot run C compiled programs”

    macOS 10.14及以后的版本,g95不再支持,所以需要重新安装gcc8或gcc9,并在configure之前设置:

        export CC=/usr/local/gcc-9.2/bin/gcc-9.2

        export CXX=/usr/local/gcc-9.2/bin/g++-9.2

        export FC=/usr/local/gcc-9.2/bin/gfortran-9.2

    再重新进行配置

        ./configure

 

    4. make 过程中提示某 ”.o”文件无法执行。

    可能是遗留了一些之前编译的可执行文件。只需make clean (或make distclean),再执行 make

 

    5. 部分系统,安装后出现多个 “x86_”文件夹

    部分系统安装后,无任何报错,而在安装的路径下,会出现两个”x86“开头的文件夹。例如 :“x86_64-pc-linux-gnu-libc2.23”和 “x86_64-pc-linux-gnu-libc2.23-2”。两个文件夹下的内容,都为软件所需要的内容,我们需要将二者合并(保持文件夹结构不变,重复内容覆盖)。可使用如下命令:

        rsync -av --progress   x86_64-pc-linux-gnu-libc2.23-2/*   x86_64-pc-linux-gnu-libc2.23/

然后可删除 x86_64-pc-linux-gnu-libc2.23-2 文件夹

        rm -rf   x86_64-pc-linux-gnu-libc2.23-2

 

    6. make进行编译过程中报错,报错信息为:

  •     readline/lib/libreadline.so: undefined reference to 'tputs'
  •     readline/lib/libreadline.so: undefined reference to 'tgoto'
  •     readline/lib/libreadline.so: undefined reference to 'tgetflag'
  •     readline/lib/libreadline.so: undefined reference to 'UP'
  •     readline/lib/libreadline.so: undefined reference to 'tgetent'
  •     readline/lib/libreadline.so: undefined reference to 'tgetnum'
  •     readline/lib/libreadline.so: undefined reference to 'PC'
  •     readline/lib/libreadline.so: undefined reference to 'tgetstr'

    这可能是所依赖的库和软件未预安装导致的,在系统上安装 libreadline6-dev, libncurses5-dev,然后重新运行make进行编译。

例如在Ubuntu系统中可执行(不同系统命令不同,使用对等的安装命令即可):
        sudo apt-get –y install libreadline6-dev
        sudo apt-get –y install libncurses5-dev

在SLC系统中则执行:

        sudo yum –y install ncurses-devel
        sudo yum –y install readline-devel

 

    7. make进行编译过程中报错,报错信息为:

  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atRotVect'
  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atQuatToEuler'
  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atInterpolateEuler'
  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atNormVect'
  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atEulerToQuat'
  • /home/user/heasoft-6.24_hxmtsoft/hxmt/BLD/x86_64-pc-linux-gnu-libc2.23-0/lib/libhxmtlib.so: undefined reference to 'atQuatToRM'

    这是编译过程中未正确指定所需库导致的错误,在报错的编译指令后加入–latFunction3.3,手动编译该指令,成功后再重新运行make继续安装即可。如Ubuntu系统下,错误信息显示,安装程序在路径/path/hxmt/hxmtscreen/下,执行编译命令

        g++ -o hxmtscreen hxmtscreen.o ...... -lhxmtlib -lhxmtHElib -lhxmtMElib -lhxmtLElib -lhxmtHEmodule -lhxmtMEmodule -lhxmtLEmodule -lhxmttoolslib -lmpfit

    时报错。所以进入报错路径  /path/hxmt/hxmtscreen/,在上述命令后面加上 -laFunction3.3  重新编译:

         g++ -o hxmtscreen hxmtscreen.o ...... -lhxmtlib -lhxmtHElib -lhxmtMElib -lhxmtLElib -lhxmtHEmodule -lhxmtMEmodule -lhxmtLEmodule -lhxmttoolslib –lmpfit –laFunction3.3

    运行成功(无任何信息,无报错)后,回到最初的安装目录~/hxmtsoft/BUILD_DIR路径下重新运行make即可。

 

8. Mac下动态库报错,"dyld not loaded":

    MacOS系统下,成功执行make, make install无任何报错,但是运行hxmtsoft的命令,诸如hegtigen,出现错误信息:

  • dyld: Library not loaded: libhxmtHEmodule.dylib
  • Referenced from: /home/user/heasoft_hxmtsoft2/x86_64-apple-darwin17.7.0/bin/hegtigen
  • Reason: image not found

    这是由于安装后程序无法找到HEADAS所需的动态库,可通过手动指定动态库的路径解决。

    首先查看某一程序的动态库依赖(以hegtigen为例):
        otool –LD $HEADAS/bin/hegtigen
    显示结果为:
        libhxmtHEmodule.dylib (compatibility version 0.0.0, current version 0.0.0)
        libhxmtlib.dylib (compatibility version 0.0.0, current version 0.0.0)
        libhxmtHElib.dylib (compatibility version 0.0.0, current version 0.0.0)
        @rpath/libhdinit_2.7.dylib (compatibility version 0.0.0, current version 0.0.0)
        ......
    其中三个动态库libhxmtHEmodule.dylib, libhxmtlib.dylib, libhxmtHElib.dylib未指定动态路径,故程序无法找到该库。我们指定这三个的路径:
        install_name_tool -change libhxmtHEmodule.dylib $HEADAS/lib/libhxmtHEmodule.dylib $HEADAS/bin/hegtigen
        install_name_tool -change libhxmtlib.dylib $HEADAS/lib/libhxmtlib.dylib $HEADAS/bin/hegtigen
        install_name_tool -change libhxmtHElib.dylib $HEADAS/lib/libhxmtHElib.dylib $HEADAS/bin/hegtigen
    并将$HEADAS/lib该路径加入动态路径:
        install_name_tool -add_rpath "$HEADAS/lib" $HEADAS/bin/hegtigen