Theory Of Operations

XSTAR

Introduction

Although XSTAR is designed with the goal of maximizing the flexibility of parameter values and assumptions available to the user, there are likely to arise situations in which the standard set of input options are not sufficient. Under these circumstances the user may want to attempt to modify the source code in order to effect a particular set of assumptions, geometry, etc. Problems for which customization is more likely to be necessary include models with additional heating or cooling processes (for example adiabatic expansion cooling or cosmic ray heating) or different assumptions about line escape probability (e.g. Sobolev escape probability in a medium with a velocity gradient). If so, the internal operation of the code must be confronted. This appendix presents a summary of the code operation in order to aid in code customization.

Programming Philosophy

XSTAR has been written and developed over many years, and much has changed during that time. Changes include advances in the fortran language, changes in the speed and memory capacity of the available computers, new insights into the flexibility required of XSTAR, and insight into which physical processes are likely to have the greatest effect on the model results.

XSTAR was written in standard fortran 77, and much of the code retains the programming style associated with the older versions of the fortran language. Hard experience with moving the code from one type of machine to another has led to an attempt to avoid any machine dependent extensions to the fortran language, any word length dependent numerical constructs or any use of extended precision arithmetic (with one or two exceptions).

The code is structured in an attempt to be modular, and to separate the calculation of the atomic rates from the calculation of level populations, ion fractions, temperature, etc. The goal is to make it relatively easy to add or change atomic data, requiring modification of just one subroutine if a new process is added or a fitting formula is changed. The data itself is all read in from an external file, so that it can be changed without any modification to the code itself if the existing fitting formulas are unchanged.

XSTAR Flow Charts

In this section we present an overview of the code structure in the form of flowcharts. Detailed descriptions of xstar routines and data structures will be found in the accompanying document containing the doxygen documentation. We also provide flowcharts and descriptions for xstar2xspec and associated tools.

XSTAR2XSPEC

XSTAR2XSPEC consists of three major components (in addition to XSTAR itself).

xstar2xspec: xstar2xspec is a Perl script which manages the overall program flow of XSTAR2XSPEC.
xstinitable: xstinitable is an FTOOL used in the initialization phase of XSTAR2XSPEC. It builds the FITS PARAMETER table from the input data (xstinitable.fits) and a text file (xstinitable.lis) which is basically of list of all the calls to XSTAR to generate the required spectra.
xstar2table: xstar2table is an FTOOL called after xstar in each iteration of the xstar2xspec loop.

xstar2xspec (script)

This is a Perl script.

One current limitation is that the file tagging in the -save option file names are limited to 9999 calls of XSTAR.

xstinitable

This FTOOL is written in C. It generates an initial FITS file (xstinitable.fits) with the appropriate PRIMARY and PARAMETERS extension from the atables and mtable file are build. It also generates a text file (xstinitable.lis) which contains a complete XSTAR calling command on each line. This file is processed by the XSTAR2XSPEC Perl script

Examples of changes in XSTAR that would require changes in this FTOOL (just meant as a sample, not necessarily an exhaustive list).

Changing the number of physical parameters in XSTAR.
Changing or altering the control parameters in XSTAR.

xstar2table

This FTOOL is also written in C. Full use is made of dynamic memory allocation. If the number of spectral channels is changed in XSTAR, this program should adapt appropriately, automatically.

Examples of changes in XSTAR that would require changes in this FTOOL (just meant as a sample, not necessarily an exhaustive list).

Changing the number of physical parameters in XSTAR.
At present, this program is written assuming that the XSTAR runs are performed sequentially and in a particular order. In fact, it checks the sequence by comparing the LASTSPEC keyword to the LOOPCONTROL variable. If, at some time in the future, the XPI interface is modified in such a way that it becomes possible to simultaneously submit multiple XSTAR runs on multiple processors, xstar2table must be modified to ignore this comparison.