3.1   Selecting the Default Configuration¶

In the high majority of cases, users will want to load the default configuration. The default configuration consists of parameters in the _init.yaml file and subsequently the _<site>.yaml, if it is present. These files are loaded automatically when performing state transitions using salobj or any higher-level software.

In most cases, the control packages contain high-level commands to enable all components under their control. An example of this is the ATCS. The following example enables all ATCS controlled components using their default configurations.

from lsst.ts.observatory.control import ATCS

atcs = ATCS()

await atcs.start_task

await atcs.enable()

If working with an individual CSC, which should be a special case, default CSC configurations are loaded by directly transitioning the CSC via:

from lsst.ts import salobj

domain = salobj.Domain()

atdome = salobj.Remote(domain, "ATDome")

await atdome.start_task()

# CSC needs to be in STANDBY state for this to work
await salobj.set_summary_state(atdome, salobj.State.ENABLED)

If these types of tasks are performed from the LOVE interface, then the same result occurs where the defaults are loaded automatically.

3.2   Discovering Available Override Configurations¶

The easiest way to get information from a CSC programmatically is by using a Jupyter notebook server. From a notebook, observers, developers and power users can easily interact with the system through Python.

In order to know which configurations are available for a specific CSC, users can read the configurationsAvailable event. This is done using a salobj.Remote class.

from lsst.ts import salobj

domain = salobj.Domain()

atdome = salobj.Remote(domain, "ATDome")

await atdome.start_task()

config_available = await atdome.evt_configurationsAvailable.aget(timeout=5.)

# This will print the available filenames.
print(config_available.configurations)

# This will print the git hash of the loaded configuration repository
print(config_available.version)

Often, this can also be accomplished using a high-level class that is designed to interact with a group of CSCs.

from lsst.ts.observatory.control import ATCS

atcs = ATCS()

await atcs.start_task

config_available = await atcs.rem.atdome.evt_configurationsAvailable.aget(timeout=5.)

# This will print the available filenames.
print(config_available.configurations)

# This will print the git hash of the loaded configuration repository
print(config_available.version)

It is also possible to check this information by querying the EFD or through the CSC summary information interface on LOVE. Examples of how to do this using the LOVE interface will be added when the functionality is ready.

3.3   Selecting an Override Configuration¶

Selecting non-default configurations via control packages is also possible. These are generally used for circumstances where customization is required, or a fallback from standard functionality is necessary. For example, if the look-up tables in the default configuration for the ATAOS are causing problems, then we can use this procedure to override the defaults by specifying a configuration file that contains the values from the previous look-up table.

When enabling components using the ATCS class, a dictionary is used to provide the appropriate configuration override files for each component that needs a non-default configuration. This example assumes the component of interest is already in the STANDBY state.

from lsst.ts.observatory.control import ATCS

atcs = ATCS()

await atcs.start_task

# ATAOS must be in STANDBY state for this to work. All other CSCs will
# use their default configurations
await atcs.enable(configurationOverride={'ATAOS': 'summit_constant_hex.yaml'})

Examples of how to do this using the LOVE interface will be added soon.

If working with an individual CSC, which should be a special case, the salobj.Remotes class may be more appropriate:

from lsst.ts import salobj

d = salobj.Domain()

atdome = salobj.Remote(d, "ATDome")

await atdome.start_task()

await salobj.set_summary_state(
atdome, salobj.State.ENABLED, configurationOverride="simple_algorithm.yaml"
)

4.1   Exceptions¶

TBR.

4.2   Finding and Using a Previously Used Configuration¶

In the future, one may want to verify which configuration was being used for a given observation and possibly load the exact same configuration. Because we often use generic filenames (e.g. simple_algorithm.yaml), and file contents can change with time, creating a robust version controlled system must go beyond simply changing filenames. For this reason, additional metadata is associated with each configuration, notably the url and version parameters in both the configurationsAvailable and configurationApplied events. These parameters are key to ensuring that each configuration is unique, and is traceable to their filename and contents.

The url parameter simply contains a URL indicating how the CSC connects to its settings (meaning a link to the repository). The version parameter is more complicated. For all CSCs (except possibly the cameras), the version parameter is a branch description[1] which is automatically generated and populated by the CSCs. This is what is output by running the following command in a configuration repository (e.g. ts_config_latiss):

git describe --all --long --always --dirty --broken

An example output is, heads/develop-0-gc89ef1a. The repository branch (or tag) name forms the first part of the branch description. This first part contain individual identifiers and can change rapidly. It may take any form necessary to convey the appropriate information. The last 7 characters (c89ef1a) is the hash of the commit of repository, so all configuration files in that repo correspond to the same hash. Users can find this commit by navigating to the repository on github, searching for the commit hash, then clicking on the “commits” section of the search results, as shown in the screenshot below.

Figure 1 Using the version output in the configurationApplied event, it is possible to traceback the repo to the configuration that was loaded.

Once we have identified the hash of the commit file we want to reload, we can do that without having to make any changes to the currently deployed ts_config package. If we simply want to use the default site-specific configuration for a given CSC, we can specify the commit hash with a preceding colon (:) as follows:

from lsst.ts.observatory.control import ATCS

atcs = ATCS()

await atcs.start_task

# ATAOS must be in STANDBY state for this to work. All other CSCs will
# use their default configurations
await atcs.enable(configurationOverride={'ATAOS': ':c89ef1a'})

If we also want to specify an override file then we insert the filename before the colon (:) as shown below:

await atcs.enable(configurationOverride={'ATAOS': 'simple_algorithm.yaml:c89ef1a'})

4.3   On-the-Fly Configuration Changes¶

During the process of creating a new configuration (4   Modifying or Creating a New Configuration) or during a commissioning/engineering run, it may be necessary to make a new configuration available to a running CSC for testing without rebuilding/re-deploying the component. In these cases, the user should also create a Jira ticket (or work out of an existing ticket) to document the occurrence.

Following are the steps to make a new configuration available to a running CSC:

1. If the configuration is not already created and pushed to GitHub, follow steps 1 to 8 in 4   Modifying or Creating a New Configuration.

2. Create an annotated tag alpha tag following semantic versioning. The tag must be created to ensure the heritage is not lost in a forced commit to the branch

   git tag -a v1.4.0.alpha.1 -m "Updated focus values based on on-sky tests"
   

3. Make sure the CSC in in STANDBY state, which can be accomplished using the following command.

   await salobj.set_summary_state(ataos, salobj.State.STANDBY)
   

4. Login to the where the CSC is running. The procedure will vary depending on how the CSC is deployed. Most Telescope and Site components are deployed on containers using Kubernetes (k8s). For CSCs that are not running on a container, you should be able to login to the host machine with ssh and continue with the procedure (go to step 3). A provisional list of IPs can be found in confluence <https://confluence.lsstcorp.org/x/qw6SBg>. For details about the deployment system see the deployment documentation.

   The procedure to access containerized components is as follows:

   1. Log in to the rancher service at https://rancher.ls.lsst.org. You will need special authorization to acquire an account on that service.

      Warning

      This service is responsible for managing the deployment of the entire system. Make sure you follow the procedure exactly. If you are in doubt about an operation make sure you verify it with knowledgeable personnel.

   2. Once logged in, you will be presented with the list of available k8s clusters.

      

      Figure 2 List of Kubernetes clusters. At the time of this writing, the only cluster available was kueyen, the commissioning cluster at the base facility in Chile.

      Click on the name of the cluster where the CSC you want to modify is running. If it is a summit operation, the name of the cluster will be andes. After selecting the cluster, you will be redirected to the cluster dashboard.

      

      Figure 3 Cluster dashboard.

   3. On the top right corner of the cluster dashboard, there is a button with Launch kubectl. This will open an interactive session on you browser that will allow you to interact with the k8s cluster you selected. If you are knowledgeable about k8s you can also download the Kubeconfig file and login to the cluster from your own computer.

      Warning

      Do not download the Kubeconfig file unless you really know what you are doing. This file contains access and credential information that would allow users direct access to the k8s cluster.

   4. Once you select Launch kubectl you will be redirected to a Shell connected directly to the selected k8s cluster.

      

      Figure 4 Kubectl shell.

   5. Use the following command to discover the container running the CSC :

      kubectl get pods -n cscs
      

      This will list all the CSCs “pods” which are, basically, the running containers. The name of the CSC will be part of the pod name and should be easy to identify.

   6. Connect to the running pod:

      kubectl exec -it -n cscs <pod-name> -- /bin/bash
      

      Make sure to replace <pod-name> with the name of the pod for that CSC.

5. Once inside the CSC host, go to the location where the configuration is installed. This information can be found in the CSC documentation or in the deployment documentation. You should be able to use regular linux command line commands (e.g. ls and cd).

6. Once in the cloned configuration package, update the git repository and checkout the tag with the new configuration:

   git fetch --all
   git checkout tags/v1.4.0.alpha.1
   

   You should see the new tag be pulled and git will tell you that you’ve changed tags/branches.

7. Now re-enable the component to load the new configuration.

   If the _init.yaml or _<site>.yaml file was modified then use the following:

   await salobj.set_summary_state(ataos, salobj.State.ENABLED)
   

   If an override configuration was modified/added, then you must specify it using the configurationOverride keyword

   await salobj.set_summary_state(ataos, salobj.State.ENABLED, configurationOverride='summit_constant_hex')
   

The version attribute in the configurationsAvailable event would reflect that change with something like:

version: heads/tags/v1.4.0.alpha.1-g79e2257

Note that it would be possible to track the configuration in the future by using the commit hash (g79e2257).

4.4   In-line changes¶

During commissioning, we anticipate that there will be situations where quick configuration changes need to be implemented and tested. In these cases, working out of a local branch and going over the 4.3   On-the-Fly Configuration Changes process may result in the loss of on-sky time. To ensure the work/changes is tracked it is still recommended that the user create a Jira ticket (or work out of an existing ticket) to document the occurrence. Then, instead of checking out the repository locally, the user can work out of the deployed CSC configuration directly in the host.

To do this, perform the following procedure:

1. Verify (or transition) the CSC in in STANDBY state.

   await salobj.set_summary_state(ataos, salobj.State.STANDBY)
   

2. Login to the where the CSC is running. The procedure will vary depending on how the CSC is deployed. For containerized components, you can find details on how to do that in the deployment documentation.

3. Once inside the CSC host, go to the location where the configuration is installed. This information can be found in the CSC documentation or in the deployment documentation.

4. Create a local branch to work on that corresponds to the Jira ticket mentioned above.

   git checkout tickets/DM-12345
   

5. Use the available text editors (vim and emacs are usually made available) to edit the configurations.

6. Once the configurations are edited and saved, re-enable the component.

   await salobj.set_summary_state(ataos, salobj.State.ENABLED)
   

Transient filenames with Jira ticket numbers may be used for developing new configurations. They should be moved to a more purpose-oriented filename at the earliest opportunity.

As stated in the warning above, these changes cannot be pushed from inside a component and therefore the changes made will result in a loss of information and traceability. When you connect to the computer running a CSC and edit the configuration directly, the version parameter reflects that change with something like:

version: heads/tickets/DM-12345-0-g79e2257-dirty

When this happens, it prevents us from precisely identifying what configuration was used. In this case, the preferred solution is to use 4.3   On-the-Fly Configuration Changes to ensure traceability is not lost, at the expense of a couple extra minutes.

4.5   Exceptions¶

The following require different procedures to create/modify a configuration

• Main and Auxiliary Telescope Pointing Components
• ATMCS and ATPneumatics

5.1   Pointing Component¶

The pointing component has a configuration file that resides with the code base which, in itself, also defines a couple different files (e.g. pointing model). Nevertheless, the CSC is not developed to be a configurable CSC, meaning it does not accept a configurationOverride value to switch between different configurations and does not output the required events.

The CSC is being developed by Observatory Sciences using C++.

5.2   ATMCS and ATPneumatics¶

5.3   Non-Configurable CSCs¶

Some CSCs will not be configurable at all. Examples are sparse in our current architecture but, the from Salobj point of view, a CSC can be developed on top of a BaseCSC which makes it a non-configurable component. Non-configurable CSCs will have no data in the configuration column of the Master CSC Table.

A non-configurable CSC will ignore the configurationOverride parameter of the start command, as it has no meaning. Likewise these CSCs will not output any of the configuration-related events.

References