\input skeleton.tex

\def\version{\it Version 1.24 --- 4/12/90}
\def\chapter{\it Spectral Fitting}

\baselineskip 24pt

\pageno=1001  % force no pagenumber by making pagenumber >999
\count100=\pageno

\font\bigfont = cmr10 scaled 1440
\bigfont

\centerline{}
\vskip 2.truein
\centerline{ROSAT Project Working Document of Science Specifications for the}
\centerline{Post Reduction Off-line Software (PROS)}
\centerline{Spectral Analysis}
\vskip 24pt
\centerline{\version}
\vskip 2.5truein
\hbox{Prepared by: \hfil}
\vskip 24pt
\centerline{Smithsonian Astrophysical Observatory}
\centerline{High Energy Astrophysics Division}
\vfill\eject

\pageno=1001  % force no pagenumber by making pagenumber >999
\count100=\pageno

\centerline{}
\vskip 4.truein
This document describes algorithms implemented in the
spectral-analysis package of the ROSAT/IRAF Post Reduction Off-line
Software (the PROS).  The document was written by
Diana Worrall and Martin Elvis, implemented by Adam Szczypek, Eric
Mandel, Mike VanHilst and John Roll, and it has now become a
`working document' which is under frequent revision.  Please check
with Diana that you have the latest version, and inform her of errors.
\vfill\eject

\baselineskip 18.pt

\pageno=-1
\count100=\pageno

\rm

\def\leaderfill{\leaders\hbox to 1em{\hss.\hss}\hfill}
\centerline{}\vskip 24pt
\bigslant
\centerline{Table of Contents}
\rm


\vskip 18pt
\line{1. Overview \leaderfill 1}
\line{ \quad 1.1 Scientific \leaderfill 1}
\line{ \quad 1.2 Programming \leaderfill 1}
\line{2. Input Data \leaderfill 1}
\line{ \quad 2.1 Observation Data \leaderfill 1}
\line{ \qquad 2.1.1 Requirements \leaderfill 1}
\line{ \qquad 2.1.2 Construct Net-Source-Count Distribution \leaderfill 2}
\line{ \qquad 2.1.3 Include Systematic Errors \leaderfill 2}
\line{ \quad 2.2 Calibration Data Tables \leaderfill 3}
\line{ \quad 2.3 Spectrum Tables \leaderfill 3}
\line{3. Input Options \leaderfill 3}
\line{ \quad 3.1 General \leaderfill 3}
\line{ \quad 3.2 Data Selection \leaderfill 4}
\line{ \quad 3.3 Model Selection \leaderfill 4}
\line{4. Display Data - Graphical \leaderfill 4}
\line{ \quad 4.1 Counts-Space Display \leaderfill 4}
\line{ \quad 4.2 Model-Space Display \leaderfill 5}
\line{ \quad 4.3 $\chi^2$-Space Display \leaderfill 6}
\line{ \quad 4.4 Unit Conversions and Constants \leaderfill 6}
\line{ \qquad 4.4.1 Constants \leaderfill 6}
\line{ \qquad 4.4.2 Wavelength, Frequency and Energy \leaderfill 6}
\line{ \qquad 4.4.3 Flux Density \leaderfill 6}
\line{ \qquad 4.4.4 Distance \leaderfill 7}
\line{5. Generate Spectral Models \leaderfill 7}
\line{ \quad 5.1 Naming Convention for Intermediate Spectrum Arrays \leaderfill 7}
\line{ \quad 5.2 Energy Binning \leaderfill 7}
\line{ \qquad 5.2.1 The {\it Einstein} IPC \leaderfill 8}
\line{ \qquad 5.2.2 The {\it Einstein} MPC \leaderfill 9}
\line{ \quad 5.3 PHA Array, $NPHA$ \leaderfill 9}
\line{ \quad 5.4 Spectrum Arrays, $f(E)$ and $f'(E)$ \leaderfill 9}
\line{ \qquad 5.4.1 Normalization \leaderfill 9}
\line{ \qquad 5.4.2 Emission Measure (for Raymond-Smith Thermal Spectrum) \leaderfill 9}
\line{ \qquad 5.4.3 Calculate Power-Law Emission Spectrum \leaderfill 10}
\line{ \qquad 5.4.4 Calculate Black Body Emission Spectrum \leaderfill 11}
\line{ \qquad 5.4.5 Calculate Exponential Spectrum \leaderfill 12}
\line{ \qquad 5.4.6 Calculate Thermal Bremsstrahlung Emission Spectrum \leaderfill 13}
\line{ \qquad 5.4.7 Calculate Gaunt Factor (Kellogg {\it et al.} Method) \leaderfill 14}
\line{ \qquad 5.4.8 Calculate Raymond-Smith Thermal Plasma Emission
Spectrum \leaderfill 17}
\line{ \qquad 5.4.9 Single Emission Line Spectrum \leaderfill 19}
\line{ \quad 5.5 Apply absorption to spectrum \leaderfill 20}
\line{ \qquad 5.5.1 Standard Absorption $N_H$ (Morrison and McCammon)
\leaderfill 20}
\line{ \qquad 5.5.2 Brown and Gould Absorption,  $N_H$ \leaderfill 22}
\line{ \qquad 5.5.3 Single Absorption Edge \leaderfill 24}
\line{ \quad 5.6 Redshift Spectrum \leaderfill 24}
\line{ \quad 5.7 Find Distance to Source in cm \leaderfill 25}
\line{ \quad 5.8 Combine Models \leaderfill 26}
\line{ 6. Convert Input Spectrum to Predicted PHA Counts \leaderfill 27}
\line{ \quad 6.1 Convert Flux Spectrum to Photons/s/keV \leaderfill 27}
\line{ \quad 6.2 Fold Spectrum through Response Matrix \leaderfill 27}
\line{ \quad 6.3 Renormalize by Exposure Time \leaderfill 28}
\line{ 7. Compare Observed and Predicted Counts and Make Best Fit \leaderfill 29}
\line{ \quad 7.1 Evaluate $\chi^2$ and Normalization \leaderfill 29}
\line{ \quad 7.2 $\chi^2$ minimization search methods \leaderfill 30}
\line{ \qquad 7.2.1 Single Value \leaderfill 30}
\line{ \qquad 7.2.2 Gradient Search 1: Congugate \leaderfill 30}
\line{ \qquad 7.2.3 Gradient Search 2: Fit using simplex method \leaderfill 30}
\line{ \qquad 7.2.4 Grid Search \leaderfill 30}
\line{ 8. Find fluxes and luminosities \leaderfill 32}
\line{ \quad 8.1 Monochromatic Fluxes \leaderfill 32}
\line{ \quad 8.2 Monochromatic Luminosities \leaderfill 32}
\line{ \quad 8.3 Broad-Band Fluxes \leaderfill 33}
\line{ \quad 8.4 Broad-Band Luminosities \leaderfill 33}
\line{ 9. Output Data \leaderfill 34}
\line{ \quad 9.1 Options  \leaderfill 34}
\line{ \quad 9.2 Choice of Units \leaderfill 34}
\line{ \quad 9.3 Values of Parameters \leaderfill 34}
\line{ \quad 9.4 Contour 2-D $\chi^2$ Values from grid search \leaderfill 34}
\line{ \quad 9.5 Data \leaderfill 35}
\line{ \quad 9.6 Fitted Spectrum \leaderfill 35}
\line{ \quad 9.7 Source Data  \leaderfill 35}
\line{ \quad 9.8 Fluxes and Luminosities \leaderfill 35}
\line{ Appendix A \leaderfill 36}
\line{ Appendix B \leaderfill 40}

\vfill\eject

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%                     D.M.W.           January 1988               %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%This document uses macros defined in skeleton.tex.               %
%                                                                 %
%      Automatic numbering of sections goes as follows:           %
%               titles:  \@{title}                                %
%            subtitles:  \**subsections (item form)               %
%         subsubtitles:  \??subsubsections (itemitem form)        %
%                                                                 %
% For unnumbered lists following \** use:                         %
%                   {\list                                        %
%                                                                 %
%                   My first in list; Note that blank lines are   %
%                                                                 %
%                   My second in list;   important                %
%                                                                 %
%                   }                                             %
%                                                                 %
% For unnumbered lists following \?? use:                         %
%                   {\listlist                                    %
%                                                                 %
%                   same idea as above                            %
%                                                                 %
%                   }                                             %
%                                                                 %
%Equations in display mode ($$   $$) should lie outside lists and %
%                                             listlists.          %
% Tables need to \moveright 2\parindent or \moveright 3\parindent %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\baselineskip 12.pt
\pageno=1
\count100=\pageno

\noindent
\@{Overview}

\**Scientific

The aim of the spectral-fitting package is to gain an understanding of the
spectral shape ({\it i.e.}, flux {\it vs} energy) of sources using the pulse
height (PHA) data provided by a detector.  Because proportional counters have
poor energy resolution, the PHA data is a smeared version of the original
(unknown) spectrum.  This smearing makes it very difficult to invert the
PHA data reliably and uniquely back into the spectrum which
is incident on the telescope.  Instead
we make models of possible incident spectra, using the physical processes of which
we know, and see which of these are consistent with the PHA
data that the detector has recorded.

Spectral fitting then proceeds in several major stages:  using a model to
generate the
spectrum incident on the telescope; converting this spectrum into the
appropriate PHA distribution; and comparing this with the
actual data recorded.  This is basically a process of guessing at the
answer and seeing how good the guess was.  We have to keep guessing until we
get a `good enough' (not necessarily the `right') fit between our guess and the actual
data.  The model may be specified with different parameters allowed to vary
(`free' parameters).  There are several ways of finding the `best fit' of
the model parameters to the data.  These search
procedures constitute another major section of the spectral fitting
package.  Development of the spectral-fitting package will proceed for
the {\it Einstein} Observatory IPC, MPC and HRI.  The ROSAT telescope, 
PSPC and HRI responses will be inserted when available.

\**Programming

From a computer operational point-of-view, the package generates a
one-dimensional (model) array of flux values against energy.  This array is the object
of all the following routines.  They read it in, perform an operation on it
and output a modified version of the array.  Most of the operations modify
the flux values ({\it e.g.}, adding components, absorbing).  Redshifting changes
the energy scale; and conversion to PHA changes both fluxes into counts and
energy into PHA channels.  Always, though, it is a transformation of the same
array.  The dimension of the starting array will need to be much larger than
that of the final PHA distribution to allow for the correct handling of sharp
features (emission lines and edges) and redshifts.  We will call this array
`the spectrum' and $f(E)$ (or $f'(E)$) throughout this document.  In
flux {\it vs} energy
space the program will use the units keV cm$^{-2}$s$^{-1}$ keV$^{-1}$.

The conversion between the array element number $i$ and the energy $E$ may not
be linear.  The width of the energy bins may need to depend on energy.  This
dependence is likely to be logarithmic (or $1/E$ or something similar)
for the PSPC so that low energy array elements will cover a
narrower range of energies than high energy elements.

It has been assumed that fast and flexible software will exist for the
extraction of subsets of photons from observations.

\@{Input Data}

\**Observation Data

\??Requirements

{\listlist
Instrument identification

Unique observation identifier

On-source counts and errors in $i$ PHA bins (up to 256 for ROSAT
PSPC), $S_i, \epsilon_{S_i}$

Background counts and errors in $i$ PHA bins, $B_i, \epsilon_{B_i}$

Area used to extract on-source counts (square arcmin), $A_S$

Area used to extract background counts (square arcmin), $A_B$

$(x,y)$ position of source

$\theta$, off-axis angle of source (arcmin)

Livetimes for on-source and on-background, $T_S, T_B$ ({\it i.e.}, the
exposure time corrected for deadtime)

Gain or gain history

Arc-fraction (from ping-counter rate), if response for arcing state available

source name (optional)

observation title (optional)

date, time of observation (optional)

\underbar{Note}: Currently the net counts and errors are input
directly and \S 2.1.2 is not available. Any off-axis
area corrections to the MPC data should be reflected in the live time.
The data display automatically calculates that the background counts
are $B_i = (\epsilon_i^2 - N_i) / [ ( 1 + A_S/A_B) \times A_S/A_B]$,
and assumes $A_S/A_B = 0.8181818$, but the background counts are not
used in the analysis.

}

\??Construct Net-Source-Count Distribution

{\listlist

Net source count in $ith$ pulseheight bin is given by:

}

$$N_i = S_i - {A_S T_S \over A_B T_B} B_i$$

{\listlist

Error in net source count in $ith$ pulseheight bin is given by:

}

$$\epsilon_i = \left[ \epsilon_{S_i}^2 + 
\left({A_S T_S \over A_B T_B} \epsilon_{B_i} \right)^2
\right]^{1/2}$$

\??Include Systematic errors

\itemitem{}Using

{\listlist

(a). Look-up Table for each instrument

(b). Global Fractional error supplied by user

(c). Individual Fractional errors supplied by user

}

\itemitem{}Add to existing error on net counts as follows:

$$\eqalign{{\rm ~~~~~~~~new~error} &= ([{\rm old~error}]^{2} \cr
 ~&+ [({\rm net~PHA~counts})\times({\rm Fractional~Systematic~error})]^{2})^{1/2} \cr}$$


\**Calibration Data Tables

{\list
(See Appendix A)\footnote\dag{The IPC area tables currently available
are those which include scattering assuming the source data are from a
$3'$-radius circle.}

Energy-to-PHA conversion matrix (``response matrix'') for each gain in
both normal and arcing states

Integral Point Response Function ($\%$ of point source
counts within a radius $r$,
arcmin) as a function of energy, $E$, off-axis angle, $\theta$, and (if necessary)
detector coordinates $(x,y)$.

On-axis mirror effective area as a function of energy (cm$^{2}$).

Mirror vignetting factor as a function of off-axis angle and energy.
(includes mirror support strut obscuration, ....)

Energy boundaries between PHA channels (keV) at nominal gain.

}
\**Spectrum Tables

{\list
A file of Raymond-Smith spectrum arrays for selected temperatures for 13
separate elements.
Each array (spectrum) is of size
$n_{max}$-elements (see section on Energy Binning).

Temperatures from 10$^{5}$~K to 10$^{8.3}$~K
in steps of 10$^{0.05}$~keV will be available (67 temperatures),
so that there will be 67 one-dimensional arrays
for a given element (of 13) (see below).

The description of the Raymond-Smith code which generates these tables
can be found in Raymond, J. and Smith B. 1977, {\it Ap.J.Suppl.},
{\bf 35}, 419.

}

\@{Input Options}

\**General

\??Select which of available data sets will be used in fit.

\??Set  up a series of data sets on which to work sequentially, with
identical procedures on each. (User must supply IRAF script.)

\??Set up a series of different fit procedures to follow on a data set or 
list of data sets. (User must supply IRAF script.)

\??Set up screen, hardcopy, filename options for output.

\??Run a spectrum through a chosen instrument response to predict PHA 
distribution without requiring any data. (Not yet available).

\**Data Selection

\??User selects pulseheight channels for each data set: Select either range or individual
channels to use for fit.  Input via:  list; cursor on any spectrum plot; cursor
on screen listing; or via energy boundaries.  For energy boundaries choose only
PHA bins lying at least 70$\%$ within boundaries.  (Not all options yet available).

\??Recompute $\chi^{2}$ for the existing fit parameters given a new
selection of the pulseheight bins.

\**Model Selection

{\list

\underbar{Aim}

User may construct a multi-component spectrum from combinations of
the standard models.

\underbar{Input}

}

{\moveright 2\parindent \vbox{\halign{
# \hfil & # \hfil \cr
Component options &  add a new component \cr
                  & delete a component \cr
                  & set components from stored file (not available)\cr
\noalign{\vskip 12pt}
Model emission options:&  power-law \cr
                       & black body \cr
                       & exponential \cr
                       & thermal bremsstrahlung \cr
                       & Raymond-Smith Thermal plasma \cr
                       & Single line (not yet available) \cr
                       & User specified model (not yet available)\cr
\noalign{\vskip 12pt}
Model Absorption options: & Intrinsic ($z \geq 0$) or Galactic \cr
                          &~~~ ($z=0$) absorption by cold matter \cr
                          &~~~at cosmic abundance using Morrison \cr
                          &~~~and McCammon or Brown and Gould \cr
                          &~~~cross-sections. \cr
                          & Single absorption edge at specified energy\cr
                          &~~and optical depth (not yet available). \cr
                          & User specified model (not yet available). \cr
}}}

{\list

Any combination of the variables may be selected as free parameters.

\underbar{Output}

Selected model components.

\underbar{Specifications}

see above and \S5.

}

\@{Display Data} (Graphical -- For text display see \S9)

\**Counts-Space Display -- Graphical

\??Display raw PHA data:  $y=$ counts, $x=$ pulseheight.  Allow for display of
more than one data set/instrument.

\??Display error bars on the counts data.  This option should be switchable.

\??Display a spectral model folded into counts {\it vs} pulseheight-channel
space.  This should include the complete model or any of its
components.  (\underbar{Note:} Currently models are combined
before folding through response. See \S 5.8.)

\??Display (observed-predicted) counts {\it vs} PHA channel; 
{\it i.e.}, (raw data) -
(predicted counts from spectrum model).

\??Convert either or both axis scales from logarithmic to linear and
back as requested by user.

\??Convert $y$-axis scale to:  counts sec$^{-1}$.

\??Convert $x$-axis scale to:  Energy (keV), Wavelength (\AA), frequency
(Hz).

\??Allow display of a subsection of the data, selectable interactively.

\**Model-Space Display -- Graphical

\??Display incident spectrum (on telescope):
$y=$~keV~cm$^{-2}$~s$^{-1}$~keV$^{-1}$, $x=$~keV.

\??Display the spectrum ``implied'' by the data, with respect to
the model. (Not yet available.) The model folded through the detector response can be
compared with the data in terms of number of standard deviations
difference.  Plot the `implied' incidence spectrum the same number
of standard deviations from the model as it is in counts space, and plot its
error bar $\Delta f$. {\it i.e.},

$$f(implied,E) = f(model, E) \times ({counts(data,E)\over counts(model, E)})$$
$$\Delta f(implied,E) = \Delta c \cdot {f(model,E)\over counts(model,E)},$$

\itemitem{}where

$$\Delta c = {\rm error~on}~counts(data, E)$$

\??Display any (intermediate spectra) of:  initial model emission
spectrum, absorbed source spectrum,
redshifted spectrum.  Each of these should be switchable
on or off.  The display should indicate which spectrum (spectra) are displayed.

\??Display the ``implied'' spectrum relative to any of the
intermediate model spectra. (Not yet available.)

\??Display (``implied''-model) spectra. (Not yet available.)

\??Convert either or both axis scales from logarithmic to linear and back as
requested by user.

\??Convert $y$-axis scale to: (a) different flux density scales: $\mu$Jy, mJy,
Jy, erg cm$^{-2}$s$^{-1}$ Hz$^{-1}$, erg cm$^{-2}$ s$^{-1}$ keV$^{-1}$;
(b) a photon density scale: keV cm$^{-2}$s$^{-1}$ keV$^{-1}$ divided by $x$-axis
value in keV; photons cm$^{-2}$ s$^{-1}$ Hz$^{-1}$; (c) an energy
distribution scale:  any of (a) multiplied by $x$-axis value in Hz for 
$y$-axis in `~Jy', or in keV for
$y$-axis in erg cm$^{-2}$ s$^{-1}$ keV$^{-1}$ and kev cm$^{-2}$ s$^{-1}$ keV$^{-1}$.

\??Convert $x$-axis scale to Hz, \AA.

\**$\chi^{2}$-Space Display

\??One-dimensional displays of $\chi^{2}$ {\it vs} fit parameter value
should be shown.  Several of these plots ({\it e.g.}, one for each fit parameter)
may be requested for display simultaneously.  Critical confidence values
(of $\chi^{2}_{min}+\Delta\chi^{2}$) should be displayed, optionally, for each
plot. (Not available)

\??Two-dimensional contour plots for any two fit parameters should be
available.  Default contours will be plotted at the 68$\%$, 90$\%$, and 99$\%$
confidence levels.
Users may alter the contour levels to be plotted.  The contour-level
values will be displayed.  The best fit point will be plotted.  A `galactic N$_{H}$
value' may be displayed (with an error bar if requested), if supplied, when
N$_{H}$ is one of the two parameters plotted.

\**Unit Conversions and Constants

\??Constants

{\listlist

Values are taken from M. Zombeck, `Handbook of Space Astronomy and Astrophysics', 2nd
edition (Cambridge University Press, 1988).

}

$$\eqalign{c&=2.99792458 \times 10^{10}~{\rm cm~s}^{-1} \cr
h&= 6.6260755 \times 10^{-27}~{\rm ergs~s} \cr
k&= 1.380658 \times 10^{-16}~{\rm ergs~K}^{-1} \cr }$$

\??Wavelength, Frequency, and Energy Equivalence

$$\eqalign{1~{\rm keV} &: 2.418 \times 10^{17}~{\rm Hertz~(Hz)} \cr
~&: 12.398~{\rm Angstrom~(\AA)} \cr
~&: 8.066 \times 10^6~{\rm cm}^{-1} \cr
~&: 1.1605 \times 10^{7}~{\rm (K)} \cr}$$

\??Flux Density

$$\eqalign{1~{\rm ergs~cm}^{-2} {\rm~s}^{-1}~{\rm keV}^{-1} &
= 4.14 \times 10^{5} {\rm Jansky~(Jy)} \cr
~&= 4.14 \times 10^{-21}~{\rm  W~m}^{-2}~{\rm Hz}^{-1} \cr
1~{\rm keV~cm}^{-2}~{\rm s}^{-1}~{\rm keV}^{-1} &= 662.5~\mu {\rm Jy} \cr
1~{\rm Jy} &= 10^{-23} {\rm erg~cm}^{-2}~{\rm  s}^{-1}~{\rm Hz}^{-1} \cr
~&= 10^{-26}~{\rm W m}^{-2} {\rm Hz}^{-1} \cr
1~{\rm mJy} &= 10^{-3}~{\rm Jy} \cr
1~\mu{\rm Jy} &= 10^{-6} {\rm Jy} \cr
1~{\rm photon~cm}^{-2}~{\rm s}^{-1}~{\rm keV}^{-1} &=
{1~{\rm keV~cm}^{-2}~{\rm s}^{-1}~{\rm keV}^{-1}
\over ({\rm Energy~of~photon,~keV})} \cr}$$

\??Distance

{\moveright 3\parindent \vbox{\halign{\indent#\hfil&\quad$#$\hfil\cr
  1 AU          &= 1.495 \times 10^{13} {\rm ~cm~(Astronomical Unit)} \cr
  1 light year  &= 9.460 \times 10^{17} ~{\rm cm} \cr
  1 parsec (pc) &= 3.086 \times 10^{18} ~{\rm cm} \cr
  1 kpc         &= 10^{3}~{\rm pc} = 3.086 \times 10^{21}~{\rm cm} \cr
  1 Mpc         &= 10^{6}~{\rm pc} = 3.086 \times 10^{24}~{\rm cm} \cr
  1 km          &= 10^{5}~{\rm cm} \cr }}}

\@{Generate Spectral Models}

\**Naming Convention for Intermediate Spectrum Arrays

{\list

Each step from generating the emission spectrum to producing a predicted
array of PHA counts generates a different spectrum array of potential
scientific value.  It is helpful to have a convention to refer to each of
these spectra.

We will use the following:

}

{\moveright 2\parindent \vbox{\halign{#\hfil&\quad#\hfil\cr

Emitted: &Pure emitted spectrum, no absorption. $f'(E)$ \cr
At-Source:&Emitted spectrum after intrinsic absorption is applied. $f_a'(E)$\cr
Redshifted:&At-Source spectrum redshifted to observed frame. $f(E)$\cr
Incident:&Redshifted spectrum with local galactic absorption \cr
        ~& applied, {\it i.e.}, as incident onto the front of\cr
        ~& the telescope. $f_a(E)$\cr }}}
{\list

The emitted and at-source spectra are both in the ``source'' frame and
will have a prime superfix in this document, ({\it i.e.}, $f'$ and $f_a'$).

The emitted spectrum redshifted to the observed frame, but with no
absorption (see ``redshifted spectrum'', above), will be called $f(E)$.

The incident spectrum is $f_a(E)$.

}

\**Energy Binning

{\list

Currently, the photon spectrum is calculated in energy bins which
are independent of redshift ({\it i.e.} a photon spectrum is
redshifted by re-distributing photons over array elements).   We may
wish to change this so that the energy-bin boundaries are determined
by the full energy range of the detector(s) (finer 
than the PHA bins) and increase by (1 + z) at the source. 
The advantages are that no re-distribution errors are then 
introduced, and the energy band over which the source spectrum is
defined is forced to be appropriate for the detector(s). 
The calculations of the model normalizations and the redshifting routine
will need appropriate modification.  [Note, however, that a fine bin
at the detector centered around 6.7 keV, for example, will not 
necessarily imply a fine bin centered around 6.7 keV in the 
source frame.] 
If we do implement the new binning scheme, then we cannot use 
the pre-computed Raymond-Smith (RS) Thermal model, which
is pre-computed with fixed bin boundaries corresponding to those
hardwired in our code for the model spectrum.
For models such as the RS, with narrow lines, a solution for the future
may be to have the RS model pre-computed as a smooth continuum with
fixed energy bins (as now) defined in the observer frame.
The continuum model would be interpolated (not shifted) to make
it appropriate for the 
energy bins of the source frame.  However, there would be 
a list of discrete lines which would not actually be 
introduced into the model until the shift to the observed frame. 

}

\??The {\it Einstein} IPC.

{\listlist

Fluxes will be stored in an array of
$n_{max}$ energy elements.  $n_{max}=125$ is appropriate for the
{\it Einstein} IPC (except for $z \simgreat 2$) and will probably
apply to the ROSAT PSPC too. In fact, $n_{max}=180$ is used --- see \S 5.2.2.

The width of each element $\Delta E$ will be proportional to energy;
thus:

}

$$\Delta E = {\rm (constant)} \times E~{\rm keV}$$

{\listlist

constant = 0.046 is appropriate for the {\it Einstein}
IPC.  A smaller value by
$\sim$2 may be needed for the ROSAT PSPC.

The central energy of the lowest and
upper energy bins ($E_{min}, E_{max}$) for the
spectrum for the {\it Einstein} IPC will therefore be

}

$$E_{min} = 0.0316~{\rm keV}$$
$$E_{max} = 9.55~{\rm keV};  n_{max}=125$$
{\listlist

The energy of the $nth$ bin is 10$^{[0.02(n-1)-1.5]}$ keV.

Similar values can be derived for the ROSAT PSPC.

These values are to some extent arbitrary and designed for ease of
computation.

Values appropriate to each instrument that the software can handle (i.e.,
for which it has access to response matrices) should be stored.  The
program will select the appropriate set of values given the instrument
information in each data file.

(Bins will be at the same energy for all spectra, for a given instrument.)

If the incident spectrum has contributions from $E_{i}$ to $E_{u}$ keV, the
value of $E_{max}$ must be larger than $(1+z)E_{u}$ for the largest
appropriate z.

}


\??The {\it Einstein} MPC.

$$E_{min} = 0.0316~{\rm keV}$$
$$E_{max} = 120.23~{\rm keV};  n_{max}=180$$

\**PHA Array, $NPHA$

{\list

The predicted count distribution will be called the PHA array or $NPHA$.

The energy boundaries of the pulseheight bins will be determined by the instrument
and its gain.

The mapping from energy to pulseheight will be
made through a `response matrix'. see \S6.2.

}

\**Spectrum Arrays, $f'(E)$ and $f(E)$

\??Normalization

{\listlist

\underbar{Definition}\footnote\dag{The normalization is defined
differently from the M600/FINSPEC program for all but the power-law model}

The normalization is the monochromatic flux density of the observed spectrum
at 1~keV before any absorption ({\it i.e.}, the redshifted spectrum),
in units of keV cm$^{-2}$ s$^{-1}$ keV$^{-1}$
(``$A$'' in all emission spectrum specifications).
The user will specify a value of $A$ as an
input parameter.  This will either be fixed or a new best-fit value will be
returned by the program.  Where multiple models are used,
normalizations are expressed as a fraction of that of the first model.
The user will specify values of $A_1, A_2, \ldots$ such that
$f = A_1 (f_1 + A_2 f_2 \ldots)$.  The 1~keV flux density for model~2
will be $A_1 \times A_2$.

\underbar{Note}:  Does not apply to Raymond-Smith spectrum which
uses ``emission measure'' instead, or to the single emission line,
which uses equivalent width.

}

\??Emission Measure (for Raymond-Smith Thermal Spectrum)

{\listlist

\underbar{Definition}

The Raymond-Smith thermal spectrum has many sharp features (emission
lines and edges) that change radically in strength with temperature.
In this case the monochromatic flux at 1~keV, which is used as a normalization
for the other, analytic, spectral forms, is inappropriate.  If an
emission line happens to fall at 1~keV, the `normalization' would be
very different from that at 1.05~keV.  Instead a quantity is used called the
`emission measure'.

The auxilliary Raymond-Smith code pre-computes tables of
$\Lambda(E_{u}, E_l, Z(13), T')$ 
in 10$^{23}$ erg cm$^{3}$ s$^{-1}$ for an energy bin ranging from
$E_{l}$ to $E_{u}$ and of central energy $E$.  Here, $T'$ is the temperature
of the plasma in the source frame in Kelvin, and $Z(13)$ refers to 13
different elements.
The Raymond model combines the $\Lambda(E, Z(13),T')$ values for the 13 elements
according to the parameter-values of the abundance decrement, r, and
the choice between cosmic and solar abundances to give  $\Lambda(E,T')$.

For some $T'$, the emitted spectrum is,
}

$$\eqalign{f'(E) &= 
10^{-23}\cdot{n_{e}n_{h} V\over 4\pi
D^{2}}\cdot\Lambda(E)\cdot\Delta E^{-1} \cr
~&=
 A.~\Lambda(E).~\Delta E^{-1} 10^{-23} /1.602\cdot10^{-9}\cr
~&~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{\rm keV~cm}^{-2}~{\rm s}^{-1}~{\rm keV}^{-1} \cr}$$

{\moveright 3\parindent \vbox{\halign{\hfil#&#\hfil\cr
where, $EM$ &= $n_e n_h V$ is called the `emission measure' \cr
($n_e$ &= electron density, cm$^{-3}$; $n_{h}$ = hydrogen density, cm$^{-3}$; \cr
$V$ &= emitting Volume, cm$^{3}$) \cr
$EM$ &$\Lambda (E)$ is the source luminosity in ergs s$^{-1}$ \cr
$D$ &is the luminosity distance to the source (see \S5.7), cm, \cr
&so $4 \pi D^2$ is the area of a sphere surrounding the source at \cr
&our distance $D$ from it, cm$^{2}$. \cr
$E$ &is the central energy of the bin, keV \cr
$\Delta E$ &is the energy bin width, $E_u - E_l$, keV \cr
$f'(E)$ &is then the flux from the source in keV cm$^{-2}$ s$^{-1}$ keV$^{-1}$ \cr}}}

{\listlist

The `normalization' $A = { EM \over 4 \pi D^2}$ in
cm$^{-5}$.

}

\??Calculate Power-Law Emission Spectrum

{\listlist

\underbar{Aim}

Produce array, $f'(E)$.  Emitted spectrum.

\underbar{Input Parameters}

}

{\moveright 3\parindent \vbox{\halign{\indent\hfil#&#\hfil\cr
z = &redshift of source \cr
$\alpha$, = &power law energy index \cr
$E_n$ = &Array of energies of the $n$ bins \cr
$A$ = &Flux density of observed spectrum at 1 keV before any \cr
~& absorption, in keV cm$^{-2}$s$^{-1}$keV$^{-1}$.\cr}}}

{\listlist

No calibration data are needed.

\underbar{Output}

$f'(E)$

Normalization (Norm) expression specified here.  Evaluated in \S7.1.

\underbar{Specification}

By definition $f(E) = AE^{-\alpha}$

using \S5.6, $f'(E) = (1+z)^{-1} f(E/1+z)$

therefore, $f'(E) = A(1+z)^{(\alpha-1)}E^{-\alpha}$

Note that if $z=0,~f'(E) = AE^{-\alpha} = f(E).$

The trial form will be $E^{-\alpha}$

$f'(E) = {\rm Norm}~E^{-\alpha}$

where ${\rm Norm} = A(1+z)^{(\alpha-1)}$.

}

\??Calculate Black Body Emission Spectrum

{\listlist

\underbar{Aim}

Produce array $f'(E)$

\underbar{Input Parameters}

}

{\moveright 3\parindent \vbox{\halign{\indent\hfil#&#\hfil\cr
$z$ = &redshift of source \cr
$T'$ = &temperature in the source frame in keV \cr 
$E_n$ = &array of energies of the n bins \cr 
$A$ = &flux density of observed spectrum at 1 keV before any \cr 
& absorption in keV cm$^{-2}$s$^{-1}$keV$^{-1}$ \cr}}}

{\listlist
 
No calibration data are needed.

\underbar{Output}

$f'(E)$

Normalization (Norm) expression specified here. Evaluated in \S7.1.

\underbar{Specification}

by definition $f'(E) = A'({E^{3}\over e^{E/T'}-1})$

Need to write $A'$ in terms of $A$

}

$$f(E) = (1+z)f'((1+z)E)$$
$$f(E) = (1+z)A'{(1+z)^3 E^3 \over e^{(1+z)E/T'}-1}$$
 
\itemitem{}by definition, $f(E) = A$ when $E = 1$

$$A' = {A\over (1+z)} [{e^{(1+z)/T'}-1\over (1+z)^{3}}]$$
$$f'(E) = {A[e^{(1+z)/T'}-1]\over (1+z)^{4}} ({E^{3}\over e^{E/T'}-1})$$
 
\itemitem{}The trial form will be ${E^{3}\over (e^{E/T'}-1)}$

$$f'(E) = {\rm Norm} {E^{3}\over (e^{E/T'}-1)}$$
 
\itemitem{}where,~~~Norm = ${A[e^{(1+z)/T'}-1]\over (1+z)^{4}}$

\??Calculate Exponential Spectrum

{\listlist

\underbar{Aim}

Produce array $f'(E)$

\underbar{Input Parameters}

}

{\moveright 3\parindent \vbox{\halign{\indent\hfil#&#\hfil\cr 
$z$ = &redshift of source \cr 
$T'$ = &temperature in the source frame in keV \cr 
$E_n$ = &array of energies of the $n$ bins \cr 
$A$ = &flux density of observed spectrum at 1 keV before any \cr 
& absorption in keV cm$^{-2}$s$^{-1}$keV$^{-1}$ \cr}}}

{\listlist
 
No calibration data are needed.

\underbar{Output}
 
$f'(E)$

Normalization (Norm) expression specified here. Evaluated in \S7.1.

\underbar{Specification}
 
By definition $f'(E) = A'(\exp(-{E\over T'}))$

need to write $A'$ in terms of $A$

}

$$f(E) = (1+z)F'((1+z)E)$$
$$f(E) = (1+z)A'e^{-(1+z)E/T'}$$

\itemitem{}by definition $f(E) = A$ when $E = 1$

$$A' = {A\over (1+z)} e^{(1+z)/T'}$$
$$f'(E) = {A e^{(1+z)/T'} e^{-E/T'}\over (1+z)}$$

\itemitem{}The trial form will be $e^{-E/T'}$

$$f'(E) = {\rm Norm}~e^{-E/T'}$$

\itemitem{}where,~~~Norm = ${A e^{(1+z)/T'}\over 1+z}$

\??Calculate Thermal Bremsstrahlung Emission Spectrum

{\listlist 
 
Note: This is equivalent to the Exponential spectrum multiplied by the
Gaunt factor.
                                                                                                                                    
\underbar{Aim}

Produce array $f'(E)$

\underbar{Input Parameters}

}

{\moveright 3\parindent \vbox{\halign{\indent\hfil#&#\hfil\cr 
$z$ = &redshift of source \cr 
$T'$ = &temperature in the source frame in keV \cr 
$E_n$ = &array of energies of the $n$ bins \cr 
$A$ = &flux density of observed spectrum at 1 keV before any \cr 
&~~~absorption in keV cm$^{-2}$s$^{-1}$keV$^{-1}$ \cr
$g(E,T')$ = &Gaunt factor averaged over the average Maxwellian \cr
&~~~velocity distribution (see \S 5.4.7)\cr}}}

{\listlist
 
No calibration data are needed.

\underbar{Output}

$f'(E)$

Normalization (Norm) expression specified here. Evaluated in \S7.1.

\underbar{Specification}

By definition, $f'(E) = A' \exp \left( - {E \over T'} \right) g(E,T')$

need to write $A'$ in terms of $A$

}

$$f(E) = (1+z)f'((1+z)E)$$
$$f(E) = (1+z)A'e^{-(1+z)E/T'} g[(1+z)E, T']$$

\itemitem{}by definition $f(E) = A$ when $E = 1$

$$A' = {A \over {(1+z)g[(1+z),T']}} e^{(1+z)/T'}$$
$$f'(E) = {A e^{(1+z)/T'} g(E,T') e^{-E/T'}\over {(1+z)g[(1+z),T']}}$$

\itemitem{}The trial form will be $g(E,T')~e^{-E/T'}$

$$f'(E) = {\rm Norm}~g(E,T')~e^{-E/T'}$$

\itemitem{}where,~~~Norm = ${A e^{(1+z)/T'} \over {(1+z) g[(1+z),T']}}$

\??Calculate Gaunt Factor: (1) Kellogg {\it et al}. method

{\listlist
 
\underbar{Aim}

Calculate the Gaunt Factor $g(E,T')$ for thermal bremsstrahlung
using the results of Karzas W.~and Latter R.~(1961, Ap.J.Suppl., 
\underbar{6},
167) as approximated in Kellogg E., Baldwin J.R., and Koch, D.~(1975,
Ap.J., \underbar{199}, 299) by polynomials, or as approximated by
Kurucz (1970, SAO Special Report no.~309, p77) outside the range
handled by KBK.  Corrections are described in Appendix~A of Molnar
{\it et al.}~(1988, Ap.~J., Submitted).

\underbar{Input}

$T'$, source temperature, keV.

$E$ = a given energy

$HEB$ = Helium to Hydrogen abundance

\underbar{Output}

$g(E,T')$, Gaunt factor.

\underbar{Specification}

The function FBG in Appendix A of Kellogg {\it et al.}, as written,
returns FBG($E,F,Q,C$) for a hydrogen plasma.  The input parameters are
$E$=energy, $F$= normalizing factor, $Q=$ temperature in keV = $T'$,
and $C$= factor related to the amount of galactic absorption to be
applied.  The output is FBG=$g(E,T') e^{-E/T'} \times$ absorption.

We require something a little different from FBG as written.

(1).We are applying absorption separately, and so must take out the
absorption term from FBG.  We don't need the parameter $C$ in the
calling sequence.

(2). We don't wish to include the term $e^{-E/T'}$, which we will
apply separately.

(3). $F$ will be unity in the calls, and can be removed.

(4). We want to allow for a percentage of the gas having atomic
number 2 (helium).  This will make our routine similar to that used by
the GSFC group and subsequently adopted in the XSPEC/XANADU
(EXOSAT) software, except that we will allow the user to modify the
He/H abundance ratio. We have the parameter $Z$ in the call of FBG.

(5). We will make 3 corrections given by Molnar {\it et al.} 1988
(Ap.~J., Submitted).  (a). We will replace the 39th, 81st and 123rd cooeficients
in the data array (0.8363, 1.398, -0.8414) with (1.020, 0.6017,
-0.2270).
(b). If $U<0.003$, we will use the correction we would compute for
$U=0.003$, and apply this to the Born
approximation for $U$.
(c). If $GAM1 > 100$, rather than
jumping to $G=1$, we will use bilinear interpolation of the tables
from Kurucz (1970), correcting the entries in the $\log U = 0.5$ row.

Our new FBG is like that in Kellogg {\it et al.} except
for the following lines:

\qquad  FUNCTION FBG($E,Q,Z$) [$E$=energy, $Q=T'$, $Z=$atomic number]

3 values in the data statement are changed (see 5a above)

the 1st line below the data statements is now:

\qquad  $GAM=Z*Z*0.01358/Q$

the 3rd line below the data statements is now:

\qquad IF ($GAM1$.GT.$100.0$) THEN

\qquad\qquad $U = EKEV/TKEV$

\qquad\qquad $GAM1 = GAM1/1000.0$

\qquad\qquad CALL KURUCZ($U, GAM1, G1$)

\qquad\qquad $FBG = G1$

\qquad\qquad RETURN

\qquad ENDIF

The statement, IF ($U$.LT.$0.003) \ldots $, in
the compute polynomial section must be changed to:

\qquad IF ($U$.LT.$0.003) U=0.003$

\qquad IF ($U$.LT.$0.003) U2=U * U$

The last 11 lines of the program reduce to:

\quad 700  FBG = $G$

\qquad     RETURN

\qquad      END

The call is:

$g(E,T') = {{\rm FBG}(E,T',1) + 4 \times HEB \times {\rm FBG}(E,T',2) \over
1 + 2 \times HEB}$

where $HEB$ is the Helium to Hydrogen abundance, which should be a
hidden parameter, but one which the user could change, if required.
The default should be 0.085.  With this default our
routine will be equivalent to the GSFC and XSPEC codes, except for (5) above.

}
{\listlist

Note that the FBG and KURUCZ routines only give sensible results for
$U \simless 50$.  At larger values of $U$ the returned Gaunt factor
either
gets very large (for high temperatures) or becomes negative (for low temperatures).
However, large values of $U$ cause a negligible model contribution
anyway (because of the $\exp (-U)$ term in the model).  Therefore, a satisfactory
solution
to the problem is, inside the gaunt-factor routines, to set:

\qquad IF ($U$.GT.$50.0) U=50.0$

} 

\par\vfill\eject
 
\??Calculate Raymond-Smith Thermal Plasma Emission Spectrum

{\listlist
 
\underbar{Aim}

The aim is to produce an array $f'(E)$, the emitted spectrum.
Pre-computed
values from a table are combined according to the value of the
`abundance choice' (a choice of `cosmic' or `solar') and $r$, the
percentage decrement. $r$ is the
percentage of all elements other than Hydrogen and Helium relative
to Hydrogen and Helium, using either cosmic or solar standards.
[Note that the tables give pre-computed model values for all 13
elements
separately, and so we could set up a model with 13 parameters in which
the user could individually set abundance values.  This is only
necessary for detectors with high resolution, and so such a cumbersome
model will not be defined at this time.]
The pre-computed tables have been made by auxilliary (non IRAF) code
and are set to exactly match our model bins.  No interpolation of the
tables is required.  However, if the source is
at non-zero redshift, photons will be redistributed during the
redshifting process, possibly leading to degredation of sharp features.


\underbar{Input Parameters}
 
$\Lambda(E_u,E_l,Z(13),T') =$ pre-computed arrays of luminosity
$\times$ volume {\it vs} energy, for temperatures from 10$^{5}$ K to
10$^{8.3}$ K and energy bins matched to the model bins.

$T'$ = temperature of plasma in the source frame in Kelvin, (values from 10$^{5}$ to
10$^{8.3}$ allowed)

abundance choice = choice of abundances. Current choices are `cosmic' or
`solar'.

$r$ = abundance decrement expressed as a fraction.
 
$A$ = normalization = (emission measure/4$\pi$D$^2$) (see \S5.4.2).

\underbar{Output}

$f'(E)$ = flux density as a function of energy (i.e., the spectrum) in
keV cm$^{-2}$ s$^{-1}$ keV$^{-1}$

\underbar{Specification}
 
Given `abundance choice' (`cosmic' or `solar') and $r$, for any $T'$ and energy bin, read
the pre-computed
tables,  $\Lambda(E_u,E_l,Z(13),T')$, and produce
$\Lambda(E, T')$ as follows:

The 13 tables for $\Lambda(Z(13))$, which we will write as
$\Lambda_i$, $i=1-13$, are computed assuming each element
in turn is the only one, and has an abundance (by number) of 1.0.
According to which of the 2 options for `abundance choice' is specified,
we read one set of the 13 abundances given in Table 5.4.8
into a 1-dimensional array of size 13, $Q_i, i=1-13$. Since the values
for $Q_i$ (Table 5.4.8) are expressed logarithmically on a scale for
which H is 12.0 ({\it e.g.}, the number abundance of He relative to H in the
`cosmic' case is 0.085), 

}

$$\Lambda = \sum_{i=1}^2 \Lambda_i 10^{(Q_i - 12)}  +
\sum_{i=3}^{12}  r \Lambda_i 10^{(Q_i - 12)}$$

{\listlist

Defining $E$ as the central energy of the bin ranging from $E_l$ to $E_u$,
and $\Delta E=E_u - E_l$,

}

$$f'(E) = {\rm Norm}~10^{-23} \Lambda(E, T')\Delta
E^{-1} / 1.602 \times 10^{-9}$$

{\listlist

where ${\rm Norm} = A =$ (emission measure $/ 4\pi D^2),
~D =$ luminosity distance (cm).

}


\par\vskip 0.5truein
\noindent
\underbar{Table 5.4.8}
 
\centerline{\underbar{Abundances for use in Raymond-Smith Spectrum}}

\halign{\indent#\hfil&\qquad\hfil#&\qquad\hfil#\cr

\underbar{Element}&\underbar{log number abundance + 12.0}\span\omit\cr
~&\underbar{Cosmic}$^{1}$&\underbar{Solar}$^{2}$\cr\noalign{\medskip}
H&12.00&12.00\cr
He&10.93&11.04\cr
C&8.52&8.68\cr
N&7.96&7.93\cr
O&8.82&8.93\cr
Ne&7.92&8.11\cr
Mg&7.42&7.61\cr
Si&7.52&7.55\cr
S&7.20&7.22\cr
Ar&6.90&6.42\cr
Ca&6.30&6.37\cr
Fe&7.60&7.51\cr
Ni&6.30&6.30\cr }

\noindent
\underbar{refs.}

\item{1.} Allen (1973), Astrophysical Quantities.
 
\item{2.}Meyer, J.P. (1979), in {\it Comm 22nd Colloque International
d'Astrophysique}, Li\'ege, {\it Les El\'ements et leurs Isotopes dans 
L'Univers}, page 153.
\par\vfill\eject
 
\??Single Emission Line Spectrum (not available)

\vfill\eject

%{\listlist
% 
%\underbar{Aim}
%
%Produce array $f'(E)$
%
%\underbar{Inputs Parameters}
%
%$E'_{line}$ = energy of line center in the source frame, keV
% 
%$\Delta E'$ = full width at half maximum of line in source frame, keV
%
%$A$ =  normalization, which is to be defined as the equivalent
%width of the line {\it i.e.}, kev cm$^{-2}$ s$^{-1}$ in the line
%divided by the flux density at $E'_{line}$.
%
%\underbar{Output}
%
%$f'(E)$
% 
%\underbar{Specification}
%
%We will use the trial form:
%
%}
%
%$$f(E') = {{\rm Norm}\over \sigma \sqrt{2\pi}} \exp \left[-{1\over 2}
% \left({E'-E'_{line}\over \sigma}\right)^{2}\right]$$
%
%\itemitem{}where
%
%$$\sigma = {\Delta E' \over 2 \sqrt{2 \ln 2}}$$
%
%{\listlist
%
%Every detector will have some resolution such that an infinitely
%narrow line
%has some width given by $\Delta E_{det}$.  Therefore, we will set,
%
%}
%
%$$\sigma_{min} = {\Delta E_{det} (1+z) \over {2 \sqrt{2 \ln 2}}}$$
%
%{\listlist
%
%The Norm defined above is equivalent to the energy cm$^{-2}$ s$^{-1}$
%in the line.  In order to get the value for $A$ as defined we must
%use,
%
%}
%
%$$A = {{\rm Norm} \over f'_{cont}(E'_{line})}$$
%
%{\listlist
%
%where $f'_{cont}$ is the emitted flux density from everything but the
%line itself.
%
%}

\**Apply absorption to spectrum

\??Standard Absorption N$_{H}$(Morrison and McCammon)

{\listlist

\underbar{Aim}

Calculate an absorption factor, $\Theta (E)$, as a function of input energy for cold
material at cosmic abundance with a total column density of hydrogen $N_H$
atoms cm$^{-2}$.  Using the cross-sections, $X(E)$, given by Morrison and McCammon
(1983, Ap.J., \underbar{270}, 119).  Multiply the absorption factor by the input
spectrum to derive an absorbed spectrum.
 
\underbar{Note}:  Absorption may be applied either before or after redshifting.

This may be applied to $f'(E)$ or $f(E)$.

\underbar{Input Parameters}

$N_H$, total hydrogen column density, atom cm$^{-2}$
 
$f(E)$, flux density versus energy [units]
 
$c_0, c_1, c_2 (E_i, E_{i\pm1}$) = table of coefficients of
piecewise polynomial fit to absorption cross-section in selected energy
ranges (see Table 5.5.1)

\underbar{Output}

$f_{a}(E), {\rm absorbed~spectrum} = f(E)\Theta(E)~{\rm or}~f_{a}^{\prime}(E)
 = f^{\prime}(E)\Theta(E)$
 
$\Theta (E)$, absorption factor {\it vs} energy

\underbar{Specification}
 
Use cross-section $X(E)$ given from analytic fit using coefficients $c_0,
c_1, c_2$ in Table 5.5.1.
 
$X(E) = (c_0 +c_1 E+c_2 E^2) E^{-3} \times 10^{-24}~{\rm cm}^{2} (E$ in keV)

$\Theta(E) = e^{-X(E) N_H}$ for each energy in the array
 
$f_a(E) = f(E)\Theta (E)$ or $f_{a}^{\prime}(E) = f'(E)\Theta (E)$

}

\vskip 18pt

{\listlist

A Compton-scattering term (not yet included) will modify $X(E)$ as
calculated
above so that

}

$$X(E) = X(E) + \kappa(E) 1.21 \times 0.665 \times 10^{-24}$$

\itemitem{}Here $\kappa(E) = \sigma(E)/\sigma_T$, the Compton Cross Section
relative to $\sigma_T$, and the value of 1.21 is the value of
$\sum {{N_Z Z} \over N_H}$ given by the Morrison and McCammon abundances.

\itemitem{}Molnar {\it et al.} (1988) (Ap.J. to be submitted), find a quadratic
approximation to $\kappa(E)$ which is good up to about 37 keV.  Above
this,
the full Klein-Nishina cross section as  given by Rybicki and Lightman
(1979),
page 197, should be used.

$$\kappa = 1- 2X + {26 X^2 \over 5} ~~~~~~~~{\rm quadratic~~approximation}$$

$$\kappa = {3 \over 4} \left[ {{1+X} \over x^3} \left( {{2 X (1+X)} \over
{1+ 2X} } - \ln (1 + 2X) \right) + {1 \over {2X}} \ln (1+2X)
- {{1+3X} \over (1+2X)^2} \right]$$

\itemitem{}where, with $E$ in keV,

$$X = {E \over 511.0}$$

\centerline{}
\vskip 18pt 
\centerline{\underbar{Table 5.5.1 Coefficients of Analytic Fit to Cross Section}}

{\moveright 3\parindent
\vbox{\halign{\indent#\hfil&\qquad\hfil#&\qquad\hfil#&\qquad\hfil#\cr 
Energy Range (keV)&c$_{0}$\hfil&c$_{1}$\hfil&c$_{2}$\hfil\cr\noalign{\medskip} 
$<$ 0.100$^{a}$&17.3&608.1&-2150.00 \cr
0.100 -- 0.284&34.6&267.9&-476.10 \cr
0.284 -- 0.400&78.1&18.8&4.30 \cr
0.400 -- 0.532&71.4&66.8&-51.40 \cr
0.532 -- 0.707&95.5&145.8&-61.10 \cr
0.707 -- 0.867&308.9&-380.6&294.00 \cr
0.867 -- 1.303&120.6&169.3&-47.70 \cr
1.303 -- 1.840&141.3&146.8&-31.50 \cr
1.840 -- 2.471&202.7&104.7&-17.00 \cr
2.471 -- 3.210&342.7&18.7&0.00 \cr
3.210 -- 4.038&352.2&18.7&0.00 \cr
4.038 -- 7.111&433.9&-2.4&0.75 \cr
7.111 -- 8.331&629.0&30.9&0.00 \cr
$>$ 8.331&701.2&25.2&0.00 \cr}}}


\itemitem{a.}Break introduced to allow adequate fit with quadratic:  no absorption
edge at 0.1 keV.

\hrule


Note:  Care must be taken at the edges (discontinuities in the analytic fit)
to include the correct fraction from each side of the edge in the energy bin of the
array $X(E).$

\par\vfill\eject

\??Brown and Gould Absorption, $N_H$

{\listlist
 
\underbar{Aim}

Calculate an absorption factor, $\Theta (E)$, as a function of input energy
for cold material at cosmic abundance with a total column density of hydrogen
$N_H$ atoms cm$^{-2}$.  Using the cross-sections, $X(E)$, given by (Brown and 
Gould 1970, Phys.~Rev.D., \underbar{1}, 2252).  Multiply the absorption factor by
the input spectrum to derive an absorbed spectrum.

\underbar{Note}:  Absorption may be applied either before or after redshifting.
 
This may be applied to $f'(E)$ or $f(E)$

\underbar{Input Parameters}

$N_H$, total hydrogen column density, atom cm$^{-2}$

$f(E)$, flux density {\it vs} energy [units]

$c_0, c_1, c_2 (E_i, E_{i\pm1}$) = table of coefficients 
of piecewise polynomial fit to absorption cross-section in selected energy
ranges (see Table 5.5.2).
 
\underbar{Output}

$f_a (E)$, absorbed spectrum = $f(E) \Theta (E)$ or $f_a'(E) = f'(E)\Theta(E)$
 
$\Theta (E)$, absorption factor {\it vs} energy
 
\underbar{Specification}
 
Use cross-section $X(E)$ given from analytic fit using 
coefficients $c_0, c_1, c_2$ in Table 5.5.2.

$X(E) = (c_0 \times (c_1/ E )^{c_2}) \times 10^{-21}$ cm$^{2} (E$ in eV)
 
$\Theta(E) = e^{-X(E)N_{H}}$ for each energy in the array
 
$f_{a}(E) = f(E)\Theta(E)$ or $f_{a}^{\prime}(E) = f'(E)\Theta(E)$

}

\vskip 18pt

{\listlist

A Compton-scattering term (not yet included) will modify $X(E)$ as
calculated
above so that

}

$$X(E) = X(E) + \kappa(E) 1.18 \times 0.665 \times 10^{-24}$$

\itemitem{}Here $\kappa(E) = \sigma(E)/\sigma_T$, the Compton Cross Section
relative to $\sigma_T$, and the value of 1.18 is the value of
$\sum {{N_Z Z} \over N_H}$ given by the Brown and Gould abundances.

\itemitem{}Molnar {\it et al.}~(1988, Ap.~J., Submitted), find a quadratic
approximation to $\kappa(E)$ which is good up to about 37 keV.  Above
this,
the full Klein-Nishina cross section as  given by Rybicki and Lightman
(1979), page 197, should be used.

$$\kappa = 1- 2X + {26 X^2 \over 5} ~~~~~~~~{\rm quadratic~~approximation}$$

$$\kappa = {3 \over 4} \left[ {{1+X} \over x^3} \left( {{2 X (1+X)} \over
{1+ 2X} } - \ln (1 + 2X) \right) + {1 \over {2X}} \ln (1+2X)
- {{1+3X} \over (1+2X)^2}\right]$$

\itemitem{}where, with $E$ in keV,

$$X = {E \over 511.0}$$

\centerline{}
\vskip 18pt
\centerline{\underbar{Table 5.5.2. Brown and Gould Coefficient
of Analytic Fit to Cross-section}}

{\moveright 3\parindent
\vbox{\halign{\indent#\hfil&\qquad\hfil#&\qquad\hfil#&\qquad\hfil#\cr 
Energy Range (keV)&c$_{0}$\hfil&c$_{1}$\hfil&c$_{2}$\hfil\cr\noalign{\medskip} 
$<$ 0.284$^{a}$&2.6&0.284&3.0212 \cr
0.284 -- 0.400&0.955&0.4&3.2931 \cr
0.400 -- 0.532&0.47&0.532&2.9658 \cr
0.532 -- 0.874&0.24&0.874&3.0297 \cr
0.874 -- 1.300&0.098&1.3&2.6621 \cr
1.300 -- 1.838&0.0387&1.838&2.8266 \cr
1.838 -- 2.469&0.0194&2.469&2.7204 \cr
2.469 -- 3.200&0.0108&3.2&2.7435 \cr
3.200 -- 100.0&0.0113&3.2&2.016 \cr
$>$ 100.0&0.0&0.0&0.0 \cr}}}

\par\vfill\eject
 
\??Single Absorption Edge (not yet available)

{\listlist
 
\underbar{Aim}

Calculate the absorption due to a single edge at energy E$_{1}$, and optical
depth $\tau$.  Assume that the cross-section reduces as $1/(E-E_{1})^{3}$ above
the edge.  Multiply this absorption factor into the input spectrum to produce
an absorbed output spectrum.

\underbar{Note}:  Absorption may be applied either before or after redshifting.
 
This may be applied to $f'(E)$ or $f(E)$.

\underbar{Input Parameters}

$E_1$, energy of edge (keV)

$\tau$, optical depth of edge.

$f(E)$, input spectrum keV cm$^{-2}$ s$^{-1}$ keV$^{-1}$
 
\underbar{Output}
 
$\Theta (E)$, absorption factor as a function of energy.
 
$f_a(E)$, absorbed spectrum as a function of energy.

\underbar{Specification}

}

{\moveright 3\parindent \vbox{\halign{\indent\hfil$#$&$#$\hfil&$#$\hfil\cr
\Theta(E) &= 1&, E < E_{1} \cr\noalign{\medskip}
~&= \exp[-\tau\cdot(E-E_{1})^{-3}]&, E \geq E_{1} \cr\noalign{\medskip}
 f_{a}(E) &= \Theta(E)f(E)~ {\rm or}~ f_{a}^{\prime}(E) = \Theta(E)f'(E)\span\omit\cr}}}

 
\**Redshift Spectrum

{\list

\underbar{Aim}

Change a spectrum $f'(E)$ into a redshifted spectrum $f(E)$ for energy
bins in the array $n(E)$

\underbar{Input Parameters}
 
$f'(E)$, emitted spectrum

$z$, redshift
 
\underbar{Output}

$f(E)$, redshifted spectrum

\underbar{Specification}

If $z=0$, then $f(E) = f'(E)$

otherwise, $f(E) = (1+z) f'((1+z)E)$

Then we need to calculate a value for $f'((1+z)E)$ where $(1+z)E$ will not
necessarily be at the center of a bin.

For the moment, a simple interpolation between two bins will be performed.

The following is the example for the {\it Einstein} IPC.

Find the bin number, $n$, in which $(1+z)E$ lies using the fact that the $nth$
bin contains energies between

}

$$10^{0.02(n-1.5)-1.5}~ {\rm and}~ 10^{0.02(n-0.5)-1.5}$$

{\list

If $(1+z)E$ lies above the center energy of the $nth$ bin

{\it i.e.},

}

$$(1+z)E > 10^{0.02(n-1)-1.5}$$

{\list

then use information from $nth$ and $(n+1)th$ bins to determine $f'$

Find, $f(E) = (1 + z) \left[ f^{\prime}_{n+1} X + f^{\prime}_{n}(1-X) \right]$

where

}

$$X = {(E_{n}-E(1+z))\over (E_{n}-E_{n+1})} = {(10^{-1.52}- 
E(1+z).10^{-0.02n})\over (10^{-1.52}-10^{-1.5})}$$

{\list
 
If $(1+z)E$ lies below the center energy of the $nth$ bin
 
{\it i.e.},

}

$$(1+z)E <10^{0.02(n-1)-1.5}$$

{\list

then use information from $nth$ and $(n-1)th$ bins to determine $f'$
 
Find, $f(E) = (1 + z) \left[ f^{\prime}_{n-1} X + f^{\prime}_{n}(1-X) \right]$

where

}

$$X = {(E_{n}-E(1+z))\over (E_{n}-E_{n-1})} = {(E(1+z)10^{-0.02(n-1)}-10^{-1.52})\over (10^{-1.52}-10^{-1.5})}$$

 
\**Find Distance to Source

{\list

\underbar{Aim}

Convert given redshift or distance to kpc. For redshift this
involves assuming a metric, $H_o$ (Hubble's Constant) and $q_o$
(the deceleration parameter).  We will use only a Friedman Universe.
Values of $H_o$, $q_o$ will default to 50 km s$^{-1}$ Mpc$^{-1}$ and 0.0
respectively, but will be accessible to the user as hidden parameters.
 
\underbar{Input}

$d$, distance specified to be in any of:  Mpc, kpc, pc, light-years,
AU (Astronomical Units), cm.
 
$z$, redshift
 
$H_o$, Hubble's Constant
 
$q_o$, deceleration parameter
 
metric, use Friedman
 
\underbar{Output}

$D$ in kpc (luminosity distance)
 
Area = 4$\pi$D$^{2}$ in kpc$^{2}$
 
\underbar{Specifications}

if $d$ is given, use conversion factor in \S4.4.4.

if $z$ is given use 
 
}

$$D = {c\over 10^3 H_o q_o^2} \left( z q_o + (q_o-1) 
\left[-1+\sqrt{(2q_o z+1)} \right] \right);\qquad\qquad q_o \neq 0$$

$$D = {c z \over 10^3 H_o} \left( 1 + { z \over 2} \right); \qquad\qquad
q_o = 0$$

{\list
 


}
 
\**Combine Models

{\list
Note: The combining of models will not occur until the incident spectra,
$f_a(E)$, have been constructed.  This will allow the option of
different intrinsic and galactic absorption on the models being
combined.

\underbar{Input}

$M$ = number of separate models, $m=1$ to $M$

$f_{a_m}(E)$ = predicted incident spectrum for the $mth$ model.

\underbar{Output}

$f_a(E)$ = single incident spectrum.

\underbar{Specification}

}

$$f_a(E) = {\rm Norm}_1 \left[ f_{a_1}(E) + \sum_{m=2}^{M}~~{\rm Norm}_m
 f_{a_m}(E) \right]$$ 

{\list

If $A_m$ is a fixed parameter, Norm$_{m}$ will be determined using the expression
given in the specification for the relevant model (\S 5.4.3 -- \S 5.4.9)

If not, Norm$_{m}$ for $m>1$ will be a free parameter in the minimization, and
Norm$_{1}$ will be calculated with the $\chi^{2}$ calculation (thus set to unity here).

Note: It is not necessary to combine the models before folding the
spectrum through the response matrix.  The most efficient method
should be chosen.

}

\@{Convert Input Spectrum to predicted PHA counts}
 
\**Convert Flux Spectrum to Photons/s/keV

{\list
 
\underbar{Aim}

Convert energy spectrum to photons/s/keV for $f_a(E)$ array
 
\underbar{Input}

$f_a(E)$, incident spectrum in keV cm$^{-2}$ s$^{-1}$ keV.
 
$\theta$, off-axis angle of source

$A(E,\theta)$, effective area as function of energy and off-aaxis
angle (calibration table)
 
\underbar{Output}

$N(E)$, in photons s$^{-1}$ keV$^{-1}$
 
\underbar{Specification}

}

$$\eqalign{N(E) &= {f_a(E)\over E} \cdot A(E,\theta)
~{\rm photons s}^{-1}~{\rm keV}^{-1} \cr\noalign{\medskip}
E &= {\rm central~energy~of~bin~(keV)} \cr}$$

\**Fold Spectrum through Response Matrix

{\list
 
\underbar{Aim}

Each observation will have a distribution of the fraction of time at each
gain step (hopefully only 1 step for the PSPC).  For some fraction of the
time the detector will be in a reduced gain state due to `arcing',
{\it i.e.},
the deposition of a large charge due to an $\alpha$-particle passing through the
detector.

Each gain state has a different conversion from energy to pulse-height.  This
conversion is probabilistic in that a given energy photon is most likely to
end up in one particular PHA bin but also may end up in one of several
adjacent PHA bins.  This distribution of the probability for a given energy
photon being recorded in a given PHA bin forms one column of the ``response
matrix''.  Parallel columns record the PHA distributions for different photon
energies.  These response matrices are basic calibration data needed for
spectral fitting.

To convert the input model photon spectrum to PHA the spectrum will be divided
into fractions corresponding to the fraction of time spent in each gain state.
These fractional spectra are then multiplied by the response-matrix and then
added together to form a predicted PHA distribution.  Multiplication
involves taking each photon and for its energy putting a fractional PHA
count into a PHA array according to the array column distribution for that gain.
All the photons are added into the same PHA array.
 
\underbar{Input}

$R(gain)$, response matrix for each gain.
 
$H(gain)$, gain histogram. Fraction of exposure time spent at each gain.
 
$N_{i} = {\rm photons s}^{-1}~{\rm keV}^{-1}~ {\rm in}~ith~{\rm energy bin}$

\underbar{Output}

$NPHA_j$, predicted counts for the $jth$ PHA bin.

\underbar{Specification}

Details concerning the application of this specification to imaging instrument
data are given in Appendix A.

}

$$NPHA_j = \sum_{gain} \sum_{i} N_i~H(gain)~R_{ij}(gain) \Delta E_i, ~~{\rm
for~all}~i=1~{\rm to}~n$$

{\list

Note that there will be separate distributions of $NPHA$ for each
instrument if data from more than one instrument, or more than one
observation with a single instrument, are to be combined.
We will assume that we have $k=1,K$ observations, $NPHA_{k_j}$.
If there is more than one model, there may also be more than one
$f_a(E)$ from which $N_i$ is derived (see \S 6.1), {\it i.e.},
$f_{a_m}(E)$ for $m=1$ to $M$.  The method described in \S5.8 may be used to combine
the $f_{a_m}(E)$ into a single $f_a(E)$, otherwise the
$NPHA$ arrays must be combined.

[The complication of non-matching model and response bins is addressed in the ASCII
file, folding.msg. The essence should be incorporated here.]

}

\**Renormalize by Exposure Time
 
{\list

\underbar{Aim}

The spectrum so far is calculated for unit exposure time (counts/second)
 
Multiply all the predicted counts by exposure of observation.

\underbar{Input Parameters}
 
$NPHA$, predicted counts distribution (counts channel$^{-1}$ sec$^{-1}$)

$t$, live time (sec) (exposure time corrected for dead time)

\underbar{Output}
 
$NPHA'$, (counts channel$^{-1}$), exposure corrected predicted counts distribution

\underbar{Specification}

$NPHA' = t~.~NPHA$ (counts channel$^{-1}$)

}
 
\@{Compare Observed and Predicted Counts and make a best fit} 
 
\**Evaluate $\chi^{2}$ and Normalization

{\list 
 
\underbar{Aim}

To test the goodness-of-fit of a predicted PHA distribution to the
observed PHA distribution using the $\chi^{2}$ statistic.
 
\underbar{Input}

$NPHA'_{k_j}$ for $j = 1, n_k$ PHA channels

$obs_{k_j}$ for $j = 1, n_k$ PHA channels (observed distribution of counts per
channel for $kth$ observation)

$err_{k_j}$ for $j = 1, n_k$ PHA channels (error distribution)

number of channels fit in $kth$ observation, $n_k$

number of free parameters in model (or combination of models), $p$

information as to whether or not Norm$_{1}$ is fixed parameter.
 
\underbar{Output}
 
$\chi^{2}$

d.o.f. =  degrees of freedom

\underbar{Specification}

d.o.f. = $\left(\sum_k n_k \right) - p$

if Norm$_{1}$ is fixed parameter

}

$$\chi^{2} = \sum_k \sum_{j=1}^{n_k} {(obs_{k_j}-NPHA'_{k_j})^{2}\over (err_{k_j})^{2}}$$

{\list
 
if Norm$_{1}$ is a free parameter

}

$${\rm Norm}_{1} = \sum_k \sum_{j=1}^{n_k} {(obs_{k_j}NPHA'_{k_j})\over
(err_{k_j})^{2}}/ \sum_k \sum_{j=1}^{n_k} {(NPHA'_{k_j})^{2}\over (err_{k_j})^{2}}$$
$$\chi^{2} = \sum_k \sum_{j=1}^{n_k} {obs_{k_j}^{2}\over
(err_{k_j})^{2}} - ({\rm Norm}_{1})^{2}
\sum_k \sum_{j=1}^{n_k} {(NPHA'_{k_j})^{2}\over (err_{k_j})^{2}}$$

{\list

Note that only 3 double sums over $kj$ are necessary to solve Norm$_{1}$ and $\chi^{2}$.

Once the best fit has been found,
the values for $A_m$ for any free parameters must be calculated from
the
corresponding values of Norm$_m~ (m=1$ to $M$).
The evaluation depends on the model and expressions are given in
\S5.4.3 -- \S5.4.9.

}
 
\**$\chi^{2}$ minimization Search Methods

{\list

The selected search method must be appropriate for the number of parameters set
as free {\it vs} fixed.

}
 
\??Single Value

{\listlist
 
\underbar{Aim}

Evaluate $\chi^{2}$ for
a single set of user specified spectral parameters.
No free parameters.

The single-value routine will search to make sure that the user has
set all parameters to be fixed.
If not, the program will temporarily fix them to evaluate $\chi^2$,
and will then return them to their original state.

}
 
\??Gradient Search 1: Congugate (or Powell) method

{\listlist

Locate a $\chi_{min}^{2}$ using the Powell method gradient-search technique described
by W.H.~Press, B.P.~Flannery, S.~Teukolsky, and W.T.~Vetterling in ``Numerical
Recipes~~~~~~~~~~~~~'', chapter 10.

The user has specified which parameters are free.  If this routine is
requested but the only free parameter is the normalization of the first
model, the program should skip straight to \S7.1 and
evaluate the normalization without actually calling the gradient
search routine.  See also Appendix B.

}

\??Gradient Search 2:  Fit Using Simplex method

{\listlist

Locate a $\chi_{min}^{2}$ and confidence region using the simplex method.

The user has specified which parameters are free.  If this routine is
requested but the only free parameter is the normalization of the first
model, the program should skip straight to \S7.1 and
evaluate the normalization without actually calling the gradient
search routine.  See also Appendix B.
 
}


\??Grid Search

{\listlist

\underbar{Aim}

Users often need to see the shape of the $\chi^{2}$ contours in pairs
of parameters.  This is valuable for judging the interdependence of
parameters.  (If we could easily display 3-(or 4!), dimensional
surfaces this would be even better).

The user needs to choose the two parameters to be displayed, to define
a grid of points by specifying the limits of the parameter region to
search and the number of points in the grid (or equivalently the step size
of the grid).

At each grid point a $\chi^{2}$-minimization search
is applied keeping the two chosen grid parameter fixed
at the values defining the grid point.  One of the minimizations of
\S 7.2 will be hardwired for this purpose.
If normalization of the first model is the only free parameter,
then the program should skip straight to \S7,1 and evaluate the
normalization at each grid point without actually calling the gradient
search routine.

The values of $\chi^{2}$ at each grid point are stored and can be output
either as an array of numbers or as a contour diagram.  The contours
will be at values of $\chi_{min}^{2} + (x_{1},x_{2}...,x_{i}...,x_{n}$) where
the values of $x_{i}$ correspond to probabilities for the given number of
free parameters.

$\chi_{min}^{2}$, is found by invoking the hardwired minimization
routine
chosen (see above) where the parameters of the grid axes are
temporarily set as free parameters in addition to any other free
parameters.

\underbar{Input}

2 parameters for grid
 
other free parameters
 
grid limits $(min,max)$ in each grid parameter
 
number of points, or step size, for grid in each parameter
 
contour probability levels.
 
\underbar{Output}

grid of $\chi^{2}$.

$\chi_{min}^{2}$ and grid parameter values at $\chi_{min}^{2}$.
 
best fit parameters.
 
d.o.f.
 
predicted PHA values for best fit, $N^{\prime}_{best}$(PHA)
 
\underbar{Specification}
 
(1).Grid points in parameter P$_{x}$ are specified by

}
\vskip 12pt
{\moveright 3\parindent \vbox{\halign{\indent\hfil$#$&$#$\hfil&\qquad$#$\hfil\cr
P_{x}(i)&= P_{x}(min) + (i-1)\Delta P_{x}& P_{x}(i)<P(max)\cr\noalign{\medskip}
\Delta P_{x} &= {\rm step~size,~if~given}\cr\noalign{\medskip}
~&= {P_{x}(max)-P_{x}(min)\over npoints_{x}-1}&
{\rm if}~npoints_{x}~{\rm is~given}\cr }}}

{\listlist

(2).Then at each grid point ($P_x, P_y$)

~~~(a). If normalization is the only extra free parameter, calculate it
using equations in \S 7.1. \underbar{Note}:  Normalization
must be found before evaluation $\chi^{2}$.
 
~~~(b) or, if there are non-grid free parameters other than the normalization,
holding ($P_x,P_y$) constant,  find $\chi^{2}$ by using a gradient
search (currently the simplex fit).
 
~~~(c) or, if there are no non-grid free parameters,
evaluate $\chi^{2}$ for ($P_x,P_y$) as in single value fit.
 
}

\@{Find Fluxes and Luminosities}

 
\**Monochromatic Fluxes 

{\list

\underbar{Aim}

For each entry in a user-specified list of energies extract a
monochromatic flux density from the input spectra.  The default spectra
would be the spectrum incident on the telescope, $f_a(E)$, and the redshifted spectrum
prior to galactic absorption,  $f(E)$.  Other intermediate
spectra may be called
for in addition or in place of these two.  The energies will be in the frame
of the spectrum and the redshift appropriate to the energies will be
printed on the output.  Energy specification will be in keV.
[\AA~and/or Hz may
be added later if there is sufficient demand for this.]

\underbar{Input}

$e_1, e_2,\ldots,e_i$, list of `energies' at which to
calculate monochromatic fluxes (in keV, or possibly other units).

Spectrum, $f_{x}(E)$.  Incident, redshifted,
{\it i.e.}, $f_a(E), f(E))$
(see \S5.1 for definitions).  Only results for summed model components,
$m=1,M$, will be computed. 

\underbar{Output}
 
$f_x(E_1), f_x(E_2), \ldots, f_x(E_i)$, monochromatic flux densities
at $E_1, E_2, \ldots, E_i$ for spectrum $f_x(E)$.

\underbar{Specification}

$E_i$ = conversion factor $\times$ $e_i$.  Convert list of energies to keV (see
\S4.4 for conversion factors)

For specified model components, at each $E_i$, interpolate
values of $f_{x}(E)$ to $f_{x}(E_i)$.

Convert output to user-friendly units.

}
 
\**Monochromatic Luminosities

{\list

\underbar{Aim}

For the user specified list of energies of \S8.1 use the flux 
densities generated in
\S8.1 to produce monochromatic luminosities.  The luminosity distance is
calculated in \S5.7.

\underbar{Input}

$e_i$, `energy' (keV, or possibly other units).

$f_x(E_i)$, keV cm$^{-2}$~s$^{-1}$ keV$^{-1}$ (see \S 8.1)

z (convert to $D$ cm using %q_o$ and $H_o$), or $D$ kpc (convert to
$D$ cm)

\underbar{Output}

$l_x(E_{i})$,  keV s$^{-1}$ keV$^{-1}$

\underbar{Specification}

$E_i$ = conversion factor $\times$ $e_i$.  Convert list of energies to keV (see
\S4.4 for conversion factors)

$l_x(E_{i}) = 4 \pi D^{2}.f_x(E_{i})$, keV s$^{-1}$ keV$^{-1}$

Convert output to user-friendly units.

}
 
\**Broad-Band Fluxes

{\list

\underbar{Aim}

as for 8.2 but integrated over energy ranges.

\underbar{Input}

$(e_{11}, e_{12}),(e_{21}, e_{22}),\ldots,(e_{i1}, e_{i2})$,
pairs of lower and upper energies specifying ranges over which to integrate
$f_x(E_i)$ (keV, or possibly other units).

[Note:  if e$_{i}$ are in \AA, ~the lower and upper values reverse on
conversion to keV.]
 
Spectrum, $f_{x}(E)$.  Incident, redshifted,
{\it i.e.}, $f_a(E), f(E))$
(see \S5.1 for definitions).  Only results for summed model components,
$m=1,M$, will be computed. 

\underbar{Output}

$F(E_{11}, E_{12}), F(E_{21}, E_{22}),\ldots,F(E_{i1}, E_{i2})$, the 
broad-band fluxes in specified ranges.

\underbar{Specification}

$E_{iy}$ = conversion factor $\times e_{iy}$. Convert list of energies to keV
(see \S4.4 for conversion factors)

Sum $f_x(E_i)$ from $E_{i1}$ to $E_{i2}$.  For the two end bins in
$f_x(E_i)$ within the range, interpolate as in \S5.6.

} 
 
\**Broad-Band Luminosities
 
{\list

\underbar{Aim}

For the user specified list of energies of \S8.3, use the flux generated in
\S8.3 to produce source luminosities.  The luminosity distance is
calculated in \S5.7.

\underbar{Input}
 
$e_{i1}, e_{i2}$ `energy' (keV, or possibly other units)
 
$F(E_{i1},E_{i2})$, keV cm$^{-2}$s$^{-1}$ (see \S 8.3)

z (convert to $D$ cm using %q_o$ and $H_o$), or $D$ kpc (convert to
$D$ cm)

\underbar{Output}
 
$L(E_{i1},E_{i2})$,  keV s$^{-1}$
 
\underbar{Specification}
 
$E_{iy}$ = conversion factor $\times e_{iy}$. Convert list of energies to keV
(see \S4.4 for conversion factors)

$L(E_{i1},E_{i2}) = 4\pi D^{2}.F(E_{i1},E_{i2})$, keV s$^{-1}$

Convert output to user-friendly units.

}
 
\@{Output Data}
 
\**Options:

{\list

to screen

to hardcopy

to file
 
}
 
\**Choice of Units

{\list

The choice of units is a matter of convenience, local convention and
personal taste.  The user should be able to choose the output units for
quantities and set defaults.  This includes labelling of plot axes.
The user must be able to specify a title string and $x,y$ axis strings on
plots.

Flux options are detailed in \S4.2.7.

Distance options are detailed in \S5.7.

Conversion factors are listed in \S4.4.

}
 
\**Values of parameters:

{\list

(Best) Fit parameters, $kT$ or $\alpha$, $N_H$, other free parameters

Normalization or emission measure (for Raymond-Smith Thermal).

$\chi^{2}$, degrees of freedom

Confidence ranges.

PHA channels fit

Energy Range fit

All parameter file values must be printable.

}
 
\**Contour 2-D $\chi^2$ Values from Grid Search

{\list
 
For the grid search contour the grid at values of
$\chi_{min}^{2}~+~n_{1},n_{2},n_{3}$..., corresponding to confidence levels
supplied by the user.  Any number of levels may be requested.  In
the default case
$n_1, n_2$ and $n_3$ will be 2.3, 4.61 and 9.21 corresponding to confidence
levels of 68\%, 90\% and 99\% that the true values of the 2 parameters lie within
the contour, assuming 2 interesting parameters
(Avni, Y., 1976, Ap.J., \underbar{210}, 642).

}
 
\**Data

{\list

Input net counts with errors

Net counts s$^{-1}$ in fit PHA channels

background counts

Predicted (Best) Fit counts

Deviations ([Obs-Pred]/[error])

Systematic errors added.
 
}
 
\**Fitted Spectra:

{\list

(a). Emitted spectrum

(b). At-Source (Absorbed) spectrum

(c). Redshifted spectrum

(d). Incident spectrum (Galactic absorbed)

(e). Difference spectrum(``unfolded'' - predicted) for any of a-d
 
For all of these either the total or specified sub-components may be output.

}

\**Source Data

{\list

all of data in \S2.1

}
 
\**Fluxes and Luminosities

{\list
 
All of values calculated in \S8.

}

\vskip 24pt

\centerline{\underbar{Limitations}}

\item{1.}We have no method to deal with UV leaks.

\item{2.}We do not allow for the possibility of the background being at a different
gain from the source.

\item{3.}We are implementing $\chi^2$ to test goodness of fit.
When the number of counts in a channel falls below about 20, Poisson
errors become rather asymmetric.  In this case a better statistical
approach would be to use the KS-test for goodness of fit, and the
maximum likelihood method for error contours.

\vfill\eject

\def\chapter{\it D.M. Worrall}
\def\version{\it Rev 1.0. November 20th, 1986.}


\chapterhead{APPENDIX~~A}
\vskip 24pt

\noindent{D.M.W. (October 3rd, 1985)  Rev 1.0. November 20th,
1986.}
\vskip 18pt

\centerline{CALIBRATIONS REQUIRED TO CONVERT FROM INCOMING PHOTON SPECTRUM}
\centerline{TO IMPLIED PHA DISTRIBUTION FOR AN IPC (OR PSPC)}
\vskip 18pt

\noindent{\bf I. GENERAL}
\startcount

The following assumes that the $x,y$ positions (for calibrations and
observations) are corrected
for electronic distortion ({\it i.e.}, DECOR for Einstein IPC, or
GAPMAP for Einstein HRI). These distortions were measured
for Einstein at Huntsville and then in flight by means of
point-source pointings (IPC) and the UV CAL (HRI).  The electronic 
distortion is a function of $x,y$ and $pulseheight$, and is due to 
distortion of the electric fields around the wire mesh and ribs.  
It is nominally assumed that
any corrections to the PSPC DECOR will be handled by special level 1
processing.  

The user may wish to view data in detector coordinates, after DECOR but
before aspect corrections.  In particular, the shadow of the PSPC wire-mesh
support structure should then be visible, and a user could be warned against
searching for variability from a point source near the mesh.
If the detector coordinates supplied to level 2 are
those before DECOR correction, we should have level 2 ability to
apply DECOR corrections.

In general, the spatial-analysis user will wish to apply area corrections
(vignetting and other effects) and exposure corrections to data in a 
selected energy band.  Calculations for the Einstein IPC have shown
that if the pointing direction changes by more than about $1^\prime$, the
vignetting at the edge of the field changes by more than about 1\%.  Therefore,
exposure maps must be re-calculated for intervals of steady aspect, and
some observations require more than one.
 
Below it is assumed that a user has obtained
net source counts using data uncorrected for exposure or vignetting.
It is implicitely assumed that the exposure correction is similar for 
source and background regions.  The net counts are calculated and the 
exposure correction (but not vignetting) is
applied before comparison with model counts, calculated as given below.

\@{Mirror Effective Area - Area$(E,x,y)$.}
The mirror area presented to incoming photons will be a function
of their angles $\theta, \phi$ with respect to the telescope axis, and
the energy of the photons. The angles with respect to telescope
axis can be translated to position $x,y$ in the detector plane. Thus
we can form the effective area function: AREA($E,x,y$).
The area is calibrated using a monochromatic photon beam.
A photon counter measures the number of photons focussed
as a function of the direction of the beam with respect to
the telescope axis. The calibrations can be checked against predictions.
This term will dominate the vignetting correction (assumed to include
4 and 5 below) - the
spatial variation of the energy-to-flux conversion.  This function
has radial symmetry for the Einstein IPC.

\@{Mirror Scattering  -  SCATTERING CORRECTION($E,x,y,radius$).}
Some photons will be scattered away by the roughness of the
mirror, and the area
into which all the photons will fall will be a function of $E$ and
position. In practice, a radius will be chosen, and the function
SCATTERING CORRECTION
will correct down the AREA to compensate for photons scattered away.
This correction is a measured quantity.  This function
has radial symmetry for the Einstein IPC.

\@{Mirror Point Response Function -  MIRRORPRF($E,x,y,radius$).}
The image progressively degrades off axis.  The amount can be
predicted using ray-tracing simulations. MPE is currently doing these
simulations for the ROSAT mirror.  This is typically small relative to the
effect of the detector point response function (see below) for
an IPC-type detector, and dominates over the detector point response
function for an HRI-type detector.  However, it will be important for the
PSPC at off-axis angles greater than $7^\prime$
(radial symmetry?), and calibration data are required.

\@{Filter and Window Transmission - FWTRANS($E$).}
Some photons will be absorbed by the filter/mesh/window combination. This
is an energy dependent function. It is usually calculated for the
materials being used, and checked with some measurements.
The presence of the wire-mesh support structure for the Einstein IPC
would have had the effect of causing a 5\% modulation
in the intensity of a source calculated assuming $1^\prime$ aspect jitter as
about 3 mesh wires crossed a $1^\prime$ radius. This 
modulation may be a greater problem for
the PSPC because some of the wires are thicker.  The presence of ribs will
cause additional energy-dependent absorption in particular spatial regions.

\@{Detector Efficiency - EFFIC($E$).}
There is a detection probability in the detector which is spatially
independent but is a function of energy.  This is predicted from the
known composition and density of gas in the detector.

\@{Detector Response Function - RES($pulseheight:E,gain$).}
This is the pulseheight normalized probability distribution for a photon
of energy E for a particular gain.

\par\noindent
Notes:

\itemitem{a).} Although not included for the Einstein IPC, it is conceivable
that the gain may be a function of the count rate of a source ---
in particular, a correction to the gain value may be necessary
if count rates are very high.  (However, in practice this will be next to
impossible to correct, and this point is thus irrelevant for
all practical purposes).

\itemitem{b).} There will also be periods when the gain is not at the
nominal value.  When an energetic particle enters the detector,
the gain may instantaneously drop and take up to 4 seconds
to recover to the nominal value. This effect is taken into
account for the Einstein IPC by way of ARCFRAC.

\@{Detector Point Response Function - DPR($pulseheight,radius$).}
The detector does not have perfect spatial response, and the
radius of the circle
in which a given fraction of point-source
pulseheight events will be recorded is a function of
energy. The simplifying assumption is made for the Einstein IPC that this 
radius is actually a function of pulseheight rather than energy. Gaussian functional
forms can be estimated, where the sigma of the Gaussian is a function
of pulseheight.  However, for the PSPC, calibration data are desirable, as are
checks into the relative importance of pulseheight and energy.




\noindent{\bf II. FORM OF CALIBRATION DATA LIKELY TO BE PROVIDED FOR ROSAT}

We expect to have the spatial distributions per pulseheight band
measured from sending a monochromatic parallel beam down the
mirror/detector experimental configuration,
at various angles with respect to the telescope axis
and for various monochromatic energies and gains.  We expect to have
results from the same calibrations repeated without the
mirror (just using a small aperture to produce point collimated
illumination).

\noindent{\bf III. FORM OF PHOTON/PULSEHEIGHT CONVERSION USED FOR THE EINSTEIN 
IPC IN FINSPEC}

Functions mentioned above are:
\halign{ \quad # \hfil \quad & # \hfil \cr
   1.   & AREA($E,x,y$) \cr
   2.   & SCATTERING CORRECTION($E,x,y,radius$) \cr
   3.   & MIRRORPRF($E,x,y,radius$) \cr
   4.   & FWTRANS($E$) \cr
   5.   & EFFIC($E$) \cr
   6.   & RES($pulseheight:E, gain$) \cr
   7.   & DPR($pulseheight, radius$) \cr
}

\vskip 16pt\noindent{\bf DEALING WITH 1,2,3,4 and 5.}

In Einstein, things are treated as being radially-symmetric
about the center of the detector so that $x,y$ can be converted
to a radius, $R$.  Number 3 above is ignored for the IPC.
We have 1,4 and 5 combined into
AREA.OFF($E,R: radius=3^\prime$, or $radius=45^\prime$).
For $3^\prime$, AREA.OFF calls NEW.0.3.OFF.  For $45^\prime$, AREA.OFF
calls NEW.0.45.OFF.  By using the calibration for the given
radius ($3 ^\prime$ for a point source or $45^\prime$ for an extended
source), we effectively include SCATTERING CORRECTION (2 above).
SCATTERING CORRECTION can be calculated for $radius=3^\prime$ by comparing
NEW.0.3.OFF with NEW.0.45.OFF.  This is required for spatial
analysis, but not for spectral analysis in which we are
integrating photons over a spatial region.  The AREA.OFF files are in
:HDATA on the M600.  NEW.0.3.OFF is also the effective area
data on F.R.Harnden, Jr.'s tape (see his memo of October 29th, 1984).

The incoming photons, IP($E,x,y$) photons~cm$^{-2}$~s$^{-1}$
are multiplied by the function
NEW.0.3.OFF($E,x,y$) or NEW.0.45.OFF($E,x,y$), to give the corrected
photon spectrum CP($E,x,y$) photons~s$^{-1}$.

\vskip 16pt\noindent{\bf DEALING WITH 6.}

A fraction, ARCFRAC, of CP is assumed to have been measured when
the gain was lower due to the effect of an energetic charged particle
(see note (b) above).

The response function RES($pulseheight:E,gain$) can be found in
RES.MATRIX linked
to REV9.RES.MATRIX in :HDATA on the M600.  In addition to 
RES($pulseheight:E,gain$),
we have something called here REStransient($pulseheight:E,gain$) which
provides the values for RES($pulseheight:E,gain$) which should be
used ARCFRAC of the time.  The reponse function matrices are generated by
RESPONSE which resides in :HSOURCE, but the fitting program should read stored
matrices rather than compute them each time.
RES and REStransient each consist of one 2D matrix for
each gain value.  They are also on F.R.Harnden, Jr.'s tape as
cards 17-316 and 321-620 respectively under response matrix.
The gain is given by the value of BAL.  We get a pulse height
distribution:
$${\rm PH}(pulseheight,x,y,nominal~gain) =$$
$$\int dE~~{\rm RES}(pulseheight:E,nominal~gain) \times {\rm CP(}E,x,y)$$
$$~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \times (1-{\rm ARCFRAC})$$
$$ +\int dE~~{\rm REStransient}(pulseheight:E,nominal~gain) \times {\rm
CP}(E,x,y)$$
$$~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \times {\rm ARCFRAC}$$

\vskip 16pt\noindent{\bf DEALING WITH 7.}

Finally, the correction is made for the fraction of pulseheight events that will
be measured in the selected radius using DPR($pulseheight,radius$).
The function
DPR is calculated from the amount of area in a Gaussian of sigma
appropriate to the pulseheight which falls inside the selected source radius.
The values of sigma appropriate to the pulseheight channels are given in
FINSPEC.PF in units of pixels (8 arcsecs).
The correction is computed in FIN1 of the overlayed
FINSPEC source code (in :HSOURCE on the M600) and applied in
FIN4.  It is called CHANCOR in FINSPEC and looks something
like:
$$ {\rm CHANCOR}(pulseheight,radius)=[{\rm DPR}(pulseheight,radius)]$$
$$~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~=[1-(exp(-radius^2 /2 \sigma^2)]$$

$${\rm CNTRATE}(pulseheight,radius,x,y,nominal~gain)~ {\rm counts~s}^{-1}$$
$$= {\rm CHANCOR}(pulseheight,radius)
\times {\rm PH}(pulseheight,x,y,nominal~gain)$$

$${\rm PHADIST}(pulseheight,radius,x,y,nominal~gain)~counts$$
$$~~~~~~~~~~~~~~~~~~~= {\rm CNTRATE}(pulseheight,radius,x,y,nominal~gain)$$
$$~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \times {\rm TIME}(x,y)$$


Time should be calculated by correcting the observation time for
deadtime, and correcting for the positional dependence
(due to aspect variations)
from the exposure map array.  In practice, the exposure map corrections
are small and are ignored in FINSPEC. It may not be possible to
ignore them for ROSAT.  For Einstein, the predominant deadtime is
due to telemetry,
and is therefore energy and positionally independent.  The same will
be true for ROSAT.  For Einstein the deadtime factor is about 4\%.
Therefore, TIME=OBSTIME/1.04.

Finally, PHADIST is compared with the measured PHA count distribution.

\vfill\eject

\def\chapter{\it D.M. Worrall}
\def\version{\it March 5th, 1987.}

\chapterhead{APPENDIX~~B}
\vskip 24pt

\noindent{D.M.W. (March 5th, 1987)}
\vskip 18pt

\centerline{PARAMETER BOUNDS FOR SPECTRAL FITTING MINIMIZATION ROUTINE}

\vskip 18pt

The following is a way of confining parameters to user-specified
bounds whilst allowing the simplex minimization routine
to search a parameter space $- \infty$ to $+ \infty$.  
Similar implementation is possible for the Powell routine (congugate
gradient search) or any other minimization method used.
The following is divided into three parts.  The first includes
a revised definition of some of the parameters seen by the
user.  The second part gives the changes needed in the main routine.
The third part gives the changes needed in the subroutine which
evaluates the function.

\noindent\underbar{1. Parameter Definitions}

A revision to the input and output parameter tables should be made
so that $\log N_H$ values are used in place of all $N_H$ values, and
$\log Norm$ in place of all $Norm$ values.

Before a simplex minimization is called, the user will have specified starting
values for the $N$ free parameters of the $NTOT$ total parameters.
Let us call these values $PINIT(i), i=1,N$.  The user will also
be expected to supply values for $\Delta P(i), i=1,N$ such
that permitted values of $P(i)$ lie between $PINIT(i) - \Delta P(i)$
and $PINIT(i) + \Delta P(i)$.

\noindent\underbar{2. Main Routine}

The main routine which calls the simplex minimization should declare a third array of
size $NTOT$.  Let us call this $PAR(i)$.
Before the call to the simplex, the array $PAR$ must be initialized;
$PAR(i)=0, i=1,NTOT$.
Let us assume the subroutine containing the function we will evaluate
is called SFUNC.  SFUNC has been declared external inside the main
routine.  Because of the transformation made in SFUNC (see below),
we will do the following;
$${\rm CALL~SIMPLEX}(N,PAR,\ldots,SFUNC,\ldots)$$

\noindent
and the best-fit values for $PAR(i),i=1,N$ will be returned.

The returned best estimates for $P(i)$,
which supercede the values of $PINIT(i)$ in the parameter table,
(let's call them $PFIN(i)$), are given by:
$$PFIN(i) = PINIT(i) + ( \Delta P(i) \ast~{\rm  SINGL(DTANH}(PAR(i))))$$

\noindent\underbar{3. SFUNC}

The subroutine SFUNC, called by SIMPLEX, only has $N, PAR, FIT$ as
arguments, where $FIT$ is the returned value of the function ({\it i.e.},
$\chi^2$ in the case of spectral fitting).  SFUNC will need to know
$PINIT$ and $\Delta P$. Therefore, it is convenient 
to pass these over in a common block.  $PAR$ and $FIT$ are
double precision, but I have assumed everything else is single
precision.

Inside SFUNC, the current values of the parameters are given by $P(i)$, where
$$P(i) = PINIT(i) + (  \Delta P(i) \ast~{\rm SINGL(DTANH}(PAR(i))))$$

\noindent
The TANH function 
(called above in its double-precision FORTRAN form) 
is actually given by TANH($PAR$) = $(e^{PAR} - e^{-PAR})/(e^{PAR} + e^{-PAR})$.
It has the
nice property that setting $PAR(i)$ in the range from
$- \infty$ to $+ \infty$ is
equivalent to TANH($PAR(i)$) in the range $- 1$ to $+ 1$.  Thus
$P$ ranges from $PINIT - \Delta P$ to $PINIT + \Delta P$, as
required.
Note that on the first call, when $PAR(i)$ values are zero,
the values of $P(i)$ are identical to $PINIT(i)$. 

Note that the $P$ values for nomalizations and column densities should
be raised to the power ten in SFUNC.
\vfill\eject\end
