UCVM 13.9.0 Advanced User Guide
Overview
This guide is intended for users looking to use the advanced features of UCVM. Most common functionality, including mesh generation and getting material properties from models, is described in the main user guide.
UCVM 13.9.0 was released on September 8th, 2013 and is the latest version of the Unified Community Velocity Model (UCVM) framework available. UCVM is a collection of software utilities that are designed to make querying velocity models, building meshes, and visualizing velocity models easier to do through a uniform software interface. UCVM has been used extensively to generate meshes and e-trees that are then used for 3D wave propagation simulations within California.
This guide describes some of the more advanced features of UCVM, such as the ability to add a custom Vs30 GTL, combine models, and install models other than CVM-S4, CVM-H 11.9.1, CVM-S4.23, and CenCal.
Download
| Platform | File | Download | Mirror |
|---|---|---|---|
| Linux | SCEC UCVM 13.9.0 Official Release (391 Mb) | ucvm-13.9.0.tar.gz | N/A |
| Linux | SCEC UCVM 13.9.0 md5 checksum (< 1Kb) | ucvm-13.9.0.tar.gz.md5 | N/A |
Installation
If you would only like CVM-S4, CVM-H 11.9.1, CVM-S4.23, and/or CenCal, we strongly recommend following this installation guide.
The first step to installing UCVM is to download the latest UCVM distribution. Then, you will need:
If you would like to export to NetCDF format, you will also need the NetCDF library.
- NetCDF
You will also need to retrieve the desired community velocity models. Currently, the following models are supported in UCVM 13.9.0:
- CVM-S4
- CVM-H 11.9.1
- CVM-S4.23
- CenCal 0.8.0
- SCEC CVM-NCI
- Magistrale Wasatch Front CVM
- Graves Cape Mendocino
- Lin-Thurber Statewide
- Tape SoCal
We recommend following a standard directory structure for building and installing UCVM. We will call the base directory $UCVM_DIR. All models will be installed in $UCVM_DIR/model. All libraries will be installed in $UCVM_DIR/lib. This allows you to keep installation paths standardized and makes the installation process much easier.
Below, we describe what you need to do to build and install each library or model.
Proj-4 4.8.0
To install Proj-4, download distribution file and type the following commands.
tar zxvf proj-4.8.0.tar.gz
cd proj-4.8.0
./configure --prefix=$UCVM_DIR/lib/proj-4 --with-jni=no
make
make install
Euclid-3 1.3
Download the Euclid3 distribution file and then follow these commands.
tar zxvf euclid3-1.3.tar.gz
cd euclid3-1.3
./configure --prefix=$UCVM_DIR/lib/euclid3
make
make install
NetCDF
CVM-S4
CVM-S4 is the SCEC community velocity model for the southern California region. To install CVM-S4, run these commands after downloading the model:
tar zxvf cvms4.tar.gz
cd CVM-S
./configure --prefix=$UCVM_DIR/model/cvms4
make
make install
CVM-H 11.9.1
CVM-H 11.9.1 is the Harvard community velocity model for the southern California region. To install CVM-H 11.9.1, run these commands after downloading the model:
tar zxvf cvmh1191.tar.gz
cd CVM-H
./configure --prefix=$UCVM_DIR/model/cvmh1191
make
make install
CVM-S4.23
CVM-S4.23 combines material properties from the starting CVM-S4 model, with perturbations that are a result of iterations of inversion simulations by Chen et al (2011) and Lee et al (2010). To install CVM-S4.23, run these commands after downloading the model:
tar zxvf cvms423.tar.gz
cd CVM-SI
./configure --prefix=$UCVM_DIR/model/cvms423
make
make install
CenCal 0.8.0
CenCal is a USGS-developed model of the Bay Area. To install, run these commands after downloading the model:
tar zxvf cencal080.tar.gz
cd cencal
./configure --prefix=$UCVM_DIR/model/cencal
make
make install
Magistrale Wasatch Front CVM
The Wasatch Front community velocity model is a CVM for Utah encompassing the Cache, Weber/Davis, Salt Lake, and Utah basins. The DEM and Vs30 maps are already included with UCVM, so you only need to download the model.
tar zxvf wfcvm_3c.tgz
cd WFCVM3c
gfortran -c -fpic wf_cvm3c.f
gcc -shared -o libwfcvm.so wf_cvm3c.o -lgfortran
ar rcs libwfcvm.a wf_cvm3c.o
mkdir -p $UCVM_DIR/model/wfcvm
cp ./* $UCVM_DIR/model/wfcvm
UCVM 13.9.0 Install
After downloading all the community velocity models you require, it is then time to actually configure and install UCVM.
First of all, untar and cd into the UCVM 13.9.0 distribution:
tar zxvf ucvm-13.9.0.tar.gz
cd UCVM
Each model requires three flags to be provided to the configure script, a lib path, a model path, and an include path. You must also tell UCVM that you would like to enable the model as well. If you installed the models as per the instructions above, the set of flags for each model would be:
CVM-S
--enable-model-cvms --with-cvms-lib-path=$UCVM_DIR/model/cvms/lib --with-cvms-model-path=$UCVM_DIR/model/cvms/src --with-cvms-include-path=$UCVM_DIR/model/cvms/src
Command Descriptions
Descriptions of all the available commands and what they do are available on the basic user guide.
Advanced Features
Supported Standard GTL Velocity Models
UCVM has built-in support for two geotechnical layer models. These near-surface models are intended to provide superior velocity information at shallow depths. The following table lists the labels for these predefined GTLs. These are reserved labels and cannot be used for a user-defined GTL.
| Label | GTL |
|---|---|
| elygtl | Ely Vs30-derived GTL (Ely et al., 2010) |
| 1dgtl | Generic 1D, identical to 1d crustal model |
Interpolation functions are used to smooth GTL material properties with the underlying crustal model material properties. This smoothing is performed over an interpolation zone along the Z axis. Interpolation functions can be assigned on a per-GTL basis. Two predefined interpolation functions are provided to the user:
| Label | Interpolation Function |
|---|---|
| linear | Linear interpolation |
| ely | Ely interpolation relation (Ely et al., 2010) |
If the user enables a GTL model but does not specify an interpolation function, linear interpolation is used by default. If no interpolation zone is specified, a depth range of 0 m - 350m is used.
Supported Standard Maps
UCVM has built-in support for a number of standard maps for California. These standard maps contain elevation data (DEM) and Vs30 data for the region and are referenced in ucvm_query and the API by their string labels. The following table lists the labels for these predefined maps. These are reserved labels and cannot be used for a user-defined map.
| Label | Map |
|---|---|
| ucvm | USGS NED 1 arcsec DEM, and Wills-Wald Vs30 (default) |
| yong | USGS NED 1 arcsec DEM, and Yong-Wald Vs30 |
There is also a special map interface that supports reading SCEC Map Etrees. These are maps that conform to a special Etree schema and metadata format convention. The user may create their own maps in this format and import them into UCVM. Any number of maps may be defined, but only one may be active at any time. Maps are defined by the user in the UCVM configuration file (see UCVM_User_Guide#Adding_a_User-defined_Map).
The map interfaces are summarized in the following table:
| Interface | Description |
|---|---|
| map_etree | SCEC Map Etree |
Combining Multiple Velocity Models into a Composite Model
UCVM combines multiple regional velocity models, along with a DEM map and a Vs30 map, into one composite model for the purposes of querying surface elevation, Vs30, Vp, Vs, and density. Individual model setup and query details are abstracted under a uniform interface, and the application sees only the composite model. This simplifies application code and makes it easier for those programs to support new velocity models in the future.
Velocity models are combined into the composite by tiling them on top of one another. When UCVM is initialized, the user selects an ordered list of models to query for data. Query points are then submitted to each velocity model in that list, one model at a time in list order. The first model to return valid velocity data for the point is considered to have fullfilled that data request and subsequent models are not queried. Generally, no smoothing is performed at the interfaces between models (an exception is interpolation between a GTL and crustal model as described below). For each query point, the following data is returned: surface elevation, Vs30, Vp, Vs, and density. The figure at right illustrates how this tiling is performed.
Regional models may include: CVM-H, CVM-H, USGS Bay Area, 1D, or other user-defined models. Most models and maps have a maximum extent, outside of which no data is available. The exception is the generic 1D model as it has infinite extents. Applications must check the returned velocity and density values to ensure they are valid.
