===============================================================================
  S H E B A - Shear-wave Birefringence Analysis
===============================================================================
  This software is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
===============================================================================

  James Wookey, School of Earth Sciences, University of Bristol

================================================================================
INSTRUCTIONS FOR INSTALLING AND RUNNING SHEBA, THE SHEAR-WAVE SPLITTING
ANALYSIS CODE. 


--------------------------------------------------------------------------------
Section 1: Introduction

1.1 Disclaimer and terms of use

This software is distributed under the term of the BSD free software license
(see end of file for details). Basically:

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  

It may be modified for your own purposes but should not be redistributed without
sufficient reference to the fact that it has been altered. Please let me know
about any bugs that you find (especially if you have a fix for them). 

1.2 References

The code SHEBA was mostly written by James Wookey (University of Bristol), 
incorporating subroutines from a number of places. The primary reference for 
(the current state of) this code is:

Wüstefeld, A.; Al-Harrasi, O.; Verdon, J.; Wookey, J. and Kendall, J-M. (2010)
"A strategy for automated analysis of passive microseismic data to image seismic 
anisotropy and fracture characteristics ", Geophysical Prospecting, vol 58, 
755–773, DOI:10.1111/j.1365-2478.2010.00891.x

Significant portions of the underlying subroutines were written by Nick Teanby. 
The algorithm used by SHEBA for multi-window analysis is described in:

Teanby, N; Kendall, J-M. and Van Der Baan, M. (2004), "Automation of shear-wave
   splitting measurements using cluster analysis", BSSA, vol 94, pp 453-463

SHEBA also now incorporates the Quality measure from:

Wüstefeld, A.; and  Bokelmann, G., (2007). "Null Detection in Shear-Wave 
Splitting Measurements." BSSA, vol 97, 1204 – 1211.

Parts of the original calculation have been modified following:

Walsh, E., Arnold, R., & Savage, M. K. (2013). Silver and Chan revisited. 
Journal of Geophysical Research-Solid Earth, 118(10), 5500–5515. 
doi:10.1002/jgrb.50386

Various other academic papers are referenced in individual subroutines. 

--------------------------------------------------------------------------------
Section 2: Prerequisites

2.1 Operating system

     SHEBA has been compiled on run successfully on several platforms including
      Linux, MacOSX and Solaris. Other UNIX variants are likely to work, but 
      no guarantees! 

      The multiple window analysis can be quite computationally expensive, so
      older machines (for example older sparc machines) may struggle. If this
      is the case, use the 'nwind one' option. 	

2.2 SHEBA requires utilities from several packages to compile and run fully: 

	- SAC, SAC2000 or MacSAC (the sacio.a library is NOT required however)

	- GMT (several GMT programs are used for plotting). GMT version 5 is 
    required. 

	- A postscript viewer. GV is recommended (and assumed by the SAC macro).  

	- PSUTILS and GHOSTSCRIPT are required for the "plot yes" option, though
        this could potentially be circumvented. 

	- A Fortran 90 compiler. SHEBA is developed on the Gnu compiler 
	gfortran (version 4.3 or more recent is compatible). Other compilers 
	known to have worked at some point are ifort, xlf, g95 and Solaris f90. 
	G77 and other Fortran 77 compilers will NOT work. 

--------------------------------------------------------------------------------
Section 3: Compiling

	- Edit the Makefile to set up:
	    * Compiler and options. Since the code can be quite intensive, 
	      optimisation is recommended. Some suggested configurations are
	      given in the Makefile.
	    * The two path variables (MACRODIR and EXECDIR) to wherever you want 
	      the macros, scripts and binaries to wind up. Remember that these
	      must be on the SAC macro path and in your $PATH respectively so
	      that they can be found.
	    * SAC compatibility option. (e.g., MacSAC vs. sac2000)  

	- Type 'make'. This will compile all the codes, and install binaries, 
        shell scripts and SAC macros. 'make clean' will remove all object
        files to allow a clean install.   

--------------------------------------------------------------------------------
Section 4: Running the code

	- SHEBA is most easily run from the SAC macro sheba. 
        - Type, e.g.: m sheba file MYFILE comps E N Z pick yes 
          (note that an identical macro called split_sheba is provided
           for legacy reasons)
	- For (many) other options see the sheba macro
	
--------------------------------------------------------------------------------
Section 5: Stacking error surfaces

	- SHEBA also has the capacity to stack error surfaces (see Restivo and 
	  Helffrich, GJI, 1999)
	- This is done with code sheba_stack. This requires a collection of 
	  .lam2 files, which are produced for the best window in any SHEBA run. 
	  These are the error surfaces to be stacked. When sheba_stack is executed
	  it reads the file "sheba_stack.in". This should be a list of the .lam2
	  files to stack. The result is output to stdout, and the files:
			sheba_stack.sol : the splitting parameters
			sheba_stack.err : the stacked error surface. This can be 
			visualised with the script "sheba_plot_stackerr.gmt", 
			which produces an EPS file, "sheba_stack_error.eps".
		
	Command line "sheba_stack [options]" where options are:
	  -wgt [one|snr|filename] : set options for weighting surfaces, where:
			one : all surfaces have equal weighting
			snr : surfaces are weighted by their signal-to-noise ratio
			filename : the name of a file containing weights (one 
			           per line, one line per surface is required). 
				   Obviously, the file can't be called "one" or 
				   "snr". The code "sheba_wgtcalc" can help 
				   combine weights of different kinds, see 
				   source code for details.

================================================================================
  LICENSE	
================================================================================

  This software is distributed under the term of the BSD free software license.

  Copyright:
     (c) 2003-2018, James Wookey

  All rights reserved.

   * Redistribution and use in source and binary forms, with or without
     modification, are permitted provided that the following conditions are
     met:
        
   * Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.
        
   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
     
   * Neither the name of the copyright holder nor the names of its
     contributors may be used to endorse or promote products derived from
     this software without specific prior written permission.


   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

-------------------------------------------------------------------------------