Installation

Running an UCVM Docker Image

Open a terminal window on your local computer and go to a directory where you plan to run UCVM.
Create a "target" directory where files will be accessible even after the container exits. This "target" subdirectory will be used for exchanging files between the UCVM container and the your local system.

$ mkdir target

Search for accessible UCVM Docker images on the Dockerhub and select the image that includes the velocity model you are interested in.

$ docker search sceccode/ucvm

Download the UCVM Docker image from the Dockerhub and start a Docker container using the docker run command below.

$ 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 if the image is not found locally. The UCVM docker images are 15 to 30 Gb in size. The first time the user tries to run the Docker image, the image will be downloaded from Dockerhub to their computer. Depending on their network speed, this download process can take 10 minutes 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
(Python2) [maechlin@26c9bd8f3aa7 target]$

When the image download is complete, the terminal window will show a Linux bash shell command line prompt (/app/target in the running container) where users can run UCVM.

(Python2) [maechlin@b3193932d900 target]$

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.

NOTE: Because there is a Docker bug for Apple M1 chipset, you may see the warning below.

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
(Python2) [maechlin@26c9bd8f3aa7 target]$

This does not affect the running of UCVM, but if you like, you may rerun 'docker run' command with platform hint.

(Python2) [maechlin@26c9bd8f3aa7 target]$ exit
exit
$ docker run --platform linux/amd64 --rm -it --mount type=bind,source="$(pwd)"/target,destination=/app/target  sceccode/ucvm_227_cvms5:0710

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 container exits. Files can write into other directories in the Docker container, but they will not be preserved after the user stop running the Docker container.

(Python2) [maechlin@b3193932d900 target]$ pwd
/app/target

Check UCVM installation

Verify which velocity models are installed in the running Docker container.

$ ucvm_query -H

returns

Usage: ucvm_query [-m models<:ifunc>] [-p user_map] [-c coordtype] [-f config] [-z zmin,zmax] [-b] < file.in

Flags:
	-h This help message.
	-H Detail help message.
	-m Comma delimited list of crustal/GTL models to query in order
	   of preference. GTL models may optionally be suffixed with ':ifunc'
	   to specify interpolation function.
	-c Z coordinate mode: geo-depth (gd, default), geo-elev (ge).
	-f Configuration file. Default is ./ucvm.conf.
	-p User-defined map to use for elevation and vs30 data.
	-v Display model version information only.
	-z Optional depth range for gtl/crust interpolation.

	-b Optional output in json format

	-l Optional input lon,lat,Z(depth/elevation)

Input format is:
	lon lat Z

Output format is:
	lon lat Z surf vs30 crustal cr_vp cr_vs cr_rho gtl gtl_vp gtl_vs gtl_rho cmb_algo cmb_vp cmb_vs cmb_rho

Notes:
	- If running interactively, type Cntl-D to end input coord list.

Version: 22.7.0

Installed Resources:
          1d : crustal model
       bbp1d : crustal model
    cmuetree : crustal model
       1dgtl : gtl
      elygtl : gtl
       cvms5 : crustal model
         ely : ifunc
        ucvm : map
        yong : map
 model_etree : model i/f
 model_patch : model i/f
   map_etree : map i/f

UCVM is installed at,

(Python2) [maechlin@b3193932d900 target]$ echo $UCVM_INSTALL_PATH
/app/ucvm

Test UCVM installation

Run an ucvm_query with a sample input file, "test_latlons.txt", from Docker image, reference ucvm_configuraiton file at "/app/ucvm/conf/ucvm.conf", and the target model is "cvms5".

(Python2) [maechlin@1a1dea59d47e target]$ ucvm_query -f /app/ucvm/conf/ucvm.conf -m cvms5 < /app/test_latlons.txt

returns

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

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

This will output a file to the "target" directory. This file will be accessible on the local computer even after the Docker image exits.

Information on how to interpret the UCVM_query results are provided on the main UCVM Documentation

Additional Users notes:

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.