#******************************************************************************#
#*                                                                            *#
#*                             FD3Dtopo-nonstaggered                          *#
#*                           =========================                        *#
#*                                                                            *#
#*                        The Fortran90 Program Package                       *#
#*            for Non-Staggered Finite-Difference Seismic Wave Modeling       *#
#*                   in 3D Complex Media with Surface Topography              *#
#*                                                                            *#
#*                                                                            *#
#*                        Wei ZHANG  and  Xiaofei CHEN                        *#
#*               email: zhangwei.zw@gmail.com, xfchen@pku.edu.cn              *#
#*             Geophysics Department, Peking University, China, 2006          *#
#*                                                                            *#
#*     A signed non-commercial agreement is required to use this program.     *#
#*             Free for non-commercial academic research ONLY.                *#
#*       This program is distributed WITHOUT ANY WARRANTY whatsoever.         *#
#*       Do not redistribute this program without written permission.         *#
#*                                                                            *#
#*                                                                            *#
#*   Managed and Maintained by Ashton FLINDERS, email: andrealphus@gmail.com  *#
#*                                                                            *#
#*                                                                            *#
#******************************************************************************#


1 Introduction

  This program simulates seismic wave propagation in 3D complex media with
  surface topography by using non-staggered finite difference method.
  We use body-fitted grid to conform the grid surface with free surface
  topography, then the non-staggered FD scheme, DRP/opt MacCormack scheme
  (Hixon,1997), is used to update the stress-velocity wave equations.
  The traction free surface boundary condition is implemented through
  Traction Image method (Zhang and Chen, 2006).

2 Directory layout

  code.vlow/
  	srcF/
  	  all source codes are here
  
  	srcF.kernel/
  	  additional source code for Frechet kernel calculations
  
  	Makefile*
  	  makefile for this package, has specific options for simulation parameters
  
  	Makefile.opt.bluewaves
  	  sets specific makefile options for compiling on the Bluewaves cluster
  
  	Makefile.inc.kernel
  	  additional makefile options for  compiling Frechet kernel code
  
  	run.make.sh
  	  script to run make to compile the source codes.
  
  config/
  	mfiles/
  	  codes/packages that might be useful for reading in data/results
  
  	crust1/
  	  the CRUST1.0 crustal seismic velocity model, see the readme for more info
  
   example/
  	grand_canyon/
  	   model_setup/
  	     matlab code to generate an initial starting model for the included example
  
  	   simulation/
  	     simulation of a source propagating at the Grand Canyon, USA

README
  this file

3 Usage
  
  1) For Bluewaves only; open up an interactive connection to a node so we are not 
  performing the following actions on the head node,
  
    interact -X -w 20:00:00
  
  2) cd into the cloned FD3Dtopo directory
  
  3) Compile the code by changing into the code.vlow/ directory, and run;
  
    ./run.make.sh
  
  4) Prepare example starting model by changing into example/grand_canyon/model_setup,
  and run;
  
    ./make_model.sh
  
  5) Exit the interactive node connection;
  
    exit
  
  6) Run the example simulation by changing into example/grand_canyon/simulation and 
  running each of the following successively, waiting for the previous to finish before
  starting the next;
  
    qsub pbs_grid_mpi.sh
    qsub pbs_metric_mpi.sh
    qsub pbs_media_mpi.sh
    qsub pbs_source_mpi.sh
    qsub pbs_station_mpi.sh
    qsub pbs_wave_mpi.sh

4 Availability and use of the program package

  Upon request from the authors.
  Contact the authors to get the latest version. 

  If you use this code for your own research, please send an email
  to Wei ZHANG <zhangwei.zw@gmail.com>
  and Xiaofei CHEN <xfchen@pku.edu.cn>
  for authorization, and cite (in BibTex format):

  @ARTICLE{Zhang2006a,
  author={W. Zhang and X.f. Chen},
  year=2006,
  title={Traction image method for irregular free surface boundaries in finite
         difference seismic wave simulation},
  journal={Geophys. J. Int.},
  volume=167,
  pages={337-353}}

  @PHDTHESIS{Zhang2006b,
  author = {W. Zhang},
  title = {Finite Difference Seismic Wave Modelling in 3D Heterogeneous Media
      with Surface Topography and its Implementation in Strong Ground Motion Study},
  school = {Peking University},
  year = {2006} }