diff --git a/tangostationcontrol/docs/source/beam_tracking.rst b/tangostationcontrol/docs/source/beam_tracking.rst deleted file mode 100644 index a9860420af79ffa6ddc9e348abfb122911a8efc9..0000000000000000000000000000000000000000 --- a/tangostationcontrol/docs/source/beam_tracking.rst +++ /dev/null @@ -1,85 +0,0 @@ -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.tilebeam.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.tilebeam.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]`` - diff --git a/tangostationcontrol/docs/source/devices/antennafield.rst b/tangostationcontrol/docs/source/devices/antennafield.rst index 13700c1d544b616deeafc3bfc07f468b2e608d80..d9c36a0148fab3b74b8cf1311b0d8c4369686da9 100644 --- a/tangostationcontrol/docs/source/devices/antennafield.rst +++ b/tangostationcontrol/docs/source/devices/antennafield.rst @@ -1,4 +1,99 @@ AntennaField -------------------- -``antennafield == DeviceProxy("STAT/AntennaField/1")`` +The ``antennafield == DeviceProxy("STAT/AntennaField/1")`` device represents a set of *antennas* or *tiles* that collectively form an antenna field. It represents a selection of inputs from one or more ``RECV`` devices, annotated with metadata such as positional information. + +:nr_tiles_R: The number of antennas or tiles in the antenna field. + + :type: ``uint32`` + +It provides many settings that map onto the ``RECV`` device directly, serving as a funnel: + +:HBAT_ANT_mask_RW: Which antennas are configured when writing settings. + + :type: ``bool[N_tiles]`` + +.. warning:: Any antennas in the field that are not connected to any ``RECV`` device will return default values (f.e. ``False`` or ``0``). + +Positions +```````````````````` + +The following attributes expose positional information about the individual antennas in the field, in different formats: + +:HBAT_reference_GEO_R: Reference position of each HBA tile, in latitude/longitude (degrees). + + :type: ``float64[N_tiles][2]`` + +:Antenna_Field_Reference_GEO_R: Reference position of the antenna field, in latitude/longitude (degrees). + + :type: ``float64[2]`` + +Additionally, the ``ITRF`` and ``GEOHASH`` variants provide the same information, but in ITRF (x/y/z, metres), and in Geohash strings, respectively. + +Also, the offsets of the elements within each HBA tile are provided: + +:HBAT_antenna_ITRF_offsets_R: Relative position of each HBA tile element with respect to the tile reference. + + :type: ``float64[N_tiles][N_elements * 3]`` + :shape: ``float64[N_tiles][N_elements][3]`` + +Configuration +```````````````````` + +The antennas represented by the antenna field are selected by the following properties: + +:RECV_devices: The list of ``RECV`` devices from which antennas are selected. + + :type: ``str[]`` + +:HBAT_Power_to_RECV_mapping: Pairs of numbers ``(recv_idx, ant_idx)`` describing the inputs on which the HBAT *power* is connected. The ``recv_idx`` is the index in ``RECV_devices``, starting at 1. The ``ant_idx`` is the absolute index of the antenna in the ``RECV`` device. A value of ``-1`` means the antenna is not connected at all. + + :type: ``int32[]`` + :shape: ``int32[][2]`` + +:HBAT_Control_to_RECV_mapping: Pairs of numbers ``(recv_idx, ant_idx)`` describing the inputs on which the HBAT *control* is connected. The ``recv_idx`` is the index in ``RECV_devices``, starting at 1. The ``ant_idx`` is the absolute index of the antenna in the ``RECV`` device. A value of ``-1`` means the antenna is not connected at all. + +Positions +"""""""""""""""""""" + +The positions are given in ETRS, using the following properties: + +:HBAT_reference_ETRS: Reference position of each HBA tile, in ETRS (x/y/z, metres). + + :type: ``float64[N_tiles][3]`` + +:Antenna_Field_Reference_ETRS: Reference position of the antenna field, in ETRS (x/y/z, metres). + + :type: ``float64[3]`` + +:ITRF_Reference_Frame: Reference frame to use for converting ETRS to ITRF (f.e. "ITRF2005"). + + :type: ``str`` + +:ITRF_Reference_Epoch: Epoch towards which to extrapolate the ITRF frame, typically in half-year increments (f.e. 2015.5). + + :type: ``float32`` + +For the ETRS positions, there is an alternative to provide them using the respective ``ITRF`` property, which overrides the automatic ETRS-to-ITRF conversion. + +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.tilebeam.hba_tile`` for these computations. + +: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]`` + diff --git a/tangostationcontrol/docs/source/devices/digitalbeam.rst b/tangostationcontrol/docs/source/devices/digitalbeam.rst deleted file mode 100644 index 7f3624c7b72de285c1d4521e5c861fb992caa525..0000000000000000000000000000000000000000 --- a/tangostationcontrol/docs/source/devices/digitalbeam.rst +++ /dev/null @@ -1,4 +0,0 @@ -DigitalBeam --------------------- - -``digitalbeam == DeviceProxy("STAT/DigitalBeam/1")`` diff --git a/tangostationcontrol/docs/source/devices/tilebeam-digitalbeam.rst b/tangostationcontrol/docs/source/devices/tilebeam-digitalbeam.rst new file mode 100644 index 0000000000000000000000000000000000000000..6127918ec3567f0fc2fd52c15ee3b7a4780f5989 --- /dev/null +++ b/tangostationcontrol/docs/source/devices/tilebeam-digitalbeam.rst @@ -0,0 +1,141 @@ +TileBeam, DigitalBeam +------------------------ + +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 a *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. 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. + +The ``tilebeam == DeviceProxy("STAT/TileBeam/1")`` device configures the HBA beam former in each HBA tile, which adds the signals of its 16 elements within the tile. The output signal of these tiles is used as input for the digital beam former (just like the direct output of an LBA). + +The ``digitalbeam == DeviceProxy("STAT/DigitalBeam/1")`` device configures the digital beam formed in SDP from antenna or tile inputs. The output signal in SDP are *beamlets*, which can + +Both devices beamform the antennas configured in its associated ``AntennaField`` device, but differ in what they beamform and with respect to which position: + +- TileBeam: + + - Beamforms HBA elements in the HBA tiles of its AntennaField device, + - Uses ``antennafield.HBAT_Reference_ITRF_R`` as the reference position for each tile, + - Allows a different pointing per HBA tile, + - ``N_output := antennafield.nr_tiles_R``, + - Uploads the computed weights to ``antennafield.HBAT_bf_delay_steps_RW``, + - These weights are actually *delay steps* to be applied in the tile for each element. + +- DigitalBeam + + - Beamforms all the antennas or tiles of its AntennaField device, + - Uses ``antennafield.Antenna_Field_Reference_ITRF_R`` as the reference position, + - Allows a different pointing per beamlet, + - ``N_output := NUM_BEAMLETS = 488``, + - Uploads the computed weights to ``beamlet.FPGA_bf_weights_xx_yy_RW``, + - These weights are actually complex *phase rotations* to be applied on each antenna input. + +Common functionality +````````````````````` + +The following functionality holds for both TileBeam and DigitalBeam. + +Beam Tracking +""""""""""""""""""""""""""""""""" + +Beam tracking automatically recomputes and reapplies pointings periodically, and immediately when new pointings are configured. It exposes the following interface: + +:Tracking_enabled_R: Whether beam tracking is running. + + :type: ``bool`` + +: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_output][3]`` + +:Pointing_direction_R: The last applied pointing of each antenna. + + :type: ``str[N_output][3]`` + +: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_output][3]`` + +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 + +Beam Steering +""""""""""""""""""""""""""""""""" + +The beam steering is responsible for pointing the beams at a target, by converting the pointing to hardware-specific weights and uploading them to the corresponding device. The beam steering is typically controlled by the beam tracker. To point the antennas in any direction manually, you should disable beam tracking first: + +:Tracking_enabled_RW: Enable or disable beam tracking (default: ``True``). + + :type: ``bool`` + +:set_pointing(pointings): Point the beams towards the specified ``pointings[N_output][3]`` for all outputs. + + :returns: ``None`` + +Celestial and geographical models +""""""""""""""""""""""""""""""""" + +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 TileBeam 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)`` + +DigitalBeam +````````````````````` + +The DigitalBeam device applies the following configuration to compute each beamlet. Here, ``N_ant := antennafield.nr_tiles_R`` and ``N_beamlet := NUM_BEAMLETS == N_output``. + +:antenna_select_RW: Which beamlets to form with which antenna. ``True`` by default, except for antennas which are not mapped on any FPGA input (see "Configuration" below). + + :type: ``bool[N_ant][N_beamlet]`` + +:beamlet.subband_select_RW: Which subband to beamform for each beamlet. + + :type: ``uint32[N_beamlet]`` + +:sdp.clock_RW: Which clock to use (in Hz, default: 200e6). + + :type: ``uint32`` + +:sdp.antenna_type_R: Which antenna type is connected: "LBA" or "HBA". Configurable through the ``sdp.Antenna_Type`` property. + + :type: ``str`` + +:sdp.nyquist_zone_R: Relevant Nyquist zone (0, 1 or 2), based on the clock and antenna type. + + :type: ``uint32`` + +Configuration +""""""""""""""""""""" + +The following properties configure the DigitalBeam: + +:Input_to_Antenna_Mapping: Which antenna from the AntennaField is the input for each antenna input of the FPGAs. + + :type: ``uint32[96]`` + diff --git a/tangostationcontrol/docs/source/devices/tilebeam.rst b/tangostationcontrol/docs/source/devices/tilebeam.rst deleted file mode 100644 index dfa2372e56051b8f46be1079f3c2c89ec5f85f08..0000000000000000000000000000000000000000 --- a/tangostationcontrol/docs/source/devices/tilebeam.rst +++ /dev/null @@ -1,86 +0,0 @@ -TileBeam --------------------- - -The ``tilebeam == DeviceProxy("STAT/TileBeam/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. - -Beam Tracking -```````````````````` - -Beam tracking automatically recomputes and reapplies pointings periodically, and immediately when new pointings are configured. It exposes the following interface: - -:Tracking_enabled_R: Whether beam tracking is running. - - :type: ``bool`` - -: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]`` - -:Pointing_direction_R: The last applied pointing of each antenna. - - :type: ``str[N_ant][3]`` - -: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: - -:Tracking_enabled_RW: Enable or disable beam tracking (default: ``True``). - - :type: ``bool`` - -: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 TileBeam 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)`` diff --git a/tangostationcontrol/docs/source/index.rst b/tangostationcontrol/docs/source/index.rst index 886292357266985897bc187ed172f7c014f9d5ef..3ecc4c12ab9dbcbb2b81d97d04bc623d9f910b4a 100644 --- a/tangostationcontrol/docs/source/index.rst +++ b/tangostationcontrol/docs/source/index.rst @@ -20,16 +20,15 @@ Even without having access to any LOFAR2.0 hardware, you can install the full st interfaces/overview devices/overview devices/using - devices/tilebeam - devices/beamlet - devices/digitalbeam devices/antennafield - devices/boot - devices/docker - devices/psoc + devices/tilebeam-digitalbeam + devices/beamlet devices/recv devices/sdp devices/bst-sst-xst + devices/boot + devices/docker + devices/psoc devices/temperature-manager devices/configure configure_station