\chapter{An Overview of XSTAR}
\label{sec:overview}

\section{Basic Operation}

An XSTAR session consists of several basic steps: initial setup, 
model calculation, and final printout.  
The initial setup consists of the input of various parameter values necessary to specifying 
a model, reading in atomic data files, and the  program's internal 
initialization.
The model calculation consists of the 
calculation of ionization, excitation, and thermal equilibrium, and 
radiation transfer (as described in Chapter~\ref{sec:physics}) at each of a number of 
spatial grid points.  After the model calculation various quantities are output, and the 
program terminates. The details of the input parameters are described in 
Chapter~\ref{sec:xstarinput}, and the output is described in Chapter~\ref{sec:xstaroutput}.  
Note that both of these have 
changed significantly since version 1.  In this chapter we describe general 
features of the XSTAR operation which are important to the user.

\subsection{Important note}

Although XSTAR is designed to be relatively user-friendly, and is 
supplied along with user-oriented software for data analysis, its 
use inevitably implies risk of incorrect or undesired results.  
Common among these are application to situations where the physical 
assumptions or numerical accuracy breaks down, or attempts to solve 
problems beyond the capabilities of the machine being used.
The user is urged to read chapter~\ref{sec:pitfalls}, `Problems and Pitfalls', before
attempting changes to parameter values far beyond those in the sample
parameter files.

\subsection{Command syntax}

As described in the previous chapter, XSTAR is invoked from the command line either 
with or without parameter specifications.  In the latter case the user is 
prompted for parameter values.  Operation can be interrupted or invoked in the 
background.

\subsection{Defining input spectra}

XSTAR allows users to input ionizing spectra constructed of several simple 
functional forms:  bremsstrahlung, blackbody, or power law.  Alternatively, 
more complicated spectra can be stored in an ascii file, and used by XSTAR 
as input.  This is discussed in more detail in Chapter~\ref{sec:xstarinput}.


\subsection{FITS Files \& Graphical Output}

The primary output method for XSTAR is via FITS files. The Interactive 
Data Language (IDL) has a number of routines designed for reading 
data from FITS files (see http://idlastro.gsfc.nasa.gov).  In 
addition, the program FV supported by the HEASARC provides 
viewing and plotting capabilities of FITS data.  The CFITSIO 
package provides additional support to read FITS files in both C and 
Fortran programming languages.  Information on these packages is 
available through the `Software' link on the HEASARC home page 
(http://heasarc.gsfc.nasa.gov/).

\subsection{The Atomic Database}
The atomic data is supplied with the code in a single binary FITS 
file named atbd.fits and known as the Atomic Database.  An ascii version of this is 
available from the xstar website.

\subsection{Supported Platforms}

An additional benefit of integrating XSTAR into the FTOOLS suite 
is that support is maintained across a wide range of platforms, notbly 
Linux (x86, redhat) and Mac OSX.

\subsection{Installation}

Version 2 is distributed by default as part of the HEAdas analysis 
package.  It is also available to be installed and run stand-alone, 
and the procedures for obtaining and installing it are described in Chapter~\ref{sec:installation}.

\subsection{Subroutine XSTAR}

One consequence of the change in the user interface between versions 1 and 2 was a loss 
of certain features, and some flexibility in specifying input 
parameters.  Examples include pipelined models and variable gas 
density.  This sacrifice was deemed acceptable in the interests of streamlined 
and simplified execution, and because these features were not often 
used (as far as we know).  In an effort to preserve these 
features in some form for dedicated users we also provide the 
capablility to call XSTAR as a fortran subroutine, which allows 
the user flexibility in specifying geometry, spectrum and density.
This is described in Chapter~\ref{sec:installation}.

\section{Limitations}

One of the potential pitfalls of using a `blackbox' code such as XSTAR 
is the application to problems for which its inherent assumptions or
numerics are invalid or inaccurate.  The best way to avoid this is 
to thoroughly understand the computational methods as outlined 
in Appendix~\ref{sec:physics}.  The user is urged to read Chapter~\ref{sec:pitfalls}: 
``Problems and Pitfalls'' in order to avoid the most obvious of these.
In what follows we have attempted to supply 
a few simple rules, which will, we hope, keep the less careful 
user from going into forbidden territory. 

\subsection{Temperature}

At high temperature, $\geq 10^9 K$, the assumption of non-relativistic 
electron velocities becomes invalid, and a variety of physical processes 
such as electron-positron pair production may come into play.  At very 
low temperatures, $\leq 3000 K$, many of the analytic fitting formulae 
used to parameterize atomic rates are unreliable, and 
the neglect of molecule formation and atomic fine structure cooling renders
rates inaccurate.  The code does not allow temperatures less than 
3000K for this reason and because serious numerical errors can occur.
If lower values are attempted the temperature is artificially reset to 3000K.
On the high temperatures end, there is no mechanism preventing 
values greater than  $10^9 K$, but the user should be aware that in this 
regime the rates are probably unreliable.


\subsection{Density}

The atomic rates for H and He-like ions are accurate for densities up to 
$10^{18}$ cm$^{-3}$ by taking into account the effects of 3-body
recombination and lowering of the continuum (\cite{bautista1998},
\cite{bautista1999}). However, these effects are not treated for 
other species which reduce the accuracy of the model results for these 
ions at high density. The density for which 
these effects become important for a given ion increases rapidly with effective charge of
the ion, starting at about $10^{12}$ cm$^{-3}$ for z=1 and at about 
$10^{16}$ cm$^{-3}$ for z=8.  At low densities numerical errors can occur;
the user is urged to read chapter~\ref{sec:pitfalls}.

\subsection{Column Density}

For column densities greater than $1.5 \times 10^{24}$ cm$^{-2}$, 
corresponding to a Thomson depth of unity, neglect of 
`Comptonization', spectral modification arising from Compton scattering, 
makes model results incorrect.

 In addition, the upper bound on
volume density declines as the total column density increases.  The
reason is that the number of transitions in detailed balance increases
rapidly as the product of volume density and column density rises.  Once
many transitions are in detailed balance, the thermal balance becomes
determined by transitions involving rarer species and excited states
which are not included in the calculation.  As a rough rule of thumb,
the product of volume density and column density should not exceed
$10^{34}$ cm$^{-5}$.

\section{Getting help}

Sections of this manual are available using the {\it fhelp} command.
Do not hesitate to contact the author with comments and questions.
