PIONIER 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 time allocation information" under the Phase 1 header.
Let's assume you were granted observing time with PIONIER 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 PIONIER User Manual
- The PIONIER 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 PIONIER, the near-infrared 4-telescope beam combiner for the VLTI. 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 fringe observation in the H-band (1.7 mu) using the GRISM mode. 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. VLTI OBs must be submitted as concatenations of science and calibrator OBs. We will thus also define two OBs that describe observations of a calibrator for S Orionis and will construct a CAL-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 PIONIER.
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 PIONIER Tutorial run, 60.A-9253(T). 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 PIONIER run.
All VLTI OBs must be part of concatenations, which is a type of container in which OBs are executed in sequence. For PIONIER, the allowed sequences are CAL-SCI-CAL and CAL-SCI-CAL-SCI-CAL. The latter can be used for a time-saving sequence providing improved aperture coverage. In our example, we wish to define a CAL-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 PIONIER 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 PIONIER: 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 as close as possible to and of similar brightness as your science target. Consulting the CalVin tool you find that the star 31 Ori (HD36167) is a suitable calibrator for your science target S Ori.
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 "Viw 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. In the TemplateType list, select "acquisition". PIONIER_acq is already highlighted as it is the only acquisition template available for PIONIER. Click the Add button next to it. The window should now look like this (with some fields already set to default values):
We already entered the V magnitude of our target for GS mag in V, since we do not require an offset Coude guide star. The H magnitude of the target has to be entered in the bottom line.
The values for "RA/DEC of guide star if COU guide star is setupfile" are used in cases where the science 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 target itself or an off-axis guide star.
In the TemplateType list, select "science". Here, "science" just refers to the template recording scientific data, be it data from a calibrator or a science target. Since we are preparing an OB for a calibrator observation, select the "PIONIER_obs_calibrator" template and click Add. There is nothing more to do for this template.
In the TemplateType list, select "calib". You see two templates available, one for recording the kappa matrix and one to take a dark. Both need to be attached, in this order, to the Obs. Description. The image below shows the kappa template attached. Please clear the check box for "Do calibration?" in this template for all other OBs in the concatenation as the kappa template should only be done once per concatentation, preferably on the brightest target!
The image below shows the fourth and last template of the OB, the dark template. It has to be enabled ("Do calibration" check box checked) for all OBs.
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, which should be the same name as used in the OB naming. Also, enter the right ascension and declination for the target. 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 "Star". 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, you type "Fringe_Obs_Constraints" in the Name field.
The PIONIER instrument webpage lists the conditions that are required for PIONIER observations, depending on the correlated magnitude of the target. In our case, the required Sky Transparency condition is "Variable, thin cirrus".
Like for the Sky Transparanecy, the PIONIER instrument webpage tells us that a Seeing better than 1.2 arcseconds is required for the correlated magnitude of our target. Hence we insert a value of 1.2.
Note that in your Phase 1 proposal you already specified some of these constraints (sky transparency and seeing) according to the requirements of the PIONIER 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.
A number of other constraints like airmass, moon constraints, Strehl, PWV are displayed in light grey. These are not a part of the PIONIER-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 VisCalc tool (taking into account shadowing of the target by domes of the 8-m telescopes, and the limited range of the delay lines).
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 calibrator OBs and science OB. 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. 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 visibility calculator VisCalc (maintained by ESO), but also using 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 03h < LST < 06:30h, 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 PIONIER 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 60.A-9253(J)], which you called 60.A-9253J.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-9253J.alfori01.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) 60.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 would need to add the science OB next, and finally another calibration OB. The latter can be created more quickly by selecting the calibrator OB and clicking on the Duplicate button. By duplicating your existing OB, the only fields that you need to modify are of course the ones related to the target, but not the instrumental setup. Don't duplicate the calibrator OB to create the science OB as the science template is different.
Please make sure you define the LST intervals of the 3 OBs in the concatenation according to the following scheme. Calibration stars must have an LST range that covers the complete LST interval of the science target and extend it by 15 minutes as indicated in the following figure (white squares indicate optional extensions):
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.
Before we can check our CAL-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 60.A-9253(J) 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 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.
PIONIER 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