\chapter{User Input to XSTAR}
\label{sec:xstarinput}

On invoking XSTAR from the 
command line, the user is prompted for a series of input values which 
are described below.  These parameters are stored in a parameter file
xstar.par, which must live in the directory specified by the 
user's PFILES environment variable.  Upon the initial invocation of 
XSTAR, the default version of the parameter file is copied into the 
pfiles directory.  Each parameter has associated 
with it a prompt string and a parameter name.  The former is used 
when values are input via prompting, and the latter when values 
are input via the command line.  In sections 1 -- 3 we describe the 
parameters used for most straightforward applications of XSTAR.  In section 5
we discuss the parameters which are ordinarily hidden from prompting, and 
which provide added flexibility.

\section{Input Parameter Summary}

Here we list the XSTAR parameters in entry order.

\begin{tabular}{lll}
	prompt string & parameter name & description \\
	Covering Fraction & cfrac &  Covering Fraction \\ 
	Temperature & temperature & Gas Temperature ($10^4 K$)  \\ 
	Constant Pressure Switch & lcpres & 1=yes, 0=no  \\ 
	Pressure & pressure & Define model pressure in dynes/cm$^2$  \\ 
	Density & density & Density in $cm^{-3}$ \\ 
	Spectrum & spectrum & Define the input spectrum  \\ 
	Spectrum File & spectrum\_file & Name of spectrum file  \\ 
	Spectrum Units & spectun & 0=energy, 1=photons \\ 
	Radiation Temperature or Alpha & trad & keV or unitless ($E^{\alpha}$)\\
	Luminosity & rlrad38 & Luminosity in $10^{38}$ ergs/s  \\ 
	Column Density & column & Column density in cm$^{-2}$ \\ 
	log(ionization parameter) & rlogxi & log($\xi$) (erg cm/s) or log($\Xi$)  \\ 
	Hydrogen abundance & habund & Hydrogen Abundance relative to Solar  \\ 
	Helium abundance & heabund & Helium Abundance relative to Solar  \\ 
	Lithium abundance & liabund & Lithium Abundance relative to Solar  \\ 
	Beryllium abundance & beabund & Beryllium Abundance relative to Solar  \\ 
	Boron abundance & babund & Boron Abundance relative to Solar  \\ 
    Carbon abundance & cabund & Carbon Abundance relative to Solar  \\ 
    Nitrogen abundance & nabund & Nitrogen Abundance relative to Solar  \\ 
    Oxygen abundance & oabund & Oxygen Abundance relative to Solar  \\ 
    Fluorind abundance & fabund & Fluorine Abundance relative to Solar  \\ 
    Neon abundance & neabund & Neon Abundance relative to Solar  \\ 
    Magnesium abundance & mgabund & Magnesium Abundance relative to Solar  \\ 
    Aluminum abundance & alabund & Aluminum Abundance relative to Solar  \\ 
    Silicon abundance & siabund & Silicon Abundance relative to Solar  \\ 
    Phosphorus abundance & pabund & Phosphorus Abundance relative to Solar  \\ 
    Sulfur abundance & sabund & Sulfur Abundance relative to Solar  \\ 
    Chlorine abundance & clabund & Chlorine Abundance relative to Solar  \\ 
    Argon abundance & arabund & Argon Abundance relative to Solar  \\ 
    Potassium abundance & kabund & Potassium Abundance relative to Solar  \\ 
    Scandium abundance & scabund & Scandium Abundance relative to Solar  \\ 
    Titanium abundance & tiabund & Titanium Abundance relative to Solar  \\ 
    Vanadium abundance & vabund & Vanadium Abundance relative to Solar  \\ 
    Chromium abundance & crabund & Chromium Abundance relative to Solar  \\ 
    Manganese abundance & mnabund & Mangnese Abundance relative to Solar  \\ 
    Iron abundance & feabund & Iron Abundance relative to Solar  \\ 
    Cobalt abundance & coabund & Cobalt Abundance relative to Solar  \\ 
    Nickel abundance & niabund & Nickel Abundance relative to Solar  \\ 
    Zinc abundance & znabund & Zinc Abundance relative to Solar  \\ 
    Copper abundance & cuabund & Copper Abundance relative to Solar  \\ 
    Model Name & modelname & Name used for identifying this run \\
\end{tabular}

\section{Description of XSTAR Parameters}

In this section detailed descriptions are given for each of the input
parameters in the order of entry.  

\subsection{Covering Fraction (cfrac)}

This parameter determines whether the geometry is a complete sphere or
covers only part of the continuum source.  In the former case, photons 
escaping the cloud in the 'inward' direction are assumed to reenter the 
cloud at the inner edge owing to the assumption of spherical symmetry.
Default is 1.0.

\subsection{Temperature (temperature)}   

Define temperature, in units of $10^4 K$.  If the parameter 
\ci{niter} is set to 0 then the temperature is fixed at this
value.  Otherwise the value is used as a first guess in calculating the 
thermal equilibrium value.  If the pressure is specified it is also used 
to calculate an initial guess at the gas density, $n=P/(kT)$, 
which is then used to calculate $\Delta R_{max}=N/n$.  Default value is 1.

\subsection{Constant Pressure Switch (lcpres)}

This parameter chooses between constant density (value 0) and constant 
pressure (value 1).
 If the pressure is constant then  the appropriate definition 
of ionization parameter ($\Xi$) is adopted.
If the density is constant then  the appropriate definition 
of ionization parameter ($\xi$) is adopted.
The constant density case is the default.

\subsection{Pressure (pressure)}

Define model pressure in dynes cm$^{-2}$.  Note that this quantity 
represents the full isotropic pressure (neutral atoms + ions + electrons
+ trapped line radiation) instead of just the pressure due to hydrogen
atoms and protons.  Whether or not this quantity is  held fixed  is determined 
by the value of the constant pressure switch lcpres. 
 If the pressure is constant then  the appropriate definition 
of ionization parameter ($\Xi$) is adopted.  In the constant density case, 
lcpres=0, then this quantity is ignored.

\subsection{Density (density)}     

Define model gas density, $n$.  This is actually the hydrogen nucleus
density, so that, e.g., the total particle density in a fully-ionized
plasma with solar abundances is $2.3 n$.  
Units are cm$^{-3}$.  The default value is 
1 cm$^{-3}$.  Whether or not this quantity is  held fixed  is determined 
by the value of the constant pressure switch lcpres. 
If the density is constant then  the appropriate definition 
of ionization parameter ($\xi$) is adopted.
The constant density case is the default.

\subsection{Spectrum (spectrum)}  

Define Spectrum.  Choices and formats are similar to those used 
by XSPEC and are given in Section~\ref{sec:spectra}.  
Note that numerical problems can arise if the radiation field is zero
throughout a significant energy range, because then the photoionization rates
for some ions may be zero, and these appear in the denominator of the 
equations for the ionization balance.  If your input spectrum is not 
one of the internally supported models, enter `file' to specify a 
custom spectrum in a text file using the next two parameters.

\subsection{Spectrum File (spectrum\_file)}

If the `file' option is chosen for the spectrum type, you must 
provide a text file of the spectrum in your current working 
directory.  The first line of the text file must be the number of 
energies listed in the table.  The remaining lines are the energy 
channel (in eV) and the flux in units of photons cm$^{-2}$ s$^{-1}$ erg$^{-1}$ or 
erg cm$^{-2}$ s$^{-1}$ erg$^{-1}$ (see next subsection).  Note that XSTAR will 
appropriately renormalize the luminosity.  Also, be aware 
that small numbers (less than 1.e-30, say), may result 
in undesired results owing to the limitations of many machines 
in the range of exponents.  Again, remember that it is not 
necessary to use actual physical units in specifying the input spectrum
(except to distinguish between photon and energy fluxes)
since the entire spectrum is renormalized to conform to the 
luminosity specified.

\subsection{Spectrum Units (spectun)}

The appropriate units for the spectrum file specified above 
(1=photons cm$^{-2}$ s$^{-1}$ erg$^{-1}$, 0=erg cm$^{-2}$ s$^{-1}$ erg$^{-1}$).
Default is 0

\subsection{Radiation Temperature or Alpha (trad)}

This parameter pulls double duty, used to enter the radiation 
temperature in units of 10$^7$K in the case of a blackbody or 
in units of keV for  bremsstrahlung input model.   It also is used to input  
the power-law index {\it (in energy)}, $\alpha$, in the case of a power-law model.  Note 
that $\alpha$ is defined as in $L_\varepsilon\sim\varepsilon^{\alpha}$ 
so generally $\alpha$ will be {\it less} than zero (this is the opposite of the convention
used by xspec).  XSTAR always works with 
specific luminosity $L_\varepsilon$ in units erg s$^{-1}$ erg$^{-1}$, 
and never uses $\varepsilon L_\varepsilon$ or $\nu F_\nu$, for example.

\subsection{Luminosity (luminosity)}  

Define model luminosity integrated between 1 and 1000 Ry.  
Units are $10^{38}$ erg s$^{-1}$.  Default value is 1.

\subsection{column\_density}   

Define model column density, $N$.  Units are cm$^{-2}$.  This quantity is used 
in calculation of thickness of model slab according to 
$\Delta R_{max}=N/n$ where n is the density or an estimate based on pressure 
and temperature initial values.  The default value for N is $10^{21}$ 
cm$^{-2}$. The model calculation terminates when this value is reached.

\subsection{log of the ionization\_parameter= log($\xi$) or log($\Xi$) (rlogxi)}    

Define initial value of the log (base 10) of the 
model ionization parameter.  If the density is
held constant, the \cite{Tarter1969} form is used:
$\xi = L/(nR^2)$.  If the pressure is held constant, a version of
the Krolik, McKee, and Tarter (1981) form is used: 
$\Xi = L/(4\pi c R^2 P)$.  Note that this differs from the original
form by using the full isotropic pressure (neutral atoms + ions + electrons
+ trapped line radiation) instead of just the pressure due to hydrogen
atoms and protons.  This quantity is used in calculating the radius
of the innermost edge of the shell by inverting the parameter definition.


\subsection{Abundances}  

Atomic abundances are entered {\it relative to solar abundances} as 
defined in \cite{Grevesse1996}, with $1.0$ being defined as the solar 
value and the current default.  Currently supported range for these values 
is $(0.0 \ldots 100.0)$.

The atomic species are all elements up to and including copper (Z=30).  Note 
that as of version 2.2.0 many of these are treated using scaled hydrogenic 
atomic rate data.


\subsection{Model Name (modelname)}  

Define model name, an 80 character string.


\section{The XSTAR Input Spectral Models}
\label{sec:spectra}

This part of the manual provides more information on specific installed 
XSTAR input spectra, as well as the use of the `user' defined model facility.
All spectral shapes are given in terms of the energy flux per unit frequency
interval. 

\subsection{Summary}

\begin{description}
	\item[bbody:]  A Black Body spectrum.

	\item[bremss:] Thermal bremsstrahlung.

	\item[powerlaw:]  Simple photon power law.

	\item[file:]  Specify a custom spectrum in a text file (see the 
	spectrum\_file and spectun parameters).
	
\end{description}

The detailed description of these models are in the sections below.

\subsection{bbody}

A black body spectrum.

\begin{equation}
	A(\varepsilon) =  \varepsilon^3 / (\exp(\varepsilon/kT)-1)
\end{equation}

where T is temperature  in units of $10^7$ K.

\subsection{bremss}

Thermal bremsstrahlung spectrum, including gaunt factors, but not including
$e-e$ bremsstrahlung.  The input parameter for this model is
plasma temperature in keV .

\subsection{powerlaw}

Simple photon power law.

\begin{equation}
	A(\varepsilon) = \varepsilon^{\alpha}
\end{equation}

where $\alpha$ is the energy index of power law.

The user is cautioned that simple power laws can have unintended consequences 
owing to the fact that they are automatically extrapolated to the lowest
(0.1 eV) and highest (1 MeV) energies employed in the calculation.  This 
can cause processes such as stimulated recombination and Compton cooling to 
dominate the model results, and may not represent a physically realistic result.
These effects can be avoided by the use of a simple file spectrum as 
demonstrated below.

\subsection{File}

Fluxes and energies are read from a text file, with name given by the 
`spectrum\_file' keyword.  The format of the file is as follows:
the first line must contain the integer number of (energy, flux) pairs;
each of the the remaining lines contains one (energy, flux) pair, 
with energy  in eV and flux in energy units (overall normalization is arbitrary).
These values will be interpolated onto the energy grid used internally by 
XSTAR using logarithmic interpolation.  An example of a file which results 
in a $\varepsilon^{-1}$ spectrum power law spectrum between 0.1 Ry and 1000 Ry
(and zero elsewhere) is as follows:

\begin{verbatim}
006
1.e-3  1.e-10
1.359 1.e-10
1.3598 1.e+11
1.3598e+5 1.e+6
1.360e+5 1.e-10
2.e+5  1.e-10
\end{verbatim}

As already states, be aware 
that small numbers (less than 1.e-30, say), may result 
in undesired results owing to the limitations of many machines 
in the range of exponents.  And remember that it is not 
necessary to use actual physical units in specifying the input spectrum
(except to distinguish between photon and energy fluxes)
since the entire spectrum is renormalized to conform to the 
luminosity specified.


\section{Direct Editing of the Parameter File}

While XSTAR will prompt users for the standard parameters, there are 
instances where you may wish to edit the parameter list directly.  
These can be edited directly with a text editor such as Emacs or vi.  
There are also several FTOOL parameter manipulation utilities: PSET, 
PGET, PUNLEARN, PLIST, \& PQUERY, in addition to the GUI tool FLAUNCH.

Note that while there are comments recorded in the parameter file as 
originally defined in the FTOOLS build, modifying these parameters 
through the regular XSTAR prompts will cause this parameter file to 
be rewritten {\it without} the comments included.

\section{Hidden Parameters}

The input parameters described so far are those which are the most physically 
relevant to the xstar results.  Other parameters which are more related 
to control of the computation are ordimarily hidden from prompting.
Changing  these parameters requires a understanding of the 
operation of the code.  Note also that the parameter file formalism
allows these parameters to be prompted along with the others, 
simply by changing the `h' to an `a' in the third field of the respective
line of the parameter file.

\subsection{Number of Steps (nsteps)}

This parameter controls the maximum number of spatial zones 
used in a calculation, only in the case where the Courant condition
step is larger than the size of the slab.  That is, 
the step size is calculated as:

$$\Delta R = min( {\rm emult}/\kappa_max(\varepsilon), R/{\rm nsteps})$$

where emult is defined below, and $\kappa_max(\varepsilon)$ is the maximum opacity from the 
previous step calculation.  $\kappa_max(\varepsilon)$  is only calculated from energies where
the optical depth to the illuminated face of the cloud is less than taumax, where 
taumax is defined below.  The default value for nsteps is 2.

\subsection{write\_switch (lwrite)} If the argument is 
a non-zero integer, causes level populations and line emissivities in the interior of the 
shell to be written to a fits dataset at each spatial step for later examination 
or plotting.  These files are named 'xout\_detail.lis' and 'xout\_detal2.lis', 
and can become quite large 
($\geq$ 10 Mb) for a model with many spatial zones.  Various fits
file manipulation routines can be used to filter and plot the
quantities in these files.  Default value is 0.

\subsection{print\_switch (lprint)} This enables 
the printing of many quantities which are defined locally at the last 
spatial zone of the calculation.  These include ion fractions, heating and cooling 
rates, line and continuum emissivities and opacitites, execution times, 
and level populations.  They are printed to the log file, xout\_step.log.
Default value is 0, and results in just the 500 brightest line luminosities (sorted by luminosity) and depths, 
and the 500 brightest recombination continuum (sorted by luminosity)
luminosities and depths to be printed to the log file at the end of the run. With a value 1 many 
additional quantities are printed, including ascii tables of continuum luminosities and depths, 
all line luminosities, along with all useful local quantities such as ion fractions, thermal 
rates, level populations.  Note that these local quantities are printed only at the final step of 
the model run.  With a value of 2 all rates affecting level populations, ionization, heating and 
cooling internal to the code are also printed.  These require significant familiarity with the 
code.  This switch affects only the ascii log file, xout\_step.log.  The standard fits output files 
are unaffected by the value of lprint.

\subsection{Courant Multiplier (emult)}

This is a constant factor used in calculating the spatial step size.  For each 
radial zone, the size of the next zone is chosen to be 

$$\Delta R = min( {\rm emult}/\kappa_max(\varepsilon), R/{\rm nsteps})$$

where emult is defined below, and $\kappa_max(\varepsilon)$ is the maximum opacity from the 
previous step calculation.  $\kappa_max(\varepsilon)$  is only calculated from energies where
the optical depth to the illuminated face of the cloud is less than taumax, where 
taumax is defined below.  The default value for nsteps is 2.
The default value of emult is 0.5, and values outside the range 0.1 -- 1 are 
unlikely to be of any practical value.

\subsection{Max Tau for Courant Step (taumax)}

This quantity is used in calculating the spatial step size, as described in the 
previous subsection.  Energy bins with continuum optical depth to the 
illuminated cloud face greater than taumax are not used when searching for the 
maximum photoelectric opacity.  Default value is 5.

\subsection{Min Electron Abundance (xeemin)}

This is the minimum allowed electron fractional abundance.  If the electron fraction 
falls below this value the current pass is ended.  The default value is 0.01.

\subsection{Ion Abundance Criterion for Multilevel Calculation (critf)}

Ions whose abundance relative to total hydrogen (H I + H II) are less than this 
value after the preliminary ion abundance calculation 
(See Chapter~\ref{sec:internals}) are not included in
full multilevel calculation.  The default value is $10^{-8}$.  This parameter should be changed 
with caution owing to the fact that it determines the size of the matrix that 
xstar tries to solve in calculating the level populations.  

In versions of xstar 2.1lxx and earlier this matrix had 
a maximum size of 2400, and an attempt to solve for more than this number of levels 
simultaneously would result in xstar stopping with a message `ipmat too large'.

In version 2.2 this limitation has been removed, and arbitrarily small values of critf 
can be accomodated.  Also, a faster algorithm has been adopted for the multi-level calculation,
so the speed advantages of large critf have been reduced.
Also, the input parameter critf now 
refers to the fractional ion abundance (i.e. relative to the parent element) 
rather than the absolute (i.e. relative to H) ion abundance.
\subsection{Turbulent Velocity (vturbi)}

This parameter allows extra line broadening to be introduced into the 
calculation of the synthetic spectrum.  The value is in km s$^{-1}$, 
and the line shapes are assumed to be Gaussian.  If a small value is input,
then the broadening is assumed to be the greater of vturbi and the 
local thermal velocity of the absorbing ion.

\subsection{Number of Passes (npass)}

This parameter determines how many 
complete calculations of the temperature and ionization 
structure of the model shell are made.
Multiple passes are needed because there is no a priori knowledge of the 
optical depth of the shell in all the lines and continua, and these 
can affect the state of the gas in the interior of the shell.
During the first pass the calculation proceeds  through the shell, and assumes that all
optical depths from points within the shell to the far edge of the shell
are 0.  If an integer greater than 1 is supplied as a parameter,
XSTAR performs that number of iterations through the entire calculation,
setting the optical depths to the far edge at the values calculated in
the previous iteration.  The odd numbered passes 
are made from the smallest to largest radius, while the 
even numbered passes are made in the inward direction.  
The emergent spectrum is not calculated accurately during the inward 
passes, so npass must be odd.
Multi-pass calculations substantially
improve the accuracy of the predictions made for shells with finite
thickness, but they are much more time consuming than
single-pass calculations. They also make use of temporary unformatted datasets, 
named 'xout\_tmp.lis', 'xout\_tmp2.lis', which can become 
quite large.  The default value for this parameter is 1.  

\subsection{Number of Iterations (niter)}  

Set maximum number of iterations for thermal equilibrium and 
charge neutrality calculation at 
each spatial step.    If this quantity is set to zero 
then a constant temperature run will result, and charge neutrality will 
not be calculated.  If this quantity is negative, then charge neutrality will be calculated, but 
thermal equilibrium will not.  Default value is 0.  Normal thermal equilbrium models 
can be calculated with niter=99, although the code seldom requires more than a few iterations 
(10 or 20 at most) to achieve thermal equilibrium under normal conditions.

\subsection{Radius Exponent (radexp)}  

New in version 2.2 is the ability to have the gas density variable as a power law in 
radius, i.e. $n=n_0(R/R_0)^{\rm radexp}$, where $n_0$ and $R_0$ are the density  and 
radius at the cloud illuminated face.  {\bf NB  Note that this creates the possibility 
for calculations which do not end.  This because the citeria for a model to end are either 
that the input column density is reached, or that the electron fraction falls below xeemin.
If radexp has a value $\leq$-1 then the column density integral converges only logarithmically 
at best, and the specified column may never be reached.  If radexp $\leq$-2 the local ionization 
parameter will increase with radius, and so the gas will not recombine and the xeemin 
criterion will not be met.}

\subsection{Number of Continuum bins (ncn2)}  

New in version 2.2 is the option to control the number of continuum bins.  Continuum 
bins are logarithmically spaced between 0.1 eV and 40 keV, and are calculated according to:

$$\Delta\varepsilon/\varepsilon=(40 {\rm keV}/0.1 {\rm eV})^{1/(0.49 {\rm ncn2})}$$

ncn2 must be in the range between 999 and 99999.  The higher value is appropriate for use 
in modeling X-ray grating spectra.  The lower value is appropriate for models where 
only integrated line luminosities or ionization fractions are desired.  Execution time 
scales approximately proportionately to ncn2.

\subsection{Loop Control (loopcontrol)}
Used by XSTAR2XSPEC to track each model generated.  This value should 
never be manipulated by the end user.

\subsection{mode}
Used by the XPI interface.  This value should 
never be manipulated by the end user