HEASoft Wrapper Utility

Users may run into problems when using HEASOFT in the same session as other related software systems such as CIAO or XMM-SAS. These issues usually stem from library conflicts, for example:

    xspec is typically linked to /usr/lib/libstdc++.so.6, but when the XMM-SAS software is initialized, a users' LD_LIBRARY_PATH will be changed to put XMM-SAS directories ahead of everything else (including /usr/lib), such that xspec - when looking for libstdc++.so.6 at runtime - will find the xmmsasYYYYMMDD_HHMM/libextra/libstdc++.so.6 instead of the one in /usr/lib.

    When these libraries differ significantly, xspec may fail with errors complaining that the libstdc++.so.6 it located is the wrong GLIBCXX version. Other compiler libraries (libgfortran, libgcc_s) included in the XMM-SAS may create similar conflicts.

    Traditionally the recommendation is made to either run HEASOFT and XMM-SAS in separate sessions (which is not ideal) or to perform the XMM-SAS setup first and then put /usr/lib back at the head of LD_LIBRARY_PATH (though this will likely then break the SAS tasks).

Other common problems are the use in both HEASoft and XMM-SAS of the PGPLOT_FONT variable which will point to different locations in each system, and the use in both HEASoft and CIAO of the PFILES variable.

In an effort to protect HEASoft tasks from these kinds of issues, we have created a script ("hwrap") which provides an alternate runtime environment in which an invoked task is just a wrapper to the real task, and in which the environment is set and exported correctly for HEASoft tasks only.

Once hwrap is run, a user only needs to add the directory it creates to their PATH to gain command-line access to all of their installed HEASoft tasks, necessarily skipping the traditional HEASoft setup in which the HEADAS variable is set and the "headas-init" script is sourced.

How it works:

  • Install HEASoft, skipping the final initialization step in the installation guide (Linux or macOS). Below we will refer to the standard $HEADAS location but neither this nor any other HEASoft-related variables need to be set in the environment.

  • Download and run the hwrap script:
    
      hwrap <location of installed HEASoft> <destination directory (optional)>
    
    For example:
    
      hwrap /path/to/heasoft-6.34/x86_64-pc-linux-gnu-libc2.35
    
    or
    
      hwrap /path/to/heasoft-6.34/x86_64-pc-linux-gnu-libc2.35 /path/to/heasoft-6.34/
    
    The required first argument is the location of a HEASoft installation (i.e. what would typically be defined as HEADAS). An optional second argument may be provided to specify the destination, a directory under which a new output directory heasoft_wrap will be created to contain the new wrappers to the HEASoft tasks. By default this will be made a subdirectory of the path specified in the first argument.

    When run, hwrap will create heasoft_wrap in the destination directory, and will populate it with symbolic links for each of the tasks it finds in what would be the standard $HEADAS/bin directory. Each symbolic link will have the name of an existing task in $HEADAS/bin, but all will point to a wrapper script which sets up the standard HEADAS environment and then executes the task that was invoked.

    For example, when heasoft_wrap/ftlist is invoked, the script wraps to the 'real' ftlist: first performing the usual HEASoft initialization and then invoking the ftlist binary in $HEADAS/bin with any command-line arguments passed along.

    If not placed under the default destination or an existing version-numbered directory (e.g. heasoft-6.34 in the second example above), users may wish to rename the heasoft_wrap directory, for instance to denote its connection to a specific HEASoft version, e.g. "heasoft_wrap_6.34".

  • Add the new heasoft_wrap directory to PATH, for example:
          C shell (csh/tcsh):
    
            setenv PATH "/path/to/my/heasoft_wrap:$PATH"
    
          Bourne shell (sh/bash):
    
            export PATH="/path/to/my/heasoft_wrap:$PATH"
    
    
    Users who have the traditional headas setup hard-coded in their .login / .cshrc / .bashrc / etc. should either remove that old setup (recommended, as leaving it in would essentially defeat the purpose of doing all this) or make sure to prepend this new directory to their PATH as above.

    Users of XMM-SAS will note that the SAS setup script (setsas.csh) requires that you have the LHEASOFT variable set before allowing you to initialize the SAS, but this is only to ensure that the SAS has access to HEASOFT tasks ('fkeyprint', etc.), so when using the wrapper method suggested here, users may safely set the LHEASOFT variable to any placeholder string they like, for example:

          C shell (csh/tcsh):
    
            setenv LHEASOFT none
    
          Bourne shell (sh/bash):
    
            export LHEASOFT=none
    
    

    Note once again that no changes are made to the current working environment in this process, and no environment variables other than PATH need to be changed in order to use HEASoft.

Notes:
  • While hwrap does prevent certain kinds of conflicts, users should be mindful that some utilities are duplicated in these systems, e.g. the parameter file utilities (pget, pset, plist, punlearn, pquery) exist in both HEASoft and CIAO.

  • For users of the Xspec Python module: A task named pyxspec will be created which wraps to "python" (which is assumed to be in the users' PATH) and exports the environment variables necessary for accessing the Xspec Python module.

  • For batch mode processing or scripting HEASOFT tasks: If a user prefers to override the standard "local" part of the PFILES variable ($HOME/pfiles by default), they may set an environment variable "HEADAS_LOC_PFILES" prior to running a task, and that variable will be used to define the "local" part of the exported PFILES variable, i.e. one will effectively have:
    
            PFILES="$HEADAS_LOC_PFILES;$HEADAS/syspfiles"
    
    

    HEASoft / FTOOLS Help Desk

    If FTOOLS has been useful in your research, please reference this site (https://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

    Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

    Web page maintained by: Bryan K. Irby


    HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

    Last modified: Thursday, 22-Aug-2024 15:36:03 EDT