SDP Subarray Device
Introduction
The SDP subarray Tango device is the principal means by which processing is initiated in the SDP.
State Model
The present implementation is shown in the diagram below. Here the state is the combination of the Tango device state and the observing state (obsState).
Behaviour
The interaction between the Telescope Monitoring and Control (TMC) subsystem and the SDP subarray device is shown below. The SDP subarray device receives commands from the TMC subarray device, and the consequent changes to the state of the SDP are reported in the device attributes.
Schemas
The arguments of the subarray commands and some of its attributes are strings
containing data in JSON format. The data are described by a schema which is
versioned to support evolution of the interfaces. The schema is specified with
the interface
keyword in the JSON string:
{
"interface": "https://schema.skao.int/ska-sdp-<interface>/<version>",
"...": "..."
}
where <interface>
identifies the command or attribute:
assignres
- AssignResources commandreleaseres
- ReleaseResources commandconfigure
- Configure commandscan
- Scan commandrecvaddrs
- receiveAddresses attribute
and <version>
is the version of the schema.
The JSON string can be validated against the schema using the telescope model library. Its documentation describes the versions of the schemas. The subarray device implements version 0.4 of the schemas, which is used in the examples below.
The commands will accept arguments in versions 0.2 and 0.3 of the schemas for
backwards compatibility. If a command argument does not have an interface
value, it defaults to version 0.2 (this was the last version before
interface
values were used routinely).
Commands
Command |
Argument type |
Return type |
Action |
---|---|---|---|
On |
None |
None |
Sets the device state to ON and the observing state to EMPTY. |
Off |
None |
None |
Sets the device state to OFF. |
AssignResources |
String (JSON) |
None |
|
ReleaseResources |
String (JSON) |
None |
|
ReleaseAllResources |
None |
None |
Releases all resources assigned to the subarray. |
Configure |
String (JSON) |
None |
|
Scan |
String (JSON) |
None |
|
EndScan |
None |
None |
Ends the scan. |
End |
None |
None |
Ends the execution block. |
Abort |
None |
None |
Aborts current activity. |
ObsReset |
None |
None |
Resets the subarray to the IDLE observing state. |
Restart |
None |
None |
Restarts the subarray in the EMPTY observing state. |
Transaction IDs
Commands that accept an argument will also accept an optional transaction ID. This is used in logging to enable tracing the execution of the commands. If the argument does not contain a transaction ID, then an internal one is generated for the command. This is also done for all commands that do not take an argument.
Example of a transaction ID:
{
"transaction_id": "txn-test-20220921-00000000",
"...": "..."
}
AssignResources
The argument of the AssignResources command describes externally-managed resources, an execution block (EB) and processing blocks (PBs) to be assigned to the subarray. The EB contains the information that is necessary for the SDP to:
receive visibility data from the correlator beam-former (CBF) and write data to one or more measurement sets;
provide calibration solutions for the CBF to form tied-array beams;
receive candidate and timing data from the pulsar search and timing subsystems.
The EB defines the scan types that can be selected by the Configure command.
Warning
The subarray will not accept the AssignResources command if an execution block is in progress (i.e. an EB has been assigned to the subarray and it has not yet been ended).
An example of the argument is below. Note that:
resources
defines the externally-managed resources that are assigned to the subarray.execution_block
is the execution block, which contains:eb_id
- execution block IDcontext
- free-form information from OET defining the context of the observationmax_length
- maximum length of the execution block in secondsscan_types
- scan typesbeams
- primary beams and tied-array beamschannels
- frequency channelspolarisations
- polarisation correlation productsfields
- fields and pointing information
processing_blocks
is a list of processing blocks, each one of which contains:pb_id
- processing block IDscript
- the processing script: its kind (real-time or batch), name and versionparameters
- optional parameters to pass to the scriptsbi_ids
- optional list of scheduling block instances to which the processing block belongsdependencies
- optional list of dependencies on other processing blocks (for batch processing blocks only)
{
"interface": "https://schema.skao.int/ska-sdp-assignres/0.4",
"resources": {
"receptors": ["SKA001", "SKA002", "SKA003", "SKA004"]
},
"execution_block" : {
"eb_id": "eb-test-20220921-00000",
"max_length": 21600.0,
"context": {},
"scan_types": [
{
"scan_type_id": ".default",
"beams": {
"vis0": {"channels_id": "vis_channels", "polarisations_id": "all"},
"pss1": {"field_id": "pss_field_0", "channels_id": "pulsar_channels", "polarisations_id": "all"},
"pss2": {"field_id": "pss_field_1", "channels_id": "pulsar_channels", "polarisations_id": "all"},
"pst1": {"field_id": "pst_field_0", "channels_id": "pulsar_channels", "polarisations_id": "all"},
"pst2": {"field_id": "pst_field_1", "channels_id": "pulsar_channels", "polarisations_id": "all"}
}
},
{
"scan_type_id": "target:a",
"derive_from": ".default",
"beams": {"vis0": {"field_id": "field_a"}}
}
],
"beams": [
{"beam_id": "vis0", "function": "visibilities"},
{"beam_id": "pss1", "search_beam_id": 1, "function": "pulsar search"},
{"beam_id": "pss2", "search_beam_id": 2, "function": "pulsar search"},
{"beam_id": "pst1", "timing_beam_id": 1, "function": "pulsar timing"},
{"beam_id": "pst2", "timing_beam_id": 2, "function": "pulsar timing"}
],
"channels": [
{
"channels_id": "vis_channels",
"spectral_windows": [
{
"spectral_window_id": "fsp_1_channels",
"count": 744, "start": 0, "stride": 2,
"freq_min": 350000000.0, "freq_max": 368000000.0,
"link_map": [[0, 0], [200, 1], [744, 2], [944, 3]]
},
{
"spectral_window_id": "fsp_2_channels",
"count": 744, "start": 2000, "stride": 1,
"freq_min": 360000000.0, "freq_max": 368000000.0,
"link_map": [[2000, 4], [2200, 5]]
},
{
"spectral_window_id": "zoom_window_1",
"count": 744, "start": 4000, "stride": 1,
"freq_min": 360000000.0, "freq_max": 361000000.0,
"link_map": [[4000, 6], [4200, 7]]
}
]
},
{
"channels_id": "pulsar_channels",
"spectral_windows": [
{
"spectral_window_id": "pulsar_fsp_channels",
"count": 744, "start": 0,
"freq_min": 350000000.0, "freq_max": 368000000.0
}
]
}
],
"polarisations": [
{
"polarisations_id": "all",
"corr_type": ["XX", "XY", "YY", "YX"]
}
],
"fields": [
{
"field_id": "field_a",
"phase_dir" : {
"ra": [123.0, 0.1],
"dec": [-60.0, 0.1],
"reference_time": "...",
"reference_frame": "ICRF3"
},
"pointing_fqdn": "low-tmc/telstate/0/pointing"
}
]
},
"processing_blocks": [
{
"pb_id": "pb-test-20220921-00000",
"script": {"kind": "realtime", "name": "test-receive-addresses", "version": "0.5.0"},
"parameters": {},
"sbi_ids": ["sbi-test-20220921-00000"]
},
{
"pb_id": "pb-test-20220921-00001",
"script": {"kind": "realtime", "name": "test-realtime", "version": "0.3.0"},
"parameters": {},
"sbi_ids": ["sbi-test-20220921-00000"]
},
{
"pb_id": "pb-test-20220921-00002",
"script": {"kind": "batch", "name": "test-batch", "version": "0.3.0"},
"parameters": {},
"sbi_ids": ["sbi-test-20220921-00000"],
"dependencies": [
{"pb_id": "pb-test-20220921-00000", "kind": ["visibilities"]}
]
}
]
}
ReleaseResources
The argument of the ReleaseResources command specifies which externally-managed resources to release from the subarray. The external resources are specified in the same format as in the AssignResources command.
Warning
The subarray will not accept the ReleaseResources command if an execution block is in progress (i.e. an EB has been assigned to the subarray and it has not yet been ended).
An example of the argument:
{
"interface": "https://schema.skao.int/ska-sdp-releaseres/0.4",
"resources": {
"receptors": ["SKA001", "SKA002", "SKA003", "SKA004"]
}
}
Configure
The argument of the Configure command specifies the type of the following scans from the values that were defined in the execution block.
Warning
The subarray will not accept the Configure command if there is no execution block in progress (i.e. an EB has not been assigned to the subarray).
An example of the argument:
{
"interface": "https://schema.skao.int/ska-sdp-configure/0.4",
"scan_type": "target:a"
}
The Configure schema has an optional new_scan_types
keyword, but that is
not supported by the current implementation of the subarray.
When executed, the obsState transitions to CONFIGURING
. It will only transition
to READY
once all of the deployments of every realtime processing block in
the executions block are up and running.
Scan
The argument of the Scan command specifies the scan ID.
An example of the argument:
{
"interface": "https://schema.skao.int/ska-sdp-scan/0.4",
"scan_id": 1
}
Attributes
Attribute |
Type |
Read/Write |
Values |
Description |
---|---|---|---|---|
version |
String |
Read |
Semantic version |
Subarray device server version |
adminMode |
Enum |
Read |
Subarray admin mode |
|
healthState |
Enum |
Read |
Subarray health state |
|
obsState |
Enum |
Read |
Subarray observing state |
|
resources |
String |
Read |
Externally-managed resources assigned to subarray |
|
ebID |
String |
Read |
Execution block ID, or “null” if execution block is not assigned |
|
receiveAddresses |
String |
Read |
Host addresses for receiving data |
|
scanType |
String |
Read |
Scan type, or “null” if scan type is not configured |
|
scanID |
Integer |
Read |
Scan ID, or 0 if not scanning |
Events
The SDP subarray device currently generates both Tango change events and archive events for the following attributes:
obsState
resources
ebID
receiveAddresses
scanType
scanID
A Tango client can subscribe to any of these events and can arrange to take appropriate action. An example of how a Python client can subscribe to archive events on the obsState attribute is:
d = DeviceProxy("test-sdp/subarray/01")
cb = tango.utils.EventCallback()
id = d.subscribe_event("obsState", tango.EventType.ARCHIVE_EVENT, cb)
Admin mode values
Admin mode is implemented as a read-only attribute, so it always returns the
value ONLINE
.
adminMode |
Description |
---|---|
ONLINE (0) |
Subarray can be used for normal operations |
Health state values
healthState |
Description |
---|---|
OK (0) |
Subarray is functioning as expected |
DEGRADED (1) |
Subarray can only provide some of its functionality |
FAILED (2) |
Subarray is unable to function |
UNKNOWN (3) |
Subarray device is unable to determine the health of the subarray |
Observing state values
obsState |
Description |
---|---|
EMPTY (0) |
No resources are assigned to the subarray |
RESOURCING (1) |
Resources are being assigned or released |
IDLE (2) |
Resources are assigned to the subarray |
CONFIGURING (3) |
Scan type is being configured |
READY (4) |
Scan type is configured and the subarray is ready to scan |
SCANNING (5) |
Scanning |
ABORTING (6) |
Current activity is being aborted |
ABORTED (7) |
Most recent activity has been aborted |
RESETTING (8) |
Resetting to IDLE observing state |
FAULT (9) |
A error has occurred in observing |
RESTARTING (10) |
Restarting to return to EMPTY observing state |
Resources values
The resources
attribute is a JSON-formatted string describing the
externally-managed resources assigned to the subarray. It has the same format
as the resources
value in the arguments of the
AssignResources and ReleaseResources
commands. If no resources are assigned to the subarray, the value is an empty
JSON object ({}
).
An example value:
{
"receptors": ["SKA001", "SKA002", "SKA003", "SKA004"]
}
Receive addresses values
The receiveAddresses
attribute is a JSON-formatted string containing the
host addresses to which data from the CSP subsystems (CBF and pulsar search and
timing) should be sent. It also contains the names of the SDP attributes that
provide the real-time calibration information to the rest of the system. The
data contains one entry per scan type, and each scan type contains one entry
per primary (visibility) beam or tied-array beam. If there are no receive
addresses associated with the subarray, the value is an empty JSON object
({}
).
An example value:
{
"interface": "https://schema.skao.int/ska-sdp-recvaddrs/0.4",
"target:a": {
"vis0": {
"host": [[0, "192.168.0.1"], [400, "192.168.0.2"], [744, "192.168.0.3"], [1144, "192.168.0.4"]],
"port": [[0, 9000, 1], [400, 9000, 1], [744, 9000, 1], [1144, 9000, 1]],
"delay_cal": [
[0, "low-sdp/telstate/rcal0/delay0"],
[400, "low-sdp/telstate/rcal0/delay1"],
[744, "low-sdp/telstate/rcal0/delay2"],
[1144, "low-sdp/telstate/rcal0/delay3"]
]
},
"pss1": {
"host": [[0, "192.168.60.0"]], "port": [[0, 8000]],
"jones_cal": [
[0, "low-sdp/telstate/rcal0/jones0"],
[400, "low-sdp/telstate/rcal0/jones1"],
[744, "low-sdp/telstate/rcal0/jones2"],
[1144, "low-sdp/telstate/rcal0/jones3"]
]
},
"pss2": {
"host": [[0, "192.168.60.0"]], "port": [[0, 8000]],
"jones_cal": [
[0, "low-sdp/telstate/rcal0/jones0"],
[400, "low-sdp/telstate/rcal0/jones1"],
[744, "low-sdp/telstate/rcal0/jones2"],
[1144, "low-sdp/telstate/rcal0/jones3"]
]
}
"pst1": {
"host": [[0, "192.168.60.0"]], "port": [[0, 8000]],
"jones_cal": [
[0, "low-sdp/telstate/rcal0/jones0"],
[400, "low-sdp/telstate/rcal0/jones1"],
[744, "low-sdp/telstate/rcal0/jones2"],
[1144, "low-sdp/telstate/rcal0/jones3"]
]
},
"pst2": {
"host": [[0, "192.168.60.0"]], "port": [[0, 8000]],
"jones_cal": [
[0, "low-sdp/telstate/rcal0/jones0"],
[400, "low-sdp/telstate/rcal0/jones1"],
[744, "low-sdp/telstate/rcal0/jones2"],
[1144, "low-sdp/telstate/rcal0/jones3"]
]
}
}
}