Home
SCEC's UCVM Software is scientific software used to query seismic velocity models for California and other regions. UCVM is designed to be compiled and run on Linux computers. UCVM involves C, C++, FORTRAN, and python software and uses open-source Linux operating systems and compilers.
This ucvm_docker repo contains scripts for running UCVM Docker Images. The scripts for creating (building) UCVM Docker Images and information about building UCVM docker images is not needed by most users. Those scripts are located in a separate github repository called create_ucvm_docker.
Geoscientists interested in crustal seismic velocity information may use SCEC UCVM software as a standard method for querying the models.
Compiling the UCVM distribution can be a challenge for researchers. SCEC is using Docker virtualization technology to simplify access to UCVM. By using Docker on their Linux, Mac, or PC, computer, users can run a pre-built version of UCVM easily.
Here we provide Docker-based distributions of UCVM and SCEC seismic velocity models. Scientists interested in querying any of 10 U.S. seismic velocity models can retrieve UCVM Docker images that include the model data, and query the model using the ucvm interface.
Users have serveral options for accessing the UCVM software:
- No UCVM software installation required.
- Run UCVM Docker Images in a container on thier local computer
- Users must install a free Docker Docker software client on their computers. Then UCVM runs on the users computer.
- UCVM is used to build large simulation meshes for ground motion simulations.
- The UCVM has parallel extensions that use MPI to signicantly speed-up the extraction of material properties from California velocity models by using parallel extractions. To build and run UCVM on Linux clusters, users can retrieve UCVM souce code from Github and compile it on a Linux-type system using GNU compilers.
UCVM users may find the UCVM Webviewer easier to use than UCVM Docker images. However, researcher may want to use UCVM Docker images their extract material properties from UCVM models for 100-1M data points. Queries below 100 pts might be easier using the website. Points more then 1M may require native installation of UCVM on a Linux server.
Using UCVM Docker images to run UCVM requires basic command line computing skills from users. Users should be comfortable moving around (cd, ls, pwd) at a Linux bash shell. UCVM Docker image users also need to run UCVM command line interfaces with appropriate parameters, like ucvm_query and basin_query.
- User installs Docker client software on their computer (Mac,Windows,Linux)
- User creates an Dockerhub Dockerhub user account
- User open a terminal window on their local computer
- User creates a "target" directory where files will be saved after container exits:
$ mkdir target
- User starts the Docker client on their local computer
- User runs the UCVM Docker image for "cvms5". This abbreviation maps to southern California seismic velocity model named" CVM-S4.26"
$ docker run --rm -it --mount type=bind,source="$(pwd)"/target,destination=/app/target sceccode/ucvm_227_cvms5:0710
Docker will then look on your local system for the specific image "sceccode/ucvm_227_cvms5:0710" and it will look on Dockerhub and retrieve it from there when the image is not found locally.
Using a user on a Mac, with Docker installed and running, here's how to run the UCVM Docker image. The UCVM Docker image contains a small test program that the user can run to confirm the image is working properly on their laptop.
- User goes to Dockerhub and log into dockerhub. This enables them to access docker images on dockerhub Dockerhub Home Page
- User starts Docker client on their laptop. On a Mac, a Docker Client is started by double clicking on the Docker Icon (which is a whale) in the applications directory.
- User moves to ucvm_docker directory on their Laptop, and creates a subdirectory. This "target" subdirectory will be used for exchanging files between the UCVM Container and the Users computer system.
cd /Users/maechlin/ucvm_docker mkdir /Users/maechlin/ucvm_docker ls /Users/maechlin/ucvm_docker/target
- Start UCVM Docker Image using docker "run" command. The docker run command below define how the "target" directory is shared (mounted) by the container and the users computer, and it specifies the UCVM Docker image to run as "sceccode/ucvm_227_cvms5:0710".
$ docker run --rm -it --mount type=bind,source="$(pwd)"/target,destination=/app/target sceccode/ucvm_227_cvms5:0710
This will download the docker image from Dockerhub. The UCVM docker images are 15 to 30 Gb in size. This means that the first time the user tries to run the Docker image, the image must be downloaded from Dockerhub to their computer. Depending on their network speed, this download process can take 10minutes to 1 hour. However, after the image is downloaded the first time, it will be cached on the users computer, and it will start-up immediately without being downloaded again.
Unable to find image 'sceccode/ucvm_227_cvms5:0710' locally 0710: Pulling from sceccode/ucvm_227_cvms5 72a2451028f1: Already exists 4f4fb700ef54: Pull complete beff868b5feb: Pull complete 89e37b19917a: Pull complete 36b0d9d8658d: Pull complete b77fe9f7c5f1: Pull complete 42b58887d3ab: Pull complete 4a21b6597a6c: Pull complete e9c17f4fa502: Pull complete 228bad3451f1: Pull complete ff6ff1951af4: Pull complete fd425e1f839d: Pull complete 6ee4d64987bc: Pull complete 6c005e4db663: Pull complete 791fc1611728: Pull complete c6c51eece20a: Pull complete ed5815078afe: Pull complete 8799738e2164: Pull complete 2ff7a9b6857e: Pull complete 99e734ad444b: Pull complete 3757f7ddf1eb: Pull complete 984e40380643: Pull complete d653340e1f3c: Pull complete 87545668baf8: Pull complete 9fde9008ffd0: Pull complete c89f4eaf5bff: Pull complete 9cbb7f4ec273: Pull complete Digest: sha256:66478363917921e3811d926d2be99db1c8eda34cddc51084e683ce6c8cec506d Status: Downloaded newer image for sceccode/ucvm_227_cvms5:0710
- When the image download is complete, the terminal window where the user invoked the "docker run...." command will present a Linux command line, like this:
(Python2) [maechlin@0ab6b1fb9ae6 target]$
This indicates that the UCVM docker image is running. The Python2 indicator is shown because the UCVM plotting routines use Python2 packages. The main UCVM executable is a C language executable, and does not require Python.
The UCVM docker image uses the "target" directory (created above) to transfer files from inside the Docker container to the Users laptop. Files that are created, or written, in the "target" directory will be preserved on the users laptop after the Docker image exits. Images can be written to other directories in the Docker container, but they will not be preserved after the user stop running the Docker image.
The following steps, move the test programs from their place in the Docker image, into the "target" directory, run the following commands.
- Confirm that the user is running the Docker image, and their working directory is "/app/target". Run the Print Working Directory (pwd) command on the commnand line, like this:
(Python2) [maechlin@1a1dea59d47e target]$ pwd /app/target
- At the command line prompt at: /app/target, the user can run a ucvm_query test query
(Python2) [maechlin@1a1dea59d47e target]$ ucvm_query -f /app/ucvm/conf/ucvm.conf -m cvms5 < /app/test_latlons.txt Using Geo Depth coordinates as default mode. -118.0000 34.0000 0.000 284.191 580.043 cvms5 1857.303 910.278 2061.182 none 0.000 0.000 0.000 crust 1857.303 910.278 2061.182 -118.0000 34.0000 50.000 284.191 580.043 cvms5 1924.967 949.979 2080.163 none 0.000 0.000 0.000 crust 1924.967 949.979 2080.163 -118.0000 34.0000 100.000 284.191 580.043 cvms5 1992.631 989.680 2098.196 none 0.000 0.000 0.000 crust 1992.631 989.680 2098.196 -118.0000 34.0000 500.000 284.191 580.043 cvms5 2533.943 1307.287 2212.444 none 0.000 0.000 0.000 crust 2533.943 1307.287 2212.444 -118.0000 34.0000 1000.000 284.191 580.043 cvms5 3097.641 1779.642 2312.024 none 0.000 0.000 0.000 crust 3097.641 1779.642 2312.024
This (1) inputs an example input file "test_latlons.txt" to ucvm_query, (2) references a ucvm configuration file in the image located at "/app/ucvm/conf/ucvm.conf", and (3) specifies that the model to be queried is "cvms5".
UCVM_query runs and prints the results to the screen. To save the results, users can redirect the outputs to a file this way:
(Python2) [maechlin@1a1dea59d47e target]$ ucvm_query -f /app/ucvm/conf/ucvm.conf -m cvms5 < /app/test_latlons.txt > /app/target/cvms5_test_latlons.tx
This will output a file to the "target" directory. This file will be accessible on the Users computer even after the Docker image exits.
Information on how to interrept the UCVM_query results are provided on the main UCVM Documentation
- Users can create your own test_latlons.txt in your "target" directory, and this file will preserved after the Docker image exits.
- Files saved to "target" will be saved after container exits. So put any input or outputs in the "target" directory.
- If you edit the /app/ucvm/conf/ucvm.conf file, since that file is in the container file system, file edits will be lost when the container exits.
