\chapter{Obtaining and Running XSTAR}
\label{sec:installation}

XSTAR is available through two sources.  It is included in the 
general FTOOLS distribution (version 4.3 and later) and as a standalone package.

\section{XSTAR as Part of the FTOOLS Package}

Instructions for installation of the heasoft package are available elsewhere
\begin{verbatim} 
http://heasarc.gsfc.nasa.gov/lheasoft
\end{verbatim}
On a system where heasoft is already installed it is necessary to 
run the same script required for other ftools in order to make sure 
environment variables are set properly for xstar: 

\begin{verbatim}
setenv HEADAS /path-to-architecture
source $HEADAS/headas-init.csh
\end{verbatim}

where 'path-to-architecture' is the full path to the directory containing the compiled executables 
and libraries for the headas software.

\section{XSTAR as a Standalone Package}

The standalone version of xstar is available as a gzipped and tarred file 
on the xstar website
\begin{verbatim} 
http://heasarc.gsfc.nasa.gov/docs/software/xstar/xstar.html
\end{verbatim}
The source code is available along with compiled executables for 
several machine architectures.  Installation requires that the file be downloaded, and the 
instructions in the README file followed.

\section{Subroutine XSTAR}

This is a version of XSTAR which retains most of the functionality 
of the full code, but which provides a framework whereby XSTAR can be 
called as a subroutine from another program, or whereby XSTAR can 
be applied to situations which do not employ the standard assumptions 
concerning, e.g. the gas density distribution, geometry, or time-steady
behavior.  This consists of a large fortran file containing all of the 
subroutines employed by the standard XSTAR, together with two wrapper 
programs: xstarsetup.f and xstarcalc.f.  As implied by the names, 
xstarsetup.f is intended to be called once at the beginning of a calculation
and handles reading of input data and initialization; xstarcalc.f 
calculates the physical conditions at one point in a photoionized gas
and returns level populations, emissivities, opacities, etc.
In addition there is a calling program which is intended to illustrate 
the use of these subroutines.  Subroutine XSTAR also requires 
the two fits data files, atdat.fits and aptrs.fits, and must be 
linked to the cfitsio subroutine library.  All are available via ftp from
\begin{verbatim} 
ftp://legacy.gsfc.nasa.gov/software/plasma_codes/xstar/subroutine/
\end{verbatim} 


\section{The XSTAR Web Site}

See the XSTAR web site http://heasarc.gsfc.nasa.gov/docs/software/xstar/xstar.html
for updates and other news about XSTAR.
