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. Specifically, this guide describes how users can install velocity models manually. Users may want to do this if the CVM model of interest is not installed automatically by the UCVM ucvm_setup.py script. This includes some supported, but less commonly used models, such as Lin-Thurber, and Graves Mendicino Junction model.

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:

• Proj-4 version 4.8.0
• Euclid-3 version 1.3

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

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

UCVM requires GNU GCC compiler 4.3+. Large high-performance computing machines such as Kraken, Blue Waters, and Stampede often have their own optimized compilers enabled by default. Therefore if you are on a HPC machine you must switch to the GNU compilers. To switch compilers:

On Blue Waters type, "module swap PrgEnv-cray PrgEnv-gnu" On Kraken type, "module swap PrgEnv-pgi PrgEnv-gnu" On Stampede type, "module swap PrgEnv-pgi PrgEnv-gnu"

On Lustre filesystems, the IOBUF module is highly recommended to improve I/O write and read times. To enable this module, type "module load iobuf".

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-S4
--enable-model-cvms --with-cvms-lib-path=$UCVM_DIR/model/cvms4/lib --with-cvms-model-path=$UCVM_DIR/model/cvms4/src --with-cvms-include-path=$UCVM_DIR/model/cvms4/src

CVM-H 11.9.1
--enable-model-cvmh --with-cvmh-lib-path=$UCVM_DIR/model/cvmh1191/lib --with-cvmh-model-path=$UCVM_DIR/model/cvmh1191/model --with-cvms-include-path=$UCVM_DIR/model/cvmh1191/include --with-gctpc-lib-path=$UCVM_DIR/model/cvmh1191/lib

CVM-S4
--enable-model-cvmsi --with-cvmsi-lib-path=$UCVM_DIR/model/cvms423/lib --with-cvmsi-model-path=$UCVM_DIR/model/cvms423/model/i23 --with-cvmsi-include-path=$UCVM_DIR/model/cvms423/include

CenCal 0.8.0
--enable-model-cencal --with-cencal-lib-path=$UCVM_DIR/model/cencal/lib --with-cencal-model-path=$UCVM_DIR/model/cencal/USGSBayAreaVM-08.3.0.etree --with-cencal-extmodel-path=$UCVM_DIR/model/cencal/USGSBayAreaVMExt-08.3.0.etree --with-cencal-include-path=$UCVM_DIR/model/cencal/include

Magistrale Wasatch Front
--enable-model-wfcvm --with-wfcvm-lib-path=$UCVM_DIR/model/wfcvm --with-wfcvm-model-path=$UCVM_DIR/model/wfcvm --with-wfcvm-include-path=$UCVM_DIR/model/wfcvm

You must also provide the location of your Euclid3 and Proj-4 libraries.

Euclid-3 1.3
--with-etree-include-path=$UCVM_DIR/lib/euclid3/include --with-etree-lib-path=$UCVM_DIR/lib/euclid3/lib

Proj-4 4.8.0
--with-proj4-include-path=$UCVM_DIR/lib/proj4/include --with-proj4-lib-path=$UCVM_DIR/lib/proj4/lib

If you installed NetCDF, you must enable and provide the path to its location as well:

NetCDF
--enable-netcdf --with-netcdf-include-path=$UCVM_DIR/lib/netcdf/include --with-netcdf-lib-path=$UCVM_DIR/lib/netcdf/lib

If you require a static build (required on Kraken, for example), there is the "--enable-static" flag. If you require the IOBUF libraries (any Lustre filesystem including Kraken and Blue Waters), you can do so using the "--enable-iobuf" flag.

The next step is to actually run the configuration script. On a typical Linux system, with CVM-S4 and CVM-H being installed, this might look like:

./configure --prefix=$UCVM_DIR --with-etree-include-path=$UCVM_DIR/lib/euclid3/include --with-etree-lib-path=$UCVM_DIR/lib/euclid3/lib --with-proj4-include-path=$UCVM_DIR/lib/proj4/include --with-proj4-lib-path=$UCVM_DIR/lib/proj4/lib --enable-model-cvms --with-cvms-lib-path=$UCVM_DIR/model/cvms4/lib --with-cvms-model-path=$UCVM_DIR/model/cvms4/src --with-cvms-include-path=$UCVM_DIR/model/cvms4/src --enable-model-cvmh --with-cvmh-lib-path=$UCVM_DIR/model/cvmh1191/lib --with-cvmh-model-path=$UCVM_DIR/model/cvmh1191/model --with-cvms-include-path=$UCVM_DIR/model/cvmh1191/include --with-gctpc-lib-path=$UCVM_DIR/model/cvmh1191/lib

On Kraken, which requires static linking and the IOBUF module to be enabled, this command would look like:

./configure --prefix=$UCVM_DIR --enable-iobuf --enable-static --with-etree-include-path=$UCVM_DIR/lib/euclid3/include --with-etree-lib-path=$UCVM_DIR/lib/euclid3/lib --with-proj4-include-path=$UCVM_DIR/lib/proj4/include --with-proj4-lib-path=$UCVM_DIR/lib/proj4/lib --enable-model-cvms --with-cvms-lib-path=$UCVM_DIR/model/cvms4/lib --with-cvms-model-path=$UCVM_DIR/model/cvms4/src --with-cvms-include-path=$UCVM_DIR/model/cvms4/src --enable-model-cvmh --with-cvmh-lib-path=$UCVM_DIR/model/cvmh1191/lib --with-cvmh-model-path=$UCVM_DIR/model/cvmh1191/model --with-cvms-include-path=$UCVM_DIR/model/cvmh1191/include --with-gctpc-lib-path=$UCVM_DIR/model/cvmh1191/lib

After the script runs, you are then ready to proceed with the usual commands:

make
make install
make check


The last "make check" command will test to make sure that UCVM was installed correctly.

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

Supported Model Flags

Underlying models may be configured in one of two ways: with a key/value string in the UCVM configuration file, or by passing configuration parameters with the ucvm_setparam()function. The following model flags are supported:

Parameter	Value	Models
USE_1D_BKG	True/False (default False)	CVM-H
USE_GTL	True/False (default True)	CVM-H

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.

UCVM model tiling method.

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.

Adding a User-defined Velocity Model

UCVM may be extended to support any user-defined velocity model. The simplest way to add a new model is to store that model as a SCEC Etree or Patch Model, and update ${UCVM_INSTALL_DIR}/conf/ucvm.conf with the model interface and path. For example:

For SCEC Etrees:

user1_interface=model_etree
user1_modelpath=/home/username/model_etree/user1.etree

For Patch models:

user2_interface=model_patch
user2_modelpath=/home/username/model_patch/user2.conf

SCEC Etrees can be created with the ./bin/ucvm2etree utility. Patch models can be created with the ./bin/patchmodel utility.

Adding a User-defined Map

Update ${UCVM_INSTALL_DIR}/conf/ucvm.conf with the map interface and Etree path:

usermap1_interface=map_etree
usermap2_mappath=/home/username/maps/usermap1.e

User-defined maps can be created with the ./bin/grd2etree utility.

Additional Information

Additional information, such as history, acknowledgements, etc., is available on the main user guide.