Static and dynamic data model

Table 2, Table 3 and Table 4 describe collection membership, construction order and field-level contracts.

The APSOB data model is intentionally dynamic at the collection level. The same Python object can hold a MOS target, an IFU spaxel or a spatially binned representation, while the shape and metadata of its arrays remain tied to the input product and selected processing options. This page records the fields that are stable enough to define the scientific contract and the fields that must be read from the object at runtime.

Object hierarchy

For MOS, an APSTARG normally corresponds to one physical fibre. For a cube, it corresponds to one reconstructed spaxel during preparation; after spatial binning, the analysis record refers to a set of spaxels and a derived bin spectrum. The object hierarchy therefore preserves both the uniform spectral access contract and the geometry needed to interpret a result.

Stable fields and runtime fields

The stable part of the contract consists of wavelength, flux, inverse variance, target identifier and provenance. Runtime fields depend on the chosen flags: joined versus separate arms, rest-frame versus observed-frame wavelengths, global versus fibre/spaxel/bin LSF, and linear versus logarithmic sampling. A module must therefore request the fields it supports and cannot assume that every APSSPEC has the same array length or wavelength frame.

APSOB construction sequence

The common object is not created by a single format conversion. The loader applies an ordered preparation sequence; individual flags can disable optional steps, but the resulting processing state is retained in the object and in the product provenance. The sequence below makes explicit which operations are shared before an engine-specific adapter receives an APSSPEC.

The order is scientifically consequential. For example, masking and IVAR normalisation affect Redrock ranking, wavelength-frame selection affects rest-frame galaxy analysis, and resolution import must precede template/data matching. The sequence is therefore part of the PyAPS interface contract, not merely an implementation detail; exact flag values and optional branches remain run-specific.

Memory and sharing semantics

The dynamic model is also a memory model. Target spectra in one arm refer to rows of shared processed arrays and share wavelength and invariant resolution objects where possible. An adapter may request a serialisable or multiprocessing shared-memory representation, but the ownership and lifetime of that view depend on the worker boundary. The measured memory and serialisation performance of these sharing strategies is reported in the accompanying paper.

Common data and configuration architecture

Input classification and normalisation

PyAPS begins by interpreting the observing mode, camera, disperser, resolution and detector binning recorded in a Level-1 FITS product. The l1_fileinfo path distinguishes five normalised input forms: MOS, LIFU, MIFU, MOSLIFU and MOSMIFU. Two-dimensional fibre products and three-dimensional reconstructed cubes are converted to a common target and spectrum representation while retaining mode-specific coordinates, physical fibre identifiers and input history where these exist.

The object hierarchy and shared-array representation are defined above in W3. The following tables add the setup selectors and spectral fields used during ingestion.

Configuration space

Here ExGal denotes the extragalactic branch (galaxies and QSOs), while Gal denotes the Galactic branch (stars and white dwarfs). The APS v2.0 source contains 30 base input-form-resolution-binning selectors and 75 accepted arm-specific resolution keys before stacking, target selection and science-module routing. These counts describe the configurations recognised by PyAPS v2.0. They do not describe how often each configuration is observed.

Every row in Table 5 contributes six base selectors and 15 arm-specific keys: three LR binning cases each accept BLUE and RED, while three HR cases each accept the internal PyAPS keys BLUE, GREEN and RED. The published WEAVE nomenclature is Blue-1 and Blue-2 (Jin et al., 2024); at HR, the internal BLUE key maps to Blue-1 and the internal GREEN key maps to Blue-2. The resulting
$5\times 6=30$

and
$5\times 15=75$

counts are reproduced in the machine-readable configuration crosswalk. The v2.0 interface therefore comprises 30 base selectors and 75 arm-specific keys. Stacking depth, target selection and scientific-module routing are independent dimensions and are not folded into these counts.

Table 5 summarises the mode-specific input forms, while Table 6 lists the common information passed to later modules. The input form, resolution and binning are identified during ingestion, before the scientific modules receive APSTARG and APSSPEC objects. Product-specific details are therefore handled once in APSOB, while later modules use the same internal structure.

Selection, correction and metadata

During construction, APSOB selects targets or spatial regions, builds the wavelength representation, normalises inverse variance, applies the requested L1 sensitivity-function calibration and spectral corrections, loads wavelength-dependent resolution, and optionally joins or splits arms. The resulting target metadata preserves identifiers needed for catalogue matching, module exchange and product assembly. Exact options are configuration- and workflow-dependent and are stored in the run configuration and processing record.

Object and memory model

Within one processed arm, target spectra share the wavelength object and refer to rows of processed two-dimensional flux and inverse-variance arrays, while retaining the corresponding L1 sensitivity-function calibration. This avoids allocating a full independent arm array for every target. Invariant global-resolution objects are also shared. The current load path uses in-place application of the count-to-flux sensitivity function, reduction-based signal-to-noise prefiltering and hoisted per-arm metadata to reduce temporary arrays and Python object work. Representative timing and peak-memory measurements are reported in the accompanying paper.