PH2 tutorial for ESPaDOnS

Updated May 23, 2017


Abstract -- This document presents the detailed PH2 tutorial for ESPaDOnS. Within PH2, help is available through a "Help" and a "Tutorial" button in the left menu. For any additional information, please contact the QSO Team by email using qsoteam -=at=- cfht.hawaii.edu.

SUMMARY OF BASICS

Users should have by now consulted the general documents Queued Service Observing at CFHT and General principles of Phase 2 (PH2). Reading those 2 documents should only take 15 minutes, so we recommend that users consult them at least once. A few highlights are repeated here:

WHAT'S NEW

1. Olapa 2amp mode

ESPaDOnS's detector Olapa has been switched to the 2 amplifier mode in 17A, which results in a time savings on the sky. The overheads charged in PH2 have been adjusted accordingly.

2. QSO-SNR mode

In most cases, QSO-SNR is the default mode of operation. The SNR mode is not suitable if:

If you are unsure if the SNR mode is suitable or not for your program, please email the QSO team qsoteam -=at=- cfht.hawaii.edu

Details are available in the QSO-SNR document.

To use QSO-SNR in PH2:

  1. Prg Constraints page: select "yes" for the question "Does your program require SNR mode?"
  2. Fixed Targets page: ensure you enter the magnitude and Teff of your targets; this allows the QSO team to verify exposure times and identify mistakes and potential issues
  3. Obs Blocks page: make sure you check the box "SNR mode?"
  4. Obs Blocks page: ensure you enter the requested SNR (per pixel bin and per frame) and the wavelength for that SNR
  5. Obs Blocks page: use the ETC "Calculatė button to check your exposure times and revise them if needed in the Instr Configs page; you may also use the ESPaDOnS ETC directly to control more options; take into account the following remarks for cool stars and the impact of the mirror coating degradation

3. Tip for setting the SNR for cool stars (Teff < 3500K) with ESPaDOnS

When using the ESPaDOnS ETC on cool stars, the SNR may end up lower than expected because a cool star's SED differs significantly from that of a blackbody (what the ETC assumes). From 400 to 700nm, the predicted SNR is the one observed. From 700 to 1000nm, the measured SNR is much larger, twice as high at 900nm (see the figure below). If you set the SNR goal at <700nm, the observed SNR in the red will be higher than what the ETC predicts (which is fine unless saturation is a concern). If you set the SNR goal at >700nm, the flux levels in the blue will be very poor.

We recommend using our 730nm wavelength and adding a margin to the SNR goal, as much as necessary depending on the part of the spectrum of interest.

4. We recommend the use of Firefox or Safari, both of which can be set to allow Java to run (for using Aladin). Chrome (version 42 and above) has disabled the standard way in which browsers support plugins; PH2 will work, but not Aladin. PH2 does not work with either Microsoft Edge or IE under Windows 10.
To enable Java on Firefox or Safari, please see How do I enable Java in my web browser?.

5. Starting with 2015A, there are 3 additional optional pieces of information that PIs can provide in the Fixed targets section: effective temperature for a target in Kelvin, proper motion in right ascension and proper motion in declination, both in milli-arcsec per year. In the Observation block section, PIs can provide the S/N per frame and per pixel bin, and the corresponding wavelength in nm. Finally, PIs can provide their own list of scheduling observations.

5a. Fixed target section. On the Targets page, users can enter the effective temperature, the proper motion in right ascension and declination for any target.

5b. Peak S/N expected. On the Observation block section, users can enter the S/N per CCD pixel for any target, per single spectroscopic exposure and the corresponding wavelength.

5c. OG scheduling. Users can specify if an OG needs to be observed within a specific scheduling constraint.

Note that only one OG scheduling constraint can be selected for the whole program.

Then, on the OGs page, users can enter the single date consraint per OG. PIs can upload a list of date constrains per OG by selecting the second option. Finally, PIs can provide the period and starting date per OG by selecting the third option.

7. Exposure time calculator. On the Instrument Configuration section, users should use the new Exposure Time Calculator (ETC) to estimate their exposure time and S/N. Some changes were made to better reproduce the S/N in the red part of the spectrum.

TABLE OF CONTENT:




ACCESSING PH2

Access to PH2 is limited to users who have received telescope time in the QSO mode. Access to PH2 is done through this small window:

The User ID and Password are sent to new users by the QSO Team, by email. If you have used PH2 before but do not remember your information, please contact the QSO Team.

Back to Table of Content




NAVIGUATING WITHIN PH2

The left frame of PH2 is the Navigation Menu. The user can easily go from one page to the other by just clicking on the appropriate button. The button corresponding to the form currently opened becomes white with blue fonts. It is highly recommended to navigate through PH2 with the menu buttons instead of the normal browser buttons. Activity in the different forms is monitored, so using the PH2 buttons ensures that all the data are saved before moving to another section of the tool.

The navigation buttons and their corresponding pages are described below.

Button
Corresponding Page
First page of PH2 (Login). User ID and Password required.
Program Selection Page, for multiple programs under the same User ID
Page describing the QSO program, the investigators (PI) and the TAC evaluation.
General Constraints and Information for the program. Depending on the answers, some options will be made available in the subsequent pages. Please use the box provided to add as many instructions as possible (priorities, acceptable extinction, if IQ can be pushed, exact requirement for photometric conditions, Moon distance or illumination constraints, etc.) Includes a section for the distribution of the data.
Page containing the table used to define all of the fixed targets used in the creation of the observation blocks
Page containing the table used to define all of the targets for which coordinates are changing with time (ephemeris). Only accessible if requested in Program Constraints page
Page used to define finding charts. To remove any possible confusion, each target must have its Finding Chart. Charts can be generated by Aladin in PH2, or prepared with a different tool and uploaded from a PI's computer.
Page containing the table used to define all of the instrument configuration (e.g. filters, exposure time, dithering pattern) used in the creation of the observation blocks
Page containing the table used to define all of the sky constraints entering in the creation of the observation blocks.
Page allowing the creation of the observation blocks from the lists of targets, instrumental configurations and constraints defined in the previous pages.
Page allowing the creation of the observation groups (e.g. sequences) from a list of observation blocks. The I-time used for the program is also calculated and compared to the time allocated by TAC. Time constraints and REEL can be accessed here, if requested.
Optional tool that can be used to define a set of specific dates and times to execute one or a series of OGs.
Optional tool that can be used to upload your own list of data constraints and tolerance per OG.
Page describing all the observations prepared with PH2 and stored in the database for a specific program.
Logging out of PH2 (needs confirmation).
Opens the quick help files for PH2, containing information on the diverse parameters of the PH2 forms.
This document! Detailed overview and general description of PH2 and how to use it.

Back to Table of Content




PROGRAM SELECTION

This page allows the selection of your program for your session:

This page can be opened at all time; it is possible to work on several programs at the same time without having to log out from PH2. The programs are first sorted out according to the semester (pull-down menu) and then are identified by the runID, instrument, and title. Be careful: always make sure that you are editing the right program! For your convenience, the runID is shown on all the PH2 forms. Note: Following recommendations by the Time Allocation Committee, it is possible that a program was split into different programs with some specific I-time and grade/rank. If it's the case, the program with the higher ranking will keep the same runID as assigned during Phase 1 but the other programs will be assigned a different runID by the QSO Team. You must first select a program and click on the "Proceed" button before being able to navigate through the other pages of PH2.

Button
Function
Open the help files to the current page.
Save the content of the current page in the QSO database and open the next form.

Back to Table of Content




PROGRAM DETAILS

This page presents information regarding the program, the investigators, and the TAC evaluation:

Button
Function
Open the quick help files to the current page.
Cancel all the modifications done to the current page and reload data stored in the database.
Save all the modifications done to the current page in the database and reload current page.
Save the content of the current page in the QSO database and open the next form.

Back to Table of Content




PROGRAM CONSTRAINTS

This page requests some important information regarding your QSO program. Depending of some of the answers you provide here, options will become available in the subsequent pages of PH2. This page is divided into several sections:

Note that there are two new questions regarding the default wavelength that should be used for the S/N measurement and your S/N goal per CCD pixel per exposure:

Back to Table of Content




FIXED TARGETS

This is the first step toward the creation of the observation blocks, and where the user defines the fixed targets of the program and their precise pointing coordinates. The target table includes the target name, coordinates, and optional magnitude, effective temperature and proper motion. A few buttons allow the addition, duplication, selection or deletion of entries. The maximum number of rows displayed at once is five. The "Next Page" and "Previous Page" buttons can be used to navigate between the different pages. The blue hyperlinks FT# represent the first row of each individual pages and can also be used for moving quickly from a page to another.

Back to Table of Content




EPHEMERIS

This form is used to define targets for which coordinates change with time. The form is only accessible if requested in the Program Constraints section.

  1. At least 3 sets of RA and Dec coordinate pairs must be entered, enough to cover the potential time of observation. The times are in UT.
  2. If the moving target moves slowly and is to be observed with sidereal rates (with or without guiding), the set of coordinates closest to the observing time will be sent to the telescope.
  3. If the moving target moves quickly enough that non-sidereal rates are requested, sets of coordinates (at least 3, up to five) will be picked and sent to the Telescope. The request will fail if there is not at least one time before and one time after the time of observation. If there are enough sets, the choice will be one before and four after the time the observation is selected. The sets must be spaced far enough apart in time to cover the longest OB they are used with. Current coordinates and rates will be interpolated by the Telescope Control System.

The general idea behind the ephemeris form is very simple: define a series of coordinates for a specific time for a given target. The table below shows the entry fields for the ephemeris of the target specified:

The top of the form allows the user to first give a name to a target. For instance, in the pull-down menu on the left, you can select "New". In the central window, you can then give a name to your target. When you click on "Update", the table in the middle frame window is then created and your target receives a label "ET#" (for "ephemeris target").

Each row in the table is an ephemeris labeled "E#" and includes the UTC Date (beginning of a night in Hawaii is ~ 05:00:00 UT) and the coordinates of the target for this date (in J2000.0). As many ephemeris as wanted can be entered for a target and as many targets as wanted can be entered for a program. After defining all of the ephemeris for the target, we recommend that you save it immediately before starting defining the ephemeris for the next target (if needed). When saved, the ET will appeared in the list of targets used for defining the observation blocks (below).

Since entering a large number of ephemeris can be cumbersome the Astrores format template can be used at the bottom of the page to upload ephemeris for a given target (that is, one upload per target is necessary). To do so, apply first the procedure described above (create a new target name and click on update), since the name of the target cannot be defined from the Astrores template. Below there is a Astrores template (XML) that can copied on your local machine and then used to upload ephemeris to the table in the middle frame. (You can also create your own template on your local machine by first defining a target and click on "download". It is important that the format is respected. You can then prepare the ephemeris for the target as seen in the lower part of the template and save the template under a specific name. When saved on your local machine, you can then upload it by specifying the path. Check that everything is fine and then save the ephemeris table for that target. Repeat if necessary!

<?xml version = "1.0"?>
<!DOCTYPE ASTRO SYSTEM "http://vizier.u-strasbg.fr/xml/astrores.dtd">
<ASTRO ID="v0.8" xmlns:ASTRO="http://vizier.u-strasbg.fr/doc/astrores.htx">
<TABLE ID="Table">
<NAME>Ephemeris</NAME>
<title>Ephemeris for CFHT QSO</title>
<!-- Definition of each field -->
<FIELD name="DATE_UTC" datatype="A" width="19" format="YYYY-MM-DD hh:mm:ss">
<DESCRIPTION>UTC Date</DESCRIPTION>
</FIELD> 
<FIELD name="RA_J2000" datatype="A" width="11" unit="h" format="RAh:RAm:RAs">
<DESCRIPTION>Right ascension of target</DESCRIPTION>
</FIELD>
<FIELD name="DEC_J2000" datatype="A" width="11" unit="deg" format="DEd:DEm:DEs">
<DESCRIPTION>Declination of target</DESCRIPTION>
</FIELD>
<!-- Data table -->
<DATA><CSV headlines="4" colsep="|">
<![CDATA[
DATE_UTC           |RA_J2000   |DEC_J2000  |
YYYY-MM-DD hh:mm:ss|hh:mm:ss.ss|+dd:mm:ss.s|
1234567890123456789|12345678901|12345678901|
-------------------|-----------|-----------|
2003-06-04 06:30:00|09:34:00.00|+16:38:00.0|
2003-06-05 06:30:00|09:35:15.00|+16:31:50.0|
2003-06-06 06:30:00|09:36:33.00|+16:25:40.0|
]]></CSV></DATA>
</TABLE>
</ASTRO>

Back to Table of Content




FINDING CHARTS

Since ESPaDOnS is a fiber-fed instrument, it is important to make sure that the right target is put into the entrance fiber. Pointing of the telescope is limited to an accuracy of at best +/- 10" on the sky so in crowded fields or when the target is faint, it might become difficult to identify the right object to put into the fiber. For obvious reasons, finding charts can only be defined for fixed targets; moving fields are not possible. All Finding Charts entered in PH2 will be automatically displayed next to the guiding window for the QSO observer at the telescope. Please make sure your files are in the jpg format. PH2 now has a mandatory section where the user can prepare Finding Charts by downloading a file which contains a suitable chart. The Aladin Sky Atlas is often used by ESPaDOnS users and is recommended by CFHT.

The finding charts must be saved as a jpg file with the following mandatory information:

  1. North and East Directions indicated on the chart.
  2. Scale indicated on the chart.
  3. The Field of View of the ESPaDOnS acquisition camera is about 100arcsec diameter. Please make the FOV big enough to include a few extra stars in addition to the target of interest.
  4. An arrow or circle or cross indicating which is the target to be observed.

Here is an example of a suitable chart produced with the most recent version of Aladin:

Once the chart has been uploaded, users should indicate in the comment box how the Service Observer can identify the target, as given in the example below:

Note that the finding charts are displayed in the summary of the program.

Back to Table of Content




INSTRUMENT CONFIGURATION

This is the second mandatory step in the creation of the observing blocks, used to define all the instrumental configurations necessary for the program. The same configuration can be used several times with different targets. The main section of the page is a table with different options under pull-down menus or editable entry fields.

The top frame can be used to help in the preparation of these configurations:

The middle frame of the configuration page consists in a table and buttons to manipulate the entry fields:

Integration Time Calculation

The integration time (I-time) calculation is done for each instrument configuration (IC) according to the general formula:

I-time (IC) = Nseq x [S(Obs.mode) x [Exptime + Overheads (readout)]]

where:

Nseq = Number of sequences
S(Obs.mode) = Number of exposures generated, depending on the observing mode selected. For polarimetry, S=4. For spectroscopy, S=1
Exptime = Exposure time defined for each individual exposure
Overheads (readout) = Overhead charged for each individual exposure. It includes the readout time + some operational overheads, as defined in the table above.

Example: In polarimetric mode, the user requires 5 sequences with the Q parameter, the normal readout mode and exposure time of 100 sec/exp. We get: IC = 5 x [4 x (100 + 60)] = 3200 seconds (20 files generated).

The following table shows the available buttons:

Button Function
Add N rows to the table.
Duplicate the selected rows N times.
Delete the selected rows. A confirmation window is displayed.
Select all the rows in the table. Clicking again on it deselect all the rows.
Check the entries for errors. The errors found are displayed in a separate window and are indicated by a red frame in the table. An automatic check is done also when the form is saved or when the "proceed" button is activated.
Display the next rows of the table.
Display the previous rows of the table.
Cancel all the modifications done to the current page and reload data stored in the database.
Save all the modifications done to the current page in the database and reload current page. Regular saving of the current form is recommended!
Save the content of the current page in the QSO database and open the next form.

Back to Table of Content




CONSTRAINTS

This page presents the table designed for defining the sky constraints under which the observations should be undertaken. The top frame displays information about the targets and instrument configurations defined previously:

The middle frame presents the table for the constraints:

A note on the Seeing. The constraint on the seeing is usually the strongest criterion for the selection of a program to be undertaken. Our goal is to never try observations during conditions exceeding the upper limit defined by your constraint by more than 10%, and at most 20%. The probability that your program is executed depends somewhat on this constraint, even with ESPaDOnS; the table below offers some statistics. Be realistic! In particular, for Programs with the C grade, it would be much preferable not to specify a seeing better than 1.0". It is important that you request a realistic IQ also when your targets do not reach a low airmass. For instance, asking for better than 1" when the airmass is never smaller than 2.0 is not very likely to happen... By definition, snapshots programs MUST request IQ > 1.5".

Image Quality (IQ) on Mauna Kea
Frequency (%)
IQ < 1.0"
70-80

1.0" < IQ < 1.5"
20-30
IQ > 1.5"
0-5

Here is a table of all available buttons:

Button
Function
Add N rows to the table.
Duplicate the selected rows N times.
Delete the selected rows. A confirmation window is displayed.
Select all the rows in the table. Clicking again on it deselect all the rows.
Check the entries for errors. The errors found are displayed in a separate window and are indicated by a red frame in the table. An automatic check is done also when the form is saved or when the "proceed" button is activated.
Display the next rows of the table.
Display the previous rows of the table.
Cancel all the modifications done to the current page and reload data stored in the database.
Save all the modifications done to the current page in the database and reload current page. Regular saving of the current form is recommended!
Save the content of the current page in the QSO database and open the next form.

Back to Table of Content




OBSERVATION BLOCKS

This is it! This page allows the user to link all the previously defined entities within observation blocks (OB). The main page is divided into two main frames.

The top frame is used to select the different components of an OB: one Target (fixed or moving), one or more Instrument Configurations, and one Constraint.

Back to Table of Content




OBSERVATION GROUPS

This page presents the last step in the preparation of your observations: the creation of the observation groups (OG). The OGs will be the entities scheduled at the telescope so this step is necessary, even if you have previously defined all the observation blocks. The top frame is used to select the components of each OG:

The middle frame presents the OGs that were created.

If the user has answered "yes" to the question "Do you need to specify the hour angle for the execution of the OGs?" on the Program Constraints page, new columns will be visible. Users can then enter the earliest HA at the start of the OG and the latest HA at the start of the OG. Note that noth times are for the start of the OG. The HA constraint does not give the range of HA within which an OG can be observed, but the range of acceptable HA for the start of the OG only.

The bottom frame shows the Integration time allocated by the Time Allocation Committee for your program; this time cannot be exceeded! The total integration time requested for all the observing groups defined in this page automatically includes the readout time for the CCD for all of the individual exposure in the OG. The I-Time Left cannot be negative. If I-time left < 0, a warning window is displayed. The new OG is included in the table but cannot be saved. You must modify the OG table in order to get I-Time equal or larger than zero. If you click on "cancel" instead, the new OG is removed from the table.

Observation Groups Options

Three options are available to include additional details on how to execute specific OGs: Monitoring, REEL, Time Constraints. These options are first presented in the "Program Constraints" section and appear only in the OG form if requested.

  1. OGs can have monitoring parameters. This option appears only if you have indicated that your program requires monitoring. You can enter a period in hours, days or weeks. To enter the parameters, first select the unit and then fill up its value. The number of iterations corresponds to the numbers of times that this OG should be done at the interval of the period. The minimum number of iterations corresponds to the acceptable minimum number of observations to reach the science goals. We will reach for the total number of iterations but only OGs that have met the minimum number of iterations will be considered valid.

  2. Relational Execution Link (REEL) are used to specify that some of the OGs must take place in a specific sequence of events. For instance, if OG1 is observed, only then OG2 should be done within a certain timescale (which can include a delay of zero hours to get back-to-back execution of OGs). The REEL creates a causal link between OGs. This option is only available if you have selected the REEL option in the "Program Constraints" section. Essentially, a REEL means this: "After the execution of the reference OG, the linked OG should be done within a certain delay." You can then link several OGs, if needed. For instance, OG3 to OG2 to OG1, etc. The links created appear in the OG table. An example of a REEL sequence is showed below.

    The REEL option should be used ONLY when appropriate. If the observations cannot be done within the window defined by the (delay +/- delay) (due to bad weather or technical problems), the completion of the chain will not be done. Also, the logic involved in defining the REELs in PH2 is complicated. It is preferable to define first all the OGs, save them, and then create the links. This can be done using the "modif OGs" button: after defining all the OGs, you can create the REEL link by selecting the OG from its label, entering the REEL parameters, click in the "select" box on the row, click on the "modif OGs" button and save. Deleting OGs which have REELs will not be permitted.

  3. For certain programs, some observations must be done during a specific time range. These entry fields, available in the OG table, allow the user to define such a constraint by specifying a period for which the observations should be undertaken. The user can enter a date and a time (HST) to specify such a window. These fields are optional and will appear only if required in the "Program Constraints" page. It must also be understood that these constraints are very severe: if for a reason or another (e.g. bad weather or conditions not meeting the sky constraints) the observations cannot be done during the period required, these observations will not be attempted again and will be taken out of the queue. Time constraints are not compatible with REELs, for example if an OG is to be done after another one is validated, that OG cannot have time constraints as well.

Here is a table of the available buttons:

Button
Function
Create one observation group (it can be of types 1OB, MOB, or SOB).
Transform all the observation blocks defined in the previous form into observation groups. The recommended approach!
Modifying an existing observation group. After selecting one or several OGs in the table ("select" column), the OGs will be modified according to the parameters redefined by the top lists after clicking the "modif OG(s)" button. So, it is now possible to change an OG without having to delete it first from the table! Important: You must make sure that the total I-time allocated for your program has not been exceeded after modifying the OG(s).
Select all the rows in the table. Clicking again on it deselect all the rows.
Delete the selected rows. A confirmation window is displayed.
Check the entries for errors. The errors found are displayed in a separate window and are indicated by a red frame in the table. An automatic check is done also when the form is saved or when the "proceed" button is activated.
Display the next rows of the table.
Display the previous rows of the table.
Cancel all the modifications done to the current page and reload data stored in the database.
Save all the modifications done to the current page in the database and reload current page. Regular saving of the current form is recommended!
Save the content of the current page in the QSO database and open the next form.

Back to Table of Content




OG SCHEDULER

For certain ESPaDOnS programs, observations can be done at specific but multiple times during a semester. For instance, if the observations have to be done during a specific transit of a binary system, several dates and times might be possible. These dates and times can now be defined precisely with a new tool, the OG scheduler, developed specifically for this purpose. The tool produces a series of possible dates and times for which one or several OGs should be executed. The OG scheduler is optional and should be used only for those few programs which really require this tool.

A note on Time Constraints

Before explaining how to use the OG scheduler, it is important to provide a clear distinction between the different possibilities offered by PH2 on how to define time constraints with ESPaDOnS. There are 3 distinct possibilities, two of them already introduced in the previous section on the OG form.

  1. Time Constraint Window: When requested in the program constraints page, it is possible to define time windows during which a OG should be done. This is the type of possible time constraint defined in the OG form. The OG will only be done within that time window.
  2. Monitoring: A specific OG might be done several times during the course of a semester, for monitoring a specific target. The monitoring is defined by a number of iterations and a period. The monitoring OG can be done within a time window, if desired.
  3. OG Scheduling: Several specific dates and times for a given OG can be needed, not just a window. OG scheduling refer to the possibility to define several dates and times for which an OG can be done. In other words, "an OG can be done at this date and time, or that one, or that one, etc...". Even a monitoring OG can be scheduled that way. In that case, it would mean "start this monitoring OG at one of these specific dates and times, then continue the monitoring of target according to the iterations and monitoring parameters (period)".

It is very easy to define a series of dates and times for which a OG could be done. NOTE: All dates and times specified within PH2 OG Scheduler are in UT. The top frame of the OG Scheduler looks like this:

After entering these parameters, by clicking the "create" button in the middle table will create the list of dates:

Back to Table of Content




UPLOAD SCHEDULE

This PH2 functionality only appears if the appropriate option is selected in the Program Constraints page:

The Upload Schedule functionality is useful for events that happen on specific dates and times, but not necessarily regularly. For regular (periodic) events, the OG scheduler can be used. For non-regular events, such as transits, the Upload Schedule allows the necessary flexibility in the choice of dates and times.

A list of dates and times can be edited as a plain ascii file, and then uploaded in PH2. The formatting is very precise; after the upload is complete, the content will be displayed in a table. Users must check the values that are displayed.

Back to Table of Content




SUMMARY

This page opens a complete summary of what is currently the Phase 2 status of the program. As showed below, the summary can be sent by e-mail to several destinations as a HTML attachment (to be compatible with people not using a browser for their mail system), by clicking on the "Send this page to" button. The summary can also be printed using the "Print" button of the browser used for PH2.

We strongly suggest that you keep the summary (printed or electronic) of the final version of the program submitted during the Phase 2. It will be useful to you for monitoring the progress of your program with the night reports and for any necessary communication between you and the QSO Team regarding the observations.

Back to Table of Content




LOGOUT

To exit PH2, you must confirm it by clicking on the "Logout" button in the window below. If you do not want to do so, select another page with the navigation buttons on the left frame.

Back to Table of Content