Skip to content

Home

Jump to bottom
Philip Maechling edited this page Aug 4, 2025 · 58 revisions

Overview of SCEC UCVM

This wiki documents SCEC's UCVM source code repository for UCVM v25.7. This version of UCVM integrates new velocity models, improves the installation proces, and incorporated GitHub Actions for CI testing workflow.

The SCEC Unified Community Velocity Model (UCVM) software is used to access information, including estimated Vp and Vs seismic wave velocities and density, about the earth's crust.

UCVM provides seismic velocity information for several California regions. Seismic velocities of rocks and sediments at shallow depths determine how strongly an area will shake. By assigning velocities to rock types in the 3-D geologic model, geologists can gain an understanding of the extent of areas of low shear velocity that are most likely to experience localized strong shaking and future earthquake damage. An important application for UCVM is for use in computer simulations of California earthquakes.

The Unified Community Velocity Model (UCVM) software framework is a collection of software tools designed to provide a standard interface to multiple, alternative, California velocity models. UCVM development is an interdisciplinary research collaboration involving geoscientists, computer scientists, and software developers. UCVM is used in high resolution 3D wave propagation simulations for California.

This version of UCVM includes several new velocity models developed by collaborating research organizations, including the USGS, University of Wisconsin, LLNL, and others. A list of the available models are posted here: Registered CVMs. Descriptions of each model and references are posted here: Model-Specific-Notes. For authoritative information about how these models were developed and guidance on their appropriate use, please refer to the original model developers.

Velocity models that can be queried by UCVM are identified by both a descriptive name and an abbreviation that is used in UCVM commands. Users should first locate the model of interest by its descriptive name, then use the corresponding abbreviation to access it within UCVM.

To separate the UCVM software from the original model software and data, we have committed the UCVM software into its own GitHub repository, and now most models are stored in their own GitHub repositories. The UCVM installation process retrieves data from multiple GitHub repositories, including the collection of GitHub repositories listed below.

Collection of repositories in UCVM ecosystem

  1. This UCVM github repository is for the UCVM core package that provides the UCVM command line interfaces and linkable APIs.

  2. These CVM velocity models are managed in their own github repositories

The following models are not distributed as part of the standard UCVM distribution, because of their large size and limited utility. Please contact UCVM developers if you need access to these:

  1. UCVM matplotlib-based plotting scripts are located in the UCVM plotting package github repository. These scripts currently use Python 3.

  2. Scripts for retrieving and running UCVM Docker images are located in the UCVM Docker repository github repository.

  3. Scripts for access and manipulate the UCVM metadata files generated by the UCVM core and by the UCVM plotting scripts UVM metadata utilities.

Changes in UCVM v25.7

Starting with this UCVM v25.7 release, we have updated UCVM to use a new version of PROJ, called PROJ 8.1.1. The USGS CenCal velocity model, which was previously accessible through UCVM, depends on an earlier version of PROJ, so this model is no longer included in UCVM. However, the newer USGS San Francisco Bay Region velocity model v21.1, which is an updated version of the CenCal model, is available in this UCVM release.

SCEC has also developed several high-resolution, large-scale regional velocity models for use in CyberShake simulations, including CS173, CS173-H, and CS248. These models are maintained in UCVM to support reproducibility of previous CyberShake runs. Because of their size (over 100 GB) and their specific design for CyberShake workflows, they are not included in the standard UCVM distribution.

If you need access to these models, please contact the UCVM development team at [email protected], or open an issue on the UCVM GitHub repository, and we will assist you with installation.

Documentation

UCVM is distributed as open-source scientific software. It can be installed compiled and run on most Linux-based computer systems if the system includes software development tools including Python, C, and Fortran compilers, and other software tools.

Software and User Support

Issue Tracking:

Project Support

UCVM was developed with support from National Science Foundation (NSF), US Geological Survey (USGS), and other sources.

UCVM Developers

Contributors to UCVM development are listed in the Credits file.

Acknowledging Use of UCVM Software

References, citations, and acknowledgements help us obtain continued support for the development of the UCVM software. If you use the UCVM software in your research, please include the citation of the UCVM paper in the references/bibliography section of your publication. This is more effective than you providing in-text acknowledgements.

  • Preferred Reference: Small, P., Gill, D., Maechling, P. J., Taborda, R., Callaghan, S., Jordan, T. H., Ely, G. P., Olsen, K. B., & Goulet, C. A. (2017). The SCEC Unified Community Velocity Model Software Framework. Seismological Research Letters, 88(5). doi:10.1785/0220170082

  • Preferred Citation: The SCEC Unified Community Velocity Model Software, Release Date: 6 November 2021, https://doi.org/10.5281/zenodo.5651277

  • Example Acknowlegement: We would like to acknowledge the use of the SCEC Unified Community Velocity Model Software (Small 2017) in this research.

License

The UCVM software is released using a BSD-3 open-source license. Please see the LICENSE.md file for distribution license and disclaimers. The underlying velocity models may be released under their own open-source license.

Shield: CC BY 4.0

This work is licensed under a Creative Commons Attribution 4.0 International License.

CC BY 4.0

UCVM Documentation

  1. Overview and Introduction
  2. Installation
  3. Registered CVMs
    1. Model-Specific-Notes
  4. UCVM Configuration File
  5. Setting the UCVM Environment
  6. Basic UCVM Commands
    1. Query by Elevation or Depth
    2. Ely/Jordan GTL
    3. Plotting Scripts
  7. List of Commands
    1. Manual Pages
    2. Executables
    3. Scripts
    4. Examples
  8. Tutorials
    1. ucvm_query
    2. makegrid.sh
    3. Make-Grid
    4. Adding GTL
    5. Basin-Query
    6. ucvm2mesh
    7. vs30_query
  9. UCVM-Docker
    1. Using-UCVM-Docker
  10. References
  11. UCVM Query Parameters
  12. Model Specific Query Behavior
  13. Model Specific GTLs
  14. System-specific Builds
  15. Model References
  16. Concepts
    1. GitHub Branches
    2. Vs30 Info
    3. UCVM Plotting
    4. C-API
    5. FORTRAN-API
    6. Projections
  17. Test Cases
    1. GTL-Testing
      1. CVM-H GTLs
      2. CVM-S5 GTLs
      3. CVM-S4 GTLs
      4. CVMSI GTLs
      5. CCA GTLs
      6. 1D GTLs
      7. BBP1D GTLs
    2. Other CVM-H-Tests
  18. Earlier Documentation
Clone this wiki locally