UCVM 13.9.0 User Guide
Contents
Overview
Released on September 8th, 2013, UCVM 13.9.0 represents the second major release of the Unified Community Velocity Model (UCVM) framework. UCVM is a collection of software utilities that are designed to make querying velocity models, building meshes, and visualizing velocity models easier to do through a uniform software interface. UCVM has been used extensively to generate meshes and e-trees that are then used for 3D wave propagation simulations within California.
The full feature list is as follows:
- Seamlessly combine two or more models into a composite model for querying
- Optionally include a California statewide geotechnical layer and interpolate it with the crustal velocity models
- Extract a 3D mesh or CVM Etree (octree) of material properties from any combination of models
- Standard California statewide elevation and Vs30 data map is provided
- Miscellaneous tools are provided for creating 2D etree maps, and optimizing etrees
- Numerically smooth discontinuities at the interfaces between different regional models
- Add support for future velocity models with the extendable interface
Currently, we support CVM-S4, CVM-H 11.9.1, CVM-S4.23, CenCal 0.8.0, and the Hadley-Kanamori as part of our automated installation package. Other models, such as SCEC CVM-NCI, Magistrale WFCVM, Graves Cape Mendocino, Lin-Thurber Statewide, and Tape SoCal are supported, however they will require a manual installation. We have also tested and include support for three major high-performance computing resources: NICS Kraken, TACC Stampede, and NCSA Blue Waters. It should work with other HPC machines as well.
The API itself is written entirely in C. We will show how to query UCVM through both C and Fortran in this user guide.
Finally, UCVM requires either Linux or OS X, GCC 4.3+, Python 2.5+, and an active internet connection to download and retrieve the models. For parallel mesh or e-tree extraction, the MPI libraries are also required. If you are installing UCVM on OS X, you must have the OS X Developer Tools (Xcode and Command Line Tools) and you must also have gfortran installed.
Installation Instructions
Easy Method
If you are installing UCVM on Linux or OS X and only need CVM-S4, CVM-H 11.9.1, CVM-S4.23, and/or CenCal, we strongly recommend following the easy installation method. Simply download UCVM 13.9.0 and run the following commands:
tar zxvf ucvm-13.9.0.tar.gz
cd ./UCVM
./ucvm_setup.py
You will then be asked a series of questions:
It looks like you are installing UCVM for the first time.
Where would you like UCVM to be installed?
(Default: /your/home/dir)>
Enter path or blank to use default:
Hit enter to use the default path or type your own. On high-performance computing resources you must change this path to be in the scratch or work directory so that UCVM can be seen by the compute nodes.
You will then be asked which models you'd like to download, such as:
Would you like to download and install CVM-S4?
Enter yes or no:
Enter "yes" (without quotation marks) or "no" if you would like to download this model or not.
After answering a few of these questions, UCVM will then begin the process of downloading and building the models you have requested. When the process is completed, you will be advised on how to test to verify that your installation is working and also any modifications that may be needed to your ~/.bash_profile.
Custom Method
Please see this page on how to install UCVM with models other than CVM-S4, CVM-H, CVM-S4.23, and CenCal.
Command Reference
ucvm_query
This is the command-line tool for querying CVMs. Any set of crustal and GTL velocity models may be selected and queried in order of preference. Points may be queried by (lon,lat,dep) or (lon,lat,elev) and the coordinate conversions for a particular model are handled transparently. A configuration file needs to be passed to ucvm_query. Typically, this would be /path/to/ucvm-13.9.0/conf/ucvm.conf.
Example usage:
./ucvm_query -f ../conf/ucvm.conf -m cvms < ../tests/cvms_input.txt
Using Geo Depth coordinates as default mode.
-118.0000 34.0000 0.000 280.896 390.000 cvms 696.491 213.000 1974.976 none 0.000 0.000 0.000 crust 696.491 213.000 1974.976
ucvm2etree
The command ucvm2etree builds an e-tree from the specifications in a given configuration file, config.
Note that this is the serial version of the command, meaning that it will only run on a single process. As such, building a large e-tree can be very slow. For large e-trees, we strongly recommend using ucvm2etree-extract-MPI, ucvm2etree-sort-MPI, and ucvm2etree-merge-MPI.
Example usage:
ucvm2etree -f ./ucvm2etree_example.conf
Troubleshooting
If you see an error similar to the following while running either the tests or the UCVM programs:
error while loading shared libraries: libsomelib.so: cannot open shared object file: No such file or directory
This indicates that UCVM was linked against one or more shared libraries and the dynamic library loader cannot find the actual .so library at run-time. The solution is to update your LD_LIBRARY_PATH to include the directory containing the library mentioned in the error message. For example, the following command adds a new search directory to LD_LIBRARY_PATH in a csh shell:
$ setenv LD_LIBRARY_PATH /home/USER/opt/somepkg/lib:${LD_LIBRARY_PATH}
By default, the ucvm_setup.py script uses static libraries. UCVM is only compiled dynamically if you pass ucvm_setup.py the "-d" option or if your system does not support static linking.
Proj. 4 Error: major axis or radius = 0 or not given
On systems with home filesystems that are not viewable to compute nodes (such as NICS Kraken), you may encounter errors with Proj.4 when trying to run any component of UCVM on compute nodes. This is due to the fact that Proj.4 actually relies on a file called proj_defs.dat which is located in the ${MAKE_INSTALL_LOCATION}/share/proj directory. So for example, suppose you had configured Proj.4 with ./configure --prefix=/not_viewable_to_compute_nodes/proj-4.7.0, Proj. 4 would then search for proj_defs.dat in /not_viewable_to_compute_nodes/proj-4.7.0/share/proj/proj_defs.dat. This will cause UCVM to throw the error "Proj.4 Error: major axis or radius = 0 or not given" and your job will fail.
The only way it seems to solve this issue is to actually make sure your --prefix directory is actually visible to the compute nodes and do a make install there. Documentation suggests that you can set the PROJ_LIB environment variable, however this seems to not work correctly without modifications to the Proj.4 source code.
API Examples
C
Calling UCVM from C code is relatively trivial. Minimally, you need the UCVM library as well as "ucvm.h".
Fortran
Calling UCVM using Fortran is a relatively trivial procedure. After you have installed UCVM as per this user guide, you must include the UCVM library, the Proj.4 library, the e-tree library, as well as any velocity model libraries that you have compiled into UCVM. For CVM-H, please note that there are actually two libraries required: lvxapi and lgeo. Because the default convention for calling C programs from Fortran automatically appends an underscore to the end of the function name, you must turn that off via a flag called "fno-underscoring". This will make the Fortran compiler try and find foo() instead of foo_().
As an example, suppose we have a Fortran file, example.f, that calls UCVM. We have compiled UCVM with CVM-S and CVM-H. The code to compile example.f would be as follows:
gfortran example.f -o ./example -L/path/to/ucvm-13.9.0/lib -L./path/to/ucvm-13.9.0/model/cvms4/lib -L/path/to/ucvm-13.9.0/model/cvmh1191/lib -L/path/to/ucvm-13.9.0/lib/proj-4/lib -L/path/to/ucvm-13.9.0/lib/euclid3/libsrc -lucvm -lcvms -lvxapi -lgeo -lproj -letree -fno-underscoring
The basic structure of how to call UCVM within Fortran is outlined in the example below.
Example.f
program example
c UCVM Configuration Location
CHARACTER(LEN=80) ucvmconf
c Model Name
CHARACTER(LEN=4) model
c Number of points we're passing to ucvm_query
INTEGER pts
c The UCVM point data structure.
c coord(1) is longitude
c coord(2) is latitutde
c coord(3) is depth
TYPE :: ucvm_point_t
REAL*8 coord(3)
END TYPE ucvm_point_t
c Generic property structure
c Source is where it comes from
c vp is P-wave velocity in m/s
c vs is S-wave velocity in m/s
c rho is density in kg/m^3
TYPE :: ucvm_prop_t
INTEGER source
REAL*8 vp
REAL*8 vs
REAL*8 rho
END TYPE ucvm_prop_t
c Returned data structure
TYPE :: ucvm_data_t
REAL*8 surf
REAL*8 vs30
REAL*8 depth
INTEGER domain
REAL*8 shift_cr
REAL*8 shift_gtl
type(ucvm_prop_t) crust
type(ucvm_prop_t) gtl
type(ucvm_prop_t) cmb
END TYPE ucvm_data_t
c For our example we'll query five points
type(ucvm_point_t) point(5)
c And we'll get back five sets of material properties
type(ucvm_data_t) returnData(5)
c Number of points is 5.
pts = 5
c We'll start at -118, 34 at 0 depth and go down by 1000m
c each step
do 10 i = 1, 5
point(i)%coord(1) = -118
point(i)%coord(2) = 34
point(i)%coord(3) = (i - 1) * 1000
10 continue
c Where is our configuration file?
ucvmconf = "/home/scec-01/davidgil/ucvm.conf" // CHAR(0)
c What model are we querying?
model = "cvms"
c Initialize UCVM
call ucvm_init(ucvmconf)
c Add the model to UCVM
call ucvm_add_model(model)
c Query the model. Note that the number of points is passed
c by value, not reference.
call ucvm_query(%VAL(pts), point, returnData)
print *, model, " results for lon -118, lat 34"
c Print out the results.
do 20 i = 1, 5
print *, "Depth ", (i - 1) * 1000
print *, "Vs ", returnData(i)%crust%vs
print *, "Vp ", returnData(i)%crust%vp
print *, "Rho ", returnData(i)%crust%rho
20 continue
c Close UCVM now that we've queried the points
call ucvm_finalize()
end
GCC Fortran 4.3+ is required for this example to work.
