Installation and first check

Requirements

Payne Zero requires Python 3.11 or newer, Git, and Git Large File Storage. Its core Python dependencies include NumPy, Numba, and PyTorch. A CUDA GPU is recommended for the fastest synthesis; Apple Metal and CPU execution are also supported.

Install from the repository

Clone the repository and run the installer from its root:

git clone https://github.com/tingyuansen/payne-zero.git
cd payne-zero
./install.sh

Related sourceInstaller · Runtime-data manifest

Check the installation before running a model

Ask each installed command for its help page before starting a longer calculation. If all three return their options, the atmosphere solver, synthesis engine, and packaged APOGEE adapter are available in the active Python environment:

payne-zero-synthesis --help
payne-zero-atmosphere --help
payne-zero-fit-apogee --help

Related sourceInstalled command definitions

Generate a first spectrum

This command constructs the atmospheric state for solar labels and calculates total, continuum, and normalized flux from 500 to 510 nm:

Effective temperature and surface gravity set the star's energy scale and gravitational pressure. Metallicity and alpha enhancement describe the bulk chemical mixture. Microturbulence represents unresolved small-scale velocities that broaden spectral lines. These inputs describe the stellar state used by both atmosphere calculation and spectrum synthesis.

payne-zero-synthesis \
  --effective-temperature 5777 \
  --log-surface-gravity 4.44 \
  --metallicity 0.0 \
  --alpha-enhancement 0.0 \
  --microturbulence-km-s 1.0 \
  --wl-start-nm 500 \
  --wl-end-nm 510 \
  --r-grid 300000 \
  --device auto \
  --dtype auto \
  --out runs/sun_spectrum.npz

A bundled model predicts the starting depth structure for this first calculation; the atmosphere equations are not iterated to convergence. This is the short synthesis-only path. When the atmospheric structure is itself part of the result, solve it to convergence first and pass its structured archive to the same synthesis command.

Related sourceSynthesis command

Choose the synthesis device once

Atmosphere iteration uses compiled multicore CPU kernels; it does not need a GPU device setting. Spectrum synthesis can run on NVIDIA CUDA, Apple Metal through PyTorch MPS, or CPU. Start by checking which accelerator PyTorch can see:

python - <<'PY'
import torch

print("CUDA:", torch.cuda.is_available())
print("Apple Metal (MPS):", torch.backends.mps.is_available())
PY

For the command line, auto chooses CUDA first, then MPS, then CPU. Explicit device choices are useful in a reproducible script or when comparing numerical precision:

# Add one pair to a payne-zero-synthesis command:
--device auto  --dtype auto
--device cuda  --dtype float32
--device mps   --dtype float32
--device cpu   --dtype float64

MPS requires float32. With dtype=auto, Payne Zero uses float32 on MPS and float64 on CUDA or CPU. CUDA can also use float32 when throughput is more important than matching the double-precision default. The equivalent Python selection is:

import torch

if torch.cuda.is_available():
    device, dtype = "cuda", "float32"
elif torch.backends.mps.is_available():
    device, dtype = "mps", "float32"
else:
    device, dtype = "cpu", "float64"

print(f"Payne Zero synthesis: {device=}, {dtype=}")

Pass those device and dtype values to synthesize or synthesize_from_labels. Keep them unchanged across a model sequence so prepared windows and device-resident data can be reused.

Caches and data locations

• Prepared synthesis windows are reused when wavelength range, sampling, device, data type, and catalog selection are unchanged.
• Persistent atmosphere and synthesis caches use .cache/payne-zero/; molecular source parsing uses ~/.cache/payne-zero-synthesis/ unless redirected.
• PAYNE_ZERO_DATA_ROOT moves the complete runtime data tree; PAYNE_ZERO_SOURCE_CATALOG_ROOT overrides only the shared raw catalogs.
• PAYNE_ZERO_NUMBA_CACHE_DIR and PAYNE_ZERO_SYNTHESIS_CACHE_DIR relocate the two persistent caches when the defaults are not suitable.

Related sourceAtmosphere execution guide · Synthesis cache controls

Open the tutorial notebook

Install the plotting and Jupyter dependencies, then open the repository notebook. It follows both atmosphere treatments and inspects their saved products:

python -m pip install -e ".[tutorial]"
jupyter lab payne_zero_tutorial.ipynb

Related sourceTutorial notebook