View source for 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:
# UNIX operating system (Linux, Solaris, MacOS)
# GCC and Fortran compilers (MPI wrappers such as mpicc are OK)
# tar for opening the compressed files


== Download ==

#Start at SCEC website: [http://scec.usc.edu/scecpedia/CVM-H http://scec.usc.edu/scecpedia/UCVM]
#Navigate to the Downloads section of the [[UCVM]] web page.
#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 (2.8 GB), so the download make take awhile.


== CheckSum Test ==

Not currently necessary.


== Installation ==

The general steps for installing UCVM are:

# Install Etree and Proj.4 packages
# Install one or more velocity models
# Define environment variables describing where Etree/Proj.4/models are located
# Run the UCVM installer
# 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

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 velocities models that you wish to use with UCVM.

For the SCEC CVM-H model:
 % tar xvf cvmh-11.7.0.tgz
 % cd cvmh
 % make all

For the SCEC CVM-s model:
 % tar xvf cvms-11.7.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 xvf ucvm-11.7.0.tar

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 and install the software:

 % cd ucvm-11.7.0
 % ./configure --prefix=/opt/ucvm LDFLAGS="-L${CVMH_DIR}/gctpc/lib -L${CVMH_DIR}/lib -L${CVMS_DIR}/lib 
 -L${ETREE_DIR}/libsrc -L${PROJ4_DIR}/lib" CFLAGS="-I${CVMH_DIR}/include -I${CVMS_DIR}/include -I${ETREE_DIR}/libsrc -I${PROJ4_DIR}/include"
 % make; make install

Where "opt/ucvm" is the target install directory of yor choice.

On a more exotic Linux system such as NICS Kraken, use the following commands (note the "-static" flag):

 % cd ucvm-11.7.0
 % ./configure --prefix=/opt/ucvm LDFLAGS="-static -L${CVMH_DIR}/gctpc/lib -L${CVMH_DIR}/lib -L${CVMS_DIR}/lib 
 -L${ETREE_DIR}/libsrc -L${PROJ4_DIR}/lib" CFLAGS="-I${CVMH_DIR}/include -I${CVMS_DIR}/include -I${ETREE_DIR}/libsrc -I${PROJ4_DIR}/include"
 % make; make install


Finally, edit the UCVM configuration file ${UCVM_INSTALL_DIR}/conf/ucvm.conf. Uncomment and setup the following config lines, replacing
UCVM_INSTALL_DIR, CVMH_DIR, CVMS_DIR with your installation directories:

 ucvm_modelpath=${UCVM_INSTALL_DIR}/model/ucvm
 cvms_modelpath=${CVMS_DIR}/src
 cvmh_modelpath=${CVMH_DIR}/bin


== Unit Tests ==

None currently implemented.


== Acceptance Tests ==

None currently implemented.


= Framework Description =

Described in [[UCVM API]].


= Extracting Values from UCVM =

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

Note that the input can be either (lon, lat, elevation) or (lon, lat, depth).
Execute ucvm_query from the /bin directory with the command:

 % ./ucvm_query -m cvms -f ../conf/ucvm.conf


== Extracting Values in a C Program ==

Described in [[UCVM API]].


= History of UCVM Releases =


= 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 CVM-H,
and for any suggestions for the delivery of the code or for this manual.

Please reference at least Süss and Shaw (2003) if you use this model; other references should
be considered, depending on the purpose (see History of CVM-H releases section).


= References =

#'''Boore, D. M., and W. B. Joyner (1997)''', Site amplifications for generic rock sites, Bull. Seis. Soc. Am., 87 (2), 327-341.
#'''Brocher, T. M. (2005)''', Empirical relations between elastic wavespeeds and density in the Earth's crust, Bull. Seis. Soc. Am., 95 (6), 2081-2092.
#'''Dreger, D. S., and D. V. Helmberger (1991)''', Source parameters of the Sierra Madre earthquake from regional and local body waves, Geophys. Res. Lett., 18 (11), 2015-2018.
#'''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. [http://earth.usc.edu/~gely/pub/Ely2010-AGU.pdf http://earth.usc.edu/~gely/pub/Ely2010-AGU.pdf]
#'''Hauksson, E. (2000)''', Crustal structure and seismicity distribution adjacent to the Pacific and North America plate boundary in southern California, J. Geophys. Res., 105 (B6), 13,875-13,903.
#'''Kanamori, H., and D. Hadley (1975)''', Crustal structure and temporal velocity change in southern California, Pure App. Geophys., 113, 257-280.
#'''Komatitsch, D., Q. Liu, J. Tromp, P. Süss, C. Stidham, and J. H. Shaw (2004)''', Simulations of ground motion in the Los Angeles basin based upon the spectral-element method, Bull. Seis. Soc. Am., 94 (1), 187-206.
#'''Lin, G., P. M. Shearer, E. Hauksson, and C. H. Thurber (2007)''', A three-dimensional crustal seismic velocity model for southern California from a composite event method, J. Geophys. Res., 112, B11306, doi:10.1029/2007JB004977.
#'''Lovely, P., J. H. Shaw, Q. Liu, and J. Tromp (2006)''', A structural VP model of the Salton Trough, California, and its implications for seismic hazard, Bull. Seis. Soc. Am., 96 (5), 1882-1896.
#'''Ludwig, W. J., J. E. Nafe, and C. L. Drake (1970)''', Seismic refraction, in New Concepts of Sea Floor Evolution, The Sea: Ideas and Observations on Progress in the Study of the Seas, vol. 4, edited by A. E. Maxwell, pp. 53-84, Wiley-Interscience, New York.
#'''Magistrale, H. (2002)''', Improvements to the SCEC Community Velocity Model, in 2002 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 12, p. 93.
#'''Magistrale, H., S. Day, R. W. Clayton, and R. Graves (2000)''', The SCEC Southern California reference three-dimensional velocity model Version 2, Bull. Seis. Soc. Am., 90 (6B), S65-S76.
#'''Mayhew, J. E., and K. B. Olsen (2010)''', Goodness-of-fit criteria for broadband synthetic seismograms, with application to the 2008 Mw 5.4 Chino Hills, CA, earthquake, Seis. Res. Lett. (submitted).
#'''McCulloh, T. H. (1960)''', Gravity variations and the geology of the Los Angeles basin of California, Tech. rep., U.S. Geol. Survey, Washington, D.C., Professional Paper 400-B.
#'''Munster, J. (2007)''', Velocity Model of the Santa Maria Basin, CA, and its Implications for Seismic Hazard Assessment, undergraduate thesis, Harvard University, Cambridge, Mass., USA.
#'''Plesch, A., P. Suess, J. Munster, J. H. Shaw, E. Hauksson, T. Tanimoto, and members of the USR Working Group (2007)''', A new velocity model for southern California: CVM-H 5.0, in 2007 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 17, p. 159.
#'''Plesch, A., J. H. Shaw, E. Hauksson, and T. Tanimoto (2008)''', SCEC Community Velocity Model (CVM-H 5.5), in 2008 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 18, p. 142.
#'''Plesch, A., C. Tape, J. H. Shaw, and members of the USR working group (2009)''', CVM-H 6.0: Inversion integration, the San Joaquin Valley and other advances in the community velocity model, in 2009 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 19, pp. 260-261. Prindle, K., and T. Tanimoto (2006), Teleseismic surface wave study for S-wave velocity structure under an array: Southern California, Geophys. J. Int., 166, 601-621.
#'''Shaw, J. H., A. Plesch, M. P. Süss, and the SCEC USE Focus Area Group (2004)''', Progress toward a Unified Structural Representation, in 2004 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 14, pp. 61-62.
#'''Stidham, C., M. P. Suess, J. Shaw, D. Komatitsch, and J. Tromp (2001a)''', 3D velocity and density model of the LA basin and spectral element method earthquake simulations, in 2001 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 11, p. 113.
#'''Stidham, C., M. P. Süss, and J. H. Shaw (2001b)''', 3D density and velocity model of the Los Angeles basin, in Geol. Soc. Am. 2001 Annual Meeting Abstracts, vol. 33, Geol. Soc. Am., Denver, Colo., USA.
#'''Suess, M. P., J. H. Shaw, P. Lovely, J. Mueller, and A. Plesch (2005)''', The new SCEC Community Velocity Model (CVM-H 2.0), in 2005 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 15, p. 189.
#'''Suess, M. P., J. H. Shaw, E. Hauksson, A. Plesch, and J. Mueller (2006)''', New SCEC Community Velocity Model (CVM-H 4.0), in 2006 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 16, p. 170.
#'''Suess, P., and J. Shaw (2002)''', Uncertainty and the creation of high resolution 3D velocity models in Southern California, in 2002 Southern California Earthquake Center Annual Meeting, Proceedings and Abstracts, vol. 12, p. 135.
#'''Süss, M. P., and J. H. Shaw (2003)''', P-wave seismic velocity structure derived from sonic logs and industry reflection data in the Los Angeles basin, California, J. Geophys. Res., 108 (B3), 2170, doi:10.1029/2001JB001628.
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2009)''', Adjoint tomography of the southern California crust, Science, 325, 988-992.
#'''Tape, C., Q. Liu, A. Maggi, and J. Tromp (2010)''', Seismic tomography of the southern California crust based on spectral-element and adjoint methods, Geophys. J. Int., 180, 433-462.
#'''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.
#'''Wald, L. A., L. K. Hutton, and D. D. Given (1995)''', The Southern California Network Bulletin: 1990-1993 summary, Seis. Res. Lett., 66 (1), 9-19.
#'''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.
#'''Yan, Z., and R. W. Clayton (2007)''', Regional mapping of the crustal structure in southern California from receiver functions, J. Geophys. Res., 112, B05311, doi:10.1029/2006JB004622.


= Miscellaneous Technical Notes =


= License and Disclaimer =

== License ==

Copyright (c)2011 Southern California Earthquake Center (SCEC) and the
University of Southern California (USC). This copyright applies to the CVM-H 
codebase as a whole, or any individual distributed applications, not covered 
by the CVM-H v6.3 Harvard software license. 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 CVM-H 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 CVM-H web site will be 
corrected. 


Software and its documentation made available on the CVM-H web site: 

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