README

README file for the SCHED root directory.
By Craig Walker

This is the root directory for everything needed to install and run
the VLBI scheduling program SCHED.  If you are seeing this, you
have probably already unpacked the distribution tar file.  If not,
that is the first thing to do.

To utilize SCHED, you should set the environment variable SCHED to
point to this directory.  The environment variables PGPLOT_DIR and
PGPLOT_FONT should be set to the location of your pgplot libraries and
font file.  Note PGPLOT_FONT is usually $PGPLOT_DIR/grfont.dat.

An HTML version of the SCHED Manual is on the Internet at
http://www.aoc.nrao.edu/software/sched/index.html.   
Another copy, which might be newer during the release process, is at:
http://www.aoc.nrao.edu/~cwalker/sched/sched.html or
http://www.aoc.nrao.edu/~cwalker/sched_beta/sched/sched.html
After you unpack the release tar file, the manual is availble locally
on your machine at $SCHED/doc/sched/sched.html.  A postscript version 
can be made by running latex on sched.tex in ./doc. Warning, it is 
large - almost 300 pages - and evolving rapidly.  If you can use a
Web version, it is more convenient and will be kept up to date.  The
author has not generated a postscript or pdf version in many years.

The subdirectories here are:

./bin:          Base location of the execute modules and some scripts.
                There are execute modules or links for the site default
                computer type here.
                This, or the type specific subdirectory, can be added 
                to your PATH for easy execution.

./bin/<arch>:   Possible computer type specific directories containing 
                execute modules.

./catalogs:     Station, source, and linename catalogs.  Also some
                stuff that may be ignored related to catalog 
                conversions.  There are some {\sl Master} subdirectories
                containing the versions of the frequency and station
                catalogs that are actually maintained, but users 
                need not be concerned about them

./catalogs/Master_JIVE:  Contains station and frequency catalog segments
                maintained at JIVE.  Not meant for users.

./catalogs/Master_NRAO:  Contains station and frequency catalog segments
                maintained at NRAO.  Not meant for users.

./catalogs/Master_HSTK:  Contains station and frequency catalog segments
                maintained at HSTK for mm VLBI.  Not meant for users.

./doc:          The SCHED Manual and some other documentation files.

./examples:     Some example SCHED input files.  A good place to 
                look for templates.  Also the location of the 
                verification script Verify.

./examples/Stdout:  Versions of outputs from the Verify script.  Will 
                be used as comparison with local output when 
                Verify is run.  There is considerable disk space here
                and it is only used when testing SCHED with Verify,
                so this area can be emptied if space is tight.

./setups:       Setup files.  Look here for what you need or 
                something close that can be modified.

./src:          The source code directory.  Also the location of the
                Makefile (which requires GNU make - get from
                prep.ai.mit.edu or the SCHED ftp area if necessary)

./src/Cit:      A directory structure containing routines, some 
                machine specific, taken, or closely associated  
                with, the Caltech VLBI package.  There are a number
                of architecture specific subdirectories (eg sys_sun)
                that are needed for specific machines.

./src/Sched:    The code for SCHED.

./src/Jpl:      The code for planetary ephemeris access.

./src/Jplstub:  Stub routines if the planetary routines are not
                wanted.  These are probably not really needed
                since the Jpl routines should compile anywhere.
                Just don't try accessing the ephemeris if you
                don't have it.

./src/Plot:     Most of the plotting routines for SCHED.

./src/PlotNRAO: A few plot routines supported at NRAO.

./src/Plotstub: The stub routines for sites that don't have
                PGPLOT.  SCHED won't link without these if 
                PGPLOT libraries are not available.

./src/Vex:      The code for writing VEX format files.

./src/Sla:      The routines from the SLALIB required by SCHED and 
                UPTIME.  This is only a subset of the SLALIB.

./PGPLOT:       Location code and libraries for PGPLOT in case 
                it is not installed on your machine already.

Any subdirectories in all capital letters are associated with code
management and testing and usually can be ignored (should not be in
the export version).  The most likely exception is if you want to
use the version of PGPLOT sent with SCHED.

For all use of SCHED, you should unpack the tar file.  It has the
catalogs, examples, standard setups, binaries for various
architectures, etc.  It also has the code in case you need to
recompile.

For certain types of computers, binary executables are provided.  As
of April 2014, those are Linux on Intel, Solaris, and Mac OSX (Intel).
All Linux versions are for 64 bit machines (LINUX64).  There is a
version with (LINUX64SPICE) and without (LINUX64) the code needed for
spacecraft tracking.  Most of the Linux versions use g77, but there is
a gfortran compilation of the 64 bit, non-satellite version.  If one
of those is what you need, your simplest installation scheme is to
copy the binary file to the bin directory, or wherever you wish to
keep your load modules.

If you need or want to compile SCHED cd to the src subdirectory.
There, for one of the architectures mentioned above and a few others,
you may be able to use one of the very short scripts, such as
configureLinux, that constructs a Makefile based on Makefile.master (if
someone can contribute a proper configure script, it would be
appreciated).  If there are problems, edit the Makefile.master to
reflect your local conditions.  Makefile.master is heavily commented
to try to make this easy.  Once you have the makefile ready, run gnu
make (the default on Linux and Mac - gmake on Sun), and SCHED should
compile and the executable should be put in the $SCHED/bin directory.
For more information, see the manual.

SCHED uses the PGPLOT routines from Caltech for plotting.  SCHED
requires PGPLOT Version 5.2 or later.  Usually these routines are
acquired independently of SCHED.  They can be installed from from the
Caltech distribution.  There is exensive documenation, including
instructions on how to get it, on the Internet at
http://astro.caltech.edu/~tjp/pgplot.  I have found the pgplot is
often available as a package for apt-get, fink and the like so check
your repositories.  Note that you may run into trouble with the 32-64
bit transition and the g77-gfortran transition when trying to use
pgplot.  Your pgplot and sched should be compiled for the same
combination.

PGPLOT version 5.3.1 is included in the SCHED tar file in the
PGPLOT subdirectory along with compiled libraries for some
architectures.  You might be able to use one of these versions,
or build your own from the code that is included.

If you cannot get pgplot, stubs are available and the comments in
the Makefile show how to use them instead of the real pgplot.  In
this case, plotting will not work, but otherwise the programs
should be fine.  Plotting is not critical for the main program
tasks.  But as of the 6 Mar 98 version, the plotting capabilities
are quite nice and it is well worth the effort of getting pgplot
installed.  It really helps with experiment planning.

SCHED understands how to get positions for the planets, the Moon and
the Sun.  For this it uses a JPL ephemeris.  It is expected that, at
least for now, this will only be used for testing and will probably
only be used at the AOC.  The emphemeris file is not included in the
distribution because of its large size.  If you need it, contact
cwalker@nrao.edu.  Also, the subroutines do not isolate machine
dependencies so they could cause problems in the installation.  If
they do, follow the directions in the Makefile to use the available
stub.  The ephemeris file (input parameter EPHFILE) is kept in a
separate directory tree.  On unix systems, the environment variable
{\tt PLANET_DATA} can be used to set the directory in which the
ephemeris is located.  Note that the emphemeris is binary so it cannot
be shared between machines that use different binary formats, such as
Sun workstations and i86 Linux boxes.

SCHED can now deal with satellites via SPICE files.  This is meant for
tracking deep space missions, not near Earth satellites, although some
targets as close as geostationary orbits have been scheduled.  Again
both the SPICE related code and the ephemeris files will not be
distributed with SCHED because they are not expected to be used
outside of the AOC and they are very bulky.

It seems that there are problems with the routine isatty on SGI
machines.  This may involve a compiler bug.  If you have this problem,
routine TSTTTY in ./src/Cit/sys_unix should just be modified to return
.FALSE. (as it does in citmsdos.for).  Or check out the alternative
in the sys_linux subdirectory.

As of the May 2002 version, SCHED can plot the locations of stations
on a map.  SCHED can read vector files to generate continental,
national, and US state boundaries and New Mexico roads (it is being
used for New Mexico Array configuration studies).  The vector files
are kept in the same directory as the ephemeris.  They are not
distributed with SCHED again because of bulk.  If you want the files,
contact cwalker@nrao.edu for information on where to pick them up.

Good luck and happy scheduling!

Between me and a concerted effort by Franco Tinarelli in Bologna,
a few years ago, SCHED has been tested on:

Current support as of April 2014
  Linux on Intel 64 bit machines using g77
  Linux on Intel 64 bit machine using gfortran
  Sun Sparc workstation using Solaris.
  Mac OS X v10.7 with gfortran on an Intel Macbook Pro  and Mac Pro.

Tested recently as of Jan 2011
  Linux on Intel 32 and 64 bit machines using g77
  Linux on Intel 64 bit machine using gfortran
  Sun Sparc workstation using Solaris.
  Mac OS X v10.6 with gfortran on an Intel Macbook Pro 
  Mac OS X v10.5 with gfortran on an Intel Mac Pro

Tested as at NRAO (Apr. 2005)
  Intel PC with LINUX using g77  (current development environment)
  SUN Sparc stations under Solaris  (actively supported at the AOC)
  Mac OS X v10.3 with g77 on PPC (First on a Mac iBook G4, Dec 2003).
  Mac OS X v10.5 with gfortran on PPC (Powerbook)

Tested not too many years ago:
  Intel PC with LINUX using fort77 (f2c and gcc).
  DEC Alpha
  HP
  SGI
  IBM with AIX (Maybe not so recent).


The Makefile contains the necessary compiler switches etc for all of
the above.  SCHED has not been tested on non-unix machines in several
years although it once worked on DOS PCs and VMS VAXs.  Note that Mac
OS X is a flavor of unix and sched is supported, and even partially
developed on this environment.  If you install SCHED on anything other
than the above please let me know.  The FORTRAN is very generic
FORTRAN77 and the known machine dependent pieces are isolated in the
sys areas so ports should be fairly easy.  A few extensions to
FORTRAN77 are used, but I have not met a compiler yet that doesn't
support them.

Most of SCHED is supported by Craig Walker at NRAO, Socorro, NM.
(cwalker@nrao.edu).  The VEX portions of SCHED are supported by Des
Small at JIVE in the Netherlands (small@jive.nl) with contributions
from Cormac Reynolds at CSIRO (cormac.reynolds@csiro.au). The
interactive plotting capabilities were supported by Franco Tinarelli in
Bologna, Italy (TINARELLI@astbo1.bo.cnr.it), although some of the
changes for configuration studies were added by Craig Walker.

Relocate to GIT