Installation and Test Guide for Kvis
Rachel Akeson, Michelson Science Center
Version 0.99, Aug 20, 2002
Version 1.1, Sept 30, 2005 (hjb, updated CVS instructions)
1. Introduction
This document describes how to acquire, install and test the
visibility reduction software for the Keck Interferometer, which is
called Kvis. This software is written and maintained by the Michelson
Science Center in Pasadena. This manual is part of the documentation
normally distributed with Kvis.
1.1 Questions, comments and bug reports
Questions, comments and bug reports on either the Kvis install files
or this manual should be sent to Rachel Akeson (rla@ipac.caltech.edu).
2. Necessary supporting packages
Building and running Kvis requires the use of several general software
tools and other Michelson Science Center software code. These are listed below.
Several of these packages (ACE, TAO) are not used directly by Kvis,
but are used by the interface with the archive data (called the API).
The API routines are normally contained within the Keck Interferometer
real-time software trees, called rtc and krtc.
If you need to checkout Kvis from Keck or JPL you will need an IPAC
issued SecureID fob, in order to pass through IPAC's gateway.
In addition, there are also tools necessary for running the auxiliary
scripts provided with Kvis (see section 6 for more details on these
scripts).
Tool Usage
CVS Check-out of source code
gcc Compilation of Kvis code
g++ Compilation of Kvis code
gmake Running install and compilation scripts
API code Interface to archive data
ACE lib Used by API
TAO lib Used by API
Optional packages
gnuplot Used by plotting scripts - see www.gnuplot.info
perl Plotting and ancilliary script langauge
3. Getting the source code
The source code for Kvis can be obtained from the CVS repository
maintained by the MSC in Pasadena. This repository is currently
located on the machine mscdev301.ipac.caltech.edu. You must have an
account at IPAC in order to check out the software, and you must
have an IPAC issued SecureID fob to checkout from remote locations.
Instructions for IPAC
------------------------------
To check out the Kvis software, set the CVS environment variable
to use ssh.
setenv CVS_RSH ssh
Next, cd to the directory where you want the source code and
check out the Kvis module.
cd /usr/local/kroot/kss/if/
cvs -d user@mscdev301.ipac.caltech.edu:/CM_Repository/KI/KI_REDUCTION/
Replace user with your user name. The Kvis module contains the
Makefiles, source code (in /src), documentation (in /doc), testing
scripts (in /test), plotting scripts (in /sumplots), pipeline
scripts (in /endNight) and ancilliary data scripts (in /scripts). Some of
the scripts are intended for use only at the Keck observatory.
Instructions for Remote Locations (JPL, Keck)
-----------------------------------------------
First set-up a tunnel from the CVS server through IPAC's firewall
gateway:
ssh -l <ipacusername> -L <userport>:mscdev301:22 ag.ipac.caltech.edu
where <userport> is some port number you choose, possibly based on your
office number to avoid conflicts with other gateway users. The gateway
(ag.ipac.caltech.edu) will prompt you for your Unix username and pin
number/SecureID token. (Please keep in mind that each SecureID token
can be input only once).
Now you need to inform CVS to use your <userport> instead of port 22.
There are two ways to do this (both of which are a little ugly). You
may either make a script which calls ssh with the correct port number,
or you can edit your ssh config file to add a block for the CVS service.
For the script, make a file called "myssh" on the remote system and
put this in it:
ssh -p <userport> $*
and then make sure the script is executable
chmod 0777 myssh
Before invoking CVS:
setenv CVS_RSH /full/path/to/myssh
setenv CVSROOT <ipacusername>@localhost:/CM_Repository/KI/KI_REDUCTION
If you would prefer to use a ssh config file, you can do the following:
On the remote system open ~/.ssh2/ssh2_config and add the this block
msccvs:
Host localhost
Port <userport>
Then before invoking CVS:
setenv CVS_RSH ssh
setenv CVSROOT <ipacusername>@msccvs:/CM_Repository/KI/KI_REDUCTION
If you system is using ssh1 instead of ssh2, the syntax (and name) of
the ssh config file will be different. Seek an ISG member for help.
Now that you're setup, you can cd to the place you want the Kvis code
to go, and
cvs checkout Kvis
4. Building Kvis
4.1 Modifying Makefile.env
The build and install process for Kvis is controlled from a Makefile
in the top level directory. Each subdirectory also contains a
Makefile file from which individual programs can be built. The user
must modify several location variables in Makefile.env. These
variables are:
DESTDIR The installation directory
ETCDIR Install directory for parameter files
CC The C compiler
C++ The C++ compiler. This needs to be a version of egcs.
ACELIB The location of the ACE, TAO and orbsvcs libraries
APILIB The location of the api library (in the krtc tree)
HEADERLIB The location of API\_FT\_GetSample.h (in the krtc tree)
UTILSLIB The location of the utils library (in the rtc tree)
For the supporting scripts:
PERL Location of the perl executable
SUMPLOTSDIR Install directory for KvisPlot package
EXECDIR Location of MSC executables (extractor, getCal, bFit)
RTKVISDIR Install directory for backup of rtKvis scripts (Keck Obs only)
RTKVISBIN Install directory for running rtKvis (Keck Obs only)
CGIDIR Install direcotry for cgi script (Keck Obs only)
For installing Kvis at the Keck observatory, default values for most
of these variables are given in comments at the end of Makefile.env.
Note that the install directories specified in DESTDIR, ETCDIR,
SUMPLOTSDIR, RTKVISDIR, RTKVISBIN and CGIDIR must already exist before
the install commands are run.
4.2 Making Kvis
You are now ready to compile Kvis. In the top level directory type
gmake Kvis
This will compile Kvis in the src subdirectory. There should
be no compilation warnings or errors. To remove the compiled
programs use
gmake clean
Note that some of the programs (rtKvis, endNight) are intended for use
at the interferometer only and so two targets are provided for
building and installing all packages within Kvis. To make Kvis and
all the supporting scripts
gmake all (at Keck Obs)
gmake partbuild (everywhere else)
4.3 Installing Kvis
Kvis will be installed in the location specified in DESTDIR.
From the top level directory run
gmake installKvis
This process can be un-done by running
gmake uninstall
You are now ready to run Kvis.
To install all packages at once
gmake install (at Keck Obs)
gmake partinstall (everywhere else)
Executables will be installed in DESTDIR and any necessary parameter
or other files will be in ETCDIR. Individual elements can also be
built within the subdirectories. More information on building the
scripts is given in section 6.
5. Testing Kvis
The source code distribution includes testing scripts for Kvis. To
run these tests go to the test subdirectory and run the script
test.script
The script will report any differences encountered between your
results and the standard results. Check the diff files for these
differences. Small numerical differences in the calculations are not
a problem and can be ignored. Other problems, particularly failure of
Kvis to run at all, may indicate problems with your build and install
procedure. By default, the script looks for Kvis in the install
location. This can be changed by modifying the KVISDIR variable in
test.script.
6. Building and installing the ancilliary scripts
All packages within the Kvis tree can be built and installed at once
as described in 4.3. The other packages use the same environment
variables described in 4.1. This section contains details about
individual packages.
6.1 Example directory structure
6.2 KvisPlot
KvisPlot is a perl script which produces plots from the output of
Kvis. See the Kvis user's guide for more information on running the
program or the README file in the sumplots directory. As KvisPlot and
its subroutines are all perl scripts, no compiling is necessary.
However, the scripts do need to be altered to contain the correct
references to the location of perl and to the installation directory.
This is done through variables in Makefile.env. The scripts assume
that gnuplot is in the user's path. The use of plotting options -gif
and -png will depend on the gnuplot installation supporting these
formats.
PERL The location of perl.
SUMPLOTSDIR The install directory for KvisPlot.
Once these variables have been set type
gmake KvisPlot
gmake installKvisPlot
The build of KvisPlot can be tested by typing
KvisPlot new.sum
in the sumplots subdirectory. This should produce a series of
plots.
6.3 Misc. helper scripts
A set of perl scripts is provided to perform various data related
tasks (gridFiles, katCounts, FTconvert). To build the scripts
gmake mscripts
and to install (in DESTDIR)
gmake installscripts
gridFiles uses EXECDIR from Makefile.env to determine
the location of the extractor executable.
6.4 rtKvis
rtKvis is a perl script to perform near-real time data reduction
and plotting. This script is only run at the interferometer. The
script does not need to be built and is installed using
gmake installrtKvis
Then follow the instructions contained in rtKvis.help (which is
in both RTKVISDIR and RTKVIBIN).
6.5 endNight
endNight is a perl script which does the automated end
of night data processing. This script is run only at the
interferometer. It is built and installed (in DESTDIR) using
gmake makeendNight
gmake installendNight
endNight requires working versions of extractor, getCal
and bFit, which it looks for in EXECDIR. The other
files needed by endNight are installed in ETCDIR.
After installing, follow the instructions given at
the end of the help file (accessible at endNight.help
in ETCDIR or type endNight -help).
6.6 trending
The trending directory contains programs to calculate
near-real time and post-processing values of instrument
performance values.
gmake trend
gmake installtrend