The MIT Voyager Plasma Science Code Documentation

Subsections of this html page are

On this page, the links are often to the documentation of the object being discussed, the object itself or both. Many of the objects have been modified so that they are html code themselves while still serving their original purpose. In cases where a link to both the documentation and the object itself is wanted, a separate clickable space or '_' will appear immediately after the link and will link to the object itself.

OVERVIEW

Most of the vgr scripts are located in ~vgr/bin . Many of these are documented by the use of local man pages stored in ~vgr/man , which also documents some of the compiled code. Some of the compiled code & data files are documented with troff files in ~vgr/doc . Of particular note is the command MAN which lists which scripts have their own vgr local man pages. Source code is stored in subdirectories of ~vgr/src . Each of these directories has a Makefile for compiling and linking the code in that directory. These Makefiles are structured in such a way that code may be imported by other members of the Plasma Group. This allows any group member to modify a personal copy of any of the Plasma Group's software with out disturbing others in the group. To import a routine, one should type

cd ~/src/test
getfor resident_directory filename

It is important that the Makefile in the receiving test directory be in the correct format. The easiest way to do this is to start with a blank directory and let "getfor" make up the Makefile. "getfor" will update the Makefile every time it imports a new program, though you will have to clean it up when you are done with the program. To compile modified programs just type

 
mm
 
rather than
make
 
To link, type
 
mm directory_name program_name
 
For most Voyager programs, the
 
RUN
 
script is the best way to execute programs. It will use GETDATA and GGG to find the correct Voyager input files, concatenating them if need be. GETDATA will also try to edit out some bad data times. RUN, GETDATA and GGG have man entries which document them.

MAKE

All the Makefiles are built off a model Makefile in ~vgr/src/ MAKEFILE. It in turn has "include" statements to four files,   Make1Make2Make3Make4. These later four files are constant files, whereas the copy of MAKEFILE is modified to contain the information particular to the given directory. Make3 is often not used in test directories, unless they have routines that were not checked out from vgr.

While the "vgr"account and others use similar Makefiles, there are certain differences. "test" directories refer to the Makefiles in vgr, but not the other way around. In each source code directory, the copy of MAKEFILE is named Makefile. The vgr Makefiles will be discussed first.
The vgr Makefile will be used as an example. Up until the first include statement, to Make1 the file just defines a few macros.

DIR
Name of this directory, also used in libraries' names
VERSION
version number
VGRHOME
vgr home directory
Make1 then defines many macros
LIB
Name for the "ar", that is the static object library
DESTDIR
The destination directory where the object code & libraries will be stored.
DESTLIB
Fully qualified name of static library
DYNAR
Fully qualified name for Dynamic library (not made!)
SHARLIB
Fully qualified name of Shared so library
SHARDAT
Fully qualified name of Shared sa library
FC
Name of Fortran compiler
CC
Name of C compiler
CCC
Name of C++ compiler
LD
Name of loader
FFLAGS
Flags to be passed to Fortran compiler
CFLAGS
Flags to be passed to C compiler
CCFLAGS
Flags to be passed to C++ compiler
LDFLAGS
Flags for the loader
FORCE
A macro to allow for the forcing of some rules
CD
To allow 'cd to same directory'
FGRIND
pretty print for Fortran
CGRIND
pretty print for C
MGRIND
Two column print for long programs
VGRINC
Name of Directory where include files are stored
SYS
Name of current system hardware.
LOAD
Type of loading requested, static or dynamic
PIC
Set to type of pic code wanted if dynamic loading is to be used
HOME
Name of vgr home directory
TERM
Type of terminal to be used, x==>X-window, n==>no_window, t==>Tektronix
WIN
Loader flag for Library for ${TERM}
BEV
Loader flag for Bevington library
DL
Loader flag for Data Library library
GI
Loader flag for Peter Ford's Gipstool Library (extract) library
IM
Loader flag for Voyager Imaging library
IMP
Loader flag for IMP library
MJS
Loader flag for mjsanl library
NRC
Loader flag for Numerical Recipes C library
NRF
Loader flag for Numerical Recipes Fortran library
NWIN
Loader flag for no window plot library
PLS
Loader flag for pls library
PLT
Loader flag for PLT plot library
RSH
Loader flag for rsh library (Obsolete)
SEDR
Loader flag for sedr library
SO
Loader flag for Stan Olbert's library
TEK
Loader flag for Tektronix's library
VEC
Loader flag for vector library
VGR
Loader flag for vgr and vgranl library
XWIN
Loader flag for X-window plot library

The Makefile then defines many macros that are either combinations of the above, and/or defined for local use and should be documented in the Makefile itself.

Then follows a set of definitions that define the type of processing to be done on each of the source files

FSOURCENL
Fortran SOURCE No Library These are Fortran source files that should not be put into the directory's libraries, usually because they have external names that conflict with other code (e.g. MAIN, main or nxtmod)
FSOURCEL
Fortran SOURCE Library These are Fortran source files that should not be put into the directory's libraries, usually because they have external names that conflict with other code (e.g. MAIN, main or nxtmod)
CSOURCENL
C SOURCE No Library These are C source files that should not be put into the directory's libraries, usually because they have external names that conflict with other code (e.g. MAIN, main or nxtmod)
CSOURCEL
C SOURCE Library These are C source files whose objects do go into this directory's libraries.
CCSOURCENL
C++ SOURCE No Library These are C++ source files that should not be put into the directory's libraries, usually because they have external names that conflict with other code (e.g. MAIN, main or nxtmod)
CCSOURCEL
C++ SOURCE Library These are C++ source files whose object do go into this directory's libraries.
Makefile then includes Make2 which defines many default rules which are control default behavior of the make. (i.e. Any thing that is not defined in detail goes this way)
FSOURCE
Fortran SOURCE is the union of all Fortran routines both library and no library
CSOURCE
C SOURCE is the union of all C routines both library and no library
CCSOURCE
C++ SOURCE is the union of all C++ routines both library and no library
 
FLIBNL
A separate Dynamic library is defined for each Fortran file that is marked as No Library
CLIBNL
A separate Dynamic library is defined for each C file that is marked as No Library
 
VARIENT
Blank, no variants are defined.
 
OBJECTL
List of all objects to be put in this director's libraries
OBJECTNL
List of all objects not to be put in this directors libraries
SOURCES
List of all sources, Fortran C & C++
.PRECIOUS
make list of files that are not to be destroyed if make fails
the following are the default rules for Fortran, C and C++. Note that they check for type of loading
.f.a:
.c.a:
.cc.a:
The Fortran, C and C++ default rules. If dynamic loading is requested, make a PIC object otherwise just make a static object.
In the vgr Makefile s, and could be in test Makefile s Make3 is included. Starting out make get rules for the static Libraries in $DESTDIR for C & Fortran files.
${DESTDIR}/lib%.a: %.c
${DESTDIR}/lib%.a: %.f
Now the targets for make are defined
all
The normal default. First the Fortran & C No Library routines, then the ${DESTLIB}, i.e. all library routines.
prt
prints out the list of routines, by type that we expect
${DESTLIB>
The static directory library, which does the dynamic libraries also if requested.
clean
Cleans up all objects, not the libraries though
grind
Does a pretty print on the Fortran & C source.
printf
Does a pretty print on the new Fortran (since last printf)
printc
Does a pretty print on the new C (since last printc)
printm
Does a 2 col print on the new Makefile (since last printm)
Back in Makefile the target
dirs
print out a list of directories used. This is mostly of importance when make is run from test. Make4 is included. It mostly define targets that are of marginal interest to the normal user.
ffl
echos list of Fortran Library sources
ffnl
ccl
echos list of C Library sources
ccnl
echos list of C No library sources
CCl
echos list of C++ Library sources
CCnl
echos list of C++ No library sources
.INIT
Done before anything else
.DONE
Done after every thing else
.FAILED
done if and only if make failed
clean
clean up only objects, this may be over written by an earlier one.
grind
Does a pretty print on the Fortran & C source.
printf
Does a pretty print on the new Fortran (since last printf)
printc
Does a pretty print on the new C (since last printc)
printm
Does a 2 col print on the new Makefile (since last printm)
Back in the main Makefile is now added any special targets that the default rules will not cover. Before the development of the command RUN, the execution of many files was done with calls to make, by way of targets such as run_vgr. While these are often still in the Makefile, the use of RUN is preferred.

Examples vgr

First an example in the logical flow when a non library program has been updated. With the execution of the command make make starts with the target .INIT. The target all, being the first target in the Makefile, is built. Since all is dependent on ${FLIBNL}   ${CLIBNL}   ${DESTLIB} any of these that are out of date will be built. If a no library fortran file is out of data, the percent rule for FLIBNL will make this a dependency of all, and its rule for building its dynamic library This is followed by building .DONE if the make was successful, or building .FAILED if make failed.

For a library routine the procedure is similar. make starts with the target .INIT. The target all, being the first target in the Makefile, is built. In this case DESTLIB is built, which in turn is dependent on ${DESTLIB} (${OBJECTL} ) which will use the suffix rule .f.a which will build the static directory static library which was being tested in the DESTLIB target. will build the library.

Examples test

If you are modifying some code, the procedure is a little different. All code should be checked out in your ~/src/test directory. Here cbg's test directory will be used as an example. Starting with an empty test directory


getfor vgr vgranl.f step.f
getfor pls getunit.f
mm

were used to check out the routines vgranl & step from the vgr directory and getunit from the pls directory. "getfor" built the Makefile and modified it to know what routines had been checked out and where they came from. It also made some dummy Fortran, C and C++ routines to keep some of the Makefile macros from being empty. mm was then executed to compile the checked units. (In this case, the make was done with a -d flag to give some debugging output.) Note that the Makefile has as dependencies of all the names of all the vgr directories from which data hac been extracted and thus does a make using that vgr directory's Makefile. In this way all routines are compiles correctly, and put in the correct liraries when that is appropriate. All of this was done with script so the output was captured in a file typescript. To link a program, e.g. vgranl, the command

mm vgr vgr

would be used to use the Makefile in ~vgr/src/vgr to make the program vgr. "mm" will change many environmental variables to ensure that when there is modified code, its object is used, not the objects from the official vgr libraries.

SOURCE CODE

The official source code for the Plasma Group is stored in several sub directories of ~vgr/src. The most important of these directories are

vgr
The code that relates to the majority of the Voyager Processing
pls
General routines used by all of the PLS group
vec
Vector handling routines
mjs
MJSANL routines. detailed analysis of single Voyage spectra.
plt
General plotting package, modeled after the old Calcomp routines. Now it can interface to many devices such as xterms, printer, Tektronix terminals or no windows.
JPL
(OLD) This function has been moved to ~vgr/RUNJPL Gets the data from JPL. Does not contain Fortran or C code. Mostly Perl and shell scripts, plus quite a bit of results. No Makefile.
bev
The Bevington routines.
dl
The old Data Library routines, C++. no longer used.
gi
A conversion routine borrowed from Peter Fords Gipstool.
im
Imaging routines, that produce the Voyager color spectral plots.
imp
IMP processing routines.
jwb
Some of jwbs programs. The Makefile has not been rewritten into the correct form.
nrc
Old Numerical Recipes in C For the newer, more complete Numerical Recipes see /plas5/h1/gsg/src/nr
nrf
Old Numerical Recipes in Fortran For the newer, more complete Numerical Recipes see /plas5/h1/gsg/src/nr
nrpc
Old Numerical Recipes in Pascal
nwin
All plot output dummied.
xwin
Plot output to X-window
prd
Originally setup for production work, Which is largely done in JPL.
rsh
An old set of procedures, for splitting a job over many machines using rsh. Not used or supported.
sedr
SEDR programs for Voyager.
tek
Plot output to Tektronix terminal.
test
Director to import test versions of subroutine. On vgr this is not used, but was a model for other accounts.
so
Stan Olbert's test routine. May be used by mjsanl.

Code can be checked out from this "official" copy of the code using 'getfor' into one's test directory. It is important to use the conventions, as otherwise main of the commands man break. "mm" should be used to compile the code checked out into one's test directory, as "mm" will use the Makefile from the "official" directory.

OBJECT CODE

The version of the code that the system uses is determined by the setting of several environmental variables. These are best set using "setopts", and can be tested using the command "opts". Usually only two options are implemented, "d 4" (the debugging mode), and "o 9" (the optimized production mode). These variables will control the compiling and linking flags as well as the placement of the object code. It is possible to cadge between non comparable compilers and machines, but we try to avoid that as much as possible.

At present, the object code is placed in the directory ${vgrLIB}, (e.g. ~vgr/lib/O/9 or ~vgr/lib/g/4 for the SunOS and ~vgr/LIB/O/9 and ~vgr/LIB/g/4 for the Solaris machines). Libraries are made for all subroutines that can be put into libraries according to the source directory that they come from. Both static & dynamic libraries are made. The names of the libraries are constructed from the name of the source directory and, for the static library, are contained in an environmental variable. e.g. the static library from the vec source directory is ${vgrVEC}, and is libVGRvec.a . (Note the use of upper case, it is important.) "main" routines, and others that can not be put into libraries, (e.g. they have conflicting external names) are put into dynamic libraries, one per source code file. The final executable is just under its own name. These directories should be cleaned out of trace files every so often.



Go to top of page