.. vim: syntax=rst Low.CBF Subarray Capabilities ============================= Subarray Capabilities consist of stations, timing beams, search beams, standard visibilities and zoom visibilities. Once a subarray has been assigned FSP resources it has the ability to reserve and use the capabilities of the resources to compute visibilities or beams and route data from SPS and to SDP, PSS or PST servers. How Subarrays configure capabilities for Scan -------------------------------------------- When a Subarray initially acquires resources, it gains access to hardware but does not yet have any of the capabilities of the hardware reserved for its use during a scan. LMC invokes the subarray **Configure** command in order to reserve capabilities for use by a particular subarray during a scan. The subarray will retain the capabilities until the scan or run of scans is complete. When scans are complete, LMC will use the subarray **End** command to release the capabilities and allow them to be accessed by other subarrays. The argument passed to the subarray Configure command is a JSON string containing sections that describe separate parts of the configuration. In overview, the Configure argument has the form .. code-block:: python subarray_cfg = { "id": 1, # config ID (required by ska-tango-base) "lowcbf": { "stations": {}, # Station parameters (input) "vis": {}, # Visibility parameters (output1) "timing_beams": {}, # Timing beam parameters (output2) "search_beams": {}, # Search beam parameters (output3) "coarse_zooms": {}, # Zoom parameter (output4) } } The following paragraphs describe the sections in the code outlined above for information only. Telmodel contains the reference. Describing Station data input configuration for Low.CBF (stations) ------------------------------------------------------------------------ The "stations" section of the JSON above describes the parameters specifying each station from which the subarray should receive SPEAD data. The parameters must be sufficient to allow the routing of SPEAD packets from SPS to a FPGA card. The five parameters required for this are: station_id, substation_id, subarray_id, station_beam_id, frequency_id. The parameter values must match those in the SPEAD header of the data packets. Since the subarray device already knows its own subarray_id, it need not be provided as a parameter to the Configure command. We expect a subarray should have one set of (sub-)stations that contribute to every one of its station beams, and a station beam should receive the same set of frequency channels from each (sub-)station. We can use a list of (sub-)stationIDs to describe the stations that contribute to the subarray, and lists of frequencyIDs to describe the station beams that are part of the subarray, as shown in the diagram. There will also be a boresight delay polynomial associated with each station beam that can be included with each station beam. .. image:: images/subarray-config-params.png The stations section describing the input configuration is expressed in the form: .. code-block:: python stations = { "stns": [ [1,1], [2,1], [3,1], [4,1], [5,1], [6,1] ], # (station, substation) tuples "stn_beams": [ # list of subarray's station-beams and their parameters { "beam_id": 1, "freq_ids": [ 400, ], "delay_poly": "url" }, ] } Describing standard Visibility output configuration for Low.CBF (vis) ---------------------------------------------------------------------------- Standard visibility parameters use the host/port/mac address formats generated by SDP and are described in the following form: .. code-block:: python vis = { # Optional firmware specification (see note under Low CBF FPGA Firmware) "firmware": "https://example.com/ska-low-cbf-fw-corr.tgz", "sps_rfi_threshold_db": -60.0, # Optional SPS flagging (see telmodel description) "stn_beams": [ { "stn_beam_id": 1, "host": [ [0, "192.168.1.10"], ], "port": [ [0, 9000, 1], ], "mac": [ [0," 02-03-04-0a-0b-0c"] ], "integration_ms": 849 } ] } Describing Zoom Visibility output configuration for Low.CBF (coarse_zooms) ---------------------------------------------------------------------------- Currently Low.CBF only supports Zoom visibilities with resolution of 257Hz or greater. Zoom visibilities are computed by the same firmware as standard visibilities. Not all resolution, centre frequency and bandwidth that are requested in a zoom configuration are possible because of FPGA constraints. The fundamental limits are: - minimum zoom resolution is: SPS channel spacing / 3456 (i.e. 225.056 Hz) - zoom resolution is always a sub-multiple of SPS channel spacing (i.e. of 781250.0 Hz) To simplify specification of zooms, an approximate specification will be adjusted: - The zoom resolution in a subarray config request is adjusted downward to the nearest supported value - The zoom bandwidth in a subarray config request is adjusted upward to the minimum possible bandwidth that contains the requested bandwidth - The centre frequency will be modified to conform to the resolution and bandwidth changes The subarray logs the requested parameters and the exact parameters implemented Parameters for Zoom visibilities are described in a dictionary with the following form: .. code-block:: python coarse_zooms = { # Optional firmware specification (see note under Low CBF FPGA Firmware) # Zoom visibilities use the same firmware as standard visibilities "firmware": "https://example.com/ska-low-cbf-fw-corr.tgz", "sps_rfi_threshold_db": -60.0, # Optional SPS flagging (see telmodel description) "stn_beams": [ { "stn_beam_id": 1, "zoom_window_id": 23, "zoom_resolution_hz": 455 "centre_frequency_hz": 77_735_875, "zoom_bandwidth_hz": 2_400, "integration_ms": 849 "host": [ [0, "192.168.1.10"], ], "port": [ [0, 9000, 1], ], } ] } Describing Timing Beam output configuration for Low.CBF (timing_beams) ---------------------------------------------------------------------- The timing beam parameters use the PST channel blocks format to describe the PST destination hosts. Timing beams can be expressed in the form: .. code-block:: python timing_beams = { # Optional firmware specification (see note under Low CBF FPGA Firmware) "firmware": "https://example.com/ska-low-cbf-fw-pst.tgz", "sps_rfi_threshold_db": -60.0, # Optional SPS flagging (see telmodel description) "beams": [ { "pst_beam_id": 1, "stn_beam_id": 1, "delay_poly": "tango://fqdn.device", "jones": "tango://fqdn/device", "destinations": [ { "data_host": "10.0.3.2", "data_port": 9000, "start_channel": 0, "num_channels": 24 }, "stn_weights": [1.0, 0.0], ] } ] } The "stn_weights" list is expected to have one entry for each of the stations in the subarray. The first weight is applied to the first station in the stations section of the config above, the second weight to the second station, etc. If there are more weights than stations, the excess weights at the end of the list will be ignored. If there are fewer weights than stations, the final weight value will be used for the remaining stations. Describing Search Beam output configuration for Low.CBF (search_beams) ---------------------------------------------------------------------- Search beams are currently written in the same form as Timing beams with "pst" changed to "pss". The description becomes bulky when the 501 possible search beams are all configured. If a more compact description can be agreed, the format may change and be different to Timing beams. Low CBF FPGA Firmware --------------------- .. note:: We discourage the use of the optional "firmware" field, as it will only work on the u55c FPGA, not the V80. Use of the Low CBF Processor's `firmware_default_versions` setting is recommended over specifying firmware in the Subarray Configure command. See the ska-low-cbf-proc Helm chart & values file for details. The active values are available as a Tango property on the Low CBF Processor device. When using the V80 FPGA, firmware images must be pre-loaded into the FPGA card's flash memory. This is a slow operation (15+ minutes), so it will not be performed at Subarray Configure-time. The Processor's `FirmwareDownload` command can be used to program the flash memory. The firmware version requested (by either the default setting or in the Configure command) must match the version in V80 flash memory. Subarray checks made on configure parameters -------------------------------------------- The schema used to check the Configure parameters is: .. literalinclude:: ../../src/ska_low_cbf/subarray/subarray.py :start-at: configure_scan_schema :end-before: """ Subarray environment variables ------------------------------ Subarrays will by default wait for all the processor devices that they are using to be ready to produce output, with a default timeout of 60 seconds. The number of devices that need to be ready can be adjusted by the subarray PROCESSOR_WAIT_QTY environment variable. Values can be: - ALL (wait for all processors used by the subarray to be ready) - NONE (do not wait for processors to be ready. Subarray obsstate will change to READY and scans can be started immediately. Scan output data will flow as processors become ready) - ONE (wait for just one of the processors to be ready) - NN (wait for NN percent of the processors used by subarray to be ready) The wait timeout can be adjusted by the PROCESSOR_WAIT_SECS environment variable