CVM-H User Guide

This PDF file can be downloaded directly from: http://hypocenter.usc.edu/research/cvmh/11.2.0/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 (Linux, Solaris, MacOS)
2. GNU make
3. tar for opening the compressed files
4. gcc compiler
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

1. Start at SCEC website: http://scec.usc.edu/scecpedia/CVM-H
2. Navigate to the CVM-H::Downloads section of the web page
3. 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.
4. Click the download link to the latest md5sum file. This can be used to confirm you an undamaged source code distribution file.

CheckSum Test

We recommend you run these verification steps before using the CVM-H for important research purposes. After you've downloaded the two files to your local Linux system, the next step is to calculate the checksums yourself and compare them to the checksums you downloaded.

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.2.0.tgz and cvmh_11.2.0.tgz.md5.

You should run the following at a command line:

$> md5sum -c cvmh_11.2.0.tgz.md5

You should get the messages

 cvmh_11.2.0.tgz: 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.

Installation

Once both files have passed the checksum test, untar into a ./cvmh subdirectory with this command:

% tar zxvf cvmh_11.2.0.tgz

Once unpacked, the files you should see are these:

 bin -- directory containing model files and executables
 build.xml -- ANT build and compilation script
 CMxVM_Model3D_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 4
 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
 CVMH_CalMex_BATO.ts -- bathymetry/topography as tsurf, version 5
 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

The package is built by executing the following commands:

% cd ./cvmh
% make all

On a system with the following gcc and linux versions (gcc (GCC) 4.3.2 20081105 (Red Hat 4.3.2-7), the distribution builds with a small number of warnings and no errors in about 1 minute.

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.

• 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

Execute all of the unit tests with the following commands, starting in the main CVM-H distribution directory:

% cd ./test
% ./unittest

All tests should pass.

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.

• 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

Execute all of the acceptance tests with the following commands, starting in the main CVM-H distribution directory:

% cd ./test
% ./accepttest

All tests should pass.

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	Origin (NW) : 371053.25 3774000 (-119.322991 / 33.013591) NE-Corner : 417052.25 3774000 (-117.257011 / 33.034954) SW-Corner : 371053.25 3725250 (-119.371155 / 34.770882)	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 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, 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:

Vs = 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;
}

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.

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	Yes	Yes	Yes	Yes	Yes	Yes
C API	Yes	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 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 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 [-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 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 "vx_sub.h"

 int main (int argc, char *argv[])
 {
  vx_entry_t entry;

  /* Perform setup */
  if (vx_setup(".") != 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] = -120.0;
  entry.coor[1] = 35.0;
  entry.coor[2] = 100.0;

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

  /* Print results */
  printf("Vp: %lf, Vs: %lf, Rho: %f", entry.vp, entry.vs, entry.rho);

  return(0);
 }

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 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 [-s] [-d] [-v] [-g gridsize] [-f outfile] -- <x1> <y1> <x2> <y2> <elev/depth> <value_type>

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

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

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.

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. 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 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.1.0	Jan 2011	-	-	-	-	-	E2010

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)
• 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, and Thomas Jordan.

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. 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.
20. 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.
21. 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.
22. 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.
23. 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.
24. 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.
25. 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.
26. Tape, C., Q. Liu, A. Maggi, and J. Tromp (2009), Adjoint tomography of the southern California crust, Science, 325, 988-992.
27. 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.
28. 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.
29. 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:

• 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, 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 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 BROADBAND 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.