Installing SCHED

This section is only needed if you do not have access to an installed copy of SCHED.

It is important that users obtain and use the latest version of SCHED  when scheduling observations. SCHED  is evolving with time to add new features, to correct bugs, and to enhance its ability to prevent errors from being made in schedules, based on experience. There are typically one or two releases each year and they are announced on the VLBI email exploder. At institutions where there are several VLBI users, someone should be in charge of making sure that the latest version is available. When that option is not available, the user should check that he/she has the latest version before attempting to schedule a project.

The sched software, catalogs, auxiliary files, and documentation all reside in subdirectories under a parent directory. At the AOC, the parent directory is /users/cwalker/sched. Installing SCHED  involves unpacking the tar files of the distribution into these directories. If a canned executable is available for your type of computer, it can be copied and, hopefully, used as is. Otherwise it will be necessary to compile the program. This may involve installing the PGPLOT subroutine library if it is not already available. On unix systems, the installation also involves setting up the useful environment variables and path. The installation can be tested using the Verify script in the examples subdirectory. That script runs all the examples and compares the results with results obtained at the time the release was created.

SCHED  is written in FORTRAN 77 using only a few common extensions from the standard. Development has occurred on a variety of machines including VAXes, PCs, and SUNs. Current development is done on a Linux PC. Reasonably recent versions have mainly been tested on Linux (g77), Solaris, and Mac OS X. Older versions were tested on Hp, SGI, IBM (AIX), and DEC Alpha. A big ``thank you'' to Franco Tinarelli at Bologna for performing many of these tests. Machine dependent code has been isolated in special subdirectories under the src/Cit code directory. All other FORTRAN files should compile without changes on a wide variety of machines. Note, however, that all current testing is under one or another flavor of unix. There has been no recent testing under other operating systems. This will only change if there is pressure to do so. Please inform Craig Walker at cwalker@nrao.edu if you install it on something else, including VMS or Windows - it has been many years since the last port to VMS or DOS, although both have served as the primary development environment for SCHED  in the past.

If you plan to support SCHED  under more than one computer architecture, you may wish to have subdirectories under bin and point to the appropriate one in the PATH environment variable. Or you may wish to have entirely separate installations.

To install SCHED, the following steps can be followed. Users of anything but unix or linux (who don't exist as far as we know) will have to make some modifications.

Users of Mac OS X will need to have X windows and the compiler installed. Also for full functionallity, pgplot should be installed. There are some more details at the end of this section.

Environment and PATH (unix systems):

Set the environment variable SCHED to the base directory under which SCHED  will be installed. To do this type, for example, either

setenv SCHED /users/cwalker/sched

or

export SCHED=/users/cwalker/sched

depending on the shell you use. Add the bin subdirectory to your PATH, or be prepared to specify the full path name when you run the program. If the plotting capabilities are used, which is highly recommended, PGPLOT will need to have been installed and the environoment variables PGPLOT_DIR and PGPLOT_FONT will need to be set. In Socorro, the path and environment variables can be established by adding setup_vlba to your .tcshrc.SunOS5 (or equivalent file for other shells).

ftp the tar file:

Use anonymous ftp to ftp.aoc.nrao.edu (user "anonymous", password should be your full email address). cd to pub/sched. Tell ftp to do binary file transfers (type binary). List the tar files present and copy the latest version of sched.aux.<date>.tar.gz to your $SCHED directory. If you will recompile, copy sched.src.<date>.tar.gz. If you can use one of the precompiled excutables, find the appropriate one in a subdirectory and copy it to your bin subdirectory. You probably want to rename any such executable to sched from the longer name including the release date that is used on the ftp site. If you want to test the program, copy sched.stdout.<date>.tar.gz which contains the comparison output files created at the aoc. The executables are around a Mbyte compressed although the size varies with architecture. The other files are a bit over 500 kbytes compressed.

Uncompress:

You will need the GNU zip utility to uncompress the tar file. This should be available on most systems. To uncompress the file, type gunzip <filename> or unzip <filename>. GNU software is available by ftp from prep.ai.mit.edu.

Unpack the tar files:

For each tar file, type tar -xvf <filename>. This will unload all files from the tar file, creating the necessary subdirectory structure in the process. A README file will appear in the top level directory which contains useful information on the directory structure and on installing SCHED.

Note that, after this step, a local html version of this manual will be available in the doc/sched/sched.html under the parent SCHED  directory ($SCHED). Your browser will probably run much faster pointing at that version than at the version at NRAO. Links inside the manual to examples depend on the presence of some logical links to other sched directories. If these are not there after unpacking the tar files, they can be established by running the script $SCHED/doc/makelinks, assuming you are using unix or linux (just type makelinks while $SCHED/doc is your default directory).

Compiling the programs:

If executables are not available for your machine, or they don't work (library problems or whatever), you will need to compile the program. To do so, cd to the $SCHED/src subdirectory. Examine the Makefile with an editor and, following the instructions in it, make any necessary changes. Note that versions preconfigured for Sun and Linux are provided. In fact, Makefile may just be a link to one of them. The changes select computer type, library locations, compiler etc. They are usually made by just altering which of several lines are not commented out. Once the Makefile is ready, invoke the GNU MAKE utility by typing make or gmake. There are a large number of routines that are compiled so this will take a few minutes and will produce quite a bit of output. Once make has finished, you are ready to run the program.

Note that the current version of the Makefile requires the use of GNU make. Check for GNU make on your system. It is installed on many if not most and is the standard make under Linux. If you don't have it, it can be obtained from prep.ai.mit.edu. Also a version (probably not current) is available in the same ftp area as SCHED.

SCHED  can be compiled with or without the plotting capabilities. It is highly recommended that you compile with those capabilites. To do so, you will need PGPLOT (version 5.2 or later) installed on your system. See below for more information on getting PGPLOT if you don't already have it. It is commonly available at astronomy sites and is used in AIPS++, so it is likely that you already have it installed. There are stubs that can be used to bypass PGPLOT if necessary and the instructions on how to do so are in the Makefile. SCHED  will still be able to make schedules if the stubs are used, but it will not be able to make any plots.

There is also a stub for the routines related to use of the JPL emphemeris, in case that code causes problems. The JPL routines are used for observations of planets, which are probably only of interest for single-dish testing of the VLBA by staff. Using the stub requires changing some comments in the Makefile. Similarily, there is a stub to avoid using the NAIF software related to satellite tracking. The normal user will use that stub because the NAIF libraries are not normally distributed with SCHED.

Testing:

The examples in the examples subdirectory can be used to test the code once it has been installed. A few outputs from each example are stored in the Stdout subdirectory which is packed in the sched.stdout.<date>.tar.gz tar file. For unix systems, the routine Verify can be used to run all of the examples and compare results with those in Stdout. The output from Verify will be in the file testruns.out. Any differences are in the output from diff. It is common to have differences in items such as source positions in the last significant figure. Different machines handle rounding differently. Such differences can be ignored. Any more serious differences are cause for concern.

As noted above, SCHED  has plotting capabilities that utilize the PGPLOT graphics subroutine library. You must have version 5.2 or later. PGPLOT is not distributed with SCHED  and will have to be obtained independently by anyone who wants to do plotting and who does not already have it available. There is extensive information on PGPLOT available from the WWW page at http://www.astro.caltech.edu/~tjp/pgplot/.

Some VAX FORTRAN features that are commonly supported by other FORTRAN compilers remain in the code. These features are supported by all of the compilers that we are aware of that are being used for SCHED  currently. But if you have problems, some of the non-standard features (in line comments, END DO etc) can be removed using the (very old) [program vaxms (contact cwalker@nrao.edu) or with ``fct'' on a CONVEX or ``f77cvt'' on a SUN (beware of bugs in f77cvt!). Note that vaxms has not been exercised in a very long time.

Some non-standard features, including long variable names, remain in the program after processing with vaxms. All of the compilers used so far allow these features but they might cause trouble for other ports. Considerable use was made of the SLALIB (STARLINK) routines for precession, etc. These routines use long variable names so removing this non-standard feature would not be easy. (email permission to use the FORTRAN SLALIB routines has been obtained from P. Wallace).

If the code or any other files are moved from a unix or VMS machine to a machine using DOS or Windows, beware that the end of line characters are different. At least on a SUN (others?), a pair of utilities unix2dos and dos2unix can be used to fix the files. Under Linux, the mcopy command can be used (from the mtools, which allow manipulation of DOS files from Linux). If DOS format input files or catalogs are given to a unix SCHED, it will abort.

We are always interested in hearing about people's experiences installing SCHED  on various machines. If you have problems, or even success on machines other than those listed earlier, please let us know (email to cwalker@nrao.edu). We would be especially interested if someone ports SCHED  to a non-unix, or unix-like (eg Linux) operating system. SCHED  was supported under VMS and DOS in the past and the coding style hasn't changed, so a port to such operating systems would probably not be difficult.

Here are a few details for Mac OS X users. SCHED  was installed on a Mac iBook G4 system in Dec 2003 with OS X version 10.3 (Panther). Before installing SCHED, the code tools had to be installed (the installation package was already on disk, but not yet installed) and X windows had to be installed from the OS X installation CD 3 (not CD 2 as some documentation stated). The code tools include gcc, but not g77 (why?). A binary version of g77 compatible with Panther was obtained from hpc.sourceforge.net. It installed itself on download and simply worked. PGPLOT was installed. There was no provided .conf file for OS X. I made a local.conf file starting with the one from ../src/sys_bsd/g77_gcc.conf. The following two lines were different:

    FFLAGD="-fno-backslash"
 LIBS="-L/usr/lib -lgcc -L/usr/X11R6/lib -lX11"

The routine that makes the font file (pgpack) caused some trouble while I was messing with various variants on the above, but eventually worked. I suspect problems with big vs little endian byte orders, but I'm not sure. Note that pgplot version 5.3 has OS X as a standard OS type. This version was not released as of Oct 2004, but might be available if you ask nicely.

Once the X windows environment, gcc/g77, and PGPLOT were ready, SCHED compiled and ran with the Makefile set up for Linux/g77 and the and the following two modified lines (one just depends on the location of PGPLOT and the other helps it find the gcc libraries): XLD = -L/usr/lib -lgcc -L/usr/X11R6/lib -lX11 # Mac OS X (ie DARWIN) LPGPLOT = /usr/local/pgplot The architecture still claimed to be LINUX and the g77 compiler flags were the same. That's all it took! It compiled and passed the verification tests. If you are using FINK, some details may be different.

If you run into problems with some missing .h files, you might have a mismatched OS version and XCODE version, as I did.

I now have SCHED  on a Powerbook and that may soon be the primary SCHED  development platform.