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).

_images/sdp_subarray_states.svg

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.

_images/sdp_subarray_interaction_tango.svg

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 command

  • releaseres - ReleaseResources command

  • configure - Configure command

  • scan - Scan command

  • recvaddrs - 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

Assigns resources to the subarray.

ReleaseResources

String (JSON)

None

Releases resources from the subarray.

ReleaseAllResources

None

None

Releases all resources assigned to the subarray.

Configure

String (JSON)

None

Configures scan type for the following scans.

Scan

String (JSON)

None

Begins a scan of the configured type.

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 ID

    • context - free-form information from OET defining the context of the observation

    • max_length - maximum length of the execution block in seconds

    • scan_types - scan types

    • beams - primary beams and tied-array beams

    • channels - frequency channels

    • polarisations - polarisation correlation products

    • fields - fields and pointing information

  • processing_blocks is a list of processing blocks, each one of which contains:

    • pb_id - processing block ID

    • script - the processing script: its kind (real-time or batch), name and version

    • parameters - optional parameters to pass to the script

    • sbi_ids - optional list of scheduling block instances to which the processing block belongs

    • dependencies - 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.

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

healthState

Enum

Read

Health state values

Subarray health state

adminMode

Enum

Read-write

Admin mode values

Subarray admin mode

obsState

Enum

Read

Observing state values

Subarray observing state

resources

String

Read

Resources values

Externally-managed resources assigned to subarray

ebID

String

Read

Execution block ID, or “null” if execution block is not assigned

receiveAddresses

String

Read

Receive addresses values

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

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

Admin mode values

The admin mode represents the intent with which the subarray will be used. Some admin mode values are not applicable to the subarray, but they are part of the control system model so they are listed here for completeness.

adminMode

Description

ONLINE (0)

Subarray can be used for normal operations

OFFLINE (1)

Subarray should not be monitored or controlled by the control system

MAINTENANCE (2)

Subarray can be used for maintenance purposes only

NOT_FITTED (3)

Subarray is not fitted and therefore cannot be used (not applicable)

RESERVED (4)

Subarray is reserved for redundancy purposes (not applicable)

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"]
      ]
    }
  }
}