----------------------------------------------------------------------
README
----------------------------------------------------------------------

This example creates a layered model as in example layered_halfspace/
with a water layer on top and an elastic layer below, using CUBIT.
It then runs a forward simulation which couples acoustic & elastic waves.

step-by-step tutorial:

1. go to this example directory:

     > cd EXAMPLES/waterlayered_halfspace/


2. create mesh:

   - run cubit GUI:
     > claro

     then run meshing script:
     claro -> Menu "Tools" -> "Play Journal File" ... and select file: "make_mesh_waterlayer-default.py"

     (or see other mesh examples, like "waterlayer_mesh_boundary_fig8.py" for mesh with doubling layer)

     this creates all the mesh files in subdirectory MESH/

   or

   - run python-script directly in case paths are all set correctly:

     > export PYTHONPATH=$PYTHONPATH:$MY-TRELISDIR
     > export PYTHONPATH=$PYTHONPATH:~/SPECFEM3D/CUBIT_GEOCUBIT

     > ./make_mesh_waterlayer-default.py


   or

   - to use GEOCUBIT, create mesh:
     > ./make_mesh_waterlayer.sh

   or

   - use default mesh provided in MESH-default/
     (generated by script make_mesh_waterlayer-default.py)


3. run simulation:
    
   - run script:
     > ./run_this_example.sh


Compare your seismograms in OUTPUT_FILES/ with the reference ones in directory REF_SEIS/


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

For runs on a cluster using a PBS job-scheduler, follow:


a. decompose mesh files:

    - set mesh directory in go_decomposer_pbs.bash to:
      MESHDIR=EXAMPLES/waterlayered_halfspace/MESH/

    - run decomposer:
      > qsub go_decomposer_pbs.bash

      which creates mesh partitions "proc0000***_Database" in directory "DATABASES_MPI".
      you can then specify "../OUTPUT_FILES/DATABASES_MPI" in "Par_file" for your "LOCAL_PATH"


b. generate databases:

    - compile and run generate_databases in directory SPECFEM3D/:
      > make xgenerate_databases
      > qsub go_generate_databases_pbs.bash

      this will create binary mesh files, e.g. "proc000***_external_mesh.bin"
      in directory OUTPUT_FILES/DATABASES_MPI/.
      (note: if execution fails due to memory shortage - most likely fails when calling routine to
           create regional mesh - then try to increase process memory stack size: ulimit -s 2000000  (2GB) )


c. run simulation:

    - compile and run specfem3D:
      > make xspecfem3D
      > qsub go_solver_pbs.bash

    note: a higher resolution simulation will take about 1 h 45 minutes and generate
          3 sets (semd,semv,sema) of 9 seismogram files in OUTPUT_FILES,
          as well as 10 timestamp****** files