Scientific engines and configuration contracts

Table 23 and Table 24 cover RVSpecFit settings and warnings; Table 25 covers FERRE. Table 26, Table 27 and Table 28 summarise IFU controls, shared settings and failure handling.

This page describes what each major scientific engine receives, computes, and returns. The interface description allows a reader to identify the input product and target class, then follow the corresponding engine path. PyAPS controls preparation, resolution delivery, wrappers, resource allocation, runtime monitoring, warnings, output validation and FITS integration around each cited scientific algorithm.

RVSPECFIT: radial velocity and stellar parameters

The PyAPS RVS path uses RVSPECFIT¹ (Koposov et al., 2011; Koposov, 2019) for STAR and WD targets after classification. Its entry point constructs an APSOB for the selected fibres or IFU bins and then dispatches target subsets to proc_weave. For each target, the worker performs the following operations:

1. obtains the processed spectrum, inverse variance and target-specific wavelength grid from APSOB;

2. evaluates the calibrated FWHM curve at the observed pixels, or falls back to the fixed APSOB resolution if interpolation is unavailable;

3. builds a sparse resolution matrix, subtracting the intrinsic template width in quadrature when deconvolution is enabled;

4. obtains an initial radial velocity from cross-correlation;

5. runs the full RVSPECFIT template fit for velocity,
   $T_{\mathrm{eff}}$

   ,
   $\log g$

   , [Fe/H], [
   $\alpha$

   /Fe] and projected rotation where configured;

6. evaluates fit, velocity, uncertainty, grid-edge and Hessian conditions; and

7. writes parameter, warning and optional model-spectrum tables.

The RVSpecFit (RVS) warning bitmask distinguishes a fit that does not improve on a continuum, a velocity at the search boundary, large velocity uncertainty, parameters at grid limits, high rotation, bad spectrum and failed Hessian. These flags are not equivalent to a failed process: a product can be written with a non-zero warning and must be interpreted through the bitmask.

For MOS, RVS works on fibre spectra. In the PyAPS IFU-Gal implementation, it works on linearly sampled spatial bins, receives the evaluated per-bin FWHM array and is allowed to fail for one bin without aborting the other bins. A missing RVS output does not necessarily prevent FERRE. The wrapper next uses the retained Redrock velocity and falls back to zero only when neither result supplies a velocity, including a target routed through TARGCLASS despite a classification mismatch. The velocity source and any zero substitution are retained in run provenance.

The module guide gives the following documented RVS configuration envelope: the velocity search is
$[-1000,1000]$

km s
${}^{-1}$

, the parameter bounds are
$2300\le T_{\mathrm{eff}}\le 15000$

K,
$-0.5\le \log g\le 6.5$

,
$-4\le [\mathrm{F}\mathrm{e}\mathrm{/}\mathrm{H}]\le 1$

, and
$0\le v\sin i\le 500$

km s
${}^{-1}$

, with a default CCF initialisation and continuum polynomial order 19. These values are configuration-guide defaults. The selected YAML and checksum identify the limits applied to each result.

The RVS adapter uses the intrinsic Gaussian width of each template library when constructing the additional resolution kernel. The current lookup table sets the template FWHM to 0.2 and 1.0 Å for MOS/mIFU HR and LR, respectively, and to 0.3 and 1.5 Å for LIFU HR and LR. The corresponding Gaussian widths are
${\sigma }_0=\mathrm{F}\mathrm{W}\mathrm{H}\mathrm{M}/2.355$

. The code returns a warning-backed fallback for an unknown mode/resolution combination; the warning distinguishes this substitution from a calibrated template.

The RVS output also carries a diagnostic bitmask alongside the fit result. The documented bits identify a fit that does not improve sufficiently on a continuum (
$\mathrm{\Delta }{\chi }^2<50$

), a velocity within 5 km s
${}^{-1}$

of a search boundary, velocity uncertainty above 100 km s
${}^{-1}$

, a parameter at a grid edge,
$v\sin i>20$

km s
${}^{-1}$

, a reserved bad-spectrum state, and a failed Hessian evaluation. A non-zero mask does not mean that no FITS row is written; the row remains usable only with the associated warning interpretation.

FERRE: grid-based stellar parameters

FERRE² (Allende Prieto et al., 2006; Allende Prieto & the APOGEE Team, 2015; Allende Prieto, 2017) is a compiled Fortran engine called by PyAPS through namelists, input arrays and subprocesses. PyAPS does not fit one target by one Python call. It batches targets, writes flux/error/wavelength/velocity inputs, launches one run per configured stellar grid, captures standard output and error, waits for the expected output files, and merges the successful grids.

The MOS path first selects stellar targets, reads RVS velocities when present, de-redshifts the spectra, marks invalid pixels with large errors, and prepares one or more grids. FERRE applies its configured running-mean normalisation during fitting; RVSpecFit instead normalises the model to the data. The IFU-Gal path applies the same preparation logic to linearly sampled spatial bins and splits overlapping arms at the overlap centre so the same wavelength pixels are not fitted twice. For two-arm LR products the blue and red arrays and their matching grids are concatenated in the same order; setup-specific single-arm runs use one grid.

PyAPS selects the correct FERRE grid family for mode, arm and resolution and passes the wavelength- and fibre-dependent LSF information used by FERRE for convolution during the fit. Grid families can represent normal stars, giants, dwarfs and white dwarfs, and may be ordinary or PCA-compressed.

FERRE uses a multi-grid strategy with separate normal-star and white-dwarf domains. Official MOS processing uses the five-dimensional m normal-star grids, fitting
$T_{\mathrm{eff}}$

,
$\log g$

,
$[\mathrm{M}/\mathrm{H}]$

,
$[\alpha /\mathrm{M}]$

and microturbulence. The lower-dimensional n family retains the three principal atmospheric parameters as an alternative. White-dwarf grids have their own temperature-gravity domains. PCA-compressed variants retain the parameter domain while reducing template storage. The accompanying paper gives the archived header ranges and sampling; the NGC 6819 comparison identifies the template revision used for that measurement in the accompanying paper.

The merge rejects a degenerate result when too few grids produce valid output, and it can choose the next-best grid when the nominal best temperature lies outside that grid’s valid range. FERRE warnings distinguish tolerated IEEE floating-point messages after valid output was written from true subprocess or missing-output failures. The final FITS product records atmospheric parameters, errors, selected grid identity, input velocity and optional model spectra.

At the file boundary, PyAPS stages one flux, error, wavelength and velocity input set per run (the documented `.frd`, `.err`, `.wav`, `.vrd` and `.lsf` files), creates one Fortran namelist per grid, and launches the external executable as a subprocess. FERRE writes `.opf`, `.mdl` and `.nrd` products; `opfmerge` waits for the expected files, rejects incomplete grid results, selects the valid lowest-
${\chi }^2$

grid per target and exposes the selected grid identity to the FITS merger. MOS targets can be batched across a grid, whereas IFU-Gal bins are processed as independent spatial units. In two-arm LR data, the overlap is split at its configured centre before the arm arrays and matching grids are concatenated, preventing duplicated wavelength pixels. These file and polling states form part of the wrapper contract and are retained in run provenance.

FERRE references

• Allende Prieto, C., Beers, T. C., Wilhelm, R., Newberg, H. J., Rockosi, C. M., Yanny, B. & Lee, Y. S. (2006), “A Spectroscopic Study of the Ancient Milky Way: F- and G-Type Stars in the Third Data Release of the Sloan Digital Sky Survey”, The Astrophysical Journal, 636, 804-820. doi:10.1086/498131; arXiv:astro-ph/0509812. This is the refereed method reference. It does not document the template grids used for WEAVE.
• Allende Prieto, C. & the APOGEE Team (2015), FERRE software. github.com/callendeprieto/ferre
• Allende Prieto, C. (2017), FERRE guide, version of 31 May 2017. cdsarc.cds.unistra.fr, ferre.pdf

pPXF: stellar kinematics for extragalactic targets

pPXF³ (Cappellari & Emsellem, 2004; Cappellari, 2017) is used for the GALAXY/QSO extragalactic branch after IFU preparation or MOS extragalactic preparation. The input is a spectrum and error array in log-wavelength sampling, a constant velocity scale, a good-pixel mask, a redshift-dependent wavelength window, and a template library prepared for the data’s LSF. The fit returns velocity, velocity dispersion and configured higher-order moments (the source writes
$h_3$

-
$h_6$

columns when requested), the best-fit model, an optimal template combination, formal errors and Monte Carlo errors.

The ExGal JSON controls the template and kinematic contract. Important fields include SSP_LIB, PCA, NORM_TEMP, VELSCALE, MOM, ADEG, MDEG, MC_PPXF, LMIN_PPXF, LMAX_PPXF, SPAXEL_WEIGHTED_LSF and LSF_N_BUCKETS. In the LIFU/mIFU production configurations, the template library is selected by SSP_LIB (for example, popstar_total) and PCA is enabled. This is treated as a configuration-controlled PCA/template-representation path; the selected stellar-population library and revision are retained with the result.

Before fitting, PyAPS converts the calibrated FWHM to the target rest frame, loads the template-library LSF curve, computes a velocity-scale ratio, prepares or reuses the LSF-matched template library, masks gaps and bad pixels, and invokes pPXF. Spaxel/bin LSF buckets select the prepared template set for each bin; they do not create a new scientific fitting stage.

The IFU guides distinguish the ExGal and Gal preparation policies. ExGal’s adaptive minimum S/N threshold uses the second percentile of positive S/N values, clamped to 0.1 to 1.5 unless a fixed value is configured; Gal uses the third percentile with a 0.3 to 3.0 clamp, reflecting the different failure modes of extended emission-line sources and stellar continua. ExGal may apply a surface- brightness filter, whereas Gal disables that filter and retains valid stellar spaxels. ExGal spectra are log-rebinned for pPXF, whereas Gal spectra remain linearly sampled for RVS/FERRE.

EMI: PyAPS’s WEAVE emission-line implementation of pPXF

EMI is PyAPS’s implementation of pPXF (Cappellari, 2017) for WEAVE emission-line analysis; it is not a separate package or engine. It operates on the same ExGal bin spectra and pPXF-compatible wavelength window, but fits emission-line components using the configured line list and moments. The production configuration exposes EMI_FILE, LMIN_EMI, LMAX_EMI, EMI_MOM, USE_STELLAR_CONTINUUM, FIX_STELLAR_CONTINUUM, MC_EMI and EMIPPXF_LEVEL. The line-list YAML defines the transitions and fitting groups; the continuum choice controls whether the stellar model is included and fixed during the emission fit. pPXF remains the underlying method and external attribution. The EMI label distinguishes this wrapper from the historically absorption-line-oriented pPXF path and replaced the earlier GANDALF-based emission workflow (Sarzi, Falcón-Barroso, Davies et al., 2006), reducing duplicated engine integration. The output contains line fluxes, widths, equivalent widths, uncertainties and bin IDs.

The emission window is resolved independently of the pPXF window. Thus a high-redshift target can have too little rest-frame coverage for pPXF while still retaining a usable emission-line window. If the resolved window is too narrow, PyAPS sets the corresponding skip flag and still writes preparation products and any other valid module outputs.

LS: line-strength indices

The line-strength module measures configured absorption indices on the ExGal spectra after spatial binning and resolution preparation. Its main controls are LS_FILE, LS_MODE, LS_RES, LS_RESOLUTION_MODE, MC_LS and the selected SSP/template library. LS_RES=ADAPTED requests resolution-aware index handling; SKIP_NEGATIVE prevents invalid or negative-resolution cases from being turned into apparently precise indices. Monte Carlo settings propagate noise into index uncertainties. The output is keyed by bin and retains the index definitions and resolution policy needed for interpretation.

Mode-specific engine configuration

The precedence for many IFU values is command-line override, function argument, JSON value and finally a hard-coded default. This precedence is part of the reproducibility contract: a JSON file alone does not identify a run if command-line overrides were supplied.

Engine-level output and failure matrix

PyAPS records file creation, module completion, fit-quality acceptance and scientific validation as separate states.

---

1. https://github.com/segasai/rvspecfit↩︎

2. https://github.com/callendeprieto/ferre↩︎

3. https://pypi.org/project/ppxf/↩︎