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.
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.
All the Makefiles are built off a model Makefile in ~vgr/src/
MAKEFILE.
It in turn has "include" statements to four files,  
Make1, 
Make2, 
Make3, 
Make4.
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.
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.
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.
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.
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