UCVM API

Overview

The Unified California Velocity Model API (UCVM API) is a programming interface that allows the user to directly query multiple velocity models in a program.

This document has been superseded by the UCVM User Guide.

This page now remains as a collection point for outstanding science issues. Significant science issues remain to be resolved. Please see the Science Issues section below.

Source Code

The UCVM source and cvm2mesh mesh generator may be checked out from SVN with these commands:

UCVM: svn co https://source.usc.edu/svn/ucvm/trunk

cvm2mesh: svn co https://source.usc.edu/svn/cvm2mesh/trunk

Implementation Details

• Models are queried in the order they are enabled in the interface. The material properties for a particular (lon,lat) point are from the first model in the ordered list to return valid values.
• Only lon,lat,dep and lon,lat,elev coordinates are currently supported
• No smoothing between crustal models is performed. They are simply tiled.
• Projections are performed with the Proj.4 package
• Depth is defined as the offset from the free surface (ground/air interface, ground/water interface) in meters, positive down. Negative depths are not supported. Elevation is defined as meters offset from MSL, positive up.

Future Improvements

• Addition of other regional models
• Addition of other GTLs
• Addition of other DEMs, VS30 maps
• Bindings for Fortran, C++

Science Issues

Overlapping Models

Imagine the scenario outlined below, where the user wishes to combine two models, a SoCal model and a NoCal model:

The models may overlap in ways which makes merging them difficult.

• For a point that falls within the Kern County region, simply interpolating between the two models may not work if NoCal reports water properties (vp, rho, no vs) and the SoCal model reports soil/rock. No interpolation is possible in this case. To deal with this situation, there are several options:
  • Coordinate edits to each model to bring their material properties into better agreement within the overlap region.
  • Crop one or both models to remove the overlap, and smooth them into the California background model.
  • Create a new “Transition Model” that covers Kern County and surrounding area that interpolates/averages the the two other models in a scientifically acceptable way. Register this new model in the API, and give it priority over the other two models. In effect, tile the Transition Model, the NoCal Model, and the SoCal Model.
  • Allow the models to overlap with discontinuities. This is currently how the UCVM API handles overlap.

Projection Distortion

Several issues with map projections come into play:

• Distortion in projections on large scales. Any state-wide model that supports querying by UTM or other projection coordinates must account for and minimize distortion.
• Inconsistent handling of projections within models. Each model generally has its own internal projection. For example, CVM-H uses a UTM projection. The projection codes used across all models should be standardized on the Proj.4 projection package to avoid small differences in the handling of coordinates. This may require resampling of the data inside the models.

Standardized Handling of Elevation

All models that support query by elevation should use a standard DEM derived from the same source.

Standardized Handling of Depth

Depth can be defined in a number of ways, with a reference point that is the ground/water interface or water/air interface or MSL, and positive down versus positive up. In fact, different regional models do define it differently. CVM-S/CVM-H defines depth as distance from ground/air interface, positive down, negative depths not supported. The USGS Bay Are model (cencalvm) defines depth as disance from the ground/air and water/air interface, positive up. The LinThurber model defines depth as offset from MSL, positive up. UCVM currently defines depth in the CVM-S convention and enforces this definition on the models by modifying how they are queried if necessary.

GTL

If a state-wide GTL is developed, the GTL within each underlying model must be stripped away.