Added documentation for beam tracking and position information

tangostationcontrol/docs/source/beam_tracking.rst

+Beam Tracking
+====================
+
+A primary function of the station is to combine its antenna signals to create a more sensitive signal. The antennas are typically aimed at celestial sources moving across the sky, but can also be aimed at stationary targets, for example to point at Earth-bound signals or to let the sky pass through the beam instead.
+
+Given a certain direction, and knowing the speed of light, one can compute the differences in arrival time for light from the observed source (its wave front) towards each antenna. The antenna signals are then aligned towards the source by delaying the signal inputs based on these differences. The antennas closest to the source get the largest delay. For celestial sources, the light is assumed to be infinitely far away and thus travel in parallel towards each antenna, greatly simplifying the calculations involved.
+
+In practice, antenna signals can only be coarsely delayed. Fine delay compensation consists of rotating the signal inputs to compensate for the remaining differences in phase. The amount of rotation is frequency dependent. The aligned signals are subsequently added, creating a single signal output of higher sensitivity towards the observed source, albeit with a narrower field of view.
+
+Beam tracking therefor requires the *pointing* direction in which to observe, as well as the *positions* of the antennas involved. Finally, the antennas need to be periodically realigned to track moving sources.
+
+Terminology
+--------------------
+
+We distinguish the following concepts:
+
+- *Beam forming* is combining individual element signals into one. This is performed by the HBAT hardware and SDP firmware,
+- *Beam steering* is uploading the delays or weights to the beam-forming hardware, in order to point the beam in a certain direction,
+- *Beam tracking* is updating the beam steering over time to track a celestial target, compensating for the Earth's movement through space.
+
+Pointing
+--------------------
+
+A *pointing* describes the direction in the sky, and consists of a set of coordinates and the relevant coordinate system. They are represented as a tuple of 3 strings: ``("coordinate_system", "angle1", "angle2")``, where the interpretation of ``angle1`` and ``angle2`` depends on the coordinate system used. For example:
+
+- ``("AZELGEO", "0deg", "90deg")`` points at Zenith (Elevation = 90°, with respect to the Earth geode),
+- ``("J2000", "0deg", "90deg")`` points at the North Celestial Pole (Declination = 90°),
+- ``("SUN", "0deg", "0deg")`` points at the centre of the Sun.
+
+For a full list of the supported coordinate systems, see https://casacore.github.io/casacore/classcasacore_1_1MDirection.html
+
+Coordinates in a celestial coordinate system result in a different direction depending on the time. Each pointing is associated with a *timestamp* for when it was or is to be applied. When not specified, ``datetime.datime.now()`` is used.
+
+Positions
+--------------------
+
+The positions of the antennas are required in ITRF, a carthesian geocentric coordinate system ("XYZ" with its origin at the center of the Earth). These coordinates provide an absolute 3D position on Earth and form the basis for most delay computations. These positions are not stationary however, due to the tectonic plate movement. Instead, we use source coordinates in ETRS89 (also carthesian geocentric), and convert those to ITRF using updated and extrapolated tectonic models (see ``tangostationcontrol.beam.geo.ETRS_to_ITRF``).
+
+:recv.HBAT_reference_ETRS: (property) The reference position of each HBA tile, in ETRS89.
+
+  :type: ``float[96][3]``
+
+:recv.ITRF_Reference_Frame: (property) The ITRF system to convert coordinates to (default: ITRF2005).
+
+  :type: ``str``
+
+:recv.ITRF_Reference_Epoch: (property) The year to extrapolate the ITRF system to (typically half-year increments, such as 2015.5).
+
+  :type: ``float``
+
+:recv.HBA_reference_ITRF_R: The computed refence positions of each HBA tile, in ITRF.
+
+  :type: ``float[96][3]``
+
+NB: It is also possible to explicitly specify ITRF positions in the ``recv.HBAT_reference_ITRF`` property to side step the calculations based on ETRS.
+
+HBAT element positions
+````````````````````````
+
+The positions of the elements within an HBA tile are handled differently. Instead of storing the positions of each of the 16 elements in each tile, we use the fact that the relative positions of the elements within each tile is fixed, and that in LOFAR stations, all the HBA tiles of a station are on the same plane (instead of following the curvature of the Earth). This plane is given its own station-local coordinates, the PQR system:
+
+- It's origin is at a chosen center of the station,
+- The Q axis is aligned with an absolute North (not the North of the station, which would be a different direction per station),
+- The P axis is roughly East,
+- The R axis is roughly down,
+- The HBA tiles on a station all lie on the same PQ plane, so R == 0.
+
+These facts allow us to use the following information to calculate the absolute position of each tile element. The conversion takes the relative offsets of the elements within a tile, rotates them in PQR space, rotates those into relative ETRS offsets, and finally into absolute positions in ETRS. See ``tangostationcontrol.beam.hba_tile`` for these computations.
+
+:recv.HBAT_base_antenna_offsets: (property) The relative offsets of each element within a tile, with respect to the tile's reference position (the center of the ground plane).
+
+  :type: ``float[16][3]``
+
+:recv.HBAT_PQR_rotation_angles_deg: (property) The horizontal rotation of each HBA tile in the PQ plane, in degrees (Q -> P).
+
+  :type: ``float[96]``
+
+:recv.HBAT_PQR_to_ETRS_rotation_matrix: (property) The 3D rotation matrix to convert PQR coordinates into relative ETRS coordinates.
+
+  :type: ``float[3][3]``
+
+:recv.HBAT_reference_ETRS: (property) The absolute reference position of each HBA tile, in ETRS89.
+
+  :type: ``float[96][3]``
+

tangostationcontrol/docs/source/devices/beam.rst

 Beam
 ====================
 
-The ``beam == DeviceProxy("STAT/Beam/1")`` device sets up the beamforming on the station:
+The ``beam == DeviceProxy("STAT/Beam/1")`` device sets up the beamforming on the station. It configures the HBA tile beam former, which adds the signals of its 16 elements within the tile. These element signals can be delayed a configurable amount of time, allowing their sum to become more sensitive in a certain direction. Each tile can have their own pointing direction configured.
 
-- The HBA tiles in RECV need *analog beamforming* to combine their 16 antennas into a single input for the RCU,
-- THe LBAs or HBA tiles need *digital beamforming* in SDP to combine their signals into beamlets.
+Beam Tracking
+--------------------
 
+Beam tracking automatically recomputes and reapplies pointings periodically, and immediately when new pointings are configured. It exposes the following interface:
+
+:HBAT_tracking_enabled_R: Whether beam tracking is running.
+
+  :type: ``bool``
+
+:HBAT_pointing_direction_RW: The direction in which the beam should be tracked for each antenna. The beam tracker will steer the beam periodically, and explicitly whenever the pointings change.
+
+  :type: ``str[N_ant][3]``
+
+:HBAT_pointing_direction_R: The last applied pointing of each antenna.
+
+  :type: ``str[N_ant][3]``
+
+:HBAT_pointing_timestamp_R: The timestamp for which the last set pointing for each antenna was applied and set (in seconds since 1970).
+
+  :type: ``float[N_ant][3]``
+
+Beam Steering
+--------------------
+
+The beam steering is responsible for pointing the beams at a target, by converting pointings to ``recv.HBAT_bf_delay_steps``. The beam steering is typically controlled by the beam tracker. To point the antennas in any direction manually, you should disable beam tracking first:
+
+:HBAT_tracking_enabled_RW: Enable or disable beam tracking (default: ``True``). 
+
+  :type: ``bool``
+
+:HBAT_set_pointing(pointings): Point the beams towards the specified ``pointings[N_ant][3]`` for all antennas (for which ``recv.ANT_mask_RW`` is set).
+
+  :returns: ``None``
+
+Computation Parameters
+-----------------------
+
+To form a beam from a set of antennas in a certain direction, the signals coming from each antenna needs to be aligned, such that signals coming from that direction become coherent. In tile beam forming, this is accomplished by proportionally delaying the signals from the antennas that are closer to the target.
+
+To compute the required delays, both the direction of the source and the position of the antennas are required. Furthermore, a *reference position* is used, a virtual position towards which the antenna signals are aligned. The reference position is typically in the center of the set of antennas.
+
+HBA positions
+```````````````````````
+
+For the tile beam, these positions are stored as follows in the ``recv`` device:
+
+:recv.HBAT_antenna_itrf_offsets_R: The relative offsets of the elements within each HBA tile with respect to its reference position, in ITRF.
+
+  :type: ``double[16][3]``
+
+:recv.HBAT_reference_itrf_R: The absolute reference position for an HBA tile, in ITRF.
+
+  :type: ``double[96][3]``
+
+NB: A LOFAR antenna field is constructed such that all tiles lie within the same plane, instead of following the curvature of the Earth. This means that the relative offsets of the elements with an HBA tile in ITRF is the same for every tile in the antenna field.
+
+HBA delays
+```````````````````````
+
+Each HBA tile is steered by configuring the number of *delay steps* to introduce for each element. 
+
+Direction information
+```````````````````````
+
+We use `python-casacore <https://casacore.github.io/python-casacore/index.html>`_ to compute the direction of a given pointing with respect to our antennas and reference positions. Casacore in turn uses *measures* tables for the precise measurements of celestial positions, geodetical information, and time calibrations (f.e. leap seconds). These tables need to be installed and periodically updated to maintain the pointing accuracy:
+
+:measures_directory_R: Directory of the active set of measures tables. The directory name includes the timestamp denoting their age.
+
+  :type: ``str``
+
+:measures_directories_available_R: List of installed sets of measures tables.
+
+  :type: ``str[64]``
+
+:download_measures(): Download (but do not activate) the latest measures tables from ftp://ftp.astron.nl. Returns the directory name in which the measures were installed.
+
+  :returns: ``str``
+
+:use_measures(dir): Activate the measures tables in the provided directory. This necessitates turning off and restarting the Beam device, so the command will always appear to fail. Turn the device back and the selected measures tables will be active.
+
+  :returns: ``(does not return)``

tangostationcontrol/docs/source/devices/recv.rst

@@ -37,4 +37,3 @@ These attributes summarise the basic state of the device. Any elements which are
 :RCU_TEMP_error_R: Whether there are alarms on any of the temperatures. NB: These values are also exposed for unused RCUs (the ``RCU_mask_RW`` is ignored).
 
   :type: ``bool[N_RCUs]``
-