S H E B A - Shear-wave Birefringence Analysis

June 7, 2018 · View on GitHub

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