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

Confirm the installed interfaces

These three help pages confirm that model generation and the packaged survey adapter are on 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. The model-generation guide develops these inputs in more detail.

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. The model-generation guide explains the available abundance descriptions and shows how to solve a converged atmosphere before passing 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 tosynthesize 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:

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

Related sourceTutorial notebook