Quick guide to MCS

Introduction

This document walks through MCS’s basic GUI features and how to setup the software to start running an observation.

Instrument description

From the point of view of the control system, the instrument has the next main devices:

  1. CCD Camera: FLI HYPERION HP1001, CCD 1024x1024

  2. Filter Wheel: FLI CFW2-7

  3. Temperature Controller: Industruino PROTO D21G

  4. Power Controller: GUDE-Expert Power Control 8210

  5. Dome Temperature/Humidity sensor: TH2E

Next figure show an overview of these elements and their interfaces:

../_images/mima_cs_arch.png

MIMA control system architecture

  • The shutter is controlled automatically by the internal CCD camera controller, so the MCS has nothing to manage about it.

  • The first version of the instrument will not include a specific device for taking Flat-fields as shown in the figure above (Flat-Field Controller), but flat-fields will be taken regularly at the dusk and dawn with no spectial device.

Starting-up

The quick procedure to start an observation is as follow:

  1. Connect to the control workstation (local o remote)

  2. Launch the MCS application (if not already running)

  3. Define the observing Campaign

  4. Set Automatic mode in MCS

Note

MIMA computer is configured to autostart MCS application after the system boot, so in it MCS should already be running in the user console.

Remote Desktop Access

Most of the times, you will operate the instrument remotely, i.e., you are not in front of the MIMA control workstation, but in the user workstation (Linux and MacOS prefered). Because the MIMA control is done through a graphical interface (GUI), you need to connect to the remote (and shared) desktop of the control workstation.

Thus, to go from your desktop to MIMA desktop, we use the remote desktop tool NoMachine. The support staff will tell you which account you can use and the corresponding password for this account.

Note

If you are in front of the control workstation, you do not need you use the remote NoMachine desktop tool, but only do a normal login into the local computer.

After login on the remote desktop, you can open a X-Terminal and type mcs or click on the MCS desktop icon. After a few seconds you should see the main window of MCS which looks like shown in the next figure below:

../_images/main_gui.png

MCS Main Tab panel

Running modes

MCS has two running modes, Manual and Automatic. By default, the MCS application starts in Automatic mode, what means that will run the next campaign scheduled that meet the observation constraints. In Manual mode, no campaign will be executued, but the user could take single expositions setting the main parameters like: filter, expositon time, repetitions, read mode, binning and imagetype (light or dark).

../_images/main_tab_auto.png

Main Tab panel with Automatic mode enabled

In Automatic mode manualbut, when observing constraints are satisfied, the instrument manager power-on the devices (filter wheel, camara and temperature control) and prepare the system for starting the observation. If some device fails, the application stop and send an email to the observer to notice about the problem. Moreover, in Automatic mode, manual expositions are not allowed.

In Manual mode autobut, the observing constraints are not taken into account, and in order to take an exposition, the user must previously power-on the devices clicking the connect button:

In its default configuration, MCS starts up with Automatic mode as show in the next figure, but without simulation activated.

../_images/main_tab_connect.png

Connect button in Main Tab panel

Simulation mode

Althought it is not forseen for the normal MIMA user, MCS allows an additional running mode called Simulation. When MCS run in that mode, no hardware device is detected, and so no real images or data are obtained, but simulated. It is thought for engineering purposes, and it can be activated/deactivated from the configuration file.

If the Simulation mode is activated, MCS shows an message in the the main tab panel with a red background as shown in the next figure:

../_images/main_tab_connect.png

Main Tab panel with Simulation mode enabled

Simulation mode is compliant with Automatic and Manual mode, thus, four configurations are possible:

  • Automatic/Manual & Simulation/No-Simulation

Defining an observing campaign

MIMA cycles repeteadly through a list of sequences with different filter (O2, OH, Na, …) and darks exposures. That working mode, it is implemented in MCS as an Observational model as shown in the next figure:

MIMA Observation Model

MIMA Observation model

Description of the entities:

  1. Campaign: a campaign is the main data structure compound of:

    • Observation Constraints

    • Observation Mode

    • Start datetime

    • End datetime

Warning

Campaigns cannot collide in time, so it is not allowed in MCS to define a campaign in the same time slot of other existing campaign.

  1. Observation Constraints: every campaign has some observing constraints. They are:

    • Sun elevation (max): maximun sun elevation allowed for the observation.

    • Moon elevation (max): maximun moon elevation allowed for the observation.

    • Moon correction: it is a function that defines a correction to add to the maximun moon elevation as function of the current moon phase. Then, MIMA will not observe if:

      moon_elevation > max_moon_eleva + moon_correction(moon_phase)
      
    • Sun offset calibration: this value is used to know when the flat-field calibration should be taken, and is added to the maximun sun elevation value. Thus, flat calibrations are taken if:

      sun_elev < max_sun_elev + sun_offset_calibration
      
    • Filter temperature: value for working temperature of filter; it is adjusted by the temperature controller. Only when that temperature is achieved (within a small tolerance specificed in the config file), the observations will be taken when working in Automatic mode.

    • CCD temperature: minimum value for working temperature of CCD; it is adjusted internally by the camera using a peltier cooler. Must be taken into account that the maximun cooling temperature is 55ºC Below Ambient, so a tipical value should be -40ºC, ie, observations will only be taken when the temperature is bellow -40ºC.

  2. Observation Mode: the observation mode defines the type of observation to be done during the entire Campaign. It is compound of a Filter Sequence and a set of readout parameters as binning and read speed, and the calibration setup for darks and flats.

    • Filter Sequence: it is a list of the triplet [Filter, ExpTime, Repetitions]

    • Readout parameters:

      • Pixel Binning in CCD readout: (1x1, 2x2, 4x4,…)

      • Digitization Speed: (1MHz High Gain(LN), 1MHz High Range, 3MHz High Gain(LN))

  • Calibrations: the user can specify in the Observing Editor the next parameters for Darks and Flat-Fields

    • DARK: darks can be adquired automatically using the same exposition time that science filter images, or manually using the exp. times defined by the user, plus a BIAS image (texp=0s); manual mode is foreseen to take a dark series to be interpolated. Additionally, both modes have the next parameters:

      • Manual time: in this box must be entered (semicolom separated) the exposition times as follow: example1-> 10.0;20.0;30.0, example2-> 10.0

      • Dark Frequency: every how many science images a dark series is taken

      • Dark repetitions: how many darks of each TEXP are taken.

      Note

      Because camera shutter is closed during the dark exposure, it does not matter which filter is chosen.

    • FLAT-FIELD
      • Filter(s), TExp and Reps for Flat-Field images; they are taken at dusk and dawn time, and the user can select which filters are required or no filter if any flat-field is required. Additionally, for each Flat-Field image the system takes automatically the corresponding Dark images.

Note

Observation modes are associated to Campaigns, and need to be defined before creating a new campaign.

Next figures shows the Campaign Tab panel and the dialogs for creating on Observation Mode and a Campaign.

../_images/campaigns_tab.png

Campaign Status

Based on the star/end datatime of a Campaign, its status can be:

* ACTIVE: campaign_datetime_start() <= now() AND campaign_datetime_end() >= now()
* PENDING: campaign_datetime_start() > now()
* FINISHED: campaign_datetime_start() < now() AND campaign_datetime_end() < now()

Observing conditions

As we have seen above, each Campaign has its own Observing Constraints that especifies when the Campaign can be executed. When the instrument is in Automatic mode, the start up of the instrument, the calibrations and campaign execution is conditioned upon three main times that are defined in the Observing Contrainsts, and that are based on a set of parameters:

  • Running (star-up) time: the instrument is powered and devices connected; it is based on next parameters: SunElevationMax, SunCalibrationoffset and WarmUp time

  • Calibration time: the instrument is prepared (temperatures are OK), then flat-field calibrations can be taken; it is based on next parameters: SunElevationMax, SunCalibrationoffset

  • Observing time: calibrations have finished, and the campaign can be executed for taking science images; it is based on next parameters: SunElevationMax, MoonElevationMax and MoonCorrection(FLI)

../_images/MIMA-SunElevationRec.jpg
  • SunElevationMax and MoonElevationMax must be in range [-90º, 90º]

  • FLI: Fraction of the moon illuminated [0, 1], 1=full moon, 0=new moon

  • moon_factor: float value, that can be defined as a constant or as a function defined in python language:

def moon_correction(phi):
    """
    Calculate the correction for maximun moon elevation as function of the
    illuminated fraction of the moon


    Parameters
    ----------
    phi : float [0-1]
        Fraction of lunar surface illuminated (0 is "new", 1 is "full")

    Returns
    -------
    correction: float
        Correction for Fraction of lunar surface illuminated [0-1]
    """
    k = 2.0
    return phi*k

Thus, MIMA will not observe if:

(SunElevation > SunElevationMax) OR (MoonElevation > MoonElevationMax + moon_correction(FLI))

Warning

If some of introduced values for the Sun/Moon elevation are not achievable (not feasible), MCS will understand them as wrong values and will not start the observation.

Next figure shows the flow diagram to decide when the applicantaion must start-up and power-on the instrument, ie., what is called RunningTime.

../_images/R_act__RunningTime__RunningTime.png

MIMA RunningTime definition

Instrument States

../_images/R_stm__ObservationModes__ObservationModes.png

MCS Instrument States

Instrument Manager Logic

The Instrument Manager is in charge of the control of the instrument devices, and once the instrument is in Automatic mode, decides when the instrument must be power-on (off). Then it looks for the next Campaign to be executed according the Scheduler and the Observing constraints of the next Campaign.

../_images/R_act__Observation__Observation.png

Instrument Manager work flow

Night Report

When the night observation is finished due to Sun elevation and the calibrations are taken, the Instrument Manager will inspect the nightly data directory (/home/mima/DATA/MCS_DATA/YYYYMMDD/) and will send by email a report to the observer with a summary of the data files taken during last night. To configure the recipients of that report, you need to modify the REPORT_RECIPIENTS keyword in the Configuration file.

Campaign Runner Logic

The campaign runner is a process that in charge of the execution of a Campaign. It starts checking the instrument temperatures are in range and the rest of constraints are satisfied. Then initiates calibrations (dusk Flat-Fields) if they were configured, and then initiate the proper observation, taking the sciece images, i.e., the filter sequences defined in the observation mode.

The campaign runner will check the instrument temperatures (ccd and filter wheel) before every exposition is taken, and the observing constraints are checked at the beginning of every filter sequece.

../_images/R_act__CampaignRunner__CampaignRunner.png

Campaign Runner work flow

Scheduler

The manager query the campaign scheduler to get the next campaign to be executed. The scheduler selects the next campaign according to the start and end datetimes defined for each campaign.

Basically, the condition to select the next campaign is:

campaign_datetime_start() <= now() AND campaign_datetime_end() >= now()

In principle, MCS does not allow to define more than one campaign in the same interval of time, i.e., two campaign cannot coincide in the time. However, in case of conflict, the older campaign would be selected to be executed.. If no campaing is found, MCS will execute the Default campaign that is pre-defined in the system.

Configuration file

The MCS application uses a configuration file that pre-sets the instrument configuracion parameters. It is read only at start-up of the application, and MCS never writes on it. Some values are used to initialize the database for the first time we launch the application, and others are used on every MCS execution. In principle, the user should not modify any value, but for the initial application setup could be necessary to adjust some values.

The configuration file config.ini to be included must be located in the base directory of:

~/.mcs/

The configuration parser (ConfigParser) processes (parses) each parameter sequentialy during the application start-up, but if some parameter is missing, it is only detected when is used during the application execution, so plase, modify the file carefully.

The file has a similar structure to what’s found in Microsoft Windows INI files. It consists of sections, each led by a [section] header, followed by key/value entries separated by a specific string (= or : ). By default, section names are case sensitive but keys are not. Leading and trailing whitespace is removed from keys and values. Values can be omitted, in which case the key/value delimiter may also be left out. Values can also span multiple lines, as long as they are indented deeper than the first line of the value. Depending on the parser’s mode, blank lines may be treated as parts of multiline values or ignored.

Warning

If some values are modified in the config file, they will take effect from the next application start-up.

Warning

MCS application never writes on the config file, only read from it.

Let’s take a very basic configuration file that looks like this:

; config.ini
[DEFAULT]
ADMIN_NAME = administrator
HW_SIMULATION = False
INIT_HW = no
# MODE: manual | auto
RUN_MODE = auto
# LOG_LEVEL: NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL
LOG_LEVEL = DEBUG

# observation constraints: default values read first time for DB creation
SUN_ELEV_MAX = 5
MOON_ELEV_MAX = 20
MOON_CORRECTION = /home/mima/moon_factor.py
SUN_OFFSET_CALIB = 2

# time (minutes, int value) need by instrument warm-up (ccd cold-down and FW-warm-up)
# currently, the maximun estimated time is due to FW-warm-up, that could
# be 1h due to Temperature Controller performances.
WARM_UP_TIME = 300

# directories
WATCHDOG_FILE = /home/mima/DATA/MSC_DATA/watchdog
DATA_DIR = /home/mima/DATA/MSC_DATA
LOG_DIR =  /home/mima/DATA/MSC_DATA/log
REPORT_RECIPIENTS = maya@iaa.es, jmiguel@iaa.es

[SITE]
NAME = OSN
DESCRIPTION = Sierra Nevada Observatory
LATITUDE = 37.06416
LONGITUDE = -3.38472
ALTITUDE= 2900
TZ=UTC

[TEST]
# currently, not used
TEST_TMP_DIR = /home/mima/DATA/MSC_DATA
TEST_TIMEOUT = 20

[DB]
DB_FILE =  /home/mima/DEVELOP/OSN/SATI.git/MCS/model/mcs_db.sqlite

[FILTER_WHEEL]
# next values are only used the first time, then MCS use the values from DB
filter_names = { 'FILTER1': 'OH-A', 'FILTER2': 'O2', 'FILTER3': 'Na', 'FILTER4': 'OI558', 'FILTER5': 'OI630', 'FILTER6': 'OH-B', 'FILTER7': 'OPEN'}

[CCD]
# Next values are NOT in DB, and are only in this file
# Working temperature (C)
SET_TEMP = -55
# Working tolerance temperature (C)
# In fact, we have no control about temperature, but only set the working temp
TEMP_TOL = 25

[TEMP_CONTROLLER]
# next values are only used the first time, then MCS use the values from DB
device = "/dev/ttyACM0"
# Setpoint for working temperature (C).
set_t = 30.0
# Tolerance for working temperature (C)
t_tolerance = 1.0
set_p = 11.0
set_i = 22.0
set_d = 33.0
interval = 60
# Single filename, LOG_DIR will be added to pathname
log_file = mcs_tempCtlr.log
log_interval = 60

[POWER_CONTROLLER]
device_ip = 10.9.0.199
ports = 4
device_ports = {'port_0': 'filter_wheel', 'port_1': 'camera', 'port_2': 'temp_ctlr', 'port_3': 'usb_externder'}

[TH2E]
url = http://th2e-sati.osn.iaa.es/fresh.xml
interval = 60

Disk Allocation

  • MCS creates automatically a directory for every observing night/session. These directories are located in $MCSHOME/DATA/MSC_DATA/YYYYMMDD, and will contain all the FITS data files of whole the night. That is valid for any Campaign that starting before the 12h of the next day.

  • By default, with no binning and BITPIX=16 (signed int), the size of the FITS files created is 2 MB each.

  • There is no automated removal of data files by the software. Users need to look into the $MCSHOME/DATA directory, the $TMP and in particular in $MCSHOME/DATA/MSC_DATA/log for obsolete and large log files left behind. The amount of space required by various log-files depends in particular on the value assigned to LOG LEVEL in configuration file.

Log file

MCS includes, in addition to the screen log and Debug Tab, the facility of logging to a file ($MCSHOME/DATA/MSC_DATA/log). The user can change the level of verbosity modifying the LOG_LEVEL keyword in the configuration file. The main level are (as definned in Python)

  • NOTSET (0)

  • DEBUG (10): for debugging pruposes by a developer

  • INFO (20): for monitoring of the observation by a user

  • WARNING (30): for monitoring the execution of the application by the user

  • ERROR (40): for error detection and bugfix by the user and developer

  • CRITICAL (40): for critical error that crash the application

When you set a logging level in the config file, you’re telling MCS you want to handle all events from that level on up. For example, if you set the log level to INFO, it will include INFO, WARNING, ERROR and CRITICAL messages.

To have a detailed observing log of the observing night, the [INFO] messages are the most suitable.

Note

If you define a high level of logging, i.e. DEBUG, you can always get a log file with a specific level doing a basic filtering of the messages, for example:

grep ERROR mcs.log

Troubleshooting

  1. Cannot connect to devices.

Before you attempt to link to the instrument, run through this checklist to make sure you are ready to begin imaging:

  • The camera/filter_wheel/ should be securely attached to the instrument. If practical, attach a safety wire, cable, or strap to catch the camera if it works loose. The camera’s power and other cables may tug on the camera as you move your mount, and if the camera isn’t completely secure it can work loose, fall off the telescope and damage or destroy the camera.

  • All electrical connections should be secure, and power to the camera should be turned on.

  • The cable from the camera or control box to your computer should be securely attached, especially if you have a laptop that may get moved about during use.

  • Double check the routing of all cables to make sure they will not catch on the instrument mount or other accessories.