Home

UCVM Docker Overview

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.

Motivation for UCVM Docker Images

Geoscientists interested in crustal seismic velocity information may use SCEC UCVM software as a standard method for querying the models. Here we prototype 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.

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.

Ways to Access UCVM Velocity Models

Users have serveral options for accessing the UCVM software:

1. SCEC Community Model Viewer (preliminary version)

• No UCVM software installation required.

2. 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.

3. 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.

Considerations before using UCVM Docker Images

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.

Required Computer Capabilities for using UCVM Images

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.

Overview of Running an UCVM Docker Image

• 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:
• User starts the Docker client on their local computer

$ mkdir target

• User runs the UCVM Docker image for "cvms5". This abbreviation maps to 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.

Example UCVM Docker Image Use Case

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
• mkdir /Users/maechlin/ucvm_docker
• cd /Users/maechlin/ucvm_docker
• User creates "target" directory for exchanging files with the UCVM Container
• cd /Users/maechlin/ucvm_docker
• mkdir target
• ls /Users/maechlin/ucvm_docker/target
• Start UCVM Docker Image using docker "run" command

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 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

(Python2) [maechlin@1a1dea59d47e target]$ cp ../make_mesh.py .
(Python2) [maechlin@1a1dea59d47e target]$ ./make_mesh.py
Creating grd.out file.
/app/ucvm/utilities/makegrid.sh
Generating grid

This will run a script that creates a 300K input data file called "grd.out" and writes it to the "target" directory. Then the make_mesh.py script uses that file to query each SCEC velocity models. Only queries for the "selected" CVM (in this case "cvms5") will succeed in this script. However the script provides a good example of how the UCVM Images can be used to extract properties for a moderate number of points.

Contact

[email protected]