UVES P2PP Tutorial

IMPORTANT: starting from Period 101, users preparing observing runs in Service and Visitor Mode for FLAMES, UVES, X-SHOOTER, VIRCAM and/or OmegaCAM shall use the new web-based tool p2 instead of P2PP. While the tutorial presented on this page is no longer applicable for the preparation of Phase 2 material, it may still be of use for understaning general Phase 2 concepts.  

Please see here guidelines for the preparation of Phase 2 material with p2.

This tutorial provides a step-by-step example of the preparation of a set of OBs with UVES, the UV-Visual Echelle Spectrograph at the ESO-VLT.

To follow it, you should have a p2pp3 installation in your computer and be familiar with the essentials of the use of p2pp3. Please refer to the P2PP Web page for detailed installation instructions, and to the p2pp3 User Manual for a general overview of p2pp3 and generic instructions on the preparation of Observing Blocks.

0: Goal of the Run

In this tutorial we will prepare OBs for a simple example observing run, consisting of high resolution spectroscopy of Eta Car (RA(2000) = 10:44:39.1, Dec(2000) = -59:37:44). The sample OBs will illustrate the use of a variety of features of p2pp3 and the kind of decisions to be taken at the time of preparing in advance an observing run, as well as some aspects that are specific to the preparation of OBs for UVES. In this imaginary observing program, we wish to observe Eta Car with two perpendicular slit orientations, and the two observations must be taken in immediate succession.

1: Getting Started

The Phase 2 process begins when you receive a communication of the ESO Observing Programmes Office (OPO) communicating to you that the allocation of time for the coming period has been finalized and that the results can be consulted in the corresponding Web page. You follow the instructions given by ESO and find that time was allocated to your run with UVES. Therefore, you decide to start preparing your Phase 2 material. First, you collect all the necessary documentation:

and you proceed with the installation of p2pp in your machine if necessary. 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 not have their own p2pp login data can still use p2pp and prepare example OBs. You can use it to prepare actual OBs intended to be executed, but only after exporting the OBs and then re-importing them back into p2pp whilst logged in either as the PI or as a Phase-2 delegate. After logging into the tutorial account, the p2pp main GUI will appear as follows:

Runs for a number of instruments appear in the Folders area, 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 for which you are PI that have been delegated to you.

2: Making OBs

Select the folder corresponding to the UVES Tutorial run, 60.A-9252(G). In this tutorial we assume that time was allocated in Service Mode. This is indicated by the SM letters that appear next to the Run ID of the UVES run.

You can now start defining your OBs. Since we want our two OBs to be executed in sequence, we must define them inside a Concatenation. Select the program folder and click on the big purple C icon. Then highlight the Concatenation and press Enter to rename it "eta Car: 37.5 and 127.5 deg" as shown:

To create the first OB, click on the dark-blue OB icon. This creates the OB inside the Concatenation. The red dot with an "x" 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. It is always a good idea to give meaningful names to OBs, so that you can browse through the list and easily recognize them. In our first example, we will build an OB to take a spectrum of Eta Carinae using UVES Blue Arm with two different slit position angles; for this reason we will call the OB "etaCar 37.5deg" by renaming it as we did for the concatenation.

Now click on the Edit icon (highlighted in the above figure), and the OB editing window appears. This is the window where you will define the contents of your OB.

2.1: Defining the acquisition template

An OB is defined in a set of one or more templates that form the Observation Description, or OD for short. It may be useful in many cases to have an easy way of identifying an 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 one of the columns 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, the OD will consist of a sequence of three spectra with increasing exposure times. We can thus appropriately name it eta Car - BLUE. We enter this name in the OD Name field.

The first template that must be part of any OB that requires a definite pointing is the acquisition template, so let us define it first. In the Template Type pull-down menu, make sure that the acquisition entry is highlighted. This will list all the acquisition templates available for UVES in the Template list under it.

After reading the description of the templates in the UVES User Manual, you have determined that the UVES_blue_acq_slit is the acquisition template you have to use for this particular observation. 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. Since we want to acquire directly on Eta Carinae, we will set both RA blind offset and DEC blind offset to 0.0. You do not have any special requirements on the guide star, which will be selected from the VLT guide star catalogue (Get Guide Star from) and hence there is no need to specify any coordinates for the guide star (Guide star RA and Guide star DEC).
Since you want to place the slit on a position angle of 37.5 degrees, you have to chose SKY as Derotation Mode and you must specify the angle 37.5 in the Position Angle field.
Eta Carinae is a bright star, and thus it is a good idea to use the neutral density filter ND2 as pre-slit filter for the acquisition (Acq. Pre-Slit Filter). There is no need for a depolarizer, so Depolarizer is left OFF, but you do want to limit the slit losses and therefore you insert the Atmospheric Dispersion Corrector (ADC), setting it to AUTO.
The set of parameters that you choose in your acquisiton template is shown in the previous figure.

2.2: Setting the target information

By default, the OB editor opens in the "Obs. Description" mode. To enter information on the target, click the "Target" icon at the top of the window.In the Name field, type the target name "eta Car"). In the Right Ascension, Declination fields, type the coordinates. Since the coordinates are given for both epoch and equinox J2000, leave these fields with their default values. You can give also the Class to which this object belongs, for archival purposes. In this case, choose Pec* (peculiar star).The proper motion of this target is negligible for the purposes of this example, and differential tracking of the telescope is not needed since this is not a moving Solar System target. Therefore, you can leave the last four fields in the Target tab set to their default values of zero.

2.3: 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 and filling the entries under it:

First, give a descriptive name to the constraint set about to be defined. In this case we choose "eta Car - PHOT" for the Name field. In the Sky Transparency entry we choose "Photometric", and since you need moderately good quality in your images, you specify 1.0 as the value of the Seeing field. Set the Airmass to 2.0, to ensure that your observations are not carried out at too low an elevation. Since you are doing high resolution spectroscopy of a bright target, the lunar illumination has very little influence, so you decide to leave the lunar parameters at their default valules.

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

2.4: Setting time intervals

We will assume now that the spectroscopy of Eta Carinae has to be obtained in May 2012, since you will have simultaneous observations at other wavelengths during that time interval. You can specify this by clicking the Time Intervals icon. You are now asked to "Click the New TI button to add a Time Interval". Do so. Now the following window pops up and you can adjust the time interval:

When clicking OK, the time interval is entered into the OB (see picture below). If your observation could be executed in other, non-contiguous time windows, you could define as many intervals as you like to cover all possible opportunities to execute the OB within the period.

Note that all time critical aspects (absolute time intervals and timelink containers) must also be explained in the section on "Time Critical Aspects" of the Readme.

For more information on entering time constraints and how to use TimeLink containers to enter relative time constraints, see the description in the p2pp manual.

2.5: Defining the Observation

Once the acquisition is completed, the science observation begins, so the observing templates need to be attached. After checking with the manual and considering the scientific requirements of your program, you have found that the suitable template to be used is UVES_blue_obs_exp.

From the  Template Type pulldown menu, select science. The available UVES science templates will appear. Select the chosen one, UVES_blue_obs_exp, and click on Add. The template will be attached to the grid below next to the acquisition template previously filled in. Next you need to set the parameters of the science template.

Following the recommendations of the manual, you choose to use the standard read-out mode 225kHz,1x1,low. For your scientific purposes you need to obtain 3 spectra of 30 seconds each of Eta Carinae, which is definitely an extended object. Due to the high signal-to-noise ratio you expect to achieve, you do not need to perform any offset along the slit. The default central wavelength (346) is the correct one but you want to improve the resolution as much as possible by using a narrow slit available. The set of parameters that you choose in your science template is thus as depicted below:

Since you now want to perform another two sets of observations with longer exposure times, you can select again the same template, Add it, and fill the parameters in the same way as done for the first template. However, since the parameters of these other two templates will be very similar to those of the one just defined, you can speed up the preparation by clicking on any entry of the template for the 30 seconds exposures, then clicking on the Duplicate button, and then clicking again on the same button. In this way, you will have produced two identical copies of the first science template in which you should now only edit the parameters that change from template to template, i.e., the exposure times, which are going to be 180 and 300 seconds respectively. You can now compute the execution time clicking on the Recalculate button next to the Execution Time field.

NOTE: the execution time field is not updated automatically, you thus need to click on the Recalculate button to display the correct value after any modification.

Finally, to complete the OB preparation, enter the expected signal-to-noise ratio in the Instrument Comments field, using the following syntax: S/N=XYZ @ xyz nm:

This completes your first OB! If you followed all the indications given so far, the OB window should look like the image above.

2.6: Attaching Finding Charts and the README file

Finding charts and README file are directly attached to the OBs. Please, see the respective tutorials on attaching Finding charts and editing and submitting the README (video or text) and also the detailed guidelines for the README file content.

2.7: Making more OBs

We want to add one more OB to our Concatenation in order to take a spectrum with the slit direction perpendicular to that of the first OB. Since most of the OB parameters will be identical, the easiest is to duplicate the OB we've already made. In the main p2pp GUI window, select the OB and click the Duplicate button. See picture:

This will add an identical OB to the concatenation. We rename this new OB to "eta Car 127.5deg". Clickin the Edit icon, we now only need to change two things: (1) the value of the Position Angle in the acquisition as shown in the image below, and (2) attach a different finding chart showing the proper slit position.

3: Finishing the preparation and submitting the OBs

With the completion of the OBs above, we consider this tutorial terminated. As already mentioned, it has certainly not covered all the observing strategies you may have foreseen for your program, but it has shown how to prepare OBs for a representative case.

The p2pp main GUI now displays the two OBs that we have prepared:

Note that the red cross has been replaced with a check mark, indicating that the OBs pass some fundamental sanity tests. However, we still need to Verify the OBs before submitting them to ESO. To do this, highlight the OBs and select the menu item Reports > Verify. This step runs a Verification Module checking that the structure and all the parameters we have specified are compliant with the instrument specifications. You should get an verification report that looks something like the following:

You can see that there is one WARNING for each individual OB and one ERROR for the concatenation. The WARNINGs are just that, warnings that there may be something wrong that you might want to correct. In this case this is the target check that has failed, but this is normal for the veriication of any OB with the the p2pp tutorial account since no phase 1 information is defined for that account. The ERROR on the other hand represents a problem. Either the ERROR must be corrected by changing the OBs appropriately (depending on the nature of the ERROR), or if it is a WAIVERABLE ERROR you can apply for a WAIVER to override the ERROR. The procedure to apply for WAIVERs is described here.

Assuming you do apply for and are granted the WAIVER then running the verification on your local version of p2pp will still generate an ERROR, this is normal. Moreover when you attempt to check in the OB(s) a local verification is performed and will indeed again produce an ERROR. To illustrate, select the concatenation, then select File > Check-in from the menu in the p2pp main GUI. The following window will appear:

If a WAIVER(s) has(have) indeed been granted to override all the ERRORs generated by the verification, then you should simply click the "Yes" button, p2pp will then attempt to proceed with the check-in. If the WAIVER has indeed been granted, then the OBs and containers will once again be verified, this time by the ESO p2pp server, which will take granted WAIVERs into account thus ignoring any ERRORs provided the appropriate WAIVER(s) has(have) been granted. In this case if you press the "Yes" button, check-in will still fail because an appropriate WAIVER has not been granted for the tutorial account.

Once OBs have been successfully checked-in, they will be locked and no further modification is possible, unless you first check them out. This status is indicated by the OB being greyed out in the p2pp main window and a lock symbol will appear just to the left of the blue tick-mark.

4: Check-Out and removal of tutorial OBs from the ESO Database

As a courtesy to the next user who follows this tutorial, if you did successfully check-in any OBs, we would like to ask you to finish this tutorial by checking-out and thus removing the OBs from the ESO Database. The p2pp User Manual gives you detailed indications on how to do this. In short,

  • In the p2pp main window select the OB(s) and/or container(s) to check-out
  • Select Check-out... from the File menu in p2pp
  • Click "Yes" in the popup window that appears

In this way the OBs will be removed from the ESO Database and will be left 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.

Instrument selector