Release Notes for HEAsoft 5.1

July 26, 2001


HEASOFT 5.1 is a software suite consisting of FTOOLS 5.1, FV 3.1,
XIMAGE 4.0, XRONOS 5.18, XSPEC 11.1.0, and XSTAR 2.1d. 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,

For each of the HEASOFT subpackages below are listed tools and/or
features which are new in version 5.1. More information on FTOOLS 5.1,
XRONOS 5.18 and XSTAR 2.1d 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.0, and XSPEC
11.1.0 all have online help available from within the program.
In addition, XIMAGE 4.0, XSPEC 11.1.0, and XSTAR 2.1d have TeX
formatted manuals for their usage.


 - Modified QUAT routines to not exit when doing a det->sky
   transformation with a tilt angle>=90 degrees.

 - Fixed bugs which made interpolation and averaging incorrect.
 - Now outputs spacecraft Euler angles to the parfile.


** New tool in this release

 - Creates a mosaic of several observations; although adaptable to
   other missions, this version contains ASCA-specific supports,
   such as the ability to construct background maps, given the mkf file.
   Also new is Perl script 'fmosaic2img', which combines the raw image,
   background map, and exposure map created by fmosaic into a single
   background-subtracted, exposure-corrected image.

** Updated tools in this release

ascalin and sispi:
 - Added support of new CTI correction formula from the SIS team.

   Note, however, that this update will not change the actual behavior
   of these tools at the time of the HEAsoft v5.1 release, as the
   new calibration file that requires the use of this new formula
   is not ready for general release.  When used with the currently
   released calibration files, the behavior remains unchanged from
   HEAsoft v5.0 (and earlier) versions of these tools.

 - Fixed a minor bug to make it more robust.

 - Incorporated the new echo correction formula from the SIS team,
   for conversion to BRIGHT2 mode.

 - Fixed a bug which prevented this tool from generating the correct
   response for bright-mode-binned spectrum.  This bug, however, did
   not impact users who rebinned bright mode spectrum into 512 linearly
   spaced channels.

 - Also updated the default echo calibration file (see below).

** Updated calibration file in refdata/sisdata area in this release

 - Updated version of the echo calibration file.  The change parallels
   the update of the tool, faint, but for the analysis of BRIGHT mode
   spectrum.  New version of sisrmg now uses this file by default.


Modified to support vector AREASCAL and BACKSCAL, and to accept the
HDUVERS=1.3.0.  Improved string-handling capability.

 - Increase the size of filename from 128 to 255.
 - Increase the number of arf files from 100 to 2500.
 - Fixed string writing bug.
 - Find ARF extensions automatically.
 - Added declaration for clenact, needed on strict Fortran implementations.

 - Increase the maximum number of files from 100 to 2500. Note that this 
   program currently grabs too much memory and this limits the number of 
   responses that can be added together in one go.
 - Increased sizes of group and element array and added an error check for
   exceeding the dimensions of these arrays.
 - Freed buffer array to avoid memory leak.
 - Upped history/comment strings to 72 chars to match CFITSIO/fcrhky mods
 - Switched from using HDUVERS2 to HDUVERS keywords to follow current standard.
 - Fixed bug causing failure in internal write for long names of rmf files.

 - Switched from using HDUVERS2 to HDUVERS keywords to follow current standard.

 - Two new hidden parameters have been added:

     * rows: allows the user to specify a subset of the rows to
       squish/expand.  The default value of "-" means all rows,
       which was the (only) behavior of the old version.

     * datacol: allows the user to specify the column name to read
       in the input file.  By default (" "), cmppha will use either
       the COUNTS or RATE column.  Some Type II pha files have additional
       columns, such as "BACKGROUND_UP" in Chandra grating spectra,
       which this option is designed for.

   These options provide a way of producing Type I pha file for specific
   rows in a Chandra grating Type II file; this, in turn, allows the use
   of such tools as 'rbnpha' and 'grppha' on Chandra grating spectra.

 - Fixed uninitialized status variable that led to problems on Linux.

 - Fixed uninitialized ierr variable which caused program to fail under

 - Switched the order of reading parameter for filename of arf and rmf.
 - upped history/comment strings to 72 chars to match CFITSIO/fcrhky mods

 - Fixed uninitialized variable bugs (caused failure on IRIX)

 - Fixed bug if the compression factor is -1.
 - Fixed uninitialized variable bug.
 - Extended lengths of filenames to 255.

Significant Changes Made to CFITSIO Since the HEASOFT 5.0 Release

A.  The following new features have been added to the 'extended
    filename syntax' in CFITSIO, which all the FTOOLS tasks support when
    reading input FITS files:

  1. Raw binary data arrays may be read as if they were FITS images;
     CFITSIO converts the raw files into virtual FITS files on the fly.
  2. On UNIX platforms, filenames that begin with "~/" or "~user/" will
     get expanded into a string that gives the path to the user's home
  3. Disk file names that begin with a minus sign are now allowed.
  4. Image HDUs may be flipped along any axis on input either by
     specifying a starting section pixel number greater than the ending
     pixel number, or by using '-*' to flip the whole axis.  Examples:
     "myfile.fits[1:100, 50:10]" or "myfile.fits[-*,*]".
  5. When specifying an expression to calculate values in a column the
     #NULL and #SNULL constants may be used to set the value to Null.
  6. When calculating column values, the C-conditional syntax is now
     supported: 'boolean ? trueVal : falseVal'.
  7. A minus sign (-) as well as an exclamation point (!) may be used
     when specifying a column or or keyword to be deleted: [col -time] will
     delete the TIME column.
  8. When filtering the rows in an input table, or create a histogram
     image from the values in a table column, CFITSIO now writes HISTORY
     keywords in the resulting file to document the filtering expression
     that was used.
  9. When a row selection or calculator expression is written in an
     external file (and read by CFITSIO with the '@filename' syntax) the
     file can now contain comment lines.  The comment line must begin with 2
     slash characters as the first 2 characters on the line.  CFITSIO will
     ignore these lines when reading the expression.
 10. The region filtering code was modified to:
     a) support the  POW, SAOtng and ds9 region file formats.  Region
     positions may now be given in HH:MM:SS.s, DD:MM:SS.s format, and
     region sizes may be given arcsec or arcmin instead of only in
     pixel units.

     b) if multiple 'include' regions are specified in the region file,
     they are ORed together, instead of ANDed, so that the filtering
     keeps points that are located within any of the 'include' regions,
     not just the intersection of the regions.

     c) if the first region is an excluded region, then it implicitly
     assumes that a prior include region covering the entire detector
     was specified.

     d) cases were a smaller include region is within a prior exclude
     region are supported

B.  Other CFITSIO Enhancements:

  1. Enhanced the keyword reading routines so that they will do implicit
     datatype conversion from a string keyword value to a numeric keyword
     value, if the string consist of a valid number enclosed in quotes.  For
     example, the keyword mykey = '37.5' can be read by ffgkye.

  2. Modified ffiimg so that it is possible to insert a new primary array
     at the beginning of the file.  The original primary array is then
     converted into an IMAGE extension.

  3. Modified ffdhdu so that instead of refusing to delete the primary
     array, it will replace the current primary array with a null primary
     array containing the bare minimum of required keywords and no data.

  4. Modified ffpmsg, which writes error messages to CFITSIO's internal
     error stack, so that messages > 80 characters long will be wrapped
     around into multiple 80 character messages, instead of just being
     truncated at 80 characters.

  5. Modified ffpcom and ffphis, which write COMMENT and HISTORY
     keywords, respectively, so that they now use columns 9 - 80, instead of
     only columns 11 - 80.  Previously, these routines avoided using columns
     9 and 10, but this is was unnecessarily restrictive.

  6. Modified drvrnet.c to deal with ftp compressed files better so that
     even fits files returned from cgi queries which have the wrong mime
     types and/or wrong types of file names should still decompress.

  7. Added support for the "-CAR" celestial coordinate projection in the
     ffwldp and ffxypx WCS routines.  The "-CAR" projection is the default
     simplest possible linear projection.

fv version 3.1

Changes to fv since the release of fv3.0:

* The hundreds of tables available in VizieR can be queried to retrieve
  FITS tables containing the objects near a given position.

* The column histogram tool can be limited to a specified row range. 

* An integer column with the TSCAL and TZERO keywords is treated as 
  a double column to prevent data truncation.

* A new tool is available for editing the name, units and display
  format of any column.

* The 'export as text' options (for images, tables or vector tables)
  have been enhanced to optionally print row numbers, and print a
  user-specified character string between each columns value.

* Double Right-clicking inside a pow graph redraws the graph with
  the default 1:1 zoom factor.

* The Zoom/in Zoom/out and replot buttons have been moved off the
  POW canvas and up into the menu bar. 

* If an HDU contains a 1-D image, the 'PLOT' button on the summary
  window displays a line plot of the pixel value vs. pixel 
  coordinate, using the WCS coordinates if available, instead of
  plotting a long, thin image.

* Rows of a vector table, either fixed or variable length, can be


 - Added "percent complete" counter.
 - Modifications to remove spurious artifacts in the smoothed image and to
   improve the speed in the case of circular kernels by about a factor of 10.

farith, fcarith, fimgbin:
 - Added new "overflow" parameter.

 - Output the cfitsio error stack.

 - Fixed bug which caused the Y pixel value to be written to the XCOORD
   (celestial coord) column and vice-versa.

fimgzip, fimgunzip:
 - New tools to compress and decompress images.

 - Allow blank lines and lines starting with '#'.
 - Add datatype parameter which sets the output image bitpix.
 - Detect real weights and set output to float.
 - Change weight/output arrays from float to double for greater precision.
 - Make VALUE column optional for FITS input file

 - Added the option of inverse mask.
 - Changed crpix hidden parameter from integer to real.
 - Added coordinate transformations and fixed filter algorithm.


 - Now correctly treats the string column.
 - Corrected a couple bugs which were preventing the command line from
   being parsed correctly.

 - Added code to correctly exclude a column (ie. -COL_NAME as input colname).
 - Added code to perform 'delkey=yes' operations.
 - Increased size of 'comment' buffer to hold longer filenames, etc.
 - Strings to hold column names expanded.

 - Implemented the exact parameter.
 - If the column is not found, return colnum 0 and don't print out the
   error message.

 - Fixed a bug when comparing string data.

 - Use fcecls to get array with column numbers, instead of calling ftgcno
   directly. Not only is this more efficient, but fcecls properly handles
   wildcards. Also, pass Boolean variable exact to fcecls for it to
   determine its case sensitivity.

 - Bug fix to handle variable length arrays.
 - Initialized ftstatus variable in fimgcl
 - Extended the string length of columns and lastkey from 80 to 255.

 - Added the parameters of totalhdu and hdunum.

 - New task to create a FITS file from a template file.

 - Fixed the TDISP format problem.
 - Fixed the memory problem (The bug will crash the system if the length of
   colname > 40 chars).
 - Skipped the blank names in the column name duplication tests.



*NOTE: The bod2rmf tool is currently not available for Linux platforms.*

The new version differs from the last release in that variations in the
detector energy channel boundaries of the BATSE Large Area Detectors
(LADs), which were made several times during the mission, were not
properly taken into account in the previous release.  The channel edges
were programmable, and several times during the mission, different channel
mappings were uploaded to the satellite. The channel mappings were
changed to alter the number of channels in a given energy range, for
example to allow more spectral resolution for an active softer source.
Such changes are now taken into account through the application of a
lookup table and an interpolation.  The algorithm to perform this correction
was provided by the NASA Marshall Space Flight Center, and ported from
VAX-specific Fortran at GSFC.

Two new arguments are required; a start and a stop time, both expressed
in truncated Julian days (JD-24400000). These parameters are used to
search the lookup table to apply the appropriate calibration.

The INSTRUME keyword is now set to LADn, where n=0,1,2,...,7 is the number
of the LAD module selected. This is now consistent with "bod2pha", thus
eliminating the instrument mismatch warning issued by XSPEC.


 - Added dynamically allocated arrays.

 - Changed the buggy ffgkyl call to ffgky.

 - Added support for ds9 (v3.0) region files. Can now deal with region files
   with positions in pixels, sky in degrees, and sky in hms and dimensions
   in pixels or arcseconds. Dimensions in arcseconds are identified by
   a '"' following the value. Positions in hms are identified by the
   presence of a ':'.

 - Added new parameter copyall which determines whether extra extensions are
   copied when extracting events. The extra extensions are now placed at the
   end of the output event file. If multiple event files are read then only
   the extra extensions from the first file are copied.

 - Propagated the value of the HDUNAME keyword in the GTI extension in the
   input event file. This keyword is used in CXC software.

 - When extracting new event files try both the primary and event extensions
   to get the basic mission keywords.

 - Added history keywords to keep track of which coordinates were used to
   make the WMAP.

 - Fixed errors in pixel to WCS and back routines.

 - Fixed bug that produced incorrect region filtering when the region file
   included an ANNULUS which contained pixels with negative coordinate

 - Removed the BLANK keyword from the WMAP header since it is not valid for
   a real array.

 - Fix so that PHALCUT and PHAHCUT are written correctly in light curve files.

 - Fixed a very occasional memory problem caused by excluded polygons
   extending outside the calculated bounding box.

 - Fixed bug in dimension conversion when image is binned.

 - Fixed a number of bugs which showed up under Linux due to variables not
   being initialized.

 - Fixed bug which caused matrix to be written incorrectly.

 - Added support for vector AREASCAL and BACKSCAL. Also removed PHA_RD and
   SET_KEY and placed in CALLIB. The loop in PHA_RD that wrote the keywords
   to the screen has been moved into the main program.
 - Fixed variable initialization bug (linux), and other string-length bugs.

 - Defined a temp work array to avoid reading/writing the output file twice.
   There will be no extraneous rows in the output file.
 - Added the check for checksum and datasum keyword in xhkexd.
 - Removed extraneous rows in the output file.

 - Bug fix/enhancement: when checking for a real value, do not allow
   characters after a real value; this is instead assumed to be a file
   name, e.g. 1.pha.

 - Add message if no points found with 1 deg from input position.
 - Changed calling parameters.
 - Fixed the pixel calculation at the boundaries.

 - Added support for vector AREASCAL and BACKSCAL.


 - Bug fix: now copy the keywords from input file to output file.


 - Increased the max number of files from 10 to 32.
 - Bug fix: no longer requires an EXTNAME keyword in the primary header.
 - Added additional history keywords to describe what the program did.

 - Corrected a casting bug, which caused a compiler problem.
 - Fixed minor problems related to namespace usage and missing return values.


Change to XANLIB affecting users of PLT and QDP

In earlier versions of HEAsoft, a number of subroutines used by QDP,
including plt.f and other PLT-related files, were built into the
XANLIB library. Recent changes to HEAsoft made it desirable to
separate these routines, so they have been moved from XANLIB into a
new PLT library. The new library is fully integrated into HEAsoft
and will be available in subsequent releases.

This change will have the following effects on the HEAsoft suite:

1) For users of future versions of HEAsoft, this change will be
   completely transparent, as the new library is built into the
   standard HEAsoft build/install procedures.

2) External software which links to XANLIB, but which does not call
   PLT-related plotting routines, will similarly be unaffected
   by this change.

3) External software which links to XANLIB, and *does* call PLT-related
   plotting routines, will also need to link to the new library,
   libplt.a. To accomplish this, developers need to add -lplt
   *after* -lxanlib in their link lines.



For full documentation on XIMAGE, refer to:

===> Major changes since XIMAGE v3.01 <===

   * Scriptable Tcl interface
   * New /xtk device provides GUI facilities
   * Multiple image maps (up to nine) may be loaded into memory at once
   * Full support for real maps, including negatives and nulls
   * Overlayed contours automatically transformed to underlying
   * New tools
      + mkcolor - Create true color images
      + mkhratio - Create hardness ratio images
   * New commands
      + map - Image map manipulation and information
      + marith - Perform arithmetic on image maps
      + screengrab - Captures current appearance of /xtk plot
      + contour/statistic - Calculate levels based on background
      + gencolor - Automatic generation of true color images
      + draw - Draw shapes

===> Other changes since XIMAGE v3.01 <===

For complete details on command changes and new features see:



===> Bug Fixes & Minor changes since xronos 5.16  <===

     earth2sun - ephemeris table extended validity period
                 from 1950-2000 to 1950-2050

     efsearch  - now plots on the X-axis the offset period from 
                 the best period rather than full period

     efsearch & efold - add parameter to skip the exposure calculation 
                 for input event file 

     lcurve/efold  - Add an option to plot color ratio and intensities 
                     versus time (or phase) for two input light curves 

Improved support for XMM. Added a binning scheme for the PN. For the MOS
truncated the spectrum to 12000 elements and binned by 5. These should
match standard matrices.

Changed the Chandra raw coordinates to CHIPX, CHIPY and made them the
default WMAP coordinates except for the HRC which keeps the WMAP as

Added a copyall option to the extract/bin command to set the new copyall
parameter in extractor. This option is hidden and defaults to no. If
the user sets it to yes then all extensions are copied when extracting

Switched the default image display to ds9. Also added a new parameter 
rebinregion which determines whether the region files will be rebinned
if the image binning is changed. This is added because ds9 region files 
don't need rebinning and fregcon currently doesn't handle them correctly.

Improved handling of instruments where users might want to switch between
energy columns (eg PHA to PI). Set phaname now resets the lower and upper
limits on the column values. If the MDB specifies spectrum truncation then
xselect now only resets the limits if they lie outside the specified truncated 

Fixed plot spectrum and curve so they recognise the qdp_commands parameter.

Attempted to make the prompt the user sees after saving an events file slightly
clearer. This still needs to be improved.

Slightly improved error reporting if the Chandra or XMM event file from which
a chip is being selected doesn't contain the GTI extension for that chip.

Initialized status variables in the routines to find the correct HDU for 
Chandra and XMM GTIs. The uninitialized variable caused the routines to fail 
under Linux.



Data input ---

Spectral files can now have vector values of AREASCAL and BACKSCAL. XMM-RGS
spectra have an AREASCAL for each channel. The vector BACKSCAL allows the
grating spectrum to be extracted from a non-rectangular region on the detector.

Since AREASCAL and BACKSCAL can be vectors they are no longer prompted for
in fakeit.

Finally got round to fixing the problem that any time one response is read 
in, they all are. Now XSPEC only reads the response(s) required. The response
reading also makes more efficient use of memory. It is still too slow for
large response files.

The constraint that the background file must have the same grouping as the
source has been relaxed. Now, if the file is not in the obsolete non-FITS 
format, the background file grouping does not matter since the source file 
grouping is automatically used.

FITS NULL values are trapped and replaced by 1.e-32. This should have no
practical effect because channels with NULL values will presumably have bad
quality set. This change is necessary because some manipulations occur to 
the values before they are ignored.

Model fitting ---

The command "model ?" now does not remove the current model.

The cstat statistic has been extended to work in the case where a background 
spectrum has been read in. The mathematical basis is described in Arnaud, 2001,
ApJ submitted.

A new model type has been added for convolution on the model times the 
effective area. This is used for pile-up models in CCDs.

Output ---

There are new options on the identify command. The user can now switch 
between line lists. The APEC line list has been added. The APEC option has 
additional options to specify a temperature and an emissivity limit. This
uses the same APEC line list file as the apec model. If the user has setplot 
wave then the input range is specified in Angstroms and wavelengths rather 
than energies are written out.

The model rate has been added to the tclout rate option.

The number of significant figures written out by the show pha command has
been increased.

The cosmo command now allows a cosmological constant to be set. This is only
allowed if the Universe is flat (when an analytic expression is available for
the luminosity distance).

Plotting ---

The setplot id command adds line IDs to the plots. The APEC line list is used
and the temperature and emissivity limit can be set.

The plot icount command makes an integrated counts plot. This is useful for
spectra with very few counts.

A new PLT feature has been used to slave any x-axis changes in the lower 
window to those in the upper for two-window plots. We have also explicitly 
included a rescale x command to ensure that the x-axis range corresponds to 
the data present. This overrides a PLT/PGPLOT feature that tends to produce 
lots of blank space on log axis plots which cover a small range.

New Models ---

The xion model from Sergei Nayakshin performs reflection from an ionized disk.

The projct mixing model does 3-D to 2-D projection for prolate ellipsoids.

The reflect convolution model calculates reflection from a neutral medium.
It subsumes the pexrav and bexrav models.

The lsmooth convolution models smooth using a Lorentzian kernel.

The Tuebingen-Boulder Galactic absorption models provide better models for
absorption due to the ISM. tbabs calculates absorption including molecular gas
and dust. ztbabs is a redshifted version without the dust. tbgrain allows the
atomic to molecular gas ratio and the grain parameters to be varied. tbvarabs
allows all parameters including gas and dust metal abundances to be varied.

Changes to current models ---

The apec and vapec models have been sped up by a factor of 50-100. The model
now uses the APEC v1.10 data files. The XSPEC_APEC environment variable has
been added to enable the user to switch the input files in use.

The default ranges for comptt have been altered to better reflect the physical
range of validity of the model.

A second parameter has been added to gsmooth to allow the width to vary with
energy in different ways.

The uvred and redden models have been changed to have unit transmission
shortward of the Lyman limit. This is physically wrong but allows them
to be used in concert with photoelectric absorption models.

The NEI models have slightly updated atomic physics. There is somewhat 
updated data for the Fe Kalpha line and a couple of bugs have been fixed. 
There are better collision strengths for He-like S, Ca, and Fe (and minor 
modifications for He-like ions for several other elements).

Bug fixes ---

The patches listed on the XSPEC bugs web page have been incorporated in
the release. The following additional bugs have also been fixed.

Neither the ** option nor giving a wavelength outside the dataset range 
worked correctly when ignoring or noticing after setplot wave.

There was a spurious zero width energy bin produced by the extend high 

The background scaling was not being taken into account when using the lstat

When using the annealing method the wrong parameters were updated if any had
been frozen.

In steppar the best/current choice had to precede the log/nolog choice. Also,
the write statement for the output for each step did not work correctly for 
more than 3 parameters.

The save command now did not save gain shift information when gain was not 
being fitted.

There were illegal blanks in the TFORM# keywords in the eigen*.fits for the
NEI models.

In linefile.fits the TRANS column was A8 which failed to newer versions of

There was a minor typo in photo.f. It would only have made a difference 
if there was more than one edge in a single energy bin, which probably never

There was an error in the table interplation algorithm which showed up if 
parameters had values less than about 1e-5 (which creators of table models 
should be discouraged from doing).

An error was corrected in comptt that was introduced in July 99. This has
been fixed along with the original problem that the earlier incorrect fix was
supposed to handle.

Only the first mixing model was available.

There was a bug that gave an incorrect equivalent width for all datasets except
the first if multiple datasets were in use and the lower end of the continuum
range used corresponded to the lowest energy in the response.

The model cevmkl was actually using the C abundance as the density. This
would only have mattered if a high density plasma was being analyzed.


Release notes for XSTAR Version 2.1d (July 2001)

Please read the instructions in INSTALL.BINARY before installing
XSTAR 2.1d from binaries, or INSTALL.SOURCE before installing
XSTAR 2.1d from source code.

The following changes were been made between v2.0 and v2.1:

 - Added 5 new input parameters vturbi, emult, critd, taumax, xeemin.

 - Added artificial broadening of absorption lines due to turbulent
   velocity controlled by input parameter vturbi.  If vturbi is less than
   the local thermal ion speed, then thermal Doppler broadening is used.

 - Changed input spectrum in default parameter file to pow.  
   Added error check for invalid input spectrum.

 - Fixed error which displayed incorrect value of the constant pressure
   switch in output files.

 - Several minor errors have been corrected in the some of the 
   calculations of atomic rates:  types 67, 51, and 70.

 - Added printout of all line emissivities at each radial zone (in
   addition to the level populations) when the write_switch parameter
   is set to 1.  These appear in the file named xout_detal2.fits.

 - Modified the algorithm for calculating thermal equilibrium so that
   for temperatures less than 3030K the iteration procedure is disabled;
   any radius zone where the equilibrium solver finds a temperature
   less than this value will not calculate thermal equlibrium.

 - Added 2 new output fits files to the standard output.  xout_lines.fits
   contains the luminosities of the 100 strongest emission lines, and 
   xout_cont.fits contains the continuum luminosities without the lines
   added (these two files can be combined by binning the lines suitably
   in order to make the contents of xout_spect1.fits).

 - Added calculation and printout of LTE level populations to the
   quantities in xout_detail.fits.

 - Improved treament of energy budget, and added printout of energy
   budget to xout_step.log.

New in Version 2.1a (December 2000):

 - Fixed error in atomic rates affecting Fe XXI which caused
   recombination rates to be too large.

 - Streamlined calculation of photoionization and recombination rate

New in Version 2.1b (January 2001)

 - Added printout of line and recombination cooling rates to printout
   in log file.

New in Version 2.1c (May 2001)

 - Fixed error in database which resulted in too large emission in some
   iron K$\beta$ fluorescence lines.

New in Version 2.1d (May 2001)

 - Added feature which appends ion column densities in an additional
   extension to the xout\_abund1.fits file.

New in Version 2.1e (June 2001)

 - Extended the energy range up to 1 MeV and added relativisitic
   Compton heating and cooling.

 - Fixed error in calculating threshold energies of some excited levels
   from type 53 data.

 - Fixed error in subroutine which creates blackbody spectra which
   resulted in spuriously large fluxes at energies above 50 keV.

** Note that on Solaris platforms, compilation using gcc will defeat the
   optimization, so for best results the Sun cc compiler should be used.


HEAsoft v5.1 includes the following changes to the XTE package since the
release of v5.0.4 (released 20 February 2001):

XPCAARF/HXTARF: Fixed a bug related to overlap between GTIs and the time
range covered by the attitude file. The tools will now refuse to generate
an output file only when there is no overlap at all between the two sets
of times. Less extreme cases of non-overlapping times result in a warning.

FAXBARY: Minor bug fixed which caused the script to fail if there was
no GTI extension on the file being barycentered. Also tightened up logic
so that an incomplete output file will not be created if an error occurs.

PCARSP: Added a new command-line option (-s) for "Smart Standard2"
processing. When invoked with this option PCARSP will automatically
determine the relevant detectors and anode chains from the .pha file
and generate an appropriate response file. Fixed "-p all" command-line
option. Added PCARMF version number to the header of the output response
file. Tightened logic so single detector .rsp won't be sent to ADDRMF.
Changed FADDCOL failure (when detectors are not added but .pha file is
not type-II) to a warning.

REX: The internal call to SUMPHA now includes "clobber=yes".

DECODEEVT: Added LONGWARN keyword to the output FITS file header.

FGABOR: A new tool which will perform a Gabor transform on a lightcurve and
return the normalized power as a function of time and frequency.

FXBARY: The ephemeris file used by this tool (de200_new.fits) has now
been extended to dates through the year 2050. (The previous version
only applies up through 31 December 2000; this file is now named
de200_old.fits). Users now have the choice of using FXBARY or the new
tool, FAXBARY (see below), to apply barycenter corrections to their data.


The following new tools and changes to existing tools were previously
released as part of HEAsoft v5.0, Patch 4 (ie, v5.0.4):


  An alternative to FXBARY, FAXBARY is a Perl script which calls a
  standalone program, axBary, and gives it functionality very similar
  to that of FXBARY.  Users are strongly encouraged to use the FAXBARY
  script rather than calling axBary directly.  The parameter list for
  FAXBARY differs from its FXBARY as follows:

                         FXBARY           FAXBARY
                         ------           -------
                         in_file           infile
                        out_file          outfile
                      orbit_file       orbitfiles
                          ra_str               ra
                         dec_str              dec
                         timecol       *NOT USED*
                      start_time       *NOT USED*
                        end_time       *NOT USED*
                       sensecase       *NOT USED*
                      *NOT USED*         refframe

Beyond the changes listed above, the biggest difference in usage is that
the ra/dec parameters in FAXBARY must be given numerically as decimal
degrees. Also the refframe parameter may be used to control whether
the JPLEPH.200 (default) or JPLEPH.405 ephemeris file is used.

The behavior of FAXBARY has been designed to match FXBARY as much as
possible.  As with FXBARY, the value of the TIMEZERO keyword applies
to the BARYTIME column in the output file, thus the barycentric
correction can be derived by simply taking the difference between the
TIME and BARYTIME columns. Note also that because axBary applies the
fine clock corrections (derived from the file tdc.dat located in the
$LHEASOFT/refdata directory) and also accounts for instrumental delay
(both of these effects are ignored by FXBARY) the more precise barycentric
corrections computed by FAXBARY/axBary may differ from FXBARY by as much
as +/- 50 microseconds.

An input list of orbit files is also handled slightly differently by
FAXBARY than by FXBARY. To use more than one orbit file one can either
just enter them directly at the orbitfiles parameter prompt (as a
whitespace separated list) or use the typical ftools @filelist syntax,
where the named file lists the orbit files one per line. Like FXBARY,
FAXBARY will first examine all of the orbit files and reject any which
do not overlap with the times in the datafile to be corrected.  Note,
however, that any list of orbit files MUST be continuous and not contain
any gaps! If this criterion is not satisfied the FAXBARY script will
print an explanatory error message and exit.


These tools now calculate appropriate response matrices for PCU0 following
the loss of the propane veto layer on May 12, 2000.   The date May 13,
2000 marks the start of calibration Epoch 5.   No overall gain adjustment
was made to the PCA: Epoch 5 simply refers to the dates following the
loss of propane in PCU0.

New energy-to-channel file, pca_e2c_e05v01.fits, includes several new
columns used in the improved energy-to-channel algorithm for all PCUs,

 channel = A + B * (E/W(E))+ C * (E/W(E))^2  + D * (E/W(E))^3


    E = energy,
    W(E) = the energy required to create one thermal electron.
           (taken from T.H.V.T. Dias et al. Phys Rev A, 48,
            2887 (1993) and personal communication.)
    (factor of 22 makes the apparent X-axis in XSPEC ~= energy)

    Day_Offset = (Day - Ref_Day) [Ref_Day from parameter file]


    A = PARM1 + PARM5 * Day_Offset + PARM7 * Day_Offset^2
    B = PARM2 + (PARM6 * Day_Offset + PARM8 * Day_Offset^2) * PARM4
    C = PARM3
    D = PARM9

    PARM4 = PARM2(current epoch) / PARM2(epoch 3)

    Currently, the value of PARM9 is zero everywhere.

The model assumes that gain drift can be fit (in epoch 3 space) as the
sum of a linear plus a quadratic term. The entire shift is corrected by
the relative channel/keV term (PARM4).

Additional improvements:

PCARMF v7.10 also includes a fix to a bug found in v7.01 and all previous
versions of the code, which resulted erroneous low energy responses
when choosing  "all" layers.  The patched PCARSP/PCARMF included a
work-around for this bug.  The corrected code is more efficient and
noticeably quicker.

Known features in the response matrices at 5 and 35 keV have reduced
equivalent widths with the new tools.

The spectral index for the Crab pulsar is closer to the canonical value
of 2.1 (the degree of improvement depends on your PCU/layer combination).
For all PCUs, all layers, the Crab pulsar spectral index is now 2.16
(down from 2.2 in the previous version).

PCARSP checks to make sure the appropriate energy-to-channel file is
being requested.  It includes warnings for data taken on May 12, 2000
as the propane was venting PCU0.


The following new tools and changes to existing tools were previously
released as part of HEAsoft v5.0, Patch 2 (ie, v5.0.2):

ASMCHANNEL: Modified to generalize the ASM channel boundaries.

FASEBIN: Corrected a bug which could have caused the tool to fail on
64-bit systems (eg, Alphas).

FBADD/FBFSUM/FBSUB: Fixed a bug which caused these tools to crash on
Linux systems.

FXBARY: Modified handling of TIMEREF and TIMESYS keywords and of multiple
GTIS when called with "barytime=no". Also fixed a bug which was triggered
when a leading "+" was included in the (optional) dec_str parameter.

PCABACKEST: Changed the default value of the "timeslop" parameter to
128 seconds.

RECOFMI: Enhanced to automatically correct day boundary glitches in FMIs
(caused by a bug in the processing pipeline).

REX: Enhanced to use sumpha (see below) in place of MATHPHA. Now also
accepts "A/B" as well as "0/1" to specify the HEXTE clusters.

SAEXTRCT/SEEXTRCT: Modified the handling of the TIMEREF keyword in some
circumstances (see FXBARY, above).

SUMPHA: A new script which calls MATHPHA internally to add pha files
and generates an output file including a merged GTI extension.


If FTOOLS has been useful in your research, please reference this site ( 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: Tuesday, 23-Oct-2007 16:44:01 EDT

HEASARC support for unencypted FTP access will be ending possibly as early as July 31, 2019. Please see this notice for details.