FLAMES 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 step-by-step instructions on how to prepare a correct set of Observation Blocks (OBs) for observations to be executed with the Fibre Large Array Multi Element Spectrograph (FLAMES), the multi-fibre facility mounted on the platform Nasmyth A at the ESO VLT Unit Telescope #2 (Kueyen).

To follow it, it is recommended to be already familiar with the basic concepts and features of P2PP and to have it installed on your local computer. Please refer to the P2PP Web page for detailed instructions on the installation, and to the P2PP User Manual for a general overview on the preparation of Observation Blocks.

Getting Started

If you are reading this page, it is very likely that your program has been allocated time with FLAMES. Because of its 39 different wavelength/resolution setups (31 in high resolution and 8 in low resolution) and 3 different instrument modes (GIRAFFE, UVES, and the combined mode GIRAFFE+UVES), this tutorial will not be able to cover all the possible combinations: it is meant to give you a general overview and get you started with the Phase2 preparation.

For the purpose of our exercise, and inspired by the some of the remarkably successful programs carried out with FLAMES, we have chosen to prepare some example OBs for a study of chemical abundances in the globular cluster M4 using the combined mode GIRAFFE Medusa+UVES (it will use two of the high-res Medusa settings and one UVES setup).The purpose of this observational project is to observe a large number of stars in M4 in order to derive elemental abundances. The observing strategy we want to implement is to observe a minimum of one hundred stars with Medusa fibres, and assign UVES fibres to the brightest objects in the field in order to achieve higher resolution and a larger spectral coverage. We will assume that we can cover all our target stars with two seperate fiber allocations centered on M4, meaning that we will use two different FPOSS setup files.

You can follow this tutorial without prior knowledge of FLAMES, but we recommend that you familiarize yourself with the documentation below before preparing your own OBs. This tutorial should then serve as a quick guide and reminder throughout the process, but the information contained in the documentation should always be your primary reference:

More details on the instrument status and on FPOSS can be found respectively on the FLAMES Web pages and on the FPOSS tool Web page. Further useful information and tools for the OB preparation can be found on the User Support  Services and Tools Web pages.

This tutorial has been prepared with the Period 89 P2PP version (p2pp version 3). In the future, text and figures will be updated only when major changes in the instrument package and/or in P2PP have been included.

For this tutorial, we will use a special P2PP account that ESO has set up for testing purposes (e.g. to prepare example OBs even if one does not have an approved observing program):

  • P2PP ID: 52052
  • password: tutorial

After logging in using the tutorial account, the P2PP main GUI will appear. Runs for a number of instruments appear as a list of Folders, since the same tutorial account is used for all VLT instruments. Similarly, if you log in with your own P2PP ID, you will get the list of all the runs of which you are PI, or to which you have been delegated access to by other PIs (http://www.eso.org/ace/). Note any Delegated runs will be listed after all of your own runs.

Selecting the folder corresponding to the FLAMES Tutorial run, i.e. 60.A-9252(I), this will be highlighted. For the purpose of this exercise, let's assume that time was allocated to this program in Service Mode, as indicated by the SM letters that appear just after the Run ID.

While not necessary, it is possible to create folders to help organize your OBs within a given observing run. Here we have created a folder M4 project for the OBs for this tutorial. Inside this folder, we create two Groups, corresponding to the two different pointings inside the cluster. Create the two groups by clicking the G icon in the menu bar twice. Select each one and rename it in turn as shown in the Figure below.

In order to start with the preparation of our OBs, select the "M4 Pointing #1" (see Figure below) and click on the OB icon in the upper left corner of the P2PP main GUI. This will make the first empty OB to appear inside the M4 Pointing #1 group. The red dot with a white "X" means that the OB failed to pass some fundamental verification criteria, which is indeed our case as the OB does not contain any information yet. Like we did for the Group, select and rename the OB to "M4com_01".

With the OB highlighted, click on the Edit icon in order to open the ObsBlock window where we will define the observations.

First of all, we need a template that defines how to acquire the object, followed by one or more templates defining the exposure time and the instrument setups of our science observations.

Let's start by assigning a OD Name (Observation Description) to our first OB. It is quite important to give meaningful labels because it is very likely that your program will include several OBs, as an Observation Block is by definition the minimum schedulable unit. In the figure below we have entered the OD Name "M4com H665 UV580".

In the pull-down menu TemplateType, you can see that there are three main Template Types we can choose from: one for acquisitions, one for the science exposures, and one for calibrations (the test type is for maintenance only). Selecting any of these will update the listing in Template to reflect the different instrument modes available. For FLAMES there are only four different acquisition Templates corresponding to the three instrument modes GIRAFFE-only, UVES-only, and the GIRAFFE+UVES combined mode plus one additional template, the FLAMES_giraf_acq_argfast for the ARGUS fast acquisition mode, which is offered only in Visitor Mode.

to the top

From the Template Type list, select acquisition and subsequently FLAMES_com_acq from the Template list. Then click the Add button next to it, which adds the acquisition template to the main central part of the window, which was so far empty.

There are three fields that need to be edited: GIRAFFE config. wavelength, UVES config. wavelength, and FPOSS target setup file. For the configuration wavelengths we must specify the wavelengths which our field(s) will be configured for, usually the wavelengths at which we will be observing. Please note that the telescope will track on the GIRAFFE configuration wavelength. Depending on the target you are observing, the time at which the OB is executed and its total execution time, the difference between the Medusa and UVES configuration wavelengths (if any) may lead to increased fibre losses. This applies also to IFU+UVES combined mode. In the FPOSS target setup file field we need to read in the target setup file we have previously prepared with FPOSS (the *.ins file).

Our strategy is to use two GIRAFFE Medusa settings, HR #15N and #13, together with UVES Red_580. From the pull-down-menu corresponding to GIRAFFE config. wavelength let's start by selecting H665.0 (which corresponds to the central wavelength of setting HR#15N - please note that the default value of this field is always L385.7). As you may have noticed, there are some settings that appear to be double in the list and that can be distinguished only by a final A or B (or N, in case of HR#15). These settings have the same central wavelength, but are characterized by different spectral coverages and resolving powers. Please take a look at the table summarising all the high resolution settings of GIRAFFE. For the UVES part, we do not need to update the UVES config.wavelength because this value is defaulted to 580, which is exactly what we want.

Clicking on the FPOSS target setup file  field, a dialog window pops up from which we can select the configuration file (the *.ins file) corresponding to this program. Note that the file is recognized even if the .ins extension is missing.

Once loaded, the field will be updated with the name of the selected file (but without the .ins extension) and the Target menu in the OB window will be automatically updated with the Name, Right Ascension and Declination (see Figure). These values are read in directly from the .ins file, and they correspond respectively to the name of the target field and the coordinates of its center as specified in the header of the catalog file (the input file of our FPOSS session).

The only field in the Target package you may still want to update is the Class of the object, which is another pull-down menu, from which one can choose the category of the target to be observed (useful for archival purposes). In our case, we select GlCl. The acquisition template can then be considered completed.

to the top

Defining the Observation Template

The selection of our science template is done in a similar way as for the acquisition. We just need to select science as our Template Type, then FLAMES_com_obs_exp from the Template list, and press the Add button. As before, this will add the selected template to the central part of this window.


We can now edit the FLAMES_com_obs_exp template by specifying the number of exposures (in our case, 1 GIRAFFE and 2 UVES), the exposure times, the central wavelength of our settings (665.0 nm and 580 nm respectively), and if we want to take a simultaneous thorium-argon calibration frame while integrating on our targets (ON or OFF - in our case set to OFF, because strong Argon lines at wavelengths greater than 650 nm may affect the science spectra, as it is documented here).

Since we are interested in observing the same field also with the setting HR#13, we have now two possibilities: to attach a second science template to this OB, or to build a second separate OB for the HR#13 setting. Since our exposures are well below the 1 hour limit, and the two chosen settings are very close in wavelength, for the purpose of this tutorial, we have decided to attach a second science template to our current OB. Following the same procedure outlined above, we select a second science  template with the Add button and we edit the fields accordingly (see figure).

This almost completes our first OB! What we are still missing is to specify the constraints under which our observations will be carried out (mandatory in Service Mode), to fill out the Instrument Comments field (which is mandatory!) and to compute/update the OB total execution time.

Setting the constraints is an important step that, in the case of FLAMES, you may forget to do because the Target view, usually the first one to be filled in, is automatically updated when the configuration file is loaded in the acquisition template. So we click on the menu Constraint Set and edit the constraints (see figure below). As you can see, our science project is not very demanding: Transparency = Thin, Seeing= 1.0, Airmass = 1.6, Fractional Lunar Illumination (FLI) = 1.0, and Moon Distance = 75 degrees.

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

For the Instrument Comments field, we need to provide the magnitudes of the VLT Guide Star and of the 4 FACB stars we have selected and used in our Target Setupfile, the hour angle interval over which our fibre configuration(s) is valid, and the targeted S/N ratio at a reference wavelength (of our choice). To ease the task, one can just follow the suggested syntax. In order to determine the total execution time of the OB, we just need to click the Recalculate button to the right of the Execution Time field: by doing this, the Execution Time is automatically updated. The execution time includes all the instrument overheads associated to the execution of a given Observation Block in addition to the actual total exposure time. However, please note that any time you make a change to your OB, you must recalculate its total execution time. This is how our ObsBlock window looks, after this step is completed:


Our first OB is now ready. We can now close the OB editing window and complete the last steps. First, we need to attach a finding chart. Start by selecting the menu Finding Charts > Attach Finding Charts (see Figure below).

A new pop-up window will let you select the finding chart corresponding to this OB, which will then appear in the main P2PP GUI window. Please check the Finding Chart tutorial for detailed instructions on creating compliant Finding Charts. Secondly, we now need to verify that our Observation Block can indeed be executed. From the P2PP main GUI window, with the M4com_01 OB highlighted, let's select the menu 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. The Verification Message report appears in a pop-up window:



In this particular case, it tells us that the OB we have just prepared has been successfully verified, despite some warning messages, which one needs to evaluate on a case-by-case basis. For our purposes, the OB is OK. Please note that should you obtain error messages (compared to only warnings), you will need to resolve these errors before you will be able to Check-In your OBs to the ESO Database.

to the top

Since we want to observe each of our fields several times, we need to make more OBs. For the sake of this tutorial, let's say we need to observe each field three times, each time with slightly different fiber configuration (i.e. different FPOSS files). The easiest way in this case is to duplicate the OB already created. With the OB "M4com_01" selected, simply click the Duplicate button as many times as necessary (see Figure below). Of course you will then have to attach new FPOSS files individually and to update the Instrument Comments accordingly.

To populate the second Group, we can copy (menu Edit > Copy) one of the OBs and paste (Edit > Paste) it into the "M4 Pointing #2" group, from where we can edit it.

The last steps: verification, README file and OBs submission

With the completion of the OBs above, we consider this tutorial successfully completed. 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. Also, you may have noticed that none of our OBs has made use of the two remaining views at the top of the OB editing window, but you may need to use them for your own program. They are: Time Intervals, in case you need to specify during which time windows your observations should be carried out;  Calibration Requirements, in case you wish to comment on possible calibrations attached to your science template or on possible special calibration needs your program may have. In order to select them, just click on them. In addition there is the optional field User Comments, in case you wish to provide some extra information about, for example, your target.

The P2PP main GUI displays now the OBs we have prepared. Before submitting them to the ESO Database, we still need to compute the Total execution time of our entire program and to fill out the associated Readme file. First, let's make sure that the execution of our program will not over subscribe the OPC allocated time, by selecting Reports > Execution Time. The number we obtain here needs to be specified in the Readme file.


And now the Readme file, which needs to be Checked-In before the OBs. By clicking on the Readme button, a new pop-up window appears, where we need to fill out the various fields (by clicking on each of them, one by one, the corresponding text window will appear) and to answer some easy questions (YES or N/A). Please, see the README tutorial for more detailed instructions.

Once the Readme file is completed, it can be submitted to the ESO Database (from the pull-down menu Readme File > Check-In Readme).

Once this last step has been performed, and once we have re-verified all our OBs (from Reports > Verify) to make sure that they are error-free, we are finally ready to submit the OBs to the ESO Database: let's highlight all the OBs, and choose File > Check-In in the main GUI window. A dialog box will appear asking for confirmation and, if we click OK, the selected OBs will be saved in the ESO Database.

The success of this step can be easily verified: if our OBs have been successfully transfered to the ESO Database, they will appear with a lock-symbol in the Obs/Calib Blocks tab of our main GUI window.

Please remember when submitting the final OBs for your own run, for which you got the time allocated by the OPC, to press the 'p2pp-submit' button (the whistle icon) in order to give a signal to the Support Astronomer that your Phase 2 submission is complete.

As a courtesy to the next user who follows this tutorial, we would like to ask you to finish this exercise by removing the OBs you have created from the ESO Database. The p2pp User Manual gives you detailed instructions on how to do this. In short,

  • select File > Check-out... from the P2PP main GUI;
  • in the Database Browser window that opens soon after, type 60.A-9252(I) in the Prog ID field, select 60 as the corresponding Period and tick how many Selected Columns you prefer (note that now you can also display which finding charts have been attached to each OB);
  • click on the Query button at the lower left corner: the OBs you have saved in the ESO Database will appear in the display area;
  • select all the OBs (normally there should be only the ones you have submitted, but if another user has submitted OBs from the same tutorial account without removing them afterward you will see them as well);
  • selecting File > Check-out will remove your OBs from the ESO Database, the lock symbol will disappear from the Summaries area of your P2PP main GUI, and the OBs will now be present only in your Local Cache. Should you prefer to delete them after this tutorial, select them once more and choose File > Delete from the same window.

Instrument selector