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 -L :mscdev301:22 ag.ipac.caltech.edu where 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 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 $* and then make sure the script is executable chmod 0777 myssh Before invoking CVS: setenv CVS_RSH /full/path/to/myssh setenv CVSROOT @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 Then before invoking CVS: setenv CVS_RSH ssh setenv CVSROOT @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