##quit

Exit the current session of SPEX, closing any opened files.

##log

SPEX has the option to store and read commands from log files.  A log file is a
copy of a sequence of commands from a previous SPEX run.  The log file may be
used to `record' steps that can be `played back' at a later time.  After the log
file is closed, it may be edited with an ASCII editor, for example to add
comment lines (comment lines start with an # as the first character of a new
line).

It is also possible to store SPEX output into a file. If in the following
options no path is specified, SPEX will read or write to a file in the
directory from which SPEX was started.

Allowed Syntax:

1. Log Execute #a                             execute all commands from file #a 
2. Log Save #a [Overwrite] [Append]           store next commands in file #a 
3. Log Output #a [Overwrite] [Append]         store output of SPEX in file #a
4. Log Close Save                             close file opened at stage 2 above
5. Log Close Output                           close file opened at stage 3 above

Here #a is the filename that the user specifies.  Note that this file is a
simple ASCII-file. Filenames are limited to 256 characters (including any
path names).   

The optional keyword overwrite can be used to overwrite an existing file (i.e.
replace a previous file if it exists).

The optional keyword append can be used to append output to filename if it
exists, or to open a new file if it does not exist.

##distance

This option allows the user to change or display the distance of the source.
SPEX needs a fixed source distance, since it calculates absolute luminosities.
The distance is needed in order to convert this to the observed flux at Earth.

Allowed Syntax:

1. DIstance SEctor #i1     #r [unit]   Sets the distance for sector #i1
2. DIstance SEctor #i1:#i2 #r [unit]   Sets the distance for sectors #i1 - #i2
3. DIstance                #r [unit]   Sets the distance for all sectors
4. DIstance SHow                       Displays the current distance
5. DIstance H0 #r                      Sets Hubble's constant to #r km/s/Mpc
                                       [default at startup: 50 km/s/Mpc]
6. DIstance Q0 #r                      Sets the deceleration parameter q0 to #r
                                       [default at startup: 0.5]

The distance for all sectors is set to the value #r, unless the optional keyword
[SEctor] with the associated sector number #i1 (integer value) or sector range
#i1 - #i2 is used, in which case the distance is only changed for the relevant
sectors.  Further the optional [unit] is the associated distance unit.  Allowed
distance units are:

   spex - internal SPEX units of 1E22 m (this is the default)
   m    - meter
   au   - astronomical unit
   ly   - lightyear
   pc   - parsec
   kpc  - kpc
   mpc  - Mpc
   z    - redshift units for the given H0 and q0
   cz   - recession velocity in km/s for the given H0 and q0

##elim

It is possible to display the observed flux and intrinsic luminosity of the
source within a certain energy band, e.g.  the 2-10 keV band, or a certain
wavelength band, e.g.  the 0.5-10 nm band.

Allowed Syntax:

1. ELim #r1 #r2 [unit]

where #r1 and #r2 are the lower and upper boundary, and the optional [unit]
is the energy or wavelength unit (default value: keV). These limits are
always transformed to a keV scale within SPEX. Allowed units are

   keV  - kiloelectronvolt (the default)
   eV   - electronvolt
   ryd  - Rydberg
   j    - Joule
   hz   - Hertz
   a    - Angstrom
   nm   - nanometer

The user should take care that these limits are not broader than the
energy grid used (either set explicitly by the egrid command or implicitly
implied by any available instruments); flux outside the energy grid range
will not be accounted for.

##egrid

For calculations where no instrument is used the user can specify the energy
grid for which the spectral calculations are to be made. This grid can
either be specified or read from file, and can be saved.

Allowed Syntax:

1. EGrid LIn #r1 #r2 #i [unit]        Lin. grid from #r1 to #r2 with #i bins
2. EGrid LIn #r1 #r2 Step #r3 [unit]  Lin. grid from #r1 to #r2 with step #r3
3. EGrid LOg #r1 #r2 #i [unit]        Log. grid from #r1 to #r2 with #i bins
4. EGrid LOg #r1 #r2 Step #r3 [unit]  Log. grid from #r1 to #r2 with step #r3
5. EGrid Read #a                      Read grid from file #a
6. EGrid Save #a                      Save current grid to file #a

The lin/log option allows the user to select an equally spaced linear or
logarithmic grid in the energy or wavelength range #r1 - #r2, with #i the number
of bins and the optional [unit] the unit of energy/wavelength (default value:
keV).  In case the step keyword is specified, instead of the number of bins the
step size #r3 is specified, in the same units as #r1 and #r2 for a linear grid,
and in 10log- steps (i.e.  dimensionless) for a logarithmic grid.  Allowed units
are

   keV  - kiloelectronvolt (the default)
   eV   - electronvolt
   ryd  - Rydberg
   j    - Joule
   hz   - Hertz
   a    - Angstrom
   nm   - nanometer

Alternatively, the read or save option allows the user to read an arbitrary
energy grid (units: keV) or to save the current grid (units:  keV) to the file
specified by filename. This is a simple ascii-file containing on subsequent
lines the energy bounds of the bins (thus, the number of lines should be 1 more
than the number of bins).

##abundance

With this option the user can change the standard set of elemental abundances.

Allowed syntax:

1. ABundance set

where set is the set of abundances used. Allowed sets:

  reset    - reset to default at startup, currently Anders & Grevesse 1989 
  ag       - Anders & Grevesse 1989
  allen    - Allen 1973
  ra       - Ross & Aller 1976
  grevesse - Grevesse 1992
  
##ibal

It is possible to choose different options for the ionisation balance,
although we recommend the default standard.

Allowed syntax:

1. IBal set

where set is the ionisation balance used. Allowed sets:

  reset   - reset to default at startup, currently ar92
  ar85    - Arnaud & Rothenflug 1985
  ar92    - Arnaud & Rothenflug 1985 + Arnaud & Raymond 1992 for Fe
  
##var

With the var command several internal SPEX variables can be set.

Allowed syntax:

1. Var Gacc Reset        Reset free-bound gaunt factor accuracy to default 1E-3
2. Var Gacc #r           Set free-bound gaunt factor accuracy to #r
3. Var Line type1 #l     Include line emission process type1 true/false
4. Var Line Reset        Include all line emission processes (the default)
5. Var Line Show         Show the line emission processes that are used
6. Var Doppler #2        Line broadening true/false (false = no broadening)
7. Var Calc type2        Use type2 for the line calculations

In the above, #l is a logical parameter set to true or false.  For the line
emission processes keywords "type1" (syntax nr 3), the allowed values are

  ex - Electron excitation
  rr - Radiative recombination
  dr - Dielectronic recombination
  ds - Dielectronic satellites
  ii - Inner shell ionisation
  
The type of line calculation type2 (syntax nr 7) can have the following values:

  old - old mekal-type calculation
  new - new updated calculation
  
##ions

It is possible to do the spectral calculations with a limited set of ions only.
This is mainly useful in order to display the contribution from a single
ion or set of ions to the total spectrum.

Allowed syntax:

1. IOns all              Selects all ions
2. IOns none             Ignore all ions
3. IOns iso #i1          Select ions from iso-electronic sequence #i1
4. IOns iso #i1 : #i2    Select ions from iso-electronic sequences #i1 - #i2
5. IOns z #i1            Select ions from element with Z = #i1
6. IOns z #i1 : #i2      Select ions from element with Z = #i1 to Z = #i2
7. IOns ion #i1 #i2      Select ion from element Z = #i1 and stage #i2
8. IOns show             Show all the selected ions.

In option 7, the (ionisation) stage is the number of lost electrons minus 1,
e.g. for Fe XXIV we would have #i1=26 (for Fe) and #i2=24.

##data

Data should be entered as response file and associated data file.

Allowed syntax:

1. DAta #a1 #a2                 Read data: response file #a1 
                                and spectrum file #a2
2. DAta Delete #i               Delete data set #i from the analysis
3. DAta SHow                    Show all data sets
4. DAta SAve #i #a [Overwrite]  Save the spectrum of instrument #i to file #a

The optional Overwrite with the save keyword can be used to force to overwrite
any existing file.
                       
##ignore

With the ignore option, certain data channels can be omitted from the analysis.
The user should specify the instrument (range), region (range) and channel (range)
for which channels are to be omitted. Note that any binning information
on the ignored channels is lost when these channels are re-used using the
"use" command. The ignored channels can be ignored permanently by using
the "optimize" command.

Allowed syntax:

1. IGnore [Instrument range1] [Region range2] range3

where range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the region range and
range 3 is the channel range.
If the instrument keyword together with its range is omitted, all instruments
will be involved; similar, if the region keyword with its range is omitted,
all regions will be involved.
                       
##use

With the use option, certain data channels that were omitted from the analysis
are taken into account again.  The user should specify the instrument (range),
region (range) and channel (range) for which channels are to be used again.  The
channels that were previously not used but are selected here are not rebinned.
No ignored channels can be restored after that the user has used the "optimize"
command.

Allowed syntax:

1. USe [Instrument range1] [Region range2] range3

where range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the region range and
range 3 is the channel range.
If the instrument keyword together with its range is omitted, all instruments
will be involved; similar, if the region keyword with its range is omitted,
all regions will be involved.
                       
##bin

With the bin option, certain data channels can be taken together in the spectral
analysis.  This should always be done in cases where the original data are
over-sampled, like most X-ray experiments.  It is also a usefull option in those
cases where the spectrum is weak, in order to improve the signal-to-noise ratio.
The user should specify the instrument (range), region (range), channel (range)
and number of bins taken together for the rebinning. The rebinning can be made
permanently and irreversible by using the optimize command. Otherwise the
original binning can be restored by rebinning back to 1 channel per bin.

Allowed syntax:

1. BIn [Instrument range1] [Region range2] range3 #i4

where range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the region range and
range 3 is the channel range. Finally, #i4 is an integer number, representing
the number of bins taken together.
If the instrument keyword together with its range is omitted, all instruments
will be involved; similar, if the region keyword with its range is omitted,
all regions will be involved.
                       
##vbin

With the vbin option, certain data channels can be taken together in the
spectral analysis, using a variable binning algorithm.  The user should specify
the instrument (range), region (range), channel (range) and minimum number of
bins taken together for the rebinning.  Also the minimum s/n ratio should be
specified.

The algorithm loops through the spectrum, starting from the highest significant
channels, and rebins untill at least the minimum number of bins is reached, or
otherwise the minimum s/n ratio is achieved.  The s/n ratio however cannot be
guaranteed, since a particular bin might get less significant by adding
low s/n neighbouring bins.

The rebinning can be made permanently and irreversible by using the optimize
command.  Otherwise the original binning can be restored by rebinning back to 1
channel per bin by using the bin command.

Allowed syntax:

1. VBin [Instrument range1] [Region range2] range3 #i4 #r

where range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the region range and
range 3 is the channel range. Finally, #i4 is an integer number, representing
the minimum number of bins taken together, and #r is the minimum s/n ratio.
If the instrument keyword together with its range is omitted, all instruments
will be involved; similar, if the region keyword with its range is omitted,
all regions will be involved.
                       
##syserr

With the syserr option, certain data channels can be given an additional
systematic error in the spectral analysis.  This can be done as a fraction of
the source spectrum as well as a fraction of the subtracted background.  This
option is always recommended in cases with high s/n spectra, where the
calibration of the instrument effective area is less accurate than the s/n ratio
of the data.  The user should specify the instrument (range), region (range),
channel (range) and sytematic error in source and background.  These systematic
errors are irreversible, however, so the user should take care.

Allowed syntax:

1. SYserr [Instrument range1] [Region range2] range3 #r1 #r2

where range1 is the instrument range, either an integer number #i indicating the
instrument number, or two integer numbers separated by a semicolon to indicate
the range of instruments.  Similar, range2 is the region range and range 3 is
the channel range.  Finally, #r1 and #r2 are real numbers, representing the
systematic error in source and background spectrum, respectively.  If the
instrument keyword together with its range is omitted, all instruments will be
involved; similar, if the region keyword with its range is omitted, all regions
will be involved.
                       
##optimize

With the optimize option, the data binning and data channel selection, obtained
from previous call of the multiply, ignore, bin or vbin command, can be made
permanently.  This can help to increase the processing speed of the subsequent
spectral analysis.  The user should specify the instrument (range) and region
(range) for which the optimization is to be done.  Note that this is an
irreversible process, which can be restored only by deleting the instrument
completely and reading the data back.

Allowed syntax:

1. OPtimize [Instrument range1] [Region range2]

where range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the region range.
If the instrument keyword together with its range is omitted, all instruments
will be involved; similar, if the region keyword with its range is omitted,
all regions will be involved.

#multiply

It is possible to scale the effective area of any component of one of the
instruments.

Allowed syntax:

1. MUltiply range1 #r
2. MUltiply range1 Component range2 #r

Here range1 is the instrument range, either an integer number #i indicating
the instrument number, or two integer numbers separated by a semicolon to
indicate the range of instruments. Similar, range2 is the component range.
Finally #r is the multiplication factor.


##sector

SPEX can analyze spectra originating from different sectors.  A sector can be a
distinct region of the sky, or a spectrum of a time series of a source.  At
startup, there is always one sector.  The user can define or delete any number
of sectors, as long as there remains at least one sector.  In each sector, a
different model can be set up and the spectra of all the sectors can be analyzed
simultaneously.

Allowed syntax:

1. SEctor New                   Set up a new sector
2. SEctor Copy #i               Set up a new sector containing model and
                                parameters of sector #i
3. SEctor Delete #i1            Delete the sector number #i1 
4. SEctor Delete #i1 : #i2      Delete the sector number #i1 
5. SEctor Show                  Shows the sectors

In the above, the sector range is either a sector number #i1 or a range
specified as #i1 : #i2 where #i1 and #i2 are the lower and upper limit.


##model

Using the model option, the model can be defined for a single sector or a 
range of sectors.

Allowed syntax:

1. MOdel [range1] comp                         Adds component comp to the model
2. MOdel Delete [range1] range2                Deletes components
3. MOdel Relation [range1] range2 dependency   Sets the dependency amongst
                                               the spectral components
4. MOdel show                                  Shows the model

In the above, range1 is the instrument range for which the model is to be
defined or deleted, and range2 the component range. Further, comp
represents the name of a valid spectral component (see   ....) for a list
of valid components). The dependency should be entered in the form of
a string of integer numbers, each integer representing a component number,
in the order in which they should be applied to the spectrum of a component.
Currently only dependencies within the same sector are allowed.

##par

It is possible to set several properties of model parameters.  These include the
value, fit status, upper and lower limit, as well as the coupling status of
the parameter. The parameter value is a real quantity. Its status can either be
frozen/false or thawn/true. A frozen parameter cannot vary during spectral
fitting, a thawn parameter can. The upper and lower limit can be changed by the
user in order to restrict the range of the solution. Finally, the value of any
parameter can be coupled to the value of any other parameter during fitting,
such that their ratio always remains constant. This is in particular useful
for e.g. restricting the number of free parameters.

Allowed syntax:

1. par [range1 [range2 [range3]]] value #v        sets parameter value to #v
2. par [range1 [range2 [range3]]] status #s       sets status to #l
3. par [range1 [range2 [range3]]] range #l #u     sets range to #l to #u

4. par [range1 [range2 [range3]]] couple [range4 [range5 [range6]]] [factor #f]
                                                  
            couples lefthandside to righthandside with factor #f

5. par [range1 [range2 [range3]]] decouple        decouples parameters
6. par show                                       shows the parameters

Here #v represents the parameter value, #s its status, #l and #u the lower and
upper limit, and #f the coupling factor.  In the above, the optional range3
represents the parameter range (indicated by the name of the first parameter and
optionally the last parameter, separated by a :).  If range3 is omitted, the
same parameter range is taken as the last time that the par command was used.
Similar, the optional range2 is the range of the components, and the optional
range1 the range of the sectors involved.  Also for these ranges, when they are
omitted the same range is taken as the last time that the par command was used.

Finally for the coupling, range4, range5 and range6 denote the sector, component
and parameter range for the target parameter. When omitted, it is assumed that
they take the same values as the corresponding range1, range2 and range3.
Note that it is possible to either couple
all parameters of the left hand side to a single parameter, or couple them
to a range of parameters; in the last case, the corresponding number of elements
on the left- and righthandside should be equal.

##simulate

Using the simulate option it is possible to simulate spectra that subsequently
can be used for spectral analysis. The existing observational data are replaced
by these simulated spectra.

Allowed syntax:

1. SImulate [instrument range] [region range] [time #ts #tb] [syserr #es #eb]
         [noise #ln] [back #lb]
         
All the keywords are optional; if not provided, the default values are assumed.
The meaning of these parameters is:

   instrument range - default value: all instruments
   region range     - default value: all regions
   time #ts #tb     - source & background integration time in s. Default
                      value: 1E5 s for both.
   syserr #es #eb   - systematic source & background error as a fraction of the
                      total source and background spectrum. Default value: 0.
   noise #ln        - Poissonian noise to be included; #ln is a logical
                      value, if true (default), the data will be randomized.
   back #lb         - background spectrum to be subtracted; #lb is a logical
                      value, if true (default), background will be subtracted.
                      
##fit

Spectra are fit using this option.

Allowed syntax:

1. FIt Method #a       sets the fitting method to option #a (see below)
2. FIt Weight Data     use the data errors as weights in the fits
3. FIt Weight Model    use the current model to predict the errors to be used
                       as weights in the fits
4. FIt Print #i        print/plot each iteration step during the fitting process
6. FIt                 do the spectral fit

In the above, the fitting method #a can have the following values:

   classical  - classical Levenberg-Marquardt minimization (default).
   simplex    - simplex fitting method
   
##error

The error on one or more parameters is determined using this option.

Allowed syntax:

1. ERror dchi #r                     Set the critical chi**2 to chi**2_min + #r
2. Error [range1 [range2 [range3]]]  Do the error search

In the above, the optional range3 represents the parameter range (indicated by
the name of the first parameter and optionally the last parameter, separated by
a :).  If range3 is omitted, the same parameter range is taken as the last time
that the error search was done.  Similar, the optional range2 is the range of
the components, and the optional range1 the range of the sectors involved.  Also
for these ranges, when they are omitted the same range is taken as the last time
that the error search was done.

##step

It is possible to do a grid search on a maximum of 4 parameters.

Allowed syntax:

1. STep dimension #i             Set the number of parameters for which the
                                 grid search should be done to #i
2. STep axis #ia parameter [[#is] #ic] #a range #r1 #r2 n #in
                                 Set for axis number #ia the parameter given
                                 by sector #is, component #ic and parameter name
                                 #a, to the range given by #r1 to #r2,
                                 with #in steps. If #in is negative, logarithmic
                                 steps will be taken
3. STep                          Do the grid search