UCVM User Guide

Overview

UCVM is a software framework for creating and distributing a state-wide California velocity model.

Requirements

The system requirements are as follows:

1. UNIX operating system (Linux, Solaris, MacOS)
2. GNU gcc/gfortran compilers (MPI wrappers such as mpicc are OK)
3. tar for opening the compressed files

Download

1. Start at SCEC website: http://scec.usc.edu/scecpedia/UCVM
2. Navigate to the Downloads section of the UCVM web page.
3. Click the download link to download the latest source code distribution file and any listed dependencies. This is typically posted as a tar and gzipped file (tgz format). The source code distribution file is large (280 Mb), so the download make take awhile.

CheckSum Test

Not currently implemented.

Installation

The general steps for installing UCVM are:

1. Install Etree and Proj.4 packages
2. Install one or more velocity models
3. Define environment variables describing where Etree/Proj.4/models are located
4. Run the UCVM installer
5. Configure UCVM

First, install the Etree and Proj.4 packages which are required by UCVM. The INSTALL/README instructions in each distribution describe how to install them, but generally:

For the Euclid Etree library:

% tar xvf euclid-latest.tar
% cd ./euclide-3.12/libsrc
% make all

If installing the Etree library on a Lustre filesystem (NICS Kraken, TACC Ranger, NCCS Jaguar), you must enable IOBUF. Please see Cvmbycols#Technical_Note_for_Lustre_Filesystems for special installation instructions.

For the Proj.4 library:

% tar xvf proj-4.7.0.tar
% cd proj-4.7.0
% ./configure --prefix=<your desired install directory>
% make; make install

Be sure to note where you installed these two packages. You will need this information later in the installation process.

Then, install the velocity models that you wish to use with UCVM. Ensure they are compiled with gcc/gfortran.

For the SCEC CVM-H model:

% tar xvf cvmh-11.9.0.tgz
% cd cvmh
% make all

For the SCEC CVM-S model:

% tar xvf cvms-11.9.0.tgz
% cd cvms/src
% make all

Again, be sure to note where you installed the community velocity models.

Declare environment variables with the paths to the Etree library, Proj.4 library, and velocity models that you previously installed.

ETREE_DIR=<Etree install path>
PROJ4_DIR=<Proj.4 install path>
CVMH_DIR=<CVM-H install path>
CVMS_DIR=<CVM-S install path>

In a bash shell, for example, the ETREE_DIR environment variable can be declared with the command:

% ETREE_DIR=/opt/etree;export ETREE_DIR

In a csh shell:

% setenv ETREE_DIR /opt/etree

Now unpack the UCVM software distribution:

% tar zxvf ucvm-11.9.0.tar.gz

The build configuration differs slightly depending on where you wish to run UCVM. On a standard Linux system with gcc, run the following commands to build the software with CVM-H and CVM-S enabled:

% cd ucvm-11.9.0
% ./configure --prefix=${UCVM_INSTALL_DIR} --with-etree-include-path="${ETREE_DIR}/libsrc" 
--with-etree-lib-path="${ETREE_DIR}/libsrc" --with-proj4-include-path="${PROJ4_DIR}/include" 
--with-proj4-lib-path="${PROJ4_DIR}/lib" --with-cvmh-include-path="${CVMH_DIR}/include" --with-cvmh-lib-path="${CVMH_DIR}/lib" 
--with-gctpc-lib-path="${CVMH_DIR}/gctpc/lib" --with-cvms-include-path="${CVMS_DIR}/include" --with-cvms-lib-path="${CVMS_DIR}/lib" 
--with-cvmh-model-path="${CVMH_DIR}/bin" --with-cvms-model-path="${CVMS_DIR}/src"
% make

Where "${UCVM_INSTALL_DIR}" is the target install directory of your choice. You may define it as an enviroment variable or just specify it directly as the argument to prefix. The above example used CVM-H and CVM-S but any of the following models may be enabled: SCEC CVM-H, SCEC CVM-S, SCEC CVM-SI, USGS CenCalVM, and WFCVM. For each velocity model you want to use, the configure script needs to know where to find the velocity model's library files (.a or .so), header files (.h), and model files so that they can be linked into UCVM.

Check that the package was built correctly with the following command:

% make check

Verify that all unit tests and acceptance tests pass.

Install the software to the desired target location with the following command:

% make install

On a more exotic Linux system such as NICS Kraken, use the following commands:

% cd ucvm-11.7.0
% module add iobuf
% ./configure --prefix=${UCVM_INSTALL_DIR} --enable-static --enable-iobuf --with-etree-include-path="${ETREE_DIR}/libsrc" 
--with-etree-lib-path="${ETREE_DIR}/libsrc" --with-proj4-include-path="${PROJ4_DIR}/include" 
--with-proj4-lib-path="${PROJ4_DIR}/lib" --with-cvmh-include-path="${CVMH_DIR}/include" --with-cvmh-lib-path="${CVMH_DIR}/lib" 
--with-gctpc-lib-path="${CVMH_DIR}/gctpc/lib" --with-cvms-include-path="${CVMS_DIR}/include" --with-cvms-lib-path="${CVMS_DIR}/lib" 
--with-cvmh-model-path="${CVMH_DIR}/bin" --with-cvms-model-path="${CVMS_DIR}/src" CC=cc
% make; make check; make install

A few notes:

• Some systems require applications to be linked statically (NICS Kraken, NCCS Jaguar)
• Lustre filesystems require linking with IOBUF module (NICS Kraken example above)
• For each velocity model that you wish to enable, the configure script needs to be told where to find the library file(s), the header file(s), and the model files. The configure script will check that the libraries and headers are present and correctly installed, and it will setup the Makefiles so that UCVM is built with that model enabled and properly configured.
• The script will attempt to auto-detect a GNU compliant compiler. If an MPI wrapper is found, the MPI version of UCVM is compiled, otherwise the serial version is built. The compiler may be overridden with the command 'CC="mpicc"' for example.

Unit Tests

Unit tests may be executed with the command:

% make check

All tests should result in a PASS.

Acceptance Tests

Acceptance tests may be executed with the command:

% make check

All tests should result in a PASS.

Framework Description

Described in UCVM API.

Extracting Values from UCVM

Two methods are provided for extracting material properties from UCVM: 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:

Extracting Values on the Command Line

The ucvm_query utility is provided for querying a set of community velocity models. Points may either be input interactively or via a text file, and can be either (lon, lat, elevation) or (lon, lat, depth).

The following output shows an interactive example on three points (followed by a Cntl-D to terminate input) using the CVM-S model. Starting in the UCVM installation directory, enter these commands:

% cd bin
% ./ucvm_query -m cvms -f ../conf/ucvm.conf
Using Geo Depth coordinates as default mode.
-118.0 34.0 0.0
-118.0 34.0 100.0
-118.0 34.0 1000.0 <Cntrl-D>
 -118.0000    34.0000      0.000    295.679    390.000       cvms    696.491    213.000   1974.976       none      0.000      0.000      0.000      crust    696.491    213.000   1974.976
 -118.0000    34.0000    100.000    295.679    390.000       cvms   1683.174    603.470   2130.773       none      0.000      0.000      0.000      crust   1683.174    603.470   2130.773
 -118.0000    34.0000   1000.000    295.679    390.000       cvms   3660.809   2056.628   2443.042       none      0.000      0.000      0.000      crust   3660.809   2056.628   2443.042

Similarly, here is an example for the CVM-H model:

% cd bin
% ./ucvm_query -m cvmh -f ../conf/ucvm.conf
Using Geo Depth coordinates as default mode.
-118.0 34.0 0.0
-118.0 34.0 100.0
-118.0 34.0 1000.0
 -118.0000    34.0000      0.000    295.679    390.000       cvmh    824.177    195.000   1084.062       none      0.000      0.000      0.000      crust    824.177    195.000   1084.062
 -118.0000    34.0000    100.000    295.679    390.000       cvmh   2371.500    727.748   2051.320       none      0.000      0.000      0.000      crust   2371.500    727.748   2051.320
 -118.0000    34.0000   1000.000    295.679    390.000       cvmh   2616.063   1082.813   2127.783       none      0.000      0.000      0.000      crust   2616.063   1082.813   2127.783

Extracting Values in a C Program

Described in UCVM API.

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). SCEC is funded by NSF Cooperative Agreement EAR-0106924 and USGS Cooperative Agreement 02HQAG0008.

Contributions to this manual were made by: Patrick Small, and Philip Maechling.

Please email software@scec.org for help on downloading and using UCVM, and for any suggestions for the delivery of the code or for this manual.

Please reference at least Small et al (2011) if you use this software framework; other references should be considered, depending on the purpose.

References

1. 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. [Ely2010-AGU.pdf]
2. Graves, R. (1994), Rupture History and Strong Motion Modeling of the 1992 Cape Mendocino Earthquake, USGS External Grant Report
3. Lin, G., C. H. Thurber, H. Zhang, E. Hauksson, P. Shearer, F. Waldhauser, T. M. Brocher, and J. Hardebeck (2010), A California statewide three-dimensional seismic velocity model from both absolute and differential Times, Bull. Seism. Soc. Am., 100, in press. supplemental
4. Small, P., P. Maechling, T. Jordan, G. Ely, and R. Taborda (2011), SCEC UCVM - Unified California Velocity Model, in 2011 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. TBD, p. TBD.
5. Taborda R., López J., O'Hallaron D., Tu T. and Bielak J. (2007), A review of the current approach to CVM-Etrees, SCEC Annual Meeting, Palm Springs, CA, USA, September 8–12. [1]
6. Wald, D. J., and T. I. Allen (2007), Topographic slope as a proxy for seismic site conditions and amplification, Bull. Seism. Soc. Am., 97 (5), 1379-1395, doi:10.1785/0120060267.
7. Wills, C. J., and K. B. Clahan (2006), Developing a map of geologically defined site-condition categories for California, Bull. Seism. Soc. Am., 96 (4A), 1483-1501, doi:10.1785/0120050179.

License and Disclaimer

License

Copyright (c)2011 Southern California Earthquake Center (SCEC) and the University of Southern California (USC). This copyright applies to the UCVM codebase as a whole, or any individual distributed applications. 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 UCVM 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 UCVM web site will be corrected.

Software and its documentation made available on the UCVM web site:

6. Could include technical or other mistakes, inaccuracies or typographical errors. UCVM 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 UCVM 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 UCVM 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 UCVM website, its contributors, or USC shall create any warranty for the software.