AMBER P2PP Tutorial
This tutorial provides a step-by-step example of the preparation of a set of OBs for AMBER, the near-infrared interferometric phase-closure instrument for the VLTI. Since P90 AMBER OBs have to be created as part of concatenation containers using the new P2PP3. To follow this tutorial, you should have a P2PP3 installation on your computer (as of P91 version 3.3.2) 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 K-band (2.3 mu) medium spectral resolution 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 A1-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 AMBER. If you have prepared OBs for MIDI before, you will see that many aspects regarding interferometric calibrators, the definition of the baseline configuration, and the setting of sidereal time constraints are very similar for MIDI and AMBER.
The Phase 2 process begins when you receive an email from the ESO Observing Programmes Office (OPO) telling you that the allocation of time for the coming period has finalized and that you can view the results by logging into the UserPortal and clicking on "Check the webletters." 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 AMBER. Therefore, you decide to start preparing your Phase 2 material. First, you collect all the necessary documentation:
- The AMBER User Manual
- The AMBER Template Manual
- The VLTI User Manual
- The VLT Service Mode Guidelines
- The P2PP Documentation referred to above.
and you proceed with the installation of P2PP on your machine if necessary.
All VLTI OBs must be part of concatenations, which is a type of container in which OBs are executed in sequence. For the VLTI, the allowed sequences are CAL-SCI-CAL and SCI-CAL. The latter can be used if the main goal of the observation is a wavelength-differential measurement and if an absolute visibility calibration is not the main goal. In our example, we wish to define a CAL-SCI-CAL sequence.
You decide to start with the definition of a concatenation and within the concatenation to start with an OB for your science object.
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.
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 AMBER Tutorial run, 60.A-9253(J) (this will also show the icons near the top in color):
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 AMBER run.
First, we create the concatenation container. Click on the icon for a concatenation (labeled "C" in the icon bar). This creates an empty container of type concatenation in the AMBER folder. Select it, hit <Enter> and type a name for your concatenation container, such as "SOri-1".
You can now start defining your OBs within the concatenation container "SOri-1": Click on the icon for an OB (labeled "OB" in the icon bar), which will create an OB in your concatenation. The red 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. 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 AMBER: A science target OB must begin with "SCI_". OB names should also be unique across different runs of the same programme. We assume for this tutorial example that S Orionis shall indeed also be observed with another run and furthermore that there will be another observation within this run. We choose the OB name "SCI_SOri-J1", because this is the first science OB for our AMBER run 60.A-9253(J). Hence, type SCI_SOri-J1 in the Name field:
In the next step, 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 -> Edit in the file menu, or double-click on the OB name.
This is the window where you will define the contents of your OB.
It may be useful in many cases to have an easy way of identifying an OD (Observation Description), like when having observations of a number of targets performed with identical instrument configuration and observation template parameters. The OD Name field in the View OB window allows you to define names for the ODs. 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. In this tutorial the observation description will define the use of the K-band (2.3 mu) medium resolution mode for the fringe observations. Thus, we enter the name Fringe_obs_medresK2.3 in the OD Name field.
The User Comments field can be used for any special requirements that you want the staff on Paranal to be alerted to, however, in most cases, this information should be part of the ReadMe attached to this OB, or should be included in the Calibration Requirements tab (see below). Since we don't have any special comments for this example, we leave this field blank.
For the VLTI instruments, the Instrument Comments field can be used to mention alternate baselines that may be used if the preferred baseline is unavailable. In our case we prepare an OB using A1-C1-D0, which will be inserted in a dedicated field below. However, we found that the triplet B1-C1-D0 gives a similar uv point and can be used as an alternate baseline. We thus enter "B1-C1-D0" in the Instrument Comments field.
The first template that must be part of any science OB is the acquisition template, so let us define it next. In the TemplateType list, click the acquisition entry. This will list all the acquisition templates available for AMBER in the Template list next to it. AMBER_3Tstd_acq is already highlighted as it is the only acquisition template available for AMBER. Click the Add button next to it. The window should now look like this (with some fields already set to default values):
Now, you need to decide on the acquisition parameters, and if necessary, modify the default values given in the acquisition template.
The first four fields in the acquisition template are the uncorrelated magnitude and minimum source visibility, for the H and K bands respectively. The numbers for the H-band, Source uncorrelated H magnitude and H minimum source visibility, are important parameters if the H-band fringe tracker FINITO is to be used as the fringe sensor (see below). We insert the values for S Ori, which are -0.01 and -0.5 for the uncorrelated magnitudes in H and K band, respectively. The expected source visibility values can be calculated using the Visibility Calculator VisCalc. We assume that you found 0.6 and 0.7 for the minimum visibilities (on the two shorter baselines), respectively:
- Source uncorrelated H magnitude: -0.01
- H Minimum source visibility: 0.6
- Source uncorrelated K magnitude: -0.5
- K Minimum source visibility: 0.7
The next fields are related to the source used for Coude guiding. Since your science target, S Ori, is at V=9.2 sufficiently bright in the visual it can be used for coude guiding itself. Therefore you choose the following parameters in your acquisition template:
- RA of guide star if COU guide star is setupfile: 0. (Default value)
- DEC of guide star if COU guide star is setupfile: 0. (Default value)
- Epoch: 2000 (Default value)
- Equinox: 2000 (Default value)
- COU guide star: SCIENCE (Default value)
- GS mag in V: 9.2
- Off-axis Coude Proper Motion Alpha: 0.0 (Default value)
- Off-axis Coude Proper Motion Delta: 0.0 (Default value)
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.
The fringe tracker FINITO must be used for Amber medium resolution observations. We thus select:
- Fringe sensor: FINITO
The next field to fill out in the acquisition template is Science or calibrator, which obviously must be SCIENCE since this is your science OB.:
- Science or calibrator: SCIENCE
The last field Standard spectral configuration sets the spectral configuration for your whole OB. Since in this example we write an OB for the K-band (2.3 mu) medium resolution mode, we choose
- Standard spectral configuration: Medium_1_2.3
Your window should now look like this:
At the top of the view window, next to Obs. decription you find the Target field where 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, in other words, insert Name: SOri. Also, enter the right ascension and declination for S Ori. 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 tab and filling the entries under it:
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 AMBER instrument webpage lists the conditions that are required for AMBER observations, depending on the correlated magnitude of the target. In our case, the required Sky Transparency condition is Variable, thin cirrus and we select this condition from the pull-down menu.
Like for the Sky Transparency condition, the AMBER instrument webpage tells us that a Seeing condition better than 1.2 arcseconds is required for the correlated magnitude of our target.. Hence we insert a Seeing 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 AMBER 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.
Let's assume that time has been allocated for your Amber run on the AT baseline quadruplet A1-B2-C1-D0. You must now choose one of the triplets of this quadruplet. For the example of this OB we choose the Amber triplet A1-B2-C1 from the baseline drop-down menu.
A number of other constraints like airmass, moon constraints, Strehl, PWV are displayed in light grey. These are not a part of the AMBER-specific constraint set, and can thus not be set.
Your constraint set view should now look like this:
We will assume now that your AMBER observations are part of a larger multi-wavelength project and that the AMBER observations should be carried out +/- 2 weeks around VLBA observations that are scheduled for December 14, 2012. You can specify this as follows:
- 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 present case, the entry should read 2012-12-01. We choose a UT start time on that day of 00:00
- In the same way, modify the end entry to 2012-12-29 at 00:00
- 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 wished, 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. Under the Sidereal Time tab you must specify this constraint on the the LST range. In this tutorial example, the feasible LST range lasts from LST 2:20h to LST 8:40h. You wish to prepare an OB that should be executed between 04h < LST < 07h, 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.
The acquisition and the titems Target, Constraint Set, Time Intervals, and Sidereal time are now completed. We will next insert the science template(s).
We go back to the Obs. Description field. On Template Type, select now science. The existing AMBER science templates will appear. Select the template AMBER_3Tstd_obs_1row (actually, the only template available) and click on Add. The template will be attached to the grid below next to the acquisition template selected and filled previously.
The first field of this science template is the integration time Frame integration time (DIT in s). The AMBER template manual tells us that the recommended DIT for the correlated magnitude of our target and the chosen instrument mode is 0.2 sec and you enter 0.2 (if your calibrator is much fainter, you might have to increase the DIT to satisfy the minimum requirement and have the same integration time for science and calibrator targets):
- Frame integration time (DIT in s): 0.2
The next two parameters of the science template are the offsets in RA and declination for taking the sky background. If you notice that the default offset would result in a position where another star (or any source of none pure sky emission) is present, you should change these parameters. In our example, we leave these values at their defaults:
- Sky telescope offset in Alpha (arcsec): 0. (Default value)
- Sky telescope offset in Delta (arcsec): 30. (Default value)
Finally, we have to define the covered wavelength range for our observation. Since the use of FINITO allows for long integration times, the full detector can be read out and we leave the default values:
- Row1: max wavelength in um : 9999.0(default)
- Row1: min wavelength in um : 0.0 (default)
The only other thing that you should really do at this point is to check the execution time for this OB. On the top part of the window, below the Instrument Comments field and above the Template Type field, you will finda field Execution Time and right next to it a button labeled Recalculate. Upon clicking on that button the calculated OB execution time appears in the display to the left of the button. In this case the total execution time is 00:25:00.
This (almost) completes your first OB! If you followed all the indications given so far, the window should look like this now.
You can now close this View OB window and you are left with the P2PP main GUI. In there, you should see an entry under your run with the following contents:
- Name: SCI_SOri-J1
- Local ID: set to a number of your local installation
- ESO Id: empty
- Status: (P)artiallyDefined
- Target: SOri
- OD: Fringe_obs_medres
- CS: Fringe_obs_constraints
- Acquisition: AMBER_3Tstd_acq
- FindingCharts: (0)
You can resize the columns as indicated in the P2PP User Manual to view the full contents of each entry.
The next thing to do is to attach the respective Finding Chart(s) to the OB. The Finding Charts must be prepared as jpeg-files and must fulfill all general and AMBER 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.
Since each science OB must be combined with a calibration OB we will briefly demonstrate how to define the calibrator OB. The necessary steps are very similar to the definition of the science OB.
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.
You can either repeat the steps as outlined above, i.e. you start defining your calibrator OB by clicking on the New button on the upper left side of the P2PP main GUI, or you can duplicate the science OB by 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.
Calibration stars must have an LST range that covers the complete LST interval of the science target (4:00-7:00) and extend it by 30 minutes as indicated in the following figure:
Here, we will use the same calibrator for the OB that precedes the science OB and that follows the scioence OB. Therefore, we use an LST range of 3:30..7:30 for both calibrator OBs (alternatively, the CAL preceding SCI may have an interval 3:30-7:00 and the CAL following SCI may have an interval 4:00-7:30).
First, make sure the OB name is updated (we choose CAL_SORI-J1) and that the calibrator target name is updated in the target information section (31Ori). In the latter, enter the correct target coordinates and proper motions for the calibrator. In the Instrument Comments field we now mention the name of the associated science OB (SCI-SOri-J1).
Update the magnitude and minimum visibility information, and also enter the V magnitude of HD 36167 in the filed GS Mag, which is 4.7 (Coude guiding on the target HD36167 itself can be used again) and the H and K magnitudes, which are 1.0 and 0.8. We have to set the Science or calibrator field obviously to CALIB. You therefore change the following fields:
- Source uncorrelated H magnitude: 1.0
- H Minimum source visibility: 1.0
- Source uncorrelated K magnitude: 0.8
- K Minimum source visibility: 1.0
- GS mag in V: 4.7
- Science or calibrator: CALIB
All other fields remain with the same values as for S Ori.
Concerning the actual observation, we choose as well the template AMBER_3Tstd_obs_1row, and use the same settings as for the science target S Ori and enter:
- Frame integration time (DIT in s):0.2 (same as science target)
- Sky telescope offset in Alpha (arcsec): 0. (Default value)
- Sky telescope offset in Delta (arcsec): 30.
- Row1: max wavelength in um : 9999.0
- Row1: min wavelength in um : 0.0
Finally, your Observation Description should look like this:
Your target information should look like this:
The Constraint Set and Absolute Time interval are the same as for S Ori. The Sid. Time Interval looks like this:
You close the OB view window and perform the final step, which is attaching a Finding Chart to your calibrator OB. The name of the Finding Chart that you have created is 60.A-9253J.31Ori.jpg. This completes your first calibrator OB!
Since we wish to create a CAL-SCI-CAL sequence, and for this example wish to observe the calibrator 31Ori before and after the science target S Ori, we duplicate our calibrator OB and name it CAL-SOri-J2.
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:
Finally, our CAL-SCI-CAL concatenation should be visible in the main P2PP3 GUI like this:
You may want to check the total execution time of your CAL-SCI-CAL concatenation, and run a verification check on it. To do so, mark the concatenation (C SORI-1), and choose from the Report menu Execution Time and Verify, respectively.
With the completion of the CAL-SCI-CAL concatenation, we consider the example developed in this tutorial to be finished.
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.
Our tutorial with this example of creating and checking in the OBs for one science target/calibration star pair ends here. For the preparation of the Phase 2 material for a whole run, more OBs may have to be created. Remember, the complete Phase 2 material includes also the ReadMe file. The ReadMe file 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 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.
AMBER P2PP Tutorial
- 1: Goal of the Run
- 2: Getting Started
- 3: Your First OB
- 3.1: Define an OB with P2PP
- 3.1.1: Filling in the basic information
- 3.1.2: Defining the acquisition template
- 3.1.3: Inserting target information
- 3.1.4: Setting the constraint set
- 3.1.5: Setting the time intervals
- 3.1.6: Setting the constraints on the sidereal time
- 3.1.7: Setting the calibration requirements
- 3.1.8: Defining the observation description
- 3.1: Define an OB with P2PP
- 4: Attaching Finding Charts
- 5: Defining the Calibrator OB
- 6: Finishing the preparation and submitting the OBs