UCVM 13.9.0 Developer Guide
Contents
Overview
This guide is intended for users looking to modify the UCVM source code, register new models with UCVM, or integrate UCVM into their own projects. Most common functionality, including mesh generation and getting material properties from models, is described in the main user guide.
Released on September 8th, 2013, UCVM 13.9.0 represents the second major release of the Unified Community Velocity Model (UCVM) framework. While at its core, UCVM is a collection of software utilities that are designed to make interacting with velocity models easier, it also includes a powerful API for interacting with or registering new velocity models. UCVM's API makes it very easy to integrate into software projects.
Register a New Velocity Model
UCVM can be extended to query any velocity model provided that certain conditions are met. Every new velocity model must have at least:
Unless the model is packaged in e-tree format, implementing it will require code modifications to the core UCVM library located in ./src/ucvm and recompilation. The general steps are:
- Define new model label UCVM_MODEL_MODELNAME in ucvm_dtypes.h
- Create ucvm_model_modelname.h/.c containing the glue code that links the UCVM query interface to the native model interface
- Modify ./src/ucvm/ucvm.c:
- Add ucvm_model_modelname.h include at top
- Add model lookup to ucvm_add_model() function
- Add model to ucvm_get_resources() function
- Modify ./src/ucvm/Makefile.am:
- Add ucvm_model_modelname.o to list of libucvm.a dependencies
- Modify ./configure.ac:
- Define "enable-modelname", "with-modelname-lib-path", and "with-modelname-incl-path" configure options
- Add library and header checks for your new model
- Modify installer to customize path to your new model in ucvm.conf:
- Add your new model to ./conf/Makefile.am
- Add config entry for your new model to ./conf/ucvm_template.conf
- Regenerate the Makefiles with ./scripts/autoconf/reconf.sh
- Reconfigure and recompile UCVM, making sure to pass your new model flags to the configure utility
Query a Velocity Model in Your Code
C
Calling UCVM from C code is relatively trivial. Minimally, you need the UCVM library as well as "ucvm.h".
Using UCVM involves three fundamental steps: 1) Initializing UCVM through the ucvm_init function, 2) adding appropriate models through the ucvm_add_model function, and 3) retrieving material properties through the ucvm_query function. These functions are shown in the example below.
Example.c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <getopt.h>
#include <sys/time.h>
#include "ucvm.h"
int main(int argc, char **argv)
{
int nn = 1;
ucvm_point_t pnts;
ucvm_data_t data;
char cmb_label[UCVM_MAX_LABEL_LEN];
printf("Init\n");
if (ucvm_init("../conf/test/ucvm.conf") != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Init failed\n");
return(1);
}
printf("Query Mode\n");
if (ucvm_setparam(UCVM_PARAM_QUERY_MODE,
UCVM_COORD_GEO_DEPTH) != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Failed to set z mode\n");
return(1);
}
printf("Add Crustal Model 1D\n");
if (ucvm_add_model(UCVM_MODEL_1D) != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Retrieval of 1D failed\n");
return(1);
}
printf("Add GTL Model Ely\n");
if (ucvm_add_model(UCVM_MODEL_ELYGTL) != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Retrieval of Ely GTL failed\n");
return(1);
}
/* Change GTL interpolation function from default (linear)
to Ely interpolation */
if (ucvm_assoc_ifunc(UCVM_MODEL_ELYGTL,
UCVM_IFUNC_ELY) != UCVM_CODE_SUCCESS) {
fprintf(stderr,
"Failed to associate interpolation function with Ely GTL\n");
return(1);
}
/* Change interpolation z range from 0,0 to 0,350 */
if (ucvm_setparam(UCVM_PARAM_IFUNC_ZRANGE, 0.0,
350.0) != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Failed to set interpolation range\n");
return(1);
}
printf("Create point\n");
pnts.coord[0] = -118.0;
pnts.coord[1] = 34.0;
pnts.coord[2] = 2000.0;
printf("Query Model\n");
if (ucvm_query(nn, &pnts, &data) != UCVM_CODE_SUCCESS) {
fprintf(stderr, "Query UCVM failed\n");
return(1);
}
/* Get cmb data label */
ucvm_ifunc_label(data.cmb.source,
cmb_label, UCVM_MAX_LABEL_LEN);
printf("Results:\n");
printf("\tsource=%s, vp=%lf, vs=%lf, rho=%lf\n",
cmb_label, data.cmb.vp, data.cmb.vs, data.cmb.rho);
return(0);
}
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.
