SKA Telescope Model

https://readthedocs.org/projects/telescope-model/badge/?version=latestDocumentation Status https://gitlab.com/ska-telescope/telescope-model/badges/master/pipeline.svgpipeline status https://gitlab.com/ska-telescope/telescope-model/badges/master/coverage.svgcoverage report

Repository for handling SKA Telescope Model information. This is a key component of the SKA architecture, centralising knowledge required to reason about the telescope as a whole.

Scope

Requirement SKA1-SYS_REQ-2645 defines the telescope model as follows: “A dynamic computational model of the Telescope shall be used to answer all queries about the state of the Telescope. The telescope model shall consist of configuration information, numerical models, empirical parameters, and conventions”.

The particular “queries” we are concerned with here are where SKA sub-systems need to agree with one another about information - such as SDP and dishes agreeing about the beam shape, or CSP and TMC agreeing about the make-up of the correlator and its connections to links. In these cases this information evolves very slowly, and therefore it is not appropriate for the two sides to agree dynamically - instead the telescope model is used as a shared source of truth.

Development

The Telescope Model is developed jointly by all teams working on the SKA telescope. To make this work, all changes will have to be tested thoroughly and pass a code review via merge request.

Testing should ensure that all code paths are checked, i.e. we want to reach 100% coverage. We also aim to minimise regressions of any kind. This means that most code and data should be versioned within the Telescope Model, with old behaviour staying supported until a sufficient depreciation period has passed.

Adding a new schema (version)

To add a new interface, you will have to adjust a number of places in the library. For a new SKA interface <interface> with <elem> as the leading sub-system, do the following steps:

  1. Add

    <ELEM>_<INTERFACE>_PREFIX = "https://schema.skao.int/ska-<elem>-<interface>/"`
    

    to src/ska_telmodel/<elem>/version.py. This is the interface namespace URI.

  2. Add a get_<elem>_<interface>_schema(version :str, strict :bool) function to src/ska_telmodel/<elem>/schema.py, returning an apppropriate Schema object. This is the main schema definition. Please add documentation as far as possible, this will be put both into the JSON schema as well as the documentation.

  3. Adjust schema_by_uri in src/ska_telmodel/schema.py to call get_<elem>_<interface>_schema for schemas starting with <ELEM>_<INTERFACE>_PREFIX so that your schema can be found.

  4. Add a documentation file docs/src/ska_<elem>_<interface>.rst with a line along the lines of

    .. ska-schema:: https://schema.skao.int/ska-<elem>-<interface>/<ver>
    

    to ensure documentation is generated

  5. Add a test in test_<elem>_schemas.py to ensure test coverage. This is especially easy if you add an example to the schema (see next sub-section).

If you just want to add new schema version, skip steps (1) and (3) and extend existing definitions in the remaining steps.

Adding a new example

It is a good idea to always provide an up-to-date example for every schema version. Assuming the schema is defined, the steps are fairly similar:

  1. Add a get_<elem>_<interface>_example(version :str) function to src/ska_telmodel/<elem>/schema.py, returning an dict. If you have multiple examples, you can add a str parameter to select the appropriate one.

  2. Adjust example_by_uri in src/ska_telmodel/schema.py to call get_<elem>_<interface>_example for schemas starting with <ELEM>_<INTERFACE>_PREFIX so that your example can be found.

  3. Add your example to docs/src/ska_<elem>_<interface>.rst by adding a line like

    .. ska-schema-example:: https://schema.skao.int/ska-<elem>-<interface>/<ver>
    

    inside the .. ska-schema block of the appropriate version

Code Style

This project uses the Black Code Formatter. To ensure that all code is formatted as required, run the following before you commit:

$ sh script/blackify.sh