#####################################
MCCS Beam Weight Store Implementation
#####################################

The **MccsBeamWeightStore** is a Tango device that provides centralized storage and
retrieval of beam weights for the SKA Low telescope. **MCCS** uses it to compute
station phase centres during beam configuration and to determine per-antenna
weights for beamforming.

The beam weight store is also used by **OSO** (Observatory Science Operations)
to add and manage weights, and by **TMC** (Telescope Monitoring and Control) to
calculate substation phase centres for generating geometric delays for the
**CBF** (Correlator Beam Former). After calibration, attributes are updated
with the applied phase centres [Thorn-198]_.

Currently, weights are the same for all stations, but there is one instance of
the MccsBeamWeightStore per station to support future per-station weightings.

Key Features
============

- Stores complex-valued weights for 256 antennas per station
- Supports CRUD operations via Tango commands
- Provides versioning of antenna weight recipes
- Supports multiple weighting keys for different configurations
- Backend-agnostic interface allows switching between implementations

Tango Commands
==============

+------------------+-----------------------------------------------------------+
| Command          | Description                                               |
+==================+===========================================================+
| Insert           | Add new weights with a weighting key                      |
+------------------+-----------------------------------------------------------+
| Update           | Modify existing weights                                   |
+------------------+-----------------------------------------------------------+
| Delete           | Remove weights by key                                     |
+------------------+-----------------------------------------------------------+
| Select           | Retrieve weights by key                                   |
+------------------+-----------------------------------------------------------+
| Contains         | Check if a weighting key exists                           |
+------------------+-----------------------------------------------------------+
| GetIndices       | Get EEP indices for antennas                              |
+------------------+-----------------------------------------------------------+
| GetWeightingKeys | List all available weighting keys                         |
+------------------+-----------------------------------------------------------+

Architecture
============

The following figure shows a class diagram illustrating the
**MccsBeamWeightStore** architecture.

.. uml::
   beam_weight.uml

The **MccsBeamWeightStore** has been implemented with two backend options:

- **Database Backend**: Uses an SQL database for persistent storage
- **Telmodel Backend**: Integrates with the telescope model database service

These are provided via the following main device and backend classes:

- ``MccsBeamWeightStore``: Tango device interface
- ``MccsBeamWeightStoreBackend``: Abstract backend interface
- ``MccsBeamWeightStoreDatabaseBackend``: SQL database implementation
- ``MccsBeamWeightStoreTelmodelBackend``: Telmodel REST API implementation

The eventual aim is to use the Telmodel database service once it is properly
deployed. However, the SQL backend is provided to enable use of the beam weight
store in the meantime. The SQL backend will be used in deployment with the same
Postgres database used by the **MCCSCalibrationStore** Tango device.

Usage in MCCS
=============

Within **MCCS**, the beam weight store is used during beam configuration.
**TMC** provides configuration parameters, including a ``weighting_key_ref``,
which is used during the station beam ``Configure`` command to query the
**MccsBeamWeightStore** for the appropriate weights.

These weights are combined with the **BeamformerTable** (set up during
``Allocate`` and ``Configure`` commands) to compute per-channel, per-antenna
weights. The calculated weights are then applied to the **SPS** subsystem via
calibration coefficients.

The ``calculatePhaseCentre`` command (currently unimplemented) will compute the
station phase centre, which is used by **MCCS** pointing algorithms for beam
steering.

A command flow diagram is provided below for reference:

.. uml::
   beam_weight_application.uml

System Integration
==================

+---------+--------------------------------------------------------------------+
| System  | Interaction with MccsBeamWeightStore                               |
+=========+====================================================================+
| MCCS    | Retrieves weights and calculates station phase centres and applies |
|         | weights to the station beams on a per antenna per channel basis.   |
+---------+--------------------------------------------------------------------+
| OSO     | Adds/updates weights via API or device interface                   |
+---------+--------------------------------------------------------------------+
| TMC     | Calculates substation phase centres to derive geometric delays for |
|         | CBF                                                                |
+---------+--------------------------------------------------------------------+

References
==========

.. [Thorn-198] https://confluence.skatelescope.org/display/SE/THORN-198+-+Beam+weighting+recipes