This document describes the execution of observations at UKIRT under the Observation Management Project(OMP)  software. Observations are selected from MSBs, which in turn are filtered from the OMP database by specifying current observing conditions. The following topics are covered. We suggest you read through sequentially and take the tours as they come up:

I. Introduction

The central system in UKIRT Observing is a database of observations, held at the  summit of Mauna Kea. Observations are prepared using the Observing Tool. The science programme is stored on disk locally to the observer (who can be anywhere in the world), and once complete, submitted into the summit database.  The observer at the summit  uses a database query tool to sort and extract observations to be done.  The observer carries out database searches and executes translated MSBs on the data-acquisition machine (at the time of writing, called ohi). The other machine is reserved for data reduction and observation preparation (at the time of writing, called kauwa). 

The following diagram shows (at a very top level, with some inaccuracy) how information flows around the summit, starting from the OMP database (in the centre) and working more or less anticlockwise. It applies to WFCAM operation.

Most functions of the UKIRT observing system are either run directly from one of three top-level guis, shown below, or from a further gui which is in turn run from the top level.

ukirtObs  (run on ohi, the acquisition machine, at start of night. Applies to both Cass and WFCAM modes)

cassObs  (run on kauwa, the reduction machine, when in Cassegrain mode)

wfcamObs (run on kauwa when in WFCAM mode)

II. Observation Selection and Execution

Tour: the Query Tool (ukirtqt)

The Query Tool takes current observing conditions, UT date and other scheduling information and returns a sorted list of MSBs which can be observed now. The Observer has considerable control over the returned list, for instance they can force their own project to come to the top preferentially (as allowed under the UKIRT flexible-scheduling scheme). To run the QT, login to the summit data acquisition machine and type ocs_up.To test out observing scenarios, for example by artificially entering different observing conditions or UT date, run the QT separately (e.g. on kauwa) by typing ukirtqt -scenario ; the latter will not run up instrument tasks, or connections to them, and can be safely run anywhere at the JAC.

A QT window initially comes up as follows (click the image for a tour):

Specifying conditions

The observer then provides observing information such as current seeing, tau, photometric quality, optionally provides some scheduling constraints such as an hour angle range, and clicks “search” to execute a search of the OMP database. In the following example, the observer has requested UKIDSS MSBs, restricted the instruments to WFCAM only, and has expanded the Title column (by dragging the column joint).

Selecting and executing MSBs

Highlight the MSB you want, and click “Fetch MSB” (obvious shortcut: just double-click the MSB). The QT window has two “Tabs” – one for MSB querying (where you were before) and one which now pops to the front and shows the contents of the fetched MSB. 

Here, a UKIDSS LAS MSB has been fetched into the science programme area, where its constituent Observations (all in the H band in this case) are displayed. The next steps are to read the observer notes for any special instructions, and then get the Observations within the MSB into the Queue system. 

Skipping Observations

Any Observation listed in green text is optional (having been flagged as such by the PI in preparing their OT programme). These can be dragged into the deferred calibration region, or if you’re really confident that you won’t be wanting them, into the waste bin just below the Fetched Program panel. Note that the waste bin is not a recycle bin; once an observation is dropped in it, it cannot be retrieved.

Parallel Observations with Other Instruments

If you wish to send an observation that does not move the telescope,  to be done in parallel with the one currently being done by the queue, there is a “Send for engineering” option in the  right-click menu which sends the selected Observation directly to the sequence console, bypassing the queue. Any observation sent in this manner does not have telescope (beam) control, so only use it to set up array tests for an  upcoming instrument change.

---

III. Observation Execution: the Queue and Sequence Console

Observation Queueing

MSB contents are sent for execution by simply clicking once on them and pressing “Send to Queue”. At this point, a number of things happen when you do this:

1. The Observations in the MSB are appended to the “queue” 
2. The queue itself is started and stopped by the observer. While started it runs continually without intervention, submitting the next Observation when the previous one is completed; when all the Observations in an MSB are exhausted, the queue asks the observer whether to accept the MSB, reject it or otherwise (this stage is discussed later).

The queue is inspected and controlled from the Queue Monitor (shown here in “started” state – hence the “STOPQ” label on the stop/start button). Here is an example with a Michelle MSB expanded into its constituent Observations and running in the queue monitor:

Queue placement

• The QT can send more than one MSB to the Queue – each MSB is expanded into its constituent Observations and displayed in sequence order in the “queue contents” window, after whatever was already there. 
• To splice an observation (e.g. an UFTI flush) into the queue immediately after the current Observation, send it to the queue from the Deferred area. 
• The QT search makes sure a retrieved MSB is within all its scheduling bounds. In the situation where you attempt to send an MSB when there are more than 60 minutes left on the queue already, the system will inform you that you should try again when there are fewer things in the queue. This reduces the chance of an MSB being executed outside its bounds.

Queue Monitor Functions

• Observations in the queue monitor are marked as QUEUED, SENT, OBSERVED or ERROR depending on their status.
• Use the middle button on a queue entry in order to bring up a menu that allows you to cut that observation from the queue, or to cut the whole MSB in which the observation belongs.

When started, the queue repeatedly sends Observations to be executed. Each time it does this, the following steps happen (some of them in the background):

1. If necessary, a “Sequence console” is popped up which displays the translated sequence and allows control over it. If a sequence console is already present (because another instrument has been run beforehand) a new “tab” pops up within that console, labelled with the name of the instrument being used, and the sequence is displayed there (see the figure below for more details). 
2. A large number of tasks are started, to which the sequence console can dispatch commands as it works through the sequence. You will see messages about these tasks in the xterm from which you launched the QT.
3. [For instruments other than CGS4] a “quick look” gaia is displayed on the second head of the acquisition machine.
4. The Observation is executed (in the sequence console – see below)
5. Once complete, the sequence console automatically solicits the next Observation from the queue.

Once steps 2 to 4 have been done, they are never repeated unless you exit the system and restart it. The DRAMA and other tasks remain in place until you exit.

Contents of the sequence console

The sequence console looks like this:

There are four main sections in the sequence console for any UKIRT instrument.

1. Control panel with buttons for stopping, starting etc.
2. The sequence itself (current point is indicated by the highlight)
3. Data taking status display with indication of latest file stored etc.
4. Instrument status display with current instrument settings.

The low-level comands shown in the sequence are generated automatically by the translator when the Observation is sent from the queue. Those displayed in the example above are typical; while you don’t interact with any of these apart from occasionally clicking on one or pressing “Run from Highlight”, we detail some of the more important ones below.

define_inst	This defines for the telescope details like which instrument is being used, where its aperture lies in the focal plane, what central wavelength etc. – all of these parameters are derived either from your OT programme or from static tables
setHeader	Various of these are seen in the sequence above. They define FITS header items which are needed by ORAC-DR or by the OMP programme-tracking database.
telConfig	Instructs the telescope to adopt a particular “config” – which includes where on the sky to point.
slew	Slew; either the main telescope (“All”) or the Guider (“guide”). Always check with the TSS before slewing. Observations sent from the queue are automatically run down to this point and then stop (this is the state the console shown above has reached).
loadConfig	Tells the system to get the instrument configuration information specified in your OT programme. As in this example, the config name is a unique filename (you don’t need to know it) and there may be variants (_1 in this case) which may specify flat, arc or object configurations. LoadConfig is a standard place to restart a sequence (for example after peaking up), because it ensures that the instrument is in the right configuration before any observation is taken.
startGroup	This is for ORACDR. The sequence will produce N frames, all of which are logically associated with the first frame. These frames are called a “group” and the DR will give all frames a group ID equal to the number of the first frame. startGroup simply tells the DR to do this. So if you want to add more frames to a given group, make sure you restart after the startGroup command.
set OBJECT	Instructs the instrument to set to its OBJECT configuration as defined in your OT programme. You will also see set ARC , set FLAT  etc.
break	One of the more important ones. This command, inserted automatically into the sequence by the translator, tells the sequence to stop at this point and wait for you to click the “Continue” button. The break shown above, just before the first exposures are taken, is there to give you a chance to look at the instrument configuration before committing yourself !
offset	offsets the telescope. The translator generates these commands from your specified offset pattern in the OT programme. Most sequences consist of a set of initialisation commands at the top, followed by a series of “offset/observe” commands.
Observe	Takes a frame using the exposure time, coadd/total exposure time information in your OT instrument component.

Controlling the Sequence

Buttons on the control panel give you the ability to control the sequence in a number of ways:

Run from Highlight	Starts the sequence from the point indicated by the “arrow” highlight, and including the command highlighted
Stop at Break	Stops the sequence at the next indicated break point. These are inserted into the sequence by the translator, and are placed such that the DR will always be able to complete a group sensibly. In the above example they are placed once every “quad” (two pairs of sky-subtracted observations)
Stop ASAP	Stops as soon as the current Observe  is complete. You can use this to suspend observing if the weather temporarily goes off, for example.
Movie	Sets the instrument into a mode where it continually reads out and displays on the “quick look” display.
Finished	In the event that a sequence is stopped early (e.g. due to sufficient signal to noise being reached, or due to an unrecoverable error), the observer can indicate that they are done with the current sequence by pressing the “Finished” button. This prompts the queue to send the next Observation.

IV. The Data-reduction Machine

Screens

The other screen (or set of screens) with which the observer interacts are on the left hand side of the control room; this machine is where the data reduction and observing tool are normally run. The three heads are shown below (merged into one wide image), with one possible layout. Note that you are free to adopt whatever layout works for you – many observers like to reserve one entire three-headed workspace for data reduction (this makes sense when you have three pipelines running at once, for three different instruments, for example). Other workspaces are then available for administrative items (obslog, tcsmon etc.), obsering tool and so on. [Note that the layout of these workspaces and taskbars is subject to change as summit computing develops; this section is intended only as a guide. Your support astronomer will instruct you in the various facilities.]

The following image shows details of the toolbar from which you launch various processes.

Bottom Toolbar

1: KDE menu	Run KDE and other programs from here. You’ll also find logout under this menu
2: Frequently used programs	OT, obslog, three of Jonathan’s launcher guis (two of which apply to kauwa), a konsole, and TCS monitor.
3: Workspace selection	You have four workspaces: ukirt_ot, DR, surf/general and Log/TCS-mon. These are suggestive only; put things where you feel most comfortable.
4: Selection buttons for every window in the current workspace	The usual selection of buttons to locate programs you are currently running.

Running the DR

The DR pipeline is started from either the wfcamObs gui or the cassObs gui. The details of command line flags etc. for use in restarting the pipeline in case of need, are discussed in the ORACDR summary page.

Logging: ompobslog [tour]

Note that ompobslog has developed somewhat since this documentation was written; however the gui remains quite self explanatory and its functions are similar.

Observing is logged automatically and you will have access to a full electronic night log. There are three levels at which you can influence the contents of this log, and it is important, in all cases, that you do so (even if it’s your own data that are being taken, please remember that the data go into the UKIRT archive and commentary is essential to efficient use of this in the future). The tool you use to create log comments and affect the flagging of observations is called ompobslog, which is an item on the observer account taskbar.

An example obslog window is shown here. Click on the image for a tour of the features. Note that the text list contains both information about individual observations, and other details such as gaps greater than a certain length (between data acquisition ending and resuming – this is done automatically).

Logging actions and examples

Individual comment (observation level)

Double click on an observation in the text panel to get access to the window below, which allows you to indicate whether a given observation is good (the default) or otherwise, and add a comment.

Generic comment (shift level)

Entered in the text field at the bottom of the ompobslog window, these are more generic comments not relating directly to a given observation. For example, “these are turning out easier than expected; need to consult PI” or “tonight started photometric but now thin cirrus is present”.

Gap comment

Gaps are identified by the data header scan. You can (and we would encourage you to) enter comments describing why a given gap occurred. Double click on the gap to get a similar editor (but note the different status checkboxes). Note that the “fault” button is not used in accounting – that is done through the normal faults system. The “weather” and “instrument” buttons are used for accounting at the end of the night, so please do try to be accurate in assigning time to gaps in this way.

Time accounting: MSB Accept and Reject

Accounting for time observed, and correctly modifying the contents of the observing database as programme MSBs are done is a crucial element of flexible scheduling. This section describes the normal steps involved in executing an MSB and documenting the fact that it’s been executed. First we reiterate the top-level sequence of events, then describe the function of the Accept/Reject dialogue and lay out the groundrules for its use, run through the normal sequence in more detail and finally treat some special cases. Most of this applies to all observers, with one or two items discussed specifically in the context of an observer executing observations off the queue, rather than their own programme. The special cases include discussion of changing the exposure time for a given Observation, which has two variants depending on whether the Observation is the last in the MSB or not.

The essential steps involved are as follows:

• Search the database for suitable MSBs.
• Select one and Fetch it.
• Send all Observations from the MSB to the queue, after deferring or disposing of those marked as optional if they are not needed.
• After the last Observation in the MSB has been executed, the system will ask you to Accept or Reject the MSB.

The Accept/Reject dialogue is described below.

General Points

Locking	This popup is non-locking – observing will continue as normal while it is up. If a second MSB finishes  before you had a chance to accept or reject the first one, it will  create a new tab in the accept/reject window so you can catch up later.
MSB Identification	MSBs in the Accept/Reject dialogue are identified with a temporary number (eg 003) that matches the MSB designation entry shown in the queue, so you can  remember which one is which.
MSB Disposal	Once you have dealt with an MSB in this  way, its entries will be removed from the queue. Single Calibrations not  belonging to an MSB hang around – use the middle button Cut to remove them.

Buttons

Accept	Accepts the MSB as done. Do this if you are sure that it was ok. This MSB’s database count will be reduced by one.
Reject	Rejects the MSB. Time used on it to date is charged to the programme, but the MSB remains viable in the queue.
Took No Data	Click this if you took no meaningful data. (If you really really took no data – not even a calibration – the system won’t bother asking you anyway).

Worked Example 

If all you need is a quick reminder of the normal sequence of events, look down the second column of the “Normal Operation” table.

Normal Operation

Step	What	Description and Comments
1	Set conditions	Enter seeing in the seeing box, tau in the tau box (if not set automatically) and click Set Current
2	Search the database	Click Search. This returns a priority-sorted list of observations into the list at the bottom of the QT window
3	Fetch an MSB into the staging area	Either double click an item in the list, or single click and press Fetch
4	Execute observations in the MSB via the queue	In the staging area, press Send to Queue, after dropping any Observations you don’t need. Remember that you can pre-fill the queue by appending other MSBs to it while Observations from the current MSB are being exected.
5	Fill the Accept/Reject dislogue	This pops up once the last Observation in the MSB is complete. If you are now happy that the MSB is complete, click Accept . If something was irretrievably wrong and the programme’s PI needs to intervene, click Reject . The case where the exposure time in the last Observation needs editing is described below.
6	If more than 15 minutes have elapsed, go to 2. if not, go to 3.	Because conditions may change and the sky is in motion, the database updates its list of observable MSBs every 15 minutes. Therefore if you are looking to fetch a new MSB after a gap of more than a quarter of an hour, click Search  before doing so.

Special Operations

1

Stopping an MSB halfway through

If you wish to trigger the accept/reject popup for the current MSB without completing all its entries, use the “Dispose MSB” button.

V. Advanced Topics and Usage Notes

Observer notes

You can, in the OT, insert a note into an MSB which will be copied into the “notes” section of the summit query tool. Simply insert the note and click the “show to observer” tick box. You only get one such note per MSB, so please be careful to be as complete as you can if your observations are flexibly scheduled. The example of MSB selection presented above in fact shows an observer note.

Classical Observing under the OMP

The OMP, while designed for use in the flexible scheduling which will be the norm at UKIRT from 2003A onward, is quite capable of classical observing also. It is possible to create a science programme following the style of orac/OMP programmes, without MSBs; however for various reasons this is the one thing not to do – each observation is treated as an MSB and the query tool will display them in an essentially random (or at least unhelpfully sorted) order. The key to classical observing under the OMP turns out to be the same as it is under flexing – optimise the content of your MSBs and the system will make observing very easy for you.