Caltech     IPAC           JPL           NASA
The getCal Interferometric Observation Planning Tool Suite

The getCal Interferometric Observation Planning Tool Suite


Next: , Previous: (dir), Up: (dir)

Manual for getCal-2.10.4

getCal is a product of the NASA Exoplanet Science Institute.

./images/NExScI_FullColorLogo_WithText.png


Next: , Previous: Top, Up: Top


Next: , Previous: Contents, Up: Top

1 Introduction


Next: , Previous: Introduction, Up: Introduction

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:

An online version of getCal is available on the web, allowing the interested user to avoid the effort of installing this software. The gcWeb tool can be accessed at http://nexsciweb.ipac.caltech.edu/gcWeb . Or, 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:

images/getCal.GUI.png

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

images/getCal.return.png

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.

images/photometry.png

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.

tGui screenshot

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.

images/ocGui.png

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.

images/uvTool.png

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:

images/HD217014_G2.5IVa.sed.png


Next: , Previous: Introduction, Up: Top

2 Setup


Next: , Previous: Setup, Up: Setup

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. As an alternative, NExScI provides a web-based version of getCal, cleverly named gcWeb, accessible online at http://nexsciweb.ipac.caltech.edu/gcWeb. The web tool provides most of the functionality of the getCal package without requiring the installation of this software.

2.2 Building and Installing getCal

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.

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.


Next: , Previous: C++ compiler, Up: Installing the Prerequisites

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:

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.


Next: , Previous: Gnuplot, Up: Installing the Prerequisites

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:

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):

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


Previous: Run-Time Configuration, Up: Setup

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.


Next: , Previous: Setup, Up: Top

3 Tools Reference

Command-line tools:

Catalog-lookup tools:

GUI's:

Other Utilities:


Next: , Up: Tools Reference

3.1 getCal


Next: , Previous: getCal, Up: getCal

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

Calibrator Selection Options

Photometry Options

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):

--fbol sub-options delegated to fbolFormat:

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:

Timing Options

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:

Calibration Script Options

Output Format Options

Visualization Options

Generic Options

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!)

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


Next: , Previous: getCal Format, Up: getCal

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)
         


Next: , Previous: getCal, Up: Tools Reference

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:

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]
     


Next: , Previous: gcList, Up: Tools Reference

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.


Next: , Previous: csAdhoc, Up: Tools Reference

3.4 timing

timing – Compute interferometric target temporal accessibility


Next: , Previous: timing, Up: timing

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

Generic options:

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.


Next: , Previous: timing, Up: Tools Reference

3.5 fbol

fbol – Bolometric Flux/Spectral Energy Distribution Modeling


Next: , Previous: fbol, Up: fbol

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


Next: , Previous: fbol Description, Up: fbol

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

Generic options:


Next: , Previous: fbol Command-Line Options, Up: fbol

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:

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.


Previous: fbol Input, Up: fbol

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.

images/HD217014_G2.5IVa.sed.png

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.


Next: , Previous: fbol, Up: Tools Reference

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


Next: , Previous: fbolFormat, Up: Tools Reference

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:

Generic options:


Next: , Previous: convertPhotometry, Up: Tools Reference

3.8 obsCalendar

obsCalendar – perl program to compute target annual accessibility.


Next: , Previous: obsCalendar, Up: obsCalendar

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.


Previous: obsCalDescription, Up: obsCalendar

Command-Line Options

obsCalendar supports the following command-line options:

     	--hourAngle= --location= --noEcho --noPreamble --replace
     	--twilightAngle= --year=
     	--copyright --debug --filename= --help --longHelp --version --stdin

Generic options:


Next: , Previous: obsCalendar, Up: Tools Reference

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

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]
     


Next: , Previous: gcConf, Up: Tools Reference

3.11 simbadInteractiveQuery

simbadInteractiveQuery – Query the Simbad database by HTTP

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

Generic options:

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:

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= ]

Modes of Operation

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

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 &quot;default&quot; 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.


Next: , Previous: irsaminer, Up: Tools Reference

3.13 2MassQuery

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


Next: , Previous: 2MassQuery, Up: 2MassQuery

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


Next: , Previous: 2mqDescription, Up: 2MassQuery

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

Generic options:


Next: , Previous: 2mqOptions, Up: 2MassQuery

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


Previous: 2mqTargets, Up: 2MassQuery

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.


Next: , Previous: 2MassQuery, Up: Tools Reference

3.14 IRASQuery

IRASQuery – Query the IRAS point-source catalog by HTTP


Next: , Previous: IRASQuery, Up: IRASQuery

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.


Next: , Previous: irasDescription, Up: IRASQuery

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

Generic options:


Next: , Previous: irasOptions, Up: IRASQuery

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


Previous: irasTargets, Up: IRASQuery

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.


Next: , Previous: IRASQuery, Up: Tools Reference

3.15 gcGui

gcGui – Graphical User Interface wrapper for getCal


Next: , Previous: gcGui, Up: gcGui

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

Note: An online version of getCal is available at http://nexsciweb.ipac.caltech.edu/gcWeb . gcWeb provides functionality similar to gcGui, running in a web browser environment. gcWeb allow any Internet user to run getCal queries on an NExScI web server without installing any software.

Here is a screenshot of gcGui in action:

images/getCal.GUI.png

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.


Next: , Previous: gcGuiDescription, Up: gcGui

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


Next: , Previous: gcGuiConfiguration, Up: gcGui

Menu and Button Descriptions

Menus:

Main gcGui window:


Next: , Previous: gcGuiMenus, Up: gcGui

Keyboard Shortcuts

gcGui supports a number of keyboard shortcuts:

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


Previous: gcGuiKeyboard, Up: gcGui

Return Windows

gcGui packages the getCal output in several return windows:


Next: , Previous: gcGui, Up: Tools Reference

3.16 tGui

tGui – Perl/Tk GUI visualization of target diurnal accessibility


Next: , Previous: tGui, Up: tGui

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 screenshot

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.


Next: , Previous: tGuiDescription, Up: tGui

Command-line Options

tGui accepts the following command-line options:

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.


Next: , Previous: tGuiOptions, Up: tGui

Third-Party Software

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


Next: , Previous: tGuiTPS, Up: tGui

tGui Menu Description

tGui provides the following menus:

Note all menus are detachable/tear-off


Next: , Previous: tGuiMenus, Up: tGui

tGui Frames and Control Buttons

Frames:

Control Buttons:


Next: , Previous: tGuiButtons, Up: tGui

Keyboard Shortcuts

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


Previous: tGuiKeyboard, Up: tGui

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;
     
     


Next: , Previous: tGui, Up: Tools Reference

3.17 ocGui

ocGui – Graphical User Interface visualization of target annual accessibility


Next: , Previous: ocGui, Up: ocGui

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:

images/ocGui.png

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.


Next: , Previous: ocGuiDescription, Up: ocGui

Command-line Options

ocGui accepts the following command-line options:


Next: , Previous: ocGuiOptions, Up: ocGui

Third-Party Software

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


Next: , Previous: ocGuiTPS, Up: ocGui

Menu Description

Menus:

Note all menus are detachable/tear-off


Next: , Previous: ocGuiMenus, Up: ocGui

ocGui Frames and Control Buttons

Frames:

Control Buttons:


Next: , Previous: ocGuiButtons, Up: ocGui

Keyboard Shortcuts

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


Previous: ocGuiKeyboard, Up: ocGui

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;
     


Next: , Previous: ocGui, Up: Tools Reference

3.18 uvTool

uvTool – render u-v plane coverage


Next: , Previous: uvTool, Up: uvTool

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:

images/uvTool.png

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.


Next: , Previous: uvToolDescription, Up: uvTool

Command-Line Options


Next: , Previous: uvToolOptions, Up: uvTool

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


Next: , Previous: uvToolTPS, Up: uvTool

uvTool GUI Menus

Menus:

Note all menus are detachable/tear-off.


Next: , Previous: uvToolMenus, Up: uvTool

Frames and Buttons

Frames:

Control Buttons:


Next: , Previous: uvToolButtons, Up: uvTool

Keyboard Shortcuts

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


Previous: uvToolKeyboard, Up: uvTool

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;
     


Previous: uvTool, Up: Tools Reference

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


Next: , Previous: Tools Reference, Up: Top

4 Release Notes

4.1 Release Notes for getCal-2.10.4

Fixes and changes to existing functionality

4.2 Release Notes for getCal-2.10.3

Fixes and changes to existing functionality

4.3 Release Notes for getCal-2.10.2

New and Improved Features

Fixes and changes to existing functionality

Known Issues

4.4 Release Notes for getCal-2.10.1

New and Improved Features

Fixes and changes to existing functionality

4.5 Release Notes for getCal-2.10

New and Improved Features

Fixes and changes to existing functionality

4.6 Release Notes for getCal-2.9.6

Fixes and changes to existing functionality

4.7 Release Notes for getCal-2.9.5

Fixes and changes to existing functionality

4.8 Release Notes for getCal-2.9.4

Fixes and changes to existing functionality

4.9 Release Notes for getCal-2.9.3

Fixes and changes to existing functionality

4.10 Release Notes for getCal-2.9.2

Fixes and changes to existing functionality

4.11 Release Notes for getCal-2.9.1

Fixes and changes to existing functionality

4.12 Release Notes for getCal-2.9

Fixes and changes to existing functionality

New and Improved Features

Known Bugs

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:

New and Improved Features

Known Bugs


Next: , Previous: Release Notes, Up: Top

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


Next: , Previous: Acknowledgments, Up: Top

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.


Previous: Copyright, Up: Top

Index

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

Program Index

g 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


    Next: , Previous: Release Notes, Up: Top

    6 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."


    Next: , Previous: Acknowledgments, Up: Top

    7 Copyright

    getCal-2.10.7, build 20081112

    Copyright © 1997 – 2008 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://nexsci.caltech.edu/contact/help_desk.html.

    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.


    Previous: Copyright, Up: Top

    Index

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

    Program Index