xstar-tools

xstar-tools is a source-faithful Python/C++ productization of XSTAR photoionization calculations. The scientific oracle remains FORTRAN XSTAR 2.59g. Packaging, portability, orchestration, interface, and performance work are qualified without silently changing that scientific boundary.

Status

The platform-specific native-wheel paths are formally qualified, and 0.6.89.5 — PYPI_CROSS_PLATFORM_RELEASE_CLOSURE is the unified release candidate that rebuilds all of them under one package version:

Platform	Release wheels	Accepted platform baseline
Linux x86_64	CPython 3.9–3.14, manylinux_2_28_x86_64	0.6.89.2.2
macOS arm64	CPython 3.9–3.14, macosx_11_0_arm64	0.6.89.3
macOS x86_64	CPython 3.9–3.14, macosx_11_0_x86_64	0.6.89.3
Windows AMD64	CPython 3.9–3.14, win_amd64	0.6.89.4.5

The 0.6.89.5 release workflow builds 24 native wheels plus one source distribution: 25 release files. All distributions use the same version so a published release can be installed normally with:

python -m pip install xstar-tools

The release workflow runs on GitHub-hosted Linux, native Apple-Silicon macOS, native Intel macOS, and Windows AMD64 runners. A developer therefore does not need local access to macOS or Windows to build those release wheels. The workflow qualifies each native wheel on its matching host and then aggregates the exact 25-file publication set. It deliberately does not auto-publish to PyPI.

The accepted cross-platform source-build contract is non-MPI on Windows and supports xstar-cpp plus local-process xstar-xspec --processes N. True MPI remains an explicit Linux/macOS/HPC build.

Quick start

A normal native source build does not require MPI:

make -C src/xstar_tools/xstar/cpp -j4

Run one XSTAR calculation:

src/xstar_tools/xstar/cpp/xstar-cpp \
  --input xstar.par \
  --data-dir /path/to/xstar/data \
  --output-dir run_xstar

Run a local two-process XSTAR2XSPEC grid:

src/xstar_tools/xstar/cpp/xstar-xspec \
  --input xstinitable.par \
  --data-dir /path/to/xstar/data \
  --output-dir run_xspec \
  --processes 2

--processes 2 means two independent xstar-cpp operating-system processes. It does not mean two threads or two MPI ranks.

Python / wheel builds

Python requires 3.9 or newer.

Build a Python-only wheel explicitly:

XSTAR_TOOLS_NATIVE=off python -m pip wheel . --no-deps

Build a native wheel when platform prerequisites are available:

XSTAR_TOOLS_NATIVE=required python -m pip wheel . --no-deps

The release-wheel profiles are deliberately narrower than a full source build:

• Linux uses pypi-linux;
• macOS uses pypi-macos;
• Windows uses pypi-windows;
• all ordinary release wheels exclude xstar-xspec-mpi;
• all release profiles exclude the standalone Python-embedding native plugin;
• atdb.fits is never bundled into ordinary wheels;
• CFITSIO is vendored into repaired release wheels.

The detailed qualification history is in docs/developer/packaging.md and the platform-specific milestone documents under docs/developer/.

To build the complete PyPI release candidate, run the GitHub Actions workflow:

.github/workflows/pypi-cross-platform-release.yml

Its final xstar-tools-0.6.89.5-pypi-release artifact contains only the 24 native wheels, the sdist, and a checksum manifest. A Python-only py3-none-any control wheel is explicitly excluded from the publication set.

After the aggregate gate accepts, download that artifact and publish the same 25 distributions first to TestPyPI and then to PyPI:

python -m pip install --upgrade twine
python -m twine check release-dist/*
python -m twine upload --repository testpypi release-dist/*
# after installation testing from TestPyPI:
python -m twine upload release-dist/*

Do not upload the local py3-none-any control wheel; it is only a packaging qualification artifact.

Native build by platform

Linux

Typical prerequisites are a C++17 compiler, GNU Make, Python development support, pkg-config, and CFITSIO development files.

make -C src/xstar_tools/xstar/cpp -j4 PLATFORM=linux

macOS

Install the native dependencies:

brew install cfitsio pkg-config

Build with Apple Clang:

make -C src/xstar_tools/xstar/cpp -j4 PLATFORM=macos

The qualified Darwin build uses .dylib libraries, @rpath install names, and @loader_path sibling-library lookup.

Windows

Use an MSYS2 UCRT64 terminal, not the plain MSYS shell. A normal source build can use the packaged MSYS2 CFITSIO development package:

pacman -S --needed \
  make \
  mingw-w64-ucrt-x86_64-gcc \
  mingw-w64-ucrt-x86_64-binutils \
  mingw-w64-ucrt-x86_64-cfitsio \
  mingw-w64-ucrt-x86_64-pkgconf \
  mingw-w64-ucrt-x86_64-python \
  mingw-w64-ucrt-x86_64-python-pytest

Then build:

make -C src/xstar_tools/xstar/cpp -j4 PLATFORM=windows

Windows produces .dll, .dll.a, and .exe artifacts. The accepted source-runtime backend uses native Win32 process creation. See docs/user/windows_installation_and_usage.md for the complete setup and troubleshooting guide.

Inspect the resolved build contract

make -C src/xstar_tools/xstar/cpp print-config

Native executables

The main native programs are:

xstar-cpp             one XSTAR model
xstar-xspec-initable  XSTAR2XSPEC grid planner
xstar-xspec-table     final XSPEC table assembler
xstar-xspec           serial/local-process XSTAR2XSPEC
xstar-xspec-mpi       true MPI XSTAR2XSPEC; opt-in build only

The compatibility executable xstar_cpp is also retained.

When installed through the Python package, the primary native console entry points are:

xstar-cpp
xstar-xspec-initable
xstar-xspec-table
xstar-xspec

Useful package inspection commands include:

xstar-tools version
xstar-tools backends
xstar-tools doctor

Atomic data

Native scientific execution requires atdb.fits and coheat.dat. These files are not silently downloaded, and atdb.fits remains external to ordinary wheels.

The clearest reproducible setup is:

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

or select the two files independently:

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

When explicit paths are omitted, discovery includes parameter/envelope paths, XSTAR_ATOMIC_DB / XSTAR_ATDB_FITS, XSTAR_COHEAT, XSTAR_DATA, $HEADAS/refdata, XSTAR_HOME/data, executable/package-relative fallbacks, and finally the current directory. See docs/user/atomic_data.md for the exact precedence.

xstar-cpp

With xstar.par

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

The positional input form is also accepted:

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

Values supplied after the file override values from the file:

xstar-cpp \
  --input xstar.par \
  --output-dir run_override \
  density=1.0e+12 rlogxi=3 modelname=override_model

Without xstar.par

Direct XSTAR-style key=value parameters are supported:

xstar-cpp \
  --data-dir /path/to/xstar/data \
  --output-dir run_direct \
  spectrum=pow spectun=0 trad=-1 \
  temperature=100 pressure=0.03 density=1e12 \
  column=1e20 rlrad38=1e6 rlogxi=1 cfrac=0.4 \
  habund=1 heabund=1 cabund=1 \
  modelname=direct_example abundtbl=xdef \
  nsteps=10 niter=99 lwrite=1 lprint=1 lstep=0 \
  emult=0.5 taumax=5 xeemin=0.1 critf=1e-6 \
  vturbi=100 npass=1 ncn2=9999

For the complete parameter and output contract, see src/xstar_tools/xstar/cpp/README.md and docs/cpp/xstar_cpp.md.

xstar-xspec

xstar-xspec owns the complete local XSTAR2XSPEC pipeline:

xstar-xspec-initable
        -> independent xstar-cpp jobs
        -> loopcontrol-ordered gather
        -> xstar-xspec-table

Parameter-file grid:

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

A direct 2 x 2 grid can be launched without xstinitable.par:

xstar-xspec \
  --data-dir /path/to/xstar/data \
  --output-dir run_grid \
  --processes 2 \
  column=1e21 columntyp=2 columnsof=1e20 columnnst=2 columnint=1 \
  rlogxi=2 rlogxityp=2 rlogxisof=1 rlogxinst=2 rlogxiint=0

The canonical spelling is --processes N; --workers N and -j N remain compatibility aliases. -np is reserved for MPI launchers.

Restart a local grid with:

xstar-xspec \
  --input xstinitable.par \
  --output-dir run_xspec \
  --processes 2 \
  --restart

A job is reusable only when its required scientific products and xstar-cpp.success marker are present. Partial or failed products are retained for inspection rather than deleted merely because unrelated files coexist in the job directory.

True MPI XSTAR2XSPEC

xstar-xspec-mpi is optional and is not part of normal make or ordinary PyPI wheels:

make -C src/xstar_tools/xstar/cpp mpi

or:

make -C src/xstar_tools/xstar/cpp xstar-xspec-mpi

Typical Linux/HPC execution is:

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

MPI concurrency comes from the communicator size. There is no local --processes option in xstar-xspec-mpi. The current file-backed MPI path requires shared visibility of executables, work/output directories, atomic data, and external model files. Windows MPI is deferred.

Outputs

A successful xstar-cpp run can publish products such as:

xout_abund1.fits
xout_cont1.fits
xout_lines1.fits
xout_rrc1.fits
xout_spect1.fits
xout_step.log
xstar_execution_provenance.json

A successful XSTAR2XSPEC run additionally publishes:

xout_ain.fits
xout_aout.fits
xout_mtable.fits
xout_etable.fits

The local-process scheduler keeps its work tree under xstar2xspec-work/jobs/NNNNNN/.

Scientific and ABI freeze

Important accepted identities are:

canonical oracle         FORTRAN XSTAR 2.59g
accepted science freeze  0.6.48.12.3.45.3.3.8
public C API ABI          60487
production-zone ABI      6048110
fixed-state program ABI  60486
XSPEC table ABI           1

Cross-platform qualification preserves scientific arithmetic/order, controller decisions, traversal/contribution order, cutoffs, publication semantics, output schema, and public ABIs unless a later explicitly qualified scientific change says otherwise.

Documentation

Start with:

• docs/user/index.md — installation and normal use;
• docs/user/atomic_data.md — atomic-data discovery and precedence;
• docs/user/windows_installation_and_usage.md — Windows/MSYS2 UCRT64 source-build guide;
• src/xstar_tools/xstar/cpp/README.md — native C++ programs and detailed examples;
• docs/cpp/index.md — native C++/CLI reference;
• docs/developer/packaging.md — packaging architecture and release-wheel policy;
• docs/developer/cross_platform_portability_status.md — accepted source-build portability status;
• CHANGELOG.md — chronological release history.

Historical qualification failures and their closure evidence intentionally live in docs/developer/ rather than this top-level README.

Development rule of thumb

Use the narrowest qualification gate that covers the changed boundary. Packaging/documentation changes should not reopen science or performance work. Scientific or orchestration changes should begin with representative fast fixtures and preserve the frozen oracle/ABI contracts before any expensive broad qualification.

License

Starting with 0.6.89.3, xstar-tools uses the project license designation GPL-3.0. The authoritative license text is the top-level LICENSE file (GNU General Public License, Version 3, 29 June 2007). Historical release notes that mention the former MIT declaration remain historical records.