\chapter{A Walkthrough of XSTAR}
\label{sec:walkthrough}

In this section we run through a couple of fictitious interactive XSTAR sessions 
to illustrate how to use XSTAR's interface.  First of all, it 
is important that the environment variables are set in a manner similar to that
required by FTOOLS.  This is described in more detail in Chapter~\ref{sec:installation}.  
Once XSTAR is installed and configured, at the unix prompt, type:

\begin{verbatim}
unix> xstar
\end{verbatim}

By invoking XSTAR with this simple command, you will be prompted for 
a series of physical and control parameters for the simulation.

The input parameters are: The model covering fraction, temperature, 
pressure or density, spectrum shape and ionizing
luminosity, column density, ionization parameter,
and element abundances relative to their cosmic 
abundances.  Definitions for these and the units assumed 
are described in detail in chapter~\ref{sec:xstarinput}.  
All input parameters have default values, selected by pressing return at 
the prompt, thus it is possible to simply start XSTAR as above to invoke 
the default model.

Input of these parameters is handled through an IRAF-style interface, XPI, 
developed for the FTOOLS suite of programs.  This has several features
which may prove convenient to the user: (i) Parameter values from 
an invocation of XSTAR are stored and available as default values
for the next XSTAR run.  These are shown in square brackets 
when the user is prompted for values. (ii) Default values of input 
parameters are stored in the file xstar.par which is stored in the 
directory specified by the PFILES environment variable. (iii) Each 
parameter has an allowed range of values, shown in parentheses 
during the prompting.  Input values outside of this range will result
in exiting the program.  (iv) Input parameters can be hidden from the 
prompting process.  Such parameters, in the default xstar.par, are 
those which are expected to be unneeded for simple problems.  
Manipulation of these parameters requires a slightly more advanced 
familiarity with the code. (v) Parameter values can be input from the 
command line rather than by prompting.  
The value of this scripting capability will be seen in 
Chapter~\ref{sec:xstar2xspec} which discusses building table models 
for the XSPEC spectral analysis program.  All these features 
are described in more detail in the documentation for FTOOLS
\begin{verbatim} (c.f. <http://heasarc.gsfc.nasa.gov/docs/frames/hhp_sw.html>)
\end{verbatim}

It is also possible to run a model at a fixed temperature, i.e. to 
disable the thermal equilibrium condition.  In order to do this the
ordinarily hidden parameter {\bf niter} must be set to 0, and then
the {\bf temperature} parameter must be set to the desired value
(in units of 10$^4$ K).


In the sections that follow are a few XSTAR sessions to 
illustrate using the program.  We illustrate both the prompted 
and the command line invocation of XSTAR with only the required parameters
specified.  


\section{XSTAR Model: Spherical cloud}

In this example we model a spherical, constant density cloud with a source 
at its center.  The cloud is optically thin. The source luminosity is 10$^{28}$ erg s$^{-1}$.  
The ionization parameter at the inner edge of the cloud
is log($\xi$)=5.  The ionizing spectrum 
is a power law with energy index -1.  We show how this model
can be run in two ways: first by invoking XSTAR with no parameter values
and utilizing the prompting for parameter values from XPI, and second by entering 
parameter values directly on the command line.  In the former case, the prompt strings are 
more descriptive than the parameter values themselves, but the net result is the same 
in both cases.  

Using prompting:

\begin{verbatim}

unix > xstar
 xstar version 2.2.0
covering fraction (0.:1.) [1.] 
temperature (/10**4K) (0.:1.e4) [10000.] 
constant pressure switch (1=yes, 0=no) (0:1) [0] 
pressure (dyne/cm**2) (0.:1.) [0.03] 
density (cm**-3) (0.:1.e18) [1.e+4] 
spectrum type?[pow] 
radiation temperature or alpha?[-1.] 
luminosity (/10**38 erg/s) (0.:1.e10) [1.e-6] 
column density (cm**-2) (0.:1.e25) [1.E17] 
log(ionization parameter) (erg cm/s) (-10.:+10.) [5.] 
hydrogen abundance (0.:100.) [1.] 
helium abundance (0.:100.) [1.] 
carbon abundance (0.:100.) [1] 
nitrogen abundance (0.:100.) [1] 
oxygen abundance (0.:100.) [1] 
fluorine abundance (0.:100.) [1.0] 
neon abundance (0.:100.) [1] 
sodium abundance (0.:100.) [1.0] 
magnesium abundance (0.:100.) [1] 
aluminum abundance (0.:100.) [1.0] 
silicon abundance (0.:100.) [1] 
phosphorus abundance (0.:100.) [1.0] 
sulfur abundance (0.:100.) [1] 
chlorine abundance (0.:100.) [1.0] 
argon abundance (0.:100.) [1] 
potassium abundance (0.:100.) [1.0] 
calcium abundance (0.:100.) [1] 
scandium abundance (0.:100.) [1.0] 
titanium abundance (0.:100.) [1.0] 
vanadium abundance (0.:100.) [1] 
chromium abundance (0.:100.) [1.0] 
manganese abundance (0.:100.) [1.0] 
iron abundance (0.:100.) [1] 
cobalt abundance (0.:100.) [1.0] 
nickel abundance (0.:100.) [1] 
copper abundance (0.:100.) [1.0] 
zinc abundance (0.:100.) [1.0] 
model name[filled sphere] 

\end{verbatim}

Using the command line:


\begin{verbatim}
xstar cfrac=1 temperature=1000. pressure=0.03 density=1.E+4 spectrum='pow' 
trad=-1. rlrad38=1.E-16  column=1.E+16   rlogxi=5.  lcpres=0 habund=1 heabund=1 
 liabund=0. beabund=0. babund=0. cabund=1. nabund=1 oabund=1 fabund=1 neabund=1 
naabund=1 mgabund=1 alabund=1 siabund=1 pabund=1 sabund=1 clabund=1 arabund=1 
kabund=1 caabund=1 scabund=1 tiabund=1 vabund=1 crabund=1 mnabund=1 feabund=1 
coabund=1 niabund=1 cuabund=1 znabund=1 modelname='filled sphere' niter=0  npass=1 
critf=1.E-07 nsteps=6 xeemin=0.04 emult=0.5 taumax=5. lprint=1  ncn2=999 
radexp=0 vturb=1.
\end{verbatim}

\section{xstar Model: H II region}

In this example we model an H II region with parameters corresponding to the 
first of the Lexington benchmarks (see appendix C).  In this case we give only 
the prompted values.  This illustrates the use of a blackbody spectrum, with 
temperature given in keV, and non-solar abundances.

\begin{verbatim}

unix > xstar
 xstar version 2.2
covering fraction (0.:1.) [1.] 
temperature (/10**4K) (0.:1.e4) [100.] 1.
constant pressure switch (1=yes, 0=no) (0:1) [0] 
pressure (dyne/cm**2) (0.:1.) [0.03] 
density (cm**-3) (0.:1.e18) [1.E+12] 1.e+2
spectrum type?[pow] bbody
radiation temperature or alpha?[-1.] 0.004
luminosity (/10**38 erg/s) (0.:1.e10) [1.] 12.7
column density (cm**-2) (0.:1.e25) [1.E23] 
log(ionization parameter) (erg cm/s) (-10.:+10.) [2.] 0.15
hydrogen abundance (0.:100.) [1.] 
helium abundance (0.:100.) [1.] 
carbon abundance (0.:100.) [1.]0.5945
nitrogen abundance (0.:100.) [1.] 0.3639
oxygen abundance (0.:100.) [1.] 0.4739
neon abundance (0.:100.) [1.] 1.7865
magnesium abundance (0.:100.) [1.] 0.
silicon abundance (0.:100.) [1.] 0.
sulfur abundance (0.:100.) [1.] 0.563
argon abundance (0.:100.) [1.] 0.
calcium abundance (0.:100.) [1.] 0.
iron abundance (0.:100.) [1.] 0.
nickel abundance (0.:100.) [1.] 0.
model name[xstar Default] H II region

\end{verbatim}

\section{xstar Model: Quasar Broad Line Cloud}

In this example we model a quasar broad line cloud.  In this case we give only 
the prompted values.  This illustrates the use of constant pressure and a 
power law spectrum, with spectral index input in energy units.

\begin{verbatim}

unix > xstar
 xstar version 2.2
covering fraction (0.:1.) [1.] 0.
temperature (/10**4K) (0.:1.e4) [100.] 1.
constant pressure switch (1=yes, 0=no) (0:1) [0] 1
pressure (dyne/cm**2) (0.:1.) [0.03] 
density (cm**-3) (0.:1.e18) [1.E+12] 1.e+10
spectrum type?[pow] pow
radiation temperature or alpha?[-1.] -0.9
luminosity (/10**38 erg/s) (0.:1.e10) [1.] 1.e+8
column density (cm**-2) (0.:1.e25) [1.E23] 
log(ionization parameter) (erg cm/s) (-10.:+10.) [2.] 0.2
hydrogen abundance (0.:100.) [1.] 
helium abundance (0.:100.) [1.] 
carbon abundance (0.:100.) [1.]
nitrogen abundance (0.:100.) [1.] 
oxygen abundance (0.:100.) [1.] 
neon abundance (0.:100.) [1.] 
magnesium abundance (0.:100.) [1.] 
silicon abundance (0.:100.) [1.]
sulfur abundance (0.:100.) [1.] 
argon abundance (0.:100.) [1.] 
calcium abundance (0.:100.) [1.] 
iron abundance (0.:100.) [1.] 
nickel abundance (0.:100.) [1.] 
model name[xstar Default] quasar BLR cloud

\end{verbatim}

