.. _`CentralNode commands`:

===============
TMC CentralNode
===============

Overview
========

Sub-array resource allocation is achieved via communication with a TMC
CentralNode device. The ``centralnode`` package models the JSON input and
responses for TMC CentralNode commands. The contents of this package are
shown in the figure below.

.. figure:: centralnode.png
   :align: center
   :alt: High-level overview of centralnode package

Classes in the `assign_resources.py`_ module model the arguments for the
``CentralNode.AssignResources()`` command.

Classes in the `release_resources.py`_ module model the arguments for the
``CentralNode.ReleaseResources()`` command.

assign_resources.py
===================

.. figure:: assignresources.png
   :align: center
   :alt: Overview of the assign_resources.py module

   assign_resources.py object model

The ``assign_resources.py`` module models the the JSON input and response
for a ``CentralNode.AssignResources()`` command.

Example v2.3 JSON input modelled by ``AssignResourcesRequest`` for MID:

.. code-block:: JSON

    {
    "interface": "https://schema.skao.int/ska-tmc-assignresources/2.3",
    "transaction_id": "txn-....-00001",
    "subarray_id": 1,
    "dish": {
        "receptor_ids": ["0001"]
    },
    "sdp": {
        "interface": "https://schema.skao.int/ska-sdp-assignres/1.0",
        "execution_block": {
            "eb_id": "eb-mvp01-20210623-00000",
            "max_length": 100.0,
            "context": {},
            "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"
            }, {
                "beam_id": "vlbi1",
                "vlbi_beam_id": 1,
                "function": "vlbi"
            }],
            "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"
                    },
                    "vlbi": {
                        "field_id": "vlbi_field",
                        "channels_id": "vlbi_channels",
                        "polarisations_id": "all"
                    }
                }
            }, {
                "scan_type_id": "target:a",
                "derive_from": ".default",
                "beams": {
                    "vis0": {
                        "field_id": "field_a"
                    }
                }
            }],
            "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": {
                    "target_name": "target_a",
                    "reference_frame": "icrs",
                    "attrs": {
                        "c1": 201.365,
                        "c2": -43.0191667
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_b",
                "phase_dir": {
                    "target_name": "Zenith",
                    "reference_frame": "altaz",
                    "attrs": {
                        "c1": 180.0,
                        "c2": 90.0
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_c",
                "phase_dir": {
                    "target_name": "Cass-A",
                    "reference_frame": "galactic",
                    "attrs": {
                        "c1": 111.734745,
                        "c2": -2.12957
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_d",
                "phase_dir": {
                    "target_name": "Sun",
                    "reference_frame": "special"
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_e",
                "phase_dir": {
                    "target_name": "ISS (ZARYA)",
                    "reference_frame": "tle",
                    "attrs": {
                        "line1": "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927",
                        "line2": "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }]
        },
        "processing_blocks": [{
            "pb_id": "pb-mvp01-20210623-00000",
            "sbi_ids": ["sbi-mvp01-20200325-00001"],
            "script": {
                "kind": "realtime",
                "name": "vis_receive",
                "version": "0.1.0"
            },
            "parameters": {
                "holography_receptor_groups": {
                    "group_1": ["SKA001", "SKA036", "SKA063"],
                    "group_2": ["SKA100"]
                }
            }
        }, {
            "pb_id": "pb-mvp01-20210623-00001",
            "sbi_ids": ["sbi-mvp01-20200325-00001"],
            "script": {
                "kind": "realtime",
                "name": "test_realtime",
                "version": "0.1.0"
            },
            "parameters": {}
        }, {
            "pb_id": "pb-mvp01-20210623-00002",
            "sbi_ids": ["sbi-mvp01-20200325-00002"],
            "script": {
                "kind": "batch",
                "name": "ical",
                "version": "0.1.0"
            },
            "parameters": {},
            "dependencies": [{
                "pb_id": "pb-mvp01-20210623-00000",
                "kind": ["visibilities"]
            }]
        }, {
            "pb_id": "pb-mvp01-20210623-00003",
            "sbi_ids": ["sbi-mvp01-20200325-00001", "sbi-mvp01-20200325-00002"],
            "script": {
                "kind": "batch",
                "name": "dpreb",
                "version": "0.1.0"
            },
            "parameters": {},
            "dependencies": [{
                "pb_id": "pb-mvp01-20210623-00002",
                "kind": ["calibration"]
            }]
        }],
        "resources": {
            "receptors": ["SKA001", "SKA036", "SKA063", "SKA100"]
        }
    },
    "telmodel": {
        "source_uris": ["car://gitlab.com/ska-telescope/ska-mid?main#tmdata"],
        "array_layout_path": "instrument/ska1_mid_aa/layout/mid-layout.json"
    }
    }

Example JSON response modelled by ``AssignResourcesResponse`` for MID:

.. code-block:: JSON

  {
    "dish": {
      "receptor_ids_allocated": ["0001", "0002"]
    }
  }

Example of JSON v4.3 input modelled by ``AssignResourcesRequest`` for LOW:

.. code-block:: JSON

   {
    "interface": "https://schema.skao.int/ska-low-tmc-assignresources/4.3",
    "transaction_id": "txn-....-00001",
    "subarray_id": 1,
    "mccs": {
        "interface": "https://schema.skao.int/ska-low-mccs-controller-allocate/3.0",
        "subarray_beams": [{
            "subarray_beam_id": 1,
            "apertures": [{
                "station_id": 1,
                "aperture_id": "AP001.01"
            }, {
                "station_id": 1,
                "aperture_id": "AP001.02"
            }, {
                "station_id": 2,
                "aperture_id": "AP002.01"
            }, {
                "station_id": 2,
                "aperture_id": "AP002.02"
            }],
            "number_of_channels": 8
        }]
    },
    "csp": {
        "pss": {
            "pss_beam_ids": [1, 2, 3]
        },
        "pst": {
            "pst_beam_ids": [1]
        }
    },
    "sdp": {
        "interface": "https://schema.skao.int/ska-sdp-assignres/1.0",
        "resources": {
            "receptors": ["C4", "C57", "C108", "C165", "C193", "C200", "S8-1", "S8-2", "S9-1", "S9-5", "S10-1", "S10-6", "S16-3", "S16-4", "S16-6"]
        },
        "execution_block": {
            "eb_id": "eb-test-20220916-00000",
            "context": {},
            "max_length": 3600.0,
            "beams": [{
                "beam_id": "vis0",
                "function": "visibilities"
            }],
            "scan_types": [{
                "scan_type_id": ".default",
                "beams": {
                    "vis0": {
                        "channels_id": "vis_channels",
                        "polarisations_id": "all"
                    }
                }
            }, {
                "scan_type_id": "target:a",
                "derive_from": ".default",
                "beams": {
                    "vis0": {
                        "field_id": "field_a"
                    }
                }
            }, {
                "scan_type_id": "calibration:b",
                "derive_from": ".default",
                "beams": {
                    "vis0": {
                        "field_id": "field_b"
                    }
                }
            }],
            "channels": [{
                "channels_id": "vis_channels",
                "spectral_windows": [{
                    "spectral_window_id": "fsp_1_channels",
                    "count": 4,
                    "start": 0,
                    "stride": 2,
                    "freq_min": 350000000.0,
                    "freq_max": 368000000.0,
                    "link_map": [
                        [0, 0],
                        [200, 1],
                        [744, 2],
                        [944, 3]
                    ]
                }]
            }],
            "polarisations": [{
                "polarisations_id": "all",
                "corr_type": ["XX", "XY", "YX", "YY"]
            }],
            "fields": [{
                "field_id": "field_a",
                "phase_dir": {
                    "target_name": "target_a",
                    "reference_frame": "icrs",
                    "attrs": {
                        "c1": 201.365,
                        "c2": -43.0191667
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_b",
                "phase_dir": {
                    "target_name": "Zenith",
                    "reference_frame": "altaz",
                    "attrs": {
                        "c1": 180.0,
                        "c2": 90.0
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_c",
                "phase_dir": {
                    "target_name": "Cass-A",
                    "reference_frame": "galactic",
                    "attrs": {
                        "c1": 111.734745,
                        "c2": -2.12957
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_d",
                "phase_dir": {
                    "target_name": "Sun",
                    "reference_frame": "special"
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }, {
                "field_id": "field_e",
                "phase_dir": {
                    "target_name": "ISS (ZARYA)",
                    "reference_frame": "tle",
                    "attrs": {
                        "line1": "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927",
                        "line2": "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
                    }
                },
                "pointing_fqdn": "low-tmc/telstate/0/pointing"
            }]
        },
        "processing_blocks": [{
            "pb_id": "pb-test-20220916-00000",
            "script": {
                "kind": "realtime",
                "name": "test-receive-addresses",
                "version": "0.7.1"
            },
            "sbi_ids": ["sbi-mvp01-20210623-00000"],
            "parameters": {}
        }]
    },
    "telmodel": {
        "source_uris": "gitlab://gitlab.com/ska-telescope/ska-low-tmdata?main#tmdata",
        "array_layout_path": "instrument/ska1_low/layout/low-layout.json"
    }
    }

release_resources.py
====================

.. figure:: releaseresources.png
   :align: center
   :alt: Overview of the release_resources.py module

   release_resources.py object model

The ``release_resources.py`` module models the input JSON for a
``CentralNode.ReleaseResources()`` command.

Example ReleaseResourcesRequest JSON that requests specific dishes be released
from a sub-array:

.. code-block:: JSON

  {
    "interface": "https://schema.skao.int/ska-tmc-releaseresources/2.1",
    "transaction_id": "txn-mvp01-20200325-00001",
    "subarray_id": 1, 
    "receptor_ids": ["0001", "0002"]
  }

Example JSON that requests all sub-array resources be released:

.. code-block:: JSON

  {
    "interface": "https://schema.skao.int/ska-tmc-releaseresources/2.1",
    "transaction_id": "txn-mvp01-20200325-00001",
    "subarray_id": 1,
    "release_all": true
  }

Example JSON that requests all sub-array resources be released for LOW:

.. code-block:: JSON

  {
    "interface": "https://schema.skao.int/ska-low-tmc-releaseresources/3.0",
    "subarray_id": 1,
    "release_all": true,
    "transaction_id": "txn-....-00001"
  }