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

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.

Utilities

The following executable utilities are provided:

vx

Original interface to Harvard's model. Accepts lon/lat/elev points from stdin and prints material properties to stdout. The original user guide can be found here .

vx_lite

Updated interface to Harvard's model that supports optional 1D background, Vs30 derived GTL, and querying by depth. Accepts lon/lat/z points from stdin and prints material properties to stdout.

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.

Known Issues

None.