View source for 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 [http://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide 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 ==

{| class="wikitable" border="1"
|-
! Platform
! File
! Download
! Mirror
|-
| Linux
| '''SCEC UCVM 13.9.0 Official Release (391 Mb)'''
| [http://hypocenter.usc.edu/research/ucvm/13.9.0/ucvm-13.9.0.tar.gz ucvm-13.9.0.tar.gz]
| N/A
|-
| Linux
| '''SCEC UCVM 13.9.0 md5 checksum (< 1Kb)'''
| [http://hypocenter.usc.edu/research/ucvm/13.9.0/ucvm-13.9.0.tar.gz.md5 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 [http://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide#Easy_Method installation guide].

The first step to installing UCVM is to download the latest UCVM distribution. Then, you will need:

* [http://hypocenter.usc.edu/research/ucvm/13.9.0/libraries/proj-4.8.0.tar.gz Proj-4 version 4.8.0]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/libraries/euclid3-1.3.tar.gz 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:

* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvms4.tar.gz CVM-S4]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvmh1191.tar.gz CVM-H 11.9.1]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvms423.tar.gz CVM-S4.23]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cencal080.tar.gz CenCal 0.8.0]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvm-nci.tar.gz SCEC CVM-NCI]
* [http://geology.utah.gov/ghp/consultants/geophysical_data/zip/wfcvm_3c.tgz Magistrale Wasatch Front CVM]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvm-cmrg.tar.gz Graves Cape Mendocino]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvmlt-13.9.0.tar.gz Lin-Thurber Statewide]
* [http://hypocenter.usc.edu/research/ucvm/13.9.0/models/cvm-tape.tar.gz 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.

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf proj-4.8.0.tar.gz<br />
cd proj-4.8.0<br/>
./configure --prefix=$UCVM_DIR/lib/proj-4 --with-jni=no<br />
make<br />
make install
</code>
</blockquote>

===== Euclid-3 1.3 =====

Download the Euclid3 distribution file and then follow these commands.

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf euclid3-1.3.tar.gz<br />
cd euclid3-1.3<br/>
./configure --prefix=$UCVM_DIR/lib/euclid3<br />
make<br />
make install
</code>
</blockquote>

===== 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:

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf cvms4.tar.gz<br />
cd CVM-S<br />
./configure --prefix=$UCVM_DIR/model/cvms4<br />
make<br />
make install<br />
</code>
</blockquote>

===== 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:

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf cvmh1191.tar.gz<br />
cd CVM-H<br />
./configure --prefix=$UCVM_DIR/model/cvmh1191<br />
make<br />
make install<br />
</code>
</blockquote>

===== 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:

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf cvms423.tar.gz<br />
cd CVM-SI<br />
./configure --prefix=$UCVM_DIR/model/cvms423<br />
make<br />
make install<br />
</code>
</blockquote>

===== CenCal 0.8.0 =====

CenCal is a USGS-developed model of the Bay Area. To install, run these commands after downloading the model:

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf cencal080.tar.gz<br />
cd cencal<br />
./configure --prefix=$UCVM_DIR/model/cencal<br />
make<br />
make install<br />
</code>
</blockquote>

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

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf wfcvm_3c.tgz<br />
cd WFCVM3c<br />
gfortran -c -fpic wf_cvm3c.f<br />
gcc -shared -o libwfcvm.so wf_cvm3c.o -lgfortran<br />
ar rcs libwfcvm.a wf_cvm3c.o<br />
mkdir -p $UCVM_DIR/model/wfcvm<br />
cp ./* $UCVM_DIR/model/wfcvm<br />
</code>
</blockquote>

=== 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:

<blockquote>
<code style="font-size: 12px; background-color: white;">
tar zxvf ucvm-13.9.0.tar.gz<br />
cd UCVM
</code>
</blockquote>

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'''<br />
--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'''<br />
--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'''<br />
--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'''<br />
--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'''<br />
--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'''<br />
--with-etree-include-path=$UCVM_DIR/lib/euclid3/include --with-etree-lib-path=$UCVM_DIR/lib/euclid3/lib

'''Proj-4 4.8.0'''<br />
--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'''<br />
--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:

<blockquote>
<code style="font-size: 12px; background-color: white;">
./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
</code>
</blockquote>

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

<blockquote>
<code style="font-size: 12px; background-color: white;">
./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
</code>
</blockquote>

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

<blockquote>
<code style="font-size: 12px; background-color: white;">
make<br />
make install<br />
make check<br />
</code>
</blockquote>

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 [http://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide#Single_Core_Command_Reference 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.

{| class="wikitable" border="1"
|-
! 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:

{| class="wikitable" border="1"
|-
! 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.

{| class="wikitable" border="1"
|-
! 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:

{| class="wikitable" border="1"
|-
! 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 <code>ucvm_setparam()</code>function. The following model flags are supported:

{| class="wikitable" border="1"
|-
! 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.

[[File:UCVM_Tiling_Concept.png|256px|thumb|right|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 [http://scec.usc.edu/scecpedia/UCVM_13.9.0_User_Guide main user guide].