################################################################################
#                                                                              #
#  README for the shansyn package: spherical harmonic analysis and synthesis   #
#                                                                              #
#                                                                              #
#  for license and copyrights, see the file COPYRIGHT.                         #
#                                                                              #
#    Copyright (C) 1999 - 2005  Thorsten W. Becker                             #
#                               twb@usc.edu                                    #
#                                                                              #
################################################################################

	This is the README file with brief instructions for
installation and usage of the 'shansyn' package of spherical harmonics
analysis and synthesis tools for UNIX/GMT environments, hereafter
simply referred to as shansyn. For the copyrights for various parts of
shansyn, which might or might not be held by me, see the file
COPYRIGHT.


PLEASE NOTE: 

	shansyn is still in the beta phase and not 'officially'
released. This means that you will likely experience some difficulty
in installing and/or running the software. Most programs tell the user
what they do when they are invoked with the '-h' option and most
routines are fairly thoroughly tested to work up to very high (~>300)
degrees. However, you might still get confusing and/or erroneous
results due to inappropriate usage or programming errors.

	Please notify me if you find any bugs or inconsistencies.
However, please also try to solve the problem first yourself since I
do not have much time for 'support'.  Thanks! And: No guarantees
whatsoever.


INSTALLATION:

	You will have to have netcdf and GMT installed to compile most
of the tools. Modify the file machine_dependent.m that gets read in
from the Makefile to suit your local settings and compiler
flags. There are comments in both files, refer to them for further
instructions. Successful compilations have been reported under IRIX,
Solaris, and LINUX.

- ARCH:

	To compile all programs, first define an environment variable
ARCH, and then type 'make' in the shansyn directory. Various tools
should be compiled and then put into the 'bin/$ARCH/' directory where
ARCH is the architecture type which you will have to define (see
machine_dependent.m). After compilation, you should put the
aforementioned directory in your path as defined in the .cshrc or
similar. I will assume you have done that in the remainder.

- GMT_DIR and NETCDF_DIR:

The makefile looks in $(GMT_DIR)/src/ for the GMT include files, and 
searches in $(NETCDF_DIR)/include for the netcdf .h files. Libraries are 
expected in $(GMT_LIB_DIR) and $(NETCDF_DIR)/lib/




MAIN PROGRAM USAGE:

	The main programs are 'shana' and 'shsyn' for spherical
harmonic analysis and synthesis (go from spatial data to spherical
harmonic coefficients and vice versa, respectively). All program use
the theoretical physics normalization for real spherical harmonics as
in Dahlen and Tromp ('Theoretical Global Seismology', Princeton
University Press, Appendix B.8 and p. 859, 1998). You can use
'abconvert' to convert to other formats, though. All other binaries
might be of limited interest to the general public. Again, you can
obtain a short man page from each program by typing 'program -h'.


Examples:

	a)	

	shana 40 etopo5.0.25 > etopo5.40.ab

	Take the GMT grd file etopo5.0.25.grd and expand it up to
	l_{max}=40, write the result in the standard ASCII format to
	the file etopo5.40.ab.



	b)

	cat etopo5.40.ab | abconvert 2 > etopo5.40.pwr


	Compute the power per degree and unit area as in Dahlen and
	Tromp (1998, B.8) and write the result in ASCII format to
	etopo5.40.pwr.



	c)

	cat etopo5.40.ab | shsyn 1 0 etopo5.40

	Expand the spherical harmonic coefficients in etopo5.40.ab on
	a 1 degree by 1 degree grd file named etopo5.40.grd using
	simple summing. 

        
        d)


        shana 50 d.1 > d1.ab ; shana 50 d.2 > d2.ab; cat d1.ab d2.ab | abconvert 5

	Compute the correlation per degree and unit area up to L=50 for
	GMT grd files d.1.grd and d.2.grd.

	

SUPPORT PROGRAM USAGE:

	Shansyn also comes with several program that deal with 'model'
files, ie. sets of spherical harmonics expansions at different depth
levels as used, for example, in describing scalar fields such as wave
speed anomalies in a 3-D geometry, eg. the Earth's mantle. The model
file format is described on

	http://geodynamics.usc.edu/~becker/tomography/ 

and the corresponding Becker & Boschi (G-Cubed, 2001) article. The
following programs deal with model files:
	
	cmodelpower: calculate the spectral power of a model per depth

	cmodelmeancorr: calculate the mean correlation between two
			models 

	cmodelcorr: calculate the correlation between models per depth

	cradialcorr: calculate the radial correlation function of a
			model

	extract_model_depths: extract the depths of the expansion
		layers of a model

	scale_model: scale all layers of a model with scalar

	modmodellmax: modify the nominal L_max of a model file

	extract_layer: extract a layer from the model file 

Example:

	extract_layer s362d1.31.m.ab 500 | shsyn 1 1 d.500

		extract spherical harmonics expansion layer at depth
		500 from model file s362d1.31.m.ab and expand at one
		degree resolution into GMT grd file named d.500.grd




This is clearly not an exhaustive description of usage but should get
you started. Good luck.




