How to Guides
There are several ways to get access to UCVM. Below, we outline several of the options:
-
SCEC Community Velocity Model Explorer CVM explorer provides a web-based interface which can be used to access UCVM velocity models. A key advantange of this approach is that no UCVM software installation required. Good for moderate number of query points using the map-based interactive interface and for producing and visualize various downloadable 2D and 1D plots .
-
UCVM Docker Images Users can run UCVM in Docker on their laptop, even if their laptop runs a non-Linux operating system including Mac OS and Windows. After installing free Docker software on most computers (e.g. Linux, MacOS, Windows), users can run an UCVM Docker image in a terminal window on their computer. Instructions for using the ucvm_docker images can be found in the ucvm_docker repository listed above. Good for small to moderate number of query commands and for users who are comfortable running command line programs in a terminal window.
-
UCVM source code The UCVM core source code distribution is written primarily in C-language. Advanced users building large simulation meshes, wanting to install many of the UCVM models, or wanting to run large parallel queries of the CVM models, should install the UCVM software on a Linux system. The UCVM software framework has several MPI-based executables. These parallel extensions use MPI to signicantly speed-up the extraction of material properties from installed velocity models. These UCVM mpi-based executables are built using the automake system if the required MPI libraries are found in the installation computing environment. To build and run UCVM on Linux clusters, users should retrieve UCVM source code from Github and compile it on a Linux-type system using GNU compilers.
- UCVM users may find the UCVM explorer easier to use than building UCVM from source code. UCVM Docker images can also be used for moderate UCVM queries, without requiring an installation of UCVM from source code. And UCVM Docker images run on Mac, Windows, and Linux systems. However, large parallel mesh extractions on supercomputer will require users to compile and run on systems with recent Linux and GNU Compilers.
The UCVM Software framework integrates a wide range of scientific software including software written in C, FORTRAN, and Python. This repository contains the core UCVM software which is primarily written in C. During the UCVM compile and installation process for UCVM, it retrieves the community velocity models selected by the user during installation. The required velocity model source code and data files are retrieved from backend storage at USC Center for Advanced Research Computing (CARC) during UCVM installation.
UCVM is developed for computers that use recent Linux distributions with automake and GNU compilers. It uses GNU automake, C and Fortran compilers, and Python 3. Since UCVM is to build large simulation meshes on supercomputers, SCEC uses the USC Center for Advanced Research Computing (CARC) Linux cluster, based on CentOS as our primary UCVM software develoment environment. It is possible to build and run UCVM in other computing environments, like MacOS, but we officially support only Linux distributions with specific compiler and software versions.
- Linux operating system (e.g. Centos-8) x86_64-linux
- vi or emacs or nano - Text Editors
- Automake, Autoconf build tools for Linux
- Git client
- GNU gcc/gfortran compilers version 10+
- Python 3.8 (Anaconda 4.10.0 (64-bit))
External Libraries Installed by UCVM (provided during installation):
- Euclid Etree library: http://www.cs.cmu.edu/~euclid
- PROJ 8.1.1 projection library: http://trac.osgeo.org/proj
- FFTW 3.3.3
- NetCDF 4.9.2
- HDF5-1.10.9
- OpenSSL-3.0.8
- Tiff-4.5.0
- sqlite-autoconf-3400100
- Curl-7.87.0
Optional Software for building MPI binaries:
- openmpi 4.0.2
USC Discovery system, where UCVM is developed, uses a module load system. We have tested the UCVM distribution using the following modules. This is a known working configuration. Other combinations may work, also, but they have not been systematically tested.
$ module -t list usc/13.3.0 gcc/13.3.0 python/3.11.9 openmpi/5.0.5 pmix/5.0.2 libxml2/2.10.3 perl/5.38.2 git/2.45.2 openblas/0.3.28 libtool/2.4.7
The following California velocity models packages are included as part of a standard UCVM installation. Each of these models can be downloaded during the installation process:
-
SCEC CVM-S4: 'cvms'
-
SCEC CVM-S4.26: 'cvms5'
-
SCEC CVM-S4.26.M01: 'cvmsi'
-
SCEC CVM-H v15.1: 'cvmh'
-
ALBACORE: 'albacore': [Albacore Offshore jouthern California model]
-
CANVAS: 'canvas'
-
SCEC CCA06: 'cca': [Tomography improved Central California model from CVM-S4 and USGS Cencal starting models.]
-
CS173 : 'cs173'
-
CS173h : 'cs173h'
-
CS248: 'cs248'
-
USGS San Francisco Bay: 'sfcvm'
-
San Jacinto Fault Zone: 'sjfz'
-
Coachela Valley: 'cvlsu'
-
Imperial Valley: 'ivlsu'
-
UW Statewide: 'uwlinca'
-
UW San Francico Bay: 'uwsfbcvm'
-
Wasatch Front Utah: 'wfcvm'
-
Deprecated: USGS BayArea Velocity Model 0.8.3: 'cencal'
The CVM-H basins are released separately as component-based regional velocity models that are constructured from components such as basin and background models. These CVM-H basin models are identifical material properties, in their values and resolution, as the basin models in CVM-H v15.2, but the basins are provided as standalone models. UCVM currently support combining these basin models with other UCVM models through a tiling process. In this process, the models are combined, but no smoothing is done between the models.
- CVM-H LA Basin : 'cvmhlabn'
- CVM-H San Gabriel Basin : 'cvmhsgbn'
- CVM-H Ventura Basin : 'cvmhvbn'
- CVM-H Inner Borderland Basin : 'cvmhibbn'
- CVM-H Ridge Basin : 'cvmhrbn'
- CVM-H Salton Trough Basin : 'cvmhstbn'
- CVM-H Santa Bernardino Basin : 'cvmhsbbn'
- CVM-H Santa Barbara Channel Basin : 'cvmhsbcbn'
- CVM-H Santa Maria Basin : 'cvmhsmbn'
Three 1D models are defined in the ucvm codebase:
- Southern California 1D Velocity Model: '1d': A modified Hadley-Kanamori 1D model
- Southern California Northridge Region 1D Velocity Model: 'bbp1d': A 1D model developed by R. Graves for use in LA region simulations
- SFCVM Sierra Foothills 1D Velocity Model : 'sf1d': 1D model developed for Cybershake 24.8
Previous releases of UCVM provided several "tiled" models that were created and used for CyberShake simulations.
These are very large models that have been preserved to support analysis and reproducibility of previous SCEC
CyberShake results. Unless you are analyzing CyberShake results, it is unlikely you will want to use these models.
These models are available on request.
- SCEC CS17.3 CyberShake Central California - 2017
- SCEC CS17.3H CyberShake Central Califorina w/ Harvard San Joaquin and Santa Maria Basins
- SCEC CS248 CyberShake Northen California w/SFCVM, CCA and sf1d velocity models
UCVM installation from source code on a Linux computer requires two directories:
-
The source directory. The source directory requires at least 23Gb of storage when installing all available models.
-
The installation directory. The installation directory requires at least 21Gb of storage when installing all available models.
While preparing to install UCVM, users should identify filesystems on their computer that have these amounts of free disk space.
As part of the installation process, users download the UCVM code from the git repository into the source directory. Once the git distribution has been downloaded, the user will need to retrieve "largefiles" into a largefiles subdirectory in the source directory tree. Once the largefiles have been retrieved, and the user has to run the stage_ucvm_files.py script that moves the files into the proper subdirectories for installation, the source directory tree will require at least 231Gb of storage, assuming all standard CVM models are installed.
In general use, once the UCVM software has been installed, all required files are copied into the installation directory tree and the source directory tree can be deleted. Advanced users that want to modify the UCVM codebase, or might want to change installation location, or that are building their own customized etrees, will need the source directory tree, in which case, it should not be removed. The installation directory should not be moved once installed because of the model configuration. If a new location is desired, ucvm_setup.py in the source directory should be rerun with the new location.
The UCVM application is built using gnu automake tools. These automake tools extend the standard Make system. While these tools add another layer of complexity into the system, they automatically construct the required Makefiles, and users do not need to edit Makefiles by hand. When the automake tools work properly, they will build the UCVM software automatically, with warnings, but no errors, on a variety of Linux and GNU software stacks. The automake tools, and GNU C and FORTRAN compilers, and a Python 3.6+ distribution must be installed on the target system for the UCVM installation scripts to work.
The basic steps to building the application are:
-
Identify the directories on the installation computer that have sufficient storage for the source directory, the installation directory, and the largefiles collection. Users should also confirm that the installation system has the required compilers (GNU C and Fortran) and Python 3 interpreter.
-
Move to the UCVM source directory. Check the UCVM distribution out from github with:
git clone https://github.com/SCECCode/ucvm.git
- Set the environment variables for UCVM_SRC_PATH and UCVM_INSTALL_PATH
(for bash) %export UCVM_SRC_PATH=YOUR_SOURCE_DIRECTORY/ucvm %export UCVM_INSTALL_PATH=YOUR_INSTALLATION_DIRECTORY
- Move to the UCVM/largefiles subdirectory, the user will run:
./get_largefiles.py
This script runs in a terminal window and asks user which large file is to be retrieved. In this example, the user downloads all available models. We recommend the user selects only the velocity models of interest to minimize storage and installation time.
Getting largefiles for UCVM version: 25.7 Running in ./largefiles source directory. This script will download and install ucvm.e, ucvm_utah.e and several other files. Due to the size of the files, this download could take minutes to hours to complete. Would you like to download cvms5, will need 1.2G? Enter yes or no: yes Would you like to download cca, will need 1.1G? Enter yes or no: yes Would you like to download cvms, will need 326M? Enter yes or no: yes Would you like to download cvmsi, will need 1.6G? Enter yes or no: yes ....
After the user responds to these questions, the window will display the message below when all requested large files are downloaded:
.... Installing files in: /var/www/html/UCVM_rel/model/UCVM/largefiles Retrieving: sfcvm/dependencies nFinished downloading: sfcvm/dependencies Retrieving: fftw Finished downloading: fftw Retrieving: euclid3 Finished downloading: euclid3 Retrieving: hdf5 Finished downloading: hdf5 Retrieving: openssl Finished downloading: openssl Retrieving: tiff Finished downloading: tiff Retrieving: sqlite Finished downloading: sqlite Retrieving: curl Finished downloading: curl Retrieving: proj Finished downloading: proj Retrieving: proj/share/proj Finished downloading: proj/share/proj Retrieving: cvms5.tar.gz Finished downloading: cvms5.tar.gz Retrieving: cca.tar.gz Finished downloading: cca.tar.gz .... Retrieving: test-grid-lib-1d.ref Finished downloading: test-grid-lib-1d.ref Completed all required downloads to build the UCVM programs.
- To check that the downloaded files are intact, the user will run:
./check_largefiles_md5.py
The script will display a message similar to below. If the script reports and errors, please re-download that file, and try again. If you get repeated errors, please contact us for help.
Checking largefiles for UCVM version: 25.7 Checking file: cvms5.tar.gz File: cvms5.tar.gz OK Checking file: cca.tar.gz File: cca.tar.gz OK .... File: test-grid-lib-1d.ref OK Checked 37 UCVM large files with: 37 OK, and: 0 errors
- Still in the UCVM/largefiles subdirectory, to move the largefiles to the required directories for installation, the user will run:
./stage_largefiles.py
The script will display the message below:
.... All required library and model files staged in UCVM work directories.
- Move back to the UCVM source directory and run:
./ucvm_setup.py
- It will ask you questions about the installation directory, and which retrieved models you wish to install. The default installation is to install all the models. The installation script will try to create the specified installation directory. The specified directory does not need to exist.
UCVM 25.7.0 Installation Copyright (C) 2025 University of Southern California. All rights reserved. Using local setup.list and system.list .... Now check system specific conditions. System_data - k: h2ologin System_data - k: all Using local setup.list file Please answer the following questions to install UCVM. Note that this install and build process may take up to an hour depending on your computer speed. Where would you like UCVM to be installed? Enter path or blank to use the default path: YOUR_UCVM_INSTALL_PATH Would you like to install CVM-S4.26? Enter yes or no: .... You have indicated that you would like to install CVM-S4.26 ... You have indicated that you would like to install FFTW, Euclid3, HDF5, OpenSSL, TIFF, Sqlite, Curl, and Proj Now setting up the required UCVM libraries...
- The automake tools will run, configure, make, install, which will build the system, and install it in the installation directory. The config, make, install process may take sometime depending on how many models are selected.
When the script completes successfully, it will display the following instructions:
Installing UCVM software... Running aclocal ==> command used.. aclocal_-I_./m4 Running automake ==> command used.. automake_--add-missing_--force-missing Running autoconf ==> command used.. autoconf Running ./configure for UCVM ==> command used.. ./configure_--enable-silent-rules_--with-fftw-include-path=/var/www/html/UCVM_rel/web/model/UCVM_TARGET/lib/fftw/include_--with-fftw-lib-path=/var/www/html/UCVM_rel/web/model/UCVM_TARGET/lib/fftw/lib_--with-etree-include-path=/var/www/html/UCVM_rel/web/model/UCVM_TARGET/lib/euclid3/include_--with-etree-lib-path=/var/www/html/UCVM_rel/web/model/UCVM_TARGET/lib/euclid3/lib_--with-hdf5-include-path=/var/www/html/UCVM_rel/web/model/UCVM_TARGET/lib/hdf5/include_--with-hdf5-lib-path=/var/www ... Making UCVM ==> command used.. make_clean ==> command used.. make Installing UCVM ==> command used.. make_install Done installing UCVM! .... Installation complete. Installation log file saved at ./setup_log.sh
The UCVM installation script creates a script in the "YOUR_UCVM_INSTALL_PATH/conf/setup_env.sh". When run, this script will set the required PATH, and LD_LIBRARY environment variables needed by UCVM.
(bash) %source YOUR_UCVM_INSTALL_PATH/conf/setup_env.sh
Users could also edit their .bashrc and call this script automatically when they run a process, or when they log into their account.
Add follow line to your ~/.bashrc
source YOUR_UCVM_INSTALL_PATH/conf/setup_env.sh
Now, log out and log back in to setup the required UCVM environment variables. Move to the UCVM installation directory and run the tests script to confirm
% cd YOUR_UCVM_INSTALL_PATH/tests % ./run-testing
Test: UCVM lib initialization PASS Test: UCVM lib add model 1D PASS Test: UCVM lib query 1D PASS Test: UCVM lib get model label 1D PASS Test: UCVM lib setparam querymode geo-depth 1D PASS Test: UCVM lib setparam querymode geo-elev 1D PASS Test: UCVM lib model version 1D PASS Test: UCVM lib add model CVMS5 PASS .... Test: ucvm library 1d model w/ large grid PASS Runnning test test_ssh_generate [SUCCESS] Runnning test test_vs30_query [SUCCESS] Running examples_api query_1d_gtl [SUCCESS] Running examples_programs_ucvm ucvm_query_cvms5 [SUCCESS] Running examples_programs_ucvm ucvm_query_cvms5_c [SUCCESS] Running examples_programs_ucvm2mesh ucvm2mesh_cvms5 [SUCCESS] Running examples_programs_surface ucvm2surface_cvms5 [SUCCESS] Running examples_programs_surface ucvm2surface_cvms5_c [SUCCESS]
Once the tests pass, ucvm is ready to run an example query.
As an cvms example:
% ucvm_query -f ./conf/ucvm.conf -m cvms < ./tests/inputs/test_latlons.txt
You will then see the following output:
Using Geo Depth coordinates as default mode. -118.0000 34.0000 0.000 280.896 468.400 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 50.000 280.896 468.400 cvms 1669.540 548.000 2128.620 none 0.000 0.000 0.000 crust 1669.540 548.000 2128.620 -118.0000 34.0000 100.000 280.896 468.400 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 500.000 280.896 468.400 cvms 3097.562 1656.495 2354.105 none 0.000 0.000 0.000 crust 3097.562 1656.495 2354.105 -118.0000 34.0000 1000.000 280.896 468.400 cvms 3660.809 2056.628 2443.042 none 0.000 0.000 0.000 crust 3660.809 2056.628 2443.042
The UCVM installation processes uses both a UCVM_SRC directory, and an UCVM_INSTALL directory. Once installed, users can save space on their computer by removing the UCVM_SRC directory.
Advanced users that are modifying the UCVM source code should keep the source directory, where they can modify and recompile the code.
UCVM contains MPI codes for building large meshes and for retrieving basin depths using parallel codes and You can confirm the MPI utilities were correctly built and installed using examples in examples/programs. They are designed to run on USC's hpc cluster.
First look in the UCVM executable directory. You should see programs with the _mpi extension. If these do not exist, then the required MPI libraries where not found when the executables were built. These MPI libraries are discovered automatically by the automake programs. In many cases, you can adjust your computing environments (e.g. in many HPC environments you can use "load modules" commands) to make these MPI libraries available. The MPI codes you should expect include the following:
- basin_query_mpi
- basin_query_mpi_complete
- ucvm2mesh_mpi
- ucvm2mesh_mpi_layer
- ucvm2etree_extract_MPI
- ucvm2etree_merge_MPI
- ucvm2etree_sort_MPI
- vs30_query_mpi
Assuming these executables exist in the ucvm/bin directory, then you can run simple MPI examples including the following:
