Atomic-data setup

Native XSTAR execution requires atdb.fits and coheat.dat. Normal scientific execution never downloads these files implicitly.

Recommended explicit setup

For one native model:

xstar-cpp \
  --input xstar.par \
  --data-dir /path/to/xstar/data \
  --output run1

For XSTAR2XSPEC:

xstar-xspec \
  --input xstinitable.par \
  --data-dir /path/to/xstar/data \
  --output-dir run_table \
  --processes 2

--data-dir DIR means that native execution should use:

DIR/atdb.fits
DIR/coheat.dat

For xstar-cpp the two files can also be selected independently:

xstar-cpp \
  --input xstar.par \
  --atomic-db /path/to/atdb.fits \
  --coheat /path/to/coheat.dat \
  --output run1

Native discovery when explicit paths are omitted

The runtime tries candidates in order and selects the first existing regular file.

atdb.fits

1. parameter-envelope atomic_database, atomic_db, or atdb;

2. atdb.fits beside the parameter envelope;

3. $XSTAR_ATOMIC_DB;

4. $XSTAR_ATDB_FITS;

5. $XSTAR_DATA/atdb.fits;

6. $HEADAS/refdata/atdb.fits;

7. $XSTAR_HOME/data/atdb.fits;

8. executable-relative ../data/atdb.fits;

9. executable-relative ../../data/atdb.fits;

10. src/xstar_tools/xstar/data/atdb.fits;

11. ./atdb.fits.

The first item includes explicit paths generated by public xstar-cpp --atomic-db and --data-dir handling.

coheat.dat

1. parameter-envelope coheat_file or coheat;

2. coheat.dat beside the parameter envelope;

3. $XSTAR_COHEAT;

4. $XSTAR_DATA/coheat.dat;

5. $HEADAS/refdata/coheat.dat;

6. $XSTAR_HOME/data/coheat.dat;

7. executable-relative ../data/coheat.dat;

8. executable-relative ../../data/coheat.dat;

9. src/xstar_tools/xstar/data/coheat.dat;

10. ./coheat.dat.

The first item includes explicit paths generated by public xstar-cpp --coheat and --data-dir handling.

HEASoft HEADAS/refdata

The accepted native runtime supports a HEASoft installation as a fallback. For example:

heainit
unset XSTAR_DATA
unset XSTAR_ATOMIC_DB
unset XSTAR_ATDB_FITS
unset XSTAR_COHEAT
unset XSTAR_HOME

xstar-cpp --input xstar.par --output run_headas

If the files exist, the runtime can select:

$HEADAS/refdata/atdb.fits
$HEADAS/refdata/coheat.dat

The selected paths are reported through native diagnostics/provenance and are canonicalized when possible.

XSTAR2XSPEC ownership

xstar-xspec-initable does not independently search XSTAR_DATA, HEADAS, or XSTAR_HOME. If xstar-xspec --data-dir DIR is supplied, the planner emits that explicit data directory into every xstar-cpp job. If --data-dir is omitted, every child xstar-cpp owns its normal runtime data discovery.

For true MPI execution across multiple nodes, prefer an explicit shared path:

mpirun -np 4 xstar-xspec-mpi \
  --input xstinitable.par \
  --data-dir /shared/xstar/data \
  --output-dir /shared/run_mpi

This avoids depending on how a particular MPI launcher exports shell environment variables to remote nodes.

Python data helper

Python-side validation remains available:

from xstar_tools.data import XStarData

data = XStarData.from_directory("/path/to/xstar/data")
print(data.validate().as_dict())
print(data.identity())

Installed wheels do not bundle the large atomic database. Configured paths and explicit downloads remain outside site-packages.