The narrow angle Astrometric observation PrEparation Software - APES

User Manual (V1.0)

Damien SÉGRANSAN

05-May-2008

I. Introduction

This section describes the narrow angle Astrometric observation PrEparation Software (APES) , which is a key tool in the preparation of OBs in both Visitor and Service Mode. The goal of APES is mainly to help the astromomer make his observation successfull by reducing the amount of information that has to be taken into account to schedule narrow angle Astrometric observations.
The purpose of the APES is fourfold :

Select an optimal VLTI array configuration that will constrain the best the astrometric motion of the science target
Compute the astrometric accuracy of the observations and the time required to conduct them.
Schedule the observations (observing night or observing run) taking into account several constraints (lst, airmass, date, seeing, etc...)
Provide input to P2PP

Inputs to APES are done through a Graphical User Interface (GUI) and through a "mandatory" science target catalog and an "optional" past measurement catalog. The format of these catalogs is described in the Catalogs Section. APES includes atmospheric conditions, such as seeing, coherence time and isoplanetic angle, science target and reference source parameters, such as brightness, the distance between reference and target (more details in the Catalogs Section). Output consists of a configuration file for P2PP namely parameter files (PAF, see Export to P2PP section). The Exposure Time Calculator is part of the Performance Estimator of APES (see Performance Estimation & ETC Section). APES can be used at any stage of the preparation of the observations. At Phase I (Call for Proposals), Phase II (Observing Preparation) or even in the course of the execution of the observations at the telescope (APES will be available at Paranal). APES is able to take into account the current external conditions and actual reference (instead of expected) source characteristics to optimize the observations, still respecting the astronomer's requirements. The FITS headers of DDL-PRIMA data contain all the necessary information on the setup used.

Where to obtain help and further information

This User Manual is not intended to provide detailed instrument-specific information. Please refer in such cases to the corresponding PRIMA/DDL User Manuals that can be found under the instrument Web pages, http://www.eso.org/instruments/
The latest version of APES, its corresponding on-site installation instructions, and this Manual can be found at http://obswww.unige.ch/~segransa/apes/apes.html.
Information on observation preparation procedures and Service Mode observing policies can be found at the ESO User Support Department Web pages:http://www.eso.org/org/dmd/usg/ 2 P2PP v2.13 User Manual Doc. No. VLT-MAN-ESO-19200-1644
General questions on observing programmes and time allocation must be addressed to the ESO Visiting Astronomers Section (visas@eso.org)
For problem reports or technical information on APES, please contact Luc Weber (Luc.Weber@obs.unige.ch)\end{verbatim}
For questions regarding installation, functionality, use, or any other inquiries on APES, please contact Luc Weber (Luc.Weber@obs.unige.ch)y

II. Starting-up APES

The narrow angle Astrometric observation PrEparation Software can be downloaded for a number of computer platforms at the following URL:Supported Platforms In principle, APES v0.98 should work within any Java Virtual Machine which supports Java Runtime Environment (JDK) 1.5.0 or later. However it has been developped and fully tested only on MacOS X (10.4 or later).

Until further notice, Geneva Observatory will only officially support APES under the following operating systems:

MacOS X (10.4 or later)

Complete installation kits for these systems, including an appropriate Java Runtime Environment, are available (see below).

If you wish to install and run APES under a different operating system, you do so at your own risk.

APES application : MacOS X Installation Procedure

To install APES, you will need to retrieve the distribution for your operating system (download section of this web page), unpack it, and start APES by double clicking on the APES.jar file. You may also need to retrieve a Java Runtime Environment, if you don't have one on your machine already.

Please follow these steps:

Move to the directory where you want to install APES.

Download the following distribution:

APES-v0.98.tar [2.9 Mbytes]

Unpack the distribution

tar xvf APES-v0.98.tar

APES-v0.98.tar/

Launch the application

open APES.jar

java -jar APES.jar

double click on APES.jar

If the APES main panel appears, then you have successfully installed APES. You can delete the compressed TAR file.

Warning: Make sure you are really running APES v0.98 or later. The APES version is listed at the top of the main window.

For a list of the changes in this release, see the list at the top of the APES News page.

Running APES using Web Start

If you havey trouble running the application you can launch APES using Web Start. Simply click on the web start link in the menu or follow this link APES Web Start.
After initialization, the main GUI will appear. The start-up procedure partly depends on the contents of your preferences file, which is created in your home directory when you start the APES for the first time. This file, called ".apes.preferences", contains the user's choices for several items, some of which can be accessed via the Preferences menu of the main GUI (see user's preferences section).

III. Graphical User Interface Overview

The GUI that appears after the initialization phase is depicted in Figure 1 for visitor mode and in Figure 2 for service mode.
The GUI is divided into three areas, which are, from top to bottom:

The menu bar, giving access to file-related or plots-related operations and other miscellaneous functionalities (see following sections).
The main panel, divided in five sub-areas which respectively deal with general information, Observational parameters, Elevation plot, astrometric motion plot, the sky conditions, and resulting performance (astrometric accuracy and exposure time).
The action area, gathering general actions such as reference star selection, ETC computation mode or creation of the P2PP parameter file.

Detailed description of each area of APES GUI

Menu bar

General information

Observational parameters

Elevation plot

Figure 6 & 7 represent elevation plots as a function the local sideral time. UT's dome shadowing are shown in "pink shadow", AT's dome shadow are shown in "blue shadow" while delay line stroke limitations are shown in "yellow shadow". The moon elevation plot is also shown as a dashed line.

Astrometric motion plot

Atmospheric parameters

Performance estimator

Reference star selection and Export to P2PP

IV. Target & Reference Stars

The limiting magnitude for the brightest target of the pair (target-reference) is expected to be K=8.5 and for the faintest target : K=14.5. Brighter stars offer better performance. Target information consists of a name, coordinates and proper motion. For the proper motion to be taken into account, it is compulsory to provide both epoch and equinox for which the coordinates are provided. The corresponding coordinates at the time of observation does correspond to the precessed coordinates at the time of the scheduled observations. This is the hardcoded epoch of the reference target. The epoch of the science target is a free parameter to set (between 1850. & 2100.). The science target and the reference star usually have different parallax and proper motion that could be defined at different epochs with the same equinox. However, some reference stars coordinates could have been identified during preparation observing run and for which no coordinates the the J2000.0 frame is known. It is therefore allowed, give a relative position between the target star and its reference at a given date, ie. equinox since we could have no knowledge about its parallax and proper motion. In that case, the coordintates at the time of the observing run are computed by APES by assuming null parallax and proper motion.

Handling several reference objects

It is possible to keep a list of several possible reference objects for observations and work alternatively with each of them. The list of reference objects should be present in "the science target and reference star catalog" which format is described at the end of the document (See science target and reference star catalog format section). Each row, below a science target, corresponds to a reference object, showing its name and its angular distance (in Deltaalpha*cos(delta), Deltadelta) to the science target or its coordinates (one of these two is mandatory). Proper motion can also be provided for the reference object. If several reference objects are available in the catalog, the exposure time calculator will work for up to 5 references simultaneously. Once you have chosen which reference star fullfill your needs better, you can select it and export the corresponding parameters to P2PP.

Morphology of the reference object

The Preparation Software - and the PRIMA instrument - can only handle objects that are barely resolved by the VLTI (up to a few mas in diameter depending on the baseline) to measure the relative phase between the objects. If an object is too resolved, no fringe pattern will be observed and therefore no relative phase could be measured. The size of the object - in solar radius unit - as well as its distance should be provided for the ETC to work.
APES also has to compute the flux coming from the reference object. So far, only the Kband and Vband magnitudes are used to compute the detected number of photons. If necessary, more sophisticated photometric information could be provided in different ways:

Magnitude + Spectral Type. Well suited to main sequence stellar objects. If you choose this option, you will need to enter the apparent magnitude, the filter in which the magnitude is measured (either V,J,H,K,L or M), and a spectral type. The spectral type is chosen in an option button.
Magnitude + Temperature. The magnitude is given in the same way as above (value + filter), but, in this case, the spectral energy distribution is modeled as a black body, which requires a temperature.

Built-in Tools

Baseline Selection Tool

The baseline selection tool can be access from APES Menu=>Setup=>Select a Baseline. This tool allows to select with the mouse (by clicking on the telescope stations) or with a slider (length or orientation) a set of baseline available during an observing period. In expert mode, all baselines are allowed but no parameter files can be exported to P2PP.

Target Selection Tool

The Target Selection Tool is automatically launched when a catalog is opened. This tool allows to make a first selection on the airmass of the target the user want to observe during his observing night or observing run (Menu=>Selection). It allows to decrease the size of the input science target and reference star catalog. However, the main use of this tool is to select a pair of target and reference star within the catalog. The user can then check on the elevation plot and on the astrometric motion plot whether or not the observations should be carried out.

Observation Scheduler Tool

The observation scheduler tool can be access from APES Menu=>view=>Observation Scheduler. This tool allows to visualize and edit the parameter files of an observing night or of a full observing night a function of LST. PAF's can be removed or imported using this tool. y

Preferences, Setup and performances

User's preferences

The Preferences panel gives access to configurable functionalities of APES, which are detailed in the following sections : \

General preferences

In the ``General preferences'' tab, the user can set-up several display option of the main GUI, such as the format of the elevation plot (airmass or elevation), the display of dome vignetting and delay lines stroke limitations.

Path and Files

In the ``Paths and Files'' tab, the user can set APES working directory ie. the name of the directory where the output files are created by APES (the one to be inserted in P2PP OBs) are saved. The default is your home directory. Every change is automatically recorded in the .paf file, located in the APES working directory.\\ The user can also define the location (path or url) of the default science target catalog and past data measurement catalog.

Exposure Time Calculator

In the ``Exposure Time Calculator'' tab, the user can change all the parameters used for the ETC. It should be used by experts during comissionning and once the correct value will be derived, modifications will no longer be possible.

Instrument Setup

There is a limited number of setup for the instrument.

Active tracking :

If the reference star is bright enough, both FSU fringe track and compute the differential phase in real time. This observing mode relax the accuracy at which the position of the reference star is known with respect to the primary star.

Blind tracking :

If the reference star is too faint, the FSU associated with the faint target cannot "see" the fringes. The position of the fringes will be retrieved after data reduction. However, the price to pay is to know with good accuracy (100ms) the position of the reference star with respect to the target star at the time of the observations! (=> good position and good proper motion)

Sky Conditions

The user characterizes the observing conditions via four parameters, the seeing, the coherence time, the isoplanetic angle (at Zenith and measured at 550 nm) and the airmass (or the elevation). The "on axis" quantities, such as the seeing on the target and the reference, are automatically computed from these parameters and some assumptions about the average wind speed and isoplanatic angle on Paranal. The Fried parameter (r0) and the isoplanatic angle (theta0) are also displayed. All on-axis quantities are computed at 550 nm.

Performance Estimator & ETC

The details about the Performance estimator and the ETC are given in the Specification Document. However, the modelisation we used should be confronted to real numbers coming from the instrument and that cannot be done before comissionnning. The two main outputs of the performance estimator that are shown on the APES main GUI are :

the astrometric accuracy that is reached for a given integration time, reference star and projected baseline
the integration time that is necessary to reach a given astrometric accuracy, given a reference star and projected baseline.

All intermediate steps such as signal to noise are displayed in the extended ETC that can be accessed from the APES Menu=>View=>Extended ETC.

APES Import/Export

Exporting to P2PP

All PRIMA acquisition templates require a configuration file which is produced by the Export to P2PP button. It has the default extension "paf" and it is saved in the directory specified in the Preferences menu, under the option set the cache folder. This file contains all the information relevant to the setup of PRIMA during acquisition of the target. When preparing your observations with the APES and P2PP the following points should be noted:

The output file is a text file, and it should never be manually edited. If you do, the execution of your OB will be seriously compromised.
There must be one configuration file per target and per OB. The same configuration file cannot be used for different targets and cannot be used for different OBs using the same target since the integration time depends on the Projected baseline and therefore of the Sideral Time.
All constraints, such as the seeing, the coherence time and the airmass, as well as the sideral time and/or universal time, and the RA and DEC fields and the DIT and the Differential Phase averaging time of P2PP will be automatically filled when the configuration file is loaded. Do not edit these fields.

Saving/Restoring an APES Session

Any exported PAF are saved on local disk and can be resored using the observation scheduler tool. Please be aware that loading a previously saved session file will discard all the data currently stored in the interface. However, it does not alter any of the configuration files that have been saved to disk. Only the files with an extension .paf can be loaded into the APES. Once a previous session is loaded into APES, each target and their corresponding reference can be accessed from the Target selection Tool.

Exporting OBs from P2PP

The export facility in P2PP allows one to export observing blocks. For the narrow angle astrometric mode of PRIMA, two files are produced, one with the extension "obx" and another with the extension "paf". These files should be kept in the same directory. P2PP will report an error if the two files are in different directories.

Catalogs

Past measurements catalog

The narrow angle Astrometric observation PrEparation Software - APES User Manual (V1.0) Damien SÉGRANSAN 05-May-2008