GRAVITY P2PP Tutorial
The Phase 2 process begins when you receive an email from the ESO Observing Programmes Office (OPO) announcing that the allocation of time for the coming period has been finalized and that you can view the results by logging into the UserPortal and clicking on "Check the webletters."
Let's assume you were granted observing time with GRAVITY in service mode. To start preparing your Phase 2 material including observation blocks, instructions, and finding charts with the P2PP software, we recommend you collect all the necessary documentation first:
- The GRAVITY User Manual
- The GRAVITY Template Manual
- The VLTI User Manual
- The VLT Service Mode Guidelines
- The P2PP Documentation.
This tutorial provides a step-by-step example of the preparation of a set of OBs for GRAVITY, a 4-beam interferometric combiner at VLT-I operating in the K-band. To follow this tutorial, you should have P2PP3 installed on your computer (version 3.4.2 or higher) and be familiar with the essentials of the use of this software. Please refer to the instructions in order to install it, and to the P2PP User Manual for a general overview of P2PP and generic instructions on the preparation of Observing Blocks.
In this tutorial we will prepare a science target OB that performs the acquisition of a science target and its dispersed fringe observation in the K-band (2.0-2.4 mu) using the single-field mode and with the high spectral resolution. GRAVITY is offered in single field mode and dual field mode, where the single field is currently the most used one. The example consists of observing the Mira variable star S Orionis (Simbad coordinates RA (2000) = 05 29 00.893, Dec (2000) = -04 41 32.75, proper motions RA -11.57 mas/year, Dec -11.34 mas/year) with the baseline configuration A0-B2-C1-D0 and within the LST range 4h...7h. We expect and angular uniform disk diameter of 8 mas. Based on the Simbad or 2Mass database, S Ori has an uncorrelated K magnitude of -0.15. Using this magnitude, the baseline configuration, and the expected angular diameter, the GRAVITY ETC tells us that the observation is feasible and provides us with the Science Target minumum Correlated Magnitude and the Science Target Minimum Visibility, which we will have to enter below in the Sciene Template. These values correspond to the lowest values of the tracking delay lines:
VLTI OBs must be submitted as concatenations of science and calibrator OBs. We will thus also define an OBs that describes the observation of a calibrator for S Orionis and will construct a SCI-CAL concatenation.
The sample OBs will illustrate the use of a variety of features of P2PP and illustrate 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 VLTI and GRAVITY.
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 no thave their own P2PP login data can still use P2PP and prepare example OBs. You cannot use this account to prepare actual OBs intended to be executed (in this case you should enter the username and password of your User Portal account)
After starting P2PP and logging in using the tutorial account, the P2PP main GUI will appear. 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 in which you are PI. Select the folder corresponding to the GRAVITY Tutorial run, 060.A-9252(M). 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 GRAVITY run.
All VLTI OBs must be part of concatenations, which is a type of container in which OBs are executed in sequence. For GRAVITY, the only currently allowed sequence is SCI-CAL. Together with a waiver request also a CAL-SCI-CAL sequence can be used. This sequence may give a better absolute visibility calibration, although the interfermetric transfer function for GRAVITY has been shown to be very stable and not to depend significantly on sky position. In our example, we wish to define a regular SCI-CAL sequence. We create the concatenation container by clicking on the icon for a concatenation (labeled "C" in the icon bar). This creates an empty container of type concatenation in the GRAVITY folder. Select it, hit <Enter> and type a name for your concatenation container, such as "SOri".
You can now create your first OB within the concatenation container "SOri": Click on the icon for an OB (labeled "OB" in the icon bar), which will create an OB in your (highlighted) concatenation. The red cross next to the OB name means that the OB fails to pass some fundamental verification criteria, as expected from the fact that no template has been attached to the OB yet. Select the OB, and enter a name just like you did for the name of the concatenation. The name of the OB must follow the specific OB naming convention for GRAVITY: A science target OB must begin with "SCI_", and a calibrator OB with "CAL_" OB names should also be unique across different runs of the same programme.
To select for each science target a calibration target, ESO offers the CalVin tool . CalVin selects suitable calibrators based on different user criteria. Ideally you would wish to have a calibrator star that is unresolved and/or of well known diameter, close on sky to your science target, and of similar brightness. GRAVITY commissioning observations have shown that the interferometric transfer function for GRAVITY seems to depend less on sky position and brightness than for other VLTI instruments. Consulting the CalVin tool you find that the star 31 Ori (HD36167) is a suitable calibrator for your science target S Ori.
We start with creating the science star OB and name it SCI_SOri:
In the next steps, we have to edit the OB information. To start this, click on the "Edit Observation Block" button in the icon bar. This will display the "View OB" window, as shown below. (Alternatively, you can click Edit in the Edit menu, or double-click on the OB name.) We have already entered into the OD Name field an observing description which is useful when having observations of a number of targets performed with identical instrument configuration and observation template parameters. The OD name appears in turn in the Summaries area of the P2PP main GUI, thus allowing the identification at a glance of all OBs having ODs with the same name.
This is the window where you will define the contents of your OB. In the following, we will in turn perform each of the four tasks by clicking the corresponding icon at the top of the "View OB" window, i.e. the Obs. Description, Target, Constraint Set, and Time Intervals tasks.
The first template that must be part of any OB is the acquisition template. You see that there are two acquisition templates available for GRAVITY: GRAVITY_dual_acq and GRAVITY_single_acq, for the dual field and single field modes, respectively. We observe our target in single field mode. We highlight GRAVITY_single_acq and click the <Add> button next to it. The window should now look like this:
We have already entered the required values for our observation of S Ori:
- SC object name: SOri
- SC object correlated magnitude: 0.65 (The K magnitude of S Ori is -0.15. GRAVITY tracks on the 4 highest visibilities, which go down to about 0.7 with the short quadruplet according to the GRAVITY ETC, see above. The correlated magnitude is then -0.15-2.5*log10(0.69)=0.65 as also directly provided by the ETC, see above.)
- FT object diameter (mas): 8
- SC object visibility: 0.69
We provide the H mangitude of S Ori, which is the brightest target in the field, and provide its parallax:
- AcqCam guide star magnitude in H: 0.3
- SC object parallax (arcsec): 0.89
We set the instrument setting to high spectral resolution. We decide to put the Wollaston prisms IN, because our target is bright enough. Note that both Wollaston prisms need to be set to the same value:
- Science spectrometer resolution: HIGH
- Fringe-tracker spectrometer Wollaston: IN
- Science-spectometer Wollaston: IN
The next 5 fields correspond to the Coude guide star for STRAP/MACAO. The values for "RA/DEC of guide star if COU guide star is setupfile" are used in cases where the FT target is not bright enough to serve for coude guiding and an off-axis guide star is provided. In that case "COU guide star:SETUPFILE" is chosen. The parameter "GS mag in V" is set to the V magnitude of the target that is used for Coude guiding, whether it is the FT target itself or an off-axis guide star. In our case, S Ori with V=7.2 can serve as a guide star, so that we choose
- Coude guide star (GS) input: SCIENCE
- GS magnitude in V: 7.2
and leave the other GS parameters at their default vaules. Note that for dual-field more COU guide star:SETUPFILE has to be chosen in any case because the template automatically points in between the FT object and the SC object and is not at the position of either of them.
In the TemplateType list, select "science". In the case of GRAVITY, "science" refers to recording scientific data on a science target. There are two templates "GRAVITY_dual_obs_exp" and "GRAVITY_single_obs_exp", for the dual field mode and single field mode, respectively. Since we are preparing an OB for a science target in single field mode, select the "GRAVITY_single_obs_exp" template and click Add. The corresponding templates for calibrator observations are organized under TemplateType "calib". After editing the values the window should now look like this:
The recommended DIT for our settings is 5 sec according to Table 1 of the template manual (Single-field, HR, Split, AT, K=-0.15). According to Table 1 we can best fill our standard allocated time of 30 minutes per OB by using a OSOS sequence with NDIT=50. This way, we spend half of the time on SKY and half on OBJECT, which is good. Since our target is a single isolated target, we can leave the sky offsets at their default values.
In the TemplateType list, select "calib". As mentioned above, you see two templates available for recording of data of a calibrator in single field mode and dual field mode. There are no other calibration templates available for instrumental calibrations. Thus, we do not need to add calibration templates for our GRAVITY observation.
Click on the Target icon at the top of the OB view window in order to insert your target name and coordinates. Here please insert the target name of the FT object. Because we use the single-field mode, the FT object is identical to our science object S Ori. We should use the same name as used for "FT object name" in the acquisition template. For dual field mode, we would enter here the coordinates of the FT object, and would specify offsets from the FT object to the SC object in the acquisition template. Enter also the right ascension and declination for the FT object. In the case of VLTI observations, coordinates as precise as possible are essential so that the optical path difference to find the fringes can best be predicted. Therefore, please enter as well the proper motions of the target in arcsec/year (unless not known). Furthermore, edit the entry in the Target-tabbed subpanel Class. In our case, choose "Mira". The fields Diff. RA and Diff.Dec are used for differential tracking (solar system objects, for instance), and in our case we leave them with the default values of 0. The acquisition template including the target information is now complete, and the Target view should look like this:
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 set of constraints which indicate under which conditions your OB can be executed.You can do this by clicking on the Constraint Set icon.
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 fringe observations using the single field mode and the high spectral resolution, you type "Fringe_Obs_SF_HR_Constraints" in the Name field.
The GRAVITY instrument webpage lists the conditions that are required for GRAVITY observations. They generally require that the Sky Transparency condition is "Clear".
Like for the Sky Transparanecy, the GRAVITY instrument webpage tells us that a bright target does not need stringent seeing conditions. We enter Seeing better than 1.5 arcseconds, corresponding to no seeing constraint.
Note that in your Phase 1 proposal you already specified some of these constraints (sky transparency and seeing) according to the requirements of the GRAVITY instrument webpage. You must make sure that none of the constraints specified in Phase 2 is more stringent than the corresponding ones specified at Phase 1.
Finally, choose for Baseline the quadruple that you asked for at Phase 1. In our example, we enter A0-B2-C1-D0.
A number of other constraints like airmass, moon constraints, Strehl, PWV are displayed in light grey. These are not a part of the GRAVITY-specific constraint set, and can thus not be set.
Your constraint set view should now look like this:
Click on the Time Intervals icon. Here you can specify both absolute time intervals (left tab) and sidereal time intervals (right tab). The former are optional and can be used to allow execution of this OB only within the windows specified, for example if the observations have to be coordinated with another facility. The latter are mandatory for VLTI observations and correspond to the LST interval during which the target is observable according to the GRAVITY ETC (taking into account shadowing of the target by domes of the 8-m telescopes, the limited range of the delay lines, and the altitude of the target).
To define time intervals, do the following:
- Select the Time Intervals icon
- Choose the Time Intervals tab (we will fill the Sid. Time intervals tab later)
- Click on the checkbox New TI
- Modify the start interval to the specified starting date of your time window.
- In the same way, modify the end entry
- Press OK
The Time Interval view should now look like this:
If your observation could be executed in other, non-contiguous time windows, you could add further time intervals in the same way as described. However, we also wish to remark that setting time intervals for an OB, and thus narrowing the possible execution time dates, limits the possibility that your OB will be successfully executed during the observing period. Remember that there are only limited service mode time windows over the period, and that VLTI baselines are scheduled block-wise at certain dates only. It is advisable to double-check the service mode schedule to make sure that the requested baseline configuration is indeed available during your time interval. Your support astronomer will be happy to help you with this.
In principle, P2PP3 allows us to specify relative time links between OBs using time link containers. However, VLTI observations are already required to make use of concatenation containers to specify the sequence of science OBs and calibrator OBs. This also means that for VLTI observations the functionality of relative time link containers can not be used (containers of containers are not yet offered). In cases where relative time links between VLTI observations are needed, these should as far as possible be translated into absolute time intervals just as described above, making use of the known block-wise schedule of baseline configurations, or else be described in the ReadMe. Again, your support astronomer will be happy to assist.
All VLTI OBs must have sideral time constraints defined within which the desired projected baseline length and angle are reached and within which the observation is feasible in terms of altitude, shadowing effects, and delay line limits. The required information can be obtained using the GRAVITY ETC (maintained by ESO), but also by external tools sich as ASPRO (maintained by JMMC). Under the Sidereal Time tab you must specify this constraint on the the LST range. Here, we wish to prepare an OB that should be executed between 02h3min < LST < 08h00min, hence you do the following:
- Select the Sidereal Time tab
- Specify the LST interval just like you did before with the absolute time interval.
In the same way you could define additional LST slots, as alternative(!) LST ranges. Please note that defining more than one sidereal time ranges in this field does NOT mean that the OB will be executed multiple times at each these LST ranges, but only once within any of the non-continous slots. Please note that for the sake of efficient observations each slot needs to span at least 1.5 hours, a dead time needs to last more than 1 hour, and the total specified LST interval should last for at least 3 hours.
Now that you have completed the definition of the OB, you have to attach the a Finding Chart(s) to the OB. The Finding Charts must be prepared as jpeg-files and must fulfill all general and GRAVITY specific requirements for finding charts. You can use any tool of your choice to create the Finding Charts in jpeg-format. P2PP, however, does not contain such an option.
Let's assume you have prepared a jpeg-Finding Chart for this tutorial run [remember: run ID 060.A-9252(M)], which you called 060.A-9252M.SOri01.jpg, and which is saved in a sub-directory of your home directory.
Now, in the P2PP main GUI click on the OB which you want to associate with this finding chart, then select Finding Charts from the top menu bar, which opens a drop-down menu:
From the drop-down menu select Attach Finding Charts, which will open up a new window that allows you to enter path and filename of the Finding Chart you wish to attach to the selected OB. In our example you choose 60.A-9252M.SOri01.jpg and finally click on the Attach Finding Charts button (you could select more than one Finding Chart). The pop-up window will close and the Summaries area of the P2PP main GUI will show the entry
- FindingCharts: (1) 060.A-92..
If you are interested in a more comprehensive explanation on how to create and attach or detach finding charts, you should have a look at this page.
Now, with the first OB of the concatenation completed, you will need to add the calibrator OB next. This follows the same procedure as for the science target, except that your OB name is CAL_31Ori and that your fringe recording template is GRAVITY_single_obs_calibrator, which you find for GRAVITY under the calib tab. Of course, you enter the name, the coordinates, and the properties of 31 Ori instead of those of S Ori.
Please make sure you define the LST interval of the calibrator OB to last 30 minutes beyond that of the science OB, so that there is still a calibrator to be observed if the science target is observed at the upper edge of its interval. This means that the LST interval of 31 Ori should be defined as 02h3min < LST < 08h30min.
Please make sure that the instrumental settings and baseline configurations are the same for the science target and the calibrator, i.e. we also choose the high spectral resolution, Wollastron prisms IN, and the short baseline A0-B2-C1-D0. Note that, unlike for other VLTI instruments, the DIT does not need to be the same for science target and calibrator. For 31 Ori with its magnitude of K=0.8, the recommended DIT is 5 sec, so that we choose DIT=5 sec, NDIT=40, and a OSOSO sequence.
Before submitting the concatenation to the ESO data base, please verify it by first selecting the concatenation, and then clicking the Verify button (the one with the Stamp icon we just placed above the verification report for the screen show shown below). The report contains important and useful information and checks rules for both concatenations (if the concatenation was selected prior to creating the report), and for the OBs.
In our case, we get a warning that the science taget S Ori is not included in the Phase 1 database for this run, which is normal for the tutorial account. Otherwise, no warnings or errors are shown, and our concatenation is ready for submission to the ESO database.
Before we can check our SCI-CAL concatenation into the ESO database, we must make sure that the OBs of our concatenation are in the correct order. To change the order of the OBs, we mark an OB in the main GUI, do a right-click, and use the Move Up or Move Down fields:
We will now check this OB concatenation into the ESO Database: select the concatenation in the Summaries list, 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, they will be saved in the ESO Database. A lock symbol will displayed next to your OBs indicating that you cannot modify the OB definition unless you check out the OB from the data base (after contacting USD to release all OBs of the concatenation).
The complete Phase 2 material includes also the ReadMe file. The ReadMe file has to be prepared with p2pp and also has to be checked into the ESO data base (look at Readme menu). A tutorial for the ReadMe file is available here. When all the OBs and the ReadMe file for a given run are checked in, the Phase 2 submission must be finalized by pressing the p2pp-submit button (the whistle icon in the main P2PP GUI).
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. By the way, the same procedure would have to be followed should you need to modify your OBs after checking them in, because this action will also lock them. The P2PP User Manual gives you detailed indications on how todo this. In short,
- Select Check-out... from the File menu in P2PP.
- In the Database Browser window that opens, type 060.A-9252(M) 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 concatenation 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.
GRAVITY P2PP Tutorial
- 1: Phase 2
- 2: Goal of the tutorial
- 3: Creating an OB container and defining OBs
- 4: Attaching Finding Charts
- 5: Completing the concatenation and verification
- 6: Submitting the OBs and ReadMe