Difference between revisions of "CVM-H User Guide"

From SCECpedia
Jump to navigationJump to search
 
(44 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This PDF file can be downloaded directly from:
+
The CVM-H 11.9.1 user guide in PDF format can be downloaded directly from: [[File:cvmh_manual.pdf]].
http://hypocenter.usc.edu/research/cvmh/11.2.0/cvmh_manual.pdf
+
 
  
 
= Overview =
 
= Overview =
Line 6: Line 6:
 
The SCEC CVM-H is a 3D model of the elastic structure of southern California. It contains volumetric representations of compressional wave velocity (Vp), shear wave velocity (Vs), and density (rho). It also contains three primary surfaces: the topological/bathymetric surface, the basement surface, and the Moho surface. The model is constructed from numerous datasets (Süss and Shaw, 2003) and has been used within parallel-computing based wavefield simulations of earthquakes within southern California (e.g., Komatitsch et al., 2004). See Section 6 for details.
 
The SCEC CVM-H is a 3D model of the elastic structure of southern California. It contains volumetric representations of compressional wave velocity (Vp), shear wave velocity (Vs), and density (rho). It also contains three primary surfaces: the topological/bathymetric surface, the basement surface, and the Moho surface. The model is constructed from numerous datasets (Süss and Shaw, 2003) and has been used within parallel-computing based wavefield simulations of earthquakes within southern California (e.g., Komatitsch et al., 2004). See Section 6 for details.
  
= Downloading CVM-H =
 
 
1. Start at SCEC website: [http://scec.usc.edu/scecpedia/CVM-H http://scec.usc.edu/scecpedia/CVM-H]
 
 
2. Read the description of the model.
 
 
3. Navigate to the Source Code section and click the download link to download the latest version.
 
NOTE: this file is large (500 MB), so the download make take awhile.
 
  
 
= Requirements =
 
= Requirements =
  
 
The system requirements are as follows:
 
The system requirements are as follows:
# UNIX operating system (Linux, Solaris, MacOS)
+
# UNIX operating system with minimum 2 GB RAM (tested on Linux and SunOs, limited support on Solaris and MacOS)
# GNU make
 
 
# tar for opening the compressed files
 
# tar for opening the compressed files
 +
# GNU make (gmake)
 +
# GNU C compiler (gcc)
 
# Optionally GTS (GNU Triangulated Surface Library) for cvmdist [http://gts.sourceforge.net http://gts.sourceforge.net]
 
# Optionally GTS (GNU Triangulated Surface Library) for cvmdist [http://gts.sourceforge.net http://gts.sourceforge.net]
 
# Optionally GMT (Generic Mapping Tools) to generate plots from vx_slice [http://www.soest.hawaii.edu/gmt/ http://www.soest.hawaii.edu/gmt/]
 
# Optionally GMT (Generic Mapping Tools) to generate plots from vx_slice [http://www.soest.hawaii.edu/gmt/ http://www.soest.hawaii.edu/gmt/]
 +
  
 
= Installation =
 
= Installation =
  
Download the latest version tarball and untar into a ./cvmh subdirectory with this command:
+
The quick start steps for installing the distribution are:
 +
# Download package, check md5 sums, and untar distribution ('tar zxvf cvmh-11.9.1.tar.gz')
 +
# Configure software for your platform ('./configure')
 +
# Build software with 'make'
 +
# Check build with 'make check', verifying that all tests pass
 +
# Install software into target directory with 'make install'
 +
 
 +
These steps are described in greater detail within the following sections.
 +
 
 +
== Download ==
 +
 
 +
Start at SCEC website: [http://scec.usc.edu/scecpedia/CVM-H http://scec.usc.edu/scecpedia/CVM-H]. Navigate to the Downloads section of the [[CVM-H]] web page.
 +
Click the download link to download the latest source code distribution file. This is typically posted as a tar and gzipped file (tgz format). The source code distribution file is large (500 MB), so the download make take awhile. Click the download link to the latest md5sum file. This file can be used to confirm you have downloaded an undamaged source code distribution file.
 +
 
 +
 
 +
== Checksum Test ==
 +
 
 +
After you've downloaded the two files to your local system, the next step is to compare the checksum of your downloaded file with our pre-computed md5.
 +
You should next verify that the ''md5sum'' command is in your path:
 +
 
 +
$ which md5sum
 +
 
 +
You should get something like /usr/bin/md5sum. If you see the message 'no md5sum in...', contact your Linux system administrator and ask to have md5sum added to your path, or add the md5sum to your path yourself by editing by editing your login shell script.
 +
 
 +
Once you can run the ''md5sum'' command, you should put the two files you downloaded together in the same directory. The two files will be named something like cvmh_11.9.1.tar.gz and cvmh_11.9.1.tar.gz.md5. Run the following command to perform the md5 comparison:
 +
 
 +
$ md5sum -c cvmh-11.9.1.tar.gz.md5
 +
 
 +
You should see the message:
 +
 
 +
  cvmh_11.9.1.tar.gz: OK
 +
 
 +
If you get "FAILED" instead, re-download the tgz files and try again. When it passes, that means the files were downloaded without error.
 +
 
  
% tar zxvf cvmh_11.2.0.tgz
+
== Basic Install ==
  
 +
Once the file has passed the checksum test, untar into a ./cvmh subdirectory with this command:
  
Optionally, download the md5 checksum (cvmh_11.2.0.tgz.md5) as well and verify that it matches the value computed with the command:
+
$ tar zxvf cvmh-11.9.1.tar.gz
  
% md5sum cvmh_11.2.0.tgz
+
Once unpacked, you should see these files:
 +
 
 +
<pre>
 +
AUTHORS -- Author list
 +
aux-config -- Autoconf config directory
 +
build.xml -- ANT build and compilation script
 +
ChangeLog -- Revision history
 +
configure -- Configure utility
 +
configure.ac -- Autconf config
 +
COPYING -- License and disclaimer
 +
doc -- Documentation directory including user guide
 +
gctpc -- GCTPC projection library
 +
INSTALL -- Installation instructions
 +
m4 -- Autoconf macros
 +
Makefile.am -- Automake makefile template
 +
model -- Model directory containing voxet files
 +
NEWS -- News file
 +
README -- README documentation
 +
scripts -- Directory containing helper scripts
 +
src -- Source directory
 +
test -- Directory containing unit and acceptance tests
 +
</pre>
  
  
Once unpacked, the files you should see are these:
+
The package is configured and built by executing the following commands:
  
 
<pre>
 
<pre>
bin -- directory containing model files and executables
+
$ cd ./cvmh-11.9.1
build.xml -- ANT build and compilation script
+
$ ./configure --prefix=${CVMH_INSTALL_DIR}
CMxVM_Model3D_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 4
+
$ make
CMxVM_Model3D_CM_BASE_Folded.dxf -- top of the basement as dxf format
+
 
CMxVM_Model3D_CM_BASE_Folded.ts -- top of the basement as tsurf
+
where:
CVMH_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 5
+
${CVMH_INSTALL_DIR} : target directory where you want the CVM-H package installed
CVMH_Moho.ts -- Moho surface
 
doc -- directory containing documentation including user guide
 
gctpc -- projection library
 
include -- header files for C API
 
interpolate -- directory with routines for inverse distance weighted interpolation
 
lib -- directory for VX C API library file
 
Makefile -- for compilation
 
README -- README documentation
 
src -- directory for source files
 
test -- directory for unit/acceptance tests
 
ts2gts.awk -- script to translate from .ts to .gts
 
ts2gts.sh -- run script for ts2gts.awk
 
viz -- directory for simple GMT visualization of horizontal slices from CVM
 
 
</pre>
 
</pre>
  
The package is built by executing the following commands:
+
As one example, if you wanted to install the distribution in the following directory:
 +
/home/scec-00/eworks/cvmh
 +
 
 +
you could type the command this way
 +
./configure --prefix=/home/scec-00/eworks/cvmh
 +
 
 +
You will need permission to write to the directory you specify in this command. If the directory you specify does not exist, the installer will try to create it.
 +
 
 +
Once the configure completes without errors, make the executables by making the distribution:
 +
 
 +
<pre>
 +
$make
 +
</pre>
 +
 
 +
 
 +
Once you build and install CVM-H, several sub-directories will be written to the directory you specified, including ./bin ./include ./lib and ./model.
 +
 
 +
The distribution should build in one minute or less. The build can be checked with the following command:
 +
 
 +
<pre>
 +
$ make check
 +
</pre>
 +
 
 +
A series of unit and acceptance tests will be executed. They should all pass. The package is installed in the prefix target directory that you specified with ./configure using the following command:
 +
 
 +
<pre>
 +
$ make install
 +
</pre>
 +
 
 +
At this point, you can use CVM-H normally.
 +
 
 +
== Advanced Install ==
 +
 
 +
CVM-H may be linked with the optional GTS package which allows the binary executable cvmdst to be built. The program cvmdst calculates the distance to and the location of the closest points on the topographic/bathymetric, top of the basement, and Moho surfaces which are provided with CVM-H. The input file has the same format as the input file to vx, the query code to CVM-H.
 +
 
 +
The following configure command shows how CVM-H with the optional cvmdst may be built:
 +
 
 +
<pre>
 +
$ cd cvmh-11.9.1
 +
$ ./configure --prefix=${CVMH_INSTALL_DIR} --with-gts --with-gts-lib-path="${GTS_LIB_DIR}" --with-gts-include-path="${GTS_INCL_DIR}"
 +
$ make; make check; make install
 +
</pre>
 +
 
 +
where ${CVMH_INSTALL_DIR} is the CVM-H installation directory of choice, and ${GTS_LIB_DIR} and ${GTS_INCL_DIR} are the paths to the GTS libraries and headers, respectively.
  
% cd ./cvmh
 
% make all
 
  
 
== Unit Tests ==
 
== Unit Tests ==
  
A set of unit tests may be executed to ensure that the CVM-H software has been installed correctly. These are organized into three test suites: vx Test Suite, vx_lite Test Suite, and C API Test Suite. Unit test execution time is approximately 1-2 minutes total.
+
A set of unit tests may be executed to ensure that the CVM-H software has been compiled and installed correctly. These are organized into three test suites: vx Test Suite, vx_lite Test Suite, and C API Test Suite. Unit test execution time is approximately 1-2 minutes total. These tests are automatically executed as part of a 'make check' but they may also be run separately as described here.
  
 
* vx Test Suite: Failure of any of these tests could indicate a problem with either the vx utility, the underlying model, or the reference data set used for comparison.
 
* vx Test Suite: Failure of any of these tests could indicate a problem with either the vx utility, the underlying model, or the reference data set used for comparison.
Line 86: Line 163:
  
  
Execute all of the unit tests with the following commands, starting in the main CVM-H distribution directory:
+
All of the unit tests can be executed manually with the following commands, starting in the main CVM-H distribution directory:
  
  % cd ./test
+
  $ cd ./test
  % ./unittest
+
  $ ./unittest
 +
 
 +
The tests print results to the screen as they run, and they should complete within 5 minutes. All tests should pass. If any tests do not pass, your operating system or compiler may not be supported. You can report problems to the help email software (at) scec.org and we can provide full information on supported operating system and compiler versions.
  
All tests should pass.
 
  
 
== Acceptance Tests ==
 
== Acceptance Tests ==
  
A set of acceptance tests may be executed to check the end-to-end functionality of vx and vx_lite. These tests are organized into a single test suite. Acceptance test execution time is approximately 2-5 minutes total depending on system performance.
+
A set of acceptance tests may be executed to check the end-to-end functionality of vx and vx_lite. These tests are organized into a single test suite. Acceptance test execution time is approximately 2-5 minutes total depending on system performance. These tests are automatically executed as part of a 'make check' but they may also be run separately as described here.
  
 
* Accept Test Suite: Failure of any of these tests could indicate a problem with either the vx/vx_lite utility, the underlying model, or the reference data set used for comparison.
 
* Accept Test Suite: Failure of any of these tests could indicate a problem with either the vx/vx_lite utility, the underlying model, or the reference data set used for comparison.
Line 103: Line 181:
 
** Extract large grid with vx_lite in elevation offset mode Test
 
** Extract large grid with vx_lite in elevation offset mode Test
  
Execute all of the acceptance tests with the following commands, starting in the main CVM-H distribution directory:
+
All of the acceptance tests can be executed manually with the following commands, starting in the main CVM-H distribution directory:
  
  % cd ./test
+
  $ cd ./test
  % ./accepttest
+
  $ ./accepttest
 +
 
 +
The tests print results to the screen as they run, and they should complete within 5 minutes. All tests should pass. If any tests do not pass, your operating system or compiler may not be supported. You can report problems to the help email software (at) scec.org, and we can provide full details on supported operating system and compiler versions.
  
All tests should pass.
 
  
 
= Model Description =
 
= Model Description =
Line 128: Line 207:
 
| Origin (SW) : 131000 3431000<br>(120d51m43.301sW 30d57m23.387sN)<br>NE-Corner : 828000 4058000<br>(113d19m58.583sW 36d36m46.622sN)
 
| Origin (SW) : 131000 3431000<br>(120d51m43.301sW 30d57m23.387sN)<br>NE-Corner : 828000 4058000<br>(113d19m58.583sW 36d36m46.622sN)
 
| Same as LR
 
| Same as LR
| Origin (NW) : 371053.25 3774000 (-119.322991 / 33.013591)<br>NE-Corner : 417052.25 3774000 (-117.257011 / 33.034954)<br>SW-Corner : 371053.25 3725250 (-119.371155 / 34.770882)
+
| SW: 371052.25 3725250.0<br>(118d23m26.686sW 33d39m33.533sN)<br>SE: 417052.25 3725250.0<br>(117d53m40.875sW 33d39m50.043sN)<br>NW: 371052.25 3774000.0<br>(118d23m52.427sW 34d5m55.914sN)<br>NE: 417052.25 3774000.0<br>(117d53m57.439sW 34d6m12.699sN)
 
| Origin (SW) : -31000.0 3410000.0<br>NE-Corner : 849000.0 4274000.0<br>Depth : 0-350m
 
| Origin (SW) : -31000.0 3410000.0<br>NE-Corner : 849000.0 4274000.0<br>Depth : 0-350m
 
|-
 
|-
Line 137: Line 216:
 
| 250m x 250m
 
| 250m x 250m
 
|}
 
|}
 +
 +
 +
The following diagram illustrates the regions spanned by each model:
 +
 +
[[File: Cvmh_model_boundaries.png]]
  
  
Line 169: Line 253:
 
== Geotechnical Layer ==
 
== Geotechnical Layer ==
  
A near-surface geotechnical layer (GTL) exists in the vx_lite utility and C API, derived from a Vs30 map of southern California as described in (Ely, 2010). The GTL extends from the free surface down to a transition depth of at least 350m. Vp, Vs, and density (rho) at the free surface are derived from the Vs30 values with the following relations:
+
A near-surface geotechnical layer (GTL) exists in the vx_lite utility and C API, derived from a Vs30 map of southern California as described in (Ely, et al. (2010)). The Vs30 map was constructed from two datasets: an interim high-resolution rasterized Vs30 map for California described in (Wills and Clahan (2006)), and a Vs30 map for points outside of California described in (Wald, et al. 2007). The two datasets were combined with no interpolation.
 +
 
 +
The GTL extends from the free surface down to a transition depth of at least 350m. Vp, Vs, and density (rho) at the free surface are derived from the Vs30 values with the following relations:
  
  Vs = Vs30
+
<pre>
 +
  Vs = 1/2 * Vs30
  
 
  Vp = 0.9409 + Vs30 * (2.0947 - Vs30 * (0.8206 - Vs30 * (0.2683 - Vs30 * 0.0251)))
 
  Vp = 0.9409 + Vs30 * (2.0947 - Vs30 * (0.8206 - Vs30 * (0.2683 - Vs30 * 0.0251)))
Line 179: Line 266:
 
   rho = 1000.0;
 
   rho = 1000.0;
 
  }
 
  }
 +
</pre>
 +
  
 +
Vp and rho are taken from Brocher (2005).
  
Between depth 0m and the transition depth (>=350m),  Vp, Vs, and rho are interpolated between the above material properties and the Vp, Vs, and rho as reported by the CVM-H LR/CM/HR/1D model at the transition depth. The interpolation relation is described in (Ely, 2010). The transition depth is nominally 350m but may be greater to accomodate points in which topo - mtop > 350m. At these points, the transition depth is increased to topo - mtop so that data is guaranteed to be available.
+
Between depth 0m and the transition depth (>=350m),  Vp, Vs, and rho are interpolated between the above material properties and the Vp, Vs, and rho as reported by the CVM-H LR/CM/HR/1D model at the transition depth. The non-linear interpolation relation is described in Ely et al. (2010). The transition depth is nominally 350m but may be greater to accomodate points in which topo - mtop > 350m. At these points, the transition depth is increased to topo - mtop so that data is guaranteed to be available.
  
 
The GTL may be turned off in source code. Set the ENABLE_GTL flag in ./src/vx_sub.c to False, and recompile, to disable the Vs30-derived GTL with vx_lite and the C API. The vx utility does not support a GTL at this time.
 
The GTL may be turned off in source code. Set the ENABLE_GTL flag in ./src/vx_sub.c to False, and recompile, to disable the Vs30-derived GTL with vx_lite and the C API. The vx utility does not support a GTL at this time.
Line 339: Line 429:
  
 
See the vx_lite Utility and C API sections later in this guide for instructions on how to enable this optional query mode.
 
See the vx_lite Utility and C API sections later in this guide for instructions on how to enable this optional query mode.
 
  
 
= Extracting Values from CVM-H =
 
= Extracting Values from CVM-H =
Line 365: Line 454:
 
|-
 
|-
 
| vx_lite
 
| vx_lite
| Yes
+
| Optional (default on)
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 373: Line 462:
 
|-
 
|-
 
| C API
 
| C API
| Yes
+
| Optional (default on)
 
| Yes
 
| Yes
 
| Yes
 
| Yes
Line 389: Line 478:
 
=== vx Utility ===
 
=== vx Utility ===
  
The vx code provides output consistent with directly querying the voxet in the Gocad software,
+
The vx code provides output consistent with directly querying the voxet in the Gocad software, and gives the position of the cell centers from which the data are provided. Also, elevation of the topographic, basement and Moho surfaces are provided, at the closest grid point to the input coordinates. Additional details are listed in Tables 5 and 6. For usage details, type vx -h. From the ${CVMH_INSTALL_DIR}/model directory, try feeding the test points into the program. The test file (./test/test_data/test.dat from the s/w distribution), contains eight input points:
and gives the position of the cell centers from which the data are provided. Also, elevation of
 
the topographic, basement and Moho surfaces are provided, at the closest grid point to the input
 
coordinates. Additional details are listed in Tables 5 and 6. For usage details, type vx -h.
 
From the bin directory, try feeding the test points into the program. The test file, /bin/test_data/test.dat,
 
contains eight input points:
 
  
 
  -125 35 -7777
 
  -125 35 -7777
Line 405: Line 489:
 
  408669 3766189 -3000
 
  408669 3766189 -3000
  
Note that the input can be either (lon, lat, elevation) or (UTMx-11, UTMy-11, elevation).
+
Note that the input can be either (lon, lat, elevation) or (UTMx-11, UTMy-11, elevation). Execute vx with the test file using this command:
Execute vx with the command:
+
 
 +
<pre>
 +
$ cd ${CVMH_INSTALL_DIR}/model
 +
$ ../bin/vx < ${CVMH_UNTAR_DIR}/test/test_data/test.dat
 +
 
 +
where:
 +
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
 +
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.
 +
</pre>
  
% ./vx < ./test_data/test.dat
 
  
 
The output has 8 rows and 18 columns (Table 5) and should look like this (here the columns are truncated):
 
The output has 8 rows and 18 columns (Table 5) and should look like this (here the columns are truncated):
Line 592: Line 683:
 
=== vx_lite Utility ===
 
=== vx_lite Utility ===
  
The vx_lite utility is a new SCEC-developed interface which supports a number of enhancements, including query by depth, extension of the coverage region with a SCEC 1D model, and replacement of the original GTL with a Vs30-derived GTL.
+
The vx_lite utility is a new SCEC-developed interface which supports a number of enhancements, including query by depth, extension of the coverage region with a SCEC 1D model, and replacement of the original GTL with a Vs30-derived GTL. The command line format for vx_lite is as follows:
  
The command line format for vx_lite is as follows:
+
<pre>
 +
    vx_lite - (c) Harvard University, SCEC
 +
Extract velocities from a simple GOCAD voxet. Accepts
 +
geographic coordinates and UTM Zone 11, NAD27 coordinates in
 +
X Y Z columns. Z is expressed as elevation offset by default.
  
% vx_lite [-s] [-d] [-v] [< input_coords]
+
        usage: vx_lite [-g] [-s] [-m dir] [-z dep/elev/off] < file.in
  
where the options:
+
Flags:
;-s
+
        -g disable GTL (default is on).
: Instructs use of SCEC 1D background model
+
        -s directs use of SCEC 1D background and topo.
;-d
+
        -m directory containing model files (default is '.').
: Interpret z coordinate as depth from free surface
+
        -z directs use of dep/elev/off for Z column (default is offset).
;-v
 
: Interpret z coordinate as elevation
 
;input_coords
 
: 3D point specified as either (lon, lat, z (meters)) or (easting, northing, z (meters)), space delimited. Input coordinates can be specified interactively or redirected to stdin from a file.
 
  
Note: Options -d and -v are mutually exclusive. Specifying neither option instructs vx_lite to interpret the z coordinate as elevation offset from free surface.
+
Output format is:
 +
        X Y Z utmX utmY elevX elevY topo mtop base moho hr/lr/cm cellX cellY cellZ tg vp vs rho
 +
 
 +
</pre>
 +
 
 +
where file.in is a list of 3D points specified as either (lon, lat, z (meters)) or (easting, northing, z (meters)), space delimited. Input coordinates can be specified interactively or redirected to stdin from a file.
 +
 
 +
Note: Specifying no Z coordinate option instructs vx_lite to interpret the z coordinate as elevation offset from free surface.
  
 
The query data is printed to stdout, and this may be redirected to a file.  
 
The query data is printed to stdout, and this may be redirected to a file.  
  
  
CVM-H defines a set of sample test points (given in ./bin/test_data/test.dat):
+
CVM-H defines a set of sample test points (given in ./test/test_data/test.dat of the s/w distribution):
  
 
  -125 35 -7777
 
  -125 35 -7777
Line 627: Line 725:
 
These may be submitted to vx_lite with this command:
 
These may be submitted to vx_lite with this command:
  
% ./vx_lite -s -v < ./test_data/test.dat
+
<pre>
 +
$ cd ${CVMH_INSTALL_DIR}/bin
 +
$ ./vx_lite -s -z elev -m ../model < ${CVMH_UNTAR_DIR}/test/test_data/test.dat
  
 +
where:
 +
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
 +
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.
 +
</pre>
  
The material properties at the sample points will be printed to stdout. You can expect to see the following output, annotated here with column headers (the columns are truncated):
+
The example above selects the model directory to use (../model), selects elevation coordinate mode, and enables the SCEC 1D background model. The material properties at the sample points will be printed to stdout. You can expect to see the following output, annotated here with column headers (the columns are truncated):
  
 
<pre>
 
<pre>
Line 738: Line 842:
  
 
<pre>
 
<pre>
/* Source: Example.c */
+
/* Source: Example.c */
  
#include "vx_sub.h"
+
#include <stdio.h>
 +
#include <stdlib.h>
 +
#include "vx_sub.h"
  
int main (int argc, char *argv[])
+
int main (int argc, char *argv[])
{
+
{
 
   vx_entry_t entry;
 
   vx_entry_t entry;
 
+
  double depth;
 +
 
 
   /* Perform setup */
 
   /* Perform setup */
   if (vx_setup(".") != 0) {
+
   if (vx_setup(argv[1]) != 0) {
 
     printf("Failed to init vx\n");
 
     printf("Failed to init vx\n");
 
     exit(1);
 
     exit(1);
Line 762: Line 869:
  
 
   /* Setup point to query */
 
   /* Setup point to query */
   entry.coor[0] = -120.0;
+
   entry.coor[0] = -118.0;
   entry.coor[1] = 35.0;
+
   entry.coor[1] = 34.0;
   entry.coor[2] = 100.0;
+
 
 +
  /* Work-around for Trac issue #6: Depth value over-written in vx_getcoord() */
 +
  depth = 100.0;
 +
   entry.coor[2] = depth;
  
 
   /* Query the point */
 
   /* Query the point */
Line 770: Line 880:
  
 
   /* Print results */
 
   /* Print results */
   printf("Vp: %lf, Vs: %lf, Rho: %f", entry.vp, entry.vs, entry.rho);
+
   printf("Lon: %lf, Lat: %lf, Z: %lf, Vp: %lf, Vs: %lf, Rho: %f", entry.coor[0], entry.coord[1], depth, entry.vp, entry.vs, entry.rho);
 +
 
 +
  /* Cleanup */
 +
  vx_cleanup();
  
 
   return(0);
 
   return(0);
}
+
}
 
</pre>
 
</pre>
  
Line 779: Line 892:
 
= Extracting Distances to Surfaces in CVM-H =
 
= Extracting Distances to Surfaces in CVM-H =
  
There is also an additional program, cvmdst, to compute the the distance to, and the location,
+
There is an additional program, cvmdst, to compute the the distance to, and the location, of the closest points on the topographic/bathymetric, top of the basement, and Moho surfaces which are provided with CVM-H. The input file has the same format as the input file to vx, the query code to CVM-H. To use this capability, you need GTS (GNU Triangulated Surface Library), available from http://gts.sourceforge.net (using a Linux-Ubuntu platform, it may be as simple as installing all "gts" packages from the Synaptic Package Manager) and rebuild CVM-H. See the Advanced Install section on how to do this.  
of the closest points on the topographic/bathymetric, top of the basement, and Moho surfaces
 
which are provided with CVM-H. The input file has the same format as the input file to vx, the
 
query code to CVM-H.
 
  
To use this capability, you need GTS (GNU Triangulated Surface Library), available from
+
Once built, try the program with the same test data as before (note that you must be in the model directory):
http://gts.sourceforge.net. (Using a Linux-Ubuntu platform, it may be as simple as installing
 
all "gts" packages from the Synaptic Package Manager.) With GTS installed, you can
 
now compile. From the main cvmh directory, compile with this command:
 
  
% make cvmdst
+
<pre>
 +
$ cd ${CVMH_INSTALL_DIR}/model
 +
$ ../bin/cvmdst < ${CVMH_UNTAR_DIR}/test/test_data/test.dat > ofile2.dat
  
This will create a cvmdst executable in the ./bin directory.
+
where:
 
+
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
Try the program with the same test data as before:
+
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.
 
+
</pre>
% cd bin
 
% ./cvmdst < ./test_data/test.dat > ofile2.dat
 
  
 
The output file ofile2.dat has 17 columns described in the table below. Note that the basement surface
 
The output file ofile2.dat has 17 columns described in the table below. Note that the basement surface
Line 883: Line 990:
 
The vx_slice utility is a new SCEC-developed interface for extracting horizontal slices from CVM-H that are suitable for plotting. The command line format for vx_slice is as follows:
 
The vx_slice utility is a new SCEC-developed interface for extracting horizontal slices from CVM-H that are suitable for plotting. The command line format for vx_slice is as follows:
  
vx_slice [-s] [-d] [-v] [-g gridsize] [-f outfile] -- <x1> <y1> <x2> <y2> <elev/depth> <value_type>
+
<pre>
 +
    vx_slice - (c) Harvard University, SCEC
 +
Extract a map of velocities from a simple GOCAD voxet for a regular
 +
grid within the specified region at the specified depth/elev. Accepts
 +
geographic/UTM coordinates for the geographic region. Outputs gridded
 +
data suitable for plotting in MATLAB or GMT.
 +
 
 +
        usage: vx_slice [-g] [-s] [-m dir] [-z dep/elev/off] [-r gridsize] [-f outfile] -- <x1> <y1> <x2> <y2> <z> <value>
  
where the options:
+
Flags:
;-s
+
        -g disable GTL (default is on).
: Instructs use of SCEC 1D background model
+
        -s directs use of SCEC 1D background and topo.
;-d
+
        -m directory containing model files (default is '.').
: Interpret z coordinate as depth from free surface
+
        -z directs use of dep/elev/off for Z column.
;-v
+
        -r flag is gridsize in degrees/meters. Defaults to 0.1.
: Interpret z coordinate as elevation
+
        -f flag specifies filename to save x,y,z values. Otherwise stdout is used.
;-g
 
: Grid size in degrees/meters (deg when using lon/lat coords, meters for UTM coords)
 
;-f
 
: Filename to save x,y,z values. Otherwise stdout is used.
 
;x1, y1, x2, y2
 
: SW (1) and NE (2) corners of region to extract in either lon/lat or UTM coords
 
;elev/depth
 
: Elevation/Depth of slice
 
;value_type
 
: Material property to extract: vs, vp, or rho
 
  
Note: Options -d and -v are mutually exclusive. Specifying neither option instructs vx_slice to interpret the z coordinate as elevation offset from free surface.
+
Arguments:
 +
        <x1> <y1> is SW corner of region to extract in geo/utm coords
 +
        <x2> <y2> is NE corner of region to extract in geo/utm coords
 +
        <z> is elev_offset, depth, or elevation depending on mode
 +
        <value> is one of: vp, vs, rho.
  
 +
Output format is:
 +
        X Y value
 +
</pre>
  
The plotting script ./viz/plot_hslice.sh illustrates how vx_slice can be used to generate a GMT plot from CVM-H at a fixed depth.
+
Note: Specifying no Z coordinate option instructs vx_slice to interpret the z coordinate as elevation offset from free surface.
 +
 
 +
The plotting script ./scripts/viz/plot_hslice.sh illustrates how vx_slice can be used to generate a GMT plot from CVM-H at a fixed depth.
  
  
Line 924: Line 1,037:
 
= History of CVM-H Releases =
 
= History of CVM-H Releases =
  
Please reference at least Süss and Shaw (2003) if you use this model. The latest model, CVM-H 11.1.0,
+
Please reference at least Süss and Shaw (2003) if you use this model. Due to continued improvements, The latest model contains several components that may warrant referencing, depending on the objectives of a particular study. For example, the background crustal tomography model is from Tape et al.(2009), the upper mantle model is from Prindle and Tanimoto (2006), and the Moho surface is
contains several components that may warrant referencing, depending on the objectives of a
 
particular study. For example, the background crustal tomography model is from Tape et al.
 
(2009), the upper mantle model is from Prindle and Tanimoto (2006), and the Moho surface is
 
 
obtained primarily from Yan and Clayton (2007). Additional references for basins within the
 
obtained primarily from Yan and Clayton (2007). Additional references for basins within the
 
high-resolution model are within these papers: Komatitsch et al. (2004), Lovely et al. (2006),
 
high-resolution model are within these papers: Komatitsch et al. (2004), Lovely et al. (2006),
Line 1,022: Line 1,132:
 
| Removed
 
| Removed
 
|-
 
|-
| CVM-H 11.1.0
+
| CVM-H 11.2.0
| Jan 2011
+
| Feb 2011
 
| -
 
| -
 
| -
 
| -
Line 1,030: Line 1,140:
 
| -
 
| -
 
| E2010
 
| E2010
 +
|-
 +
| CVM-H 11.9.0
 +
| Sep 2011
 +
| Plesch et al. (2011)
 +
| -
 +
| P2011
 +
| -
 +
| P2011
 +
| -
 +
|-
 +
| CVM-H 11.9.1
 +
| Dec 2012
 +
| Plesch et al. (2011)
 +
| -
 +
| P2011
 +
| -
 +
| P2011
 +
| -
 
|}
 
|}
  
Line 1,043: Line 1,171:
 
*M2007 (Munster, 2007)
 
*M2007 (Munster, 2007)
 
*PT2006 (Prindle and Tanimoto, 2006)
 
*PT2006 (Prindle and Tanimoto, 2006)
 +
*P2011 (Plesch et al., 2011)
 
*SS2003 (Süss and Shaw, 2003)
 
*SS2003 (Süss and Shaw, 2003)
 
*T2009 (Tape et al., 2009, 2010)
 
*T2009 (Tape et al., 2009, 2010)
 
*YC2007 (Yan and Clayton, 2007)
 
*YC2007 (Yan and Clayton, 2007)
 
*1D (Kanamori and Hadley, 1975; Dreger and Helmberger , 1991; Wald et al., 1995)
 
*1D (Kanamori and Hadley, 1975; Dreger and Helmberger , 1991; Wald et al., 1995)
 
  
 
= Acknowledgements and Contact Info =
 
= Acknowledgements and Contact Info =
Line 1,058: Line 1,186:
  
 
Contributions to this manual were made by: Andreas Plesch, Carl Tape, John Shaw, Patrick
 
Contributions to this manual were made by: Andreas Plesch, Carl Tape, John Shaw, Patrick
Small, Geoff Ely, and Thomas Jordan.
+
Small, Geoff Ely, Thomas Jordan, and Philip Maechling.
  
 
+
Please email software@scec.org for help on downloading and using CVM-H, and for any suggestions for the delivery of the code or for this manual.
Please email software@scec.org for help on downloading and using CVM-H,
 
and for any suggestions for the delivery of the code or for this manual.
 
  
 
Please reference at least Süss and Shaw (2003) if you use this model; other references should
 
Please reference at least Süss and Shaw (2003) if you use this model; other references should
 
be considered, depending on the purpose (see History of CVM-H releases section).
 
be considered, depending on the purpose (see History of CVM-H releases section).
 
  
 
= References =
 
= References =
Line 1,088: Line 1,213:
 
#'''Plesch, A., J. H. Shaw, E. Hauksson, and T. Tanimoto (2008)''', SCEC Community Velocity Model (CVM-H 5.5), in 2008 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 18, p. 142.
 
#'''Plesch, A., J. H. Shaw, E. Hauksson, and T. Tanimoto (2008)''', SCEC Community Velocity Model (CVM-H 5.5), in 2008 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 18, p. 142.
 
#'''Plesch, A., C. Tape, J. H. Shaw, and members of the USR working group (2009)''', CVM-H 6.0: Inversion integration, the San Joaquin Valley and other advances in the community velocity model, in 2009 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 19, pp. 260-261. Prindle, K., and T. Tanimoto (2006), Teleseismic surface wave study for S-wave velocity structure under an array: Southern California, Geophys. J. Int., 166, 601-621.
 
#'''Plesch, A., C. Tape, J. H. Shaw, and members of the USR working group (2009)''', CVM-H 6.0: Inversion integration, the San Joaquin Valley and other advances in the community velocity model, in 2009 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 19, pp. 260-261. Prindle, K., and T. Tanimoto (2006), Teleseismic surface wave study for S-wave velocity structure under an array: Southern California, Geophys. J. Int., 166, 601-621.
 +
#'''Plesch, A., C. Tape, R. Graves, J. H. Shaw, P. Small, and G. Ely (2011)''', Updates for the CVM-H including new representations of the offshore Santa Maria and San Bernardino basins and a new Moho surface, in 2011 Southern California Earthquake Center Annual Meeting, accepted.
 
#'''Shaw, J. H., A. Plesch, M. P. Süss, and the SCEC USE Focus Area Group (2004)''', Progress toward a Unified Structural Representation, in 2004 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 14, pp. 61-62.
 
#'''Shaw, J. H., A. Plesch, M. P. Süss, and the SCEC USE Focus Area Group (2004)''', Progress toward a Unified Structural Representation, in 2004 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 14, pp. 61-62.
 
#'''Stidham, C., M. P. Suess, J. Shaw, D. Komatitsch, and J. Tromp (2001a)''', 3D velocity and density model of the LA basin and spectral element method earthquake simulations, in 2001 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 11, p. 113.
 
#'''Stidham, C., M. P. Suess, J. Shaw, D. Komatitsch, and J. Tromp (2001a)''', 3D velocity and density model of the LA basin and spectral element method earthquake simulations, in 2001 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 11, p. 113.
Line 1,097: Line 1,223:
 
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2009)''', Adjoint tomography of the southern California crust, Science, 325, 988-992.
 
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2009)''', Adjoint tomography of the southern California crust, Science, 325, 988-992.
 
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2010)''', Seismic tomography of the southern California crust based on spectral-element and adjoint methods, Geophys. J. Int., 180, 433-462.
 
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2010)''', Seismic tomography of the southern California crust based on spectral-element and adjoint methods, Geophys. J. Int., 180, 433-462.
 +
#'''Wald, D. J., and T. I. Allen (2007)''', Topographic slope as a proxy for seismic site conditions and amplification, Bull. Seism. Soc. Am., 97 (5), 1379-1395, doi:10.1785/0120060267.
 
#'''Wald, L. A., L. K. Hutton, and D. D. Given (1995)''', The Southern California Network Bulletin: 1990-1993 summary, Seis. Res. Lett., 66 (1), 9-19.
 
#'''Wald, L. A., L. K. Hutton, and D. D. Given (1995)''', The Southern California Network Bulletin: 1990-1993 summary, Seis. Res. Lett., 66 (1), 9-19.
 +
#'''Wills, C. J., and K. B. Clahan (2006)''', Developing a map of geologically defined site-condition categories for California, Bull. Seism. Soc. Am., 96 (4A), 1483-1501, doi:10.1785/0120050179.
 
#'''Yan, Z., and R. W. Clayton (2007)''', Regional mapping of the crustal structure in southern California from receiver functions, J. Geophys. Res., 112, B05311, doi:10.1029/2006JB004622.
 
#'''Yan, Z., and R. W. Clayton (2007)''', Regional mapping of the crustal structure in southern California from receiver functions, J. Geophys. Res., 112, B05311, doi:10.1029/2006JB004622.
  
Line 1,107: Line 1,235:
  
 
Log file from 6/2007 onward:
 
Log file from 6/2007 onward:
 +
* 06/2011 AP: Revised Moho, open Santa Maria basin to W, smooth transition at S border of HR to LR model, San Bernardino basin, various former GTL related cleanups.
 
* 09/2010 AP: GTL removed
 
* 09/2010 AP: GTL removed
 
* 10/2009 AP: minor update of Moho surface in CM, corresponding update to changed cells, truncated border by one cell in LR, fixed VP/VS in interpolation area
 
* 10/2009 AP: minor update of Moho surface in CM, corresponding update to changed cells, truncated border by one cell in LR, fixed VP/VS in interpolation area
Line 1,126: Line 1,255:
 
== License ==
 
== License ==
  
Copyright (c)2011 Southern California Earthquake Center (SCEC) and the
+
Copyright (c)2011 Southern California Earthquake Center (SCEC) and the University of Southern California (USC). This copyright applies to the CVM-H codebase as a whole, or any individual distributed applications. The individual contributions of government employees, which may be identified on a per-file basis using Subversion (SVN) (see developer site), are in the public domain.  
University of Southern California (USC). This copyright applies to the CVM-H  
 
codebase as a whole, or any individual distributed applications, not covered
 
by the CVM-H v6.3 Harvard software license. The individual contributions of  
 
government employees, which may be identified on a per-file basis using  
 
Subversion (SVN) (see developer site), are in the public domain.  
 
  
 
The software and content provided on this website are made available under the  
 
The software and content provided on this website are made available under the  
Line 1,146: Line 1,270:
 
== Disclaimer ==
 
== Disclaimer ==
  
THIS SOFTWARE AVAILABLE ON THE BROADBAND WEBSITE IS PROVIDED "AS IS" AND ANY  
+
THIS SOFTWARE AVAILABLE ON THE CVM-H WEBSITE IS PROVIDED "AS IS" AND ANY  
 
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED  
 
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED  
 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE  
 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE  

Latest revision as of 20:28, 22 December 2012

The CVM-H 11.9.1 user guide in PDF format can be downloaded directly from: Cvmh manual.pdf.


Overview

The SCEC CVM-H is a 3D model of the elastic structure of southern California. It contains volumetric representations of compressional wave velocity (Vp), shear wave velocity (Vs), and density (rho). It also contains three primary surfaces: the topological/bathymetric surface, the basement surface, and the Moho surface. The model is constructed from numerous datasets (Süss and Shaw, 2003) and has been used within parallel-computing based wavefield simulations of earthquakes within southern California (e.g., Komatitsch et al., 2004). See Section 6 for details.


Requirements

The system requirements are as follows:

  1. UNIX operating system with minimum 2 GB RAM (tested on Linux and SunOs, limited support on Solaris and MacOS)
  2. tar for opening the compressed files
  3. GNU make (gmake)
  4. GNU C compiler (gcc)
  5. Optionally GTS (GNU Triangulated Surface Library) for cvmdist http://gts.sourceforge.net
  6. Optionally GMT (Generic Mapping Tools) to generate plots from vx_slice http://www.soest.hawaii.edu/gmt/


Installation

The quick start steps for installing the distribution are:

  1. Download package, check md5 sums, and untar distribution ('tar zxvf cvmh-11.9.1.tar.gz')
  2. Configure software for your platform ('./configure')
  3. Build software with 'make'
  4. Check build with 'make check', verifying that all tests pass
  5. Install software into target directory with 'make install'

These steps are described in greater detail within the following sections.

Download

Start at SCEC website: http://scec.usc.edu/scecpedia/CVM-H. Navigate to the Downloads section of the CVM-H web page. Click the download link to download the latest source code distribution file. This is typically posted as a tar and gzipped file (tgz format). The source code distribution file is large (500 MB), so the download make take awhile. Click the download link to the latest md5sum file. This file can be used to confirm you have downloaded an undamaged source code distribution file.


Checksum Test

After you've downloaded the two files to your local system, the next step is to compare the checksum of your downloaded file with our pre-computed md5. You should next verify that the md5sum command is in your path:

$ which md5sum

You should get something like /usr/bin/md5sum. If you see the message 'no md5sum in...', contact your Linux system administrator and ask to have md5sum added to your path, or add the md5sum to your path yourself by editing by editing your login shell script.

Once you can run the md5sum command, you should put the two files you downloaded together in the same directory. The two files will be named something like cvmh_11.9.1.tar.gz and cvmh_11.9.1.tar.gz.md5. Run the following command to perform the md5 comparison:

$ md5sum -c cvmh-11.9.1.tar.gz.md5

You should see the message:

 cvmh_11.9.1.tar.gz: OK

If you get "FAILED" instead, re-download the tgz files and try again. When it passes, that means the files were downloaded without error.


Basic Install

Once the file has passed the checksum test, untar into a ./cvmh subdirectory with this command:

$ tar zxvf cvmh-11.9.1.tar.gz

Once unpacked, you should see these files:

AUTHORS -- Author list
aux-config -- Autoconf config directory
build.xml -- ANT build and compilation script
ChangeLog -- Revision history
configure -- Configure utility
configure.ac -- Autconf config
COPYING -- License and disclaimer
doc -- Documentation directory including user guide
gctpc -- GCTPC projection library
INSTALL -- Installation instructions
m4 -- Autoconf macros
Makefile.am -- Automake makefile template
model -- Model directory containing voxet files
NEWS -- News file
README -- README documentation
scripts -- Directory containing helper scripts
src -- Source directory
test -- Directory containing unit and acceptance tests


The package is configured and built by executing the following commands:

$ cd ./cvmh-11.9.1
$ ./configure --prefix=${CVMH_INSTALL_DIR}
$ make

where:
${CVMH_INSTALL_DIR} : target directory where you want the CVM-H package installed

As one example, if you wanted to install the distribution in the following directory:

/home/scec-00/eworks/cvmh

you could type the command this way

./configure --prefix=/home/scec-00/eworks/cvmh

You will need permission to write to the directory you specify in this command. If the directory you specify does not exist, the installer will try to create it.

Once the configure completes without errors, make the executables by making the distribution:

$make


Once you build and install CVM-H, several sub-directories will be written to the directory you specified, including ./bin ./include ./lib and ./model.

The distribution should build in one minute or less. The build can be checked with the following command:

$ make check

A series of unit and acceptance tests will be executed. They should all pass. The package is installed in the prefix target directory that you specified with ./configure using the following command:

$ make install

At this point, you can use CVM-H normally.

Advanced Install

CVM-H may be linked with the optional GTS package which allows the binary executable cvmdst to be built. The program cvmdst calculates the distance to and the location of the closest points on the topographic/bathymetric, top of the basement, and Moho surfaces which are provided with CVM-H. The input file has the same format as the input file to vx, the query code to CVM-H.

The following configure command shows how CVM-H with the optional cvmdst may be built:

$ cd cvmh-11.9.1
$ ./configure --prefix=${CVMH_INSTALL_DIR} --with-gts --with-gts-lib-path="${GTS_LIB_DIR}" --with-gts-include-path="${GTS_INCL_DIR}"
$ make; make check; make install

where ${CVMH_INSTALL_DIR} is the CVM-H installation directory of choice, and ${GTS_LIB_DIR} and ${GTS_INCL_DIR} are the paths to the GTS libraries and headers, respectively.


Unit Tests

A set of unit tests may be executed to ensure that the CVM-H software has been compiled and installed correctly. These are organized into three test suites: vx Test Suite, vx_lite Test Suite, and C API Test Suite. Unit test execution time is approximately 1-2 minutes total. These tests are automatically executed as part of a 'make check' but they may also be run separately as described here.

  • vx Test Suite: Failure of any of these tests could indicate a problem with either the vx utility, the underlying model, or the reference data set used for comparison.
    • Extract 8 test points Test
  • vx_lite Test Suite: Failure of any of these tests could indicate a problem with either the vx_lite utility, the underlying model, or the reference data set used for comparison.
    • Extract 8 test points w/o SCEC 1D (in elevation mode) Test
    • Extract 8 test points w/o SCEC 1D (in depth mode) Test
    • Extract 8 test points w/ SCEC 1D (in elevation mode) Test
  • C API Test Suite: Failure of any of the following tests could indicate a problem with either the C API source, the underlying model, or the reference data set used for comparison.
    • Initialization of entry structure Test
    • Initialization of voxel structure Test
    • Get surface value at 8 test points Test
    • Get material properties at 8 test points w/o SCEC 1D Test
    • Get material properties at 8 test points w/ SCEC 1D Test
    • Register background model Test


All of the unit tests can be executed manually with the following commands, starting in the main CVM-H distribution directory:

$ cd ./test
$ ./unittest

The tests print results to the screen as they run, and they should complete within 5 minutes. All tests should pass. If any tests do not pass, your operating system or compiler may not be supported. You can report problems to the help email software (at) scec.org and we can provide full information on supported operating system and compiler versions.


Acceptance Tests

A set of acceptance tests may be executed to check the end-to-end functionality of vx and vx_lite. These tests are organized into a single test suite. Acceptance test execution time is approximately 2-5 minutes total depending on system performance. These tests are automatically executed as part of a 'make check' but they may also be run separately as described here.

  • Accept Test Suite: Failure of any of these tests could indicate a problem with either the vx/vx_lite utility, the underlying model, or the reference data set used for comparison.
    • Extract large grid with vx Test
    • Extract large grid with vx_lite in emulation mode Test
    • Extract large grid with vx_lite in depth mode Test
    • Extract large grid with vx_lite in elevation offset mode Test

All of the acceptance tests can be executed manually with the following commands, starting in the main CVM-H distribution directory:

$ cd ./test
$ ./accepttest

The tests print results to the screen as they run, and they should complete within 5 minutes. All tests should pass. If any tests do not pass, your operating system or compiler may not be supported. You can report problems to the help email software (at) scec.org, and we can provide full details on supported operating system and compiler versions.


Model Description

This program originated as a code designed for SCEC-IT to demonstrate the capability of a final interface for the HUSCV-model as described by Süss and Shaw (2003). The code is now available to the community as a simple tool to extract data from the HUSCV-model. In this new version also the High Resolution velocity volume is supported by the code. The Harvard University Southern California Velocity Model (HUSCV 1.0) describes the seismic P-wave velocity structure in the Los Angeles basin and surrounding areas. The model is defined by gridded volumes with higher and lower resolutions, as well as two surfaces used to define the volume of sediments (the top pre-Cretaceous basement and topography/bathymetry). A water-layer with a VP velocity of 1480 m/s is included. No Vs is defined for water, and density is 1000 kg/m3.

The model was designed in a UTM Zone-11 projection with the following coordinates for each model:

Table 1: Model Coordinates
LR CM HR GTL
Coordinates Origin (SW) : 131000 3431000
(120d51m43.301sW 30d57m23.387sN)
NE-Corner : 828000 4058000
(113d19m58.583sW 36d36m46.622sN)
Same as LR SW: 371052.25 3725250.0
(118d23m26.686sW 33d39m33.533sN)
SE: 417052.25 3725250.0
(117d53m40.875sW 33d39m50.043sN)
NW: 371052.25 3774000.0
(118d23m52.427sW 34d5m55.914sN)
NE: 417052.25 3774000.0
(117d53m57.439sW 34d6m12.699sN)
Origin (SW) : -31000.0 3410000.0
NE-Corner : 849000.0 4274000.0
Depth : 0-350m
Resolution 1000m x 1000m x 100m
670 x 400 x 200 grid cells
10000m x 10000m x 1000m
71 x 64 x 186 grid cells
250m x 250m x 100m
185 x 196 x 100 grid cells
250m x 250m


The following diagram illustrates the regions spanned by each model:

Cvmh model boundaries.png


The velocity volumes are stored in the GoCAD voxet format.

The program accepts geographic coordinates and UTM zone 11 (NAD27) coordinates. Coordinate transformation is performed by GCTPC2.0, a free projection library by the USGS. Sources for the library are included.

Vs is calculated from VP using the "mudline" relation and "Brocher's regression line" (Brocher , 2005):

Vs = (Vp - 1360)/1.16 .
For Vp < 1500 m/s, Vs is fixed at 121 m/s which corresponds to Vp = 1500 m/s.


CVM-H contains a geotechnical layer (GTL) that describes the velocity structure in the shallow subsurface, where low shear wave speeds, in particular, can have a significant impact on strong ground motions. The GTL velocity values (both Vp and Vs) and density are derived from the Vs30 map by the algorithm described in Ely (2010).

The models are extrapolated from their data limits to the model boundaries.

The underlying tomographic model is taken from Tape, C., Q. Liu, A. Maggi, and J. Tromp, (2009).

Mantle data were provided by Toshiro Tanimoto (personal communication) and are derived from waveform matching of teleseismic surface waves (Prindle and Tanimoto, 2006).

We adopt the Nafe-Drake scaling relationship to compute density from Vp (Ludwig et al., 1970; Brocher , 2005):

rho = 1.6612*Vp - 0.4721*(Vp)^2 + 0.0671*(Vp)^3 - 0.0043*(Vp)^4 + 0.000106*(Vp)^5,

where rho is in g/cm3 and VP is in km/s.

No specific shear quality factor is predicted by the model. A Qu of 90 has been used in the sediments by Komatitsch et al. (2004).

The code provides output consistent with directly querying the voxet in the Gocad software, and gives the position of the cell centers from which the data are provided. In addition, elevation of the topographic, basement and Moho surfaces are provided, at the closest grid point to the input coordinates. Flags indicate which voxet was used to extract data, and what the provenance of the data points within a given voxet is. 1D background, mantle, tomography, basins, and air are distinguished as possible data sources.


Geotechnical Layer

A near-surface geotechnical layer (GTL) exists in the vx_lite utility and C API, derived from a Vs30 map of southern California as described in (Ely, et al. (2010)). The Vs30 map was constructed from two datasets: an interim high-resolution rasterized Vs30 map for California described in (Wills and Clahan (2006)), and a Vs30 map for points outside of California described in (Wald, et al. 2007). The two datasets were combined with no interpolation.

The GTL extends from the free surface down to a transition depth of at least 350m. Vp, Vs, and density (rho) at the free surface are derived from the Vs30 values with the following relations:

 Vs = 1/2 * Vs30

 Vp = 0.9409 + Vs30 * (2.0947 - Vs30 * (0.8206 - Vs30 * (0.2683 - Vs30 * 0.0251)))

 rho = Vs30 * (1.6612 - Vs30 * (0.4721 - Vs30 * (0.0671 - Vs30 * (0.0043 - Vs30 * 0.000106))))
 if (rho < 1000.0) {
   rho = 1000.0;
 }


Vp and rho are taken from Brocher (2005).

Between depth 0m and the transition depth (>=350m), Vp, Vs, and rho are interpolated between the above material properties and the Vp, Vs, and rho as reported by the CVM-H LR/CM/HR/1D model at the transition depth. The non-linear interpolation relation is described in Ely et al. (2010). The transition depth is nominally 350m but may be greater to accomodate points in which topo - mtop > 350m. At these points, the transition depth is increased to topo - mtop so that data is guaranteed to be available.

The GTL may be turned off in source code. Set the ENABLE_GTL flag in ./src/vx_sub.c to False, and recompile, to disable the Vs30-derived GTL with vx_lite and the C API. The vx utility does not support a GTL at this time.


SCEC 1D Background Model

The CVM-H coverage region may be extended by an optional Hadley-Kanamori 1D background model. The following table describes the depth-Vp relationship:

Table 2: Depth-Vp relation for optional SCEC 1D background model
Depth (km) Vp (km/s)
0-1 5.0
5 5.5
6 6.3
10 6.3
15.5 6.4
16.5 6.7
22.0 6.75
31.0 6.8
33.0 7.8


The velocity Vp at the desired depth is linearly interpolated between the two velocities of the surrounding depth brackets. The final Vp, Vs, and rho are then derived from the interpolated Vp with the following relations:

 Vp = Vp * 1000.0

 rho = 1865.0 + 0.1579 * Vp

 Vs = Vp * sqrt( (0.5 - nu) / (1.0 - nu) )

 where nu is from the relation:
 if (rho < 2060.0) {
   nu = 0.40
 } else if (rho > 2500.0) {
   nu = 0.25
 } else {
   nu = 0.40 - ((rho - 2060.0) * 0.15 / 440.0)
 }

The velocities Vp and Vs are measured in (m/s), and rho is measured in (kg/m3).

The surface elevation in the SCEC 1D background is considered to be 0.0 m.

Application of this 1D background model becomes complicated when CVM-H is queried by elevation. In this query mode, valid data responses may include material properties for air and water and these cannot be interpolated with a soil 1D background. In these regions, air/water material properties are simply extended outward from the core LR/CM models without modification.


Smoothing Between Models

Smoothing (interpolation) is performed programmatically at many interfaces between models in CVM-H. These are summarized in the table below, along with the applicable interpolation distance:

Table 3: Smoothing Between Models
Point Falls Within Interp. w/
LR
Interp. w/
CM
Interp. w/
HR
Interp. w/
GTL
Interp. w/
1D
GTL (and HR/LR/CM),
Case 1
If within LR model,
use voxel at depth 350 m
If within CM model,
use voxel at depth 350 m
If within HR model,
use voxel at depth 350 m
None None
GTL (and 1D),
Case 2
If within 50km of LR,
use Case 1 at
closest LR point with same dep/elev
If within 50km of CM,
use Case 1 at
closest CM point with same dep/elev
None None 1D properties at depth 350 m
(performed before LR/CM interp)
1D only,
Case 3
If within 50km of LR,
and depth > 350 m,
and LR has voxels at same depth/elev,
use closest voxel at same elev/depth
If within 50km of CM,
and depth > 350 m,
and CM has voxels at same depth/elev,
use closest voxel at same elev/depth
None If within 50km of GTL,
and depth <=350m,
use Case 2 at
closest GTL point
None


There are several details to keep in mind:

  • All smoothing is linear interpolation between the material properties at the point of interest, weighted against the material properties at the closest voxel/point in the other model by the inverse of the distance between the two points.
  • Smoothing between the GTL and the LR/CM/HR/1D models along the z axis has been described in the geotechnical layer description.
  • Smoothing is performed with respect to the current query mode. When querying by elevation, smoothing is performed along points of equal elevation. Similarly, querying by depth causes smoothing to be performed along points of equal depth.
  • When interpolating the GTL with LR/CM and the 1D with LR/CM, either LR or CM is chosen as the interpolation target depending upon which model contains a voxel at the z value of interest. For example, at shallow depths, the GTL will typically be interpolated with LR, and at greater depths (> 20 km) the GTL will be interpolated with CM.
  • Since CVM-H has the concept of a "no data" value for Vp, Vs, and rho at any particular point, there may be regions within the model where no smoothing can be performed due to this missing data. This missing data may lead to discontinuities or other artifacts in the smoothed areas.
  • As mentioned previously, smoothing between air/water and the SCEC 1D when querying CVM-H by elevation is not meaningful. In this situation, air and water properties are extended outward from the LR/CM models without any modification.


Topography Flattening

CVM-H offers three Z axis modes for querying the underlying model: elevation, elevation offset (from the free surface), and depth. In depth mode, z values may be specified as a positive (or zero) depth value in meters. Querying by depth has the effect of stripping away the topography (as well as air and water) embedded within CVM-H. It is useful for extracting 3D meshes for sub-surface anelastic wave propagation simulations.

Note: The vx utility does not support topography flattening. These capabilities are only available in the vx_lite utility and the C API.

CVM-H must determine the elevation of the free surface at the x/y (lon/lat) point of interest when depth query mode is used. This is required in order to convert depth to elevation, since the model is internally represented as a collection of 3D volumes delineated by elevation along the Z axis. The method by which this free surface elevation is determined is different if the GTL is enabled or disabled.

By default, the Vs30-derived GTL is enabled. In this case, the free surface is taken to be the value reported by the topographic map at that point (the 'topo' value). When the GTL is disabled, the free surface is first determined by this algorithm:

 free_surf = min( topo(x,y) , mtop(x,y) )
 
 where:
  topo: elevation as reported by topo model at x,y
  mtop: uppermost elevation of data available at x,y

However, there are regions in the model with empty voxels at mtop, so that when queried at (x ,y, free_surf), the "no data" placeholder will still be returned. This is undesirable for many applications. So the surface elevation is adjusted further by the following recursive algorithm:

 data = query( x , y , free_surf )
 for i in 1...MAX_STEPS {
  if ( data == NO_DATA ) {
    switch (data.model):
    case LR:
      free_surf = free_surf - 100m
    case HR:
      free_surf = free_surf - 100m
    case CM:
      free_surf = free_surf - 1000m
    data = query( x , y , free_surf )
  } else {
   break for loop
  }
 }

The free surface is stepped down, voxel by voxel, until a data voxel is found. The point at which data is available is then assigned to be the free surface elevation at point (x,y). With the free surface known, the user depth can be converted to elevation and the model can be queried for material properties.

See the vx_lite Utility and C API sections later in this guide for instructions on how to enable this optional query mode.

Extracting Values from CVM-H

Two methods are provided for extracting material properties from CVM-H: command-line tools, and a C API. These are described in the sections below. The following table summarizes the model features supported by each interface:

Table 4: Model feature support by interface
Interface GTL Query by Elevation Query by Elevation Offset Query by Depth SCEC 1D Smoothing
vx No Yes No No No No
vx_lite Optional (default on) Yes Yes Yes Yes Yes
C API Optional (default on) Yes Yes Yes Yes Yes


Extracting Values on the Command Line

Two utilities are provided for querying the community velocity model, vx and vx_lite. The vx utility is the original interface to Harvard's model. The vx_lite utility is an updated interface that supports additional functionality.


vx Utility

The vx code provides output consistent with directly querying the voxet in the Gocad software, and gives the position of the cell centers from which the data are provided. Also, elevation of the topographic, basement and Moho surfaces are provided, at the closest grid point to the input coordinates. Additional details are listed in Tables 5 and 6. For usage details, type vx -h. From the ${CVMH_INSTALL_DIR}/model directory, try feeding the test points into the program. The test file (./test/test_data/test.dat from the s/w distribution), contains eight input points:

-125 35 -7777
-118.56 32.55 -2450
360061 3750229 -1400
-118.52 34.12 -1400
-116.40 32.34 -1000
376592 3773379 -1770
376592 3773379 -17700
408669 3766189 -3000

Note that the input can be either (lon, lat, elevation) or (UTMx-11, UTMy-11, elevation). Execute vx with the test file using this command:

$ cd ${CVMH_INSTALL_DIR}/model
$ ../bin/vx < ${CVMH_UNTAR_DIR}/test/test_data/test.dat

where:
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.


The output has 8 rows and 18 columns (Table 5) and should look like this (here the columns are truncated):

      X               Y             Z    ...     tag        vp        vs       rho
   -125.000000       35.000000  -7777.00 ...  -99999.00 -99999.00 -99999.00 -99999.00
   -118.560000       32.550000  -2450.00 ...       2.00   5575.15   3132.10   2631.81
 360061.000000  3750229.000000  -1400.00 ...       2.00   4554.52   2313.56   2469.78
   -118.520000       34.120000  -1400.00 ...       2.00   5066.61   2916.30   2545.10
   -116.400000       32.340000  -1000.00 ...       2.00   5372.79   3024.30   2595.55
 376592.000000  3773379.000000  -1770.00 ...       3.00   4181.37   2432.22   2418.45
 376592.000000  3773379.000000 -17700.00 ...       2.00   6533.31   3776.40   2841.47
 408669.000000  3766189.000000  -3000.00 ...       2.00   4997.06   2889.03   2534.30


The values for the eighth row are listed below, in transpose form, and with some annotations:

 408669.000000
 3766189.000000
 -3000.00
 408669.00
 3766189.00
 408625.00
 3766125.00
 93.89 --> elevation of topo/bath surface
 50.00 --> elevation of top of model (below which there is data)
 -2820.45 --> elevation of basement surface
 -29799.86 --> elevation of Moho surface
 hr
 408552.25
 3766250.00
 -3000.00
 2.00 --> value from tomography model
 4997.06 --> Vp
 2889.03 --> Vs
 2534.30 --> density

Note that there is a discrepancy between the top of the model (50.00 m) and the topography (93.89 m). The "real" top of the model is defined by mtop, and there may be minor discrepancies between mtop and topo.


Table 5: Columns of the output produced by vx. Queries which fall outside of the model area return -99999, the no-data value, for all fields.
Column Index Variable Description
1 X Input X (longitude or UTM coordinate)
2 Y input Y (latitude or UTM coordinate)
3 Z input Z (elevation, meters above sea level, i.e., positive up)
4 utmX UTM coordinate (zone 11), easting
5 utmY UTM coordinate (zone 11), northing
6 elevX X coordinate of center of the cell which provided data value for elevations
7 elevY Y coordinate of center of the cell which provided data value for elevations
8 topo topographic/bathymetric elevation in m
9 mtop top of model in m, below this depth there are data
10 base basement elevation in m (generally negative)
11 moho Moho elevation in m (always negative)
12 hr/lr/cm flag to indicate whether high- (hr), low-resolution (lr) or lower crust/mantle voxet was used; (nr) if no data available
13 cellX X coordinate of center of cell which provided velocity data value
14 cellY Y coordinate of center of cell which provided velocity data value
15 cellZ Z coordinate of center of cell which provided velocity data value
16 tag provenance of data point (see Table 6)
17 vp compressional wave velocity in m/s
18 vs shear wave velocity in m/s
19 rho density in kg/m3


Table 6: Provenance tags
Index Description
1 mantle data
2 tomography
3 basins
4 air
5 basin GTL
6 extrapolated tomography
7 water
8 basement GTL
9 basin-background transition in outer area (no basin model)
10 air in outer area
11 filled-in mantle
12 filled-in crust
13 extrapolated mantle
14 background model
15 Vs30 derived GTL


vx_lite Utility

The vx_lite utility is a new SCEC-developed interface which supports a number of enhancements, including query by depth, extension of the coverage region with a SCEC 1D model, and replacement of the original GTL with a Vs30-derived GTL. The command line format for vx_lite is as follows:

     vx_lite - (c) Harvard University, SCEC
Extract velocities from a simple GOCAD voxet. Accepts
geographic coordinates and UTM Zone 11, NAD27 coordinates in
X Y Z columns. Z is expressed as elevation offset by default.

        usage: vx_lite [-g] [-s] [-m dir] [-z dep/elev/off] < file.in

Flags:
        -g disable GTL (default is on).
        -s directs use of SCEC 1D background and topo.
        -m directory containing model files (default is '.').
        -z directs use of dep/elev/off for Z column (default is offset).

Output format is:
        X Y Z utmX utmY elevX elevY topo mtop base moho hr/lr/cm cellX cellY cellZ tg vp vs rho

where file.in is a list of 3D points specified as either (lon, lat, z (meters)) or (easting, northing, z (meters)), space delimited. Input coordinates can be specified interactively or redirected to stdin from a file.

Note: Specifying no Z coordinate option instructs vx_lite to interpret the z coordinate as elevation offset from free surface.

The query data is printed to stdout, and this may be redirected to a file.


CVM-H defines a set of sample test points (given in ./test/test_data/test.dat of the s/w distribution):

-125 35 -7777
-118.56 32.55 -2450
360061 3750229 -1400
-118.52 34.12 -1400
-116.40 32.34 -1000
376592 3773379 -1770
376592 3773379 -17700
408669 3766189 -3000


These may be submitted to vx_lite with this command:

$ cd ${CVMH_INSTALL_DIR}/bin
$ ./vx_lite -s -z elev -m ../model < ${CVMH_UNTAR_DIR}/test/test_data/test.dat

where:
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.

The example above selects the model directory to use (../model), selects elevation coordinate mode, and enables the SCEC 1D background model. The material properties at the sample points will be printed to stdout. You can expect to see the following output, annotated here with column headers (the columns are truncated):

      X               Y             Z    ...    tag        vp        vs       rho
   -125.000000       35.000000  -7777.00 ...     14.00   6300.00   3637.31   2859.77
   -118.560000       32.550000  -2450.00 ...      2.00   5575.15   3132.10   2631.81
 360061.000000  3750229.000000  -1400.00 ...      2.00   4554.52   2313.56   2469.78
   -118.520000       34.120000  -1400.00 ...      2.00   5066.61   2916.30   2545.10
   -116.400000       32.340000  -1000.00 ...      2.00   5372.79   3024.30   2595.55
 376592.000000  3773379.000000  -1770.00 ...      3.00   4181.37   2432.22   2418.45
 376592.000000  3773379.000000 -17700.00 ...      2.00   6533.31   3776.40   2841.47
 408669.000000  3766189.000000  -3000.00 ...      2.00   4997.06   2889.03   2534.30


Table 7: Columns of the output produced by vx_lite. Queries which fall outside of the model area return -99999, the no-data value, for all fields.
Column Index Variable Description
1 X Input X (longitude or UTM coordinate)
2 Y input Y (latitude or UTM coordinate)
3 Z input Z (elevation, meters above sea level, i.e., positive up)
4 utmX UTM coordinate (zone 11), easting
5 utmY UTM coordinate (zone 11), northing
6 elevX X coordinate of center of the cell which provided data value for elevations
7 elevY Y coordinate of center of the cell which provided data value for elevations
8 topo topographic/bathymetric elevation in m
9 mtop top of model in m, below this depth there are data
10 base basement elevation in m (generally negative)
11 moho Moho elevation in m (always negative)
12 hr/lr/cm/gt/bk flag to indicate whether high- (hr), low-resolution (lr) or lower crust/mantle voxet was used, (gt) for GTL, (bk) for 1D background; (nr) if no data available
13 cellX X coordinate of center of cell which provided velocity/Vs30 data value
14 cellY Y coordinate of center of cell which provided velocity/Vs30 data value
15 cellZ/Vs30 Z coordinate of center of cell which provided velocity data value; Vs30 value if value derived from GTL
16 tag provenance of data point (see Table 6)
17 vp compressional wave velocity in m/s
18 vs shear wave velocity in m/s
19 rho density in kg/m3


Extracting Values in a C Program

SCEC has extended the interface to CVM-H with a C programming interface (C API). The C header file containing the datatype and function definitions is located in ./src/vx_sub.h. By including this header in your source, and the libvxapi.a library at link time, your program can directly query CVM-H.

The following C code example shows how to initialize and query CVM-H programmatically. This example also illustrates the use of the SCEC 1D background and query by depth.


/* Source: Example.c */

#include <stdio.h>
#include <stdlib.h>
#include "vx_sub.h"

int main (int argc, char *argv[])
{
  vx_entry_t entry;
  double depth;
  
  /* Perform setup */
  if (vx_setup(argv[1]) != 0) {
    printf("Failed to init vx\n");
    exit(1);
  }

  /* Register SCEC 1D background model */
  vx_register_scec();

  /* Query by depth */
  vx_setzmode(VX_ZMODE_DEPTH);

  /* Query by lat/lon */
  entry.coor_type = VX_COORD_GEO;

  /* Setup point to query */
  entry.coor[0] = -118.0;
  entry.coor[1] = 34.0;

  /* Work-around for Trac issue #6: Depth value over-written in vx_getcoord() */
  depth = 100.0;
  entry.coor[2] = depth;

  /* Query the point */
  vx_getcoord(&entry);

  /* Print results */
  printf("Lon: %lf, Lat: %lf, Z: %lf, Vp: %lf, Vs: %lf, Rho: %f", entry.coor[0], entry.coord[1], depth, entry.vp, entry.vs, entry.rho);

  /* Cleanup */
  vx_cleanup();

  return(0);
}


Extracting Distances to Surfaces in CVM-H

There is an additional program, cvmdst, to compute the the distance to, and the location, of the closest points on the topographic/bathymetric, top of the basement, and Moho surfaces which are provided with CVM-H. The input file has the same format as the input file to vx, the query code to CVM-H. To use this capability, you need GTS (GNU Triangulated Surface Library), available from http://gts.sourceforge.net (using a Linux-Ubuntu platform, it may be as simple as installing all "gts" packages from the Synaptic Package Manager) and rebuild CVM-H. See the Advanced Install section on how to do this.

Once built, try the program with the same test data as before (note that you must be in the model directory):

$ cd ${CVMH_INSTALL_DIR}/model
$ ../bin/cvmdst < ${CVMH_UNTAR_DIR}/test/test_data/test.dat > ofile2.dat

where:
${CVMH_INSTALL_DIR}: CVM-H installation directory (defaults to /usr/local, or set with --prefix flag)
${CVMH_UNTAR_DIR}: Location where you unpacked the CVM-H distribution.

The output file ofile2.dat has 17 columns described in the table below. Note that the basement surface is not defined over the entire area of the model.


Table 8: Columns of the output produced by cvmdst
Column Index Variable Description
1 X Input X (longitude or UTM coordinate)
2 Y input Y (latitude or UTM coordinate)
3 Z input Z (elevation, meters above sea level, i.e., positive up)
4 utmX UTM coordinate (zone 11), easting
5 utmY UTM coordinate (zone 11), northing
6 t_x X coord of location of the closest point on the topographic/bathymetric surface
7 t_y X coord of location of the closest point on the topographic/bathymetric surface
8 t_z X coord of location of the closest point on the topographic/bathymetric surface
9 t_dst distance to the closest point on the topographic/bathymetric surface
10 b_x X coord of location of the closest point on the basement surface
11 b_y Y coord of location of the closest point on the basement surface
12 b_z Z coord of location of the closest point on the basement surface
13 b_dst distance to the closest point on the basement surface
14 m_x X coord of location of the closest point on the Moho surface
15 m_y Y coord of location of the closest point on the Moho surface
16 m_z Z coord of location of the closest point on the Moho surface
17 m_dst distance to the closest point on the Moho surface


Extracting a Horizontal Slice from CVM-H

The vx_slice utility is a new SCEC-developed interface for extracting horizontal slices from CVM-H that are suitable for plotting. The command line format for vx_slice is as follows:

     vx_slice - (c) Harvard University, SCEC
Extract a map of velocities from a simple GOCAD voxet for a regular
grid within the specified region at the specified depth/elev. Accepts
geographic/UTM coordinates for the geographic region. Outputs gridded
data suitable for plotting in MATLAB or GMT.

        usage: vx_slice [-g] [-s] [-m dir] [-z dep/elev/off] [-r gridsize] [-f outfile] -- <x1> <y1> <x2> <y2> <z> <value>

Flags:
        -g disable GTL (default is on).
        -s directs use of SCEC 1D background and topo.
        -m directory containing model files (default is '.').
        -z directs use of dep/elev/off for Z column.
        -r flag is gridsize in degrees/meters. Defaults to 0.1.
        -f flag specifies filename to save x,y,z values. Otherwise stdout is used.

Arguments:
        <x1> <y1> is SW corner of region to extract in geo/utm coords
        <x2> <y2> is NE corner of region to extract in geo/utm coords
        <z> is elev_offset, depth, or elevation depending on mode
        <value> is one of: vp, vs, rho.

Output format is:
        X Y value

Note: Specifying no Z coordinate option instructs vx_slice to interpret the z coordinate as elevation offset from free surface.

The plotting script ./scripts/viz/plot_hslice.sh illustrates how vx_slice can be used to generate a GMT plot from CVM-H at a fixed depth.


CVM Evaluation Testing

SCEC community 3D seismic velocity models, like CVM-H, are used in deterministic earthquake wave propagation simulations. Wave propagation simulations of moderate-sized historical California earthquakes generate synthetic seismograms that can be compared to observed seismograms. An accurate CVM will produce a good match between synthetics and observed data.

SCEC has established a CVM evaluation system designed to evaluate currently available southern California 3D velocity models. SCEC's CVM evaluation systems uses earthquake wave propagation simulations to help evaluate the performance of a velocity model.

Current evaluations are based on simulations of a m5.4 Chino Hills earthquake. The CVM under evaluation is used to build a velocity mesh needed to run a 1Hz Chino Hills earthquake simulations. Then, the earthquake simulation results are compared against observational data for the Chino Hills earthquake. The simulation results are shown in Goodness_of_Fit plots. The expectation is that as the CVM's are updated, the goodness of fit performance of the CVM's will improve.

The SCEC CVM evaluation systems is designed to evaluate alternative CVM's. CVM developers can register their CVM with the SCEC evaluation system. The CVM software is used to create a velocity mesh for the 1Hz simulation. Results are posted on the CVM evaluation sites together with links to download the CVM software.

The CVM evaluation system continues to develop and improve. Current information about the SCEC CVM evaluation system is available through the SCEC wiki pages.


History of CVM-H Releases

Please reference at least Süss and Shaw (2003) if you use this model. Due to continued improvements, The latest model contains several components that may warrant referencing, depending on the objectives of a particular study. For example, the background crustal tomography model is from Tape et al.(2009), the upper mantle model is from Prindle and Tanimoto (2006), and the Moho surface is obtained primarily from Yan and Clayton (2007). Additional references for basins within the high-resolution model are within these papers: Komatitsch et al. (2004), Lovely et al. (2006), Munster (2007). References for the Vs30-derived GTL are Ely (2010).

Table 9 documents the references for each release (up to Plesch et al. (2009)), as well as references for new components associated with each release. The CVM-H model has also been presented at these SCEC meetings: Stidham et al. (2001a), Suess and Shaw (2002), Shaw et al. (2004).

Table 9: History of CVM-H releases
Version Date Reference New Mantle New Moho New Crust New Basins New GTL
CVM-H 1.0 2003 Süss et al. (2003) - - - SS2003 -
CVM-H 2.0 Sept 2005 Suess and Shaw (2005) 1D - H2000 K2004, L2006 -
CVM-H 4.0 Sept 2006 Suess and Shaw (2006) - - - - -
CVM-H 5.0 Sept 2007 Plesch et al. (2007) PT2006 - L2007 M2007 M2000, M2002
CVM-H 5.5 Sept 2008 Plesch et al. (2008) - - - - BJ1997
CVM-H 6.0 Sept 2009 Plesch et al. (2009) - YC2007 T2009 - -
CVM-H 6.2 Jan 2010 Plesch et al. (2009) - - - - -
CVM-H 6.3 Sept 2010 Plesch et al. (2009) - - - - Removed
CVM-H 11.2.0 Feb 2011 - - - - - E2010
CVM-H 11.9.0 Sep 2011 Plesch et al. (2011) - P2011 - P2011 -
CVM-H 11.9.1 Dec 2012 Plesch et al. (2011) - P2011 - P2011 -


References

  • BJ1997 (Boore and Joyner , 1997)
  • E2010 (Ely, 2010)
  • H2000 (Hauksson, 2000), L2007 (Lin et al., 2007)
  • L2006 (Lovely et al., 2006)
  • K2004 (Komatitsch et al., 2004)
  • M2000 (Magistrale et al.,2000)
  • M2002 (Magistrale, 2002)
  • M2007 (Munster, 2007)
  • PT2006 (Prindle and Tanimoto, 2006)
  • P2011 (Plesch et al., 2011)
  • SS2003 (Süss and Shaw, 2003)
  • T2009 (Tape et al., 2009, 2010)
  • YC2007 (Yan and Clayton, 2007)
  • 1D (Kanamori and Hadley, 1975; Dreger and Helmberger , 1991; Wald et al., 1995)

Acknowledgements and Contact Info

Support for the development and maintenance of the CVM-H model has been provided by the Southern California Earthquake Center (SCEC), the National Earthquakes Hazard Reduction Program (NEHRP), and the National Science Foundation (NSF). SCEC is funded by NSF Cooperative Agreement EAR-0106924 and USGS Cooperative Agreement 02HQAG0008.

Contributions to this manual were made by: Andreas Plesch, Carl Tape, John Shaw, Patrick Small, Geoff Ely, Thomas Jordan, and Philip Maechling.

Please email software@scec.org for help on downloading and using CVM-H, and for any suggestions for the delivery of the code or for this manual.

Please reference at least Süss and Shaw (2003) if you use this model; other references should be considered, depending on the purpose (see History of CVM-H releases section).

References

  1. Boore, D. M., and W. B. Joyner (1997), Site amplifications for generic rock sites, Bull. Seis. Soc. Am., 87 (2), 327-341.
  2. Brocher, T. M. (2005), Empirical relations between elastic wavespeeds and density in the Earth's crust, Bull. Seis. Soc. Am., 95 (6), 2081-2092.
  3. Dreger, D. S., and D. V. Helmberger (1991), Source parameters of the Sierra Madre earthquake from regional and local body waves, Geophys. Res. Lett., 18 (11), 2015-2018.
  4. Ely, G., T. H. Jordan, P. Small, P. J. Maechling (2010), A Vs30-derived Near-surface Seismic Velocity Model Abstract S51A-1907, presented at 2010 Fall Meeting, AGU, San Francisco, Calif., 13-17 Dec. http://earth.usc.edu/~gely/pub/Ely2010-AGU.pdf
  5. Hauksson, E. (2000), Crustal structure and seismicity distribution adjacent to the Pacific and North America plate boundary in southern California, J. Geophys. Res., 105 (B6), 13,875-13,903.
  6. Kanamori, H., and D. Hadley (1975), Crustal structure and temporal velocity change in southern California, Pure App. Geophys., 113, 257-280.
  7. Komatitsch, D., Q. Liu, J. Tromp, P. Süss, C. Stidham, and J. H. Shaw (2004), Simulations of ground motion in the Los Angeles basin based upon the spectral-element method, Bull. Seis. Soc. Am., 94 (1), 187-206.
  8. Lin, G., P. M. Shearer, E. Hauksson, and C. H. Thurber (2007), A three-dimensional crustal seismic velocity model for southern California from a composite event method, J. Geophys. Res., 112, B11306, doi:10.1029/2007JB004977.
  9. Lovely, P., J. H. Shaw, Q. Liu, and J. Tromp (2006), A structural VP model of the Salton Trough, California, and its implications for seismic hazard, Bull. Seis. Soc. Am., 96 (5), 1882-1896.
  10. Ludwig, W. J., J. E. Nafe, and C. L. Drake (1970), Seismic refraction, in New Concepts of Sea Floor Evolution, The Sea: Ideas and Observations on Progress in the Study of the Seas, vol. 4, edited by A. E. Maxwell, pp. 53-84, Wiley-Interscience, New York.
  11. Magistrale, H. (2002), Improvements to the SCEC Community Velocity Model, in 2002 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 12, p. 93.
  12. Magistrale, H., S. Day, R. W. Clayton, and R. Graves (2000), The SCEC Southern California reference three-dimensional velocity model Version 2, Bull. Seis. Soc. Am., 90 (6B), S65-S76.
  13. Mayhew, J. E., and K. B. Olsen (2010), Goodness-of-fit criteria for broadband synthetic seismograms, with application to the 2008 Mw 5.4 Chino Hills, CA, earthquake, Seis. Res. Lett. (submitted).
  14. McCulloh, T. H. (1960), Gravity variations and the geology of the Los Angeles basin of California, Tech. rep., U.S. Geol. Survey, Washington, D.C., Professional Paper 400-B.
  15. Munster, J. (2007), Velocity Model of the Santa Maria Basin, CA, and its Implications for Seismic Hazard Assessment, undergraduate thesis, Harvard University, Cambridge, Mass., USA.
  16. Plesch, A., P. Suess, J. Munster, J. H. Shaw, E. Hauksson, T. Tanimoto, and members of the USR Working Group (2007), A new velocity model for southern California: CVM-H 5.0, in 2007 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 17, p. 159.
  17. Plesch, A., J. H. Shaw, E. Hauksson, and T. Tanimoto (2008), SCEC Community Velocity Model (CVM-H 5.5), in 2008 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 18, p. 142.
  18. Plesch, A., C. Tape, J. H. Shaw, and members of the USR working group (2009), CVM-H 6.0: Inversion integration, the San Joaquin Valley and other advances in the community velocity model, in 2009 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 19, pp. 260-261. Prindle, K., and T. Tanimoto (2006), Teleseismic surface wave study for S-wave velocity structure under an array: Southern California, Geophys. J. Int., 166, 601-621.
  19. Plesch, A., C. Tape, R. Graves, J. H. Shaw, P. Small, and G. Ely (2011), Updates for the CVM-H including new representations of the offshore Santa Maria and San Bernardino basins and a new Moho surface, in 2011 Southern California Earthquake Center Annual Meeting, accepted.
  20. Shaw, J. H., A. Plesch, M. P. Süss, and the SCEC USE Focus Area Group (2004), Progress toward a Unified Structural Representation, in 2004 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 14, pp. 61-62.
  21. Stidham, C., M. P. Suess, J. Shaw, D. Komatitsch, and J. Tromp (2001a), 3D velocity and density model of the LA basin and spectral element method earthquake simulations, in 2001 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 11, p. 113.
  22. Stidham, C., M. P. Süss, and J. H. Shaw (2001b), 3D density and velocity model of the Los Angeles basin, in Geol. Soc. Am. 2001 Annual Meeting Abstracts, vol. 33, Geol. Soc. Am., Denver, Colo., USA.
  23. Suess, M. P., J. H. Shaw, P. Lovely, J. Mueller, and A. Plesch (2005), The new SCEC Community Velocity Model (CVM-H 2.0), in 2005 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 15, p. 189.
  24. Suess, M. P., J. H. Shaw, E. Hauksson, A. Plesch, and J. Mueller (2006), New SCEC Community Velocity Model (CVM-H 4.0), in 2006 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 16, p. 170.
  25. Suess, P., and J. Shaw (2002), Uncertainty and the creation of high resolution 3D velocity models in Southern California, in 2002 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 12, p. 135.
  26. Süss, M. P., and J. H. Shaw (2003), P-wave seismic velocity structure derived from sonic logs and industry reflection data in the Los Angeles basin, California, J. Geophys. Res., 108 (B3), 2170, doi:10.1029/2001JB001628.
  27. Tape, C., Q. Liu, A. Maggi, and J. Tromp (2009), Adjoint tomography of the southern California crust, Science, 325, 988-992.
  28. Tape, C., Q. Liu, A. Maggi, and J. Tromp (2010), Seismic tomography of the southern California crust based on spectral-element and adjoint methods, Geophys. J. Int., 180, 433-462.
  29. Wald, D. J., and T. I. Allen (2007), Topographic slope as a proxy for seismic site conditions and amplification, Bull. Seism. Soc. Am., 97 (5), 1379-1395, doi:10.1785/0120060267.
  30. Wald, L. A., L. K. Hutton, and D. D. Given (1995), The Southern California Network Bulletin: 1990-1993 summary, Seis. Res. Lett., 66 (1), 9-19.
  31. Wills, C. J., and K. B. Clahan (2006), Developing a map of geologically defined site-condition categories for California, Bull. Seism. Soc. Am., 96 (4A), 1483-1501, doi:10.1785/0120050179.
  32. Yan, Z., and R. W. Clayton (2007), Regional mapping of the crustal structure in southern California from receiver functions, J. Geophys. Res., 112, B05311, doi:10.1029/2006JB004622.


Miscellaneous Technical Notes

This section contains notes on previous versions of the CVM-H model. Note that the information here does not necessarily apply to the current model.

Log file from 6/2007 onward:

  • 06/2011 AP: Revised Moho, open Santa Maria basin to W, smooth transition at S border of HR to LR model, San Bernardino basin, various former GTL related cleanups.
  • 09/2010 AP: GTL removed
  • 10/2009 AP: minor update of Moho surface in CM, corresponding update to changed cells, truncated border by one cell in LR, fixed VP/VS in interpolation area
  • 09/2009 AP: replaced LR and HR data files with Tape et al. (2009) m16 model as background, replaced Moho data with update, changed tagging
  • 06/2009 AP: returned GTL cells in Salton trough to original CVM-H values, higher coordinate output precision
  • 03/2009 AP: changed density scaling to Nafe-Drake (Brocher , 2005)
  • 09/2008 AP: fixed VS in buffer zone, used model VP/VS, not interpolated VS, in core zone to be consistent with VP there
  • 08/2008 AP: enlarged area to fit TeraShake box, added model VS in all voxets, no tt file creation
  • 01/2008 AP: replaced striped artifacts offshore San Diego with depth-basin depth-seafloor calibrated model data
  • 11/2007 AP: clarified geodetic datum with P. Suess
  • 10/2007 AP: added VS voxet for lower crust/mantle, switched to Brocher (2005) VS in LR/HR, truncated min. VP at 121 m/s, made HR consistent with LR for nodata points.
  • 9/2007 AP: updated lower crustal/mantle voxet to include Socal background VP
  • 9/2007 AP: added lower crustal/mantle voxet, elevation voxets; updated background tomographic model
  • 6/2007 AP: modified to be consistent with direct query of voxet in gocad, provide cell center


License and Disclaimer

License

Copyright (c)2011 Southern California Earthquake Center (SCEC) and the University of Southern California (USC). This copyright applies to the CVM-H codebase as a whole, or any individual distributed applications. The individual contributions of government employees, which may be identified on a per-file basis using Subversion (SVN) (see developer site), are in the public domain.

The software and content provided on this website are made available under the terms of the Apache License, Version 2.0. A copy of the License is provided by the Apache Software Foundation (http://www.apache.org/licenses/LICENSE-2.0).

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Disclaimer

THIS SOFTWARE AVAILABLE ON THE CVM-H WEBSITE IS PROVIDED "AS IS" AND ANY EXPRESSED 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 SOUTHERN CALIFORNIA EARTHQUAKE CENTER (SCEC), THE UNIVERSITY OF SOUTHERN CALIFORNIA (USC), OR ANY OF THEIR 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.


Without limiting the foregoing, SCEC and USC make no warranty that:

1. The software will meet your requirements.

2. The software will be uninterrupted, timely, secure or error-free.

3. The results that may be obtained from the use of the software will be effective, accurate or reliable.

4. The quality of the software will meet your expectations.

5. Any errors in the software obtained from the CVM-H web site will be corrected.


Software and its documentation made available on the CVM-H web site:

6. Could include technical or other mistakes, inaccuracies or typographical errors. CVM-H contributors may make changes to the software or documentation made available on its web site.

7. May be out of date and SCEC, its contributors, and USC make no commitment to update such materials.


SCEC, its contributors, and USC assume no responsibility for errors or omissions in the software or documentation available from the CVM-H web site.

In no event shall SCEC, its contributors, or USC be liable to you or any third parties for any special, punitive, incidental, indirect or consequential damages of any kind, or any damages whatsoever, including, without limitation, those resulting from loss of use, data or profits, whether or not SCEC, its contributors, or USC has been advised of the possibility of such damages, and on any theory of liability, arising out of or in connection with the use of this software.

The use of the software downloaded through the CVM-H site is done at your own discretion and risk and with agreement that you will be solely responsible for any damage to your computer system or loss of data that results from such activities. No advice or information, whether oral or written, obtained by you from SCEC, the CVM-H website, its contributors, or USC shall create any warranty for the software.