The MIT Voyager Plasma Science Code Documentation

Subsections of this html page are

• OVERVIEW

• MAKE

• SOURCE CODE

• OBJECT CODE

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
 

make
 

 
mm directory_name program_name
 

 
RUN
 

MAKE

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

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

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.

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

.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.

${DESTDIR}/lib%.a: %.c

${DESTDIR}/lib%.a: %.f

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)

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