KMOS P2PP Tutorial

This tutorial provides a step-by-step example of the preparation of a set of Observation Blocks (OBs) with KMOS, the K-band Multi Object Spectrograph on UT1 (Antu) of the VLT. The specifics of this tutorial pertain to the preparation of OBs for Period 93 onwards. To follow it, you should have a P2PP (version 3) installation on your computer and be familiar with the essentials of the use of the software. Please refer to the instructions in order to install it, and to the P2PP3 User Manual for a general overview of P2PP3 and generic instructions on the preparation of Observing Blocks and scheduling containers.

0: Goal of the Run

In this tutorial we will prepare OBs for one simple example observing run. More cases will be added later.

Case A consists of spectroscopy in the HK band of lensed galaxies behind the massive galaxy cluster A1689.

1: Getting started

The Phase 2 process begins when you receive an email from ESO telling you that the allocation of time for the coming period has finalized and that you can view the results by logging into the User Portal and clicking on "Check the web letters." Note that the username and password that you need to use for the User Portal are the same as those you will use to prepare your OBs.

You follow the instructions given by ESO and find that time was allocated to your run with KMOS. Therefore, you decide to start preparing your Phase 2 material.

First, you collect all the necessary documentation:

and you proceed with the installation of P2PP3 on your machine if necessary.

One very important prerequisit for the preparation of KMOS OBs is one or more KARMA set up files, which have to be attached to the OBs. In those files the positions of the arms as well as the coordinates of the guide and reference stars are defined. KARMA also should be used to create the necessary finding charts that have to be attached to the KMOS science OBs. You can find the documentation and download page of KARMA here:

2: Case A: lensed galaxies behind A1689

Let's start with the first science case. So, off you go to define those observations.

2.1: P2PP

For the sake of this tutorial, we will hereafter use the following P2PP information:

  • P2PP ID: 52052
  • password: tutorial

This is a special account that ESO has set up so that users who do now have their own P2PP login data can still use P2PP and prepare example OBs. You cannot use it to prepare actual OBs intended to be executed.

After logging in using the tutorial account, the P2PP main GUI will appear as follows:

Click here to see the fullsize image.

Runs for a number of instruments appear as folders on the left, since the same tutorial account is used for all of them. Similarly, if you log in with your own P2PP ID, you will get the list of all the runs in which you are PI.

Select the folder corresponding to the KMOS Tutorial run, 60.A-9253(Q). In this tutorial we assume that time was allocated in Service Mode. This is indicated by the SM letters that appear next to the RunID of the KMOS run.

You can now start defining your OBs. In this science case we want to habe three OBs on the same target configuration because our galaxies are faint and the S/N reached with one 1-hour OB would not be sufficient.

To create an OB, press the 'OB'-bullet in the icon menu on the top. You can give it a name by selecting the OB with the mouse and choosing 'Rename' in the menu of the right mouse button, or by using the 'File' menu on the top of the window and choosing 'Rename' there. Let's call the OB 'A1689 HK 1'.

The red dot with the white cross next to the OB name means that the OB fails to pass some fundamental verification criteria, as may be expected from the fact that no template has been attached to the OB yet.

To view and edit the OB press the 'Edit Observation Block' icon (pen with OB bullet) in the top icon menu. The OB window appears:

Click here to see the fullsize image.

This is the window where you will define the contents of your OB.

to the top

2.2: Defining an OB

2.2.1: Filling in the Basic Information

This is an OB for spectroscopy in the HK band. It may be useful in many cases to have an easy way of identifying an observation description (OD), like when having observations of a number of targets performed with identical instrument configuration and exposure times. The OD Name field in the OB window allows you to define names for the ODs. The OD name appears in turn in the 'Obs/Calib Blocks' area of the P2PP main GUI, thus allowing the identification at a glance of all OBs having ODs with the same name. In this example OB, we can appropriately name it 'HK spectroscopy'. Enter this name in the OD Name field.

Next, the User Comments field can be used for any information you wish (to keep further track of the characteristics of the OB, to alert the staff on Paranal to special requirements. In particular, if you wish to have a certain spectral type as telluric standard you can write something like "The telluric standard should be of type G0V".

The entries then look like this:

Click here to see the fullsize image.

to the top

2.2.2: Defining the acquisition template

The first template that must be part of any OB is the acquisition template, so let us define it next. In the Template Type list, make sure that the acquisition entry is selected. This will list the four acquisition templates available for KMOS in the Template list.

After reading the description of the templates in the KMOS User Manual, you have determined that the KMOS_spec_acq template is the right one. You thus click on this template in the Template list, and then on the Add button next to it.

You need to decide now on the acquisition parameters. These are required for the pointing and tracking of the telescope, the setting of the derotator mode and the grating, and for centering of the reference stars and targets in the IFUs.

In our case the reference stars are rather faint (J=13.5) so we set the DIT to 40s and NDIT to 1. The total execution time of the science template has to be entered into the Duration of SCI template field. It is used to calculate the atmospheric refraction, which in turn is needed to correct the IFU centering. Since the acquisition will take about 10 min for this OB, you should enter 3000 sec (=60-10 min) in this field.

The Suppress rotator optimization box should remain unchecked in case you want to make sure that your highest priority targets (priorities 1 and 2) get an IFU allocated. This is important if one or more arms are locked due to technical failures during the observing period.

In the GratingFilter field you can choose the right band from a pull-down menu, in our case HK.

Now the most important point. Clicking on the KARMA target setup file will open a browser where you can select in your directory structure the appropriate KARMA setup file for this OB, in our case named KARMA_2013-06-16_Stare_test1.ins.

In summary, the set of parameters that you choose in your acquisition template is thus:

  • Integration time: 40
  • Number of DITs: 1
  • Suppres rotator optimization: box remains unchecked
  • Duration of SCI template: 3000
  • GratingFilter: HK
  • KARMA target setup file: KARMA_2013-06-16_Stare_test1.ins

The acquisition template is now complete, and the window should now look like this:

Click here to see the fullsize image.

2.2.3: Target Information

Let us for a moment take a break from inserting templates into this OB.

The coordinates (including epoch and equinox) of the science target have been automatically inserted into the Target-tab while uploading the KARMA setup file. Just press the target icon in the icon menu on the top to have a look. Please never change any of the parameters in this tab! The only exception is the Class parameter, which can be set to GravLens for this science case.

The values in the target-panel look then like this:

Click here to see the fullsize image.

to the top

2.2.4: Setting the Constraint Set

As stated in Section 1, we assume for the purposes of this tutorial that the program has been allocated time in Service Mode. You thus need to specify a Constraint Set for your OBs. You can do this by clicking on the Constraint Set icon on the top icon menu and then filling the following entries:

  • First, give a descriptive name to the constraint set about to be defined. Since you have decided that this constraint set will be applied to all the OBs, you type HK constraints in the Name field.
  • Since you are not interested in achieving accurate flux calibration of your spectra, you request Variable, thin cirrus conditions in the Sky Transparency entry.
  • You would like to spatially resolve your targets. Therefore you should choose a good seeing. Enter 0.8 as value in the Seeing field.
  • Set the Airmass to 1.6, to ensure that your observations are not carried out at too low an elevation.
  • Since you are doing spectroscopy in the NIR, the lunar illumination has basically no influence. You should require 1.0 for the Lunar Illumination and 30 degrees for the Moon Angular Distance (smaller values might cause problems linked to the telescope guiding system).
  • The Twilight constraint can be relaxed to -15 minutes, since observations in the H- and K-band can be taken without problems before the astronomical twilight ends (negative values).
  • Precipitable water vapour (PWV) influences the atmospheric water lines in particular beyond 2 microns. However, for the relative low resolution HK-band telluric lines this does not matter too much. We choose for PWV a value of 15 mm.

Your Constraint Set panel should look like this after entering the values:

Click here to see the fullsize image.

Note that in your Phase 1 proposal you already specified some of these constraints (seeing, lunar illumination, transparency). You must make sure that none of the constraints specified in Phase 2 is more stringent than the corresponding one specified at Phase 1.

to the top

2.2.5: Setting the time intervals

Since the observations are not time critical we do not have to chnage anything in the Time Intervals tab. Anyway, clicking on that tab shows the following panel:

Click here to see the fullsize image.

to the top

2.2.6: Defining the Observation Description

Target, Constraint Set and Time Intervals are completed, the science template(s) can be inserted.

After checking with the manual and considering the scientific requirements of your program, you have decided to execute the observations using the freedither mode, which allows to freely define the number of dither offsets. The right template is the KMOS_spec_freedither template. To select it, choose in the Template Type menu science. Then select the template and click on Add. The template will be attached to the grid below next to the acquisition template selected and filled previously.

Given the flux of your sources and the advice on the duration of the individual DITs in each band as given in the User Manual and checked with the Exposure Time Calculator (ETC), you decide that an appropriate choice of integration time is a DIT of 450 sec. This allows within a 1-hour OB four exposures on target and two exposures on sky. The dithern pattern can be, for example: DITHER pattern in ALPHA="0 0.2 0 -0.2" and DITHER pattern in DELTA="0 0 0.2 0". Note that the offsets are defined in an absolute sense, referring to the initial pointing position. I.e. the offsets are not cumulative, relative to the previous position.

For two sky exposures you should set Sky will be observed every X science exposures to 2. This will give a sequence ABA ABA (A=object, B=sky). Since no additional sky exposure is necessary the Exp. time for optional sky can remain zero.

The KMOS_spec_obs_freedither template thus has the following parameters:

  • DIT: 450
  • NDIT: 1
  • Exp. time for optional sky: 0
  • DITHER pattern in ALPHA: 0 0.2 0 -0.2
  • DITHER pattern in DELTA: 0 0 0.2 0
  • Sky will be observed every X science exposures: 2

The only other thing that you should really do at this point is to check the execution time for this OB. Press the Recalculate button next to the Execution Time label. The calculated OB execution time appears in the display to the right of the label. In this case the total execution time is 01:01:58.0, which is just acceptable for the 1 hour execution time limit.

This completes your first OB! If you followed all the indications given so far, the OB window should look like this now:

Click here to see the fullsize image.

and you should see the OB named A1689 HK 1 in the P2PP main GUI with the following contents in the Obs/Calib Blocks tab:

  • Local Id: 472 (in our case, can be any number)
  • Status: (P)artiallyDefined
  • Target:
  • OD: HK spectroscopy
  • CS: HK constraints
  • Acquisition: KMOS_spec_acq
  • FindingCharts: (0)
  • EphemerisFile:

You can reshape the columns as indicated in the P2PP User Manual to view the full contents of each entry.

You may have noticed the (0) under the heading ofFindingCharts. This is because you have not attached any Finding Charts to the OB. Following the general rules and KMOS-specific rules for Finding Chart generation, you make your Finding Chart(s). The jpg file(s) should then be on your local disk, and you attach them one by one to the OB by highlighting the OB, clicking on the Finding Charts item on the top menu, and selecting Attach Finding Chart(s) from the pull-down menu. This gives you a browser window, in which you navigate to the correct directory and select the file(s). The P2PP Finding Chart Tutorial gives more advice on how to attach Finding Charts within P2PP.

to the top

Since in this example case, the lensed galaxies around A1689 should be observed for a longer total exposure time to reach the necessary depth, you need to create more OBs, let's say three OBs in total in our case. This can be best done by duplicating the existing OB. Highlight the OB 'A1689 HK 1' and press the Duplicate icon in the top icon menu two times. You then can rename the two duplicated OBs. In our case the structure of the KMOS run looks then like this:

Click here to see the fullsize image.

to the top

3: Finishing the preparation and submitting the OBs

Another view of the observing run structure is the Schedule view. In the P2PP main GUI click on the tab Schedule below the icon menu. The CRIRES runs should then look like this:

Click here to see the fullsize image.

In this view you can assign priorities to the containers or single OBs. You can choose numbers between 1 and 10. The lower the number the higher the priority of the group. In our case, just to illustarte we chose priorities 1, 2 and 3 for the three OBs (although it does not matter for identical OBs which one is observed first).

With the completion of the OBs, we consider the example developed in this tutorial to be finished.

We will now submit these OBs to the ESO Database: highlight all the OBs, go to the File menu in the P2PP main GUI, and select the Check-in option. A dialog box will appear asking for confirmation and, if you click on OK or Yes, they will be saved in the ESO Database.

At this point, for the case of a real Service Mode Run only you should click on the Whistle-icon on the upper right of the top icon menu. This has the effect of sending a signal email to your Support Scientist that OBs have been checked into the ESO Repository.

Again for the case of a real Service Mode Run only you should also view/edit/check-in a corresponding README file. For that you have to use the View / Edit Readme icon in the top icon menu. A special tutorial is available for the Readme file.

As a courtesy to the next user who follows this tutorial, we would like to ask you to finish these exercises by removing the OBs form the ESO Database. The P2PP User Manual gives you detailed indications on how to do this. In short,

  • Select Check-out... from the File menu in P2PP
  • In the Database Browser window that opens, type 60.A-9253(Q) in the Prog ID selection criterion
  • Click on the Query button on the lower left
  • Select all the OBs that appear in the display area after the query. Normally there should be your submitted OBs only, but if another user has submitted other OBs from this same account without removing them afterward you will see them as well.
  • Under the File menu in the View OB window, select Check-out

In this way the OBs will be removed from the ESO Database and will beleft in your Local Cache only. From there you can delete them if you like by selecting them and choosing the Delete option under the File menu in the P2PP main GUI.

to the top

Instrument selector