.help ao Oct96 ftools.rosat
.ih
NAME
ao -- Evaluates the geometrical variation of the scattered solar X-ray background
.ih
USAGE
ao obs iflag tlog1 scale1 tlog2 scale2 
.ih
DESCRIPTION
  Program AO uses the methods described in Snowden and Freyberg
  (1993,  ApJ, 404, 403)  
  to estimate the nominal scattered solar X-ray background observed by ROSAT.
  This program organizes the calculation of atmospheric column
  densities along the line of sight of the observation and the
  intensity of scattered solar X-rays from those column densities
  for pointed observations.  It uses the subroutine SSX to calculate
  the scattered solar spectrum.  It also calculates the count rates
  in the seven standard pulse-height bands.  The count rates are not
  normalized but do tend to have required scale factors between 0.1 and 1.
  (The actual  scale  factor is derived  using the program RATE_FIT.)
  AO  is written to use the linear combination of two thermal
  spectra to model the solar spectrum.  The output of AO is used
  by the program RATE_FIT to fit the observation light curve.

  AO creates a list of nominal scattered solar X-ray
  background count rates on the 60-s sample interval of the
  orbit data extension of the RDF xxx_ANC.FITS
  file.  The output is used in the program RATE_FIT
  in conjunction with the output of the program RATE to fit the scattered
  solar X-ray and long-term enhancement background contamination. 

The input file:
.sp
ftp://legacy.gsfc.nasa.gov/caldb/data/gen/bcf/solar_geophys_data_v1.fits
.sp
contains solar and geophysical data which are required for AO and TILT. 

If the observation to be analyzed occurred after
the range of time covered by the file (i.e., if the file has not been
updated recently enough), AO will return a warning.

The AO package uses the following input files.

1)ancillary data fits file for the observation: xxx_ANC.FITS for RDF data
.le
2) Other fixed input : 
.le
valid_times_all.dat
The file valid_times.dat is 
an ascii file; each line in the file consists of a  counter (an integer), begin 
time (an integer), and end time (an integer), where the times are given in terms 
of spacecraft clock time.
This must be the same time selection as used with the programs
CASTDATA, CASTEXP, CASTPART, and LTE.

.le
3) In addition, AO reads the following FITS files from the CALDB database:
On-axis effective area (EFFAAREA), Window transmission (WTRANS),
Gas efficiency (DET_EFF), ROSAT energy grid (ENERGY_GRID),
Solar-geophys-data file (SOLAR_GEOPHYS), Detector response matrix (MATRIX)
and Raymond and Smith thermal spectra (1991 vintage)(RAYMOND_SPECTRA).


The output from the AO package are the following ASCII files.

1) AO_SSX_SC.OUT - nominal SSX count rates on 60-s intervals, used in the
program RATE_FIT. 
.le
2) AO_COL.OUT - column densities of atmosphere constituents on 60-s
intervals.
.fi
.ih
NOTES ON USAGE
.sp
Before running this task user needs to set the CALDB environment
variable in order to access data from the Calibration Database. 
For information on accessing the CALDB, see
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_remote_access.html
to access the HEASARC CALDB remotely, or 
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_install.html
for information on installing a version of the HEASARC CALDB locally.

.ih
PARAMETERS
.ls (obs = "OBS") [string]
Observation identifier, which is the prefix for the filename xxxxxxxx_anc.fits.  Currently obs is limited to 8 characters, so if (for example) you have downloaded the file rp900176n00_anc.fits from the ROSAT archive, you should rename it to rp900176_anc.fits before running AO.  
.le
.ls (iflag = "1") [integer]
Mode control:  IFLAG=1 for simple treatment, 2 for more complete treatment.
The simple treatment assumes that the residual atmosphere of the
observation geometry (both along the line of sight and between the Sun and
positions along the line of sight) is optically thin.  The more complete
treatment uses a nearly complete radiative transfer approach; it considers
absorption between the Sun and a scattering element along the line of sight
and between the scattering element and the satellite.  The simple treatment
runs a couple of orders of magnitude faster and is probably sufficient for all
ROSAT PSPC observations. 
.le
.ls (tlog1 = "6.2") [real]
Temperature  for the first solar component - the intrinsic
solar X-ray spectrum is modelled as two-component thermal plasma emission,
in this case, Raymond and Smith (1977) with the 1991 computer code update.
The program requests the log_10 of the temperature and the scale factor
for each component.  These same temperatures and scale factors must also be
used below in the program TILT for consistency. 
.le
.ls (scale1 = "0.8") [real]
The scale factor for the first solar component.
.le
.ls (tlog2 = "5.7") [real]
Temperature  for the second component -  
Scale factors which sum to one for temperatures near log_10 T of near 6
(e.g., 6.2 0.8 and 5.7 0.2) will give model count rates which are typically
within a factor of a few to ten of the true values (determined later by the
program RATE_FIT). 
.le
.ls (scale2 = "0.2") [real]
The scale factor for the second solar component. 
.le
.ls (caldbdir = " ") [string]
This should be left blank.
If the fixed input FITS files are in a different location than CALDB then
the directory structure can be defined using caldbdir. 
This is mostly for test purposes and should be left unchanged.
.le
.ls (calfexp = "caldb") [string]
Name of calibration information to be used. 
.le
.ls (chatter = "9") [string]
Chatter flag level for the output.
.le
.ih
EXAMPLES

1. For the input file test_anc.fits and for input parameters 
(6.2, 0.8) and (5.7, 0.2) (as the first and second temperatures and 
scale factors respectively), assuming simple treatment (iflag=1) the usage is
.nf

	ft>  ao test 1 6.2 0.8 5.7 0.2

.fi
.ih
BUGS
The "OBS" parameter must be limited to 8 characters.  Versions prior to 
FTOOLS 4.3 required that the input files be in uppercase; this requirement 
was removed in FTOOLS 4.3.  The solar_geophys_data_v1.fits only includes data up to 1995/09/30.
.endhelp
