L1-to-L2 routes through APSOB

Table 16 specifies the input, intermediate and output contracts along these routes.

The L1 product type determines how PyAPS prepares the data and records its history, while the classification determines which scientific modules run. For every route, PyAPS first inspects the input and constructs an APSOB. It then runs the appropriate class-specific modules. The final merger uses their products together with the target and processing identifiers already stored in APSOB. Throughout these routes, EMI denotes PyAPS’s implementation of pPXF for WEAVE emission-line analysis; it is not an independent package or engine.

The single, stack, superstack, cube, cubelet, supercube and supercubelet routes in Table 15 are production-active. The three supertarget routes are commissioning-only and have not yet been exercised in operational testing. The table shows the planned processing steps for these commissioning routes.

The common APSOB stage

At entry, l1_fileinfo records the observing form, array dimensionality, arm/camera, resolution, detector binning, wavelength range, calibration references and input history. APSOB then creates APSTARG objects for selected targets or spatial elements and APSSPEC instances for their wavelength, count-to-flux calibrated spectrum, propagated inverse variance and retained L1 sensitivity-function arrays. A 3-D cube is reshaped at this stage. Its spatial coordinates and source or bundle identifiers remain attached to the resulting spectra, so downstream modules can use the same spectrum-oriented objects as the MOS route. PyAPS handles the L1 layout once instead of asking each scientific module to do so again.

MOS route: classification to merger

The MOS adapter applies configured masks, joins compatible arms and sends the selected APSSPEC rows to Redrock. The retained ranked solutions, target-class metadata and warning bits form the routing record. STAR/WD rows are passed to RVS for velocity and stellar fitting preparation and then to FERRE for the configured atmospheric grid analysis. GALAXY/QSO rows are sent to pPXF, followed by emission-line fitting and line-strength measurement when enabled. These branches can run independently after their classification dependency; the merger is released after every branch terminates, admits absent optional component groups as flagged empty extensions and rejects the product when the classification table is empty or both the stellar and galaxy tables are empty. The MOS merger writes classification, stellar, galaxy, spectral and history extensions without changing the underlying APSOB identity.

IFU route: cube, patch, bin and merger

For a LIFU or mIFU cube, APSOB construction is followed by white-light source detection and patch preparation. Each accepted patch row carries aperture geometry, row type, class/redshift ranks and masks. The ExGal worker selects the patch spaxels, applies its S/N/surface-brightness policy, performs optional prebinning and Voronoi/PowerBin tessellation, and log-rebins spectra for pPXF. It then produces the pPXF, emission-line and line-strength products. The Gal worker uses the same patch geometry and APSOB spectra but keeps the observed wavelength grid and follows RVS/FERRE preparation. The bin table retains the generating spaxels, and the LSF path aggregates spaxel curves to each bin. Finally, the IFU merger combines patch, bin, class-specific science and history tables, preserving CNAME, bundle, arm, RESBIN and input-run processing record. A patch failure is localized to a patch/target row; an all-target worker failure is terminal. The ExGal merger requires non-empty patch and binned-spectrum tables, while the Gal merger requires a non-empty patch table, so neither case is silently converted into a cube-wide zero result.

Mode-specific execution and product flow

Table 17 and Table 18 summarise the processing stages and exchanged products.

This section expands the common architecture into the concrete execution paths used for MOS and IFU products. The distinction is important: APSOB provides a shared representation, but the target-selection, spatial preparation, module ordering and output products remain mode-dependent.

Common entry point and stage selection

The runner first resolves the input files and configuration before constructing the workflow graph. Header inspection identifies the observing form, camera, resolution and detector binning; the selected JSON/YAML configuration then controls target filters, wavelength ranges, masks, LSF policy, binning and module options. The source contains separate MOS and IFU graph generators, with the IFU generator covering LIFU and MIFU. Parameter precedence is explicitly resolved by the IFU configuration helper rather than left to each scientific module.

The resulting workflow passes files and tables between several stages. A typical MOS path begins with classification and then routes stellar targets to radial-velocity and stellar-parameter modules, while galaxy targets are routed to redshift, emission-line and population-analysis modules. An IFU path first creates spatial products and bins, then branches to the Galactic or extragalactic analysis family. The exact graph is determined by configuration and available intermediate products.

MOS processing

Classification and routing

The MOS workflow uses Redrock classification and redshift to select the subsequent analysis. Its table supplies class labels, redshifts and target identifiers that are consumed by later modules. Stellar and white-dwarf rows are eligible for the RVS and FERRE adapters; galaxy-like rows are passed to the extragalactic analysis path. The contributed-software generator can additionally construct commands for project-approved contributed analysis packages, ALFA-NEAT, RRLGV and RRLEW, subject to configuration and target availability.

Stellar branch: RVS and FERRE

The RVS adapter reads the selected stellar targets through APSOB, attaches a per-target wavelength-dependent resolution matrix when available, and calls the external RVSPECFIT engine. The adapter records radial velocity and stellar-parameter outputs together with PyAPS warning information in WEAVE oriented FITS tables. FERRE can use those velocities as initial conditions. It then writes batched spectral inputs, runs one or more external Fortran grids, waits for grid outputs, selects the lowest-
${\chi }^2$

valid grid per target and converts the merged results into a PyAPS FITS product. Grid selection, subprocess control, resource policy and output merging are PyAPS integration; the synthetic-grid fitting algorithm is FERRE.

Extragalactic branch

For galaxy and quasar-like targets, the MOS path reuses the APSOB spectra and the classification table while constructing the inputs required by pPXF, emission-line fitting and line-strength modules. The adapters map the common flux, inverse variance, wavelength and LSF representation into each engine’s contract, collect warnings and attach the resulting columns to the final L2 tables. Contributed methods may instead consume a normalised L1 path, a classifier/RVS intermediate product or the assembled APS L2 path. The selected path is retained in the run configuration.

IFU processing

The conceptual design of the first PyAPS IFU workflow was informed by the GIST pipeline, in particular its separation of preparatory operations from modular kinematic, emission-line, stellar-population and line-strength analysis stages (Bittner et al.,, 2019). Subsequent development diverged into an independently maintained, WEAVE-specific system: the source history records that PyAPS no longer depended on GIST by August 2020, and the current code has no GIST runtime import. GIST remains an important influence on the original design, but the present IFU pipeline is an independent system. It extends beyond that initial concept by accepting both reconstructed and fibre-level WEAVE IFU products, constructing patch and bin representations, routing classified targets through Galactic and extragalactic branches, propagating spatially varying LSF information and assembling survey-defined L2 products.

Spatial preparation

IFU processing has an additional spatial layer before scientific fitting. aps_ifu_prepare can generate a patch from image segmentation and classification or consume an existing patch table. APSOB then applies target and spatial selection to the cube, preserving the mapping between spaxel IDs, sky coordinates and contributing exposures. Extragalactic preparation can pre-bin, filter low-S/N spaxels and perform adaptive binning; Galactic preparation filters patch rows to stellar or white-dwarf targets and applies configured spatial or adaptive binning. The resulting tables preserve the linkage needed to reproduce which spaxels contributed to each bin.

IFU Galactic and extragalactic branches

The IFU Galactic branch passes accepted stellar apertures or spatial bins to the RVS and FERRE adapters. The IFU extragalactic branch passes binned spectra to pPXF, emission-line and line-strength modules, while retaining patch and bin identifiers for L2 assembly. In both branches the resolution input can be global, fibre-derived, spaxel-weighted or bin-specific. Thus the common APSOB contract does not erase IFU spatial semantics; it carries them alongside the same spectral access methods.

Spatially varying resolution

For a reconstructed cube, PyAPS resolves the physical fibres that contributed to each spaxel, evaluates their calibrated FWHM curves and combines them with geometric or flux-derived weights. Bin-level curves are then formed from the member spaxels and may be represented by bounded resolution buckets. The current baseline is Gaussian-equivalent FWHM; non-Gaussian
$h_3/h_4$

ingestion and propagation remain future work. The Gaussian-equivalent spaxel/bin path is production-approved and covered by the LSF propagation tests.

Products and hand-offs

The final output is saved as a FITS product. MOS products contain primary metadata plus classification, stellar, galaxy and analysed-spectrum information where applicable. IFU extragalactic products additionally link per-spaxel patch rows to adaptive-bin spectra; IFU Galactic products retain the selected stellar apertures and their analysis outputs. The merger writes available processing identifiers, quality fields, FITS checksums and data sums. The products pass the current conformance tests.