Release Notes for HEAsoft 5.2

June 18, 2002

                                   SUMMARY

HEASOFT 5.2 is a software suite consisting of FTOOLS 5.2, FV 3.1,
XIMAGE 4.1, XRONOS 5.19, XSPEC 11.2, and XSTAR 2.1h. This document
contains notes about significant changes made since the last major
release of each.  All this software shares common build, installation
and initialization procedures. Please see the files README.Q-AND-A,
README.USERS, INSTALL.SOURCE and/or INSTALL.BINARY for details.

For each of the HEASOFT subpackages below are listed tools and/or
features which are new in version 5.2. More information on FTOOLS 5.2,
XIMAGE 4.1, XRONOS 5.19, XSPEC 11.2, and XSTAR 2.1h can be obtained
using the fhelp utility.  Type "fhelp ftools" to obtain a full listing
of all the tools available, or "fhelp " to list all
of the tools in a particular subpackage, e.g., "fhelp asca".  Finally,
type "fhelp " for more detailed help on a particular tool.
FV 3.1, XIMAGE 4.1, and XSPEC 11.2 all have online help available from
within the program.  In addition, XIMAGE 4.1, XSPEC 11.2, and XSTAR 2.1h
have TeX formatted manuals for their usage.

Over the past year, many of the tools within HEAsoft began to exhibit
problems under newer versions of Linux operating systems.  These problems -
which were generally caused by uninitialized variables - were addressed
in the intermediate HEAsoft release 5.1A by use of the "finit-local-zero"
compiler flag.  An attempt was made by LHEA staff to track down and do proper
initializations in all of the code with HEAsoft, such that in HEAsoft 5.2,
this flag (which, while preventing these uninitialized variable problems,
also inflates the size of the resultant binaries) is no longer used.

HEASOFT v5.2 contains new versions of tcl/tk (8.3.4) and readline (4.2a),
and also new in this release is support for builds on the Macintosh OS X
platform.


******************************************************************************
                                   ATTITUDE
******************************************************************************

draw_teldef:

 - New task which produces a PostScript plot of coordinates described
   by a teldef calibration file.

aspect:

 - Fixed bug which caused the tool to hang if the nominal pointing was
   outside the initial bin structure.

coordinator:

 - Removed machine dependence in the way random numbers were generated.
   Added support for the SKY_FROM teldef keyword.

libcoordfits:

 - Updated the teldef file format to reflect the latest "official" version:
   See http://adfwww.gsfc.nasa.gov/swift/teldef_doc/teldef.html


******************************************************************************
                                    ASCA
******************************************************************************

Content Update:

* ascaray: Change default 'goldens' parameter to 18.5 g/cc, reflecting
        our current calibration, instead of 19.3, the bulk density.
        The use of the higher density value will result in an overestimate
        of the high energy effective area.

Bug Fixes:

* We have identified and fixed many "uninitialized variable" problems
  in ASCA tools (they only affected the Linux versions).  In particular,
  ascalin is now believed to behave correctly on Linux machines.
  Faint, sispi, mkgisbgd, and mkdtime were also affected by this bug
  (when these tools failed on Linux machines, they failed in obvious
  ways, as far as we are aware).

* fmosaic: fixed a bug so it will run on Solaris.

* ascaeffmap: Fixed a bug in calculation of the SIS efficiency from
  the RMF.


******************************************************************************
                                   CALLIB
******************************************************************************

- Fix typo that caused rdpha2 to ignore a BACKSCAL column.
- Added support for HDUVERS=2 WMAPs
- Fixed problems in shellig.f which caused build errors and occasional seg
  faults.
- Update to wtpha1.f to handle undef value for COUNTS.

******************************************************************************
                                  CALTOOLS
******************************************************************************

chkrmf:

- Fixed bug which caused errors if the first input RMF did not have the
  largest number of response elements. Also changed amount of memory
  grabbed for the accumulated response to be 10 times the input rather
  than number of files times the input. This should be enough and should
  avoid out of memory problems when adding many files.


******************************************************************************
                                   CFITSIO
******************************************************************************

CFITSIO library changes that globally affect all FTOOLS tasks:
  
- Most tasks can now write 'gzipped' compressed output FITS files if
  the specified name of the file ends with the characters ".gz".  CFITSIO
  will initially create the uncompressed FITS file in memory.  When the
  FITS file is closed, CFITSIO will compress the file and write it out to
  disk.

- The syntax for on-the-fly column filtering when using CFITSIO's
  virtual file name syntax has been modified so that if one specifies a
  list of column names, then only those columns will be copied into the
  virtual file.  This provides a simple way to make a copy of a table
  containing only a specified list of columns.  If the column specifier
  explicitly deletes a column, however, than all the other columns will
  be copied to the virtual file, regardless of whether the columns
  were listed or not. Examples:
  
        mytable.fit[1][col Time;Rate]  - only the Time and Rate
        columns will exist in the virtual input table.

        mytable.fit[1][col -Time ] - all but the Time column will be
        present in the virtual input file.

- Tasks that delete or modify values in FITS binary tables containing
  variable length vector columns (where the data are stored in the
  'heap') now operate more efficiently.  Any unused space in the heap
  will be recovered, thus producing smaller output FITS files.

- Most tasks that read or write FITS images now support a new "tile
  compressed" FITS image format.  In this format, the image is divided up
  into a rectangular grid of tiles, and each tile of pixels is compressed
  individually and stored in a row of a variable-length array column in a
  binary table.  Users can force the output FITS images to be written in
  tile-compressed format by using a new extended filename syntax.
  Examples: "myimage.fits[compress]" will use the default compression
  parameters, and "myimage.fits[compress GZIP 100,100]" will use the GZIP
  compression algorithm with 100 x 100 pixel tiles.
  
- Most tasks now provide at least limited support for FITS files
  containing 64-bit integer data values.  These non-standard FITS files
  have BITPIX = 64 or TFORMn = 'K'.  Some ftools tasks may truncate the
  values to the range of 32-bit integers, however.

- The standard COMMENT keywords that are written at the beginning of
  every FITS file have been modified to refer to the newly published FITS
  Standard document in Astronomy and Astrophysics.  Because of this
  change, any FITS file created with this release of FTOOLS will not be
  identical to the same file written with a previous version.


******************************************************************************
                                    FHELP
******************************************************************************

- Added support for CIAO and SAS help utilities.

******************************************************************************
                                   FIMAGE
******************************************************************************

fimgmerge:

- Fixed bug which caused failure when running fimgmerge as
  fimgerge   


******************************************************************************
                                   FUTILS
******************************************************************************

fcreate:

- Revised algorithm to handle very wide tables, where a single row of
  FITS table values are wrapped around onto multiple rows of the ASCII
  template file.

fdiff:

- If there are more than one keywords that are same, sort them in ascending
  order of keyword position in the header.

fmemsort:

- Added cyclical sort function.

fverify:

- Fixed prototype call error: fverify had passed a regular long instead of
  a 64-bit long long on supported platforms, giving a faulty move (to zero).
  fverify reported an extraneous-byte error in every file as a result.


******************************************************************************
                                     GRO
******************************************************************************

barytime:

- This is a first release of barytime, which is based on the program of the
  same name originally developed by the EGRET Instrument team. This routine 
  reads EGRET event files, performs user-selected cuts on photon direction,  
  energy  and  quality  screening  parameters, and produces an output list with 
  a column  containing  the solar-system barycenter  corrected photon arrival 
  times. Its use requires several auxiliary files containing spacecraft pointing
  and orbital parameters (as detailed in the documentation). 

  The input/output event files are typically ~10 Mb, so a few 10's of Mb 
  free disk space are required. A minimum of 12Mb is recommended.

bcmppha:

- The major change for LHEASOFT version 5.2 is the addition of an interactive
  graphics capability.  This allows the user to perform the data selections
  for source and background data segments with an interactive cursor.
  Alternatively, one can make a printable copy (Postscript, gif, etc.), then
  re-run  the program making data selection cuts in the parameter file as
  in the previous version. The option to list the time history digitally,
  as ascii output, is also retained as in the previous version. The graphics
  are based on the PGPLOT package (distributed with FTOOLS). The default
  environment for the interactive graphics support is X-windows.

  Data and output directory paths can now be specified in the parameter file
  (datadir, outputdir) to conform with other CGRO analysis utilities.

bod2pha:

- This is a re-release of bod2pha. The input options have been modified relative
  to previous versions to facilitate ease of use. The user may now input a
  CGRO Viewing Period number instead of start and stop times in truncated
  Julian days, although this latter option is still supported. 

  Data and output directory paths can now be specified in the parameter file
  (datadir, outputdir) to conform with other CGRO analysis utilities.

bod2rmf:

- This is a re-release of a previous version.  In the current version, the
  Fortran structures  previously used, that prevented bodrmf from compiling
  on Linux or Dec have been replaced with arrays. The code has now been ported
  to these platforms as well as to Macintosh OS X. In addition, the input
  options have modifed to faclitate ease of use. The user may now input a
  CGRO Viewing Period number, instead of start and stop times, plus the
  spacecraft X- and Z- axis coordinates (the old input option, i.e. entering
  each of these fields individually is still supported).

  Data and output directory paths can now be specified in the parameter file
  (datadir, outputdir) to conform with other CGRO analysis utilities.

bodfluxhis:

- This is the first release of this utility. Its purpose is to read and
  manipulate light curve data from the BATSE Earth occultation summary files.
  It can display data to screen, printable graphics files, ascii files, or
  simple FITS formatted data files. System requirements to run bodfluxhis are
  minimal. The software has been tested on linux, digital unix (OSF), solaris,
  and Mac OS X.

eaddmap:

- This is a re-release of a previous version. A minor change was made to
  accommodate a revision in some FITS header keywords. Specficially, the
  "RA" and "DEC" keywords in the EGRET database  were changed to "RA-CAR"
  and "DEC-CAR" in order to facilitate the overplotting (using tools such
  as FV) of EGRET skymaps with maps generated (by other instrument data) in
  different coordinate systems. Eaddmap now works with the revised FITS files.

emapgen:

- A deficiency was discovered in an earlier version. The start and end time
  specifications for the desired data interval (and output map) must be equal
  to, or be bracketed by the start and end times of the input file (Viewing
  Period Event Data File).  This is now made clear in the documentation, and
  in comment fields added to the parameter file. 

intmap:

- This is the first release under FTOOLS/HEAsoft. Intmap is based on the
  program of the same name developed by the EGRET Instrument team. The
  "XView" interface of the original program has been replaced with the
  standard parameter file interface, and the calibration database files
  (energy dispersion, sensitive area, and point spread files) are implemented
  as FITS files. 

  The program is computationally intensive. Recommended system requirements
  are 256 Mb memory and about 150 Mb of scratch disk space for temporary
  files.  Intmap has been sucessfuly built and tested on Linux and Solaris.
  The port to digital unix (OSF 4.0) was problematic, and use of this program
  on DEC systems is not recommended. Similarly, the port to Macintosh OS X
  was unsucessful.  Mac OS X support will be addressed in a future release,
  but support for DEC OSF is uncertain.

like:

- This is the first release of the FTOOLS version of the EGRET Instrument Team 
  maximum-likelihood point-source detection and flux determination program
  "like".  The interactive (command-line driven) portions of the program meant
  to be as similar as possible to the original program. The architecture-
  dependent binary calibration files have been replaced with FITS files, which
  are available from the CGRO public data archive. The initial setup phase of
  the program is now accomplished through the FTOOLS parameter file interface,
  and the required environment settings are also specified there. The program
  requires a substantial amount of memory (recommended 256 Mb or more) to run
  efficiently, and a scratch disk space of several hundred Mb is also required
  for temporary files. 

  Like was developed under Linux, and has been successfully ported to and
  tested on Sun OS and the Mac OS X (Darwin). The port to DEC (Digital Unix
  OSF) was unsuccessful at the time of this release.

specmat:

- This is the first release of specmat, which is based on the EGRET Instrument
  team "spectral" program. It is used to construct an approximate detector
  count spectrum, and accompanying instrumental response matrix for an EGRET
  point (or compact extended) source determination. The spectra is output into
  an PHA type FITS file, which can be used by XSPEC, and manipulated by other
  HEASARC utilities. Similarly, the response matrix is written in RMF format.
  Specmat takes as input an ascii table produced by the relate program "like".
  Specmat is not a resource intensive program, and can be used on minimally
  configured systems. The port to DEC (Digital Unix 4.0) was problematic,
  but the program builds and runs properly on linux, solaris and Mac OS X.


******************************************************************************
                                   HEASARC
******************************************************************************

extractor: see release notes for XSELECT & EXTRACTOR below.

mathpha:

- Updated to use wtpha2 and default to version 1.2.0 of the spectral file
  format (fixes the TNULL keyword value bug).

grppha:

- Fixed error which assigned quality=2 to channels left over at the end
  of grouping even if the channels started off with quality=1. Now keeps
  such channels as quality=1.   


******************************************************************************
                                    ROSAT
******************************************************************************

abc:

- Fixed problem in libros which caused failure if the input events file was
  compressed.

pcrpsf:

- Added support for HDUVERS=2 WMAPs.

******************************************************************************
                                    TIME
******************************************************************************

maketime:

- fixed bug which created duplicate HDUCLASS keywords

mgtime:

- fixed bug which occurred when the TIMEZERO keyword was not present

******************************************************************************
                                    XIMAGE
******************************************************************************

XIMAGE VERSION 4.1

For full documentation on XIMAGE, refer to:

  http://heasarc.gsfc.nasa.gov/docs/xanadu/ximage/
  
===> Major changes since XIMAGE v4.0 <===
  
   * XMM support
   * Output detector coordinates compatible with ds9
   * Support for internally compressed images
   * New commands
      + ccorr - Correct image coordinates given guide source locations
      + srcmrg - Merge the results of detect, removing duplicates
      + rdarray - Read text file into Tcl array
      + prarray - Print Tcl array to screen or write to file
      + select - Use the cursor to make a selection
  
===> Other changes since XIMAGE v4.0 <===
  
For complete details on command changes and new features see:
  
  http://heasarc.gsfc.nasa.gov/docs/xanadu/ximage/ximrelease.html


******************************************************************************
                                   XRONOS
******************************************************************************

XRONOS VERSION 5.19
  
Minor bug fixes aimed at improving support for Linux and Mac OS X.


******************************************************************************
                             XSELECT & EXTRACTOR
******************************************************************************

The first 60 ASCA GIS channels are now set to bad when saving spectra. In
modes with compressed spectra the first 60/compression factor channels
are set to bad.

The select chip command now successfully resets the data subspace keywords to
take into account the removal of GTIs for the chips not selected.

Added support for the extractor ccol parameter. Also removed error if the GTI
cannot be found because if data subspace keywords are in use we can find GTIs
that way.

Added support for passing the wmapver parameter to extractor.

Added the ccol argument to xselect.mdb to give the name of the column with
the CCD ID for each event. This is used in dealing with multiple GTIs in
Chandra and XMM-Newton files. Other missions can set this argument to 'NONE'.

Changes to xselect.mdb for Chandra to be consistent with CIAO v2 (WMAP in
DETX/DETY and binned up by a factor of 8). Also switched default spectra
from PHA to PI since that is what most people want to use.

Fixed error in xselect.mdb in the BeppoSAX TIMESYS setting. Spacecraft times
are measured from 1/1/1994 not 1/1/1995.

Added parameter to the extract/bin command to pass the wmapver parameter to
extractor.


Extractor has been extensively modified. It now
      - correctly handles multiple chips with their own GTIs
      - writes a FITS region extension describing selected regions into the
        output file
      - reads FITS region extensions (a la XMM) or data subspace keywords
        (a la CIAO) to find any regions already selected from the input events
        files
      - writes datamodel subspace keywords describing the event selection
        performed
      - propagates deadtime corrections using DEADC, DTCOR, or the ratio of
        LIVETIME and ONTIME
      - does not output relevant keywords and GTI extensions for CCDs from
        which no events are selected
      - reads a new ccol parameter which gives the column name for the CCD
        number
      - writes keywords in the WMAP which correctly use WCS (and correspond
        to CIAO output). To recover the old version of the WMAP set the new
        wmapver parameter to 1.
      - outputs images which include the WCS PHYSICAL coordinates
      - does not incorrectly shift the selected region by one pixel for
        ACIS data

Output from extractor should now be compatible with CIAO and SAS. Please let us
know if you find counter-examples to this assertion.

Note that extractor bins into image space then region-selects. This may produce
slight differences from cfitsio and dmextract which region-select and then bin.
Extractor includes all image bins whose center lies within the selected region.

Also note that the interpretation of region files produced by eg. ds9
differs between software systems. extractor/cfitsio, ciao, sas, and
funtools can interpret region files containing exclude regions in
widely different ways.

However, the xselect 'select' command does not yet write datamodel
subspace keywords since it just runs fselect.


******************************************************************************
                                    XSPEC
******************************************************************************

XSPEC V11.2 release notes
-------------------------
  
V11.2 is an incremental release over V11.1. Major improvements are a command
to wrap-up the setting of XSPEC internal variables, methods to estimate
confidence ranges on fluxes and equivalent widths, and new and improved
models.
  
Commands
--------
  
There is a new command : xset. This is a wrap-up for abund, cosmo, mdatadir,
method, statistic, weight, xsect. It also enables the setting of strings to
be passed to models. Those currently implemented are :
  APECROOT         which allows the user to change the APEC input files used
                   in the models apec and vapec
  NEIVERS          the version number for the NEI models
  NEIAPECROOT      which allows the user to change the NEIAPEC input files
                   used in the NEI models when NEIVERS=2.0.
  RGS_XSOURCE_FILE the file to read to get rgsxsrc parameters.
Note that xset does not check whether the names or strings input are valid.
To use this facility for local models all you need to do is add a call to
fgmstr(name) to your routine (both fgmstr and name should be declared as
character*128).
  
The eqwidth, flux, and lumin commands now have an option to estimate a
confidence range. A similar technique is used to improve the goodness
command.

The fakeit command now automatically creates a faked background file to
go with the faked source file if a background file is in use when the
command is run. If the source file is called foo.bar then the background
file is foo_bkg.bar.

setplot rebin has an option to change the algorithm used to calculate error
bars in plots.
  
setplot id has an option to set a redshift.
  
abund (and xset abund) now also include the wilm relative abundances
(from Wilm et al. 2000 and appropriate for the ISM).

Models
------

The NEI models now come in several versions. To switch between them use
eg. 'xset neivers 1.0'. 1.0 gives the NEI models in XSPEC v11.1, 1.1 uses
improved eigenfunction files, and 2.0 uses the improved eigenfunction files
and emission spectra calculated using APEC. Emission from Ar is included in
2.0.

A new model rgsxsrc is useful for analyzing XMM-Newton RGS spectra of
extended sources.

The pile-up model has additional parameters for PSF fraction and number of
regions. It should now be an exact analog of that available in ISIS.

General
-------

Since the Minuit source code is now freely distributable it is included in
this version of XSPEC. It is no longer necessary to download an additional
library in order to use the minuit options.

An inefficiency in reading response matrices has been removed. They now
read up to five times faster than in v11.1.

During a fit only the variable parameters are written out instead of all
the parameters.


******************************************************************************
                                    XSTAR
******************************************************************************

Release notes for Version 2.1h (June 2002)

Relativistic corrections to Compton heating and cooling have been added,
using a procedure based on the work of Guilbert (1986).

A new format for the storage of atomic data has been adopted, resulting in
smaller files, and faster read times.  This change should be transparent to the
user, except for considerable speeding of data loading and program startup.

A new algorithm for continuum transfer has been adopted, outward only transfer.
This gives better energy conservation overall.  A new column has been added
in the log file output, labeled `h-c', it tells the percent error in total
energy conservation in the radiation field, i.e. total emitted - total absorbed.

A new algorithm has been adopted for solving the statistical equilibrium, in
place of LU decomposition.  The algorithm involves an iterative solution to a
simplified set of equations,  and is described by Lucy (2001). This change
should result in fast execution for models involving iron and other heavy
elements, but will otherwise be transparent to the user.

Various changes to atomic data, including increase in size of data file and
addition of a new data type, for excitation of Fe XIX using data from Bhatia.

Various minor inconsistencies and errors have been corrected, including
spurious recombination emission to multiply excited levels.

Standard output in the log file has been extended to include a list of the
strongest absorption lines, and emission and absorption edges.

Also, a new output file, xout_rrc1.fits, is created which contains a fits
format list of the RRC strengths.


******************************************************************************
                                     XTE
******************************************************************************

Other than a few minor bug fixes which caused tools to crash in certain
circumstances and/or on particular machines, the significant changes to
the RXTE FTOOLS center around improvements to PCA response matrices and
background models.

New versions of PCARMF, XPCAARF, and the wrapper script PCARSP are
included in this release, as is the associated energy-to-channel FITS
file pca_e2c_e05v02.fits.

PCARMF v8.0 has the following features:

*  Calculation of instrumental energy resolution has been improved
*  Energy channels in the matrix are now spaced logarithmically
*  Each detector can now have a separate value for the thickness
   of the "dead layer" between xenon volumes (via new parameters
   in pcarmf.par)
*  There is now an opportunity to specify a second a+bx law (and date
   when it starts) for the amount of xenon in the propane layer. At the
   moment this is only used for PCU0 (to set the amount to zero after
   the loss of that layer)

PCU0 is still slightly discontinuous over the loss of the propane layer,
but much less so than before.

The only change to XPCAARF is to the default values (in xpcaarf.par)
for the geometric areas of four of the five PCUs (PCU 2 was left
unchanged). These were chosen to make the flux of the Crab similar
when fit to the five detectors (epoch 3/4 chosen for the comparison).
Note that this will likely result in a step function in monitoring
fluxes unless the whole data set is reanalyzed with a constant set of
XPCAARF coefficients.

PCARSP (v8.0) has been updated to ensure that the default value for the
partial charge fraction matches the value in PCARMF (was 0.0, now 0.02).
A bug was also fixed in the previous version which caused the "-n"
flag to fail to properly rename the final output response file in
single-detector cases.

PCABACKEST has been updated to support the new Combined Models (CM)
and to include more information in the output file headers documenting
which models were used. In addition, XTEFILT (ie., FCOLLECT and XTEDERIVE)
has been modified to add a new derived quantity, L6CNTPCU0, to the filter
file. This can be used to filter out times when large flares appear in
the background model due to the loss of the propane layer in PCU0. Six
new quantities must be added to the input AppID list to allow L6CNTPCU0 to
be computed (the full AppID list is given in the fhelp for XTEFILT).
The new quantities are:

 74 X2LX2RCntPcu0
 74 X3LX3RCntPcu0
 74 X1LX2LCntPcu0
 74 X1RX2RCntPcu0
 74 X2LX3LCntPcu0
 74 X2RX3RCntPcu0

Please see the PCA Digest page at
http://heasarc.gsfc.nasa.gov/docs/xte/pca_news.html
(and references within) for additional details on PCA background issues.

The tool FGABOR, which calculates windowed short-term Fourier
transforms on a lightcurve file, has also been enhanced since the
previous release. It now includes two new hidden parameters ("sigma"
and "normalize") to allow users to tweak the gap-detection algorithm
and the output power normalization.

The script FAXBARY has had a bug fixed which caused it to fail to create
a proper merged orbit file if the input list included mission day 1157.
A new (hidden) parameter, "tolerance", has also been added to allow for
leap seconds in the orbit file timestamps. The default value is 3 seconds.

Finally, the help files for the HEXTE deadtime corrector (HXTDEAD) have
been updated to add the hidden parameter "detectors", which controls
which detectors are included. Note that the parameter itself is not new,
it was just missing from the documentation.