################################################################################
#                                                                              #
#  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 might experience some difficulty in installing and/or
running the software. However, people were able to use this code on
various platforms without much effort.

Since there are other packages out there such as SHTOOLS, development
is somewhat on hold. This software came out of a term project years
ago, so the coding is not very elegant. However, everything is
expected to work...


NUMERICAL ACCURACY, EFFICIENCY, AND ROBUSTNESS

A) spherical harmonic analysis: shana can use simplex integration, and
Gaussian integration, but not inverse FFT for longitudes (no reason).
If you want to determine coefficients by least squares, shana can
produce the A matrix for |Ax-y| -> 0 but the matrix inversion is not
yet built in.

B) spherical harmonic synthesis: shsyn can use efficient inverse FFT,
and simple summation.

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, but see below for
the Becker & Boschi tomography format. 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,
i.e. 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, e.g. 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:
	
	extract_layer: extract a layer from the model file. Uses linear inter-
			and extrapolation if not told else wise. 

	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


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.




