CVM-H User Guide

User Guide for the Southern California Earthquake Center

Community Velocity Model: SCEC CVM-H 11.1.0

Andreas Plesch, Carl Tape, John H. Shaw, Patrick Small, Geoff Ely

Harvard University, University of Southern California

January 21, 2011

This PDF file can be downloaded directly from: http://structure.harvard.edu/cvm-h/download/cvmh_manual.pdf

Overview

The SCEC CVM-H 6.2 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 (�). 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¨uss 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

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

The system requirements are as follows:

1. UNIX operating system (Linux, Solaris, MacOS)
2. GNU make
3. tar and for opening the compressed files
4. Optionally GTS (GNU Triangulated Surface Library) for cvmdist http://gts.sourceforge.net

Installation

• Download the latest version tarball and untar into a ./cvmh subdirectory with this command:

% tar zxvf cvmh_11.1.0_RC.tgz

The files you should see are these:

CMxVM_Model3D_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 4
CVMH_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 5
CMxVM_Model3D_CM_BASE_Folded.ts -- top of the basement as tsurf
CVMH_Moho.ts -- Moho surface
ts2gts.awk -- script to translate from .ts to .gts
ts2gts.sh -- run script for ts2gts.awk
Makefile -- for compilation
interpolate -- directory with routines for inverse distance weighted interpolation
gctpc -- projection library
src -- directory for source files
bin -- directory for RUN
doc -- directory containing documentation including user guide
test -- directory for unit/acceptance tests
viz -- directory for simple GMT visualization of horizontal slices from CVM
lib -- directory for VX C API library file

• The package is built by executing the following commands:

% cd ./cvmh
% make clean;make all

• Ensure that the s/w is correctly built by running the unit tests. All tests should pass.

% cd ./test
% ./unittest

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 following sections.

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 1 and 2. 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
-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 command:

% ./vx < ./test_data/test.dat

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

  -125.000000      35.000000  -7777.00 -230844.88 3902223.73 -99999.00 -99999.00 -99999.00 -99999.00 -99999.00 -99999.00 nr -99999.00  -99999.00 -99999.00 -99999.00
  -118.560000      32.550000  -2450.00  353525.18 3602285.14 353625.00 3602375.00 -1114.91  -1150.00  -1327.54 -21571.67 lr 354000.00 3602000.00  -2400.00      2.00
360061.000000 3750229.000000  -1400.00  360061.00 3750229.00 360125.00 3750125.00   -56.93    -50.00  -1404.07 -24868.83 lr 360000.00 3750000.00  -1400.00      2.00
  -118.520000      34.120000  -1400.00  359819.67 3776309.78 359875.00 3776375.00   491.46    450.00     38.42 -28061.40 lr 360000.00 3776000.00  -1400.00      2.00
  -116.400000      32.340000  -1000.00  556464.74 3578092.46 556375.00 3578125.00   780.43    750.00    616.39 -31413.62 lr 556000.00 3578000.00  -1000.00      2.00
376592.000000 3773379.000000  -1770.00  376592.00 3773379.00 376625.00 3773375.00    99.38    100.00  -2374.53 -28165.35 hr 376552.25 3773500.00  -1800.00      3.00
376592.000000 3773379.000000 -17700.00  376592.00 3773379.00 376625.00 3773375.00    99.38    100.00  -2374.53 -28165.35 cm 380000.00 3770000.00 -18000.00      2.00
408669.000000 3766189.000000  -3000.00  408669.00 3766189.00 408625.00 3766125.00    93.89     50.00  -2820.45 -29799.86 hr 408552.25 3766250.00  -3000.00      2.00

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 1: 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

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 [-s] [-d] [-v] [< input_coords]

where the options:

-s

Instructs use of SCEC 1D background model

-d

Interpret z coordinate as depth from free surface

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

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):

-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:

% ./vx_lite -s -v < ./test_data/test.dat

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 three important fields are the last three, containing vp, vs, and rho.

     X               Y             Z       utmX        utmY      elevX       elevY      topo      mtop      base      moho  hr/lr/cm cellX     cellY     cellZ       tag        vp        vs       rho
  -125.000000       35.000000  -7777.00 -230844.88  3902223.73  -99999.00   -99999.00      0.00      0.00 -99999.00 -99999.00 bk  -99999.00   -99999.00 -99999.00     14.00   6300.00   3637.31   2859.77
  -118.560000       32.550000  -2450.00  353525.18  3602285.14  353625.00  3602375.00  -1114.91  -1150.00  -1327.54 -21571.67 lr  354000.00  3602000.00  -2400.00      2.00   5575.15   3132.10   2631.81
360061.000000  3750229.000000  -1400.00  360061.00  3750229.00  360125.00  3750125.00    -56.93    -50.00  -1404.07 -24868.83 lr  360000.00  3750000.00  -1400.00      2.00   4554.52   2313.56   2469.78
  -118.520000       34.120000  -1400.00  359819.67  3776309.78  359875.00  3776375.00    491.46    450.00     38.42 -28061.40 lr  360000.00  3776000.00  -1400.00      2.00   5066.61   2916.30   2545.10
  -116.400000       32.340000  -1000.00  556464.74  3578092.46  556375.00  3578125.00    780.43    750.00    616.39 -31413.62 lr  556000.00  3578000.00  -1000.00      2.00   5372.79   3024.30   2595.55
376592.000000  3773379.000000  -1770.00  376592.00  3773379.00  376625.00  3773375.00     99.38    100.00  -2374.53 -28165.35 hr  376552.25  3773500.00  -1800.00      3.00   4181.37   2432.22   2418.45
376592.000000  3773379.000000 -17700.00  376592.00  3773379.00  376625.00  3773375.00     99.38    100.00  -2374.53 -28165.35 cm  380000.00  3770000.00 -18000.00      2.00   6533.31   3776.40   2841.47
408669.000000  3766189.000000  -3000.00  408669.00  3766189.00  408625.00  3766125.00     93.89     50.00  -2820.45 -29799.86 hr  408552.25  3766250.00  -3000.00      2.00   4997.06   2889.03   2534.30

The previous section on the vx utility provides a more detailed description of each of these fields.

Extracting Values in a C Program

SCEC has developed a C API to the Harvard model. The header 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. See the cvm2mesh mesh extraction tool below for an example implementation that uses this API.

Extracting Distances to Surfaces in CVM-H

There is also 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.) With GTS installed, you can now compile. From the main cvmh directory, compile with this command:

% make cvmdst

This will create a cvmdst executable in the ./bin directory.

Try the program with the same test data as before:

% cd bin
% ./cvmdst < ./test_data/test.dat > ofile2.dat

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

Table 3: 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	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

Extracting a Horizontal Slice from CVM-H

The following utility is provided:

vx_slice

Visualization utility for extracting a 2D horizontal slice of Vp, Vs, or Rho (density) from the model, suitable for plotting with a graphics package.

History of CVM-H Releases

Please reference at least Suss and Shaw (2003) if you use this model. The latest model, CVM-H 11.1.0, 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 Vs-30 derived GTL are (TBD).

Table 4 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 4: History of CVM-H releases

Version	Data	Reference	Mantle	Moho	Crust	Basins	GTL
CVM-H 1.0	2003	Suss and Shaw (2003)	-	-	-	SS2003	-

References

• BJ1997 (Boore and Joyner , 1997)
• 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)
• SS2003 (S¨uss 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)