******************************************************************************

                         RELEASE NOTES FOR HEASOFT 5.3
                               November 17, 2003

                                   SUMMARY

HEASOFT 5.3 is a software suite consisting of FTOOLS 5.3, FV 4.0,
XIMAGE 4.2, XRONOS 5.20, XSPEC 11.3, and XSTAR 2.1j. 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, README.CYGWIN, 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.3. More information on FTOOLS 5.3,
XIMAGE 4.2, XRONOS 5.20, XSPEC 11.3, and XSTAR 2.1j can be obtained
using the fhelp utility.  Type "fhelp ftools" to obtain a full listing
of all the tools available, or "fhelp <sub-package-name>" to list all
of the tools in a particular subpackage, e.g., "fhelp asca".  Finally,
type "fhelp <toolname>" for more detailed help on a particular tool.
FV 4.0, XIMAGE 4.2, and XSPEC 11.3 all have online help available from
within the program.  In addition, XIMAGE 4.2, XSPEC 11.3, and XSTAR 2.1j
have TeX formatted manuals for their usage.

HEASOFT v5.3 contains new versions of tcl/tk (8.4.4) and tix (8.1.4).
Also new in this release is support for builds under the Cygwin
environment for the Windows platform.  Cygwin users should read the
file README.CYGWIN carefully for build and usage instructions.


******************************************************************************
                                CONFIGURATION
******************************************************************************

- The "LHEASOFT setup complete..." success message generated upon software
  initialization has been silenced.  Errors are still generated if
  initialization fails.

- The installation directory mnemonic has changed with this release to
  conform to the GNU/autoconf standard.

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

Updates:

- sisrmg algorithm updated to correctly determine the center of HDUVERS=2 WMAPS

- addascaspec: Allow users to specify the error method used when calling mathpha


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

Updates:

- rdebd3 & rdedb4: when the TLMIN keyword is not found, use the first
  element of the CHANNEL column instead of assuming the first legal channel
  is 1.

- rdrmf4.f: add test for HDUVERS1 keyword in addition to HDUVERS/HDUVERS2.

- wtpha1 & wtpha2:  For potentially long filename keywords (BACKFILE,
  CORRFILE, RESPFILE, ANCRFILE) write long string keywords (i.e. to make
  use of the CONTINUE keyword if necessary).


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

- addrmf: add test for HDUVERS1 keyword in addition to HDUVERS/HDUVERS2.

- cmppha:
  - fixed computation of statistical errors
  - fixed error computation (Squish mode) when there is only 1 spectrum
  - fixed file close behavior when there is only 1 spectrum in the input file.
  - increased input spectra limit from 256 to 1024
  - copy all values of ANCRFILE, RESPFILE etc. keywords from the input
    spectral columns (if any), not just the first row.

- gcorrmf & marfrmf: modified to keep the order of extension HDUs

- rbnrmf: fixed bug that occurs if rmf file has extra extensions which
  the user wants to copy.

- udcif:
  - if updating a CIF with a file whose name is greater than 40 characters
    (the limit on the CAL_FILE column), warn the user that the file name is
    being truncated (and thus cannot be located in the CALDB)
  - require that the alias_config.fits file be under $CALDB no matter
    what value the CALDBALIAS variable contains.


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

CFITSIO changes:

- supports unlimited number of HDUs in a FITS file (previous
  maximum was 1000 HDUs).

- the limit on the number of files that a program can open
  at one time has been increased from 40 to 300.

- FITS tables with ascii character columns that are more than
  28800 characters wide are now supported.

- modified the driver code for opening remote FITS files
  via HTTP to support the HTTP 1.1 protocol and to
  support proxy HTTP servers.

- ported CFITSIO to support newer operating systems, including the
  AMD Opteron 64-bit OS and Mac OS-X.

- fixed problems in CFITSIO's virtual file syntax parser to correctly
  handle cases where keyword values are modified on the fly when
  the file is opened.


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

New tool in this release:

- fexpoadapt: smoothes (using an adaptive boxcar filter) an image and the
  associated exposure map in exactly the same way, to produce an
  adaptively-smoothed, exposure-corrected image.


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

New tools in this release:

- spibkg_init: New INTEGRAL ftool for use with XSPEC 12
  Spibkg_init -- Initialize input database for the XSPEC  "spibkg"     models
  that are used in the spectral deconvolution of INTEGRAL/SPI     data

Updates:

- fcopy: fixed bug which caused it to not report an End-of-File error
         if the input file was corrupted and shorter than expected.

- fcreate: modified to deal with bits type (nX) columns data.
           To enter vector bit column data e.g. enter '7' (not '1 1 1')
           to set all bits of a 3X column.

- fdiff: added tolerance and reltol parameters:

     Numerical  quantities  are  flagged as different when their arithmetic
     difference  exceeds  a  certain  threshold.  Users  can supply both an
     absolute  and  relative  threshold  using the "tolerance" and "reltol"
     parameters.  For  quantities  x1  and  x2 from file1 and file2, values
     which satisfy this expression:
 
        |x1 - x2| > tolerance + |x1|*reltol
 
     are   considered   to  be  different.  A  relative  tolerance  may  be
     appropriate if there is a large dynamic range in values. By using both
     an  absolute  and relative tolerance, users can also guard against the
     case  when x1 is near zero. The default tolerances are '0', indicating
     that an exact match is required.
 
- fimgcreate: modified such that it now writes the BLANK keyword if
              BITPIX is > 0 and nulltest = YES.

- fkeypar: modifications to support long string keyword values.

- fselect: fixed bug which occurred when selecting on tables that have
           variable length columns.

- ftabpar: modified to support unsigned 4-byte integer columns

- fverify:
  - fixed logical error in retrieving and printing total number of errors
    at the end
  - modified such that with prstat=no it will only write a 1-line pass/fail
    message
  - modified to return number of errors and warnings
  - modified to support the new WCSAXES keyword
  - modified to perform additional checks, such as: 
     . check that the mandatory keywords are in fixed format
     . check new WCS keywords
     . checks related to indexed keywords verify that the keyword actually
       has an integer index suffix before applying the check

******************************************************************************
                                    FV
******************************************************************************

Fv enhancements:

- ds9 support: user can choose to display images or line plots using
  ds9 instead of the POW image display tool that comes integrated with fv.

- better scripting capabilities:  more XPA access points have
  been added to fv and POW to be able to control most major
  functions from external scripts or processes using the XPA
  messaging system.  See the fv 'scripting' help file for more
  details

- the functions of the left and right mouse buttons has been reversed
  to be more compatible with ds9.  A user preference option can be
  selected to switch the buttons back to there previous state.


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

New tools in this release:

- bcont: Reads one or more (contiguous) BATSE daily data sets for
         plotting, interactive time cuts, statistical tests

- bpulsarspec: Reads BATSE pulsar database files and displays the
               hardness ratio vs. phase or time, flux vs. phase

- groview: Display BATSE, COMPTEL and EGRET viewing angles for
           user selected range of viewing

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

New tools in this release:

-  arf2arf1: new task to convert a Type 2 ARF file to a Type 1 ARF file.

-  grppha2: new tool which manipulates OGIP standard TYPEII PHA FITS file.
            Both input and output files are of TYPE II PHA.

Updates to existing tools:

- chkrmf: updated to enforce OGIP standard for rmf files that HDUCLAS1 must
          be 'RESPONSE'and HDUCLAS2 must be either 'RSP_MATRIX' or 'EBOUNDS'.

- mathpha:
  Modified to allow for ~1000 input files.  When the input expression gets
  over approximately 1000 characters, users must input the expression via
  a text file, as in "mathpha expr=@expr.txt" because the string parameter
  length in xpi is limited.  The filename length is not strictly limited, but
  the code is generally expecting filenames to be on the order of 12 chars,
  i.e. the "8.3" format, especially as the number of input files approaches
  1000.  The true limiter is that the final expression it constructs internally
  (which is much longer than the original input expression) has a limit of
  32768 chars.  Users should therefore avoid using long directory paths as
  part of filenames, especially when the number of files is very large.


******************************************************************************
                                     QDP
******************************************************************************

- HEAsoft v5.3 uses the 2003-07-21 release of QDP/PLT.
  Changes since the last version are:

  2003-07-21 - LIne Step now works if X-coordinate is decreasing.
  2003-07-17 - Fix crashes when user uses an undefined group.
  2003-04-15 - Grid ON now works with images.
  2002-08-02 - Fix bug where PLT incorrectly decides no points are in fit range.
  2002-04-02 - Model is now plotted for entire displayed range not fitted range.
  2002-03-21 - Add CGau and NCGa built-in functions.
  2002-03-19 - SCR [White|Default|Black] added to set default background color.
  2002-03-18 - Cursor keys now work with xterms (change to cget.f).
  2002-01-22 - STat and IMOdel commands now works with 2D groups.
  2002-01-22 - Y range limit implemented for 2D fitting.
  2002-01-22 - Fix calling of PLTSVW from PLTCUR routine.
  2002-01-17 - Increase to MXPAR=120, MXFREE=100 (computers are faster).
  2001-07-18 - "err sq y", "gap err", "r y" now correctly sets the scale.


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

- New perl scripts 'day2time' and 'time2day':

  day2time - Convert time offset (in days) relative to a reference date/time
             to an absolute date/time

  time2day - Calculate time (days) between input and reference date/time


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

XIMAGE VERSION 4.2

For full documentation on XIMAGE, refer to:

  http://ximage.gsfc.nasa.gov/

===> Major changes since XIMAGE v4.1 <===

   * WCS support added using Starlink AST library. Ximage now recognizes
      the coordinate systems defined in the WCS convention, enabling
       grid plots and coordinate conversions in such systems.

   * Added Swift XRT support

   * Ability to read in event file with a rebin that is a real value.
       For example, rebin=0.5 in the case of Chandra subdivides the
       standard pixel size in half.

   * New commands
      + crop - Crop image without re-reading
      + curve - Draw path of shortest distance between to sky positions
      + moper - Perform elementary math operations between maps
      + remap - Remap image to new coordinate system, resampling
                pixels by a variety of methods
      + wcs - Manage internal wcs data structures

===> Other changes since XIMAGE v4.1 <===

For complete details on command changes and new features see:

  http://heasarc.gsfc.nasa.gov/docs/xanadu/ximage/ximrelease.html


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

XRONOS VERSION 5.20

Minor bug fixes

For details see:

  http://heasarc.gsfc.nasa.gov/docs/xanadu/xronos/xronrelease.html


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

- Added filter grade option.

- Added option to 'save spectrum' to automatically create a response
  appropriate to the spectrum file.  Note that when extracting Chandra
  spectra this requires CIAO and when extracting XMM-Newton spectrum it
  requires SAS.

- Added initial support for Swift XRT and UVOT.

- Added swmapx and swampy parameters to extractor to allow for missions
  (such as XMM-Newton) whose detector coordinates are in a system looking
  down on the detector not through the detector out at the sky.  These
  parameters are set by xselect according to information in the MDB.


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

XSPEC v11.3 release notes

Commands
--------

Added new option "forcecalc on/off" to xset to force calculation of the model
for all datasets. This is required for mixing models.

Added the following new options to "tclout" : ftest, query, response, arf,
backgrnd, xflt, areascal, backscal, expos

If "steppar" is run with a single parameter then followed by "plot contour"
a plot of statistic vs. parameter value will be produced.

The model description written as part of the standard output at the end of
a fit can now be cut-and-pasted directly into the "editmod" command.

The commands "datafile{n}" and "arf{n}" can now mean n-1th extension
following the first spectral extension. This only works for type I spectral
extensions. If the first spectral extension is type II then the commands
have their usual interpretation as the nth spectrum in the extension.

When using the C-statistic the command "plot chisq" now gives contributions
to C shown either +ve or -ve depending on the sign of data-model.

There is a new option to the command "log filename" to add to the filename
a string giving a date and time stamp.


Models - new models
-------------------

acisabs - the absorption due to the contamination on ACIS. Should only be
          used with response matrices that do not have this effect included!

bkn2pow - a three-segment broken power-law.

expdec - simple exponential decay model.

nsa - neutron star H atmosphere model with different values of magnetic field.

pwab - absorption with a power-law distribution of covering fraction.

smaug - deprojection model for an extended an optically-thin source (eg a
        cluster).

xmmpsf - model to mix spectra between regions to take into account XMM-Newton            PSF.


Models - changes
----------------

The command "xset APECROOT" can now take an argument giving just the APEC
version number. The default has been updated to 1.3.1.

The projct model works correctly for multiple datasets.

The mekal cooling flow models now come in two versions. The default version
has a variable number of emission measure steps that can be set using the
command "xset cflow_ntemps" followed by a number. The old version of the
models, which included a bug, are available by setting "xset cflow_version 1".


General
-------

The "ignore" command runs much faster on spectra with big response matrices.

The screen output from "error" now also includes the parameter range in
terms of plus and minus difference from the best fit.

The abundance tables have been extended to include all elements up to Zn.

The abundance table and cross-section in use have been added to (auto)save.

The default cosmology has been set to the "WMAP standard" of H0=70,
Lambda=0.73 in a flat Universe.


Markov-Chain Monte Carlo
------------------------

Preliminary code for Markov Chain Monte Carlo is included. The "chain"
command runs MCMC chains and the results can be displayed using "plot mcmc".
This is still in the experimental stage. At the moment it seems to work
reasonably well if a fit is done then chains run to generate the posterior
probability distribution. The aim is to improve this so that it is not
necessary to first find the minimum.


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

Release notes for xstar Version 2.1j (September 2003):

- New atomic data for iron K emission and absorption as described
  in Palmeri et al., 2004 A and A and references therein (see TK homepage
  for reprints).

- Added n=2-3 iron UTA absorption using data from FAC (Gu 2003).

- Fixed bug which limited length of spectrum file name to 8 characters.

- Fixed bug which allowed buffer containing ion fractions vs. xi to
  overflow when the number of spatial zones exceeded 1000.  Now the limit
  on the number of spatial zones is 3000, and the code stops with a message
  when this is exceeded.

- Added accurate Voigt profile calculations for all lines in synthetic spectra.

- Fixed bug which limited length of spectrum file name to 8 characters.


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

There have been only two significant changes to the XTE FTOOLS since
the LHEASOFT v5.2 release (June 2002).

The first concerns the tools that generate PCA response matrices
(pcarmf/xpcaarf/pcarsp). A brief description of the changes and their
effects are:

- More recent data has been included for the time-dependent components
  of the instrument response, so a response matrix that is generated
  for recent data is a smaller extrapolation (giving a better result).

- There is better agreement among PCU 1-4 for the Crab (each now gives
  gamma=2.1).  PCU 0 after the loss of the propane layer (May 2000)
  yields a spectral index for the Crab which is somewhat lower.

- The default geometric area parameters per PCU for the tool xpcaarf
  have been adjusted to bring the Crab flux result onto the standard
  scale.

- A new energy to channel file (pca_e2c_e05v03.fits) is supplied and
  will be copied to the $LHEA_DATA directory when LHEASOFT v5.3 is
  installed. The new version of pcarsp (v10.1) will use this e2c file
  by default. This can be verified at runtime by examining the screen
  log and/or the FITS header of the output response file.

A summary of the new responses, and their characteristics, can be found
in the poster at http://lheawww.gsfc.nasa.gov/~keith/xrt2003_jahoda.pdf

and in more detail in the draft in progress
http://lheawww.gsfc.nasa.gov/~keith/pca_calibration_draft.ps

The second notable change to the XTE FTOOLS in LHEASOFT v5.3 relates to
the method used to generate the $LHEA_DATA/tdc.dat file used for fine
clock corrections by tools such as fasebin and faxbary.  The data in this
file are now the result of an improvement to the clock fitting procedure
that ensures continuity of the piecewise continuous quadratic polynomial
used. Both the old and the new tdc.dat files have systematic fitting
errors. In the new file, the fitting errors are constrained to be less
than 2 microseconds, while in the old file the errors could be as much
as 10 to 15 microseconds. Comparisons of the new tdc.dat file with that
generated via the previous method produce results that agree to within a
few tens of microseconds.  While there are offsets and drifts on a daily
scale, no global shift or drift in times results from switching between
the old and new tdc.dat files. However, users who are interested in fine
time correction in long term monitoring campaigns may wish to reanalyze
their data with the new tdc.dat file, as the correction will be better.

Any other changes to the XTE FTOOLS were minor tweaks designed to:

 - Fix bugs that caused the tools to crash under some circumstances

 - Improve robustness (eg, better keyword checking and error handling)

 - Expand portability to new operating systems such as Mac OS X and
   Win32/Cygwin.

 - Ensure that tools operate as documented