Quality Attributes
==================

Overview
********

Low CBF publishes telescope- and subarray-level *quality* figures that let
operators judge the quality of the Low CBF signal-processing outputs — delay
readiness, Jones-matrix application, SPS RMS levels and flagging, link-up and
host resolution. These figures are exposed as Tango attributes on the quality
device ``low-cbf/transducer/quality``, aggregated from the underlying
Allocator, Subarray, Processor and Connector devices, and refreshed
every few seconds.

Published quality attributes
****************************

.. list-table::
   :header-rows: 1
   :widths: 32 12 56

   * - Attribute
     - Type
     - Description
   * - ``processorsReadyPercent``
     - JSON map
     - Per-subarray percentage of processors ready.
   * - ``processorEthernetLockedPercent``
     - JSON map
     - Per-subarray percentage of processors ethernet locked.
   * - ``spsLinkUpPercent``
     - Double
     - Telescope-wide percentage of SPS ingest links that are up.
   * - ``cbfPacketLossRate``
     - Double
     - Telescope-wide percentage of SPS ingest links packet loss rate.
   * - ``cbfPacketCorruptionRate``
     - Double
     - Telescope-wide percentage of SPS ingest links packet corrupted rate.
   * - ``pssHostsResolvedPercent``
     - JSON map
     - Per-subarray percentage of PSS destination hosts resolved.
   * - ``pstHostsResolvedPercent``
     - JSON map
     - Per-subarray percentage of PST destination hosts resolved.
   * - ``sdpHostsResolvedPercent``
     - JSON map
     - Per-subarray percentage of SDP destination hosts resolved.
   * - ``stationBeamDelayReadyPercent``
     - JSON map
     - Per-subarray percentage of station beams with valid delays.
   * - ``pstBeamDelayReadyPercent``
     - JSON map
     - Per-subarray percentage of PST sub-beams with valid delays.
   * - ``pssBeamDelayReadyPercent``
     - JSON map
     - Per-subarray percentage of PSS sub-beams with valid delays.
   * - ``pstJonesAppliedPercent``
     - JSON map
     - Per-subarray percentage of PST beams with a Jones matrix applied.
   * - ``pstJonesAge``
     - JSON map
     - Per-subarray mean age (seconds) of the applied PST Jones matrices.
   * - ``spsRmsInRange``
     - JSON map
     - Per-subarray percentage of SPS RMS samples within the accepted range.
   * - ``spsFlagsPercentMean``
     - JSON map
     - Per-subarray mean SPS flagged-sample percentage.
   * - ``processorFpgaTemperatureMean``
     - JSON map
     - Per-subarray processors mean temperature.
   * - ``processorFpgaPowerMean``
     - JSON map
     - Per-subarray processors mean power.

JSON output format
******************

Every per-subarray attribute above (type "JSON map") is a Tango string
attribute whose value is a JSON object mapping a **subarray id** to a value::

    {"<subarray_id>": <value>, ...}

* Keys are the integer subarray ids, encoded as JSON object keys (i.e.
  strings, e.g. ``"1"``).
* A value is ``null`` when the figure cannot be computed for that subarray
  (for example, no data has yet been reported for it).
* The map contains only the subarrays that are currently configured, so it
  scales to any number of subarrays.

Example (``stationBeamDelayReadyPercent``):

.. code-block:: json

    {"1": 100, "2": 75, "3": null}

Here subarray 1 has all station-beam delays valid, subarray 2 has three
quarters valid, and subarray 3 reported no usable data.

``spsLinkUpPercent`` is the one exception: it is a plain scalar ``Double``
(telescope-wide), not a JSON map.

Attribute detail
****************

SPS link-up and host resolution
-------------------------------

* ``spsLinkUpPercent`` — the telescope-wide percentage of SPS ingest links
  that are currently up.
* ``pssHostsResolvedPercent`` / ``pstHostsResolvedPercent`` /
  ``sdpHostsResolvedPercent`` — the per-subarray percentage of PSS / PST /
  SDP destination hosts whose network address has been resolved. Each is a
  ``{subarray_id: percent}`` map:

  .. code-block:: json

      {"1": 100, "2": 0}

Processor readiness and Ethernet
--------------------------------

* ``processorsReadyPercent`` — per subarray, the percentage of the subarray's
  assigned processors that are ready (reporting a ready stats mode **and** an
  OK health state).
* ``processorEthernetLockedPercent`` — per subarray, the percentage of the
  subarray's assigned processors whose ingest Ethernet link is locked (the
  processor reports its link locked **and** the matching switch port is up).

Both are ``{subarray_id: percent}`` maps and are ``null`` when the subarray is
not in ``READY`` or ``SCANNING``, or has no processors assigned:

.. code-block:: json

    {"1": 100, "2": 50, "3": null}

CBF packet loss and corruption
------------------------------

* ``cbfPacketLossRate`` — the fraction of CBF SPEAD packets lost, aggregated
  over the processors the Allocator has currently assigned to a subarray.
  Derived from per-processor SPEAD counters as ``missing / (received +
  missing)`` over the interval between refreshes.
* ``cbfPacketCorruptionRate`` — the fraction of CBF SPEAD packets corrupted
  (bad Ethernet packets), over the same denominator.

Both are plain scalar ``Double`` values (telescope-wide), expressed as a
fraction in the range ``0.0``–``1.0``. With no processors allocated the
counters are empty and both resolve to ``0.0``.

Delay readiness
---------------

``stationBeamDelayReadyPercent``, ``pstBeamDelayReadyPercent`` and
``pssBeamDelayReadyPercent`` give, per subarray, the percentage of beams
that currently have valid delays — at the station-beam, PST sub-beam and PSS
sub-beam levels respectively.

Each is a ``{subarray_id: percent}`` map, with ``null`` where no delay data is
available:

.. code-block:: json

    {"1": 100, "2": 88, "3": null}

PST Jones (applied % and age)
-----------------------------

Jones figures are **PST only** — there is no PSS Jones data, so there are no
``pssJones*`` attributes.

* ``pstJonesAppliedPercent`` — per subarray, the percentage of configured
  PST beams that have had a Jones (calibration) matrix applied.
* ``pstJonesAge`` — per subarray, the mean age in seconds of the most
  recently applied PST Jones matrices. A beam that has not yet had a matrix
  applied counts as **3600 s (1 hour)** old. The figure is ``null`` when a
  subarray has no PST beams reporting.

Both are ``{subarray_id: value}`` maps — a percentage for
``pstJonesAppliedPercent``, a mean age in seconds for ``pstJonesAge``:

.. code-block:: json

    {"1": 100, "2": 50}

.. code-block:: json

    {"1": 12, "2": 3600}

SPS RMS-in-range and flags percent
-----------------------------------

* ``spsRmsInRange`` — per subarray, the percentage of SPS RMS samples
  (across both polarisations) that fall within the accepted range. The range
  bounds are configurable and default to 10–30.
* ``spsFlagsPercentMean`` — per subarray, the mean percentage of SPS samples
  that are flagged.

Both are ``{subarray_id: percent}`` maps, and are ``null`` for a subarray that
reports no SPS data:

.. code-block:: json

    {"1": 97, "2": 100, "3": null}

Processor FPGA temperature and power
------------------------------------

* ``processorFpgaTemperatureMean`` — per subarray, the mean FPGA core
  temperature (degrees Celsius) across the subarray's assigned processors.
* ``processorFpgaPowerMean`` — per subarray, the mean FPGA power draw (watts)
  across the subarray's assigned processors.

Both are ``{subarray_id: value}`` maps — degrees Celsius for temperature,
watts for power — and are ``null`` where the subarray has no processors
assigned:

.. code-block:: json

    {"1": 41.5, "2": 39.8, "3": null}