The getCal Interferometric Observation Planning Tool Suite

Manual for getCal-2.10.4

• Contents
• Introduction
• Setup
• Tools Reference
• Release Notes
• Acknowledgments
• Copyright
• Index

getCal is a product of the NASA Exoplanet Science Institute.

1 Introduction

• Overview and Features
• Screenshots

1.1 Overview and Features

getCal is an interferometric observation planning software suite. Its tools can be used to resolve common star names into standard catalog designations and astrometry; extract visibility calibrators from the Hipparcos catalog according to a variety of geometric, brightness, and astrophysical criteria; compute target zenith and delay accessibility; interface with the Simbad astronomical database, the PTI and KI sequencer GUIs, visibility calibration codes, and sky visualization software.

getCal also has other uses, is portable among UNIX varieties, can be autonomously driven over a list of sources, and can be accessed either from either the Unix command line or a (Perl/Tk) GUI.

More abstractly, getCal is an information synthesis tool; it aims to pull together the information needed to efficiently plan and analyze interferometric observations, and to present that information to you in a format you can easily integrate and comprehend.

To the user, getCal appears as an integrated application available from both the command line and GUI that:

• Resolves standard astronomical names (e.g., iota Pegasi) or catalog designations (HR 8430) into standard catalog (e.g. Henry-Draper catalog) designation, rough classification (e.g. Spectroscopic Binary), and astrometry via Simbad and/or the Hipparcos catalog.
• Optionally extracts ancillary/quantitative information from the Simbad database (e.g. broadband photometry, v sin i). See simbadInteractiveQuery.
• Extracts potential visibility calibrators from standard astronomical catalogs (e.g. Hipparcos) according to geometric and astrophysical criteria (e.g. brightness, luminosity class, estimated angular diameter), and will also query Simbad on the potential calibration objects.
• Estimates calibrator angular diameters by a variety of methods, including bolometric flux/effective temperature methods based on spectrophotometry retrieved from Simbad. See fbol.
• Computes both temporal and calendar target and calibrator accessibility (zenith angle and delay) restrictions for user-defined observation locations and/or baselines. See timing and obsCalendar.
• Generates displays of target (list) timings, and runs in real-time against a nightly observing list, displaying LST and sunset/sunrise indicators. See tGui.
• Generates displays of target (list) calendar accessibilities. See ocGui.
• Displays u-v tracks limited by delay and zenith-angle restrictions on user-selectable target and baselines. Also runs in real time to provide current u-v and relative geometry information. See uvTool.
• Composes provisional calibration scripts used to interface with/drive standard KI (PTI) visibility (V^2) calibration codes (see http://nexsci.caltech.edu/software/V2Calib).
• Outputs target astrometry in either PTI-standard or Keck-standard (sky) input formats. See getCal Format.
• Drives XEphem sky plotting software for sky visualization.

For further information on getCal, see the NASA Exoplanet Science Institute software page at http://nexsci.caltech.edu/software.

1.2 Screenshots

Here we're going to give a few illustrative screenshots to whet your appetite and introduce you to a few of the more popular use cases for getCal suite.

Here is the basic user interface window produced by gcGui:

Here's the standard output window that displays the getCal results. The getCal invocation line is coded in blue, the GUI-consumable object designations are coded in red (getCal Format), and everything else is comments intended for your consumption. The "Simbad Browser" button allows you to spawn a Simbad query on the returned objects in an external web browser (see below).

Attached to the "Save Photometry" button in the top-level GUI is the ability to view, save, and edit the photometric data getCal retrieves from Simbad and 2Mass, and to iteratively process your edits through fbol.

Here's an example of the target/calibrator accessibility/timing calculations for 20 December 2002 computed with timing, and displayed with the timing GUI tool tGui.

Here we're actually displaying a whole night's observing schedule for Santa, but if invoked from getCal (gcGui) only the selected target gets displayed. The current UT/LST/local time indicators (vertical red line and text boxes) update in real-time (in case you're at the telescope); lighter red lines indicate target cluster transitions; and the bottom time axis labels toggle between off, LST (default), local time, and UT. Sunrise and sunset times are rendered (blue); timings are calculated by the timing component, and arbitrary sun twilight angles (e.g. 12 deg nautical (default), 18 deg astronomical) can be selected. Moon illumination and sky presence are indicated at the bottom of the graph. tGui renders timings for multiple baselines in multiple notebook pages accessible with tabs, and for multiple baseline observations a "Composite" page has the intersection of accessibility for all baselines. tGui also provides external-browser Simbad query support on the input target list (see below). There is also support for command-line options and batch-mode hardcopy (PostScript, pdf, jpeg, png) creation. Please see the tGui documentation for details.

Along these same lines, getCal components obsCalendar and ocGui respectively compute and display the annual accessibility of astronomical targets. Like the other timing/display components these function can be accessed either within or external to getCal proper.

Here's an example of the u-v track display tool uvTool for HD 187642 on 1 August 2006. The optional concentric circles indicate fringe spacings at various spatial frequencies (in case like me you can't do the conversion between Mlambda and mas in your head). The current UT/LST/HA markers (red arrows) and text update in real-time, as do the current time, hour angle, airmass...(you get the point). uvTool also provides external-browser Simbad query support (see below). Also new in uvTool is support for command-line options and batch-mode hardcopy (PostScript, pdf, jpeg, png) creaton. Please see the uvTool documentation for details.

Finally, here's an example of using the fbol module to fit a single component Plank black-body uniform stellar disk model to the Simbad-extracted broad-band photometry:

2 Setup

• getCal Web Interface
• Building and Installing getCal
• Run-Time Configuration
• Performance

2.1 getCal Web Interface

While we have done our best to simplify the installation procedures here, getCal can take some amount of effort to build and install.

2.2 Building and Installing getCal

• Obtaining getCal and its Dependencies
• Installing the Prerequisites
• Building getCal
• Platform Compatibility

Obtaining getCal and its Dependencies

The following table summarizes the dependencies of getCal, plus other software that is useful alongside it.

Note: Previous releases of getCal used the "lynx" utility as a tool for accessing web services such as Simbad. As of getCal-2.8, lynx is no longer required by getCal.

Package	Version	Note	URL
getCal tarball	2.10.4	Required	http://nexsci.caltech.edu/software
Perl	5.6.1+	Required	ftp://ftp.perl.org/pub/CPAN/src
C++ compiler		Required	ftp://ftp.gnu.org/gnu/gcc
Several Non-standard Perl modules: Time::CTime HTML::TreeBuilder HTML::FormatText LWP::UserAgent		Required	URL not needed if you use CPAN.pm to install these modules. Otherwise you should be able to find them on CPAN at http://www.cpan.org .
Hipparcos catalog		Required	ftp://cdsarc.u-strasbg.fr/pub/cats/I/239
Hipparcos informational annexes		Recommended	ftp://cdsarc.u-strasbg.fr/pub/cats/I/239
Tk library	8.4	Highly recommended	http://sourceforge.net/project/showfiles.php?group_id=10894
Tk Perl module	8.4	Highly recommended	Use CPAN to install this module.
Perl CPAN module	1.76	Highly recommended	ftp://ftp.perl.org/pub/CPAN/modules/by-module/CPAN
ps2pdf		Recommended	ftp://ftp.gnu.org/gnu/ghostscript (ps2pdf is part of the Ghostscript package.)
Gnuplot		Recommended	ftp://ftp.gnuplot.info/pub/gnuplot
Netpbm		Recommended	http://sourceforge.net/projects/netpbm
CIO catalog		Optional	http://ircatalog.gsfc.nasa.gov/
XEphem		Optional	http://www.clearskyinstitute.com/xephem/xephem.html

Installing the Prerequisites

To build getCal, you will need a working *NIX (UNIX or Linux) system with the following items installed. Note that the list order reflects the packages' order of installation.

• C++ compiler (e.g. g++)
• Perl
• Tk*
• Non-standard Perl modules
• Hipparcos catalog
• Hipparcos informational annexes*
• CIO catalog*
• Ghostscript*
• Gnuplot*
• netpbm*
• XEphem*

The starred items above are optional in varying degrees, so you may be able to get along without them. Please refer to the detailed notes below.

Several of these items may have been installed by the system administrator. If you are in doubt, the build scripts for getCal will examine the system and alert you if anything is missing.

C++ compiler

A C++ compiler – for fbol. You almost certainly already have this, but in case you don't, gcc is a popular choice.

Perl

Perl 5.6.1 or higher is required. Almost all of getCal is in Perl, so there's no getting around it. Fortunately Perl is pretty pervasive these days, so this package may come bundled with your system. This dependency/version requirement is checked during the configuration step.

Tk

The Tk package is required if you want to use any of the GUI tools (gcGui, ocGui, tGui, uvTool) in the getCal suite. Thus it is highly recommended that you install Tk prior to building getCal.

The Tk toolkit is often installed by UNIX system administrators. Before installing it yourself, look for library file libtk.so and header tk.h.

Non-standard Perl modules

A default Perl installation includes many useful modules. However, thousands more modules have been written and are publicly available. The Perl community has addressed the issue of distributing such modules by creating the Comprehensive Perl Archive Network (CPAN) Web site, http://www.cpan.org. getCal requires some of these add-on modules. If they are not already installed on your system, they must be installed before building getCal.

A handy utility module CPAN.pm exists to simplify the retrieval and installation of these modules. Once installed at your site, the CPAN module takes care of retrieving and installing other modules from CPAN. It allows you to sidestep the syndrome known as “dependency hell” because it is able to determine inter-module dependencies, find modules already installed on your system, and to transparently install all prerequisites for the modules that you really want. The instructions below use the CPAN module to assist with installing other needed modules.

Installation location for Perl modules

An important decision to be made before continuing is whether modules will be installed in the site's Perl module repository, or in some private repository (e.g. under your home directory). Instructions are provided below for both types of installations.

Installing modules in the site repository will allow other users will be able to access the modules you install. However, depending on how Perl is installed on your system, root access may be necessary to install modules in the site repository. If you do not have root access or write permission to update the site repository you will probably not be able to use this option.

On the other hand, installing modules in a private repository may make cleanup easier should you have trouble with the installation and wish to start fresh, but requires a few extra steps to specify where modules should be installed, and to setup your environment to search for modules in that location.

The following sections describe the procedure for each of these alternatives. If you wish to install modules as a root user in the site repository, follow the steps in the next section. Otherwise, skip ahead to the following section.

Installing Perl modules from CPAN (root user, site repository):

1. Prepare to use passive FTP.

   Some networks have firewalls or gateways that block regular FTP traffic and require the use of "passive" FTP. If you are on such a network, or you find that the module installation procedure below seems to stall at the point of retrieving modules from the Internet, it may be helpful for you to set environment variable FTP_PASSIVE to a value of 1.

2. Test to see whether you already have the CPAN module installed:

             $ perl -MCPAN -e shell
        

   If you find yourself looking at a cpan> prompt, CPAN.pm is already installed and you can skip the next step.

3. Install the CPAN module (if needed):
   • Point your browser at http://search.cpan.org and search for CPAN.
   • Download the latest CPAN tarball to your local machine. At the time of this writing, the latest version of CPAN was 1.76, so that value will be used in this example.
   • Build the module:

                    gunzip -c CPAN-1.76.tar.gz | tar -xv
                    cd CPAN-1.76
                    perl Makefile.PL
                    make
                    make install
               

4. Launch the CPAN shell:

             $ perl -MCPAN -e shell
        

   The very first time you do this after installing CPAN.pm, you will be prompted on whether you want to perform a manual configuration of CPAN. You can generally answer no to this question and let the module work out its own initial settings. If it works, you'll save yourself a long Q&A session.

5. Install your first module:

             cpan> install LWP::UserAgent
        

   You may be prompted that CPAN has found additional dependencies for the requested module, and given an option to prepend those dependencies to the build list. You should answer yes to this question.

   From there on, the process is fairly automatic: CPAN should build, test and install all the required modules. Watch the output for error messages; it should be clear whether or not a module installed correctly.

   Sometimes, the dependency processing doesn't work out cleanly and an installation will fail with a message saying that something wasn't found, even though the dependency was just installed. If an installation step fails, trying it a second time sometimes works.

   If a module still fails to install correctly, you may need to use the force keyword–e.g.:

             cpan> force install LWP::UserAgent
        

   You need to use common sense with this option, though, since it won't do you any good to install a module that truly doesn't work.

6. Repeat the previous step for other modules required by getCal:

             cpan> install Time::CTime
             cpan> install HTML::TreeBuilder
             cpan> install HTML::FormatText
        

7. Install the Tk Perl module

   This item is somewhat optional, just like the Tk library. (The Tk module allows Perl programs to utilize the Tk library, which is written in C.) This module is highly recommended.

   Before you install the Tk module, please be aware that the module's unit tests require an X server (DISPLAY should be defined in the environment). The build script may report errors if you attempt to install Tk via a console-only session.

             cpan> install Tk
        

Installing Perl modules from CPAN (non-root user, private repository):

1. Prepare your local Perl module directory. Create the directory if needed; also create a lib subdirectory:

             mkdir $HOME/perl
             mkdir $HOME/perl/lib
        

2. Prepare to use passive FTP.

   Some networks have firewalls or gateways that block regular FTP traffic and require the use of "passive" FTP. If you are on such a network, or you find that the module installation procedure below seems to stall at the point of retrieving modules from the Internet, it may be helpful for you to set environment variable FTP_PASSIVE to a value of 1.

3. Test to see whether you already have the CPAN module installed:

             $ perl -MCPAN -e shell
        

   If you find yourself looking at a cpan> prompt, CPAN.pm is already installed and you can skip the next step.

4. Install the CPAN module (if needed):
   • Point your browser at http://search.cpan.org and search for CPAN.
   • Download the latest CPAN tarball to your local machine. At the time of this writing, the latest version of CPAN was 1.76, so that value will be used in this example.
   • Build the module:

                    gunzip -c CPAN-1.76.tar.gz | tar -xv
                    cd CPAN-1.76
                    perl Makefile.PL -- PREFIX=$HOME/perl LIB=$HOME/perl/lib
                    make
                    make install
               

5. Modify your PERL5LIB environment variable to include your local Perl library directory, or whereever you are going to put the Perl modules you will be installing in the steps ahead – e.g., $HOME/perl/lib. (If you have multiple paths in PERL5LIB, separate them with colons.) If you modify your personal environment script (~/.bashrc, ~/.cshrc, ~/.profile, etc.), make sure you source the script before continuing.
6. Launch the CPAN shell:

             $ perl -MCPAN -e shell
        

   The very first time you do this after installing CPAN.pm, you will be prompted on whether you want to perform a manual configuration of CPAN. You can generally answer no to this question and let the module work out its own initial settings. If it works, you'll save yourself a long Q&A session.

7. Configure CPAN to place modules in your local Perl repository You can adjust the directories shown here if you want to use something else, just make sure that the LIB directory here is included in $PERL5LIB (see previous step).

             cpan> o conf makepl_arg "PREFIX=~/perl LIB=~/perl/lib"
             cpan> o conf commit
        

8. Install your first module:

             cpan> install LWP::UserAgent
        

   You may be prompted that CPAN has found additional dependencies for the requested module, and given an option to prepend those dependencies to the build list. You should answer yes to this question.

   From there on, the process is fairly automatic: CPAN should build, test and install all the required modules. Watch the output for error messages; it should be clear whether or not a module installed correctly.

   Sometimes, the dependency processing doesn't work out cleanly and an installation will fail with a message saying that something wasn't found, even though the dependency was just installed. If an installation step fails, trying it a second time sometimes works.

   If a module still fails to install correctly, you may need to use the force keyword–e.g.:

             cpan> force install LWP::UserAgent
        

   You need to use common sense with this option, though, since it won't do you any good to install a module that truly doesn't work.

9. Repeat the previous step for other modules required by getCal:

             cpan> install Time::CTime
             cpan> install HTML::TreeBuilder
             cpan> install HTML::FormatText
        

10. Install the Tk Perl module

    This item is somewhat optional, just like the Tk library. (The Tk module allows Perl programs to utilize the Tk library, which is written in C.) This module is highly recommended.

    Before you install the Tk module, please be aware that the module's unit tests require an X server (DISPLAY should be defined in the environment). The build script may report errors if you attempt to install Tk via a console-only session.

              cpan> install Tk
         

Hipparcos catalog

You need to have the Hipparcos catalog installed to perform the basic functionality of selecting calibrators and extracting astrometry. We did this quite intentionally – minimal planning functionality at the telescope must not be compromised even if the network connection is unavailable.

Hipparcos was an ESA space astrometry mission from the late 1980's and 1990's which surveyed roughly 120,000 stars brighter than V ~ 10 (exact magnitude limits are a function of galactic coordinates).

If you don't have the Hipparcos catalog already, you can find zipped copies of the main catalog and annexes at ftp://cdsarc.u-strasbg.fr/pub/cats/I/239.

New in release 2.8, getCal includes a utility makeHipIdx that will generate a set of indexes for the Hipparcos catalog to speed lookups. getCal will use the indexes, if present, to quickly locate records within the catalog instead of searching the entire catalog. Use of these indexes is optional, getCal will still work if they are not available.

Hipparcos informational annexes

If available getCal will scan the Hipparcos informational annexes, specifically concerning multiplicity and variability. getCal will still operate without access to the annexes, but if you're choosing visibility calibrators you really do want that additional information. If you don't have the annexes but would like them you can follow the URL link given above for the full catalog.

In particular, getCal uses the following annexes when available:

• Component solution annex – h_dm_com.dat
• Orbital solution annex – hip_dm_o.dat

You should place the annexes into the same directory as the main Hipparcos catalog files, identified by runtime parameter GC_HIPPARCOS_PATH.

CIO catalog

The Catalog of Infrared Observations. CIO is a valuable source of IR radiometric data. You can find the online information concerning CIOv5.1 (including instructions on how to get your very own copy) at http://ircatalog.gsfc.nasa.gov/.

Ghostscript

tGui, ocGui, and uvTool use the Ghostscript translator ps2pdf to make PDF output. See http://www.cs.wisc.edu/~ghost/.

Gnuplot

fbol can make spectrophotometry plots using gnuplot, but of course only if you have it. Most environments already have gnuplot installed, but in case yours doesn't, you can find it at http://www.gnuplot.info/. Note that some installations of gnuplot may not support the "png" terminal type. If your gnuplot does not support png, you will be unable to save fbol plots in the png format, but other formats (ps, eps) should still work.

Netpbm

tGui, ocGui, and uvTool use utilities from the netpbm package (namely pstopnm, pnmflip, ppmtogif, ppmtojpg, and pnmtopng) to generate GIF, JPEG, and PNG output. Please see http://netpbm.sourceforge.net/.

XEphem

getCal can optionally drive the popular XEphem software for sky visualizations. XEphem can be found at the URL http://www.clearskyinstitute.com/xephem/xephem.html, and is worth the investment of your time to download if you don't already use it...

Building getCal

Building and installing getCal from a distribution tarball (i.e. getCal-*.tar.gz) looks something like this:

     gunzip -c getCal-2.10.4.tar.gz | tar -xv
     cd getCal-2.10.4
     setenv GC_HIPPARCOS_PATH {path to Hipparcos catalog files}
     ./configure --prefix={installation prefix directory}
     make
     make index (optional)
     make check
     make install

The process in detail:

1. Unpack the getCal tarball using gunzip and tar.
2. Set the environment variable GC_HIPPARCOS_PATH to point to the directory containing Hipparcos files. This step is needed only during installation and need not be a permanent setting in your environment. The Hipparcos catalog is required for the unit tests invoked by make check. While it is possible for you to build and install getCal without running the tests, doing so is recommended–it may save you some trouble later on.

   By default, configure looks for the Hipparcos catalog under $(prefix)/data/catalogs/hipparcos, so if your Hipparcos files have that position relative to your installation prefix, you don't need to set GC_HIPPARCOS_PATH explicitly, even while building.

3. Run the configure script. The configure script inspects the system on which it runs, looking for external dependencies such as Perl, Gnuplot, Tk, and so on. It then generates scripts and makefiles tailored to your environment, which you will use for compiling getCal.

   One thing to consider in this step is where you will want getCal to be installed. If you have root access, you might want getCal to go under /usr/local (the default location) or another system-wide directory such as /opt. Otherwise, you'll probably prefer to have it go inside a personal directory such as ~/software.

   The configure script takes a --prefix=[some path] argument. Use this to specify your installation prefix path.

   If configure fails, it should print a descriptive message stating the problem. Generally, it fails because of some unsatisfied dependency; the point is to alert you to any problems as soon as possible.

   Distribution tarballs should always contain a configure script. If you are not building from a tarball or otherwise do not find a configure script, the autoreconf utility will generate a new one. This should not be necessary when building from a distribution tarball. In the top level directory, run

             autoreconf
        

   If you do not have autoreconf available, you can instead try something like:

             aclocal
             automake
             autoconf
        

   Then, run the configure script and continue.

4. make

   This is a fairly quick process but a lot of messages will scroll by. Take note of any error or warning messages.

5. make index

   If your system has the recommended DB_File Perl module, this optional step will run the makeHipIdx utility to create the Hipparcos catalog index files which getCal uses to speed Hipparcos lookups. You don't need to do this step if usable index files already exist.

6. make check

   This optional step runs getCal's unit tests. This step requires several minutes to run, but is a good idea since it exercises your build of getCal. If it passes these tests, getCal should work correctly after installation.

   Note: There is also an option make check-long, which runs a more extensive series of tests. This option is intended primarily for the maintainers of the source code. If you are interested only in validating the build of getCal, make check is the command to use.

7. make install

   If you are installing to a system-wide directory such as /usr/local, you will need to perform this step as the root user.

Platform Compatibility

For your reference, getCal-2.10.4 has been successfully built and tested on the following platforms/configurations:

• Linux: Red Hat 9 (kernel 2.4.20-8), perl 5.8.0, gcc 3.2.2, Perl/Tk 800.025
• Linux: Red Hat Enterprise Linux 4 (kernel 2.4.21-27.0.2), perl 5.8.0, gcc 3.2.3, Perl/Tk 804.027
• Solaris: Solaris 5.8, perl 5.6.1, gcc 3.2.3, Perl/Tk 804.027
• Solaris: Solaris 5.8, perl 5.8.2, gcc 3.2.3 Perl/Tk 800.024
• MacOS: MacOS 10.4.6, Perl v5.8.6 (included with OSX 10.4.6), gcc 4.0.1, Perl/Tk 804.027 (X11 SDK from OSX install CD provides the X11 header files required to build Perl/Tk)

2.3 Run-Time Configuration

getCal has a number of configuration parameters which can be changed by the user. These are documented below.

Prior to version 2.8, getCal required each user to set the run-time configuration through environment variables. Starting with 2.8, environment variables can still be used, but they are no longer required. Instead, getCal now uses a configuration file for most user-configurable values, and uses environment variables to override settings from the config file when desired. Additionally, getCal can use an alternate user-specified configuration file, minimizing the need for numerous environment variables to be set at runtime.

The sources for runtime-configurable values used by getCal are (in order of increasing precedence):

• Site-wide configuration file. This file, created at the time of getCal's installation, is $(prefix)/etc/getCal.conf. Subsequent installations will not overwrite this file, but will update $(prefix)/etc/getCal.conf.example to reflect any changes to the supported parameters.
• Personal configuration file. Set environment variable GC_CONFIG to point to your personal copy of getCal.conf.
• Environment variables. You can override the values of individual parameters by setting them in the environment. This can be especially useful for values like HTTP_PROXY, which may be used by programs other than getCal. It is also backwards- compatible with previous versions of getCal.
• Command-line switches. Some programs support options (e.g., --debug) that overlap with the runtime parameters. Command-line options always take precedence.

The gcConf utility lists all configuration parameters in force, and the source (env var, config file, etc) for each value. Use gcConf to resolve any confusion about what configuration parameters are in effect, and their origins.

getCal's Runtime Parameters

The getCal suite of programs use the following parameters, configurable via getCal.conf or environment variables:

Parameter	Description	Default
GC_CONFIG	Location of getCal configuration file.	$(prefix)/etc/getCal.conf
GC_CIO_CATALOG_PATH	directory containing CIO catalog files	$(prefix)/data/catalogs/CIO5.1/ciov5.1
GC_BROWSER	Browser executable to use when running interactive Simbad queries. Can be any browser that accepts a URL on the command line.	`which mozilla` or `which netscape`
GC_CAL_MINK	Min K mag constraint for calibrator stars	2.0
GC_CAL_MAXK	Max K mag constraint for calibrator stars	5.0
GC_CAL_MINV	Min V mag constraint for calibrator stars	2.0
GC_CAL_MAXV	Max V mag constraint for calibrator stars	7.5
GC_CAL_MINN	Min N mag constraint for calibrator stars	undefined
GC_CAL_MAXN	Max N mag constraint for calibrator stars	undefined
GC_CAL_MINL	Min L/L' mag constraint for calibrator stars	undefined
GC_CAL_MAXL	Max L/L' mag constraint for calibrator stars	undefined
GC_CAL_SEARCHRADIUS	Search radius constraint for calibrator stars. Units are degrees.	10.0
GC_2MASS_SEARCHRADIUS	Search radius for position matching done in 2MASS queries. Units are arcseconds.	3
GC_IRAS_SEARCHRADIUS	Search radius for position matching done in IRAS queries. Units are arcseconds.	10
GC_CIO_CATALOG_PATH	directory containing CIO catalog files	$(prefix)/data/catalogs/CIO5.1/ciov5.1
GC_DEFAULT_BASELINE	Interferometer baseline, depends on location. See interferometers.pm.	all
GC_DEFAULT_BIASOFFSET	Default delay bias offset (LDL), in meters.	0.0
GC_DEFAULT_FORMAT	Output format for getCal. Allowed values: new|old|sky.	new
GC_DEFAULT_INTERFEROMETER	See interferometers.pm	all
GC_DEFAULT_LOCATION	Default observing location. Allowed values are: CHARA Flagstaff KI Keck Lowell MaunaKea MtWilson NPOI PTI Palomar PalomarMtn	Palomar
GC_DEFAULT_TIMEOFFSET	Sets the graphic zero point for tGui. Should be a time offset in the form hh:mm.	00:00
GC_FIRSTPASS_K	If 2MASS Kmag was requested (option --K2Mass), model Kmag must be within this value (in mag) if the indicated Kmag min/max limits before getCal will actually query 2MASS. This reduces the overhead of performing unnecessary 2MASS lookups for stars where the model Kmag is far outside the desired min/max limits.	0.5
GC_FIRSTPASS_N	If IRAS-based Nmag was requested (option --NIRAS), model Nmag must be within this value (in mag) if the indicated Nmag min/max limits before getCal will actually query IRAS. This reduces the overhead of performing unnecessary IRAS lookups for stars where the model Nmag is far outside the desired min/max limits.	0.5
GC_HIPPARCOS_PATH	directory containing Hipparcos catalog (e.g., hip_main.dat) and annex files	$(prefix)/data/catalogs/hipparcos
GC_HIPPARCOS_IDX_PATH	directory to place the Hipparcos catalog index files, created by makeHipIdx and used by getCal to speed catalog searches.	$(prefix)/data/getCal
GC_HTTP_TIMEOUT	Seconds to wait before declaring a timeout on HTTP transactions. Should be a positive integer, or 0 for infinite.	30
GC_IDENT_HDC	Boolean value (0 or 1) to toggle the substitution of `HDC' in place of `HD' in object identifiers output by getCal. The `HDC' prefix is a convention used by PTI, but is otherwise nonstandard usage, so this should be only be used when preparing observing schedules for PTI. Use of `HDC' was the default behavior for getCal releases prior to 2.8.	1
GC_IRSA_HOST	IRSA web server	irsa.ipac.caltech.edu
GC_NULLDEPTH_TRGDIAM	Default target angular size (mas) to use for null depth estimates	1.5
GC_NULLDEPTH_WAVELENGTH	Default Wavelength (um) to use for null depth estimates	11.25
GC_SIMBAD_HOST	Simbad web server	simbad.harvard.edu
GC_SIMBAD_CACHEDIR	Directory for caching of Simbad queries, useful for testing against a known set of Simbad results. Also potentially useful for speeding repeated queries against the same set of objects, though may be dangerous if the cached results become stale, as no checking of the freshness of cached results is done.	None
GC_SIMBAD_CACHEONLY	When set to 1, only previously cached Simbad results are used. If a query is not found in the cache, Simbad is NOT queried, and the query will fail. Useful for testing against a known set of Simbad results, and running getCal when Simbad is offline.	0
GC_TOLERANCE_K	A warning will be output if the difference between model and 2MASS Kmags exceeds this value.	0.4
GC_TOLERANCE_N	A warning will be output if the difference between model and IRAS Nmags exceeds this value.	0.4
GC_TWILIGHT_ANGLE	Default twilight angle limit (degrees below horizon) for sunrise/sunset calculations.	12.0
GC_XEPHEM_FIFO	Optional FIFO file that xeConvert should use for communicating with XEphem	None
GC_ZENITH_ANGLE	Default zenith angle limit (degrees from zenith) for target accessibility calculations.	35.0
HTTP_PROXY	Use this parameter to route HTTP traffic (Simbad and IRSA) through an HTTP proxy server (e.g., localhost:8080).	None

2.4 Performance

getCal can be a fairly slow application. Some parts of it are CPU-intensive; some are I/O-bound; still others spend time waiting for replies from the SIMBAD or IRSA web servers. Here are some ways to improve getCal's performance.

CPU

getCal uses an appreciable amount of CPU time. If you have a choice of hosts on which to run it, you should opt for the faster CPU (e.g., choose Intel ahead of SPARC), and opt for an unloaded, single-user machine over a multi-user system.

I/O

getCal makes extensive use of the Hipparcos catalog; this catalog is stored as a set of files in the local filesystem. It is advisable that the Hipparcos catalog files be stored on a local disk if possible. The GC_HIPPARCOS_PATH parameter tells getCal where to find the catalog files.

New in release 2.8 is an indexing feature for the Hipparcos catalog. getCal includes a utility makeHipIdx that will create a set of index files to greatly speed Hipparcos catalog lookups by allowing getCal to consult the index instead of scanning the entire file. The GC_HIPPARCOS_IDX_PATH parameter tells getCal where to store and find these index files. If the indexes are not available, getCal will still work, but Hipparcos lookups (and the hipRecord command) will function more slowly.

Web Traffic

In the process of acquiring up-to-date information about targets and calibrator stars, getCal issues web-based queries to SIMBAD and IRSA. The time taken performing those queries and waiting for responses can add up, especially when running repeated queries for the same sources.

The overhead of repeated web queries can be reduced by using a caching HTTP proxy server, and routing getCal's queries through that proxy. Depending on your level of interest in improving getCal query performance (and your thirst for adventure), you can also set up such a server on your own system. One such proxy server is Squid (http://www.squid-cache.org), some advice on installing Squid on linux is given below.

A version of Squid, along with a nice gui control panel for it, is available in pre-packaged form for MacOSX. See http://homepage.mac.com/adg/SquidMan/index.html. After installing the package, see the configuration information in the next section.

Setting up Squid

The remainder of this section provides a first-person account of how Squid was used to speed up getCal on one machine. It is not intended as a replacement for Squid's user manual, but rather as a complement to it.

Squid server configuration (root user):

1. I installed Squid 2.5 on my desktop Gentoo Linux machine, patronella.ipac.caltech.edu.
2. I edited Squid's configuration file, /etc/squid/squid.conf, as described by the following annotated diff (before vs. after editing) snippets:
   • Allow caching of CGI queries.

                    438,439c438,439
                    < acl QUERY urlpath_regex cgi-bin \?
                    < no_cache deny QUERY
                    ---
                    > #acl QUERY urlpath_regex cgi-bin \?
                    > #no_cache deny QUERY
               

   • Permit the logging of CGI query parameters.

                    3189c3195
                    < # strip_query_terms on
                    ---
                    > strip_query_terms off
               

   • Set the amount of RAM to use as an in-memory HTTP cache.

                    477c477
                    < # cache_mem 8 MB
                    ---
                    > cache_mem 100 MB
               

   • Adjust object size to accommodate SIMBAD result pages.

                    527c527
                    < # maximum_object_size_in_memory 8 KB
                    ---
                    > maximum_object_size_in_memory 512 KB
               

   • Set Squid's disk-based cache to 500 MB.

                    692c692
                    < # cache_dir ufs /var/cache/squid 100 16 256
                    ---
                    > cache_dir ufs /var/cache/squid 500 16 256
               

   • Set Squid to cache pages for 3-7 days. (SIMBAD's pages have no HTTP expiration timestamp, so Squid's default behavior is not to store them in its cache.)

                    1465c1465
                    < refresh_pattern .             0       20%     4320
                    ---
                    > refresh_pattern .             4320    20%     10080   override-expire reload-into-ims
               

   • Configure access control lists (ACL's) and access rules to limit access to Squid to clients on IPAC local networks, and to restrict HTTP forwarding to only the IRSA or SIMBAD web servers.

                    1871a1872,1877
                    > # Only allow access to domains that getCal uses
                    > acl getcal_usage dstdom_regex simbad.harvard.edu|simbad.u-strasbg.fr|irsa.ipac.caltech.edu
                    > http_access deny !getcal_usage
                    > # Only allow access to local machines
                    > acl ipac_clients src 192.168.1.0/24 192.168.2.0/24
                    > http_access allow ipac_clients
               

3. I started Squid as a daemon process.

Client configuration (non-root user):

1. I ran

             time make check
        

   to establish a rough baseline of how long getCal takes to complete its test suite without using Squid. This took 8 minutes, 55 seconds.

2. I set environment variable HTTP_PROXY to http://patronella.ipac.caltech.edu:3128. (Squid's default TCP port is 3128, not the more common 8000 or 8080.)
3. I ran

             time make check
        

   again. This time, it completed in 3 minutes, 28 seconds.

4. I ran

             grep TCP_ /var/log/squid/access.log
        

   and observed that TCP_HIT appeared throughout the log's entries. TCP_MISS would have indicated that some pages were not cached. Since I had previously run getCal's test suite against Squid, all the required pages should have been–and were, in fact–already loaded in Squid's cache.

   Note that the access log's location may vary by system; it is set in Squid's configuration file.

3 Tools Reference

Command-line tools:

• getCal
• gcList
• csAdhoc
• timing
• fbol
• fbolFormat
• convertPhotometry
• obsCalendar
• xeConvert
• gcConf

Catalog-lookup tools:

• simbadInteractiveQuery
• irsaminer
• 2MassQuery
• IRASQuery

GUI's:

• gcGui
• tGui
• ocGui
• uvTool

Other Utilities:

• makeHipIdx

3.1 getCal

• Description
• Command-Line Options
• Inputs and Outputs
• Format
• Calibration Script Support
• Examples

getCal Description

getCal is the “driver” application for most of the command-line tools in the getCal suite. Given a target, it selects calibrator stars; orchestrates the lookup of target and calibrator data in one or more catalogs; calculates various spectral, photometric and timing-related values of interest; and outputs these data in one of several formats.

getCal Option Summary

Usage:

     	getCal {target options} [other options]

Target Selection Options

     	--searchRA= --searchDec=
     	--targetName= |	--targetHD= | --targetHIP= | --targetDM=

Calibrator Selection Options

     	--cal= | --noCalibrators
     	--searchRadius= --effTemp --linearDiam --lClass=
     	--maxAD= --minK= --maxK= --minV= --maxV= --minN= --maxN= --minL= --maxL=
     	--useMeasurement

Photometry Options

     	--K2Mass --NIRAS --Nband --Lband --Lprime

(Enabled by --fbol; implies --simbadInteractiveQuery):

[from fbol]

     	--constrainTemp

[from fbolFormat]

     	--2Mass --CIO --fLambda --fNu --geneva --gezari --hipparcos/--tycho
     	--longWL --noB --noPlx --noU --noV --stromgren/--uvby

SIMBAD Options (enable with --simbadInteractiveQuery):

     	--allData/--meas --browser --commonNames --coord --FK5 --HD= --HIP=
     	--SAO --html --identifiers/--pseudonyms --Kmag --lineWidth= --list --url

Timing Options (enable with --timing):

     	--airmass= --baseline= --biasOffset=/--LDL=/--offset= --day=
     	--delayLimit= --delayMax= --delayMin= --location= --month=
     	--noEcho --noPreamble --noPrecess --noTargets --precess --replace
     	--twilightAngle= --year= --za=/--zenithAngle=
     	--table --tableStep=
     	--nullDepth -NDstep --NDwavelength --trgAngDiam=

Observation Calendar Options (enable with --obsCalendar):

     	--hourAngle= --location= --noEcho --noPreamble --replace
     	--twilightAngle= --year=

Calibration Script Options

     	--calScript

Output Format Options

     	--format=new|old|sky --noInterspersed --photometry/--savePhotometry
         --noMessages/--noWarnings/--quiet --verbose
         --plx/--parallax --sigFigures=
         --rename --identHDC/--noIdentHDC

Visualization Options

     	--xEphemDisplay

Generic Options

     	--copyright --debug --help --longHelp --version

getCal Command-Line Options

General comments: The use of command-line options in getCal adheres to the Unix standard, except that all the options have long (more than single-character) names. Technically this is referred to as the POSIX standard with GNU extensions. (Handling of options is by Perl's Getopt::Long module, and most of the positive attributes of our command-line processing is by virtue of that module.)

Options should be prefaced by double dashes. You may be able to get away with using single dashes or with abbreviating options, but you could run into trouble–e.g., --searchR could match either --searchRA or --searchRadius.

Options that require arguments should have an equal sign (--option=)as per the GNU convention, though --option val may also work.

Target Selection Options

• --searchRA=, --searchDec=: search input coordinates, no default. The search input coordinates can have a variety of formats, mostly based around either decimal degrees, or an hour/deg - minute - second designation. Here are some examples which should all yield equivalent results:

            --searchRA=331.75
            --searchRA=22:07
            --searchRA=22h7m00s
            --searchRA=22_07_00
            
            --searchDec=25.3333333333333
            --searchDec=25d20m
            --searchDec=25:20:00
            --searchDec=+25_20
       

  If you want to use spaces in the arguments, you may, as long as you quote the arguments using double quotes–e.g.:

            --searchRA="22 07 00" --searchDec="25 20 00"
       

  Note that using seconds is optional for both RA and Dec, but using minutes is not. Without a minutes argument the program will think you're trying to give it a decimal degrees (i.e. --searchRA=22 will be interpreted as 22.0 degrees), probably not what you had in mind.

  When used, these options require a string argument.

• --targetHD=/--targetHIP=/--targetDM=: target ID number/name designations, no default. If used, we will take our search coordinates from the position of the input target – unless searchRA/searchDec are also used, in which case the target position gets overwritten. (Sorry, but this condition is sort of like "Doctor, it hurts when I hit myself in the head with a hammer...".) When used, these options require a numeric argument.

  (BTW, yes the DM option really works, it just works slowly. Try a --targetDM=B+24_4533 (iota Peg) and go get some lunch. Notice you need to replace the spaces in the DM designations by underlines.)

• --targetName=: target common name designation, no default. If used, we will take our search coordinates from a SIMBAD resolution of the name into a HD or HIP numbers, or SIMBAD coordinates if both of those fail. When the name contains spaces, it must be quoted using double-quotes (--targetName=``iota peg''), or else the spaces must be replaced by underscores (--targetName=iota_peg). On-line queries to SIMBAD are not speedy, so be patient. When used this option requires a string argument.

  Note that this is the option of choice when your target doesn't have a HIP entry and you want to observe it anyway. getCal will do its best to compose an appropriate GUI line out of the Simbad coordinate return. The user should especially be on the lookout for missing proper motions...

Calibrator Selection Options

• --cal=[identifier in HD or HIP]: Don't search for calibrators, but instead output just the designated calibrator stars. Multiple --cal= options can be specified as arguments. This option is useful when you know what calibrators you want to use and you just want getCal to assemble the formatted output lines for you. At present the specified calibrators must use HD or HIP formats.
• --noCalibrators: do not scan the Hipparcos catalog for calibrators, default off (yes scan for calibrators). getCal -noCal probably sounds funny, but if you think about this option allows you to do the other things that getCal does (compute coordinates, model SED, query SIMBAD) for a target without the extra step of the calibrator scan (see example #3 below). Default is no – we scan for calibrators. When used, this option does not take an argument.
• --searchRadius=: The geometrical search radius around the search position, default 10 deg. Self-explanatory. --searchRadius=5 will give you a 5-degree search radius. When used, this option requires a numerical argument (deg).
• --effTemp: Compute apparent diameter based on measured V-magnitude, and model bolometric correction and effective temperature based on spectral type. Default behavior is to report average of effective temperature and linear diameter methods. When used, this option does not take an argument.
• --lClass=: select luminosity classes, default V (main-sequence). This allows you to select the luminosity classes you will use in a scan, and you can select more than one. For instance, --lClass=III --lClass=IV --lClass=V will select giant, subgiant, and main sequence calibrator candidates, but will exclude supergiants. The valid values are I, II, III, IV, V, and all; the latter will pass everything. Note that each desired instance of a luminosity class requires a separate --lClass invocation:

            --lClass=III IV V
       

  will just get the giants, while

            --lClass=III --lClass=IV --lClass=V
       

  gets them all. When used, this option requires a string argument.

• --linearDiam: compute apparent diameter based on Hipparcos parallax and model linear diameter. Default behavior is to report average of effective temperature and linear diameter methods. This option overrides use of effTemp option. When used, this option does not take an argument.
• --maxAD=: Maximum angular diameter, no default. If selected, this option will allow you to exclude potential calibrators based on their estimated angular diameter. When used this option requires a numerical argument (mas).
• --maxV=; --minV=; --maxK=; --minK= --maxN=; --minN=; --maxL; --minL: calibrator magnitude limits, defaults of 7.5, 2.0, 5.0, 2.0. There are no default limits for N/L/L' magnitudes. Specifying either --minN=n or --maxN=n implies --Nband. Specifying either --minL=n or --maxL=n implies --Lband.

  When used, these options require a numerical argument (mag). Defaults for these values can be controlled by Run-Time Configuration.

• --useMeasurement: Limit checks for K and N magnitudes (see --minK/--maxK/--minN/maxN above) are normally performed using internal model estimates of K and N, even when --K2Mass and/or --NIRAS are used (see Photometry Options). --useMeasurement causes any 2MASS and IRAS lookups to be performed prior to those limits being tested, potentially slowing the calibrator search by forcing additional network database lookups to be done for sources which may not meet all of the selection criteria. Default off.

Photometry Options

• --K2Mass causes getCal to query the IPAC/IRSA 2MASS database (see http://irsa.ipac.caltech.edu) for K magnitude, and use that value instead of using the internal V-K model used by default. If no 2MASS information is found for a source within the configured 2MASS position search radius (see getCal config param GC_2MASS_SEARCHRADIUS), getCal will issue a warning message and revert to using an internal V-K model.
• --NIRAS causes getCal to query the IPAC/IRSA IRAS database (see http://irsa.ipac.caltech.edu) for IRAS 12um flux, and translates that into an estimated N magnitude.

  The calculation applies a IRAS color correction factor (based on object estimated effective temperature), per the method described in the IRAS PSC Explanatory Supplement, Sec VI. A passband correction factor is then applied to convert the corrected IRAS 12um flux into an estimated N-band (10micron) flux.

  If no IRAS information is found for a source within the configured IRAS position search radius (see getCal config param GC_IRAS_SEARCHRADIUS), getCal will issue a warning message and revert to using a value calculated from an internal V-N model.

  See also --Nband, which is implied when --NIRAS is used.

• --Nband: Include N-band magnitude information on the output line. By default, getCal uses an internal V-N model model as a function of spectral type to provide an estimated N-band (10micron) magnitude. See also the --NIRAS option.

  In the "new" output format, the N-band magnitude appears as an addtional tagged field on the output line (N=...). In the "old" output format, the N-band magnitude will be inserted between the B-V color index and the spectral type. See getCal Format. No argument when used.

• --Lband: Include L-band magnitude information on the output line. This option is only implemented for "new" format output. The L-band magnitude appears as an additional tagged field on the output line (L=...). By default, getCal uses an internal model of K-L as a function of spectral type to provide an estimated L-band magnitude. When --K2MASS is also used, the 2MASS K value will be used for the K-L model calculation of L. No argument when used.
• --Lprime: Similar to --Lband, include L'-band ("L-prime") magnitude information on the output line. This option is only implemented for "new" format output. The L'-band magnitude appears as an additional tagged field on the output line (LPRIME=...). By default, getCal uses an internal model of K-L' as a function of spectral type to provide an estimated L'-band magnitude. When --K2MASS is also used, the 2MASS K value will be used for the K-L' model calculation of L'. No argument when used.

The --fbol option directs getCal to compute apparent diameter estimates based on effective temperature and a bolometric flux model fit to available photometry. (Photometry sources are SIMBAD and 2MASS). Defaults to no.

--fbol sub-options delegated to fbol (see fbol Command-Line Options):

• --constrainTemp

--fbol sub-options delegated to fbolFormat:

• --2Mass: Use IRSA 2Mass photometry on sources in fbol fitting. Default to off.
• --CIO/--gezari: Use photometry/radiometry from the Gezari a.k.a CIO catalog (Fifth Catalog of Infrared Observations, Gezari et al–see http://ircatalog.gsfc.nasa.gov/ ). Off by default.
• --fLambda: Produce photometry/radiometry reports in Flambda units (erg s^-1 cm^-2 um^-1)
• --fNu: Produce photometry/radiometry reports in Fnu units (Jy – 10^-26 W m^-2 Hz^-1)
• --geneva: Produce reports for Geneva photometry. Default to no.
• --hipparcos/--tycho: Produce reports for Hipparcos/Tycho photometry from the Hipparcos catalog. Default to no.
• --longWL: Produce reports for IRAS mid-infrared observations (retrieved from SIMBAD). Off by default.
• --noB: Exclude B-band photometry/radiometry
• --noPlx: Exclude distance estimate/parallax
• --noU: Exclude U-band photometry/radiometry
• --noV: Exclude V-band photometry/radiometry
• --stromgren/--uvby: Produce reports for Stromgren (uvby) photometry

SIMBAD Options

Enable the lookup of calibrator stars in SIMBAD with --simbadInteractiveQuery. By default this option prints out just the Simbad object classification (e.g. iota peg Type: Spectroscopic Binary), but this behavior is customizable through a number of additional options:

• --allData: directs simbadInteractiveQuery to dump all results returned by Simbad. No argument when used.
• --browser [browser_executable]: directs simbadInteractiveQuery to refer the composed queries (URLs) to an external browser. This option takes an optional argument for the browser executable (e.g. /usr/bin/mozilla) – if no argument is given the runtime parameter GC_BROWSER is used for the browser executable. As it takes this optional argument, this option cannot be arbitrarily interspersed with other options when used without argument, but must precede another option or be placed at the end of the line in order for the command-line parsing to function properly, as in

            simbadInteractiveQuery --browser --list iota_Peg 51_Peg
            simbadInteractiveQuery NGC_1068 --browser
       

• --commonNames: directs simbadInteractiveQuery to extract and report common names (e.g. alpha And, Sirrah) on the result summary line. No argument when used.
• --coord: directs simbadInteractiveQuery to extract and report on (ICRS 2000) astrometry for search targets. No argument when used.
• --FK5, --HD, --HIP, --SAO: directs simbadInteractiveQuery to extract and report on specific popular catalog designations. No argument when used.
• --html: Used with --allData, this option makes simbadInteractiveQuery dump the report in HTML rather than plain text.
• --identifiers|--pseudonyms: directs simbadInteractiveQuery to extract and report on all designations for search targets. No argument when used.
• --Kmag: directs simbadInteractiveQuery to estimate K for search targets based on Simbad V and model V-K (based on Simbad spectral type). No argument when used.
• --lineWidth= arg: directs simbadInteractiveQuery to format the result return lines to width argument. Only useful in conjunction with the allData option, integer argument required when used.
• --list: when using the browser option (above), produces a (generally more useful) list query, returning a selectable list of identifiers. No argument when used, ignored if the browser option not selected. Netscape users please note – the list option is especially important for your use, as netscape is challenged with respect to opening multiple windows.
• --url: When this option is included, simbadInteractiveQuery generates and prints the URL for querying Simbad based on your search criteria, but does not execute that query.

Timing Options

• --airmass=: Specify maximum airmass constraint (dimensionless). No default. Overrides --zenithAngle switch, numeric argument required when used.
• --baseline=: Specify interferometer baseline. Default "all" (from GC_DEFAULT_BASELINE runtime parameter). Valid responses are all supported baselines for selected location and are thus context sensitive (e.g. all, PTI_NS, PTI_NW, and PTI_SW for PTI); exception thrown with an invalid baseline designation (and valid list provided in error message). String argument required when used. Multiple baselines are indicated by multiple instances of the baseline option e.g.:

            --baseline=PTI_NS --baseline=PTI_NW
       

  Default all provides timings for all supported baselines at selected location, and supercedes all other baseline arguments. Value of "none" computes no delay timings. May be invoked multiple times.

• --biasOffset=/--LDL=/--offset=: Specify an additional bias (constant, in meters) delay to be added to the baseline models. Default 0 (from GC_DEFAULT_BIASOFFSET runtime parameter). This is an additional bias value to be added to the model static bias included in the interferometer baseline model. Numeric argument required when used.
• --day: Specify day for timing calculations (e.g. --day=16). Default current day. Integer argument required when used.
• --delayLimit=: Specify minimum and maximum delay constraints (meters). Limits are set symmetrically about 0 (i.e. -n to +n). Default adapts to be appropriate for location (e.g. +/- 38.3 m for PTI delay lines, +/- 15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Positive definite numeric argument required when used.
• --delayMin=: Specify minimum delay constraint (meters). Has no effect when --delayLimit is also used. Default adapts to be appropriate for location (e.g. -38.3 m for PTI delay lines, -15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Numeric argument required when used.
• --delayMax=: Specify maximum delay constraint (meters). Has no effect when --delayLimit is also used. Default adapts to be appropriate for location (e.g. +38.3 m for PTI delay lines, +15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Numeric argument required when used.
• --location=: Specify interferometer location. Default Palomar (from GC_DEFAULT_LOCATION runtime parameter). Supported locations (alphabetical order): CHARA, Flagstaff, KI, Keck, Lowell, MaunaKea, MtWilson, NPOI, PTI, Palomar, PalomarMtn, Paranal, VLTI. Exception thrown with an invalid location designation (and valid locations listed in error message). String argument required when used.
• --month=: Specify month for timing calculations (e.g. --month=7). Default current month. Integer argument required when used.
• --noEcho: Do not echo information contained in the input stream, only produce preamble and timing annotations. No argument when used.
• --noPreamble: Compute timings, but do not prepend the timing preamble (i.e. do not say what the timings are for). Default preamble on. No argument when used.
• --noPrecess: Do not apply precession effects to input (J2000) target astrometry to reference to the timing calculation epoch. Default off, no argument when used.
• --noTargets: Output timing preamble but do not compute target timings. Overrides --noPreamble and sets --baseline=none when selected. Default timing calculations on. Note that envVar.(c)sh defines an alias "tonight" (as timing –noTargets) to dump pertinent information about the night's observing conditions. No argument when used.
• --precess: Apply precession effects to input (J2000) target astrometry to reference to the timing calculation epoch. Default on, no argument when used.
• --replace: replace old timing annotations with new ones. No argument when used.
• --twilightAngle=: Specify twilight angle for sunset/sunrise calculations (degrees below horizon). Default is (the industry-standard nautical twilight value of) 12 degrees (from GC_TWILIGHT_ANGLE runtime parameter). Other common values are 18 (astronomical twilight), and 6 (civil twilight). Numeric argument required when used.
• --verbose: provide verbose running commentary on timing calculations. No argument when used.
• --year=: Specify year for timing calculations (e.g. --year=2000). Default is the current year. Integer argument required when used.
• --zenithAngle=/--za=: Specify maximum zenith angle constraint (degrees). Default 35 (from GC_ZENITH_ANGLE runtime parameter). Numeric argument required when used.
• --table Generates table of predicted delay position vs time for each object and baseline. The table is included in output as comment lines. Columns are hour angle (deg), time (UT), total delay (m), delay bias (m, see biasOffset), and FDL delay (m) (this is total delay remaining after adding any delay bias).
• --tableStep Specify time step size (seconds) to use when generating delay predict tables. See --table. Default delay table step size is 300.0 seconds.
• --nullDepth Generate a table of estimated null depth value vs time for each object and baseline. The table is included in output as comment lines. Columns are hour angle (deg), time (UT), projected baseline (m), and null depth. Time interval between output lines is controlled using the --NDstep option.
• --NDstep Specify time step size (seconds) to use when generating null depth tables. See --nullDepth. Default null depth table step size is 300.0 seconds.
• --NDwavelength=/--NDlambda=: Specify wavelength in microns to use for null depth estimate. Default 11.25 um (from GC_NULLDEPTH_WAVELENGTH runtime parameter). Numeric argument required when used.
• --trgAngDiam=: Specify target angular size in mas to use for null depth estimate. Target lines output from getCal do not automatically contain an angular diameter value. Timing will use this value for the angular diameter if no "DIAM=xxx" tag is found for the given source. Default 1.5 mas (from GC_NULLDEPTH_TRGDIAM runtime parameter). Numeric argument required when used.

Observation Calendar Options

--obsCalendar directs getCal to compute observing calendar information for the composed program using obsCalendar. Depending on additional arguments (e.g. --year=) this option can determine calendar constraints for this year, or any other observation year. When used, this option does not take an argument.

Both obsCalendar and timing use the GC_DEFAULT_LOCATION and GC_DEFAULT_BASELINE runtime parameters to define defaults, and fall back to PTI and PTI_NS and PTI_NW baselines if they are not set. A discrete set of other locations and baselines can be used (see --location and --baseline below).

Sub-options enabled with --obsCalendar:

• --hourAngle=: Specify hourAngle offset for additional accessibility calculations – i.e. hours pre-transit at sunrise and hours past transit at sunset. Default off. Units are in hours, numerical argument required when used.
• --location=: Specify observation location; default=Palomar. You will probably prefer to set this parameter through the GC_DEFAULT_LOCATION runtime parameter. Supported locations (alphabetical order): CHARA, Flagstaff, KI, Keck, Lowell, MaunaKea, MtWilson, NPOI, PTI, Palomar, PalomarMtn, Paranal, VLTI; exception thrown with an invalid location designation (and valid locations listed in error message). String argument required when used.
• --noEcho: Do not echo information contained in the input stream, only produce preamble and timing annotations. No argument when used.
• --noPreamble: Do not write a descriptive header into the output.
• --replace: Replace old timing annotations with new ones. No argument when used.
• --twilightAngle=: Specify twilight angle for sunset/sunrise calculations (deg). Default is (the industry-standard nautical twilight value of) 12 degrees. Other common values are 18 (astronomical twilight), and 6 (civil twilight). Numerical argument required when used.
• --year=: Specify year for calculations (e.g. --year=2000). Defaults to current year. Integer argument required when used.

Calibration Script Options

• --calScript: compose a provisional calibration script, default no. This option directs getCal to pipe the target and calibrator Hipparcos records through calScript to format a provisional calibration script. Note that the calibration script generation requires you to have designated a target. Also, the estimated angular diameters are very rough, and based on model information. I'd always suggest you backstop this calculation with your favorite diameter estimation method before you actually start trusting the diameter value. When used, this option does not take an argument, i.e. --calScript directs the program to compose the calibration script. Please see getCal Calibration Script Support for more information.

Output Format Options

• --format=new|old|sky: Used to set the format of getCal's output. For the “new” (Keck) format, the first 12 fields are identical to the "old" (PTI) getCal format (Designation through B-V). The new format uses a TAG=value format for the other fields. For example:

            HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7  0.50 SPECTYP=F8V... ROLE=TRG PID=? PLX=0.0418
       

  The --format=sky option turns on the Keck observatory “sky” format, e.g.:

            HDC4676      00 48 58.708 +16 56 26.318 2000 pmra=-0.002 pmdec=-0.202 vmag=5.1 3.7 F8V... 0.0 xxx   xxx  trg
       

  The default value for this option is is new.

  Please see getCal formats for more information on these formats.

• --noInterspersed:
• --photometry/--savePhotometry: Toggles the printing of photometry output.
• --noMessages, --noWarnings, --quiet: used to suppress informational messages about photometric variability and suspected multiplicity based on Hipparcos determinations. Messages and warnings are enabled by default.
• --verbose: used to enable additional informational messages in the output, including more detailed magnitude values (model, 2MASS, IRAS). Default is off.
• --plx, --parallax: used to have the GUI-formatted lines contain the Hipparcos parallax, units of arcsec. When the most accurate astrometry counts... Default is no, no argument when used.

  The format of the "parallax-enhanced" "old-format" line looks like:

            HDC120136 13 47 15.743 +17 27 24.862 -0.504 0.054 0.06412 4.5 3.2 F7V xxx xxx trg
       

  that is, the parallax (64.12 mas for tau Boo) has been inserted between the dec PM and the V-magnitude. In the "new" output format, the parallax is tagged with "PLX=". See getCal Format.

• --sigFigures=: control the significant figures printed out in coordinates, default 3 fractional digits. Mostly an exercise in perl for myself, this option allows you to specify an arbitrary number of fractional digits in the coordinate output. Default is 3 digits past the decimal (milliarcseconds, in keeping with the quoted accuracy of the Hipparcos catalog). When used this option requires a positive definite integer argument.
• --rename: control rewriting of target names. By default this option is disabled, and target designations specified with the --targetName option will appear in the getCal output as given. When the --rename option is used, getCal will rename the target to an official object designation using information returned by SIMBAD.
• --identHDC/--noIdentHDC: Enables PTI-style "HDC" prefixes for output calibrator names (instead of HD). PTI has the idiosyncracy of preferring HDC instead of HD for target and calibrator prefixes. Overrides GC_IDENT_HDC configuration parameter. By default this option is disabled.

Visualization Options

• --xEphemDisplay: route the composed object list to the XEphem sky display program. See xeConvert. When selected, this option directs getCal to route the composed program (target and calibrators) to the XEphem sky plotting software via the input catalog fifo (named pipe in Unix-land). Good for visual feedback if you're into that sort of thing. Default is no, no xephem interaction. When used, this option takes no argument.

  Note this argument requires you to have xephem running separately, and configured to accept objects through the FIFO mechanism. Please consult the xeConvert on-line documentation.

Generic Options

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.

getCal Inputs and Outputs

In its most basic form, getCal resolves designations into standard catalog representations, and makes potential calibration source recommendations. This takes the command-line form:

     getCal --targetName=iota_Peg

which results in:

     ### GUI catalog from getCal-2.8 ###
     # Resolving target iota_peg via SIMBAD
     # target HD 210027
     HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg
     # HIP 106897 (HD 206043) has his variability flag set (1)
     #  with 0.020 mag scatter in 166 observations
     HDC206043 21 39 01.189 +20 15 55.623  0.131 -0.001 5.8 5.0  0.31 F2V     8.2 0.37+/-0.1  cal HDC210027
     # HIP 107310 (HD 206826) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 4.856
     #    B component -- V= 6.308 at sep 2.002 arcsec/PA 302 deg
     HDC206826 21 44 08.578 +28 44 33.476  0.297 -0.243 4.5 3.3  0.51 F6V     6.1 0.67+/-0.4  cal HDC210027
     HDC208527 21 56 23.984 +21 14 23.490  0.002  0.015 6.4 3.5  1.70 K5V     4.8 0.58+/-1.1  cal HDC210027
     HDC210074 22 07 28.593 +19 28 31.893  0.129  0.037 5.7 4.9  0.33 F2V:    5.9 0.32+/-0.2  cal HDC210027
     HDC210460 22 10 19.021 +19 36 58.821  0.098 -0.094 6.2 4.8  0.69 G0V     5.8 0.32+/-0.3  cal HDC210027
     # HIP 110548 (HD 212395) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 6.391
     #    B component -- V= 9.287 at sep 0.42 arcsec/PA   0 deg
     HDC212395 22 23 39.565 +20 50 53.627  0.359 -0.015 6.2 4.9  0.52 F7V     5.9 0.36+/-0.1  cal HDC210027

The format of getCal's output is documented in getCal Format.

getCal Format

“old” format

getCal supports a legacy “old” format, originally used by the Palomar Testbed Interferometer (PTI, http://nexsci.caltech.edu/missions/alomar.html ) sequencer.

Here are a couple of sample lines:

     # Simbad Search HD 210027: Type: Spectroscopic binary  F5V V=3.76 * iot Peg  * iot Peg A  * 24 Peg
     HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg
     # Simbad Search HD 206043: Type: Variable Star of delta Sct type  F2V V=5.783 V* NZ Peg
     HDC206043 21 39 01.189 +20 15 55.623  0.131 -0.001 5.8 5.0  0.31 F2V     8.2 0.37+/-0.1  cal HDC210027

A description is given for each of these fields in the following table:

Field	Item	Description
1	Designation	Object Designation (string). No spaces are allowed.
2-4	RA (J2000)	Object right ascension in hh mm ss.s format (J2000)
5-7	Dec (J2000)	Object declination in +/-dd mm ss.s format (J2000)
8	PMra	RA Proper motion (arcsec/yr)
9	PMdec	Dec Proper motion (arcsec/yr)
10	V	Object V magnitude (mag)
11	K	Object K magnitude (mag)
12	B-V	Object B-V color (mag)
13	SpYtpe	Object spectral type descriptor (string)
14	AngSep	Angular separation from target (zero for target) (deg)
15	AngDiam	Estimated angular diameter (xxx for target) (mas)
16	AngDiamErr	Estimated angular diameter error (xxx for target) (mas)
17	trg/cal	Target/Calibrator designation (string)

There are several optional variants to this format:

Parallax

One variant on the getCal output format also includes the parallax in arcsec, inserted between the PMdec and V fields:

     # Simbad Search HD 210027: Type: Spectroscopic binary  F5V V=3.76 * iot Peg  * iot Peg A  * 24 Peg
     HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 0.085 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg

This variant is controlled by using the --parallax or --plx command-line option (see getCal Command-Line Options), or the parallax button (see gcGui controls).

N-band Photometry

Another available variant on the getCal output line is the inclusion of an N-band photometry estimate, inserted between the B-V color and spectral type fields:

     # Simbad Search HD 4676: HD 4676 -- Spectroscopic binary  F8V V=5.07 * 64 Psc
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7  0.50 3.7 F8V...  0.0 xxx   xxx  trg

This variant is controlled by using the --Nband and/or --IRAS command-line options (see getCal Command-Line Options), or the N-band and/or IRAS buttons (see gcGui controls).

"new" format

Because of evolving getCal requirements and other new software, a "new" output format has been defined. As of version 2.8, this format is the default for getCal, and is currently used by the Keck Interferometer (KI, http://nexsci.caltech.edu/missions/KI/index.shtml) sequencer.

This format looks like:

     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7  0.50 SPECTYP=F8V... ROLE=TRG PID=? PLX=0.0418 N=3.8
     HDC2454 00 28 20.052 +10 11 23.452  0.033 -0.203 6.0 4.8  0.45 SPECTYP=F6Vawvar ROLE=CAL DIAM=0.36 DIAMERR=0.120 CALFOR=HDC4676 PLX=0.02751 D=8.4 N=4.8

The first 12 fields (Designation through B-V) are identical to the normal "old" getCal format (without the parallax), and the rest of the fields are formatted as "TAG=value", as listed below. Some of these tagged fields are required and some are optional. (For now, the tagged fields will be in the order below as well, but this may change at any time!)

• The CALFOR tag gives the target name for which the source is a calibrator; required for calibrators. Ex.:

            CALFOR=HDC4676
       

• The D tag gives the distance from the target to the calibrator; optional for calibrators. Ex.:

            D=8.4
       

• The DIAM tag gives the angular diameter of the calibrator; required for calibrators. Ex.:

            DIAM=0.36
       

• The DIAMERR tag gives the angular diameter error of the calibrator; required for calibrators. Ex.:

            DIAMERR=0.120
       

• The N tag gives the N-band magnitude of the source, requested using the --Nband and/or --IRAS options (see getCal Command-Line Options); optional for both targets and calibrators. Ex.:

            N=3.8
       

• The L tag gives the L-band magnitude of the source, requested using the --Lband (see getCal Command-Line Options); optional for both targets and calibrators. Ex.:

            L=3.8
       

• The LPRIME tag gives the L'-band ("L-prime") magnitude of the source, requested using the --Lprime (see getCal Command-Line Options); optional for both targets and calibrators. Ex.:

            LPRIME=3.9
       

• The PID tag gives a placeholder for the "project ID" required by other software; required for targets. Ex.:

            PID=?
       

• The PLX tag gives the parallax of the source; optional for both targets and calibrators. Ex.:

            PLX=0.02751
       

• The ROLE tag gives the "role" of the source in this getCal run, either "target" (TRG) or "calibrator" (CAL); required for both targets and calibrators. Ex.:

            ROLE=TRG
       

• The SPECTYP tag gives the spectral type of the source; required for both targets and calibrators. Ex.:

            SPECTYP=F8V
       

This format is requested using the --format=new command-line option (see getCal Command-Line Options), or the New Format button (see gcGui controls).

WMKO sky format

Finally for use with the Keck Interferometer, getCal also supports the William M Keck Observatory's sky software format for generating object lists compatible with Keck telescope control software. This format looks like:

     HDC4676         00 48 58.708 +16 56 26.318 2000 pmra=-0.0002 pmdec=-0.202 vmag=5.1 B-V=0.50 F8V... 0.0 xxx   xxx  trg

The authoritative reference on this format is given at http://www2.keck.hawaii.edu/realpublic/observing/obs_support_coord/starlist-help.html.

This variant is controlled by using the --format=sky command-line option (see getCal Command-Line Options), or the sky button (see gcGui controls).

getCal Calibration Script Support

The V^2 calibration applications wbCalib and nbCalib, part of the V2Calib package, use an input format called a calibration script to define calibration targets and sources, and ancillary information (e.g. astrometry, angular diameter information, etc):

     # Simbad Search HD 9939: Type: High proper-motion Star  K0IV V=6.99
     HDC9939
     01 37 25.107   +25 10 03.969 -0.211 -0.208 0.0238 # K0IV  V = 7.0, K = 5.0
     ---
     2
     # Simbad Search HD 7034: Type: Star  F0V V=5.160
     ##  7 HD7034--F0V      7306 +/-   0    1.79  11    25.82 +/- 0.66  0.52 +/- 0.01  XX
     HDC7034   01 11 06.768   +31 25 29.051  -0.009 -0.012 0.00582 0.50 0.05   # F0V   V = 5.2, K = 4.5
     # Simbad Search HD 7964: Type: Star  A3V V=4.752
     ## 9 HD7964--A3V      8686 +/-   0    9.18  20    47.44 +/- 1.85  0.50 +/- 0.01  XX         XXXX
     HDC7964   01 19 27.993   +27 15 50.611   0.026 -0.012 0.01049 0.47 0.05   # A3V   V = 4.7, K = 4.6

The reader is referred to the V2Calib documentation for more information on this format.

To relieve some of the tedium in composing these calibration scripts, getCal offers you the --calScript option.

getCal --calScript option

getCal supports the creation of a provisional calibration script natively through the use of the --calScript option, as in:

     (gnomad:6) getCal --targetName=iota_peg --calScript --simbadInteractiveQuery
     ### GUI catalog from getCal v2.6dev ###
     # Resolving target iota peg via SIMBAD
     # target HD 210027
     # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76
     HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7 0.43 F5V 0.0 xxx   xxx  trg
     # HIP 106897 (HD 206043) has his variability flag set (1)
     #  with 0.020 mag scatter in 166 observations
     # Simbad Search HD 206043: HD 206043 -- Variable Star of delta Sct type  F2V V=5.783
     HDC206043 21 39 01.189 +20 15 55.623  0.131 -0.001 5.8 5.0 0.31 F2V 8.2 0.37+/-0.1  cal HDC210027
     # HIP 107310 (HD 206826) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 4.856
     #    B component -- V= 6.308 at sep 2.002 arcsec/PA 302 deg
     # Simbad Search HD 206826: HD 206826 -- High proper-motion Star  F6V V=4.51
     HDC206826 21 44 08.578 +28 44 33.476  0.297 -0.243 4.5 3.3 0.51 F6V 6.1 0.67+/-0.4  cal HDC210027
     # Simbad Search HD 208527: HD 208527 -- Star  K5V V=6.399
     HDC208527 21 56 23.984 +21 14 23.490  0.002  0.015 6.4 3.6 1.70 K5V 4.8 0.58+/-1.1  cal HDC210027
     # Simbad Search HD 210074: HD 210074 -- Star  F2V: V=5.742
     HDC210074 22 07 28.593 +19 28 31.893  0.129  0.037 5.7 4.9 0.33 F2V: 5.9 0.32+/-0.2  cal HDC210027
     # Simbad Search HD 210460: HD 210460 -- Star  G0V V=6.194
     HDC210460 22 10 19.021 +19 36 58.821  0.098 -0.094 6.2 4.8 0.69 G0V 5.8 0.32+/-0.3  cal HDC210027
     # HIP 110548 (HD 212395) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 6.391
     #    B component -- V= 9.287 at sep 0.42 arcsec/PA   0 deg
     # Simbad Search HD 212395: HD 212395 -- High proper-motion Star  F7V V=6.04
     HDC212395 22 23 39.565 +20 50 53.627  0.359 -0.015 6.2 4.9 0.52 F7V 5.9 0.36+/-0.1  cal HDC210027
     
     ### Begin Calibration script ###
     # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76
     HDC210027
     22 07 00.648   +25 20 42.402  0.297  0.027 0.08506 # F5V  V = 3.8, K = 2.7
     ---
     6
     # Simbad Search HD 206043: HD 206043 -- Variable Star of delta Sct type  F2V V=5.783
     HDC206043   21 39 01.184   +20 15 55.623   0.123 -0.001 0.02557 0.37 0.1   # F2V   V = 5.8, K = 5.0
     # Simbad Search HD 206826: HD 206826 -- High proper-motion Star  F6V V=4.51
     HDC206826   21 44 08.556   +28 44 33.476   0.260 -0.243 0.04464 0.67 0.4   # F6V   V = 4.5, K = 3.3
     # Simbad Search HD 208527: HD 208527 -- Star  K5V V=6.399
     HDC208527   21 56 23.984   +21 14 23.490   0.002  0.015 0.00284 0.58 1.1   # K5V   V = 6.4, K = 3.6
     # Simbad Search HD 210074: HD 210074 -- Star  F2V: V=5.742
     HDC210074   22 07 28.588   +19 28 31.893   0.122  0.037 0.01639 0.32 0.2   # F2V:   V = 5.7, K = 4.9
     # Simbad Search HD 210460: HD 210460 -- Star  G0V V=6.194
     HDC210460   22 10 19.018   +19 36 58.821   0.092 -0.094 0.01801 0.32 0.3   # G0V   V = 6.2, K = 4.8
     # Simbad Search HD 212395: HD 212395 -- High proper-motion Star  F7V V=6.04
     HDC212395   22 23 39.551   +20 50 53.627   0.335 -0.015 0.0295 0.36 0.1   # F7V   V = 6.2, K = 4.9
     
     ### End Calibration script ###
     
     ...
     

The calibration script composed by getCal in this use case is intended to be provisional only – you may not want to use all the calibrators that getCal suggests, and you certainly want to carefully check the details of the angular diameter estimates provided by getCal in this context.

Please note that if invoked in the context of gcGui, the returned calibration script will be rendered in a dedicated window.

In conjunction with --calScript, you may find the --cal option useful. --cal, which can be supplied multiple times in the getCal command, allows you to specify which calibrator stars should be used, rather than relying on getCal to pick a set for you.

getCal Examples

The following examples will help you get started with getCal by leading you through some of the more popular features. We'll do this in the context of the command-line, but most of these examples can be emulated from the getCal GUI (gcGui) as well. It would be a good exercise to try and emulate these examples in both contexts.

The intended way for you to get access to getCal and it's components is by putting either the mscSoftware/bin directory (e.g. $HOME/mscSoftware/bin). Please see Building and Installing getCal for more information.

getCal requires a valid runtime configuration; see the Run-Time Configuration discussion for more details.

—

1. Let's get started. getCal, like a lot of good programs, will respond with a help message if you give it no arguments:

             (gnomad:2) getCal
             Usage: getCal [target options] [other options]
             
             
             scan for visibility calibrators and format for the GUI, and
             optionally correlate SIMBAD database information, compute target
             accessibility time intervals and plot on the sky using xephem.
             
             
             Options:
             
             -help, -longHelp : help messages of various granularities.  No
                argument.  Overrides all other arguments.
             
             -version : print out version information and exit.  No argument.
             
             -copyright : print out copyright information and exit.  No argument.
             
             -targetName : define target by common name (i.e. iota_peg), and
                resolve into catalog id/coordinates by SIMBAD.  no default,
                argument required when used.
             
             -targetHD | -targetHIP | -targetDM : define target by HD|HIP|DM target
                designation.  no default, argument required when used.
             ...
        

   Notice that there's a -longHelp option that gives a more complete discussion.

2. In terms of actually doing something we'll start small. Just a basic calibrator query on the (in)famous spectroscopic binary iota Peg, resolving the name through the Simbad database, and looking for basic Simbad information and common names for the calibrators:

             (gnomad:6) getCal --format=old --targetName=iota_peg --simbadInteractiveQuery --commonNames
             ### GUI catalog from getCal-2.7c ###
             # Resolving target iota peg via SIMBAD
             # target HD 210027
             # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76 * iot Peg * iot Peg A * 24 Peg
             HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg
             # HIP 106897 (HD 206043) has his variability flag set (1)
             #  with 0.020 mag scatter in 166 observations
             # Simbad Search HD 206043: HD 206043 -- Variable Star of gamma Dor type  F2V V=5.783 V* NZ Peg
             HDC206043 21 39 01.189 +20 15 55.623  0.131 -0.001 5.8 5.0  0.31 F2V     8.2 0.37+/-0.1  cal HDC210027
             # HIP 107310 (HD 206826) has his multiple component flag set to C
             #  the C designation indicates solutions were found for individual components
             #    2 components:
             #    A component -- V= 4.856
             #    B component -- V= 6.308 at sep 2.002 arcsec/PA 302 deg
             # Simbad Search HD 206826: HD 206826 -- High proper-motion Star  F6V V=4.51 * 78 Cyg A * mu.01 Cyg * mu. Cyg A ** STF 2822A
             HDC206826 21 44 08.578 +28 44 33.476  0.297 -0.243 4.5 3.3  0.51 F6V     6.1 0.67+/-0.4  cal HDC210027
             # Simbad Search HD 208527: HD 208527 -- Star  K5V V=6.399
             HDC208527 21 56 23.984 +21 14 23.490  0.002  0.015 6.4 3.5  1.70 K5V     4.8 0.58+/-1.1  cal HDC210027
             # Simbad Search HD 210074: HD 210074 -- Star  F2V: V=5.742
             HDC210074 22 07 28.593 +19 28 31.893  0.129  0.037 5.7 4.9  0.33 F2V:    5.9 0.32+/-0.2  cal HDC210027
             # Simbad Search HD 210460: HD 210460 -- Star  G0V V=6.194 ** CHA 106
             HDC210460 22 10 19.021 +19 36 58.821  0.098 -0.094 6.2 4.8  0.69 G0V     5.8 0.32+/-0.3  cal HDC210027
             # HIP 110548 (HD 212395) has his multiple component flag set to C
             #  the C designation indicates solutions were found for individual components
             #    2 components:
             #    A component -- V= 6.391
             #    B component -- V= 9.287 at sep 0.42 arcsec/PA   0 deg
             # Simbad Search HD 212395: HD 212395 -- High proper-motion Star  F7V V=6.04 * 33 Peg ** STF 2900AB
             HDC212395 22 23 39.565 +20 50 53.627  0.359 -0.015 6.2 4.9  0.52 F7V     5.9 0.36+/-0.1  cal HDC210027
             ...
        

   Before you can get this far getCal will have had to find the Hipparcos catalog (and optionally, the annexes) in your installation.

   Please see the Run-Time Configuration description for more information.

3. Staying with iota Peg, let's assume that I wasn't satisfied with the main sequence (default) calibrators selected the first example. In this next query I'll select giant calibrators within 5 degrees of iPeg, and with estimated K between 3.5 and 4.2:

             
             (gnomad:7) getCal --format=old --targetName=iota_peg --simbadInteractiveQuery --commonName --lClass=III --minK=3.5 --maxK=4.2 --searchRadius=5
             ### GUI catalog from getCal-2.7c ###
             # Resolving target iota peg via SIMBAD
             # target HD 210027
             # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76 * iot Peg * iot Peg A * 24 Peg
             HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg
             # Simbad Search HD 208700: HD 208700 -- Star  K3III V=7.187
             HDC208700 21 57 29.193 +29 18 36.379 -0.001 -0.044 7.2 4.2  1.22 K3III   4.5 0.98+/-0.4  cal HDC210027
             # Simbad Search HD 211432: HD 211432 -- Star  G9III V=6.378
             HDC211432 22 16 29.647 +27 48 14.507 -0.017 -0.004 6.4 4.1  0.98 G9III   3.2 0.94+/-0.3  cal HDC210027
             # Simbad Search HD 211884: HD 211884 -- Star  K5III V=7.33
             HDC211884 22 19 53.969 +25 43 26.316 -0.021 -0.027 7.3 3.7  1.59 K5III   2.9 0.92+/-0.2  cal HDC210027
             
             
             ### Simbad query results ###
             # Simbad Search HD 208700: HD 208700 -- Star  K3III V=7.187
             # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76 * iot Peg * iot Peg A * 24 Peg
             # Simbad Search HD 211432: HD 211432 -- Star  G9III V=6.378
             # Simbad Search HD 211884: HD 211884 -- Star  K5III V=7.33
             
             
             ### End Simbad query results ###
        

4. Now we'll get a little more ambitious. Here I'll get (default main-sequence) calibrators for another SB2 64 Psc, check the Simbad database for types, common names, all archived measurements, and produce a preliminary calibration script for use with wbCalib. (BTW, check out the fun spectral type discrepancy between Simbad and Hipparcos on 55 Psc = HD 3690.) I'll show you one thing you can do with all that Simbad measurement data in the next example...

             (gnomad:13) getCal --format=old --targetName=64_psc --calScript --simbadInteractiveQuery --meas
             ### GUI catalog from getCal-2.7c ###
             # Resolving target 64 psc via SIMBAD
             # target HD 4676
             # Simbad Search HD 4676: HD 4676 -- Spectroscopic binary  F8V V=5.07
             HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7  0.50 F8V...  0.0 xxx   xxx  trg
             # Simbad Search HD 2454: HD 2454 -- High proper-motion Star  F6Vawvar V=6.04
             HDC2454 00 28 20.052 +10 11 23.452  0.033 -0.203 6.0 4.8  0.45 F6Vawvar 8.4 0.36+/-0.1  cal HDC4676
             # Simbad Search HD 3651: HD 3651 -- Variable Star  K0V V=5.80
             HDC3651 00 39 21.806 +21 15 01.701 -0.495 -0.371 5.9 3.9  0.85 K0V     4.9 0.72+/-0.0  cal HDC4676
             # HIP 3138 (HD 3690) has his multiple component flag set to C
             #  the C designation indicates solutions were found for individual components
             #    2 components:
             #    A component -- V= 5.611
             #    B component -- V= 8.657 at sep 6.61 arcsec/PA 194 deg
             # Simbad Search HD 3690: HD 3690 -- Star in double system  K0Iab: V=5.438
             HDC3690 00 39 55.572 +21 26 18.582  0.031 -0.029 5.4 4.5  1.16 F3V...  5.0 0.32+/-0.5  cal HDC4676
             # Simbad Search HD 8723: HD 8723 -- Variable Star  F2V:var V=5.356
             HDC8723 01 26 15.262 +19 10 20.444 -0.028  0.010 5.3 4.5  0.40 F2V:var 9.1 0.49+/-0.1  cal HDC4676
             
             
             ### Begin Calibration script ###
             ## 64 psc
             # Simbad Search HD 4676: HD 4676 -- Spectroscopic binary  F8V V=5.07
             HDC4676
             00 48 58.708 +16 56 26.318 -0.002 -0.202 0.042 ## F8V...  V=5.1 K=3.7
             ---
             3
             # Simbad Search HD 3651: HD 3651 -- Variable Star  K0V V=5.80
             HDC3651 00 39 21.806 +21 15 01.701 -0.495 -0.371 0.090 0.72 0.0 ## K0V     V=5.9 K=3.9
             # Simbad Search HD 3690: HD 3690 -- Star in double system  K0Iab: V=5.438
             HDC3690 00 39 55.572 +21 26 18.582  0.031 -0.029 0.008 0.32 0.5 ## F3V...  V=5.4 K=4.5
             # Simbad Search HD 8723: HD 8723 -- Variable Star  F2V:var V=5.356
             HDC8723 01 26 15.262 +19 10 20.444 -0.028  0.010 0.038 0.49 0.1 ## F2V:var V=5.3 K=4.5
             
             
             ### End Calibration script ###
             
             
             ### Simbad query results ###
             # Simbad Search HD 2454: HD 2454 -- High proper-motion Star  F6Vawvar V=6.04
             
             ...
             
        

   —

5. I'll execute essentially the same query, but this time I'll push the results through getCal's fbol module, which estimates apparent diameters by modeling SEDs and estimating (fitting) effective temperature and bolometric flux based on extracted photometry from Simbad. For reference I'll make (encapsulated PostScript) plots of the photometric models (using gnuplot, required for this purpose)...

             ### GUI catalog from getCal-2.7c ###
             # Resolving target 64 psc via SIMBAD
             # target HD 4676
             # Simbad Search HD 4676: HD 4676 -- Spectroscopic binary  F8V V=5.07
             HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7  0.50 F8V...  0.0 xxx   xxx  trg
             # Simbad Search HD 2454: HD 2454 -- High proper-motion Star  F6Vawvar V=6.04
             HDC2454 00 28 20.052 +10 11 23.452  0.033 -0.203 6.0 4.8  0.45 F6Vawvar 8.4 0.36+/-0.1  cal HDC4676
             # Simbad Search HD 3651: HD 3651 -- Variable Star  K0V V=5.80
             HDC3651 00 39 21.806 +21 15 01.701 -0.495 -0.371 5.9 3.9  0.85 K0V     4.9 0.72+/-0.0  cal HDC4676
             # HIP 3138 (HD 3690) has his multiple component flag set to C
             #  the C designation indicates solutions were found for individual components
             #    2 components:
             #    A component -- V= 5.611
             #    B component -- V= 8.657 at sep 6.61 arcsec/PA 194 deg
             # Simbad Search HD 3690: HD 3690 -- Star in double system  K0Iab: V=5.438
             HDC3690 00 39 55.572 +21 26 18.582  0.031 -0.029 5.4 4.5  1.16 F3V...  5.0 0.32+/-0.5  cal HDC4676
             # Simbad Search HD 8723: HD 8723 -- Variable Star  F2V:var V=5.356
             HDC8723 01 26 15.262 +19 10 20.444 -0.028  0.010 5.3 4.5  0.40 F2V:var 9.1 0.49+/-0.1  cal HDC4676
             
             
             ### Bolometric Flux Diameter Fit results ###
             # option fixedError
             # option eps
             # option stdin
             # 3 command line arguments processed
             # Read 141 data lines from file stdin
             #                                   ChiSqr        F_bol (10^-8       Ang
             #   Star               Teff(K)      /DOF   DOF     erg/cm2/s)     Size (mas)    Filters
               1 HD_2454--F6Vawvar  6019 +/-  85    0.36  18  12.17 +/- 1.17  0.53 +/- 0.11 XXXXXXXXXXXXXXXXXXXX
               2 HD_3651--K0V     4698 +/-  54    3.00  41  14.01 +/- 1.23  0.93 +/- 0.33 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
               3 HD_3690--K0Iab:  4482 +/- 274   12.16   5  22.88 +/- 10.3  1.30 +/- 1.50 XXXXXXX
               4 HD_4676--F8V     5738 +/- 159    0.38   5  29.17 +/- 5.46  0.90 +/- 0.27 XXXXXXX
               5 HD_8723--F2V:var  6204 +/- 205    0.70   6  22.25 +/- 4.83  0.67 +/- 0.26 XXXXXXXX
             
             
             ### Simbad query results ###
             # Simbad Search HD 2454: HD 2454 -- High proper-motion Star  F6Vawvar V=6.04
             ...
             
        

   There are a number of options associated with the fbol module, I'll defer you to the documentation for more details.

6. By popular demand, you can use getCal just to retrieve data on a target using the -noCal switch:

             (gnomad:15) getCal --format=old --targetName=capella --noCal --simbadInteractiveQuery
             ### GUI catalog from getCal-2.7c ###
             # Resolving target capella via SIMBAD
             # target HD 34029
             # HIP 24608 (HD 34029) has his variability flag set (1)
             #  with 0.011 mag scatter in  52 observations
             # HIP 24608 (HD 34029) has his multiple component flag set to O
             #  Warning: the O designation indicates an orbital solution was found
             #   with photocentric SMA 2.16 mas, 104.0220 day period
             # Simbad Search HD 34029: HD 34029 -- Variable of RS CVn type  G5IIIe+... V=0.08
             HDC34029 05 16 41.359 +45 59 52.768  0.109 -0.427 0.1 -3.8  0.80 M1:comp 0.0 xxx   xxx  trg
             
             
             ### Simbad query results ###
             # Simbad Search HD 34029: HD 34029 -- Variable of RS CVn type  G5IIIe+... V=0.08
             
             
             ### End Simbad query results ###
        

7. There is now a "new" output format for the source data lines, required by evolving getCal requirements and other new software. The same query with the format=new option returns:

             (gnomad:51) getCal --format=new --targetName=capella --noCal --simbadInteractiveQuery
             ### GUI catalog from getCal-2.7c ###
             # Resolving target capella via SIMBAD
             # target HD 34029
             # HIP 24608 (HD 34029) has his variability flag set (1)
             #  with 0.011 mag scatter in  52 observations
             # HIP 24608 (HD 34029) has his multiple component flag set to O
             #  Warning: the O designation indicates an orbital solution was found
             #   with photocentric SMA 2.16 mas, 104.0220 day period
             # Simbad Search HD 34029: HD 34029 -- Variable of RS CVn type  G5IIIe+... V=0.08
             HDC34029 05 16 41.359 +45 59 52.768  0.109 -0.427 0.1 -3.8  0.80 SPECTYP=M1:comp ROLE=TRG PID=? PLX=0.07729
             
             
             ### Simbad query results ###
             # Simbad Search HD 34029: HD 34029 -- Variable of RS CVn type  G5IIIe+... V=0.08
             
             
             ### End Simbad query results ###
        

8. One last example with getCal proper. Here I'll just get all the giants in a particular part of the sky (demonstrating the search by location) brighter than a K of 3 (because bright giants are numerous), and run them through the getCal timing module to compute accessibility timings for both the PTI NS and NW baselines (because inquiring minds want to know...):

             (gnomad:16) getCal --format=old --searchRA=21:07 --searchDec=25:30 --lClass=III --maxK=3 --timing --location=PTI --baseline=PTI_NS --baseline=PTI_NW
             ### GUI catalog from getCal-2.7c ###
             posTarget 21 07 00.000 +25 30 00.000 PM? PM? V? K? B-V? Sp? 0.0 xxx   xxx  trg
             HDC196852 20 38 59.517 +30 20 03.355 -0.032 -0.066 5.7 3.0  1.09 K2III   7.8 1.45+/-0.1  cal posTarget
             # HIP 102388 (HD 197752) has his multiple component flag set to G
             #  the G designation indicates acceleration or higher-order terms in astrometric solution
             HDC197752 20 44 52.505 +25 16 14.220 -0.031 -0.178 4.9 2.2  1.18 K2III   5.0 1.78+/-0.4  cal posTarget
             # HIP 103004 (HD 198809) has his multiple component flag set to G
             #  the G designation indicates acceleration or higher-order terms in astrometric solution
             HDC198809 20 52 07.678 +27 05 49.126 -0.081 -0.061 4.6 2.4  0.83 G8III   3.7 1.75+/-0.2  cal posTarget
             HDC199697 20 58 16.351 +22 19 33.267 -0.003 -0.004 5.3 2.0  1.42 K4III   3.7 1.96+/-0.4  cal posTarget
             # HIP 103645 (HD 200043) has his variability flag set (2)
             #  with 0.027 mag scatter in 217 observations
             HDC200043 20 59 58.795 +32 29 44.295 -0.002 -0.028 6.8 2.2  1.64 M3III   7.2 1.83+/-2.1  cal posTarget
             HDC200546 21 03 19.910 +27 19 53.489 -0.014 -0.024 7.1 2.8  1.80 M2III   2.0 1.54+/-1.3  cal posTarget
             
             
             # Timing summary (timing v0.64dev) run at 3/31/2005 UTC, day 2005090
             #  for timings on 3/31/2005 UTC, day 2005090
             # Using PTI Location (long: -116:51:48   lat: +33:21:24)
             # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
             # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
             # The JD at 0 hr UT is 2453460.5 (precessing coordinates to this date)
             # The LST at 0 hr UT is 04:46:25
             # The Local Time at 0 hr UT is 16:00:00
             # Approximate UT sunset -- sunrise times: 03:00 -- 12:42 (12 deg twilight)
             # Approximate LST at sunset -- sunrise: 07:47 -- 17:31
             # Approximate UT moonrise -- moonset times: 07:41 -- 17:22
             #   66% moon illumination -- 1.5 days before last quarter (moon transit 17 23 RA  -28 15 Dec)
             # Using 35 deg zenith angle (1.22 airmass) constraint
             # Using -38.3 to 38.3 m delay interval
             # posTarget 21 07 13.8  +25 31 16.6  transits at 16:18 UT, zenAng 7.8 deg (1.01 am) target
             # posTarget is within zenith angle range from 13:40 to 18:55 UT
             # posTarget is within delay range from 13:05 to 23:45 UT for PTI_NS
             # posTarget is within delay range from 13:58 to 18:04 UT for PTI_NW
             # HDC196852 20 39 12.5  +30 21 10.6  transits at 15:50 UT, zenAng 3.0 deg (1.00 am)
             # HDC196852 is within zenith angle range from 13:04 to 18:35 UT
             # HDC196852 is within delay range from 13:04 to 22:51 UT for PTI_NS
             # HDC196852 is within delay range from 13:31 to 17:52 UT for PTI_NW
             # HDC197752 20 45 06.1  +25 17 23.5  transits at 15:56 UT, zenAng 8.1 deg (1.01 am)
             # HDC197752 is within zenith angle range from 13:18 to 18:33 UT
             # HDC197752 is within delay range from 12:42 to 23:25 UT for PTI_NS
             # HDC197752 is within delay range from 13:35 to 17:42 UT for PTI_NW
             ...
        

9. A lot of the programs in the getCal suite were written to have a life of their own outside getCal. I introduced you to a particular instance in the previous example – timing. I developed timing (and it's matching GUI tGui) primarily to layout PTI nightly schedules, and its getCal application is largely an afterthought. A stand-alone invocation of timing would be:

             (gnomad:18) timing --replace --day=12 --month=8 --base=PTI_NS --baseline=PTI_NW < ~/mscSoftware/src/tools/planning/getCal/getCal-2.7/src/timing/testCases/14july00.cat
             # Timing summary (timing v0.64dev) run at 3/31/2005 UTC, day 2005090
             #  for timings on 8/12/2005 UTC, day 2005224
             # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
             # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
             # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
             # The JD at 0 hr UT is 2453594.5 (precessing coordinates to this date)
             # The LST at 0 hr UT is 13:34:44
             # The Local Time at 0 hr UT is 17:00:00 (Daylight Savings Time)
             # Approximate UT sunset -- sunrise times: 03:35 -- 12:09 (12 deg twilight)
             # Approximate LST at sunset -- sunrise: 17:10 -- 01:46
             # Approximate UT moonrise -- moonset times: 19:03 -- 06:07
             #   39% moon illumination -- 1.1 days before first quarter (moon transit 14 12 RA  -15 50 Dec)
             # Using 35 deg zenith angle (1.22 airmass) constraint
             # Using -38.3 to 38.3 m delay interval
             #
             # NW baseline, K20 mode
             #
             ## Cluster 1: Sundown to 4:30 UT
             # Simbad Search HD 134083: Type: Variable Star  F5V V=4.93 * 45 Boo  * c Boo
             # HDC134083 15 07 32.8  +24 50 52.2  transits at 01:32 UT, zenAng 8.5 deg (1.01 am)
             # HDC134083 is within zenith angle range from 22:56 to 04:09 UT
             # HDC134083 is within delay range from 22:16 to 09:03 UT for PTI_NS
             # HDC134083 is within delay range from 23:12 to 03:17 UT for PTI_NW
             HDC134083 15 07 18.066 +24 52 09.104  0.204 -0.164 4.9 3.8 F5V 6.6 0.62+/-0.1  cal HDC131511
             # Simbad Search HD 131511: Type: Variable Star  K2V V=6.01 V* DE Boo (BY Dra Var, 125 d period)
             # HDC131511 14 53 39.2  +19 07 48.3  transits at 01:18 UT, zenAng 14.2 deg (1.03 am) target
             # HDC131511 is within zenith angle range from 22:54 to 03:42 UT
             # HDC131511 is within delay range from 21:34 to 09:18 UT for PTI_NS
             # HDC131511 is within delay range from 22:55 to 02:49 UT for PTI_NW
             HDC131511 14 53 23.766 +19 09 10.074 -0.469  0.217 6.0 3.8 K2V xxx xxx trg
             ...
        

   I'm not going to reproduce the timing documentation here, but three particular variants I'll bring to your attention are

   a) routing the output of timing into the timing GUI tGui

             (gnomad:39) timing -replace -day 12 -month 8 -base PTI_NS -baseline PTI_NW < 14july00.cat | tGui
        

   b) routing the timing output to the u-v track visualization tool uvTool:

             (gnomad:40) timing -replace -day 12 -month 8 -b PTI_NS -baseline PTI_NW < 14july00.cat | uvTool
        

   c) a specialized invocation of timing that reports interesting astronomical information:

             (gnomad:19) which tonight
             tonight:         aliased to timing --noTargets
             (gnomad:20) tonight
             # Timing summary (timing v0.6dev) run at 3/31/2005 UTC, day 2005090
             #  for timings on 3/31/2005 UTC, day 2005090
             # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
             # The JD at 0 hr UT is 2453460.5 (precessing coordinates to this date)
             # The LST at 0 hr UT is 04:46:25
             # The Local Time at 0 hr UT is 16:00:00
             # Approximate UT sunset -- sunrise times: 03:00 -- 12:42 (12 deg twilight)
             # Approximate LST at sunset -- sunrise: 07:47 -- 17:31
             # Approximate UT moonrise -- moonset times: 07:41 -- 17:22
             #   66% moon illumination -- 1.5 days before last quarter (moon transit 17 23 RA  -28 15 Dec)
        

3.2 gcList

gcList – Run getCal over a list of targets

Relatively early in the getCal lifecycle users started requesting a way to drive getCal over a list of targets rather than only target at a time. Our answer was gcList. gcList reads an input (standard input) list of targets and an optional set of getCal command line options, and walks the input list invoking getCal on each input target, returning the getCal output (standard output). Any input getCal command-line directives are forwarded to getCal for each target. A typical gcList invocation would look like:

     gcList [--objDesig=name|HD|HIP] [getCal command-line arguments] < targetList [> gc.targList.out]

gcList recognizes two command-line arguments:

• --help: Print-out (this) short documentation prose and exit
• --objDesig=: Indicate the type of target specification designation used on input. gcList defaults to assume that the input target list consists of Simbad-resolvable names. However, HD or HIP catalog designations can also be given. For example --objDesig=HD directs gcList to expect HD (Henry-Draper) catalog designations. When used, this option requires a string argument having value HD, HIP, or name.

Input file format:

The following is a sample input file format:

     iota peg ## Iota Peg -- SB2
     
     # Random comment
     
     64 Psc
     

Comments are indicated by a pound or hash sign (#). All characters on a line following one or more comment characters are ignored.

Example:

An illustrative invocation of gcList is:

     (gnomad:8) gcList -fbol < tmp
     
     
     ## executing getCal -targetName iota_peg -fbol
     
     ### GUI catalog from getCal-2.7c ###
     # Resolving target iota peg via SIMBAD
     # target HD 210027
     # Simbad Search HD 210027: HD 210027 -- Spectroscopic binary  F5V V=3.76
     HDC210027 22 07 00.666 +25 20 42.402  0.328  0.027 3.8 2.7  0.43 F5V     0.0 xxx   xxx  trg
     # HIP 106897 (HD 206043) has his variability flag set (1)
     #  with 0.020 mag scatter in 166 observations
     # Simbad Search HD 206043: HD 206043 -- Variable Star of gamma Dor type  F2V V=5.783
     HDC206043 21 39 01.189 +20 15 55.623  0.131 -0.001 5.8 5.0  0.31 F2V     8.2 0.37+/-0.1  cal HDC210027
     # HIP 107310 (HD 206826) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 4.856
     #    B component -- V= 6.308 at sep 2.002 arcsec/PA 302 deg
     # Simbad Search HD 206826: HD 206826 -- High proper-motion Star  F6V V=4.51
     HDC206826 21 44 08.578 +28 44 33.476  0.297 -0.243 4.5 3.3  0.51 F6V     6.1 0.67+/-0.4  cal HDC210027
     # Simbad Search HD 208527: HD 208527 -- Star  K5V V=6.399
     HDC208527 21 56 23.984 +21 14 23.490  0.002  0.015 6.4 3.5  1.70 K5V     4.8 0.58+/-1.1  cal HDC210027
     # Simbad Search HD 210074: HD 210074 -- Star  F2V: V=5.742
     HDC210074 22 07 28.593 +19 28 31.893  0.129  0.037 5.7 4.9  0.33 F2V:    5.9 0.32+/-0.2  cal HDC210027
     # Simbad Search HD 210460: HD 210460 -- Star  G0V V=6.194
     HDC210460 22 10 19.021 +19 36 58.821  0.098 -0.094 6.2 4.8  0.69 G0V     5.8 0.32+/-0.3  cal HDC210027
     # HIP 110548 (HD 212395) has his multiple component flag set to C
     #  the C designation indicates solutions were found for individual components
     #    2 components:
     #    A component -- V= 6.391
     #    B component -- V= 9.287 at sep 0.42 arcsec/PA   0 deg
     # Simbad Search HD 212395: HD 212395 -- High proper-motion Star  F7V V=6.04
     HDC212395 22 23 39.565 +20 50 53.627  0.359 -0.015 6.2 4.9  0.52 F7V     5.9 0.36+/-0.1  cal HDC210027
     
     
     ### Bolometric Flux Diameter Fit results ###
     # option fixedError
     # option stdin
     # 2 command line arguments processed
     # Read 170 data lines from file stdin
     #                                   ChiSqr        F_bol (10^-8       Ang
     #   Star               Teff(K)      /DOF   DOF     erg/cm2/s)     Size (mas)    Filters
       1 HD_206043--F2V   6157 +/- 322    1.86   6  15.53 +/- 5.37  0.57 +/- 0.35 XXXXXXXX
       2 HD_206826--F6V   6212 +/-  96    0.71   9  41.8 +/- 3.6  0.92 +/- 0.21 XXXXXXXXXXX
       3 HD_208527--K5V   3319 +/- 257    8.95   5  22.51 +/- 12.6  2.36 +/- 2.79 XXXXXXX
       4 HD_210027--F5V   6353 +/-  68    1.44  53  83.67 +/- 5.58  1.24 +/- 0.31 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
       5 HD_210074--F2V:  8277 +/- Inf     Inf   0  17.33 +/- Inf  0.33 +/-  Inf XX
       6 HD_210460--G0V   5092 +/-  96    0.23   5  12.32 +/- 1.69  0.74 +/- 0.17 XXXXXXX
       7 HD_212395--F7V   6649 +/- Inf     Inf   0  11.55 +/- Inf  0.42 +/-  Inf XX
     
     
     ### Simbad query results ###
     # Simbad Search HD 206043: HD 206043 -- Variable Star of gamma Dor type  F2V V=5.783
     
     [snip]
     

3.3 csAdhoc

Warning: csAdhoc is deprecated and may be removed from the getCal suite in the future. You should use getCal --calScript --cal instead.

A tool for ad-hoc calibration script generation is csAdhoc:

     (gnomad:10) csAdhoc --target=iota_peg HD_210074 HD_206043 capella 51_peg --verbose
     ## iota_peg resolved to HIP 109176
     ## HD_210074
     ## HD_206043
     ## capella resolved to HIP 24608
     ## 51_peg resolved to HIP 113357
     HDC210027
     22 07 00.648   +25 20 42.402  0.297  0.027 0.08506 # F5V  V = 3.8, K = 2.7
     ---
     4
     HDC210074   22 07 28.588   +19 28 31.893   0.122  0.037 0.01639 AD?  ADerr?   # F2V:   V = 5.7, K = 4.9
     HDC206043   21 39 01.184   +20 15 55.623   0.123 -0.001 0.02557 AD?  ADerr?   # F2V   V = 5.8, K = 5.0
     HDC34029   05 16 41.340   +45 59 52.768   0.076 -0.427 0.07729 AD?  ADerr?   # M1:comp   V = 0.1, K = -3.8
     HDC217014   22 57 27.972   +20 46 07.796   0.208  0.061 0.0651 AD?  ADerr?   # G5V   V = 5.5, K = 3.9
     

csAdhoc is designed for those circumstances when the user has taken the data already, and wants to compose a provisional calibration script with a particular set of calibration objects.

The standard invocation of csAdhoc can be with or without a target designation, as in:

     csAdhoc [--target=targetDesig] cal1 [cal2...]

such as:

     (gnomad:13) csAdhoc HD_210074 HD_206043 capella 51_peg
     ---
     4
     HDC210074   22 07 28.588   +19 28 31.893   0.122  0.037 0.01639 AD?  ADerr?   # F2V:   V = 5.7, K = 4.9
     HDC206043   21 39 01.184   +20 15 55.623   0.123 -0.001 0.02557 AD?  ADerr?   # F2V   V = 5.8, K = 5.0
     HDC34029   05 16 41.340   +45 59 52.768   0.076 -0.427 0.07729 AD?  ADerr?   # M1:comp   V = 0.1, K = -3.8
     HDC217014   22 57 27.972   +20 46 07.796   0.208  0.061 0.0651 AD?  ADerr?   # G5V   V = 5.5, K = 3.9

and

     (gnomad:16) csAdhoc HD_206043 capella sirius 51_peg -target spica
     HDC116658
     13 25 11.580   -11 09 40.759 -0.043 -0.032 0.01244 # B1V  V = 1.0, K = 1.7
     ---
     4
     HDC206043   21 39 01.184   +20 15 55.623   0.123 -0.001 0.02557 AD?  ADerr?   # F2V   V = 5.8, K = 5.0
     HDC34029   05 16 41.340   +45 59 52.768   0.076 -0.427 0.07729 AD?  ADerr?   # M1:comp   V = 0.1, K = -3.8
     HDC48915   06 45 08.931   -16 42 58.017  -0.546 -1.223 0.37921 AD?  ADerr?   # A0m...   V = -1.4, K = -1.4
     HDC217014   22 57 27.972   +20 46 07.796   0.208  0.061 0.0651 AD?  ADerr?   # G5V   V = 5.5, K = 3.9

Overstating the obvious, without a target designation the intent is that the target line is to be supplied later by the user.

In all cases csAdhoc does not prepare angular diameter estimates for calibrators – instead these fields are left to be supplied by the user. Please note that wbCalib and nbCalib (part of the V2Calib package) will fail to parse such a calibration script without numerical values in these fields.

At the time of this writing targets and calibrators served by csAdhoc must be contained in the Hipparcos catalog.

Note: before getCal v. 2.7, csAdhoc did not correctly handle HIP designations; it was getting the HIP number from an undefined variable. Now it uses the input target HIP number properly.

3.4 timing

timing – Compute interferometric target temporal accessibility

• timing Description
• timing Command-Line Options
• timing Defaults and Customization
• timing Examples

timing Description

timing is a Perl program that ingests one or more astronomical target specifications (identifier + RA/Dec), and computes interferometer temporal accessibility for these targets, specifically when the target matches zenith and delay specifications for a given site on a specified day. This information is (by default) inserted into the input stream on output in the form of pound (hash – #) delimited annotations, and input to and output from timing is done through the stdin and stdout channels. Using command-line arguments the user can specify date for the calculation, geometric criteria (zenith angle, delay limits, bias offsets), location (e.g. Palomar), multiple baseline designations (e.g.: PTI_NS, PTI_NW, all), and various other output options. Timing also has the ability to compute pointing accessibility based on physical telescope alt/az limits.

The canonical use case is that the user has some list of astronomical targets (objects), and timing is used as a conduit to add timing constraint information to that list (as in):

     timing [options] < list.in > list.out

or

     timing [options] --stdin < list.in > list.out

(one of the recognized options is --stdin – see command-line options below). Note that to use the first form the user cannot enter ANY options not recognized by timing (i.e. ARGV must be empty after processing through getOpt).

Alternatively, timing can also accept a filename as an argument:

     timing [options] --filename=list.in

or

     timing [options] --filename=list.in --filename=list2.in --filename=list3.in > list.out

Note that in the last form the user cannot enter ANY options not recognized by timing (i.e. ARGV must contain only desired files after processing through getOpt). Object lists from multiple input files are concatenated in their order of appearance on the output stream.

As implied, in any form timing's output is written to stdout.

The coordinate format is a standard ASCII obj, ra, dec + ancillary data format common in astronomical applications. For example, at PTI (where timing was developed) this format looks like:

     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

timing is interested in the positional information and target/calibrator role only, and (except as indicated in the option settings) only adds to the input stream, so the format of the remainder of the line is arbitrary from the timing perspective. The target/calibrator role information must be found somewhere in the line as the strings "trg", "cal", "ROLE=TRG" or "ROLE=CAL". We explicitly assume that input astrometry is referenced to epoch J2000.

Timing constraint information is added in the form of comment information (indicated by a #-sign) prefacing each valid target line detected in the input stream (we refer to these as timing annotations):

     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     # HDC234677 18 33 55.773  +51 43 08.905  transits at 06:44:49 UT, zenAng 18.4 deg target
     # HDC234677 is within zenith angle range from 03:58:49 to 09:30:49 UT
     # HDC234677 is within delay range from 07:33:09 to 10:11:57 UT for PTI_NS
     # HDC234677 is within delay range from 04:18:23 to 19:31:16 UT for PTI_NW
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

When input to the PTI/KI sequencers these timing annotations are ignored as comment lines. You can already see that timing is setup to handle interferometers with multiple simultaneous baselines (i.e. NOT PTI).

So you can actually figure out what all these calculations are based on, timing provides a preamble in the output stream that provides context:

     # Timing summary (timing v0.51dev) run at 12/28/2001 UTC, day 2001362
     #  for timings on 12/28/2001 UTC, day 2001362
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
     # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
     # The JD at 0 hr UT is 2452271.5
     # The LST at 0 hr UT is 22:38:41
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 01:46:00 -- 13:51:41 (12 deg twilight)
     # Approximate LST at sunset -- sunrise: 00:24:59 -- 12:32:39
     # Approximate UT moonrise -- moonset times: 22:43:48 -- 13:00:29
     #   94% moon illumination -- 2.2 days until full moon (moon at 04:26 RA  +19:46 Dec)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     # Using 38.3 m delay constraint

In particular there's interesting sunset/rise, moonrise/set/illumination/phase, LST, Julian date, and local time information in the preamble. If the user ONLY desires this information and no target accessibilities we have added the –noTargets option to exit timing after the (pertinent part of the) preamble is finished (see command-line options below).

timing's output is designed to be human readable, but the tGui and uvTool graphical user interface (GUI) applications also read that format and create (hopefully) informative line graph renderings of the timing output in temporal and u-v track spaces – see the tGui and uvTool documentation for details.

timing allows the computation of delay limits for interferometers with two stages of delay (i.e. "long" delay lines and "fast" delay lines, like NPOI and KI). The --biasOffset option (used in conjunction with the --delayLimit option) allows timing to compute either the full temporal delay limits, or just the temporal delay limits with the long delay lines in a particular configuration.

timing computes target zenith angle constraints based on a default value of the zenith angle (35 degrees), but this behavior can be modified using either the --zenithAngle (--za) or the --airmass switches (see below). For example:

     timing --zenithAngle=40 < list.in > list.out
     timing --airmass=1.25 < list.in > list.out

(Note: the airmass switch overrides the zenithAngle switch.)

For timing users also interested in using single-aperture telescopes (e.g. me), the baseline command-line option now accepts "none" (or "NONE" or "None") to NOT compute delay timings:

     timing --baseline=none < list.in > list.out

By default, target astrometry (assumed J2000) is precessed to the current epoch/epoch of calculation. This can be controlled on or off with the -precess and -noPrecess options discussed below.

In addition to zenith angle and delay range constraints, timing can also compute windows of pointing accessibility for the given telescope/baseline. This captures the limitations of telescope pointing, since many telescopes are unable to access certain parts of the sky due to physical constraints of the telescope mount or nearby obstructions. These calculations are only done for baselines where pointing limits have been configured (sorry, they're hardcoded at this time, see interferometers.pm if you want to hack and add your own). Pointing range information is reported similarly to zenith and delay range information, as comments in the output stream.

     # altair 19 51 05.9  +08 53 07.1  transits at 10:16 UT, zenAng 10.9 deg (1.02 am) target
     # altair is within zenith angle range from 07:59 to 12:34 UT
     # altair is within delay range from 11:17 to 18:05 UT for KI_K1K2
     # altair is within pointing range from 06:26 to 13:52 UT for KI_K1K2
     altair 19 50 46.999 +08 52 05.959  0.543  0.386 0.8 0.3  0.22 SPECTYP=A7IV-V ROLE=TRG PID=PID?

timing comes with an ancillary utility stripTiming that removes the timing annotations added by timing. (stripTiming is actually just a tedious grep call.) The use case here is that you want to remove (and possibly replace) timing annotations previously inserted in a list:

     stripTiming < list.in [| timing [options] ] > list.out

or more straightforwardly, timing will pass the input through stripTiming for you using the -replace argument:

     timing --replace [options] < in > out

Like timing, stripTiming takes its input on stdin and produces its output on stdout.

timing is also used as a component in the getCal suite to provide timing information for experiment planning purposes.

timing Command-line Options

Usage:

     	timing [options]

where valid options include:

     	--airmass= --baseline= --biasOffset=/--LDL=/--offset= --day=
     	--delayLimit= --delayMax= --delayMin= --location= --month=
     	--noEcho --noPreamble --noPrecess --noTargets --precess --replace
     	--twilightAngle= --year= --za=/--zenithAngle=
     	--table --tableStep=
     	--nullDepth -NDstep --NDwavelength --trgAngDiam=

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --airmass=: Specify maximum airmass constraint (dimensionless). No default. Overrides --zenithAngle switch, numeric argument required when used.
• --baseline=: Specify interferometer baseline. Default "all" (from GC_DEFAULT_BASELINE runtime parameter). Valid responses are all supported baselines for selected location and are thus context sensitive (e.g. all, PTI_NS, PTI_NW, and PTI_SW for PTI); exception thrown with an invalid baseline designation (and valid list provided in error message). String argument required when used. Multiple baselines are indicated by multiple instances of the baseline option e.g.:

            --baseline=PTI_NS --baseline=PTI_NW
       

  Default all provides timings for all supported baselines at selected location, and supercedes all other baseline arguments. Value of "none" computes no delay timings. May be invoked multiple times.

• --biasOffset=/--LDL=/--offset=: Specify an additional bias (constant, in meters) delay to be added to the baseline models. Default 0 (from GC_DEFAULT_BIASOFFSET runtime parameter). This is an additional bias value to be added to the model static bias included in the interferometer baseline model. Numeric argument required when used.
• --day: Specify day for timing calculations (e.g. --day=16). Default current day. Integer argument required when used.
• --delayLimit=: Specify minimum and maximum delay constraints (meters). Limits are set symmetrically about 0 (i.e. -n to +n). Default adapts to be appropriate for location (e.g. +/- 38.3 m for PTI delay lines, +/- 15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Positive definite numeric argument required when used.
• --delayMin=: Specify minimum delay constraint (meters). Has no effect when --delayLimit is also used. Default adapts to be appropriate for location (e.g. -38.3 m for PTI delay lines, -15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Numeric argument required when used.
• --delayMax=: Specify maximum delay constraint (meters). Has no effect when --delayLimit is also used. Default adapts to be appropriate for location (e.g. +38.3 m for PTI delay lines, +15 m for KI delay lines). Defaults for each baseline are configured in source module interferometers.pm. Numeric argument required when used.
• --location=: Specify interferometer location. Default Palomar (from GC_DEFAULT_LOCATION runtime parameter). Supported locations (alphabetical order): CHARA, Flagstaff, KI, Keck, Lowell, MaunaKea, MtWilson, NPOI, PTI, Palomar, PalomarMtn, Paranal, VLTI. Exception thrown with an invalid location designation (and valid locations listed in error message). String argument required when used.
• --month=: Specify month for timing calculations (e.g. --month=7). Default current month. Integer argument required when used.
• --noEcho: Do not echo information contained in the input stream, only produce preamble and timing annotations. No argument when used.
• --noPreamble: Compute timings, but do not prepend the timing preamble (i.e. do not say what the timings are for). Default preamble on. No argument when used.
• --noPrecess: Do not apply precession effects to input (J2000) target astrometry to reference to the timing calculation epoch. Default off, no argument when used.
• --noTargets: Output timing preamble but do not compute target timings. Overrides --noPreamble and sets --baseline=none when selected. Default timing calculations on. Note that envVar.(c)sh defines an alias "tonight" (as timing –noTargets) to dump pertinent information about the night's observing conditions. No argument when used.
• --precess: Apply precession effects to input (J2000) target astrometry to reference to the timing calculation epoch. Default on, no argument when used.
• --replace: replace old timing annotations with new ones. No argument when used.
• --twilightAngle=: Specify twilight angle for sunset/sunrise calculations (degrees below horizon). Default is (the industry-standard nautical twilight value of) 12 degrees (from GC_TWILIGHT_ANGLE runtime parameter). Other common values are 18 (astronomical twilight), and 6 (civil twilight). Numeric argument required when used.
• --verbose: provide verbose running commentary on timing calculations. No argument when used.
• --year=: Specify year for timing calculations (e.g. --year=2000). Default is the current year. Integer argument required when used.
• --zenithAngle=/--za=: Specify maximum zenith angle constraint (degrees). Default 35 (from GC_ZENITH_ANGLE runtime parameter). Numeric argument required when used.
• --table Generates table of predicted delay position vs time for each object and baseline. The table is included in output as comment lines. Columns are hour angle (deg), time (UT), total delay (m), delay bias (m, see biasOffset), and FDL delay (m) (this is total delay remaining after adding any delay bias).
• --tableStep Specify time step size (seconds) to use when generating delay predict tables. See --table. Default delay table step size is 300.0 seconds.
• --nullDepth Generate a table of estimated null depth value vs time for each object and baseline. The table is included in output as comment lines. Columns are hour angle (deg), time (UT), projected baseline (m), and null depth. Time interval between output lines is controlled using the --NDstep option.
• --NDstep Specify time step size (seconds) to use when generating null depth tables. See --nullDepth. Default null depth table step size is 300.0 seconds.
• --NDwavelength=/--NDlambda=: Specify wavelength in microns to use for null depth estimate. Default 11.25 um (from GC_NULLDEPTH_WAVELENGTH runtime parameter). Numeric argument required when used.
• --trgAngDiam=: Specify target angular size in mas to use for null depth estimate. Target lines output from getCal do not automatically contain an angular diameter value. Timing will use this value for the angular diameter if no "DIAM=xxx" tag is found for the given source. Default 1.5 mas (from GC_NULLDEPTH_TRGDIAM runtime parameter). Numeric argument required when used.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

timing Defaults and Customization

Most default values in timing are controlled by configuration parameters (see Run-Time Configuration). Some of the parameters of particular relevance to timing are GC_DEFAULT_LOCATION, GC_DEFAULT_INTERFEROMETER, GC_DEFAULT_BASELINE, GC_DEFAULT_BIASOFFSET, GC_NULLDEPTH_WAVELENGTH, GC_NULLDEPTH_TRGDIAM, GC_TWILIGHT_ANGLE, GC_ZENITH_ANGLE.

Examples

As shown above, the canonical use case for timing is:

     timing [options] < list.in > list.out

1) A simple timing calculation (that replaces old timings) therefore goes something like:

     (gnomad:143) timing -replace < testCases/64p.list
     # Timing summary (timing v0.5dev) run at 12/22/2001 UTC, day 2001356
     #  for timings on 12/22/2001 UTC, day 2001356
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
     # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
     # The JD at 0 hr UT is 2452265.5
     # The LST at 0 hr UT is 22:15:01
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 01:42:39 -- 13:49:07 (12 deg twilight)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     # Using 38.3 m delay constraint
     ### GUI catalog ###
     # Resolving target 64 psc via SIMBAD
     # target HD  4676
     # HDC4676 00 48 58.708  +16 56 26.318  transits at 02:33:58 UT, zenAng 16.4 deg (1.04 am) target
     # HDC4676 is within zenith angle range from 00:16:11 to 04:51:44 UT
     # HDC4676 is within delay range from 22:39:01 to 10:44:22 UT for PTI_NS
     # HDC4676 is within delay range from 00:09:49 to 03:59:33 UT for PTI_NW
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7 F8V...  xxx   xxx  trg

Timings for an alternate day can be computed by (note we've used the filename on the command line – rather than pushing it in on stdin):

2) Alternate locations and baselines can be specified via:

     (gnomad:145) timing -replace -location MaunaKea -baseline KI_S1S2 < testCases/64p.list
     # Timing summary (timing v0.5dev) run at 12/22/2001 UTC, day 2001356
     #  for timings on 12/22/2001 UTC, day 2001356
     # Using MaunaKea Location (long: -155:28:24   lat: +19:49:36)
     # Using KI_S1S2 Baseline (ENUBias: 12.37 16.23 0.01 17)
     # The JD at 0 hr UT is 2452265.5
     # The LST at 0 hr UT is 19:40:35
     # The Local Time at 0 hr UT is 14:00:00
     # Approximate UT sunset -- sunrise times: 04:39:43 -- 16:00:55 (12 deg twilight)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     # Using 16.5 m delay constraint
     ### GUI catalog ###
     # Resolving target 64 psc via SIMBAD
     # target HD  4676
     # HDC4676 00 48 58.708  +16 56 26.318  transits at 05:08:24 UT, zenAng 2.9 deg (1.00 am) target
     # HDC4676 is within zenith angle range from 02:41:05 to 07:35:42 UT
     # HDC4676 is within delay range from 05:02:29 to 14:02:41 UT for KI_S1S2
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7 F8V...  xxx   xxx  trg

3) Different zenith angle, delay limit, and bias offsets are set by:

     (gnomad:146) timing -replace -location MaunaKea -baseline KI_S1S2 -zenith 45 -delay 19 -bias 12 < testCases/64p.list
     # Timing summary (timing v0.5dev) run at 12/22/2001 UTC, day 2001356
     #  for timings on 12/22/2001 UTC, day 2001356
     # Using MaunaKea Location (long: -155:28:24   lat: +19:49:36)
     # Using KI_S1S2 Baseline (ENUBias: 12.37 16.23 0.01 17)
     # The JD at 0 hr UT is 2452265.5
     # The LST at 0 hr UT is 19:40:35
     # The Local Time at 0 hr UT is 14:00:00
     # Approximate UT sunset -- sunrise times: 04:39:43 -- 16:00:55 (12 deg twilight)
     # Using 45 deg zenith angle (1.41 airmass) constraint
     # Using 19 m delay constraint with 12 m bias offset
     ### GUI catalog ###
     # Resolving target 64 psc via SIMBAD
     # target HD  4676
     # HDC4676 00 48 58.708  +16 56 26.318  transits at 05:08:24 UT, zenAng 2.9 deg (1.00 am) target
     # HDC4676 is within zenith angle range from 01:58:30 to 08:18:17 UT
     # HDC4676 is never within delay range for KI_S1S2
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7 F8V...  xxx   xxx  trg

As mentioned above, the --biasOffset option was added to provide support for interferometers with two-stage delay chains (e.g. NPOI, KI). To compute the delay limits for the fast delay lines (FDLs) moving around a particular long delay line (LDL) setting:

     timing -delayLimit FDLLimit -biasOffset LDLSetting < list > listAnnotated

Conversely, to compute the limits for the full LDL+FDL excursion range this invocation becomes:

     timing -delayLimit (FDLLimit+LDLLimit) < list > listAnnotated

4) This time setting twilight angle for sunset/sunrise:

     (gnomad:147) timing -replace -twilight 5 testCases/64p.list
     # Timing summary (timing v0.5dev) run at 12/22/2001 UTC, day 2001356
     #  for timings on 12/22/2001 UTC, day 2001356
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
     # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
     # The JD at 0 hr UT is 2452265.5
     # The LST at 0 hr UT is 22:15:01
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 01:06:22 -- 14:25:24 (5 deg twilight)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     # Using 38.3 m delay constraint
     ### GUI catalog ###
     # Resolving target 64 psc via SIMBAD
     # target HD  4676
     # HDC4676 00 48 58.708  +16 56 26.318  transits at 02:33:58 UT, zenAng 16.4 deg (1.04 am) target
     # HDC4676 is within zenith angle range from 00:16:11 to 04:51:44 UT
     # HDC4676 is within delay range from 22:39:01 to 10:44:22 UT for PTI_NS
     # HDC4676 is within delay range from 00:09:49 to 03:59:33 UT for PTI_NW
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7 F8V...  xxx   xxx  trg

5) Here's an example where I illustrate the no baseline/delay timing feature and the -filename command-line switch:

     (gnomad:17) timing -replace -base none -filename testCases/64p.list
     # Timing summary (timing v0.52dev) run at 1/4/2002 UTC, day 2002004
     #  for timings on 1/4/2002 UTC, day 2002004
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # The JD at 0 hr UT is 2452278.5
     # The LST at 0 hr UT is 23:06:17
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 01:50:44 -- 13:53:37 (12 deg twilight)
     # Approximate UT moonrise -- moonset times: 05:56:47 -- 19:00:57
     #   68% moon illumination -- 1.6 days before last quarter (moon transit 11 38 RA  +07 26 Dec)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     ### GUI catalog ###
     # Resolving target 64 psc via SIMBAD
     # target HD  4676
     # HDC4676 00 48 58.708  +16 56 26.318  transits at 01:42:25 UT, zenAng 16.4 deg (1.04 am) target
     # HDC4676 is within zenith angle range from 23:24:38 to 04:00:11 UT
     HDC4676 00 48 58.708 +16 56 26.318 -0.002 -0.202 5.1 3.7 F8V...  xxx   xxx  trg
     # HDC2454 00 28 20.052  +10 11 23.452  transits at 01:21:50 UT, zenAng 23.2 deg (1.09 am)
     # HDC2454 is within zenith angle range from 23:27:29 to 03:16:10 UT
     HDC2454 00 28 20.052 +10 11 23.452  0.033 -0.203 6.0 4.8 F6Vawvar 8.40892 0.36+/-0.1  cal
     # HDC3651 00 39 21.806  +21 15 01.701  transits at 01:32:50 UT, zenAng 12.1 deg (1.02 am)
     # HDC3651 is within zenith angle range from 23:03:55 to 04:01:44 UT
     HDC3651 00 39 21.806 +21 15 01.701 -0.495 -0.371 5.9 3.9 K0V 4.87127 0.72+/-0.0  cal

6) Here's a demo of the -noTargets option:

     (gnomad:57) timing -noTarg -noPre
     # Timing summary (timing v0.53dev) run at 2/17/2002 UTC, day 2002048
     #  for timings on 2/17/2002 UTC, day 2002048
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # The JD at 0 hr UT is 2452322.5
     # The LST at 0 hr UT is 01:59:45
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 02:27:31 -- 13:35:30 (12 deg twilight)
     # Approximate UT moonrise -- moonset times: 17:34:30 -- 05:44:36
     #   27% moon illumination -- 2.5 days before first quarter (moon transit 02 02 RA  +07 28 Dec)

timing is part of the getCal suite – a product of the NASA Exoplanet Science Institute, California Institute of Technology – http://nexsci.caltech.edu.

3.5 fbol

fbol – Bolometric Flux/Spectral Energy Distribution Modeling

• fbol Description
• Command-Line Options
• Input Format
• Theory

fbol Description

fbol is a spectral energy distribution (SED) modeling and angular diameter estimation tool (and part of the getCal suite); it is designed to estimate simple star apparent (angular) diameters by modeling their photometry with a Plank black-body SED parameterized by effective temperature and bolometric flux. The angular diameter (theta – units of radians) is simply related to effective temperature (T) and bolometric flux (Fbol) by:

Fbol = 1/4 theta^2 sigma T^4 = 1/4 pi theta^2 integral[B_lambda(T) d lambda]

with sigma being the Steffan-Boltzman constant. This relationship defines effective temperature, and is derived in the accompanying fbolSED.tex (see the doc directory in the getCal tarball).

The basic fbol invocation looks like:

     fbol [options] photometry.file [phot.file2 ...] [more options]

By default fbol reads input photometry/flux information from one or more photometry files (the format is discussed below), however photometry can also be read from stdin using a stdin switch:

     fbol --stdin [more options] < photometry.file

fbol output is written to stdout:

     fbol ~/photometry.51_Peg
     # Read 89 data lines from file: /home/bode/photometry.51_Peg
     #                                   ChiSqr        F_bol (10^-8       Ang
     #   Star               Teff(K)      /DOF   DOF     erg/cm2/s)     Size (mas)    Filters
      1 HD_217014--G2.5IVa  5705 +/- 36   0.54  85   19.14 +/- 0.189  0.74 +/- 0.11 .........

Errors quoted in the model parameters are mapped to a fit chi squared per degree of freedom of 1.

Errors quoted in the model parameters are FORMAL errors, and should NOT be taken as the actual errors (i.e. stars are only approximately black body radiators).

fbol can also output plots of the input photometric/flux data and resulting SED model using the third-party graphing package gnuplot (available on most systems, see http://www.gnuplot.info/). Plots are available in screen display, PostScript, and png formats (see more information in the options section below).

Command-line Options

Usage:

     	fbol [options]

where valid options include:

     	--blackwellCorrections --constrainTemp --eps --fixedErrors= --hardCopy
     	--plots --png --reddening --verbose

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --blackwellCorrections: compute estimated corrections for non-black-body effects in stellar atmospheres. This correction is estimated on the basis of B-V color, and derived from the dataset of Blackwell and Lynas-Gray 1994 (more to come).
• --constrainTemp: constrains the model effective temperature in the fit to the data. Effective temperature is constrained to the input value contained in the photometry data (i.e. by input lines) like:

            > T HD_217014--G2.5IVa  5808 # Model Effective Temp <= Spectral Type G2.5IVa)
       

  No argument when used.

• --eps: Encapsulated PostScript SED model plots. No argument when used.
• --fixedErrors=: apply a uniform fractional error to all input photometry (rather than using the input error estimates associated with each of the individual measurements). If used this switch takes an optional argument defining the fractional error to be used – the default value for this fractional error is 0.1 (i.e. 10%).
• --hardCopy/--hc/--ps: PostScript SED model plots. No argument when used.
• --plots/--screen: SED model plots using gnuplot and display them at the terminal.
• --png: Produce SED model plots in the PNG (portable network graphics) format.
• --reddening (--noReddening): apply (or not) reddening correction to the input photometry based on input distance (parallax) and a simple wavelength-parametric reddening model from Allen (3rd ed, p 264). No argument when used.
• --verbose: verbose description of the output from the program. No argument when used.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

Input Format

The photometry file format a is simple ASCII-based format:

     ### HD 19373 -- High proper-motion Star
     ### ICRS 2000: 03 09 04.0197 +49 36 47.799
     ### Spectral Type G0V
     T HD_19373--G0V  5930 # Model Effective Temp <= Spectral Type G0V
     ### V=4.05
     M HD_19373--G0V Johnson V 4.05 0.09  # Simbad V=4.05
     ### B-V=0.59
     C HD_19373--G0V B-V=0.59 ## Simbad B-V color index
     D HD_19373--G0V 10.534 0.074 ## Parallax 94.93 [.67] A [21]1997A&A...323L..49P
     M HD_19373--G0V Johnson V 4.04 0.05  # UBV Johnson V=4.04  1953ApJ...117..313J
     M HD_19373--G0V Johnson B 4.64 0.05  # UBV Johnson B=4.64  1953ApJ...117..313J
     M HD_19373--G0V Johnson U 4.74 0.05  # UBV Johnson U=4.74  1953ApJ...117..313J
     ## The format supports comments
     ## The format also support flux in Flambda or Fnu units
     Fl HD_19373--G0V 360 68  5.22e-07 2.3e-08  ## M HD_19373--G0V Johnson U 4.77 0.05  # UBV Johnson U=4.77  1966CoLPL...4...99J
     Fl HD_19373--G0V 555 89  8.83e-07 4e-08  ## M HD_19373--G0V Johnson V 4.07 0.05  # UBV Johnson V=4.07  1967AJ.....72.1334C
     Fl HD_19373--G0V 450 98  8.75e-07 3.9e-08  ## M HD_19373--G0V Johnson B 4.66 0.05  # UBV Johnson B=4.66  1967AJ.....72.1334C
     Fl HD_19373--G0V 360 68  5.07e-07 2.3e-08  ## M HD_19373--G0V Johnson U 4.8 0.05  # UBV Johnson U=4.8  1967AJ.....72.1334C
     Fl HD_19373--G0V 555 89  9e-07 4e-08  ## M HD_19373--G0V Johnson V 4.05 0.05  # UBV Johnson V=4.05  1952ApJ...116..251S
     Fl HD_19373--G0V 450 98  8.85e-07 4e-08  ## M HD_19373--G0V Johnson B 4.648 0.05  # UBV Johnson B=4.648  1952ApJ...116..251S
     ## Format supports different photometric systems (e.g. Johnson, Cousins,
     ##  Stromgren, Geneva, and 2Mass)
     M HD_19373--G0V Stromgren u 5.959 0.08  # Stromgren ubvy u=5.959  1998A&AS..129..431H
     M HD_19373--G0V Stromgren v 5.004 0.08  # Stromgren ubvy v=5.004  1998A&AS..129..431H
     M HD_19373--G0V Stromgren b 4.427 0.08  # Stromgren ubvy b=4.427  1998A&AS..129..431H
     M HD_19373--G0V Stromgren y 4.05 0.08  # Stromgren ubvy y=4.05  1998A&AS..129..431H
     #M HD_19373--G0V Stromgren u 5.956 0.08  # Stromgren ubvy u=5.956  1966AJ.....71..709C
     #M HD_19373--G0V Stromgren v 5.003 0.08  # Stromgren ubvy v=5.003  1966AJ.....71..709C
     #T HD_19373--G0V   5528 # model Effective Temp <= Stromgren photometry
     M HD_19373--G0V Johnson J 3.06 0.05  # JP11 Johnson J=3.06  1968ApJ...152..465J
     M HD_19373--G0V Johnson K 2.69 0.05  # JP11 Johnson K=2.69  1968ApJ...152..465J
     M HD_19373--G0V Johnson L 2.66 0.05  # JP11 Johnson L=2.66  1968ApJ...152..465J
     M HD_19373--G0V Johnson H 2.73 0.05  # JP11 Johnson H=2.73  1968ApJ...152..465J
     # 2Mass Search HD_19373:  K = 2.723 +/- 0.266  J = 3.143 +/- 0.246  H = 2.875 +/- 0.206
     M HD_19373--G0V 2Mass Ks 2.723 0.266  # 2Mass Ks=2.723 +/- 0.266
     M HD_19373--G0V 2Mass J 3.143 0.246  # 2Mass J=3.143 +/- 0.246
     M HD_19373--G0V 2Mass H 2.875 0.206  # 2Mass H=2.875 +/- 0.206

Available formats in this scheme are:

     M starID System Band Magnitude Error          <### Generic photometry format
     M StarID Lambda Bandpass Magnitude Error      <### (magnitudes in Johnson system assumed)
     F StarID Lambda Bandpass Flux Error           <### (Fluxes in Jy)
     Fn StarID Lambda Bandpass Flux Error          <### (Fluxes in Jy)
     Fl StarID Lambda Bandpass Flux Error          <### (Fluxes in erg s^-1 cm^-2 um^-1)
     C StarID B-V=color                            <### Star B-V color
     S StarID Filter Magnitude Error (Not yet implemented)
     Z Filter Lambda Bandpass Zeropoint (For specifying a new filter)
     D StarID Distance
     P StarID Parallax
     N Datafilename BlackbodyFilename (For specifying output filenames)

General notes on this format:

• wavelengths and bandpass are specified in nm
• fluxes are specified either in Jy (F, Fn – F_nu units) or erg s^-1 cm^-2 um^-1 (Fl – F_lambda units)
• zeropoints for magnitudes should be in Flambda units (erg s^-1 cm^-2 um^-1)
• distance is specified in pc
• parallax is specified in mas

For magnitude data in an unspecified system (Johnson assumed), the supported Johnson-system bands (wavelengths, pass-bands, and zeropoints) (in nm and erg s^-1 cm^-2 um^-1) are:

Filter	Lambda_0	Delta_lambda	Zero (F_lambda)	Zero (F_nu)
	(nm)	(nm)	(erg s^-1 cm^-2 um^-1)	(Jy)
U	360	68	4.27e-5	1829
B	445	98	6.61e-5	4144
V	555	89	3.64e-5	3544
R	668	210	1.74e-5	2950
I	879	240	9.12e-6	2280
J	1215	260	3.18e-6	1630
H	1654	290	1.15e-6	1050
K	2179	410	4.14e-7	655
L	3500	700	6.59e-8	276
M	4769	450	2.11e-8	160
N	10472	5190	9.63e-10	35.2
Q	20130	7800	7.18e-11	9.70

getCal uses the companion (perl) program fbolFormat to automatically create this photometry file format from Simbad (and other) database material. getCal now exposes this format to the user so they can see details of the bolometric flux calculations, and save (and modify) this data in future calculations. Note that starting in the v2.6 series, by default getCal produces all photometry records in the generic system/band specification. Further, fbol uses the companion script convertPhotometry to render disparate photometry data into consistent flux (Flambda or Fnu) units.

Theory

Estimating Stellar Angular Diameters With SED Modeling

As argued elsewhere, we are motivated to estimate star angular diameters. For instance, our own sun viewed from a typical solar neighborhood distance of 10 pc is less than 1 milliarcsecond (10^(-3) arcseconds, mas) in apparent diameter. Therefore, as an adjunct to both selecting and using calibration stars, it is a practical necessity to estimate stellar angular diameters from ancillary data. While several techniques exist for such estimates, the most broadly applicable and prevalent techniques are based on modeling the stellar photosphere as a blackbody, in which case the apparent diameter of the star reduces to a simple function the observed bolometric flux and the effective temperature (e.g.~see Blackwell94 and references therein). This section documents the algorithm fbol uses for angular diameter estimation.

First consider a unit area Plank blackbody at temperature T. The emittance (radiation emitted per unit surface – dimensions of energy per unit time) is:

where the last two expressions capture the spectral energy distribution of the blackbody radiation. Radiation from the unit surface is isotropic, so the specific intensity (radiation flux density per unit solid angle – dimensions of energy per unit time per unit solid angle) is a simple function of the projected area, so in a direction \bf \hat o this flux density is:

where \bf \hat n is the unit normal to the surface, and $\theta$ is the angle between \bf \hat n and \bf \hat o. Thus at a location D \, \bf \hat o from the unit emitter, the radiation flux per unit cross-sectional area (dimensions of energy per unit time per unit area) is:

Now consider the photosphere of a star as an isotropic sphere of radius R, the surface of which is taken to be a Plank blackbody radiator at uniform temperature T. For the observer at distance D the total radiation flux per unit cross-sectional area (the bolometric flux) can be computed as the integral of the contributions f_a \, dA over the hemisphere of the star visible to the observer:

Choosing the observer direction \bf \hat o as the reference axis in a spherical polar coordinate system allows us to identify the star surface area element dA as R^2 \sin \theta \, d \theta \, d \phi, making the evaluation of the integral straightforward:

with the identification of the star's angular diameter \Theta = 2 R / D, and introducing the stellar flux per unit wavelength F_\lambda. Solving Eq.~\ref(eq:Fbol) for \Theta yields the desired angular diameter estimator:

\approx 8.17 mas \times 10^(-0.2 * (V + BC)) \left[T / 5800 K \right]^(-2)

with V and BC as the star's (Johnson) visual magnitude and bolometric correction respectively. A couple of aspects of Eq.~eq:angDiameter are noteworthy. First, it is significant that no particular knowledge of the physical size of the star is necessary – the bolometric flux characterizes the solid angle of the star on the sky, and the blackbody temperature characterizes the emittance of the stellar surface. This emphasizes the intuitive notion that two stars of the same temperature but different physical radii R_1 and R_2 (e.g.~an M-dwarf and an M supergiant) will have the same apparent size and bolometric flux so long as R_1 / D_1 = R_2 / D_2. Secondly, in deriving Eq.eq:angDiameter it was sufficient that the photospheric emittance was taken as isotropic and characterizable by a ancillary parameter (temperature); no particular use is made of the blackbody SED model.

The operational issue in applying Eq.angDiameter to potential calibrators is determining the bolometric flux and effective temperature for the star. The most prevalent methods for this estimation is by modeling the observed spectral energy distribution (SED) of the star. This is illustrated in Fig.~fig:SEDmodel1 which depicts the modeling of the SED for 51 Pegasi (HD~217014) with a Plank blackbody form (specifically Eq.eq:Flambda) with free parameters \Theta and T_eff. In both cases the flux data for the stars is derived from archival optical and infrared photometry. In the first example (Fig.~fig:SEDmodel1) the 51~Peg SED is well-modeled by Eq.eq:Flambda with T \approx 5600 K and \Theta \approx 0.74 mas (despite the putative planetary-mass companion to 51 Peg; the implied temperature and physical size (R \sim 1.3 R_\odot from this diameter estimate and Hipparcos parallax) are in good agreement with the putative evolutionary state of the star.

Modeling of the spectral energy distributions for 51 Pegasi (HD 217014) with a single-temperature Plank blackbody photosphere model (Eq.eq:Flambda). The agreement between data and model is reasonably good.

3.6 fbolFormat

fbolFormat is a companion application to fbol that retrieves photometry (and optionally, radiometry) information for astronomical objects and produces formatted records for use by fbol (see fbol Input). Normally this happens behind the scenes in getCal without user intervention, but this short section introduces fbolFormat to the user if the need ever arises for manual processing.

Note: Unlike in past releases, fbolFormat now retrieves information from Simbad and other information sources directly instead of using records returned from another utility. In the past, fbolFormat read reports produced by another utility, simbadInteractiveQuery. This functionality is no longer supported.

For illustration, a manual fbolFormat invocation looks like:

     > fbolFormat iota_peg --longWL --strom --geneva --2Mass --fLambda | fbol --stdin
     
     # option stdin
     # 1 command line arguments processed
     #                                   ChiSqr        F_bol (10^-8       Ang
     #   Star               Teff(K)      /DOF   DOF     erg/cm2/s)     Size (mas)    Filters
       1 HD_210027--F5V   6320 +/-  57    6.13  86  83.52 +/- 4.8  1.25 +/- 0.42 ..........................................................................XX............

Command-Line Options

fbolFormat supports the following options:

     	--2Mass --CIO --fLambda --fNu --geneva --gezari --hipparcos/--tycho
     	--longWL --noB --noPlx --noU --noV --stromgren/--uvby

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --2Mass: Use IRSA 2Mass photometry on sources in fbol fitting. Default to off.
• --CIO/--gezari: Use photometry/radiometry from the Gezari a.k.a CIO catalog (Fifth Catalog of Infrared Observations, Gezari et al–see http://ircatalog.gsfc.nasa.gov/ ). Off by default.
• --fLambda: Produce photometry/radiometry reports in Flambda units (erg s^-1 cm^-2 um^-1)
• --fNu: Produce photometry/radiometry reports in Fnu units (Jy – 10^-26 W m^-2 Hz^-1)
• --geneva: Produce reports for Geneva photometry. Default to no.
• --hipparcos/--tycho: Produce reports for Hipparcos/Tycho photometry from the Hipparcos catalog. Default to no.
• --longWL: Produce reports for IRAS mid-infrared observations (retrieved from SIMBAD). Off by default.
• --noB: Exclude B-band photometry/radiometry
• --noPlx: Exclude distance estimate/parallax
• --noU: Exclude U-band photometry/radiometry
• --noV: Exclude V-band photometry/radiometry
• --stromgren/--uvby: Produce reports for Stromgren (uvby) photometry

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

3.7 convertPhotometry

convertPhotometry is a companion application to fbol to manipulate photometry data in fbol format (fbol Input). convertPhotometry converts disparate photometry and flux units into a consistent set of fluxes (either Flambda in erg s^-1 cm^-2 um^-1 or Fnu in Jy). fbol literally uses convertPhotometry to convert input on the fly, but convertPhotometry is also exposed to the getCal user for their convenience.

The basic convertPhotometry invocation looks like:

     convertPhotometry [options] photometry.file [phot.file2 ...] [more options] [> output]

or

     convertPhotometry [options] --stdin < input [> output]

As indicated in the above examples, convertPhotometry can read input from one or more files listed on the command line, or accept input from stdin (but not both). All convertPhotometry output comes out on stdout.

convertPhotometry is written to function both as a command-line user tool to manipulate photometry files, and as an in-line filter to convert photometry formats on the fly (this is exactly how fbol uses convertPhotometry).

Example

To illustrate, a common use of convertPhotometry is the conversion of photometry file:

     > convertPhotometry photometry.iota_per
     ### HD 19373 -- High proper-motion Star
     ### ICRS 2000: 03 09 04.0197 +49 36 47.799
     ### Spectral Type G0V
     T HD_19373--G0V  5930 # Model Effective Temp <= Spectral Type G0V
     ### V=4.05
     Fl HD_19373--G0V 555 89  9e-07 7.2e-08  ## M HD_19373--G0V Johnson V 4.05 0.09  # Simbad V=4.05
     ### B-V=0.59
     C HD_19373--G0V B-V=0.59 ## Simbad B-V color index
     D HD_19373--G0V 10.534 0.074 ## Parallax 94.93 [.67] A [21]1997A&A...323L..49P
     Fl HD_19373--G0V 555 89  9.08e-07 4.1e-08  ## M HD_19373--G0V Johnson V 4.04 0.05  # UBV Johnson V=4.04  1953ApJ...117..313J
     Fl HD_19373--G0V 450 98  8.92e-07 4e-08  ## M HD_19373--G0V Johnson B 4.64 0.05  # UBV Johnson B=4.64  1953ApJ...117..313J
     Fl HD_19373--G0V 360 68  5.36e-07 2.4e-08  ## M HD_19373--G0V Johnson U 4.74 0.05  # UBV Johnson U=4.74  1953ApJ...117..313J
     Fl HD_19373--G0V 555 89  9e-07 4e-08  ## M HD_19373--G0V Johnson V 4.05 0.05  # UBV Johnson V=4.05  1966CoLPL...4...99J
     Fl HD_19373--G0V 450 98  8.83e-07 4e-08  ## M HD_19373--G0V Johnson B 4.65 0.05  # UBV Johnson B=4.65  1966CoLPL...4...99J
     Fl HD_19373--G0V 360 68  5.22e-07 2.3e-08  ## M HD_19373--G0V Johnson U 4.77 0.05  # UBV Johnson U=4.77  1966CoLPL...4...99J
     Fl HD_19373--G0V 350 34  4.85e-07 3.4e-08  ## M HD_19373--G0V Stromgren u 5.959 0.08  # Stromgren ubvy u=5.959  1998A&AS..129..431H
     Fl HD_19373--G0V 411 20  8.63e-07 6.1e-08  ## M HD_19373--G0V Stromgren v 5.004 0.08  # Stromgren ubvy v=5.004  1998A&AS..129..431H
     Fl HD_19373--G0V 467 16  9.98e-07 7.1e-08  ## M HD_19373--G0V Stromgren b 4.427 0.08  # Stromgren ubvy b=4.427  1998A&AS..129..431H
     Fl HD_19373--G0V 547 24  8.95e-07 6.4e-08  ## M HD_19373--G0V Stromgren y 4.05 0.08  # Stromgren ubvy y=4.05  1998A&AS..129..431H
     # 2Mass Search HD_19373:  K = 2.723 +/- 0.266  J = 3.143 +/- 0.246  H = 2.875 +/- 0.206
     Fl HD_19373--G0V 2159 262  3.49e-08 7.6e-09  ## M HD_19373--G0V 2Mass Ks 2.723 0.266  # 2Mass Ks=2.723 +/- 0.266
     Fl HD_19373--G0V 1235 162  1.74e-07 3.5e-08  ## M HD_19373--G0V 2Mass J 3.143 0.246  # 2Mass J=3.143 +/- 0.246
     Fl HD_19373--G0V 1662 251  7.86e-08 1.4e-08  ## M HD_19373--G0V 2Mass H 2.875 0.206  # 2Mass H=2.875 +/- 0.206

As you can see, the converted flux lines have the original input lines appended to them to provide data traceability. convertPhotometry passes lines it doesn't recognize (i.e. non-photometry or flux lines) without modification.

Command-Line Options

convertPhotometry supports the following command-line options:

• --fLambda: set convertPhotometry output to be in Flambda units (erg s^-1 cm^-2 um^-1) (default).
• --fNu: set convertPhotometry output to be in Fnu units (Jy).

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

3.8 obsCalendar

obsCalendar – perl program to compute target annual accessibility.

• obsCalendar Description
• Command-Line Options

obsCalendar Description

obsCalendar is a Perl program that ingests one or more astronomical target specifications (designation + RA/Dec), and computes annual accessibility information (i.e. when the target is available in the sky for viewing). This accessibility information is (by default) inserted into the input stream on output in the form of pound (hash – #) delimited annotations, and input to and output from obsCalendar is done through the stdin and stdout channels. Using command-line arguments the user can specify year for the calculations, geometric criteria (zenith angle), location (e.g. Palomar), and various other output options. The user interface and option set for obsCalendar in general mimics its older sibling timing.

The canonical use case is that the user has some list of astronomical targets (objects), and obsCalendar is used as a conduit to add accessibility constraint information to that list (as in):

     obsCalendar [options] < list.in > list.out

or

     obsCalendar [options] --stdin < list.in > list.out

(one of the recognized is stdin – see command-line options below). Note that to use the first form the user cannot enter ANY options not recognized by obsCalendar (i.e. ARGV must be empty after processing through getOpt).

Alternatively, obsCalendar can also accept a filename as an argument:

     obsCalendar [options] --filename=list.in

or

     obsCalendar [options] --filename=list.in --filename=list2.in --filename=list3.in > list.out

Note that in the last form the user cannot enter ANY options not recognized by obsCalendar (i.e. @ARGV must contain only desired files after processing through getOpt). Object lists from multiple input files are concatenated in their order of appearance on the output stream.

As implied, in any form obsCalendar's output is written to stdout.

The coordinate format is a standard ASCII obj, ra, dec + ancillary data format common in astronomical applications. For example, at PTI (where obsCalendar was developed) this format looks like:

     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

obsCalendar is interested in the positional information and target/calibrator role only, and (except as indicated in the option settings) only adds to the input stream, so the format of the remainder of the line is arbitrary from the obsCalendar perspective. The target/calibrator role information must be found somewhere in the line as the strings "trg", "cal", "ROLE=TRG" or "ROLE=CAL".

The obsCalendar constraint information is added in the form of comment information (indicated by a #-sign) prefacing each valid target line detected in the input stream:

     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     # HDC234677 18 33 55.773  +51 43 08.905  is near transit at sunrise on 4/23/2002 (2002113) target
     # HDC234677 is near transit at midnight on 6/26/2002 (2002177)
     # HDC234677 is near transit at sunset on 9/14/2002 (2002257)
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

The accessibility calculations default to the dates of transit for local sunrise, midnight, and sunset. These are serviceable definitions, but they are rather restricted in their scope. So obsCalendar also accepts an -hourAngle command-line argument that allows the user to add additional computation of offsets from transit that expand the accessible range:

     (gnomad:24) obsCalendar --hourAngle=2 tmp
     # Observing calendar (obsCalendar v0.1dev) run at 2/23/2002 UTC, day 2002054
     #  for timings in 2002 UTC
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     # HDC234677 18 33 55.773  +51 43 08.905  is near transit at sunrise on 4/25/2002 (2002115) target
     # HDC234677 is 2 hours pre-transit at sunrise on 3/10/2002 (2002069)
     # HDC234677 is near transit at midnight on 6/26/2002 (2002177)
     # HDC234677 is near transit at sunset on 9/14/2002 (2002257)
     # HDC234677 is 2 hours post-transit at sunset on 10/28/2002 (2002301)
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

Like timing, obsCalendar provides a (currently minimal) preamble that provides context...:

     # Observing calendar (obsCalendar v0.1dev) run at 2/18/2002 UTC, day 2002049
     #  for timings in 2002 UTC
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)

obsCalendar's output is designed to be human readable, but the ocGui graphical user interface (GUI) application also reads that format and creates (hopefully) informative line graph renderings of the obsCalendar output – see the ocGui and uvTool documentation for details.

timing and obsCalendar come with an ancillary utility stripTiming that _removes_ the annotations added by timing and obsCalendar. (stripTiming is actually just a tedious grep call.) The use case here is that you want to remove (and possibly replace) timing and/or obsCalendar annotations previously inserted in a list:

     stripTiming < list.in [| timing [options] ] > list.out

or more straightforwardly, obsCalendar will pass the input through stripTiming for you using the -replace argument:

     obsCalendar --replace [options] < in > out

Like obsCalendar, stripTiming takes its input on stdin and produces its output on stdout.

Command-Line Options

obsCalendar supports the following command-line options:

     	--hourAngle= --location= --noEcho --noPreamble --replace
     	--twilightAngle= --year=

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --hourAngle=: Specify hourAngle offset for additional accessibility calculations – i.e. hours pre-transit at sunrise and hours past transit at sunset. Default off. Units are in hours, numerical argument required when used.
• --location=: Specify observation location; default=Palomar. You will probably prefer to set this parameter through the GC_DEFAULT_LOCATION runtime parameter. Supported locations (alphabetical order): CHARA, Flagstaff, KI, Keck, Lowell, MaunaKea, MtWilson, NPOI, PTI, Palomar, PalomarMtn, Paranal, VLTI; exception thrown with an invalid location designation (and valid locations listed in error message). String argument required when used.
• --noEcho: Do not echo information contained in the input stream, only produce preamble and timing annotations. No argument when used.
• --noPreamble: Do not write a descriptive header into the output.
• --replace: Replace old timing annotations with new ones. No argument when used.
• --twilightAngle=: Specify twilight angle for sunset/sunrise calculations (deg). Default is (the industry-standard nautical twilight value of) 12 degrees. Other common values are 18 (astronomical twilight), and 6 (civil twilight). Numerical argument required when used.
• --year=: Specify year for calculations (e.g. --year=2000). Defaults to current year. Integer argument required when used.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

3.9 xeConvert

xeConvert – conversion to XEphem catalog format

xeConvert is a small utility that converts a getCal-composed catalog file for use with the excellent third-party sky visualization package XEphem.

As mentioned above, xeConvert is a small utility that transforms the native getCal output format into the input catalog format for the popular XEphem sky visualization package. A typical use case for xeConvert is:

     xeConvert < my.schedule.file > my.XEphem.catalog.file

or perhaps using the XEphem input fifo mechanism (see the fifo discussion below):

     xeConvert < my.schedule.file > $HOME/XEphem/fifos/xephem_db_fifo

Several of the getCal components (gcGui, tGui, ocGui, uvTool) use xeConvert to convert native schedule formats into XEphem catalogs for sky visualization.

Working with XEphem

Completely unsolicited and free of charge, I'm including my tips for working with getCal and XEphem.

XEphem Setup

• First you have to get XEphem. I use the source tarball (rather than say from an RPM), mostly because of the next item...but this has the downside that you'll need to have a MOTIF package available (please see the XEphem documentation).
• Build and install XEphem according to directions. For what it's worth at this point I usually hack the XEphem source to handle longer object type (spectral types) codes than the nominal 2 characters that XEphem uses by default. This modification is to circum.h in libastro, and I modify the declaration of the fo_spect field in the ObjF typedef (line 126) to be char [10], as in:

            char  fo_spect[10]; /* spectral codes, if appropriate -- mod A.B. */
       

  This way the XEphem spectral codes can carry along astrophysical information – object luminosity class information at a minimum, and other ancillary information as is common. This is clearly more of an issue for the professional astronomer user of XEphem than the casual user.

• Create fifos if desired. XEphem uses FIFO (named pipe – see “man fifo”) for real-time input and output. If you'd like getCal components to interact directly with the running XEphem application, you're going to need to create these fifos.

  Forgive me, I'm ignorant of the contents/MO of the RPMs, but in the source distribution there's a directory xephem-xxx/GUI/xephem/fifos which contains the Makefile for these fifos that XEphem uses. In that directory you simply type 'make' and magic happens.

• Create yourself a $HOME/XEphem directory if desired. XEphem looks (among other places) in that directory for the XEphem resource file, XEphem. This resource file is used to control the startup behavior of XEphem.

  I also find it expedient to setup a symbolic link from $HOME/XEphem/fifos to the XEphem fifo subdirectory in the build tree, but this is just personal preference.

• Define the getCal XEphem fifo environment variable GC_XEPHEM_FIFO to point to the appropriate db fifo created in the step above. See Run-Time Configuration.

Running with XEphem

If you're just going to be writing XEphem catalogs to disk with getCal components, then there are no strong dependencies between the two packages – you can arbitrarily create XEphem catalogs without regard to the run state of XEphem, and then use these catalogs at your leisure.

However, if you plan to use the XEphem fifo mechanism for communication, then XEphem should be up and accepting data from this fifo. With the 2.6 release I have now figured out how to write to the fifo in a non-blocking way (so there are no more wedges – yea!!), but if XEphem isn't up and catching the getCal output the catalogs you write will be lost (the fifo mechanism doesn't buffer this output).

3.10 gcConf

The gcConf describes in detail the run-time configuration of your getCal installation. This includes the search paths for executables and Perl modules, plus the values of run-time parameters set through the getCal configuration file (e.g., $(installation prefix)/etc/getCal.conf) and/or environment variables.

If you observe odd or unexpected behavior from getCal after attempting to change the run-time configuration, it may be worth your while to run gcConf. Hopefully, this transparency (making getCal “show its work”) will quickly allow you to locate and fix any configuration-related glitches.

Sample output from gcConf:

     
     % ~/dev/bin/gcConf
     ############################################
     Current configuration information for getCal
     ############################################
     
     getCal version                            getCal-v2.10.4, build 20071029
     
     Current bin directory                     /Users/sgroom/dev/bin
     Default location of getCal Perl modules   /Users/sgroom/dev/bin/../lib/modules
     
     Current configuration file                /Users/sgroom/dev/etc/getCal.conf
     Configuration file location can be overridden by setting the GC_CONFIG
     environment variable. Run-time parameters in the configuration file
     can be overridden using environment variables.
     
     Build-time configuration:
     Build directory                           /Users/sgroom/work/getCal
     Installation prefix                       /Users/sgroom/dev
     Installation bin directory                /Users/sgroom/dev/bin
     
     Search path(s) for Perl modules (from environment variable PERL5LIB):
             /Users/sgroom/local/perl/lib
     
     Search path(s) for Perl modules (from the site configuration):
             .
             /Library/Perl
             /Library/Perl/5.8.1
             /Library/Perl/5.8.6
             /Library/Perl/5.8.6/darwin-thread-multi-2level
             /Network/Library/Perl
             /Network/Library/Perl/5.8.6
             /Network/Library/Perl/5.8.6/darwin-thread-multi-2level
             /System/Library/Perl/5.8.6
             /System/Library/Perl/5.8.6/darwin-thread-multi-2level
             /System/Library/Perl/Extras/5.8.6
             /System/Library/Perl/Extras/5.8.6/darwin-thread-multi-2level
             /Users/sgroom/dev/bin/../lib/modules
             /Users/sgroom/local/perl/lib/darwin-thread-multi-2level
     
     
     Parameters in effect:
     getCal version                           2.10.4 [build-time configure script]
     getCal build ID                          20071029 [build-time configure script]
     build root directory                     /Users/sgroom/work/getCal [build-time configure script]
     installed bin directory                  /Users/sgroom/dev/bin [build-time configure script]
     sort utility                             /usr/bin/sort [build-time configure script]
     grep utility                             /usr/bin/grep [build-time configure script]
     egrep utility                            grep -E [build-time configure script]
     getCal data path                         /Users/sgroom/dev/data/getCal [build-time configure script]
     getCal doc path                          /Users/sgroom/dev/doc/getCal [build-time configure script]
     gnuplot utility                          /Users/sgroom/local/bin/gnuplot [build-time configure script]
     Perl interpreter                         /usr/bin/perl [build-time configure script]
     pstopnm utility                          /sw/bin/pstopnm [build-time configure script]
     pnmflip utility                          /sw/bin/pnmflip [build-time configure script]
     ppmtogif utility                         /sw/bin/ppmtogif [build-time configure script]
     ppmtojpeg utility                        /sw/bin/ppmtojpeg [build-time configure script]
     pnmtopng utility                         /sw/bin/pnmtopng [build-time configure script]
     ps2pdf utility                           /sw/bin/ps2pdf [build-time configure script]
     GC_CONFIG                                /Users/sgroom/dev/etc/getCal.conf [build-time configure script]
     GC_BROWSER                               open /Applications/Safari.app [environment variable GC_BROWSER]
     GC_CAL_MAXK                              5.0 [config file]
     GC_CAL_MAXL                              undefined
     GC_CAL_MAXN                              undefined
     GC_CAL_MAXV                              7.5 [config file]
     GC_CAL_MINK                              2.0 [config file]
     GC_CAL_MINL                              undefined
     GC_CAL_MINN                              undefined
     GC_CAL_MINV                              2.0 [config file]
     GC_CAL_SEARCHRADIUS                      10.0 [config file]
     GC_CIO_CATALOG_PATH                      /Users/sgroom/dev/data/catalogs/CIO5.1/ciov5.1 [config file]
     GC_DEBUG                                 0 [config file]
     GC_DEFAULT_BASELINE                      all [config file]
     GC_DEFAULT_BIASOFFSET                    0 [hard-coded default]
     GC_DEFAULT_FORMAT                        new [config file]
     GC_DEFAULT_INTERFEROMETER                PTI [config file]
     GC_DEFAULT_LOCATION                      Palomar [config file]
     GC_DEFAULT_TIMEOFFSET                    00:00 [config file]
     GC_FIRSTPASS_K                           0.5 [hard-coded default]
     GC_FIRSTPASS_N                           0.5 [hard-coded default]
     GC_HIPPARCOS_PATH                        /Users/sgroom/dev/data/catalogs/hipparcos [config file]
     Hipparcos catalog file                   /Users/sgroom/dev/data/catalogs/hipparcos/hip_main.dat [under Hipparcos Path]
     GC_HIPPARCOS_IDX_PATH                    /Users/sgroom/dev/data/getCal [config file]
     GC_HTTP_TIMEOUT                          30 [config file]
     GC_IRAS_SEARCHRADIUS                     10 [hard-coded default]
     GC_IDENT_HDC                             1 [config file]
     GC_IRSA_HOST                             irsa.ipac.caltech.edu [config file]
     GC_NULLDEPTH_TRGDIAM                     1.5 [hard-coded default]
     GC_NULLDEPTH_WAVELENGTH                  11.25 [hard-coded default]
     GC_SIG_FIGURES                           3 [hard-coded default]
     GC_SIMBAD_CACHEDIR                        [hard-coded default]
     GC_SIMBAD_CACHEONLY                      0 [hard-coded default]
     GC_SIMBAD_HOST                           simbad.harvard.edu [config file]
     GC_TOLERANCE_K                           0.4 [hard-coded default]
     GC_TOLERANCE_N                           0.4 [hard-coded default]
     GC_TWILIGHT_ANGLE                        12 [hard-coded default]
     GC_2MASS_SEARCHRADIUS                    3 [hard-coded default]
     GC_XEPHEM_FIFO                            [config file]
     GC_ZENITH_ANGLE                          35 [hard-coded default]
     HTTP_PROXY                               http://localhost:8080 [environment variable HTTP_PROXY]
     

3.11 simbadInteractiveQuery

simbadInteractiveQuery – Query the Simbad database by HTTP

• Description
• Command-Line Options
• Search Target Input
• Implementation
• Runtime Configuration

Description

simbadInteractiveQuery (simbadInteractiveQuery) is a perl program (and part of the getCal suite) that interfaces with the Simbad astronomical database to resolve astronomical designations and retrieve data on one or more astronomical objects (herein search targets). Optionally, simbadInteractiveQuery can return specific designation, astrometric, or measurement information, and submit the query in the context of an external user-interactive web browser application. Most of the simbadInteractiveQuery interface semantics and functionality is designed to be a general service for getCal components, but the executable is exposed to the user as part of the getCal install, and is accessible (and maybe even useful) from the command-line.

Simbad (and its US mirror at SAO-CfA) is an astronomical database that provides basic data, cross-identifications and bibliography for astronomical objects outside the solar system.

The basic simbadInteractiveQuery invocation looks like:

     simbadInteractiveQuery [options] search_target [search_target2...] [more options]

By default simbadInteractiveQuery retrieves the search targets from the command line, but it can optionally read from stdin or multiple filenames as in:

     simbadInteractiveQuery --stdin < my.list

and

     simbadInteractiveQuery --filename=my.list [--filename=my.list2 ...]

By default simbadInteractiveQuery output is written to stdout, but with the -browser option simbadInteractiveQuery can issue the query in the context of one or more external browser instances:

     simbadInteractiveQuery target [target2...] [--list] --browser [browser_executable]

Other than for external browser-based queries, simbadInteractiveQuery produces basic information on the target(s) on stdin, as in:

     simbadInteractiveQuery iota_Peg
     # Simbad Search iota_Peg: HD 210027 -- Spectroscopic binary  F5V V=3.76
     
     simbadInteractiveQuery IM_Peg -SAO
     # Simbad Search IM_Peg: HD 216489 -- Variable of RS CVn type  K1.5II-IIIe V=5.892
     SAO 108231
     
     simbadInteractiveQuery DG_Tau -coord
     # Simbad Search DG_Tau: V* DG Tau -- T Tau-type Star  GV:e...
     coord 04 27 04.76 +26 06 16.9 D
     
     
     (gnomad:23) simbadInteractiveQuery -all NGC_1068
     # Simbad Search NGC_1068: APG 37 -- Interacting Galaxies  S...
     
                                                                                                                   [1]Jump to the CDS home page
     SIMBAD Query Result
     ...
     
        Object query :
        search NGC 1068
          _________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________
     
     ...
     
         Basic data : APG 37 -- Interacting Galaxies Query around with radius ____ arc min.
     
                                 ICRS 2000.0 coordinates
         02 42 40.83 -00 00 48.4 D [18]1999ApJS..125..409C
                               FK5 2000/2000 coordinates
         02 42 40.83 -00 00 48.4
                               FK4 1950/1950 coordinates
         02 40 07.17 -00 13 32.3
                                       Galaxy dimensions
         1.88 0.05 70 (~)
                           B magn, V magn, Peculiarities 8.91,
                                           Spectral type
         S...
                Radial velocity (v:Km/s) or Redshift (z)
         z +.003786 [ .000033] D [19]2002LEDA..........P
     
     ...

Command-Line Options

Usage:

     	simbadInteractiveQuery [options] target

where valid options include:

     	--allData/--meas --browser --commonNames --coord --FK5 --HD= --HIP=
     	--SAO --html --identifiers/--pseudonyms --Kmag --lineWidth= --list --url

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --allData: directs simbadInteractiveQuery to dump all results returned by Simbad. No argument when used.
• --browser [browser_executable]: directs simbadInteractiveQuery to refer the composed queries (URLs) to an external browser. This option takes an optional argument for the browser executable (e.g. /usr/bin/mozilla) – if no argument is given the runtime parameter GC_BROWSER is used for the browser executable. As it takes this optional argument, this option cannot be arbitrarily interspersed with other options when used without argument, but must precede another option or be placed at the end of the line in order for the command-line parsing to function properly, as in

            simbadInteractiveQuery --browser --list iota_Peg 51_Peg
            simbadInteractiveQuery NGC_1068 --browser
       

• --commonNames: directs simbadInteractiveQuery to extract and report common names (e.g. alpha And, Sirrah) on the result summary line. No argument when used.
• --coord: directs simbadInteractiveQuery to extract and report on (ICRS 2000) astrometry for search targets. No argument when used.
• --FK5, --HD, --HIP, --SAO: directs simbadInteractiveQuery to extract and report on specific popular catalog designations. No argument when used.
• --html: Used with --allData, this option makes simbadInteractiveQuery dump the report in HTML rather than plain text.
• --identifiers|--pseudonyms: directs simbadInteractiveQuery to extract and report on all designations for search targets. No argument when used.
• --Kmag: directs simbadInteractiveQuery to estimate K for search targets based on Simbad V and model V-K (based on Simbad spectral type). No argument when used.
• --lineWidth= arg: directs simbadInteractiveQuery to format the result return lines to width argument. Only useful in conjunction with the allData option, integer argument required when used.
• --list: when using the browser option (above), produces a (generally more useful) list query, returning a selectable list of identifiers. No argument when used, ignored if the browser option not selected. Netscape users please note – the list option is especially important for your use, as netscape is challenged with respect to opening multiple windows.
• --url: When this option is included, simbadInteractiveQuery generates and prints the URL for querying Simbad based on your search criteria, but does not execute that query.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

Search Target Input

simbadInteractiveQuery is (of course) just a Simbad robot. It works (primarily) by routing Simbad search targets to Simbad without interpretation. If (when) you get the pervasive error message:

     simbadInteractiveQuery DGTau
        This identifier is not present in the database: NAME DGTAU

Please consult the designation dictionary at Simbad (http://vizier.u-strasbg.fr/cgi-bin/Dic-Simbad) for clarification on Simbad designation standards.

As indicated above, this version of simbadInteractiveQuery can accept search targets by three method: on stdin, via one or more files, or as direct command-line arguments. These three input methods are mutually exclusive.

Search target input on stdin is assumed by simbadInteractiveQuery if there are no remaining command-line arguments after option processing, or if specifically directed by the –stdin command-line argument (see below). Input on stdin follows the general principles outlined in the file format discussed in the following paragraph.

Search target input via files is invoked by one or more instances of the --filename= option on the command line (see below). The required format of the file is individual search targets listed one per line. Blank lines and #-prefaced comments are acceptable. An example illustrating most of the aspects of the file format is:

     ## Sample simbadInteractiveQuery input file format
     
     ## Previous line left intentionally blank
     Omi Cet
     iota Peg  ## The universe's most important spectroscopic binary
     DG Tau    ## A boring low-mass YSO
     NGC_1068  ## I'm Shapley -- I don't believe in extragalactic objects
     ## EOF

If not using stdin or files, search target input via the command-line is the last alternative. Here you can input one or more search targets on the command-line, interspersed with command options:

     simbadInteractiveQuery --commonNames Omi_Cet --list iota_peg DG_Tau --HD NGC_1068 --browser

Unique to the command-line input method, underscores are required to join multiple words in a target designation (iota_peg, 64_Psc, 75_Cnc, 12_Boo). (These are optional but acceptable in the stdin and filename input methods.)

Implementation

simbadInteractiveQuery is based on the Astro::SIMBAD Perl module, version 2.0.0 or higher. It is an “all-Perl” implementation: Unlike simbadInteractiveQuery from previous getCal releases, it does not require Lynx or any other non-Perl utilities.

Runtime Configuration

simbadInteractiveQuery uses these parameters from the getCal set:

• GC_SIMBAD_HOST
• GC_BROWSER
• GC_HTTP_TIMEOUT
• HTTP_PROXY

See Run-Time Configuration for an explanation of these values.

3.12 irsaminer

irsaminer queries the IRSA catalog and prints the results in tabular form on standard output. It is essentially a command-line interface for a subset of the IRSA services offered through the OASIS Web page at http://irsa.ipac.caltech.edu/applications/Oasis/svc/index.html.

irsaminer replaces the earlier tools 2MassQuery and IRASQuery. Although those tools still remain in the getCal package, their capabilities are very limited in comparision to irsaminer's. Furthermore, 2MassQuery and IRASQuery have been redesigned so that they function as front-end interfaces to irsaminer. For all new uses, we recommend using irsaminer rather than these older tools.

By design, irsaminer.pl does not depend on any other components within the getCal suite. Thus, it can be separated from the rest of getCal and run by itself, provided that the host's Perl environment contains the necessary modules. Please be aware, though, that irsaminer is a wrapper shell script for irsaminer.pl, and irsaminer is part of getCal.

irsaminer is rather terse in its responses. This reduces its user-friendliness, but makes for an output that is easily parsed. For human-interactive use, you may find it easier simply to use the Web page through a browser. However, when scripting a task, irsaminer (or its counterpart, gcIrsa.pm, also part of getCal) should be more useful.

Usage

             irsaminer --catlist [ --delim= --server= --titles ]
             irsaminer --ddlist --dd= [ --delim= --server= --titles ]
             irsaminer --catalog= | --dd= [ --cols= --where= --within= --objstr= ]

• --catalog specifies the catalog to be queried. Note that most IRSA catalog names are unique, but a couple are not. It is a bit safer to use --dd.
• --catlist prints a list of IRSA catalogs
• --cols is a comma-separated list of column names (the default is to print all columns)
• --dd specifies a data dictionary. Data dictionary names in IRSA are unique.
• --ddlist prints the contents of a data dictionary (e.g., operation@rmt_boulder:irasfscr_dd)
• --delim sets the field delimiter; default is |
• --objstr names a reference body for spatial searches
• --server specifies the IRSA web server; default is irsa.ipac.caltech.edu
• --titles turns on the printing of column titles
• --url restricts output to the query URL
• --verbose (or -v) turns on verbose output. Using -vv makes it very verbose.
• --where supplies an SQL 'where' clause for the query.
• --within supplies a spatial parameter (e.g., '2 degrees') for searching around a target (indicated by --objstr)

Modes of Operation

irsaminer has three modes, corresponding to the following OASIS services:

• Catalog Holdings List
• Catalog Data Dictionary
• Catalog Search

Catalog Holdings List

Usage:

     irsaminer --catlist [ --delim= --server= --titles ]

Example:

     $ irsaminer --catlist --titles
     
     archive|server|database|catname|ddname|desc
     IRSA|@rmt_stone|fp_2mass|fp_psc|operation@rmt_boulder:fp_psc_dd|2MASS All-Sky Point Source Catalog (PSC)
     IRSA|@rmt_stone|fp_2mass|fp_xsc|operation@rmt_boulder:fp_xsc_dd|2MASS All-Sky Extended Source Catalog (XSC)
     IRSA|@rmt_boulder|public|lga_v2|operation@rmt_boulder:lga_v2_dd|The 2MASS LargeGalaxy Atlas
     ...

The --catlist mode option directs irsaminer to print a list of IRSA catalogs.

--delim sets the character to be used as a field delimiter, by default the pipe (|) character. --server names the IRSA web server, nominally irsa.ipac.caltech.edu. --titles toggles the printing of column titles (off by default).

Catalog Data Dictionary

A data dictionary query provides you with the fields contained inside a particular catalog:

Usage:

     irsaminer --ddlist --dd= [ --delim= --server= --titles ]

Example:

     $ irsaminer --ddlist --dd=operation@rmt_boulder:fp_psc_dd --titles
     archive|dd|colname|dbtype|format|nulls|units|desc
     IRSA|operation@rmt_boulder:fp_psc_dd|ra|decimal(9,6)|10.6f|n|deg|right ascension (J2000 decimal deg)
     IRSA|operation@rmt_boulder:fp_psc_dd|dec|decimal(8,6)|10.6f|n|deg|declination (J2000 decimal deg)
     IRSA|operation@rmt_boulder:fp_psc_dd|err_maj|decimal(3,2)|4.2f|n|arcsec|major axis of 1-sigma error ellipse
     IRSA|operation@rmt_boulder:fp_psc_dd|err_min|decimal(3,2)|4.2f|n|arcsec|minor axis of 1-sigma error ellipse
     IRSA|operation@rmt_boulder:fp_psc_dd|err_ang|smallint|3hd|n|deg|angle of error ellipse major axis (E of N)
     IRSA|operation@rmt_boulder:fp_psc_dd|designation|char(17)|17s|n||source designation formed from sexigesimal coordinates
     IRSA|operation@rmt_boulder:fp_psc_dd|j_m|decimal(5,3)|6.3f|y|mag|J band selected "default" magnitude
     ...

Catalog Search

The catalog search mode allows you to extract rows of data from a catalog.

Usage:

     --catalog= | --dd= [ --cols= --where= --within= --objstr= ]

Example:

     $ irsaminer --catalog=fp_psc --cols=designation,ra,dec --objstr="51 peg" --within="2 arcmin"
     22572727+2044358|344.363650|20.743284|
     22573111+2045128|344.379659|20.753574|
     22573120+2045316|344.380032|20.758804|
     22572647+2044157|344.360328|20.737703|
     22573209+2045206|344.383737|20.755726|
     22572936+2046008|344.372363|20.766909|
     22572233+2046372|344.343057|20.777025|
     22573011+2044280|344.375485|20.741117|
     22572795+2046077|344.366498|20.768818|

When specifying a catalog to search, you can supply either the catalog name or the name of a data dictionary. This is useful because a handful of catalog names are not unique; however, all data dictionary names are unique. Generally, --catalog= will work; if the name is not unique, irsaminer will return an error message rather than querying a potentially wrong catalog.

Although the Web page requires a few more parameters than just the name of the catalog or data dictionary, irsaminer looks those up so as to require the minimal amount of data needed to perform the lookup.

3.13 2MassQuery

2MassQuery – Query the 2MASS point-source catalog by HTTP

• 2MassQuery Description
• Command-Line Options
• Search Target Input
• Implementation

Description

2MassQuery is a Perl program (part of the getCal suite) that interfaces with the 2MASS point-source catalog to query that catalog for 2MASS photometry on one or more astronomical objects (herein search targets) or position search targets. (See 2MASS description at http://www.ipac.caltech.edu/2mass, and a description of the catalog at http://www.ipac.caltech.edu/2mass/releases/allsky.)

2MassQuery is primarily designed to retrieve 2MASS photometry, but optionally 2MassQuery can also return astrometric information, and submit the query in the context of an external user-interactive web browser application. Most of the 2MassQuery interface semantics and functionality is designed to be a general service for getCal components, but the executable is exposed to the user as part of the getCal install, and is accessible (and maybe even useful) from the command-line.

2MassQuery uses services from the InfraRed Science Archive (IRSA) at the Infrared Processing and Analysis Center (IPAC).

The basic 2MassQuery invocation looks like:

     2MassQuery [options] search_target [search_target2...] [more options]

By default 2MassQuery retrieves the search targets from the command line, but it can optionally read from stdin or multiple filenames as in:

     2MassQuery --stdin < my.list

and

     2MassQuery --filename=my.list [--filename=my.list2 ...]

By default 2MassQuery output is written to stdout, but with the --browser option 2MassQuery can issue the query in the context of one or more external browser instances:

> 2MassQuery target [target2...] --browser

Other than for external browser-based queries, 2MassQuery produces basic information on the target(s) on stdin, as in:

     2MassQuery NGC_4151 75_cnc 64_psc
     # 2Mass Search NGC_4151:  K = 8.519
     # 2Mass Search 75_cnc:  K = 4.372
     # 2Mass Search 64_psc:  K = 4.182
     
     2MassQuery NGC_4151 --error
     # 2Mass Search NGC_4151:  K = 8.519 +/- 0.018
     
     2MassQuery NGC_4151 --photometry --error --coord
     # 2Mass Search NGC_4151:  12 10 32.6  +39 24 21.1  K = 8.519 +/- 0.018  J = 10.262 +/- 0.023  H = 9.436 +/- 0.023

Command-Line Options

Usage:

     	2MassQuery [options]

where valid options include:

     	--allData --browser --coord --error --extended --Hmag --Jmag --Kmag
     	--lineWidth= --photometry --searchRadius --searchRA= --searchDec= --url

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --Hmag: return 2MASS H-band photometry on the designated source(s). Units are magnitudes. Default off, no argument when used.
• --Jmag: return 2MASS J-band photometry on the designated source(s). Units are magnitudes. Default off, no arguments when used.
• --Kmag: return 2MASS K-band (Ks) photometry on the designated source(s). Units are magnitudes. [This option on by default (and at present there is no way to turn it off).] No argument when used.
• --photometry: return all three bands (J, H, Ks) of 2MASS photometry.
• --allData/--data: directs 2MASSQuery to dump the returned result text without any parsing – you get just what IRSA serves. No argument when used.
• --browser: directs 2MASSQuery to open the composed queries (URLs) in an external browser. The runtime parameter GC_BROWSER is used here.
• --coord: directs 2MASSQuery to extract and report on the 2MASS astrometry for search targets. No argument when used.
• --error: return error estimates on the provided photometry. Default off, no arguments when used.
• --extended: Execute an extended 2MASS query, returning such items as the 2MASS designation, error flags, etc. Default off, no arguments when used. When invoked, 2MASSQuery returns the full IRSA reply text (see --allData above).
• --lineWidth=: format the result return lines to width argument. Only useful in conjunction with the --allData option, integer argument required when used.
• --searchRA=, --searchDec=: search input coordinates, no default. The search input coordinates can have a variety of formats, mostly based around either decimal degrees, or an hour/deg - minute - second designation. Here are some examples which should all yield equivalent results:

            --searchRA=331.75
            --searchRA=22:07
            --searchRA=22h7m00s
            --searchRA=22_07_00
            
            --searchDec=25.3333333333333
            --searchDec=25d20m
            --searchDec=25:20:00
            --searchDec=+25_20
       

  If you want to use spaces in the arguments, you may, as long as you quote the arguments using double quotes–e.g.:

            --searchRA="22 07 00" --searchDec="25 20 00"
       

  Note that using seconds is optional for both RA and Dec, but using minutes is not. Without a minutes argument the program will think you're trying to give it a decimal degrees (i.e. --searchRA=22 will be interpreted as 22.0 degrees), probably not what you had in mind.

  When used, these options require a string argument.

• --searchRadius=|--radius=: Set the search radius (in arcsec) of the query. IRSA services resolve designations via NED/Simbad into coordinates if necessary, then cone-search in the catalog by position. This argument allows the user to control the radius of the cone search. The default search radius is three (3) arcseconds. An argument is required when this option is used.
• --url/--generateURL: directs 2MASSQuery to return the composed URL(s) on stdout (rather than executing the HTTP transaction). No argument when used.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

Search Target Input

2MassQuery is (of course) just a 2MASS robot. It works (primarily) by routing search targets to the 2MASS point-source catalog server at IPAC/IRSA without interpretation. If (when) you get the pervasive error message:

     2MassQuery bogus
     Designation bogus resulted in a query error to the 2MASS database:
     
      ERROR
       Error Type: UserError
       Message: Invalid location specification or object name.

it means the name was not recognized during "name resolution". Name resolution for IRSA services is provided by NED and Simbad, so if (when) you have these issues I suggest you consult the designation dictionary at Simbad (http://vizier.u-strasbg.fr/cgi-bin/Dic-Simbad) for clarification on Simbad designation standards (or, if you're looking at extra-galactic targets, the equivalent at NED http://nedwww.ipac.caltech.edu/).

As indicated above, this version of 2MassQuery can accept search targets by three methods: on stdin, via one or more files, or as direct command-line arguments. These three input methods are mutually exclusive.

Search target input on stdin is assumed by 2MassQuery if there are no remaining command-line arguments after option processing, or if specifically directed by --stdin. Input on stdin follows the general principles outlined in the file format discussed in the following paragraph.

Search target input via files is invoked by one or more instances of the -filename option on the command line (see below). The required format of the file is individual search targets listed one per line. Blank lines and #-prefaced comments are acceptable. An example illustrating most of the aspects of the file format is:

     ## Sample 2MQ input file format
     
     ## Previous line left intentionally blank
     Omi Cet
     iota Peg  ## The universe's most important spectroscopic binary
     DG Tau    ## A boring low-mass YSO
     NGC_1068  ## I'm Shapley -- I don't believe in extragalactic objects
     ## EOF

If not using stdin or files, search target input via the command-line is the last alternative. Here you can input one or more search targets on the command-line, interspersed with command options:

     2MassQuery Omi_Cet --photometry iota_peg --error NGC_1068 --coord
     # 2Mass Search Omi_Cet:  02 19 20.8  -02 58 39.3  K = -2.213 +/- 0.216  J = -0.732 +/- 0.148  H = -1.574 +/- 0.192
     # 2Mass Search iota_peg:  22 07 00.7  +25 20 42.4  K = 2.564 +/- 0.290  J = 2.954 +/- 0.222  H = 2.729 +/- 0.184
     # 2Mass Search NGC_1068:  02 42 40.7  -00 00 48.0  K = 7.271 +/- 0.019  J = 10.179 +/- 0.104  H = 9.136 +/- 0.120

Unique to the command-line input method, underscores are _required_ to join multiple words in a target designation (iota_peg, 64_Psc, 75_Cnc, 12_Boo). (These are optional but acceptable in the stdin and filename input methods.)

Implementation

2MassQuery is somewhat deprecated beginning with getCal release 2.8. 2MassQuery is included for backward compatibility with previous versions of the getCal suite; all of its queries get funnelled into irsaminer. We recommend using irsaminer in place of 2MassQuery.

3.14 IRASQuery

IRASQuery – Query the IRAS point-source catalog by HTTP

• Description
• Command-Line Options
• Search Target Input
• Implementation

Description

IRASQuery is a perl program (and part of the getCal suite) that interfaces with the IRAS point-source catalog to query that catalog for IRAS photometry on one or more astronomical objects (herein search targets) or position search targets. (See IRAS description at http://irsa.ipac.caltech.edu/IRASdocs/iras.html.)

IRASQuery is primarily designed to retrieve IRAS photometry, but optionally IRASQuery can also return astrometric information, and submit the query in the context of an external user-interactive web browser application. Most of the IRASQuery interface semantics and functionality is designed to be a general service for getCal components, but the executable is exposed to the user as part of the getCal install, and is accessible (and maybe even useful) from the command-line. IRASQuery is the companion program to simbadInteractiveQuery and 2MassQuery, and they share many design features and implementation techniques.

IRASQuery uses services from the InfraRed Science Archive (IRSA) at the Infrared Processing and Analysis Center (IPAC).

The basic IRASQuery invocation looks like:

     IRASQuery [options] search_target [search_target2...] [more options]

By default IRASQuery retrieves the search targets from the command line, but it can optionally read from stdin or multiple filenames as in:

     IRASQuery -stdin < my.list

and

     IRASQuery -filename my.list [-filename my.list2 ...]

By default IRASQuery output is written to stdout, but with the -browser option IRASQuery can issue the query in the context of one or more external browser instances:

> IRASQuery target [target2...] -browser

Other than for external browser-based queries, IRASQuery produces basic information on the target(s) on stdin, as in:

     IRASQuery 64_psc iota_peg HD_166
     # IRAS Search 64_psc:  fnu_12 = 1.192e+00
     # IRAS Search iota_peg:  fnu_12 = 3.697e+00
     # IRAS Search HD_166:  fnu_12 = 7.897e-01
     
     IRASQuery iota_peg -error
     # IRAS Search iota_peg:  fnu_12 = 3.697e+00 +/- 6%
     
     IRASQuery iota_peg -phot -error -coord
     # IRAS Search iota_peg:  22 07 00.8  +25 20 43.4  fnu_12 = 3.697e+00 +/- 6% fnu_25 = 8.211e-01 +/- 12% fnu_60 = 4.000e-01 +/- 0% fnu_100 = 1.000e+00 +/- 0 %

Please note that the output photometry is flux in units of Janskys, as opposed to the magnitudes you're probably used to.

Command-Line Options

IRASQuery supports a variety of command-line options:

     	--allData --browser --coord --error --extended --f12 --f25 --f60 --f100
     	--lineWidth= --photometry --searchRadius --searchRA= --searchDec= --url

     	--copyright --debug --filename= --help --longHelp --version --stdin

• --f12: return IRAS 12 um flux photometry on the designated source(s). Units are Janskys. [This option on by default (and at present there is no way to turn it off).] No argument when used.
• --f25: return IRAS 25 um flux photometry on the designated source(s). Units are Janskys. Default off, no arguments when used.
• --f60: return IRAS 60 um flux photometry on the designated source(s). Units are Janskys. Default off, no argument when used.
• --f100: return IRAS 100 um flux photometry on the designated source(s). Units are Janskys. Default off, no argument when used.
• --photometry: return all four bands (12 um, 25 um, 60 um, 100 um) of IRAS flux photometry.
• --allData/--data: directs IRASQuery to dump the returned result text without any parsing – you get just what IRSA serves. No argument when used.
• --browser: directs IRASQuery to open the composed queries (URLs) in an external browser. The runtime parameter GC_BROWSER is used here.
• --coord: directs IRASQuery to extract and report on the IRAS astrometry for search targets. No argument when used.
• --error: return error estimates on the provided photometry. Default off, no arguments when used.
• --extended: Execute an extended IRAS query, returning such items as the IRAS designation, error flags, etc. Default off, no arguments when used. When invoked, IRASQuery returns the full IRSA reply text (see --allData above).
• --lineWidth=: format the result return lines to width argument. Only useful in conjunction with the --allData option, integer argument required when used.
• --searchRA=, --searchDec=: search input coordinates, no default. The search input coordinates can have a variety of formats, mostly based around either decimal degrees, or an hour/deg - minute - second designation. Here are some examples which should all yield equivalent results:

            --searchRA=331.75
            --searchRA=22:07
            --searchRA=22h7m00s
            --searchRA=22_07_00
            
            --searchDec=25.3333333333333
            --searchDec=25d20m
            --searchDec=25:20:00
            --searchDec=+25_20
       

  If you want to use spaces in the arguments, you may, as long as you quote the arguments using double quotes–e.g.:

            --searchRA="22 07 00" --searchDec="25 20 00"
       

  Note that using seconds is optional for both RA and Dec, but using minutes is not. Without a minutes argument the program will think you're trying to give it a decimal degrees (i.e. --searchRA=22 will be interpreted as 22.0 degrees), probably not what you had in mind.

  When used, these options require a string argument.

• --searchRadius=|--radius=: Set the search radius (in arcsec) of the query. IRSA services resolve designations via NED/Simbad into coordinates if necessary, then cone-search in the catalog by position. This argument allows the user to control the radius of the cone search. The default search radius is five (5) arcseconds. An argument is required when this option is used.
• --url/--generateURL: directs IRASQuery to return the composed URL(s) on stdout (rather than executing the HTTP transaction). No argument when used.

Generic options:

• --copyright: print out getCal copyright information and exit.
• --debug: Turns on debugging output, sent to stderr. When used multiple times, this option increases the verbosity of debug output.
• --help: print out short help message. Overrides all other arguments.
• --longHelp: print out a long help message. --longHelp overrides all other arguments except --help.
• --version: print out module version information and exit.
• --stdin: force reading of input items from stdin. No argument when used.
• --filename=: Read input from the specified file(s). Multiple instances of this option are allowed.

Search Target Input

IRASQuery is (of course) just a robot. It works (primarily) by routing search targets to the IRAS point-source catalog server at IPAC/IRSA without interpretation. If (when) you get the pervasive error message:

     IRASQuery bogus
     Designation bogus resulted in a query error to the IRAS database:
     
      ERROR
       Error Type: UserError
       Message: Invalid location specification or object name.

it means the name was not recognized during "name resolution". Name resolution for IRSA services is provided by NED and Simbad, so if (when) you have these issues I suggest you consult the designation dictionary at Simbad (http://vizier.u-strasbg.fr/cgi-bin/Dic-Simbad) for clarification on Simbad designation standards (or, if you're looking at extra-galactic targets, the equivalent at NED http://nedwww.ipac.caltech.edu/). If nothing seems to work, try a search on the position coordinates instead of the name.

As indicated above, this version of IRASQuery can accept search targets by three method: on stdin, via one or more files, or as direct command-line arguments. These three input methods are mutually exclusive.

Search target input on stdin is assumed by IRASQuery if there are no remaining command-line arguments after option processing, or if specifically directed by the -stdin command-line argument (see below). Input on stdin follows the general principles outlined in the file format discussed in the following paragraph.

Search target input via files is invoked by one or more instances of the -filename option on the command line (see below). The required format of the file is individual search targets listed one per line. Blank lines and #-prefaced comments are acceptable. An example illustrating most of the aspects of the file format is:

     ## Sample IRASQuery input file format
     
     ## Previous line left intentionally blank
     Omi Cet
     iota Peg  ## The universe's most important spectroscopic binary
     DG Tau    ## A boring low-mass YSO
     NGC_1068  ## I'm Shapley -- I don't believe in extragalactic objects
     ## EOF

If not using stdin or files, search target input via the command-line is the last alternative. Here you can input one or more search targets on the command-line, interspersed with command options:

     IRASQuery Omi_Cet -phot iota_peg -error NGC_1068 -coord
     # IRAS Search Omi_Cet:  02 19 20.8  -02 58 36.1  fnu_12 = 4.881e+03 +/- 6% fnu_25 = 2.261e+03 +/- 6% fnu_60 = 3.008e+02 +/- 7% fnu_100 = 8.844e+01 +/- 10 %
     # IRAS Search iota_peg:  22 07 00.8  +25 20 43.4  fnu_12 = 3.697e+00 +/- 6% fnu_25 = 8.211e-01 +/- 12% fnu_60 = 4.000e-01 +/- 0% fnu_100 = 1.000e+00 +/- 0 %
     # IRAS Search NGC_1068:  02 42 40.9  -00 00 46.1  fnu_12 = 3.830e+01 +/- 5% fnu_25 = 8.683e+01 +/- 4% fnu_60 = 1.858e+02 +/- 8% fnu_100 = 2.405e+02 +/- 8 %

Unique to the command-line input method, underscores are _required_ to join multiple words in a target designation (iota_peg, 64_Psc, 75_Cnc, 12_Boo). (These are optional but acceptable in the stdin and filename input methods.)

Implementation

IRASQuery is somewhat deprecated beginning with getCal release 2.8. IRASQuery is included for backward compatibility with previous versions of the getCal suite; all of its queries get funnelled into irsaminer. We recommend using irsaminer in place of IRASQuery.

3.15 gcGui

gcGui – Graphical User Interface wrapper for getCal

• gcGui Description
• Configuration
• Menu and Button Descriptions
• Keyboard Shortcuts
• Return Windows

gcGui Description

gcGui is a Perl/Tk graphical user interface (GUI) to the getCal suite of tools. It allows the user to graphically interact with getCal, both inputting information into entry forms, and displaying information in return text boxes which can be saved to files.

gcGui works by interacting with the user, composing and issuing the appropriate getCal command-line invocation, and returning the output both to stdout (where it could be captured by the user to keep a log of the session) and to text boxes created expressly for display purposes. gcGui is essentially a command-line composer – all the actual smarts remains within getCal (and its constituents).

Here is a screenshot of gcGui in action:

To keep the interface relatively clean, not all getCal functions and options are exposed/accessible through gcGui – hopefully I've enabled the ones most interesting to you.

gcGui requires that the Perl/Tk module be installed in Perl tree (or Perl module path), see the getCal installation and setup documentation).

This documentation does not constitute an exhaustive getCal discussion – for more complete discussions of getCal structure and function see the getCal documentation itself.

Configuration

gcGui uses the following values from the getCal runtime parameter list (see Run-Time Configuration):

GC_BROWSER – the default external browser. Nominally a standard browser application like netscape, mozilla, safari, or firefox.

GC_DEFAULT_LOCATION – default location

GC_DEFAULT_BASELINE – default baseline designation

Menu and Button Descriptions

Menus:

• File:
  • Dispatch – invoke getCal with current option set (keyboard Alt-g)
  • Reset – return all gcGui options and settings to default conditions (keyboard Alt-r)
  • Quit – go find something else to do (keyboard Alt-q)
• Help:
  • gcGui help – this help message (keyboard Alt-h)
  • about gcGui – minimalist about gcGui info
  • getCal help – the long getCal help file
  • getCal short help – getCal help for those with ADD
  • fbol help – more about fbol...
  • fbol help – more about fbol...
  • timing help – more about timing...
  • obsCalendar help – more about obsCalendar...
  • getCal version – getCal version statement...
  • getCal copyright – getCal copyright statement...

Main gcGui window:

• Target Frame:
  • Object Designation/Position – User input of target designation or search position. Discussion on the use of these options can be found in the getCal documentation. Note that keyboard return in the object entry box dispatches the getCal retrieval.
  • Designator Type – -targetName, -targetHD, -targetHIP, -searchRA, -searchDec control. User control of the type of designation made: name (resolved by Simbad), HD catalog number, HIP catalog number, or Pos astrometric position.
• Photometry Search/Output Options Frame: Options controlling how getCal obtains and uses photometry information.
  • K-Band – select source for K-band photometry. When "Model" is selected, getCal will use an internal model (V-K) for estimating K-band magnitude. When "2Mass" is selected, the 2Mass point source catalog is queried for K-band magnitude. Default is "Model".
  • N-Band – When enabled using the checkbox, include N-band photometry in target and calibrator output lines, and enable buttons for selecting source for N-band photometry. When "Model" is selected, getCal will use an internal model (V-N) for estimating N-band magnitude. When "IRAS" is selected, the IRAS point source catalog is queried for 12um flux data, which is then used to approximate an N-band magnitude. This option is disabled by default, and when enabled the default is "Model".
  • Use 2MASS/IRAS measurements for cal search – when selected, causes getCal's calibrator search function to use the K/N magnitudes from 2MASS/IRAS instead of the internal model when evaluating magnitude range limits. This option can slow getCal significantly, as 2MASS/IRAS queries must be performed for each calibrator candidate before magnitude range checks are performed, greatly increasing the number of queries done. However, it may improve the accuracy of calibrator search results where model-based magnitudes are significantly different than the actual values.
• Calibrator Output Control Frame: This frame controls whether calibrator information is included in the output, and if so, the method and parameters used for calibrator selection. When unchecked, the -noCal option is passed to getCal to disable calibrator output. When checked, the calibrator options listed below are enabled.
  • User-specified calibrators – -cal control. Bypass calibrator selection algorithm, instead including calibrators which have been provided by the user. Calibrators are entered as a comma-separated list of names. At this time only HD and HIP designations are recognized, and no SIMBAD name lookups are performed for object designations entered in this field.
  • Calibrator search – enable getCal calibrator selection algorithm, using selection criteria from the parameter entry boxes.
  • Luminosity Class Selection – -lClass control. V (main sequence – default), III (giant), or I (supergiant) calibrators. Any or all can be selected. If NONE are selected getCal will default to main sequence calibrators.
  • Max Diam – -maxAD control. Select maximum model diameter for calibrators. When selected, select calibrators whose model diameter is smaller than the entered size (units of mas). Disabled by default.
  • Calibrator Search Radius – -searchRadius control. Calibrator proximity search radius, units of deg, default 10, argument required when used.
  • Magnitude Ranges – -minV, -maxV, -minK, -maxK, -minN, -maxN control. Calibrator V/K/N magnitude ranges. Use requires both checkbox selection and argument input (units of mag). getCal will use default values for V/K limits if not specified. getCal does not use any default values for N mag limits, N mag is not limited unless limits are explicitly specified. The gcConf utility Also see Run-Time Configuration for configuration of these defaults.
• Simbad Query Frame: Simbad Query – -simbadInteractiveQuery control. Invokes Simbad database access for targets/calibrators – Disabled by default.
  • Common Names – -commonNames control. Extracts and reports on object common names – default off.
  • Simbad Meas – -meas control. Extracts and reports on measurements in the Simbad database – default off.
  • Browser – -browser control. Invokes Simbad query on the returned object set in an external browser (specified by the GC_BROWSER runtime parameter).
• Timing Info Frame – -timing control (see timing). Compute object transit times, zenith angle and delay temporal limits, sunrise and sunset – default off. When enabled, the following timing-related options are available:
  • Observing Calendar Display – (no getCal CL-option analog). Run obsCalendar to perform observation calendar computations and route output to ocGui – default off.
  • Timing Display – (no getCal CL-option analog). Route timing info computations to tGui – default off.
  • u-v Display – (no getCal CL-option analog). Route timing info computations to uvTool – default off.
  • Select Location – (-location option to timing). Specify observing location used for timing calculations from list of interferometers known to getCal – Defaults to location indicated by GC_DEFAULT_LOCATION runtime parameter).
  • Select Baseline – (-baseline option to timing). Specify observing baseline from among a discrete set of options – Defaults to baseline indicated by GC_DEFAULT_BASELINE runtime parameter). Multiple individual baselines can be selected.
  • Select Zenith Angle Limit – (-zenithAngle option to timing). Specify the zenith angle limits for timing calculations. Defaults to 35 deg.
  • Select Delay Bias Offset – (-bias option to timing). Specify the delay bias offset for the timing calculations (for use to compute delay limits for LDL/FDL combination see timing documentation). Default is set appropriately for designated interferometer.
  • Delay Limits – Specify delay line limit(s) used for timing calculations. Delay can be expressed as symmetric (-delayLimit option to timing) or asymmetric (-delayMin / -delayMax options to timing). Default limit is set appropriately for designated interferometer.
  • Select Date – Date used for timing calculations, default is today (UTC).
  • Month – -month control. Default this month UTC.
  • Day – -day control. Default today UTC.
  • Year – -year control. Default this year UTC.
  • Compute Null Depth Estimates – (-nullDepth control When selected, generates null depth report. Default off. See the --nullDepth option to timing.
• fbol Diameters – -fbol control. Compute apparent diameter estimates based on effective temperature and bolometric flux model fit to available photometry extracted from Simbad – default off. When used, getCal will automatically invoke Simbad measurement extraction regardless of user selections. Defaults to extracting UBV, Geneva, Stromgren, and JP11 Simbad photometry. See the fbol documentation.
  • 2Mass IR Phot – -2Mass control. IF fbol Diameters selected, extract 2Mass photometry from the 2Mass point source catalog server at IPAC/IRSA – default off. See 2MassQuery.
  • IRAS Long WL Phot – -longWL control. IF fbol Diameters selected, extract Simbad IRAS flux data – default off.
  • Constrain Temp – -constrainTemp control. IF fbol Diameters selected, constrain effective temperatures in black-body fits to model effective temperatures based on spectral type, Geneva photometry, and Stromgren photometry – default off.
  • Save Photometry – -savePhotometry control. IF fbol Diameters selected, records the input fbol photometry created from various sources – default no.. When checked the fbol photometry input comes up in a separate window and can be edited and separately saved.
  • fbol Plots – -plots control. IF fbol Diameters selected, use gnuplot to generate plots of photometric fits – default off. If no additional plot options are selected (see below), plots will be X11 screen plots.
  • PostScript – -hardcopy control. IF fbol Plots is selected, allow user to select generation of gnuplot vanilla (landscape) PostScript plots of the spectrophotometry fits – default no. Plots will be placed in current working directory under names like HD123999--F9IVw.sed.ps.
  • EPS – -eps control. IF fbol Plots is selected, allow user to select generation of gnuplot encapsulated (portrait) PostScript plots of the spectrophotometry fits – default no. Plots will be placed in current working directory under names like HD123999--F9IVw.sed.eps.
  • PNG – -png control. IF fbol Plots is selected, allow user to select generation of PNG (Portable Network Graphics) plots of the spectrophotometry fits – default no. Plots will be placed in current working directory under names like HD123999--F9IVw.sed.png.
• Additional Options Frame:
  • Message Level – (-quiet, -verbose options). Reduces or increases verbosity of informational messages produced by getCal. Default is "Normal".
  • Output Format – (-format control). Select output format produced by getCal. Default is controlled by GC_DEFAULT_FORMAT runtime parameter. See getCal Format for descriptions of these formats.
    • "new" - (-format=new). Output is in "new" format (used by KI).
    • "old" - (-format=old). Output is in "old" format (used by PTI).
    • "Keck sky" - (-format=sky). Output is in Keck sky software compatible format.
  • Parallax – -plx control. Direct getCal to include the object parallax as part of the GUI line – default off.
  • Rename targets to HD/HIP ID – (-rename control). Causes target designations to be rewritten as a preferred HD or HIP designation where possible. Default is off, targets will appear in the output as originally specified by the user.
  • Use PTI-style HDC prefix – (-identHDC control). Causes "HDC" prefix to be used in place of "HD" for output designations. Default is off.
  • Cal Script Composition – -calScript control. Compose preliminary calibration script for use with calib-suite of visibility calibrators – default no. When selected, getCal will (try to) create a prototype calibration script, and display it in its own (editable – emacs commands) text window. Can be saved separately from the rest of getCal output.
  • xEphem Display – xEphemDisplay control. Route the getCal output to xephem sky plotting software – default no.
• Invocation Frame:
  • Dispatch – invoke getCal with current option set
  • Reset – return all gcGui options and settings to default conditions
  • NExScI Logo – Shameless self-promotion. Remember, we're from the NExScI, we're here to help.
  • Quit – go find something else to do

Keyboard Shortcuts

gcGui supports a number of keyboard shortcuts:

• Alt-g – Dispatch getCal (go, do!)
• Alt-r – Reset defaults
• Alt-q – Quit gcGui
• Alt-h – gcGui help

Return in object designation entry box dispatches getCal retrieval. Return in other entry boxes selects/enables the corresponding option (e.g. max K mag, zenith angle restriction).

Return Windows

gcGui packages the getCal output in several return windows:

• Main return window – the main return window is always produced by a gcGui/getCal invocation. This window allows the user to query Simbad on the returned object set a posteriori via an external browser (Simbad Browser button).
  
• calScript window – the calScript window is optionally created with the contents of the prototype calibration script composed by getCal.
• tGui, ocGui, and uvTool display – these getCal companion tools are invoked for additional information as specified by the user.
• photometry window – the retrieved photometry for SED modelling.
  

  Also new in the v2.6 series, the photometry display window now offers the option of processing the displayed (and editable) photometric data with fbol. Clicking the “run fbol” button will open a dialog box to edit fbol options, and then allow you to process the photometry through fbol and displaying the textual result.

3.16 tGui

tGui – Perl/Tk GUI visualization of target diurnal accessibility

• tGui Description
• Command-Line Options
• Third-Party Software
• tGui Menu Description
• tGui Frames and Control Buttons
• Keyboard Shortcuts
• tGui Customization

tGui Description

tGui is a Perl/Tk application that renders a line graph depicting the target accessibility calculations performed by the timing application from getCal. Its purpose is to graphically inform the user about the target temporal accessibility. As such it additionally provides functionality to depict local sunrise/sunset times, current UT/LST, and target cluster transitions, so tGui has both planning and real-time utility.

A screenshot of tGui in action is given here:

tGui functions by reading and parsing the output of the getCal timing program (timing), which looks like:

     # Timing summary (timing v0.51dev) run at 12/28/2001 UTC, day 2001362
     #  for timings on 12/28/2001 UTC, day 2001362
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Using PTI_NS Baseline (ENUBias: -37.116352 -103.264746 3.319338 -12.915245)
     # Using PTI_NW Baseline (ENUBias: -81.685124 -28.214086 3.105647 0.031416)
     # The JD at 0 hr UT is 2452271.5
     # The LST at 0 hr UT is 22:38:41
     # The Local Time at 0 hr UT is 16:00:00
     # Approximate UT sunset -- sunrise times: 01:46:00 -- 13:51:41 (12 deg twilight)
     # Approximate UT moonrise -- moonset times: 22:43:48 -- 13:00:29
     #   94% moon illumination -- 2.2 days until full moon (moon at 04:26 RA  +19:46 Dec)
     # Using 35 deg zenith angle (1.22 airmass) constraint
     # Using 38.3 m delay constraint
     
     # HIP113715 23 01 49.467  +45 53 09.119  transits at 00:23:05 UT, zenAng 12.5 deg (1.02 am) target
     # HIP113715 is within zenith angle range from 21:30:36 to 03:15:34 UT
     # HIP113715 is within delay range from 23:35:27 to 05:26:10 UT for PTI_NS
     # HIP113715 is within delay range from 22:01:35 to 04:04:42 UT for PTI_NW
     HIP113715 23 01 49.467 +45 53 09.119 -0.006  0.001 9.7 9.7 C3.4v 0.0 xxx   xxx  trg

Like the rest of the getCal architecture, the idea with the functional decomposition is the timing program has utility outside of just gui functions. tGui accepts input on stdin:

     timing < my.schedule | tGui

or

     cat my.schedule | timing | tGui

or if the schedule already contains timing annotations just

     tGui < my.schedule.with.annotations

or tGui will accept a filename as a single command-line argument:

     tGui my.schedule.with.annotations

or even the maximally explicit:

     tGui -filename my.schedule.with.annotations

tGui renders the accessibility calculations as a graph with time on the horizontal axis, and with horizontal lines indicating the target's temporal accessibility for the set of input objects. This view is modeled after a conventional scheduling Gant chart, and was the original idea of Gerard van Belle (thanks GvB!). By default (and popular demand) tGui renders the logical intersection of the separate zenith angle, delay (and if defined, pointing) limits, but the Intersection Track control button (see below) can quickly toggle the display between the intersection and separate constraints.

tGui allows the user to add an arbitrary (UT) time offset to the timing graph; see UT Offset below.

tGui can indicate the transitions between target clusters in a nightly schedule provided that there are cluster timing annotations in the schedule in the following form:

     ## Cluster 1: sunset to 4:30 UT
     ...
     ## Cluster 2: 4:30 to 7:30 UT
     ...
     ## Cluster 3: 7:30 to 9:00 UT
     ...
     ## Cluster 4: 9:00 UT to sunrise
     ...

These time values are assumed to be in UT. A "Cluster" control button allows user control of rendering the vertical lines indicating these cluster transitions (see "Clusters" below). (Note – the search keys on two hashes, a space, and the Cluster keyword.)

tGui can make PostScript of the current timing display, shipping the output directly to a PostScript-capable printer or save the output to a PostScript file. pdf, gif, jpg, and png file formats are also supported.

I further find it useful to have both tGui and uvTool running simultaneously, so I added a option (under the File menu) to route the input information into uvTool (designed to save you a little work over a separate command-line invocation).

tGui also provides a Simbad menu used to spawn Simbad queries on targets contained in the input stream. By default these queries are executed in an external web browser (set via the runtime parameter GC_BROWSER). If an external browser is unavailable, the query results will be displayed in a pop-up text window. (Note: the remote access can be slow.)

If you don't like my sense of aesthetics you can alter the appearance of tGui by editing the tGui attribute file (tGuiAttributes.pm, a perl module file) in the modules subdirectory. There you can play with colors, sizes, menu parameters, and the like. Some crude things (like window resizing) now work a little more intuitively.

tGui now takes command-line options, and can generate hardcopy (PostScript, pdf, gif, jpg, png) in batch mode, and also interactively. Command-line options are necessary to support the batch-mode hardcopy creation, but are potentially useful on startup to the interactive user as well (see tGuiOptions below). Hardcopy options beyond PostScript require third-party support software – again see options below. Interactive hardcopy creation is supported by a dedicated popup dialog box triggered from the print command/button (see below).

tGui can recompute (i.e. drive the recomputation through timing) the timings on the input catalog (or even read a whole new catalog through timing). The default timing argument is adaptive, reflecting the timing options contained in the input – this makes it less labor-intensive to make small changes to the timing computations.

As of getCal-2.6beta2, tGui has popup balloon help messages for many of its controls and features.

Command-line Options

tGui accepts the following command-line options:

• -help: generate a short help message and exit.
• -version: generate a short version message and exit.
• -stdin: force reading of timing input from stdin – no arguments when used.
• -filename arg: force reading of timing input from a particular file – desired filename argument when used.
• -sun [arg]: select sunrise/sunset rendering options – default off, optional integer argument when used. Integer arg can have the following values: 0 – no rendering (default and no argument), 1 – render lines but no labels, 2 – render lines and labels.
• -moon: select moon rendering – default off, no argument when used.
• -timeLabels [arg]: select secondary time axis labeling options – default 1 (LST), optional integer argument when used. Integer arg can have the following values: 0 – no rendering (default and no argument), 1 – render LST, 2 – render local time, 3 – render UT.
• -currentTime [arg]: select display options of a red vertical line indicating the current UT/LST – default 0 (none), optional integer argument when used. Integer arg can have the following values: 0 – no rendering (default and no argument), 1 – render line only, 2 – render line with UT and LST annotations.
• -baseline arg: select baseline to render – default composite, string argument required when used. Default is to render the composite baseline (the intersection of the baseline restrictions for all the baselines in the input).
• -intersectionTrack [arg]: select whether or not to render zenith/delay/pointing intersection representation – default on, optional integer argument when used. Integer arg can have the following values: 0 – no intersection rendering, 1 – intersection rendering.
• -zenithTrack [arg]: select whether or not to render zenith angle-limited representation – default off, optional integer argument when used. Integer arg can have the following values: 0 – no zenith track rendering, 1 – zenith angle track rendering.
• -delayTrack [arg]: select whether or not to render delay range-limited representation – default off, optional integer argument when used. Integer arg can have the following values: 0 – no delay track rendering, 1 – delay track rendering.
• -pointingTrack [arg]: select whether or not to render pointing range-limited representation – default off, optional integer argument when used. Integer arg can have the following values: 0 – no pointing track rendering, 1 – pointing track rendering.
• -calibrators: select whether or not to render objects designated as calibrators – default no, no argument when used. Note that calibrators are rendered in muted colors to aid their identification.
• -ps|postscript|PostScript|hc: direct batch-mode (i.e. tGui exits after) creation of a PostScript timing graph – output to timing.ps. Default no, no argument when used.
• -pdf: direct batch-mode creation of a pdf timing graph – output to timing.pdf. Default no, no argument when used.
• -gif: direct batch-mode creation of a gif timing graph – output to timing.gif. Default no, no argument when used.
• -jpg: direct batch-mode creation of a jpg timing graph – output to timing.jpg. Default no, no argument when used.
• -png: direct batch-mode creation of a png timing graph – output to timing.png. Default no, no argument when used.

All command-line arguments can be abbreviated to uniqueness (e.g. -he[lp], -de[layRange], -s[un], -ps) using one or two hyphens, and given in arbitrary order with respect to other command-line items.

Third-Party Software

In addition to the Perl/Tk package, tGui uses the following third-party software:

• To generate gif, jpg, and png, tGui uses utilities from the netpbm package, namely pstopnm, pnmflib, ppmtogif, ppmtojpg, and pnmtopng. See http://netpbm.sourceforge.net/
• To generate pdf, tGui uses ps2pdf, the ps to pdf translator function from ghostscript. See http://www.cs.wisc.edu/~ghost/.
• tGui can interface to the excellent third-party sky visualization software XEphem

tGui Menu Description

tGui provides the following menus:

• File (general program controls):
  • Recompute timings... – Recompute & re-render timings for the current input object set (keyboard Alt-r). This option opens a window where the user can compose the appropriate timing invocation (see the timing documentation). Default timing argument reflects timing settings of input.
  • Open... – Open new schedule file (keyboard Alt-o). This option opens a file selector window.
  • Open Through timing... – Open new catalog file and recompute timings (keyboard Alt-O). This option opens a file selector window followed by a timing invocation composition window (see timing).
  • View Input – View the input information (schedule) into tGui in a text window (keyboard Alt-v). Allows schedule save.
  • uvTool – Route the input information (schedule) into uvTool (keyboard Alt-u).
  • XEphem Catalog – translate the working catalog into an XEphem catalog via xeConvert, and save the output (keyboard Alt-x).
  • XEphem FIFO – translate the working catalog into an XEphem catalog via xeConvert, and write the output to the XEphem database FIFO specified in GC_XEPHEM_FIFO (keyboard Alt-X).
  • Print – Print the display canvas to a PostScript, pdf, gif, jpeg, or png file or printer (keyboard Alt-p). Opens dialog box.
  • Quit – Go find something else to do (keyboard Alt-q).
• Target (object rendering controls):
  • Targets – Render only objects designated as targets (default) (keyboard Alt-t).
  • Calibrators – Toggle the rendering of objects designated as calibrators (keyboard Alt-c).
  • All – Render all input objects (keyboard Alt-a).
  • Invert – Toggle rendering of all objects (keyboard Alt-i).
  • None – Render no objects (keyboard Alt-n).
  • xxx – Toggle rendering for an individual object (checkbox indicates current status).
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.
• Baseline (baseline rendering controls):
  • xxx – Render delay constraints for baseline designation xxx.
  • none – Do not render delay constraints (in case you don't have a delay line...or an interferometer).
• Simbad (Simbad query controls):
  • Targets – Query Simbad on all objects designated as targets. Calibrators – Query Simbad on all objects designated as calibrators.
  • All – Query Simbad on all objects.
  • xxx – Query Simbad on individual objects
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.

    [For all – if external browser is accessible through runtime parameter GC_BROWSER, queries will be executed in the browser context. If not, queries are executed and minimal information is returned in a text window.]

• Help (view available help):
  • tGui help – View this help file.
  • timing help – View timing help file.
  • getCal version – getCal version statement.
  • getCal copyright – getCal copyright statement.

Note all menus are detachable/tear-off

tGui Frames and Control Buttons

Frames:

• Preamble Frame: Scrollable read-only text frame that displays some pertinent information (e.g. date, location, baselines, constraint settings) extracted from the preamble of the timing input.
• Current Time Frame: Displays (approximate) current UT, LST, and observatory local time (if available).
• Display Canvas: Scrollable display area for the target accessibility line graph. The graph displays time (UT in hours) on the horizontal axis, and multiple objects on the vertical axis. For each target the local transit time is rendered with a red triangle. Colored horizontal lines indicate when the target will be within range. The zenith angle accessibility is rendered with a green horizontal line. The delay line accessibility for the selected baseline (Baseline menu) is rendered by a blue horizontal line. If the input includes pointing range information, the pointing range accessibility is rendered with an orange horizontal line, otherwise this line is not shown. The logical intersection of the ZA, delay and pointing is rendered in black. Demarcations indicating local sunset/sunrise times and current UT/LST can be displayed (see below).

  Note that if pointing information is available indicating that an object is out of pointing range when it transits, the normal transit marker (a red triangle) is highlighted with a yellow background and overlaid with a black vertical bar.

• Legend Canvas: Simple canvas displaying legend for intersection, delay, zenith, and transit markers.

Control Buttons:

• Intersection Track: Toggle the display of intersection (ZA and delay) tracks or individual ZA/delay tracks. Default is that intersection track is rendered. (keyboard Ctrl-i).
• ZA Track: Toggle the display of zenith angle track. Default off. (keyboard Ctrl-z).
• Delay Track: Toggle the display of delay range track. Default off. (keyboard Ctrl-d).
• Pointing Track: If telescope pointing range calculations are included in the input stream, toggles the display of pointing range track. Default on. (keyboard Ctrl-p).
• XEphem: save catalog in XEphem format (keyboard Alt-x).
• UT Offset: UT offset display indicator/editor. User can enter UT offset for rendering (keyboard Return activates). Format for the UT offset input is a colon-delimited UT time, as in "02:31".
• Baseline: Simple baseline display indicator/editor. User can enter baseline designation for rendering (keyboard Return activates).
• Current UT/LST: Toggle the display of a red vertical line indicating the current UT/LST. Intersection of the (red) current UT/LST line and the (green) zenith and (blue) delay constraint lines indicates the target satisfies all interferometer observational constraints. Toggling in three-phase: off, line only, and line with UT and LST annotations. Default off. (keyboard Ctrl-u).
• Sunrise/Sunset: Toggle the display of blue vertical lines indicating the local sunset and sunrise times (_if_ this information is contained in the timing input). Because optical interferometers only observe at night... Toggle is three-phase: off, lines only, and lines with UT annotations. Default off. (keyboard Ctrl-s).
• Time Labels: Toggle the rendering of secondary time labels (LST and local time). Toggling is four-phase: off, LST, local time, and UT. Default LST. (keyboard Ctrl-t).
• Clusters: Toggle the rendering of cluster transitions indicated in the input schedule (per the format described above). Toggling is three-phase: off, line only, and line with UT time annotation. Default off. (keyboard Ctrl-c).
• Calibrators: Toggle the rendering of objects designated as calibrators. Note that calibrators are rendered in muted colors to aid their identification. Equivalent to the Calibrator option in the Target menu above. (keyboard Alt-c).
• Moon: Toggle the rendering of the moon on and off. Default off (keyboard Ctrl-m).
• Print: Print the display canvas to a PostScript, pdf, gif, jpeg, or file or printer. Equivalent to the Print option in the File menu above. (keyboard Alt-p).
• Close: Close the GUI. Equivalent to the Quit option in the File menu above. Vaya con Dios. (keyboard Alt-q)

Keyboard Shortcuts

Where practical we have bound menu items with Alt keys, and control buttons with Ctrl keys. Complete list of keyboard shortcuts:

• Alt-r – Recompute timings
• Alt-o – Open schedule file
• Alt-O – Open catalog file through timing
• Alt-v – View input
• Alt-u – Route to uvTool
• Alt-x – save catalog in XEphem format
• Alt-x – write catalog to XEphem db FIFO
• Alt-p – Print
• Alt-q – Quit
• Alt-t – Select Targets
• Alt-c – Toggle Calibrators
• Alt-a – All objects
• Alt-i – Invert selection
• Alt-n – No targets
• Alt-h – Display tGui help
• Ctrl-i – Toggle intersection track
• Ctrl-z – Toggle zenith angle track
• Ctrl-d – Toggle delay track
• Ctrl-p – Toggle pointing track
• Ctrl-u – Toggle current UT display
• Ctrl-s – Toggle sunset/sunrise display
• Ctrl-t – Toggle time labels
• Ctrl-c – Toggle cluster display
• Ctrl-m – Toggle moon display
• Return – Closes text displays (view input, help)

Customizing

A number of customizations of the tGui display are possible. The perl module tGuiAttributes.pm (in getCal-2.10.4/src/gui/tGui/modules) contains all the tGui customization parameters:

     
     $tGuiCopyright = "Copyright 1998 -- 2005 CIT";
     
     ## Define the colors in the tGui display
     $intersectionColor = "DarkSlateGray";
     $zaColor = "green4";
     $delayColor = "blue";
     $transitColor = "red";
     $currentUTColor = "red3";
     $sunColor = "MediumBlue";
     $clusterColor = "red";
     $moonColor = "green4";
     
     $pointingColor = "OrangeRed";
     $pointingThickness = 3;
     
     ## Define tGui's canvas size
     $tGuiXCanvasSize = 700;
     $tGuiYCanvasSize = 300;
     $tGuiDisplayHours = 18.0;
     
     ## Max Items in the target menu(s)
     $targMenuItems = 25;
     
     

3.17 ocGui

ocGui – Graphical User Interface visualization of target annual accessibility

• Description
• Command-Line Options
• Third-Party Software
• Menus
• Frames and Control Buttons
• Keyboard Shortcuts
• Customization

ocGui Description

ocGui is a simple Perl/Tk GUI application that renders the calendar target accessibility information output from obsCalendar in the form of a line graph (patterned after a Gant chart). It's purpose is to graphically inform the user about annual astronomical target accessibility.

Here's a screenshot of ocGui in action:

ocGui functions by reading and parsing the output of the getCal observing calendar program (obsCalendar), which looks like:

     # Observing calendar (obsCalendar v0.1dev) run at 2/24/2002 UTC, day 2002055
      for timings in 2002 UTC
     # Using Palomar Location (long: -116:51:48   lat: +33:21:24)
     # Using 2.0 hour transit offsets in accessibilty calculations
     #
     ## HD 40084 -- G5III Binary 219 d period
     # Simbad Search HD 40084: Type: Star  G5III V=5.917
     # HDC40084 05 59 21.780  +49 55 28.344  is near transit at sunrise on 10/5/2002 (2002278) target
     # HDC40084 05 59 21.780  +49 55 28.344  is 2.0 hours pre-transit at sunrise on 9/10/2002 (2002253)
     # HDC40084 05 59 21.780  +49 55 28.344  is near transit at midnight on 12/18/2002 (2002352)
     # HDC40084 05 59 21.780  +49 55 28.344  is near transit at sunset on 3/8/2002 (2002067)
     # HDC40084 05 59 21.780  +49 55 28.344  is 2.0 hours post-transit at sunset on 4/3/2002 (2002093)
     HDC40084 05 59 21.780 +49 55 28.344 -0.007 -0.003 5.9 3.8 G5III 0.0 xxx   xxx  trg

Like the rest of the getCal architecture, the idea with the functional decomposition is the obsCalendar program has utility outside of just gui functions. ocGui accepts input on stdin:

     obsCalendar < my.schedule | ocGui

or

     cat my.schedule | obsCalendar | ocGui

or if the schedule already contains calendar annotations just

     ocGui < my.schedule

or ocGui will accept a filename as a single command-line argument:

     ocGui my.schedule.with.annotations

or even the maximally explicit:

     ocGui -filename my.schedule.with.annotations

ocGui renders the accessibility calculations as a graph with time/date on the horizontal axis, and with horizontal lines indicating target annual accessibility for the set of input objects. This view is modeled after a conventional scheduling Gant chart, and was the original idea of Gerard van Belle in the context of the companion tGui application (thanks GvB!).

ocGui can make PostScript of the current timing display, shipping the output directly to a PostScript-capable printer or save the output to a PostScript file. pdf, gif, jpg, and png file formats are also supported.

ocGui also provides a Simbad menu used to spawn Simbad queries on targets contained in the input stream. By default these queries are executed in an external web browser (set via the runtime parameter GC_BROWSER). If an external browser is unavailable, the query results will be displayed in a pop-up text window. (Note: the remote access can be slow.)

If you don't like my sense of aesthetics you can alter the appearance of ocGui by editing the ocGui attribute file (ocGuiAttributes.pm, a perl module file) in the modules subdirectory. There you can play with colors, sizes, menu parameters, and the like.

ocGui takes command-line options, and can generate hardcopy (PostScript, pdf, gif, jpg, png) in batch mode. Command-line options are necessary to support the batch-mode hardcopy creation, but are potentially useful to the interactive user on startup as well (see below). Hardcopy options beyond PostScript require third-party support software – again see options below.

ocGui can recompute (i.e. drive the recomputation through obsCalendar) the calendar for the input catalog (or even read a whole new catalog through obsCalendar). The default obsCalendar argument is adaptive, reflecting the obsCalendar options contained in the input – this makes it less labor-intensive to make small changes to the calendar computations.

As of getCal-2.6beta2, ocGui has popup balloon help messages for many of its controls and features.

Command-line Options

ocGui accepts the following command-line options:

• -help: generate a short help message and exit.
• -version: generate a short version message and exit.
• -stdin: force reading of timing input from stdin – no arguments when used.
• -filename arg: force reading of timing input from a particular file – desired filename argument when used.
• -calibrators: select whether or not to render objects designated as calibrators - default no, no argument when used. Note that calibrators are rendered in muted colors to aid their identification.
• -ps|postscript|PostScript|hc: direct batch-mode (i.e. ocGui exits after) creation of a PostScript timing graph – output to timing.ps. Default no, no argument when used.
• -pdf: direct batch-mode creation of a pdf timing graph – output to timing.pdf. Default no, no argument when used.
• -gif: direct batch-mode creation of a gif timing graph – output to timing.gif. Default no, no argument when used.
• -jpg: direct batch-mode creation of a jpg timing graph – output to timing.jpg. Default no, no argument when used.
• -png: direct batch-mode creation of a png timing graph – output to timing.png. Default no, no argument when used.

Third-Party Software

In addition to the Perl/Tk package, ocGui uses the following third-party software:

• To generate gif, jpg, and png, ocGui uses utilities from the netpbm package, namely pstopnm, pnmflib, ppmtogif, ppmtojpg, and pnmtopng. See http://netpbm.sourceforge.net/
• To generate pdf, ocGui uses ps2pdf, the ps to pdf translator function from ghostscript. See http://www.cs.wisc.edu/~ghost/.
• tGui can interface to the excellent third-party sky visualization software XEphem

Menu Description

Menus:

• File (general program controls):
  • Recompute calendar... – Recompute & re-render accessibility for the current input object set (keyboard Alt-r). This option opens a window where the user can compose the appropriate obsCalendar invocation (see the obsCalendar). Default obsCalendar argument reflects timing settings of input.
  • Open... – Open new calendar file (keyboard Alt-o). This option opens a file selector window.
  • Open Through obsCalendar... – Open new calendar file and recompute calendar. This option opens a file selector window followed by a obsCalendar invocation composition window (see the obsCalendar documentation).
  • View Input – View the input information (calendar) into ocGui in a text window (keyboard Alt-v). Allows calendar save.
  • tGui – Route the input information into tGui (keyboard Alt-t).
  • XEphem Catalog – translate the working catalog into an XEphem catalog via xeConvert, and save the output (keyboard Alt-x).
  • XEphem FIFO – translate the working catalog into an XEphem catalog via xeConvert, and write the output to the XEphem database FIFO specified in GC_XEPHEM_FIFO (keyboard Alt-X).
  • Print – Print the display canvas to a PostScript, pdf, gif, jpeg, or png file or printer (keyboard Alt-p). Opens dialog box.
  • Quit – Go find something else to do (keyboard Alt-q).
• Target (object rendering controls):
  • Targets – Render only objects designated as targets (default) (keyboard Alt-t).
  • Calibrators – Toggle the rendering of objects designated as calibrators (keyboard Alt-c).
  • All – Render all input objects (keyboard Alt-a).
  • Invert – Toggle rendering of all objects (keyboard Alt-i).
  • None – Render no objects (keyboard Alt-n).
  • xxx – Toggle rendering for an individual object (checkbox indicates current status).
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.
• Simbad (Simbad query controls):
  • Targets – Query Simbad on all objects designated as targets.
  • Calibrators – Query Simbad on all objects designated as calibrators.
  • All – Query Simbad on all objects.
  • xxx – Query Simbad on individual objects
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.

  [For all – if external browser is accessible through runtime parameter GC_BROWSER, queries will be executed in the browser context. If not, queries are executed and minimal information is returned in a text window.]

• Help (view available help):
  • ocGui help – View this (lame-o) help file.
  • obsCalendar help – View obsCalendar help file.
  • getCal version – getCal version statement
  • getCal copyright – getCal copyright statement

Note all menus are detachable/tear-off

ocGui Frames and Control Buttons

Frames:

• Preamble Frame: Scrollable read-only text frame that displays some pertinent information (e.g. date, hour angle offsets) extracted from the preamble of the obsCalendar input.
• Current Time Frame: Displays (approximate) current date, year day, and universal time (UTC).
• Display Canvas: Scrollable display area for the target accessibility line graph. The graph displays date on the horizontal axis, and multiple objects on the vertical axis. By the default settings, for each target transit dates for local sunrise, midnight, and sunset are rendered with a green triangle, blue diamond, and (inverted) red triangle respectively. The computed accessibility is rendered with a gray horizontal line. A demarcation indicating the current date.year day can be displayed (see below).
• Legend Canvas: Simple canvas displaying legend for accessibility and transit markers.

Control Buttons:

• Current Date: Toggle the display of a red vertical line indicating the current date/year day. Intersection of the this current date line and the (gray) accessibility lines indicates the target satisfies accessibility criteria. Default off. (keyboard Ctrl-d).
• Year Day: Toggle the rendering of year day labels. Default off. (keyboard Ctrl-y).
• Calibrators: Toggle the rendering of objects designated as calibrators. Note that calibrators are rendered in muted colors to aid their identification. Equivalent to the Calibrator option in the Target menu above. (keyboard Alt-c).
• Tonight: Generate and display a description of observing conditions (JD and LST at 0 UT, local sunrise/sunset, moonrise/moonset/moon illumination) for tonight using the tonight alias for the timing program (timing -noTargets). (keyboard Ctrl-t).
• XEphem: save catalog in XEphem format (keyboard Alt-x).
• Print: Print the display canvas to a PostScript, pdf, gif, jpeg, or file or printer. Equivalent to the Print option in the File menu above. (keyboard Alt-p).
• Close: Close the GUI. Equivalent to the Quit option in the File menu above. Vaya con Dios. (keyboard Alt-q)

Keyboard Shortcuts

Where possible we have bound menu items with Alt keys, and control buttons with Ctrl keys. Complete list of keyboard shortcuts:

• Alt-r – Recompute calendar
• Alt-o – Open schedule file
• Alt-O – Open catalog file through obsCalendar
• Alt-v – View input
• Alt-u – Route to tGui
• Alt-x – save catalog in XEphem format
• Alt-x – write catalog to XEphem db FIFO
• Alt-p – Print
• Alt-q – Quit
• Alt-t – Select Targets
• Alt-c – Toggle Calibrators
• Alt-a – All objects
• Alt-i – Invert selection
• Alt-n – No targets
• Alt-h – Display ocGui help
• Ctrl-d – Toggle current date/year day
• Ctrl-y – Toggle year day labels
• Ctrl-t – Generate/display tonight's observing conditions
• Return – Closes text displays (view input, help)

Customizing

A number of customizations of the ocGui display are possible. The perl module ocGuiAttributes.pm (in getCal-2.10.4/src/gui/ocGui/modules) contains all the ocGui customization parameters:

     
     $ocGuiVersion = "0.2dev";
     $ocGuiCopyright = "Copyright 1998 -- 2005 CIT";
     
     ## Define the colors in the oCalGui display
     $intersectionColor = "DarkSlateGray";
     $zaColor = "green4";
     $delayColor = "blue";
     $currentDayColor = "red3";
     $sunColor = "MediumBlue";
     $obscureColor = "black";
     $clusterColor = "red";
     $transitColor = "blue";
     $sunriseColor = "green3";
     $sunsetColor = "red";
     
     
     ## Define oCalGui's canvas size
     $ocGuiXCanvasSize = 700;
     $ocGuiYCanvasSize = 300;
     
     ## Max Items in the target menu(s)
     $targMenuItems = 25;
     

3.18 uvTool

uvTool – render u-v plane coverage

• uvTool Description:
• Command-Line Options:
• Third-Party Software:
• uvTool GUI Menus:
• Frames and Buttons:
• Keyboard Shortcuts:
• uvTool Customization:

uvTool Description

uvTool is a Perl/Tk graphical user interface (GUI) application that renders a line graph of u-v track and instantaneous u-v point information. uvTool runs both in and out of the context of the getCal planning tool suite. It ingests input from stdin (in particular the timing annotation produced by the getCal timing module), and computes its u-v renderings based (solely) on those inputs. uvTool produces no outputs other than the GUI window and PostScript hardcopy of the line graph.

Here's a screenshot of uvTool in action:

uvTool takes its input either from stdin:

     uvTool < list.with.annotations.in

or

     cat list.without.annotations.in | timing | uvTool

or

     timing < list.without.annotations.in | uvTool

or uvTool will read a filename given as a single argument on the command-line:

     uvTool list.with.annotations

The input list format looks like (the output from timing):

     # Timing summary run at 7/16/2000, day 00198
     #  for timings on 7/16/2000, day 00198
     # Using Palomar Location (long, lat: -116.8633, 33.3567)
     # Using PTI_NS Baseline (ENUBias: -37.116352, -103.264746, 3.319338, -12.915245)
     # Using PTI_NW Baseline (ENUBias: -81.685124, -28.214086, 3.105647, 0.031416)
     # The JD at 0 hr UT is 2451741.5
     # The LST at 0 hr UT is 11:49:06.5
     # Approximate UT sunset -- sunrise times: 03:20:13 -- 12:26:48
     # Using 35 deg zenith angle constraint
     # Using 38.3 m delay constraint
     ...
     # Simbad Search HD 234677: Type: Variable of BY Dra type  K6Ve V=8.07
     # HDC234677 18 33 55.773  +51 43 08.905  transits at 06:44:49 UT, zenAng 18.4 deg target
     # HDC234677 is within zenith angle range from 03:58:49 to 09:30:49 UT
     # HDC234677 is within delay range from 07:33:09 to 10:11:57 UT for PTI_NS
     # HDC234677 is within delay range from 04:18:23 to 19:31:16 UT for PTI_NW
     HDC234677 18 33 55.773 +51 43 08.905  0.301 -0.325 8.2 5.0 K7Vvar  xxx   xxx  trg

uvTool uses information in the timing preamble to define interferometer location and baseline 3-vectors, and individual target annotations for timing constraints. The input target list may contain an arbitrary number of targets, and an arbitrary number of interferometer baseline definitions. (However there are practical limitations to list sizes because uvTool constructs both target and baseline selection menus.)

uvTool renders u-v tracks for a single object as observed by an arbitrary number of interferometer baselines, with transit (and hour angle) markers indicating local meridian passage (and offsets thereof). The rendered target and baselines are user-selected with selection menus at the top of the uvTool window. The rendered tracks are constrained by target accessibility criteria as computed by the getCal timing module. Note that uvTool renders the u-v tracks as they would appear on the sky – increasing East is to the left, and increasing North is up. A small (and hopefully unobtrusive) indicator is given in the upper left to remind the viewer of this orientation convention.

In addition to rendering simple u-v tracks constrained by zenith angle, uvTool separately renders those tracks constrained by delay line range, a new concept to those with a heterodyne interferometry background. Direct (homodyne) interferometry requires the use of delay lines for pathlength equilibration, and a necessary condition for observation is that the target be within the delay constraints imposed by the interferometer. Both zenith angle and delay coverage are computed by the getCal timing module and are ingested by uvTool in the form of timing annotation; see the timing documentation for more details. By default (and popular demand) uvTool renders the u-v tracks delimited by the intersection of delay and zenith angle constraints, but the individual constraints can rendered separately (my personal preference) either by toggling the Intersection Track button, or by individually toggling the ZA Track and Delay Track buttons (see below). Intersection, zenith angle, and delay-limited tracks can all be toggled off and on. As per the convention, rendered u-v tracks are shown in axially symmetric pairs, which follows from the fact that sky brightness distributions are real – see any standard interferometry textbook (e.g. Thompson, Moran, and Swenson) for a discussion. To provide context, what we have termed "ghost" tracks – the baseline projection for a full 24-h earth rotation with no accessibility constraints – are also available

Timing markers indicating transit and integral hour angle values on the tracks can be toggled by the Hour Angle control button (see below). These timing markers are three-phase (off, transit-only – default, markers between +/- 3 hrs of transit). Similarly, fringe spacing circles (indicating the angular scales measured by the interferometer) can be toggled by the Fringe Spacing control button (see below). These fringe spacing circles are four-phase (off – default, min fringe spacing, max fringe spacing, 2nd max fringe spacing).

Like it's tGui sibling, uvTool can render the instantaneous u-v point for each selected baseline (see the Current UT/LST control button below). This gives uvTool real-time utility during observing. Further, I often find it useful to have both uvTool and tGui running; they provide quasi-orthogonal information that I find informative in real-time applications. So I added an option (in the File menu) to route the input to uvTool into tGui (designed to save you a little work over a separate command-line invocation).

uvTool can make PostScript of the current timing display, shipping the output directly to a PostScript-capable printer or save the output to a PostScript file. pdf, gif, jpg, and png file formats are also supported.

uvTool also provides a Simbad menu used to spawn Simbad queries on targets contained in the input stream. By default these queries are executed in an external web browser (set via the runtime parameter GC_BROWSER). If an external browser is unavailable, the query results will be displayed in a pop-up text window. (Note: the remote access can be slow.)

If you don't like my sense of aesthetics you can alter the appearance of uvTool by editing the uvTool attribute file (uvToolAttributes.pm, a perl module file) in the modules subdirectory.

uvTool now takes command-line options, and can generate hardcopy (PostScript, pdf, gif, jpg, png) in batch mode, and also interactively. Command-line options are necessary to support the batch-mode hardcopy creation, but are potentially useful on startup to the interactive user as well (see below). Hardcopy options beyond PostScript require third-party support software – again see options below. Interactive hardcopy creation is supported by a dedicated popup dialog box triggered from the print command/button (see below).

uvTool can recompute (i.e. drive the recomputation through timing) of the timings on the input catalog (or even read a whole new catalog through timing). The default timing argument is adaptive, reflecting the timing options contained in the input – this makes it less labor-intensive to make small changes to the timing computations.

As of getCal-2.6beta2, uvTool has popup balloon help messages for many of its controls and features.

Command-Line Options

• -help: generate a short help message and exit.
• -version: generate a short version message and exit.
• -stdin: force reading of timing input from stdin – no arguments when used.
• -filename arg: force reading of timing input from a particular file – desired filename argument when used.
• -intersectionTrack [arg]: select whether or not to render zenith/delay intersection representation – default on, optional integer argument when used. Integer arg can have the following values: 0 – no intersection rendering, 1 – intersection rendering.
• -zenithTrack [arg]: select whether or not to render zenith angle-limited representation – default off, optional integer argument when used. Integer arg can have the following values: 0 – no zenith angle rendering, 1 – zenith angle rendering.
• -delayTrack [arg]: select whether or not to render delay range-limited representation – default off, optional integer argument when used. Integer arg can have the following values: 0 – no delay range rendering, 1 – delay range rendering.
• -hourAngle|haMarks [arg]: selects rendering of hour angle marks on the u-v tracks, default transit markers, optional integer argument when used. Integer arg can have the following values: 0 – no hour angle marks, 1 – render transit markers (default), 2 – add hour angle markers within three hours of transit.
• -anglesOn [arg]: selects rendering of fringe spacing markers – default off, optional integer argument when used. Integer arg can have the following values: 0 – no rendering, 1 – minimum fringe spacing marker, 2 – maximum fringe spacing marker, 3 – third fringe spacing marker.
• -currentTime|utOn: select display of current time/UTC/LST marker. Default off – no argument when used.
• -targetID arg: select display of particular target on invocation, string argument required when used. Default render first target in input stream. If arg is not found in the input stream, uvTool falls back to the default condition (first desig in stream).
• -wavelength arg: select operating wavelength (um), float argument required when used. Defaults to 2.2 um (IR K-band).
• -ps|postscript|PostScript|hc: direct batch-mode (i.e. uvTool exits after) creation of a PostScript timing graph – output to uvPlot.ps. Default no, no argument when used.
• -pdf: direct batch-mode creation of a pdf timing graph – output to uvPlot.pdf. Default no, no argument when used.
• -gif: direct batch-mode creation of a gif timing graph – output to uvPlot.gif. Default no, no argument when used.
• -jpg: direct batch-mode creation of a jpg timing graph – output to uvPlot.jpg. Default no, no argument when used.
• -png: direct batch-mode creation of a png timing graph – output to uvPlot.png. Default no, no argument when used.

Third-Party Software

In addition to the Perl/Tk package, tGui uses the following third-party software:

- To generate gif, jpg, and png, uvTool uses utilities from the netpbm package, namely pstopnm, pnmflib, ppmtogif, ppmtojpg, and pnmtopng. See http://netpbm.sourceforge.net/

- To generate pdf, uvTool uses ps2pdf, the ps to pdf translator function from ghostscript. See http://www.cs.wisc.edu/~ghost/.

uvTool GUI Menus

Menus:

• File (general program controls):
  • Recompute timings... – Recompute & re-render timings for the current input object set (keyboard Alt-r). This option opens a window where the user can compose the appropriate timing invocation (see the timing documentation). Default timing argument reflects timing settings of input.
  • Open... – Open new schedule file (Keyboard Alt-o)
  • Open Through timing... – Open new schedule file and recompute timings. This option opens a file selector window followed by a timing invocation composition window (see the timing documentation).
  • View Input – View the input information (schedule) input uvTool in a text window (keyboard Alt-v). Allows schedule save.
  • tGui – Route the information (schedule) input into tGui (see the tGui documentation) (keyboard Alt-t).
  • XEphem Catalog – translate the working catalog into an XEphem catalog via xeConvert, and save the output (keyboard Alt-x).
  • XEphem FIFO – translate the working catalog into an XEphem catalog via xeConvert, and write the output to the XEphem database FIFO specified in GC_XEPHEM_FIFO (keyboard Alt-X).
  • Print – Print the display canvas to a PostScript, pdf, gif, jpeg, or png file or printer (keyboard Alt-p). Opens dialog box.
  • Quit – Go find something else to do (keyboard Alt-q).
• Target:
  • xxx – Render an individual object (mutually exclusive – radiobox indicates current selection).
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.
• Baseline:
  • All – Render all baselines (keyboard Alt-a).
  • xxx – Render delay constraints for baseline designation xxx (inclusive – checkboxes indicate current selection).
• Simbad (Simbad query controls):
  • Targets – Query Simbad on all objects designated as targets.
  • Calibrators – Query Simbad on all objects designated as calibrators.
  • All – Query Simbad on all objects.
  • xxx – Query Simbad on individual objects
  • Target List N – For short target sets the targets are listed individually as described above; for longer target sets they are broken into a set of sublists in cascading menus.

  [For all – if external browser is accessible through runtime parameter GC_BROWSER, queries will be executed in the browser context. If not, queries are executed and minimal information is returned in a text window.]

• Help:
  • uvTool help – View this (lame-o) help file (keyboard Alt-h).
  • timing help – View the getCal timing help file.
  • getCal version – getCal version statement
  • getCal copyright – getCal copyright statement
• Plot scale:
  • Mlambda – u-v axes in Mlambda (default).
  • Klambda – u-v axes in Klambda.
• Wavelength – define operating wavelength (um). Defaults to 2.2 um (IR K-band). Return in this entry window or rescale triggers rescaling of plot.

Note all menus are detachable/tear-off.

Frames and Buttons

Frames:

• Preamble Frame: Scrollable read-only text frame that displays some pertinent information (e.g. date, location, baselines, constraint settings) extracted from the preamble of the timing input.
• Current Time Frame: Displays (approximate) current UT, LST, and observatory local time (if available).
• Display Canvas: Scrollable display area for the target u-v track line graph. The graph displays tracks in u-v (spatial frequency) space. For each track (pair) the local transit is rendered with a red circle, the zenith angle accessibility track is rendered with a green line, and the delay line accessibility is rendered by a blue line. Indicators for instantaneous u-v at the current UT/LST/HA can be displayed (see below).
• Legend Canvas: Simple canvas displaying legend for delay, zenith, and transit markers.

Control Buttons:

• Intersection Track: Toggle the display of the u-v track delimited by the intersection of zenith angle and delay restrictions – default on. User can select between intersection and separate zenith angle and delay delimited tracks (keyboard Ctrl-i).
• ZA Track: Toggle the display of the u-v track delimited by the input zenith angle restriction. Default off. Selection supercedes the rendering of intersection-delimited tracks (keyboard Crtl-z).
• Delay Track: Toggle the display of the u-v track delimited by delay line range restriction. Default off. Selection supercedes the rendering of intersection-delimited tracks (keyboard Ctrl-d).
• Ghost Track: Toggle the display of complete u-v track with no accessibility constraints or delimiters. Default off. (keyboard Ctrl-g).
• Simbad: Spawn external-browser Simbad query on the current display object.
• Current UT/LST: Toggle the display of a red marker indicating instantaneous u-v point on all rendered baseline at the current UT/LST/HA. Default off. (keyboard Ctrl-u).
• Hour Angle: Toggle the three-phase display of red markers indicating hour angle marks on the tracks at transit and between +/- 3 hours. Default transit marker on. (keyboard Ctrl-h).
• Fringe Spacing: Toggle the four-phase display of red, blue, and green circles indicating the fringe spacings at illustrative spatial frequencies (for those of us who can't do the reciprocal in our head). Default off. (keyboard Ctrl-f).
• Print: Print the display canvas to a PostScript, pdf, gif, jpeg, or file or printer. Equivalent to the Print option in the File menu above. (keyboard Alt-p).
• Close: Vaya con Dios, amigo. Equivalent to file menu quit command (keyboard Alt-q).

Keyboard Shortcuts

Where possible we have bound menu items with Alt keys, and control buttons with Ctrl keys. Complete list of keyboard shortcuts:

• Alt-r – Recompute timings
• Alt-o – Open schedule file
• Alt-O – Open catalog file through timing
• Alt-v – View input
• Alt-t – Route to tGui
• Alt-x – save catalog in XEphem format
• Alt-x – write catalog to XEphem db FIFO
• Alt-p – Print
• Alt-q – Quit
• Alt-a – All baselines
• Alt-h – Display uvTool help
• Ctrl-i – Toggle intersection track
• Ctrl-z – Toggle zenith angle track
• Ctrl-d – Toggle delay track
• Ctrl-g – Toggle ghost track
• Ctrl-u – Toggle current UT display
• Ctrl-h – Toggle hour angle markers
• Ctrl-f – Toggle fringe spacing markers
• Return – Closes text displays (view input, help)

Customizing

A number of customizations of the uvTool display are possible. The perl module uvToolAttributes.pm (in getCal-2.10.4/src/gui/uvTool/modules) contains all the uvTool customization parameters:

     
     $uvToolVersion = "0.9dev";
     $uvToolCopyright = "Copyright 1999 -- 2005 CIT";
     
     ## Define the colors in the uvTool display
     $intersectionColor = "DarkSlateGray";
     $zaColor = "green4";
     $delayColor = "blue";
     $ghostColor = "black";
     $transitColor = "red";
     $currentUTColor = "red3";
     $obscureColor = "black";
     
     $maxFSpaceColor = "firebrick3";
     $medFSpaceColor = "blue2";
     $minFSpaceColor = "ForestGreen";
     
     
     ## Define uvTool's canvas size
     $XCanvasSize = 450;
     $YCanvasSize = 450;
     
     
     ## Max target menu items
     $targMenuItems = 25;
     

3.19 makeHipIdx

makeHipIdx is a utility to create a set of index files for the Hipparcos catalog, to speed searches of the catalog. getCal will use these indexes, if available, to quickly locate individual records within the catalog based on HD, HIP or DM identifiers.

makeHipIdx locates the main Hipparcos catalog file hip_main.dat in the directory indicated by GC_HIPPARCOS_PATH, and stores the created index files in the directory indicated by GC_HIPPARCOS_IDX_PATH. Three index files are generated, they are idx_hd.db, idx_hip.db, and idx_dm.db. Any existing index files in the destination directory are overwritten.

Usage

             makeHipIdx

4 Release Notes

4.1 Release Notes for getCal-2.10.4

Fixes and changes to existing functionality

• Fixed problem where HD target designations specified with --targetName were not being rewritten with the HDC prefix when --identHDC was used.
• Updated default delay ranges for KI nulling baselines.
• Removed obsolete utility nullDepth, the functionality has been incorporated into timing.
• Moved configuration parameters relating to timing from timingAttributes.pm into main getCal config file, and made them accessible for user override via that mechanism. Affected parameters include defaults for zenith angle limit, twilight angle, and defaults involved in nulldepth calculations. File timingAttributes.pm is no longer used.
• Updated documentation of runtime configuration parameters.

4.2 Release Notes for getCal-2.10.3

Fixes and changes to existing functionality

• Fixed problem with SIMBAD lookup failures for positional targets (specified by --searchRA/--searchDec) when the --fbol option was used. Positional targets are given the designation "POSTARGET", but this designation is unknown to SIMBAD and was triggering the SIMBAD lookup failures.
• Merged functionality from nullDepth into timing, as a command-line option (timing --nullDepth). The nullDepth tool still exists, but is expected to be removed in a future release since it is more difficult to maintain it as a separate utility from timing.

4.3 Release Notes for getCal-2.10.2

New and Improved Features

• Added support for per-baseline delay ranges.
• Added --table option to output a table of predicted delay line positions vs time for each object and baseline.

Fixes and changes to existing functionality

• Updated Keck_Nulling location to better reflect actual delay limitations, improving accuracy of delay predictions.
• Fixed problem with SIMBAD lookups involving '+' in target's name. This bug was introduced in 2.10.
• Fixed problem with SIMBAD returning common name identifiers prefixed by 'NAME'. This bug was introduced in 2.10.
• Fixed problem in timing calculations of composite pointing/delay ranges, where some composite ranges were not being reported. This bug was introduced in 2.10.
• Changed reporting of delay intervals to exclude times when the object is below the local (0deg) horizon, reducing some output clutter.
• Added sidereal-to-solar time correction for delay and pointing predicts. Previously, reported delay/timing intervals did not take this into account. This bug has been around for a long time, but the effects of this correction are generally smaller than the 1-minute resolution of delay/pointing predicts reported by timing.
• getCal no longer aborts when a specified calibrator is not found. It now prints an error message, ignores the unknown calibrator and continues.
• Adjusted legend area of tGui printed plots to accommodate timing changes for multiple baselines with different delay range limits. For now, when a "Composite" baseline is printed, no delay constraint detail (text) appears in the page footer. This detail will appear as before when a single baseline is printed. More work is needed.
• Added button in gcGui to specify use of getCal's internal delay limit defaults. Previously gcGui always overrode these defaults with what was entered in the gcGui screen.

Known Issues

There is presently no way to specify (on the command line or in any of the getCal guis) a site configuration using multiple baselines with unique delay limits for individual baselines. This is reflected in the tGui tool, when selecting the "Recompute timings..." option. tGui attempts to compose a command line for timing having multiple -delayMin/-delayMax options, but timing only uses a single pair of delayMin/delayMax values. Currently the only way to create such a baseline configuration is by manually editing the interferometers definition file interferometers.pm located within the getCal source code.

4.4 Release Notes for getCal-2.10.1

New and Improved Features

• Added new L and L' photometry options, --Lband and --Lprime, respectively. These options produce model L/L' magnitude estimates as tagged fields on the output line (L=... or LPRIME=...) based on whatever K magnitude is selected. These output fields are implemented for "new" format output only.
• Added --minL and --maxL options to filter calibrators based on their L/L' magnitude. Note these options apply to both L and L' magnitudes, because in most all cases L and L' are very close. Filtering by L' independently of L is not supported.
• Added configuration file parameters for min/max N and L magnitude limits: GC_CAL_MINN, GC_CAL_MAXN, GC_CAL_MINL, GC_CAL_MAXL. These parameters have no hardcoded defaults, so no N/L limits are in effect unless set by the user in the configuration file, an environment variable, or command line option.

Fixes and changes to existing functionality

• Tightened up code in tGui/uvTool/ocGui that looks for timing annotations in their input, to help avoid mistaking user comments containing certain key phrases from being misinterpreted as timing annotations.
• uvTool now displays all available delay windows in the same way that tGui does, instead of displaying at most one.
• Output lines in "sky" format now use the lower case tag "b-v" for that field, was previously upper case "B-V".
• Added support for local caching of SIMBAD query results to make regression testing more reliable in finding actual bugs instead of output changes due to SIMBAD updates.
• Reworked some code that was unnecessarily truncating precision of magnitude values internally. In some cases this truncation was causing some objects with magnitudes at or near the ends of acceptable ranges to be included or excluded inappropriately.
• Information in footer of printed timing diagrams was not always showing delay information correctly when multiple baselines were used.

4.5 Release Notes for getCal-2.10

New and Improved Features

• Initial support for SIMBAD4. The CPAN module Astro::SIMBAD::Query, required for releases 2.8 and 2.9.* of getCal, is no longer used.
• The timing utility now reports composite delay and pointing windows whenever multiple baselines are selected.

Fixes and changes to existing functionality

• simbadInteractiveQuery has been replaced by simbadQuery. The new utility provides basic functionality only and is not a complete replacement, but this change was necessitated by the termination of SIMBAD3 service. In response to this change, it was decided to restructure the way in which information from Simbad is used and passed between modules within getCal. getCal now performs SIMBAD lookups using an internal module instead of using the utility, which is a small wrapper around the same module. The utility is retained in command form for general use, but it is no longer a key component of getCal.
• The fbolFormat utility no longer processes records returned by simbadInteractiveQuery. Instead, it now takes a list of object names on the command line, and retrieves photometry for those objects directly from Simbad and elsewhere. Most functionality in the fbolFormat utility has been moved to a library module. fbolFormat is now a small wrapper script around this module. getCal now uses that module directly as needed, but this utility is retained for general use. Some options which are no longer relevant have been removed.
• Updated existing KI baseline information, implemented new locations and baselines for KI nulling.
• Retrieval of 2MASS photometry for use by fbol is now done using a cone search around the object's position (according to SIMBAD). Previously, the 2MASS lookup was done by object name. Because 2MASS/IRSA uses a different name resolution engine than SIMBAD, the 2MASS/IRSA search would sometimes fail to return data for an object because the object name was unrecognized. This is now consistent with how getCal searches 2MASS for retrieval of K magnitude information.
• Fixed problem with retrieval and formatting of CIO photometry
• Fixed problems with calScript output when --simbad is used.
• Added support for a "delay offset" in interferometer baseline configuration (file interferometers.pm). This parameter indicates that the center of that baseline's delay range is offset from 0 by a certain amount. The length of the delay range remains the same for all baselines at a site, only the center of the delay range is shifted for the individual baseline. When an offset is used, this is noted in the preamble section of the output from timing.

4.6 Release Notes for getCal-2.9.6

Fixes and changes to existing functionality

• Implemented US daylight savings time changes effective in 2007.

4.7 Release Notes for getCal-2.9.5

Fixes and changes to existing functionality

• fixed skyFormat to remove warnings about undefined variables, and to deal with leading whitespace on comment lines

4.8 Release Notes for getCal-2.9.4

Fixes and changes to existing functionality

• Changed method for locating Perl modules, to behave properly when the program itself was referenced via a symlink.

4.9 Release Notes for getCal-2.9.3

Fixes and changes to existing functionality

• Changed behavior of --targetHD/--targetHIP/--targetDM search options. If one of these options is used and the Hipparcos catalog search fails for a given HD/HIP/DM designation, getCal will now fall back to doing a SIMBAD search by name for that designation. The previous behavior was to fail when the supplied designation was not found in Hipparcos.
• Removed warning message from gcConfig module, issued when no valid browser is found, changed simbadInteractiveQuery to check for valid browser before attempting to use it.
• The calculation of pointing range limits done by timing has been made more sensitive to detection of small pointing obstructions, particularly at high elevation angles.
• Fixed a bug that produced warnings when trying to draw pointing range for objects which are never in range.
• Minor improvements to appearance of range lines and transit marker in timing plots produced by tGui

4.10 Release Notes for getCal-2.9.2

Fixes and changes to existing functionality

• Fixed UT offset feature in tGui. Previously some charts were drawn incorrectly when the offset was nonzero.

4.11 Release Notes for getCal-2.9.1

Fixes and changes to existing functionality

• Fixed problem with gcGui causing it to not work with Tk prior to 804.027.
• Fixed problem with fbol postscript plot creation failing for objects having a '/' character present in their spectral type.

4.12 Release Notes for getCal-2.9

Fixes and changes to existing functionality

• Updated algorithm and tables for N magnitude estimation, now uses table of V-N (with some real values) instead of K-N (that was essentially just setting N=K).
• Updated bolometric correction estimation with more complete lookup tables for fewer lookup failures.
• Target names are no longer automatically rewritten in a preferred format (e.g. "altair" rewritten as "HD187642"). The new default is that whatever name is supplied will be used as the target designation in the output. Target renaming can be enabled by using the new --rename option.
• gcGui was ignoring some numeric input fields when a zero was entered.
• Precision changes. Magnitudes, DIAM and DIAMERR are now reported with a single digit after the decimal point.
• The calibrator selection algorithm implementation has been reworked. The internal programs calSelect, catScan and magsWarn are no longer needed and have been removed from getCal. If an earlier release of getCal was installed on your system, you should manually remove these obsolete utilities from the installation area.
• Fixed <= vs = comparison which affected magnitude comparisons. Tests are now inclusive. i.e., --minK=5.0 will now include calibrators with K magnitude of 5. Also removed some internal rounding that was affecting the resuls as well.
• The option for retrieval of 2MASS K magnitudes has been renamed to --K2Mass (from --2Mass), to eliminate conflict with the --2Mass option used by fbol.
• The option for retrieval of IRAS-based (N-band) magnitudes has been renamed to --NIRAS (from --IRAS).
• The option --NIRAS has been improved by increasing the search cone radius used in database searches and using increased precision in the positions used for the search. Both the 2MASS and IRAS search radii for position matching are now available as configuration file parameters: GC_2MASS_SEARCHRADIUS and GC_IRAS_SEARCHRADIUS.
• The conversion of IRAS 12micron flux to N band magnitude now includes a passband correction factor (see the IRASNmag subroutine in calCheck.pm).
• For "new" format, getCal will now output N=N? when --Nband requested but no N value available. For "old" (PTI) format, N? will be output as well. In 2.8, the field was missing.
• The irsaminer program now uses the HTTP_PROXY environment variable.
• The Hipparcos HD index file (introduced in 2.8) no longer needs to be writeable.

New and Improved Features

• N-band magnitude search criteria added: --minN=n and/or --maxN=n. Use implies --Nband.
• The new option --useMeasurement, used in conjunction with --K2Mass (K band) and/or --IRAS (N band), will cause the requested 2MASS/IRAS lookups to be performed before calibrator magnitude limits are evaluated. This can increase calibrator search time significantly, but may provide a more accurate calibrator list. By default, only the model K/N magnitudes are evaluated against the specified magnitude limits. Related to this, new configuration variables have been added to control a first pass comparison using model magnitudes as well as the threshold before warnings are issued. See the Run-Time Configuration section.
• --identHDC and --noIdentHDC can be used to override GC_IDENT_HDC configuration variable.
• --verbose enables additional magnitude comments such as computed model and results from 2Mass and IRSA. --quiet disables all comments. Default is to output Hipparcos warnings as comments.
• The timing utility will now report multiple delay range windows for an object on a baseline. Previously, at most one delay window was reported, even though a second one is sometimes available (i.e. when an object passes in and out of delay range more than one time per day).
• The timing utility will now compute when an object is within pointing range for each baseline of the selected site, when pointing limits have been defined for that baseline. This pointing information is now processed and displayed by tGui in addition to the existing zenith angle and delay range information it already displayed. This new pointing range display replaces the old "Obscured Track" feature of tGui. The appearance of some items displayed by tGui has been enhanced for greater visibility, especially the noticability of short gaps in zenith/delay/pointing range, and a highlighted transit marker in cases where an object is out of pointing range at transit.

Known Bugs

• The UV Tool plots have not been updated (as with tGui) to show multiple delay windows or pointing range limits.
• The XEphem output support has not been updated recently, it probably does not work as it should.
• The Keck "sky" output support has not been updated recently, it probably does not work as it should.

4.13 Release Notes for getCal-2.8

Fixes and changes to existing functionality

Among the issues which have been identified and corrected in this release:

• The internal error checking has been greatly expanded, including the enabling of additional perl error checking options. This has helped us uncover and fix many problems, both large and small. Many of these problems were silently present in earlier releases.
• Perl version 5.6.1 or later is now required to run getCal. This is necessary to support the additional error checking.
• This release requires several CPAN perl modules not required by previous releases. See the instructions on installing getCal for details, and instructions on how to obtain and install these prerequisites.
• Reworked algorithms for estimation of magnitudes (K and N), and estimation of linear and angular diameters. These algorithms are based on hard-coded lookup tables. Previously, spectral type and luminosity class were being used inconsistently by the various estimation algorithms. In certain cases, lookup failures caused erroneous estimates to be returned without any indication of failure. The table interpolation mechanism now treats spectral type and luminosity class more consistently, and properly handles lookup errors. The estimation algorithms are more careful to not propagate invalid estimates.
• Changed default prefix used for HD object designations. Prior to 2.8, getCal rewrote “HD” object identifiers with the prefix “HDC” by default. This is now optional behavior, controlled by the GC_IDENT_HDC configuration file parameter and environment variable. (The HDC notation is used by the PTI sequencer but is not generally recognized, so this PTI-specific behavior is now optional.)
• The default output format for getCal has changed. getCal now defaults to the “new” (Keck) format by default instead of the “old” (PTI) format. The default value for this parameter can now be set on a site-wide basis in the getCal config file, by the user with the GC_DEFAULT_FORMAT environment variable, or on the command line using the --format option.
• When using the “new” output format, the PLX output tag is now generated only when explicitly requested.
• A warning message is now produced when the N magnitude lookup differs from the internal model value by more than a set amount (currently 0.4mag).
• IRSA lookups for object in the 2Mass and IRAS catalogs previously failed when IRSA's notion of the object's location was significantly different than the position used by getCal (from SIMBAD or Hipparcos). IRSA queries for 2Mass and IRAS information are now done by object position rather than by object name.
• Fixed problem in calSelect which produced a crash for objects having parallax=0.
• For SIMBAD-recognized targets having no usable Hipparcos identifier, target information (magnitudes, proper motion) is now taken from SIMBAD, with an appropriate warning that this is happening.
• The -searchRA option did not work properly when using decimal degrees.
• The csAdHoc command failed with a cryptic error messages when no Hipparcos record could be found for a specified target.
• Probably many others not mentioned here...

New and Improved Features

• The lynx utility is no longer required to run getCal. The SIMBAD client code has been replaced with the Astro::SIMBAD Perl module.
• Updated and reorganized documentation.
• Cleaned up option processing, more complete support for standard options. Support for --option=value notation for specifying options.
• A new option --debug is now supported in most getCal tools, and will produce (often voluminous) messages to aid developers in debugging.
• getCal has a new option, --cal, that allows the user to specify calibrator stars, bypassing the normal calibrator search mechanism.
• More error checking during the build process. There is a new make check-long option in addition to the traditional make check.
• Simplified configuration of run-time environment. It is no longer necessary to set getCal's run-time configuration through environment variables. getCal now has a configuration file, getCal.conf. You can still use environment variables, but they are no longer required. The new utility gcConf will display a detailed listing what getCal is using for all environment and configuration file parameters, including the origin of each (environment variable, config file, build-time configuration, etc).
• getCal now has the ability to create and use a set of index files to speed searching of the Hipparcos catalog. The indexes are created by the new utility makeHipIdx.
• getCal now supports the optional use of an HTTP proxy server to speed up SIMBAD and IRSA queries, by setting the HTTP_PROXY environment variable to the URL of the proxy server.
• Improved interface to IRSA catalogs. There is a new command-line tool, irsaminer, for querying IRSA catalogs. The more limited 2MassQuery and IRASQuery are now deprecated and may be removed in a future release. The new tool is less sensitive to configuration changes of the IRSA server. Previously getCal knew too much about IRSA internals which caused problems when the IRSA configuration changed.

Known Bugs

• Support for the Xephem utility has not been maintained during the development of this release. We expect to re-verify this functionality in a future release.
• When doing SIMBAD lookups, getCal cannot distinguish between failure to contact the SIMBAD server, and a lookup failure returned by the SIMBAD server.
• The addition of more extensive internal regression tests has exposed some differences in numeric output across CPU types. In other words, the numbers come out slightly different on a Mac or a Sun than they do on a PC running linux. These differences are not fully understood at this time, but appear to be due to differences in floating point formats and internal precision between processor types. However, some of these differences are more prominent than they probably should be. fbol is one area where problems have been known to occur, but they also sometimes show up in getCal itself. If the regression tests (make check-long) indicate errors, you should compare the expected output with the actual test output and identify what differences exist. If the discrepancies are in the form of small differences in numeric values, then it could be that this is the cause. We are still investigating how to remove this platform sensitivity.
• The calibrator selection algorithm always checks K magnitude limits for candidate calibrators using the model K magnitude produced by the internal estimation algorithm, even when the -2Mass option has been specified.
• Several tools such as timing that read getCal output are not very tolerant of formatting errors in their input, especially in cases users have edited the input files manually. Such formatting errors typically cause warnings from the internalLine.pm module about references to undefined or uninitialized values. A more robust parser is a project for the future.

5 Acknowledgments

getCal was originally written and maintained for many years by Andy Boden, who was motivated by the difficulty of manually composing observing schedules for PTI.

getCal has benefited over the years from the contributions of many people that we want to acknowledge (and thank) here...

- Andy stole the original idea of scanning the (then new) Hipparcos catalog for calibration sources from his long-time colleague and friend Gerard van Belle (GvB). In addition to being a user "not shy about providing feedback", Gerard also contributed the original "Gant-chart" concept for tGui.

- Another long-time friend and colleague Ben Lane (together with GvB) actually did the first hackery on what was to become fbol. Ben was an "early adopter", and helped to sharpen many of the presentation and user interface aspects of the getCal package.

- Michelle Creech-Eakman has been a loyal user and "critic", and contributed to the documentation for the fbol package.

- Rafael Millan-Gabet has been a user for a relatively short time, but already holds (what will probably be) the career record for exposing getCal bugs.

- Steve Groom for doing lots of testing, finding a platform-dependent flakey if test in fbol, contributing the fbol/convertPhotometry communication code, testing getCal on the Mac platform, and re-working the internal data handling code.

- Tracey Evans for adding new getCal options and debugging some old ones.

- Mark Echeverri and Claude Felizardo helped with a major rework of the installation and configuration mechanisms, massive overall code refactoring, and elimination of the dependancy on lynx.

- Irene Bregman, Mark Abajian, and Jennifer Herstein for helping make gcWeb (the web interface for getCal) come to life.

- [Andy's] wife Nan "for the Perl evangelism, for a clever or elegant incantation here and there, and mostly for being patient when I was trying to track down a bug."

Of course, underlying it all is the grateful acknowledgment to NASA for support of getCal development over the years.

—

If you find getCal (or any other NASA Exoplanet Science Institute software or service) useful in your research, we would appreciate the following acknowledgment:

"This research has made use of services from the NASA Exoplanet Science Institute, California Institute of Technology, http://nexsci.caltech.edu."

6 Copyright

getCal-2.10.4, build 20071105

Copyright © 1997 – 2007 California Institute of Technology. Developed with U.S. Government sponsorship under contract with the National Aeronautics and Space Administration. All Rights Reserved.

For questions or comments about this software, please visit the NExScI Help Desk at http://exoplanetarchive.ipac.caltech.edu/cgi-bin/NExScI_Helpdesk/nph-genTicketForm.

Permission to use, copy and distribute this software and its documentation for academic and/or non-profit research purposes, without fee and without a written agreement is hereby granted, provided that the above copyright notice, this paragraph and the following three paragraphs appear in all copies. Reuse of all or part of the software contained here for commercial purposes is strictly prohibited.

The California Institute of Technology makes no proprietary claims to the results, prototypes, or systems supporting and/or necessary for the use of the research, results and/or prototypes for academic and/or non-profit research uses only. However, to the extent that any software and system built in collaboration with industry partners may incorporate proprietary designs of the industry partners, it is possible that certain restrictions may be imposed on the proprietary information.

In no event shall California Institute of Technology be liable to any party for direct, indirect, special, incidental or consequential damages, including lost profits, arising out of the use of this software and its documentation, even if the California Institute of Technology has been advised of the possibility of such damage.

The California Institute of Technology specifically disclaims any warranties, including the implied warranties or merchantability and fitness for a particular purpose. The software and documentation provided hereunder is on an "as is" basis, and the California Institute of Technology has no obligations to provide maintenance, support, updates, enhancements or modifications.

Index

Concept Index * getCal: (getCal). Interferometric observation planning tool suite

• 2MassQuery: 2MassQuery
• 2MassQuery Description: 2mqDescription
• Acknowledgments: Acknowledgments
• Building and Installing getCal: Building and Installing getCal
• Configuration: Run-Time Configuration
• convertPhotometry: convertPhotometry
• Copyright: Copyright
• csAdhoc: csAdhoc
• Customization: ocGui: ocGuiCustom
• Customization: tGui: tGuiCustom
• Customization: timing: timing Defaults and Customization
• Customization: uvTool: uvToolCustom
• Environment Variables: Run-Time Configuration
• fbol: fbol
• fbol Description: fbol Description
• fbol Input Format: fbol Input
• fbolFormat: fbolFormat
• gcConf: gcConf
• gcGui: gcGui
• gcGui Description: gcGuiDescription
• gcGui Keyboard Shortcuts: gcGuiKeyboard
• gcGui Menus and Control Buttons: gcGuiMenus
• gcGui Return Windows: gcGuiReturnWindows
• gcList: gcList
• getCal: getCal
• getCal Calibration Script Support: getCal Calibration Script Support
• getCal Command-Line Options: getCal Command-Line Options
• getCal Description: getCal Description
• getCal Examples: getCal Examples
• getCal Format: getCal Format
• getCal General Description: Overview and Features
• getCal Inputs and Outputs: getCal Inputs and Outputs
• getCal Option Summary: getCal Command-Line Options
• getCal Web Interface: getCal Web Interface
• Introduction: Introduction
• IRAS Search Target Input: irasTargets
• IRASQuery: IRASQuery
• IRASQuery Description: irasDescription
• IRSA: irasDescription
• IRSA: 2mqDescription
• irsaminer: irsaminer
• makeHipIdx: makeHipIdx
• New Format: getCal Format
• obsCalendar: obsCalendar
• ocGui: ocGui
• ocGui Control Buttons: ocGuiButtons
• ocGui Customization: ocGuiCustom
• ocGui Description: ocGuiDescription
• ocGui Keyboard Shortcuts: ocGuiKeyboard
• ocGui Menus: ocGuiMenus
• Overview and Features: Overview and Features
• pbol: fbol
• Release Notes: Release Notes
• Release Notes for getCal-2.10: Release Notes
• Release Notes for getCal-2.10.1: Release Notes
• Release Notes for getCal-2.10.2: Release Notes
• Release Notes for getCal-2.10.3: Release Notes
• Release Notes for getCal-2.10.4: Release Notes
• Release Notes for getCal-2.8: Release Notes
• Release Notes for getCal-2.9: Release Notes
• Release Notes for getCal-2.9.1: Release Notes
• Release Notes for getCal-2.9.2: Release Notes
• Release Notes for getCal-2.9.3: Release Notes
• Release Notes for getCal-2.9.4: Release Notes
• Release Notes for getCal-2.9.5: Release Notes
• Release Notes for getCal-2.9.6: Release Notes
• Run-Time Configuration: Run-Time Configuration
• Screenshots: Screenshots
• Search Target Input: 2mqTargets
• Setup: Setup
• simbadInteractiveQuery: simbadInteractiveQuery
• simbadInteractiveQuery Description: siqDescription
• simbadInteractiveQuery Search Target Input: siqTargetInput
• sky Format: getCal Format
• tGui: tGui
• tGui Control Buttons: tGuiButtons
• tGui Customization: tGuiCustom
• tGui Description: tGuiDescription
• tGui Keyboard Shortcuts: tGuiKeyboard
• tGui Menu Description: tGuiMenus
• timing: timing
• timing Command-Line Options: timing Command-Line Options
• timing Defaults & Customizations: timing Defaults and Customization
• Tools Reference: Tools Reference
• uvTool: uvTool
• uvTool Command-Line Options: uvToolOptions
• uvTool Customization: uvToolCustom
• uvTool Description: uvToolDescription
• uvTool Frames and Control Buttons: uvToolButtons
• uvTool Keyboard Shortcuts: uvToolKeyboard
• uvTool Menus: uvToolMenus
• Working with XEphem: xeConvert
• xeConvert: xeConvert

Program Index

• csAdhoc: csAdhoc
• gcConf: gcConf
• gcGui: gcGui
• gcWeb: getCal Web Interface
• getCal: getCal
• makeHipIdx: makeHipIdx
• obsCalendar: obsCalendar
• ocGui: ocGui
• simbadInteractiveQuery: simbadInteractiveQuery
• tGui: tGui
• timing: timing
• uvTool: uvTool