s3dgrid by X.D. Li and C.H. Megnin, UCB Seismographic Station, May 1996

s3dgrid is designed to run on Sun & HP

Please reference :

Li, X.D. and B. Romanowicz, "Global Mantle Shear-Velocity Model Developed
Using Nonlinear Asymptotic Coupling Theory"< Geophys. J.R. astr. Soc., Vol 
101, No B10, 22,245-22,272, 1996

Last update : 10/24/1996
-----------------------------------------------------------------------

Our mantle models are written in a format called s3d. They 
are expanded laterally in spherical harmonics and radially 
in Legendre polynomials. 

The contents of an s3d file are the following :

At the top of the file is a header line with the following information :
smax kmaxw kmaxu kmaxl ndisc disc1, disc2,...
smax  = max spherical harmonic degree 
kmaxw = Max order of Legendre polynomial for whole mantle parametrization
        (This value is -1 if the model has two-layered parametrization)
kmaxu = Max order of upper mantle Legendre polynomial for two-layered 
	parametrization (currently 5)
kmaxl = Max order of lower mantle Legendre polynomial for two-layered 
	parametrization (currently 7)
ndisc = number of discontinuities
disc1, disc2,... = name of each of the ndisc

The models coefficients constitute the rest of the file. 
Their ordering is as follows :

		      --|	      --|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=0		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		| 
		      			|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=1		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|	Upper mantle
	.				|
	.				|
	.				|
					|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=kmaxu	|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|
		      		      --|
_________________________________________
		      --|	      --|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=0		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		| 
		      			|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=1		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|	Lower mantle
	.				|
	.				|
	.				|
					|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| k=kmaxl	|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|
		      		      --|
_________________________________________
		      --|	      --|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| disc 1	|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		| 
		      			|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| disc2		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|	Discontinuities
	.				|
	.				|
	.				|
					|
		      --|		|
C00			|		|
C10 C11 S11		|		|
C20 C21 S21 C22 S22	| ndisc		|
.			|		|
.			|		|
Csmax,0 ...		|		|
		      --|		|
		      		      --|
_________________________________________

s3dgrid.c writes the contents of an s3d file at a given depth
onto a grid. 

/* Dowloading s3dgrid() */
--------------------------
copy the file grid.tar
to 'untar' execute the command :
tar xvf grid.tar
This will generate a directory 'grid' that contains the program
& its dependencies.

/* Compiling s3dgrid() */
-------------------------
s3dgrid is stored in a separate directory. That directory
has 3 subdirectories named 'LIB', 'DUMP' & 'WORK'.
The path for the location of the executables s3dgrid.exe is 
defined as EXE at the top of the make file s3dgrid.mk and can be
redefined to accomodate the system s3dgrid() will run on. 
To compile, use the command make :
make -f s3dgrid.mk
 
The header files "---.h" should be in the 'LIB' directory
The object files "---.o" are output to the 'DUMP' directory 
The executable 's3dgrid.exe' is output by default to the 'DUMP'
directory. This can be modified by changing the default path
in s3dgrid.mk

/* Default parameters */
------------------------
The defaut parameters are in the file griddefault.dat in the 'LIB'
subdirectory. Two parameters can be changed :
Row & Col correspond to the latitude & longitude mesh respectively.
The default values are set to 37 X 73. This will generate a grid on a
5 degree by 5 degree mesh. (s3dgrid computes the model value at both
phi=0 & 360 degrees but only outputs the value at 0 degree). 
The values for a partcular mesh should be should be :
Row=[180/(# of degrees) + 1]
Col=[360/(# of degrees) + 1]
eg/ : to change the mesh to 1 degree by 1 degree, set the values to
181 & 361. 
The other default parameters in griddefault.dat should not be altered.

/* Running s3dgrid() */
-----------------------
s3dgrid should be run from the shell file s3dgrid located in the 'WORK'
directory. This file should be altered, if necessary, to include 
the proper path for the executable which is located, by default in the
'DUMP' directory.

/* Output */
------------
s3dgrid() outputs the values of d ln(Vs) at a given depth.
The output format is on 3 columns :
theta, phi, d ln(Vs)
where :
theta=colatitude : 0 = North Pole to 180 = Southe Pole
phi=longitude    : 0 = Greenwich
    d ln(Vs)     : % deviation from PREM
written to a file named 'grid.dat'.

After each run, the previous file 'grid.dat' is erased and
replace by the new grid. 'grid.dat' should thus be renamed 
after each new call to s3dgrid(). 

Please address all questions related to s3dgrid.c by email to 
Charles Megnin : pepe@seismo.berkeley.edu