Screenshots for this tutorial were made using the demo mode of p2, but should not differ in any way from one's experience in preparing your own OBs under your run.

0: Goal of the Run

In this tutorial we will prepare OBs for a simple example observing run, consisting of 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 p2 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 XSHOOTER. In this imaginary observing programme, 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 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 XSHOOTER. Therefore, you decide to start preparing your Phase 2 material. First, you collect all the necessary documentation:

• The XSHOOTER User Manual.
• The VLT Service Mode instructions.
• The documentation to the help section about p2 referred to above.

2: Making OBs

2.0: p2

For the sake of this tutorial, we will use the p2 demo facility: https://www.eso.org/p2demo

This is a special facility that ESO has set up so that users who do not have their own p2 login data can still use p2 and prepare example OBs (for example, while writing a proposal to get the overheads right!).  You cannot use it to prepare actual OBs intended to be executed.  When you prepare such OBs you should use your ESO User Portal credentials for p2 (with http://www.eso.org/p2).

After directing your browser to the p2 demo facility the main p2 GUI will appear as follows:

Runs for a number of instruments appear in the lefthand column, since the p2 demo facility is used for all of them.  Similarly, if you log into p2 (instead of p2demo) with your own ESO User Portal credentials, you will get the list of all the runs for which you are PI, or for which you have been declared as a Phase 2 delegate by the respective PI(s).

The newly created concatenation will automatically be selected and displayed in the main part of the window. As for the case of the new folder you must click on the blue name field near the top to rename the Concatenation.

Hence, please rename the concatenation to "eta Car at 37.5 and 127.5 deg"

3: Editing the OBs

When an OB is selected on the left hand side of the p2 window, its content is displayed on the right hand side. On the snapshot above, the OB "eta Car at 37.5 deg" is selected (highlighted in blue). The relevant fields to be edited to finalize the creation of an OB are included in the "Obs. Description/Target/Constrain Set/Time Intervals/Finding Charts/Ephemeris" tabs. Select these tabs to design the OB by editing templates, target information, constraint set information, uploading FCs and Ephemeris files. A check of the Target Visibility is also possible. 

3.1: Setting the target information

By default, the newly selected OB is displayed in the "Obs. Description" tab. To enter the target information, click the "Target" tab near the top of the window. In the Name field, type the target name "eta Car". By pressing the "Resolve" button, the coordinates and proper motions of a known astronomical target will be automatically inserted in the OB.
If the target is unknown, it is possible to type in the Right Ascension and Declination fields the ICRS or FK5 coordinates. Since the coordinates are given for both Equinox J2000 and Epoch 2000, leave these fields with their default values. Wherever possible provide the Proper Motions of target, preferably from Gaia -- remember the units required in p2 are arcsec/yr where as most catalogues list milli-arcsec/yr.
Differential tracking of the telescope is not needed for eta Car since this is not a moving Solar System target. Therefore, you can leave the last two fields in the Target tab set to their default values of zero.

3.2: Setting the constraint set

If your programme is in Visitor mode, you can ignore this section since you do not need to set the constraints for Visitor Mode OBs. 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" tab and filling the fields accordingly.

First, give a descriptive name to the constraint set about to be defined. In this case we choose "etaCar-THIN" for the Name field.

Your actual constraints then need to be set to be compatible with what you specified in your Phase 1 proposal, and at the same time consistent with the scientific goals of you project, the awarded time and the OPC ranking of your run. As a rule, you can not set stricter constraints than you specified in your proposal, but you can relax the constraints compared to your proposal (see the policy here). In general you should try to relax the constraints as much as possible (in order to maximise the chances for execution) whilst balancing the constraints and exposure times in order to still achieve the S/N you need to achieve your science goals.

Also consider that while we guarantee that IF your Obs are executed, they will be executed within 10% of your constraints, they could well be executed in significantly better conditions. So if you have very relaxed constraints, you may wish to consider nonetheless several short exposurs, rather than one long exposure, in order to avoid the possibility of saturation in case the OB(s) is(are) executed in significantly better constraints than specified -- Alternatively, you can note in your README strategies that the observatory could employ to avoid saturation in such cases (e.g. "If executing in significantly better conditions than the constraints please decrease expsoure times to avoid saturation whilst maintaining the targeted S/N.")

Since in your proposal you specify "Seeing" through a Turbulence Category, i.e more or less the image quality at the zenith in V-band, but in your OBs you must specify Image Quality, the number you put in the Image Quality field of the OBs will not in general be the same as the Seeing value you specified in the proposal through the Turbulence Category. In general for observations bluer than V-band you will eed to specify a poorer image quality than the Phase 1 seeing you specified, while for observations redder than V-band, you can often specify and Image uality constraint better than the Phase 1 seeing you specified.

You can use the ETC to check what is the appropriate Image Quality constraint to specify for the phase 1 seeing you specified. It is also often useful to experiment with the ETC with different combinations of airmass, moon illumination and distance, sky transparency and perhaps image quality to see how to best optimise the probability for successful execution of your OBs.

Alternatively you can also use the Check function of p2, which will tell you if you have specified an Image Quality that is not consistent with your Phase 1 seeing, though you can't do this till the OB has at least a basic complete definition (see below).

So having experimented with the ETC for our present case  we set the constraints as follows in order to achieve our science goals: Sky Transparency = "Variable, thin cirrus", Airmass = 2.4,  Image Quality = 1.6, Lunar illumination = 1.0, Twilight (min) = 0 and Moon Angular Distance = 30 (degrees). Please note that Eta Car, the target of this OB, is a very bright object (V=6.2). Hence the choice of a very high airmass limit (2.4). Please notice that in most cases a much lower airmass limit is reccomended. Please note that the XSHOOTER's ADCs compensate for atmospheric dispersion in order to minimize slit losses and allow orienting the slit to any position angle on the sky up to a zenith distance of 60deg (airmass 2).

Go to the top of the page

3.3: Setting time intervals

We will assume now that the spectroscopy of Eta Carinae has to be obtained in Jan 2019, since you will have simultaneous observations at other wavelengths during that time interval.
You can specify this by clicking the Time Intervals tab. Using the "Add" button and the fields/calendars you can set the time interval:

When clicking OK, the time interval is entered into the OB. If your observation could be executed in other, non-contiguous time windows, you can define multiple intervals in the same way as described.

Here we note two important matters:

• If your observation could be executed in other, non-contiguous time windows, you could define more intervals in the same way as described.
• The timeline associated with the Absolute Time Constraints tab will not display useful content for the demo of p2, but will, of course, provide useful content for "real" runs.
  

Note that such time critical aspects must also be explained in the section on "Time Critical Aspects" of the Readme. It is not sufficient to enter the constraints only here.

Go to the top of the page

4: Designing the Observations: OB templates in the Obs. Description

After clicking on the Obs. Description tab you see three free-text fields at the top: Observation Description Name (or OD for short), User Comments, and Instrument Comments.  

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.  

In this example OB, the OD will consist of a a single spectrum of eta Car at a specific position angle. We can thus appropriately name it eta Car at 37.5 deg. We enter this name in the OD Name field.

The User Comments field can be used to communicate brief details of the observations (which should be explained in more detail in the README).  Finally, in the Instrument Comments field you should enter the expected signal-to-noise ratio and the preferred spectral type for the telluric standard star (only if requeted in Phase 1), using the following syntax: S/N=XYZ @ xyz nm; preferred telluric: xx-star.

4.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 a single spectrum of eta Car at a specific position angle. We can thus appropriately name it eta Car 37.5 deg. 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 selected. This will list all the acquisition templates available for XSHOOTER in the Template list behind it.

After reading the description of the templates in the XSHOOTER User Manual, you have determined that the XSHOOTER_slt_acq 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 Template 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 RA and DEC offsets to 0. Moreover, the target has no meaningful proper motion and therefore you do not need any additional tracking velocity. You also do not have any special requirements on the guiding star, which will be selected in the VLT guide star catalogue and hence there is no need to specify any coordinates for the guiding star.
Since you want to place the slit on a position angle of 37.5 degrees, you have to specify ththis number in the Position Angle on Sky field.
The set of parameters that you choose in your acquisiton template is shown in the previous figure.

In case you want to acquire a faint target (V>22.5mag) you have to do a blind offset. A tutorial about how to use blind offset with X-Shooter is available. In short, please use the ObsPrep tab to set the OBs correctly to perform blind offset acquisition. The tool will thus specify the offset RA and offset Dec from your science target to that reference target in the respective fields of the acquisition template.

Go to the top of the page

4.2: Defining the Observation: the Science Template

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 XSHOOTER_slt_obs_GenericOffset.

On Template Type, select now science. The existing XSHOOTER science templates will appear. Select the chosen one, XSHOOTER_slt_obs_GenericOffset, and click on Add. The template will be attached to the grid below next to the acquisition template selected and filled previously. What you need to do next is to set the parameters in the science template.

Following the recommendations of the manual, you choose to use the standard read-out mode 100k/1pt/hg. For your scientific purposes you need to obtain spectra of 100 seconds in the UVB of Eta Carinae, which is definitely an extended object. Therefore you decide not to nod on the slit, but to take separate sky exposures. You adjust the slit widths for the different arms to the requested seeing (this will be slightly better in the NIR). Note that the UVB and VIS arm share the same FIERA controller and thus cannot be read-out simultaneously. In order to optimise your science time, you can add the time needed to read-out the UVB arm (68s) , as exposure time to the VIS. The NIR arm can be read-out simultaneously, and has a very short read-out time (1.44s). Take a look at the user manual if you want to optimise your exposure times and minimise overheads. The set of parameters that you choose in your science template is thus as depicted below:

You can now compute the execution time clicking on the Exec. Time button .

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

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

4.3: Attaching Finding Charts and the README file

Finding charts and README file are directly attached to the OBs. Please, see the tutorial on README for instructions on how to do that.

For Finding Charts, please use the ObsPrep and Generate Finding charts button to create intrument compliant finding charts. Please note that a different background image than the standard one can be used on the ObsPrep tool, and this will allow one to generate a Finding Chart with that specific backround image. This is particularly relevant in cases where the target is located in a region with high background, or in a crowded region.

4.4: 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 p2pp3 GUI window, select the OB and click the Duplicate button. See picture:

5: Finishing the preparation: Check, Certify and Notify ESO

With the completion of the standard star OB, we consider the examples developed in this tutorial to be finished. 

Though, for a real run, you would also make sure to:

1. click the "Check" button (to the right of the Exec. Time button) for each OB.  Check performs consistency checks on the selected OB(s).
2. click on the Certify" button (to the right of the Check button).  Certify does the same as Check, but additionally (if the check was successful) marks the OB(s) as fully compliant and reaxdy for ESO's review.  It also marks the OB(s) as readonly.
3. (optionally) select one or more certified OBs and click on the "Revise" button (to the right of the Certify button) to revoke the certified status and allow re-editing.  If this is done it steps 1 and 2 above should be re-done for the OB(s) in question.
4. complete the information in the README file
5. click on the "Notify ESO" button (to the right of the Revise button).  This will lock all certified OBs as well as the README, in preparation for ESO's Phase 2 review process.

As mentioned above, all users have access to the p2 demo facility.  And, unlike the situation that existed with p2's predessesor, P2PP3, all OBs are created directly on the ESO database (there is no longer a "check-in" requirement).  Hence, all users can see what you leave behind.  Indeed, after a while, if not properly maintained, the p2 demo runs could and would get cluttered with all manner of OBs, containers, etc.  Thus, as a courtesy to the next user who follows this tutorial, we would like to ask you to finish these exercises by deleting the OBs, containers, etc. that you make.

Finally, please note that when looking at the tutorial run in the p2 demo facility you will see that both OBs are marked as (+) Accepted.  This is a state that these OBs have been set in (by ESO) solely to avoid them being inadvertently deleted from p2.

Go to the top of the page

p2 Documentation

• General help
• Video: getting ready with p2
• Video: ObsPrep tutorial
  
• Finding Chart help

X-Shooter p2 Tutorial

• Main page X-Shooter p2 tutorial
  
• General X-Shooter observation example: eta Car
  
• Blind offset with X-Shooter
  
• Access to example OBs