.. _getting_started: ################## 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: .. figure:: ../_static/mima_cs_arch.png :align: center :width: 80% 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: #. Connect to the control workstation (local o remote) #. Launch the MCS application (if not already running) #. Define the observing Campaign #. 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. Connection ********** **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. Launch the MCS application ************************** 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: .. figure:: ../_static/gui/main_gui.png :align: center :width: 80% 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). .. figure:: ../_static/gui/main_tab_auto.png :align: center :width: 100% 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. .. figure:: ../_static/gui/main_tab_connect.png :align: center :width: 100% 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: .. figure:: ../_static/gui/main_tab_connect.png :align: center :width: 100% 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: .. figure:: ../_static/MIMA_ObsModel.png :align: center :width: 70% :alt: MIMA Observation Model MIMA Observation model Description of the entities: #. 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. #. 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. #. 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: * Calibrations: the user can specify in the :ref:`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. .. figure:: ../_static/gui/campaigns_tab.png :align: center :width: 70% 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) .. figure:: ../_static/uml/MIMA-SunElevationRec.jpg :align: center :width: 60% - 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: .. code-block:: python 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**. .. figure:: ../_static/uml/RunningTime.jpg :align: center :width: 60% MIMA RunningTime definition Instrument States ################# .. figure:: ../_static/uml/R_stm__ObservationModes__ObservationModes.png :align: center :width: 80% 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. .. figure:: ../_static/uml/R_act__Observation__Observation.png :align: center :width: 80% 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 :ref:`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. .. figure:: ../_static/uml/CampaignRunner.jpg :align: center :width: 80% 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: 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: .. code-block:: python ; 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 ############### #. 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. .. |connectbut| image:: ../_static/gui/plug.png .. |quitbut| image:: ../_static/gui/quit.png .. |resetbut| image:: ../_static/gui/reset.png .. |autobut| image:: ../_static/gui/play_auto.png .. |manualbut| image:: ../_static/gui/pause_auto.png .. |redled| image:: ../_static/gui/red-led-on.png :width: 10% .. |greenled| image:: ../_static/gui/green-led-on.png :width: 10% .. |temperaturebut| image:: ../_static/gui/icons8-temperatura-100.png :width: 5% .. _MIMA: http://gapt.iaa.es/content/mima .. _NoMachine: https://www.nomachine.com/getting-started-with-nomachine .. _ConfigParser: https://docs.python.org/3/library/configparser.html#configparser.ConfigParser .. _DS9: https://sites.google.com/cfa.harvard.edu/saoimageds9