1 XSPEC tutorial
		A tutorial on X-Ray Spectral fitting using XSPEC
			and associated programs.
 
	This tutorial uses the XHELP subroutines.  To read through the entire
tutorial just hit continued returns to the occasional prompts.  This tutorial
may be exited by typing an end of file (<Ctrl-Z>).  You may tailor your reading
of topics by responding to the XHELP prompts (type "??" to see a brief
description of the special responses).  In particular, if you wish to skip
to the next branch of the tutorial tree type ">" to the prompt.
2 Overview
	This tutorial is divided into three general areas:  A review
of spectral fitting, with particular attention to common issues faced in the
analysis of X-ray data;  how to perform a spectral analysis using XSPEC; and
a description of the family of associated programs available to assist you.
2 Philosophy
	This section is a somewhat abstract description of X-ray spectral
analysis and some of the issues that are faced when designing the analysis
software.  Much of it is at a very elementary level, pitched particularly to
the novice in the field.  However, even the expert might gain useful
information skimming the following, as it will introduce the nomenclature used
as well as highlight particular design choices made in the current
implementation of XSPEC. 
3 X-ray_spectra
	The general purpose of spectroscopy is to study the distribution of a
source's emission with energy.  Such a study can in principle, distinguish
between a proposed physical processes responsible for the emision and to
determine or at least constrain the parameters that detail the process.
However, because of the limitations of the actual data, often what can be
acheived is simply a characterization of the data (`The underlying process must
look something like this.') rather than an absolute statement (`The physical
process responsible IS this.').  Even such limited goals have a great deal of
utility, particularly in making comparisons of objects or charting the change
in a particular source's behavior. 
3 Models
	Ideally, then we start with a model for the emission, F(E) which is a
continuous function of energy.  Because the units of such function is often in
terms of the differential number of photons per second per square centimeter,
incident on a detector, such a spectrum is conventially referred to as a
`photon' spectrum. 
	F(E) can have a very complicated form, but is usually decomposed into a
variety of components.  Usually these components can be classified into two
varieties:  an actual source of emission (such as a black body, the emission of
an optically thin thermal source, a synchrotron source, or recombination line
emission), or a component that  modifies the spectrum between its emission and
detection (such as photo-electric or line absorption).  These two kinds of
emission can be referred to as `additive' and `multiplicative' components.  Of
course, more complicated models could be constructed (e.g. models which activly
reprocess the emission from other components) but these are best treated as a
single component (where for example geometric effects can be explictly included
within the description of the component). 
	In general, each component is a function of one or more parameters,
so that the total emission is
	F ( E; {ALPHA})
where {ALPHA} represents the set of parameters.  In an ideal world, the
process of spectral analysis would consist of directly determining F(E), see
if a particular combination of models describes it and then determine
the proper value of the elements of {ALPHA}.
3 Data_and_detectors
	In the real world, though, F(E) is not directly measured.  Instead we
have measurements from one or more detectors, where the detector instrumental
response plays a crucial complicating role.  The actual measurements wil be a
number of detected counts in one or more channels. In the earliest X-ray
spectrometers, which channel a detected photon was assigned to was determined
by the height of the signal pulse it produced in the detector, so traditionally
a spectral channel was called a PHA (Pulse Height Analyzer) channel.  In XSPEC
the data files are often given the shorthand designation of PHA files. 
	The link between the incident spectrum F(E), and the observed
distribution of counts, N(i) (where i refers to the Ith channel) is given by
the response function R(E,i), which is the probability that a photon incident
on a detector will be detected in channel i.  All the physics (and black magic)
associated with the understanding of the detectors is embodied in that
function. If Npred(i) is the predicted number of counts per second for a
particular F(E), then 
		Npred(i) = Integral dE F(E) R(E,i) .
R includes both the detector quantum efficiency and its spectral resolution.
Note that R is a descrete function of channel number i, but (strictly speaking)
a continuous function of the energy E.   However, the response is not ever
known exactly, nor is it practical to perform a variety of integrals.  Instead
the energy E, is binned up into descrete ranges, E(j) to E(j+1), the incident
photon spectrum converted to F(j), the number of photons in that range and
R(j,i) is the average response of the detector to a photon in the range. Just
how finely E is binned depends on issues of the resolution of the detector, the
quality of the data, and the degree to which the detector response is actually
known.  Now R(j,i) is descrete both in the input energy (j) and output channel
number (i), so that the effect of the response is a simple matrix
multiplication: 
	Npred(i) = SUMj R(j,i) F(j) .
The values R(j,i) are a 2-dimensional matrix, (often refered to the response
or detector matrix).  Many of the values of R(j,i) are effectivly zero, so
that the internal representation of R in XSPEC is as a sparse matrix, saving
storage space and computation.  As far as XSPEC is concerned all information
about the detectors is contained in R.  This information is stored in files
called RSP files.
	The representation of the detector response is general enough to
include some non-PHA `spectrometers'.  The results of a simple filter based
measurement can be treated as performed with a single channel spectrometer,
where R(j,1) is the total instrument spectral efficiency.  By itself, such
a measurement usually could not lead to much information, but in combination
with other filter measurements (or other true spectroscopy measurements), the
incident model may be constrained. A dispersive spectrometer could be
similarly handled by R(j,i), for example a grating spectrum that has been
projected on an imaging detector.  In this case the index i would refer not
to the Ith PHA channel, but instead to the Ith row of the image.  R(j,i)
could directly include such issues as the efficiency and resolution of
the grating, the efficiency of the imaging system and detector, and
complications such as multiple orders.
3 Statistics
3 Parameters
3 Fits
3 Data_grouping
3 Interpretation
4 Goodness_of_fit
4 Additional_components
4 Parameter_estimation
4 Contrasting_models
4 Astronomy_vs_astrophysics
2 XSPEC
	suggest command
	sample output
3 Input_&_Output
4 Input
5 User_Input
		XPARSE
5 PHA_files
5 RSP_files
5 Profiles
5 Command_files
5 Initialization
4 Output
		chatter command
5 Screen_Output
5 Log_file
5 History_files
5 Profiles
3 data_definition
4 file_numbers
4 channels_&_bins
4 associated_files
5 background_files
5 correction_files
5 response_files
6 gain_shifts
3 data_selection
4 ignore
4 notice
3 rebinned_data
3 models
4 user_models
	In addition to the installed models
3 fit_parameters
4 newpar
4 freeze_&_thaw
3 fits
4 general_fitting
4 errors
4 renorm
4 correction_norms
4 parameter_stepping
3 graphics
4 devices
4 rebinning
4 file_grouping
4 axes_units
5 channels_(arbitrary)
5 energy
4 plot_quality
3 plots
4 data_and_model
5 folded_(counts)
5 incident_(photons)
5 unfolded_(estimated_photons)
4 Response
4 Sensitivity
3 Calculations
4 Flux
4 Dummy_Response
4 Equivalent_Width
4 Fake_Data
2 Auxiliary_Programs
	In this section we outline a few of the associated programs and
command files associated with XSPEC.  Not included in this discussion is
the family of programs specific to individual devices, for example those
that create the PHA and RSP files.  Details of these are undoubtably
discussed in other help files.  In fact, with the exception of the
section on User defined models, most of these programs are outlined
in greater detail in the system help files.
3 PHA_programs
RDPHA
CHANPHA
3 RSP_programs
RDRSP
3 Confidence_contours
DOXSPEC
PLCONT
3 User_models
	In addition to the `installed' models, that are prelinked into
XSPEC, the user may define an additive and/or multiplicative model of
his own.  These are accessed in XSPEC as the model USERADD1 or USERADD2.
By default these user models are very boreing flat models.  In order to use
his own models a user must first write FORTRAN subroutines following
a certain format.  Then they must be linked using the MKUMD command (or
DBUMD if they wish to debug the routines within XSPEC).  Finally they must use
the SETUMD command to tell XSPEC to use their routines, before typing
the XSPEC command.  Note that once you begin an XSPEC session you can not
redefine the user model without leaving XSPEC.
	A user may have multiple sets of user models, but only one set
can be currently defined with SETUMD.
	In the following we will consider as an example a particular user
model which calculates power laws.
4 model_format
	XSPEC calls the two user models by calling subroutines named
XSUSA1 (for the additive model) and XSUSM1 (for the multiplicative model).
The calling sequence it uses is
	CALL XSUSA1(ear, ne, param, worksp, photar)
where the following are the definitions of the parameters:
	real*4 EAR(0:NE)	! Input:  An array of energy boundaries.
	integer*4 NE		! Input:  The number of energy ranges
	real*4 PARAM(20)	! Input:  The current model parameters
	real*4 WORKSP(*)	! A workspace array
	real*4 PHOTAR(NE)	! The returned model intensity.
The user's subroutine must calculate PHOTAR. For an additive model, PHOTAR(i)
is the expected number of photons per second per square centimeter in the
energy range from EAR(i-1) to EAR(i), assuming the model norm is 1.0.  The
other model parameters are taken from the PARAM array.  XSPEC will initialize
these parameters to zero, and treat them as frozen.  The `thaw' and `newpar'
commands, of course, can be used to modify this initial state.  For the XSUSM1
multiplicative routine PHOTAR is the mean multiplication factor over the range
EAR(i-1) to EAR(i).
	Currently, user models should NOT use the WORKSP variables for any
reason.  Subsequent releases of XSPEC (with additional user model properties)
may allow this use.
5 model_example
	The user should place the XSUSA1 subroutine in a file with a name
that is mneominic of the actual user model.  For example consider the file
named POWERLAW.FOR:
c	POWERLAW --- This is an XSPEC user model to calculate a powerlaw
	subroutine xsusa1 (ear, ne, param, worksp, photar)
c
	implicit none
	real*4 ear(0:*)
	integer*4 ne
	real*4 param(1)  ! The one and only parameter is the index
	real*4 worksp
	real*4 photar(ne)
c
	integer*4 i
	real*4 gamma, f, emid
	gamma = param(1)
	f = 1./ (-gamma+1.)
	do i=1,ne
c ** 	   ** calculate the integral of the counts
	   photar(i) = f * (ear(i)**(1.-gamma) - ear(i-1)**(1.-gamma))
	    end do
	return
	end

The object file will be created by FORTRAN:
 $ FOR POWERLAW 
4 MKUMD
	In order to use the user defined model it most be converted to a
VMS sharable executable.  The MKUMD command was
written to handle a lot of the hassel behind this opaque
statement.  Its simplest possible use would be
 $ MKUMD <Object file>
e.g. MKUMD POWERLAW, as in the above example.  MKUMD will then create a
shareable executable, e.g. POWERLAW.EXE.  You can specify the name of the
executable with a second optional argument to MKUMD, so that
 $ MKUMD POWERLAW TESTLAW
will place the shareable executable in TESTLAW.EXE.  In order to use this
simple form of MKUMD the model code, with the XSUSA1 subroutine and
any subroutines it calls must all be contained in the single
object file  (this would be the case when the source code is contained
in a single FORTRAN file or if the compilation is of the form
 $ for file1+file2+file3...    )
The model is allowed to reference subroutines that are linked automatically
through libraries using the LNK command, for example the XPARSE routines.
In addition, in order to use the simple form of MKUMD, the model subroutines
or any subroutines it calls must not contain any COMMON block statements.
	Both of these conditions can be overcome through the use of a link
options file (see the Xanadu LNK command or the VMS LINK command documentation).
In this case, an option file with extension .OPT is created.  The first
lines of this option file must contain a list of the object modules and
library references needed for the program:
 POWERLAW,SUB1,SUB2,SUB3, -
 ANOTHERSUB,USER:[FRED]FREDSUB, -
 USER:[ME]MYLIB/LI
Then for every common block used by the model subroutine, or by the
subroutines it calls including any library subroutines, a line must be
added of the form
 PSECT = <common block>, LCL,NOSHR
where <common block> is the name of the common block.  For example, if you
have one of the common block POWERCOM somewhere in the code, you must say
 PSECT = POWERCOM, LCL,NOSHR.
	To have MKUMD use the options file, just use the option file name
as the first argument, so if you create a POWERLAW.OPT file then
 $ MKUMD POWERLAW
will continue to work properly, using the OPT file in preference to the OBJ
file.
	When using MKUMD the object file or OPT file can include either
code for XSUSA1 or for XSUSM1 or both.  If one or the other is omitted, then
the default form of the user model will be used.  Thus if you define both
additive and multiplicative models simultaneously, you must have both
included in the OPT or OBJ file.
4 SETUMD
	The SETUMD command is used to change the module used by XSPEC for the
user model shareable executable.  This is done through the definition of a
VMS logical variable, placed in your process logical name table.  Thus you
must use SETUMD before XSPEC if you want to change from the default user
models:
 SETUMD POWERLAW
will define POWERLAW.EXE in the current directory as the current user model
module.
	This definition will continue during the remainder of the session
until superceeded by another SETUMD command.  A SETUMD command executed
within XSPEC (using the $ command in XSPEC) has NO effect on the version
of XSPEC then running (and in fact will have NO effect on subsequent
XSPECs).
	If you run XSPEC in batch mode, be sure that a SETUMD command is
included in the batch file.  Thus in the case of the DOXSPEC command, the
batch file must be edited OR a line must be temporarily added to your
LOGIN.COM making the SETUMD.
4 Running_XSPEC
	After the SETUMD, XSPEC can be invoked normally.  The USERADD1 and/or
USERMUL1 model(s) will properly access your code.  If they do not appear to
be used, check that the source code includes the proper subroutine names:
	SUBROUTINE XSUSA1
or
	SUBROUTINE XSUSM1		.
	If when you attempt to run XSPEC, you fail and receive an error
message saying that your sharable executable is "write enabled and
must be installed", then in all likelihood your user routine uses a common
block that you forgot to properly declare in the OPT file (see the discussion
under MKUMD above).
4 Debugging_(DBUMD)
	The DBUMD command file is an analagous form of MKUMD, used to create a
user model shareable executable from an OBJ or OPT file.  In this case the
module is linked in /DEBUG mode.  To fully use the debugger you should compile
the source code of interest with /NOOPT/DEBUG (or use the FORDB command).  Then
use DBUMD, SETUMD, and finally XSPEC.  In order to use the interactive debugger
you must leave XSPEC in PAUSE mode (through the `exit' command)  and then type
DEBUG to the VMS prompt.  In order to then access the source code, variables,
etc. of the user model you must then type to SET MODULE UMDSHR to debug. 
Remember that the symbolic name of the user models will be XSUSA1 or XSUSM1 and
NOT the filename of the source code.
	As an example of the entire process, recall the POWERLAW example
user model outlined above.  The following might be an example of the debugging
process:
 $ fordb powerlaw
 $ dbumd powerlaw
 $ setumd powerlaw  ! This is optional if it had already been done to
		    !	a non-debug version of POWERLAW.EXE
 $ xspec
 XSPEC> dummy .2 10. 10  ! Define a dummy response matrix with 10 energy ranges
			! from 0.2 keV to 10 keV for test purposes
 XSPEC> exit		! Pause from XSPEC
 $ DEBUG		! Do NOT run any intervening VMS commands
 DEBUG> set module share$umdshr ! This tells debug to access the user models
 DEBUG> set break xsusa1	!   Set a break point at the beginning of the
				!   additive user model.
 DEBUG> go
 XSPEC> model useradd1
 .
 .  ... The user is prompted for the 20 user model parms (plus norm)
 .	    after which a breakpoint is generated at XSUSA1 as the model
 .	    is evaluated.
 .	    
 DEBUG> step
 DEBUG> step
 DEBUG> step
 DEBUG> examine param(1) ! Look at the value of the input parameters
and so on.
