Module input/output contracts

Table D1 of the paper maps module inputs and outputs; Table 10 describes the quality flags.

The module map follows each product through scientific preparation, fitting and output assembly. EMI denotes the PyAPS pPXF emission-line wrapper.

Table D1 of the paper provides this inventory.

Concrete wrapper lifecycle

Table 8 and Table 9 show how the main wrappers are organised. Their details differ: Redrock handles ranked template solutions, FERRE manages files and compiled processes, and the IFU branches work patch by patch. They nevertheless follow the same broad sequence of input checks, preparation, execution, error handling and product assembly. A contributed module follows this sequence when its results are to be included in the standard Level-2 workflow.

Failure and fallback propagation

PyAPS uses several fallbacks, each for a different problem. A missing LSF fibre can use the nearest or global calibration curve. A missing redshift can trigger IFU-Gal reclassification. A failed IFU aperture can be skipped without stopping other targets, and a failed FERRE grid does not prevent other grids from completing. The L2 product records the relevant warning, while the run log retains the original error or substitution.

At scheduler level, the current runner uses completion-based afterany dependencies because failed jobs must still reach the merger; success-based afterok would prevent that path. Consequently, a failed predecessor releases its dependent script, whose own input checks and exit state decide whether useful work remains possible. The generated script returns the wrapped command status. For IFU processing, per-target exceptions are isolated and an all-applicable-target failure exits the worker; RVS and FERRE outcomes in the Galactic branch are evaluated independently.

At product level, partial assembly is conditional. gen_hdu emits an empty extension and a condition used in APSQFLAG when none of a component group’s files exists. The MOS merger still requires classification and at least one populated scientific branch; IFU ExGal requires patch and binned-spectrum content; IFU Gal requires patch content. The operations layer identifies scheduler failures and exposes failed records for operator-controlled resubmission. Aggregate failure/completion is reported through the Operational Repository.

For example, if all MOS extragalactic table inputs are absent, gen_hdu creates an empty GALAXY_TABLE and the merger sets bit value 4 in APSQFLAG. A product can still be written when CLASS_TABLE and STAR_TABLE are populated. If the classification table is empty, or both science tables are empty, the merger returns failure without accepting the product. This describes the implemented missing-input path; an empty table alone does not distinguish an unselected branch from an execution failure, for which the job record is also needed.

Run metadata required for interpretation

The reproducible run record identifies:

1. the input MOS/fibre product, stack, superstack, IFU cube or edited patch, together with the available arms and resolution mode;

2. the APSOB masks, sensitivity-function calibration, inverse variance (IVAR) normalisation, wavelength frame and LSF settings;

3. the number of retained Redrock ranks, the class used for routing and any PCA/archetype or class-representation fallback;

4. for IFU data, the patch rows, mask regions, spaxel filters, spatial pre-binning, Voronoi/PowerBin settings and target S/N; and

5. the scientific-engine versions, template/grid revisions, resource settings, warnings and skipped stages.

L2 merge-quality flag mapping

The merger writes the primary-header keyword APSQFLAG as a sum of bit values returned when an expected component HDU is missing or empty. The following table records the PyAPS implementation mapping.

The current IFU-extragalactic merger writes PATCH_TABLE, PATCH_BINSPEC, GALAXY_TABLE and the configured galaxy spectrum products; the component-presence state is encoded in APSQFLAG.

Scientific methods and APS interfaces

Each scientific engine has a distinct role in the production workflow. PyAPS combines their established numerical estimators with its own WEAVE-specific preparation, data-quality logic, resolution handling, fallback strategies, resource control and L2 product construction. Each engine receives a defined APSOB representation and returns a product identified by target, rank, patch or bin.

A common interface, with engine-specific contracts

For every branch, the input boundary is an APSOB object containing one or more APSTARG target entries. Each target contains one or more APSSPEC spectra with wavelength, flux-calibrated spectrum, propagated IVAR and retained L1 sensitivity-function arrays, plus per-arm metadata for mode, setup, calibration, LSF and provenance. This means that a MOS fibre, a fibre-formatted IFU product and a selected IFU spaxel can enter the same preparation and quality-control code without asking the scientific engine to understand the original FITS layout. Geometry and provenance are retained: IFU patch, spaxel and bin identifiers remain attached to spectra and are used when assembling the IFU L2 product.

The common boundary ends where an engine’s native numerical contract begins. Redrock consumes arm-aware arrays and resolution matrices; RVSpecFit consumes contiguous spectra when gap filling is enabled and a per-target resolution matrix; FERRE consumes staged files and a namelist understood by its compiled executable; pPXF consumes logarithmically rebinned spectra and a template/data resolution relationship; EMI and LS consume rest-frame windows and their own line/index definitions. The adapters perform the scientific data preparation required to apply each estimator to WEAVE products.

Catalogues enrich the L2 decision and provenance model

The spectral arrays are not the only inputs to APS. L1 FIBTABLE metadata and catalogue files supplied through catdir or an explicit match-table contract provide target identifiers, coordinates, survey/program labels, predefined target classes, fibre status and, where available, priors or auxiliary selection fields. l1_fileinfo and APSOB carry these fields into each APSTARG; the classifier then uses TARGCLASS, TARGPROG and TARGSRVY in the documented priority order. The resulting L2 tables retain both catalogue-derived classification/routing fields and measured Redrock ranks, redshifts, warnings and downstream parameters.

This metadata-routing layer was executed on the 600-row FIBTABLE of the real blue LIFU-form input: 302 rows resolved to GALAXY and 298 to STAR under the PyAPS v2.0 survey configuration. Controlled conflicting inputs confirmed that TARGCLASS takes precedence over TARGPROG, followed by survey-code lookup and the supplied fallback. This test exercises deterministic metadata routing; spectral-classification accuracy is evaluated with labelled spectra.

This separation matters when a target is ambiguous. A predefined catalogue class can constrain selection or ensure that a relevant candidate appears in the retained ranks, but it is not silently substituted for the measured spectrum. L2 provenance identifies the catalogue or match-table source, its revision and the fields used, distinguishing an input class prior from an APS measurement.

Ranked classification and fallback are routing decisions

Classification is retained as a ranked object rather than reduced immediately to one label. The configurable ntop table carries class, redshift, uncertainty, warning and fit information. In the IFU preparation configuration, class_ntop=3; the selected value is stored with the run configuration. Target metadata are interpreted hierarchically: TARGCLASS, then TARGPROG, then survey-code configuration in TARGSRVY. When a requested class is absent from the retained ranks, PyAPS searches the full fit table and replaces only the last retained slot when a matching candidate exists. If the archetype fit is degraded relative to the coarse PCA reference, fallback can preserve the trusted redshift/class reference, retain archetype coefficients and attach an APS warning bit. These operations preserve ambiguity for inspection; they do not establish that the classification is correct. Their rates and accuracy remain commissioning measurements.

The rank-retention mechanics were separately exercised with controlled Redrock-like tables. For ntop=3, a target whose retained classes were GALAXY,QSO,GALAXY and whose full fit contained a valid STAR candidate received that candidate in slot 3, while slots 0 and 1 were preserved. When no matching full-fit candidate existed, the helper performed no injection. These controlled cases verify the container and fallback mechanics, while labelled samples provide the corresponding classification-accuracy tests.

For the multi-arm CPU coarse scan, PyAPS fits template coefficients independently in each arm at each trial redshift and sums the arm
${\chi }^2$

values. It returns an equal-weight mean of the fitted arm coefficients. This differs from the upstream joint fit, which uses one coefficient vector across the input spectra. The summed
${\chi }^2$

retains the input inverse-variance weighting. Single-arm and GPU paths use the original Redrock batch solver (Section F of the paper).

Run identity and reproducibility

Each numerical result is associated with the PyAPS revision, external package versions, FERRE executable and compiler build, template and grid identifiers, LSF calibration, configuration files, input identifiers and output manifest. Table 11 summarises these fields; Section F of the paper expands them by module.