View source for UCVM API

= Overview =

The Unified California Velocity Model API (UCVM API) is a programming interface that allows the user to directly
query multiple velocity models in a program. The API currently support these models:


Crustal Models:
* [[CVM-S]]
* [[CVM-SI]]
* [[CVM-H]]
* USGS Central California
* Hadley-Kanamori 1D
* [[Lin Thurber CVM]] California Statewide
* Rob Graves Cape Mendocino
* Any Etree formatted to the SCEC Etree convention
* Any user-defined model that can be encapsulated in a C header and source/library file


GTL Models:
* Ely Vs30-derived GTL
* Hadley-Kanamori 1D


Notes:
* MPI-capable, has been shown to scale to 2100 cores on NCCS Jaguar in a mesh generator.
* Allows application programs to tailor which set of velocity models are linked in to minimize memory footprint.
* API is currently a prototype C interface.
* Compatible with grid resources that have data stage-in policies for jobs, such as USC HPCC, and light-weight kernels that support static libraries only, such as NCCS Jaguar and NICS Kraken. 
* Tested on NCCS Jaguar, NICS Kraken, and USC HPCC.


Significant science issues remain to be resolved. Please see the Science Issues section below.


= Concept of Operation =

UCVM combines multiple regional velocity models and two internal UCVM models into one "meta-model" for the purposes of querying Vp, Vs, and density. Individual model setup and query details are abstracted under a uniform interface, and the application sees only the meta-model. This simplifies application code and makes it easier for those programs to support new velocity models in the future.

Velocity models are combined into the meta-model by tiling them on top of one another. When UCVM is initialized, the user selects an ordered list of models to query for data. Query points are then submitted to each velocity model in that list, one model at a time in list order. The first model to return valid velocity data for the point is considered to have fullfilled that data request and subsequent models are not queried. Generally, no smoothing is performed at the interfaces between models (an exception is interpolation between a GTL and crustal model as described below). For each query point, the following data is returned: surface elevation, Vs30, Vp, Vs, and density.

Regional models may include: CVM-H, CVM-H, USGS Bay Area, 1D, etc. Internal models include the UCVM DEM and Vs30 map. Most models, both regional and internal, have a maximum extent, outside of which no data is available. The exception is the generic 1D model as it has infinite extents. Applications must check the returned velocity and density values to ensure they are valid.

The API distinguishes between two types of regional velocity models: GTL models, and crustal models. GTL models are shallow near-surface velocity models called geotechnical layers. Crustal models are deeper velocity models such as tomographic models. When a user selects to query from one or more crustal models only, the API executes the previously described behavior. However, if one or more GTL models are selected, additional processing is performed.

When a GTL model is given in the ordered list of models, the API creates a default interpolation zone along the z-axis over which interpolation between this GTL and the underlying crustal models is performed. It also assigns a default (linear) interpolation function to smooth the velocities of the GTL and underlying crustal models. Both the interpolation zone and interpolation function can be changed by the user. Querying for a point in this operating mode is now slightly different from the previous crustal-only case. As before, all query points are submitted to the crustal models in the ordered list of models (skipping any GTLs). However, the z coordinate of the points may be shifted down to the lower edge of the interpolation zone if the point falls within it. The models are queried with this possibly modified 3D coordinate and the velocities/density values are saved. The same list of query points is then submitted to the GTL models in the ordered list of models (skipping any crustals) and the z coordinate of those points within the interpolation zone may be shifted up to the top edge. The models are queried with this possibly modified 3D coordinate and the velocity/density values are saved. The list of query points is then traversed one final time. Those points that fall above the interpolation zone will have their velocities/densities set to those of the GTL as processed by the interpolation function assigned to that GTL. Those points that fall within the interpolation zone and have valid GTL/crustal values will have their GTL/crustal values smoothed according to the assigned interpolation function. Points that fall below the interpolation ozne and have valid crustal values will have their velocities/densities set to the crustal values. Note that points with invalid/incompatible velocities in either the GTL or crustal dataset cannot be smoothed and the interpolation results will be marked as invalid.


=== Querying Models Via Native Interface versus Querying UCVM ===

For the most part, querying any model through its native interface will yield the same material properties as UCVM. There are a few exceptions, which are noted here:

* When querying by elevation with CVM-H and any GTL, points that fall above the UCVM free surface and within the CVM-H domain are normalized to be relative to the CVM-H free surface. This is done to eliminate small discrepancies between the UCVM DEM and the CVM-H DEM.
* The same correction is performed when querying by elevation with CenCalVM and any GTL.
* When querying CenCalVM by depth, UCVM does not directly pass that point to the cencalvm interface since the definition of depth differs between UCVM and cencalvm. Instead, UCVM derives the elevation of the free surface (ground/air, ground/water) at the point of interest by drilling down through the model at that point and finding the highest octant with valid material properties. UCVM then converts the query point depth to elevation and queries cencalvm by elevation.


= Interface =

== UCVM Interface ==

UCVM provides an interface for querying Vp, Vs, and rho from any user-defined model. The main UCVM interface is as follows:
<pre>
#ifndef UCVM_H
#define UCVM_H

#include <stdarg.h>
#include "ucvm_dtypes.h"

/* Initializer */
int ucvm_init(const char *config);

/* Finalizer */
int ucvm_finalize();

/* Enable specific model(s), by string list, by label, or 
   by ucvm_model_t */
int ucvm_add_model_list(const char *list);
int ucvm_add_model(const char *label);
int ucvm_add_user_model(ucvm_model_t *m, ucvm_modelconf_t *conf);

/* Associate specific interp func with GTL model, by label 
   or by ucvm_ifunc_t */
int ucvm_assoc_ifunc(const char *mlabel, const char *ilabel);
int ucvm_assoc_user_ifunc(const char *mlabel, ucvm_ifunc_t *ifunc);

/* Get label for a model */
int ucvm_model_label(int m, char *label, int len);

/* Get label for an interpolation function */
int ucvm_ifunc_label(int f, char *label, int len);

/* Get version for a model */
int ucvm_model_version(int m, char *ver, int len);

/* Set parameters (see ucvm_dtypes.h for valid param flags) */
int ucvm_setparam(ucvm_param_t param, ...);

/* Query underlying models */
int ucvm_query(int n, ucvm_point_t *pnt, ucvm_data_t *data);

#endif
</pre>

The general order of operations for using this interface is:
* Initialization (<code>ucvm_init()</code>)
* Add models in order of preference using <code>ucvm_add_model()</code>. These may be either crustal or GTL models. See below for specific details.
* If GTLs have been added:
** Associate an interpolation function with each using <code>ucvm_assoc_ifunc()</code>. Otherwise, linear interpolation will be used.
** Set an interpolation depth range using <code>ucvm_setparam(UCVM_PARAM_IFUNC_ZRANGE, ...)</code>. Otherwise the interpolation range is set to 0,0.
* Query points of interest with <code>ucvm_query()</code>
* Finalization (<code>ucvm_finalize()</code>)


Notes on enabling models:
* Models are referenced either by a pre-defined string id or by a populated <code>ucvm_model_t</code> structure.
* Multiple models may be registered, and they are queried in order of registration.
* A helper function <code>ucvm_add_model_list()</code> is provided to quickly add multiple models. The string format is "gtl_model<:gtl_interp>,crustal_model,..." where "<:gtl_interp>" is an optional GTL interpolation function specification. For example, the string "elygtl:ely,cvmh" specifies the Ely GTL and CVM-H, adn the use of the Ely interpolation function to smooth between the GTL and crustal models.
* Pre-defined models include: CVM-S, CVM-H, CenCal, Lin-Thurber, Rob Graves Cape Mendocino, 1D, Ely GTL, any SCEC Etree or patch listed in the UCVM configuration file. These models are enabled by calling <code>ucvm_add_model()</code> with their name string identifier as listed in either ucvm_dtypes.h (pre-defined) or in the UCVM configuration file (user-defined SCEC Etree, UCVM patch).
* Most predefined model interfaces only support one model instance at a time. However, multiple Etrees and patches may be enabled. Etrees and patches are defined in the UCVM configuration file with the following commands:
<pre>
# Etree definition and path to etree
modid_interface=etree
modid_modelpath=/home/...

# Patch definition and path to configuration file
modid_interface=patch
modid_modelpath=/home/...

where:
modid : replaced with desired string identifier for the etree/patch model
</pre>
* The programmer may also define their own models and integrate them into UCVM. A user model interface is defined by creating the init(), finalize(), getversion(), getlabel(), setparam(), and query() functions for the model interface, and populating the <code>ucvm_model_t</code> structure with these function pointers and some additional record keeping information. Configuration information for a specific model instance of that interface is placed in a <code>ucvm_modelconf_t</code> structure. Once a model is fully described with a <code>ucvm_model_t</code> interface and a <code>ucvm_modelconf_t</code> configuration, it can be registered for use with the <code>ucvm_add_user_model()</code> function and queried with the <code>ucvm_query()</code> function. 


=== Data Type Descriptions ===

The full list of defined data types are listed in /include/ucvm_dtypes.h. The following is a general description of the useful application definitions:

Points are specified with a <code>ucvm_point_t</code> structure:
<pre>
/* 3D point */
typedef struct ucvm_point_t 
{
  double coord[3];
} ucvm_point_t;
</pre>


Return data is specified with a <code>ucvm_data_t</code> structure:
<pre>
typedef struct ucvm_data_t 
{
  double surf; /* Elevation of free surface in meters */
  double vs30; /* Vs30 value in m/s */
  ucvm_domain_t domain;  /* Domain where the point lies: GTL model, interpolation zone, crustal model, none. */
  double shift_cr; /* Depth shift applied to point when querying crustal models. Only used when a GTL is enabled. */
  double shift_gtl; /* Depth shift applied to point when querying GTL models. Only used when a GTL is enabled. */
  ucvm_prop_t crust; /* Material properties from crustal model */
  ucvm_prop_t gtl; /* Material properties from GTL model */
  ucvm_prop_t cmb; /* Combined GTL/crustal material properties. This is the final property set that applications should reference. */
} ucvm_data_t;

where ucvm_prop_t is:

/* Material properties */
typedef struct ucvm_prop_t 
{
  int source; /* Model idenfitifer */
  double vp; /* Velocity in m/s */
  double vs; /* Velocity in m/s */
  double rho; /* Density in g/m^3 */
} ucvm_prop_t;
</pre>


Model interfaces (both crustal and GTL) are defined with a <code>ucvm_model_t</code> structure:
<pre>
/* Model */
typedef struct ucvm_model_t 
{
  ucvm_mtype_t mtype;
  int (*init)(int id, ucvm_region_t *r, const char *config);
  int (*finalize)();
  int (*getversion)(int id, char *ver, int len);
  int (*getlabel)(int id, char *ver, int len);
  int (*setparam)(int id, int param, ...);
  int (*query)(int id, ucvm_ctype_t cmode,
               int n, ucvm_point_t *pnt, 
               ucvm_data_t *data);
} ucvm_model_t;
</pre>


=== Model-specific Configuration ===

Underlying models may be configured in one of two ways: with a key/value string in the UCVM configuration file, or by passing configuration parameters with the <code>setparam()</code>function.

Currently, the UCVM configuration file allows the user to specify the paths to the main and secondary model files for each model. The key format is:

<pre>
<model_name>_modelpath    : Main model path
<model_name>_extmodelpath : Optional secondary or extended model path (currently only used by CenCalVM)

where:
model_name: is the string label of the model (eg: "cvms")
</pre>


The following model flags may be set using the <code>setparam()</code> function and the UCVM_PARAM_MODEL_CONF parameter:

<pre>
 key: "USE_1D_BKG"     valid values: "True"/"False"    (CVM-H only)
</pre>

For example, execute the following to enable the 1D background model for CVM-H:

<pre>
ucvm_setparam(UCVM_PARAM_MODEL_CONF, UCVM_MODEL_CVMH, "USE_1D_BKG", "True");
</pre>


== UCVM Grid Interface ==

Provides an interface for generating 2D regular grids in any USGS map projection.

<pre>
/* Generate grid from projection and dimensions */
int ucvm_grid_gen(ucvm_proj_t *iproj, ucvm_trans_t *trans,
                  ucvm_proj_t *oproj,
                  ucvm_dim_t *dims, double spacing, 
                  ucvm_point_t *pnts);

/* Generate grid from projection and dimensions */
int ucvm_grid_gen_file(ucvm_proj_t *iproj, ucvm_trans_t *trans,
                       ucvm_proj_t *oproj,
                       ucvm_dim_t *dims, double spacing, 
                       const char *filename);

/* Convert point list from one projection to another */
int ucvm_grid_convert(ucvm_proj_t *iproj, 
                      ucvm_proj_t *oproj, 
                      size_t n, ucvm_point_t *pnts);

/* Convert point list from one projection to another */
int ucvm_grid_convert_file(ucvm_proj_t *iproj, 
                           ucvm_proj_t *oproj, 
                           size_t n, const char *filename);

</pre>


== SCEC Etree Convention ==

=== Etree Model Format ===
* Variable resolution based off of Vs, max supported frequency, and points per wavelength. The resolution at any particular region will be dependent upon the local Vs value (relation shown below). However, a minimum Vs at Etree creation will clamp the resolution to a maximum value regardless of how low the local Vs is found to be.
<pre>
rez = vs / (ppwl * freq)

where:
vs: Vs at point of interest (m/s)
ppwl: points per wavelength
freq: max supported frequency (Hz)
</pre>
* Model data is referenced relative to free surface. Free surface is defined at air/ground, water/ground interface. UCVM topography and bathymetry can be used to determine if a point is in the air/water and default properties returned for those domains.
* Stored properties are Vp, Vs, and density.


=== Etree Metadata Description ===

The Etree metadata tag describes the payload of the octants, the extents of the coverage region, and the map projection. It will have the following format, with fields delimited by vertical bars:

<pre>
metatype_version|title|author|date|vs_min|max_freq|ppwl|format|proj.4_string|geo_origin|rot_angle|xyz_dims|xyz_ticks

where:
metatype_version: "SCEC_CVM_V1" string of max length 64 chars
title: free-format title string of max length 64 chars
author: free-format author string of max length 64 chars
date: YY/MM/DD date string
vs_min: vs minimum used to determine max resolution
max_freq: maximum supported frequency in Hz
ppwl: Points per wavelength
format: data format specification of octants. Uses string format: "name,data_type,size,units". eg: "vp,float,4,m/s;vs,float,4,m/s;rho,float,4,kg/m^3"
proj.4_string: Proj.4 projection string, eg: "+proj=aeqd +lat_0=36.0 +lon_0=-120.0 +x_0=0.0 +y_0=0.0"
geo_origin: Origin point of CVM region in geo coordinates, eg: "-129.25,41.0"
rot_angle: Rotation angle of bounding box in degrees, eg "55.0"
xyz_dims: Dimensions of bounding box in km, eg "1800,800,100"
xyz_ticks: Number of ticks along each dimension
</pre>


= Example Usage of API =

== Configuring UCVM ==

The following is an example ucvm.conf file showing model paths to all predefined models as well as several user-defined etrees and patches.

<pre>
# UCVM config file

# UCVM model path
ucvm_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/ucvm

# Coverage regions (currently disabled)
#cvms_region=-122.0,30.0,-112.0,35.5
#cvmh_region=-122.0,30.0,-112.0,35.5
#cencal_region=-126.0,35.5,-119.0,40.0

# Predefined model paths
cvms_modelpath=/home/scec-00/USER/opt/aftershock/cvms/src
cvmh_modelpath=/home/scec-00/USER/opt/aftershock/cvmh/bin
cencal_modelpath=/home/scec-00/USER/opt/etree/USGSBayAreaVM-08.3.0.etree
cencal_extmodelpath=/home/scec-00/USER/opt/etree/USGSBayAreaVMExt-08.3.0.etree
lin-thurber_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/lin-thurber
cmrg_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/cmrg
cmuetree_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/cmuetree

# User-defined models
cybershake_interface=etree
cybershake_modelpath=/home/scec-00/USER/tmp/cybershake_1hz_250ms.e
cencal_p1_interface=patch
cencal_p1_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p1.conf
cencal_p2_interface=patch
cencal_p2_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p2.conf
cencal_p3_interface=patch
cencal_p3_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p3.conf
cencal_p4_interface=patch
cencal_p4_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p4.conf
cvmh_p1_interface=patch
cvmh_p1_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1.conf
cvmh_p2_interface=patch
cvmh_p2_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p2.conf
cvmh_p3_interface=patch
cvmh_p3_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p3.conf
cvmh_p4_interface=patch
cvmh_p4_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p4.conf

# Model flags
cvmh_param=USE_1D_BKG,False
</pre>

== Basic Example with Crustal Model Only ==

The following code snippet illustrates how the API is used with CVM-S. No GTL is included.

<pre>
  int nn = 1;
  ucvm_point_t pnt1;
  ucvm_data_t data1;
  
  printf("Init\n");
  if (ucvm_init("./ucvm.conf") != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Init failed\n");
    return(1);
  }
  
  printf("Query Mode\n");
  if (ucvm_query_mode(UCVM_COORD_GEO_DEPTH) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Set query mode failed\n");
    return(1);
  }
  
  printf("Add Model CVM-S\n");
  if (ucvm_add_model(UCVM_MODEL_CVMS) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Retrieval of CVM-S failed\n");
    return(1);
  }

  printf("Create point\n");
  pnt1.coord[0] = -119.0;
  pnt1.coord[1] = 31.0;
  pnt1.coord[2] = 2000.0;

  printf("Query Model\n");
  if (ucvm_query(nn, &pnt1, &data1) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Query CVM failed\n");
    return(1);
  }
 
  printf("Results\n");
  printf("source=%d, vp=%lf, vs=%lf, rho=%lf\n",
         data1.cmb.source, data1.cmb.vp, data1.cmb.vs, data1.cmb.rho);
</pre>


== Example with Multiple Models and GTL ==

The following code snippet illustrates how the API is used with the CVM-H crustal model and the Ely GTL model. Smoothing between the Ely GTL and CVM-H is performed with the predefined Ely interpolation function over a depth range of 0 - 350.0 m.


<pre>
  int nn = 1;
  ucvm_point_t pnt1;
  ucvm_data_t data1;
  
  printf("Init\n");
  if (ucvm_init("./ucvm.conf") != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Init failed\n");
    return(1);
  }
  
  printf("Query Mode\n");
  if (ucvm_query_mode(UCVM_COORD_GEO_DEPTH) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Set query mode failed\n");
    return(1);
  }
  
  printf("Add Crustal Model CVM-S\n");
  if (ucvm_add_model(UCVM_MODEL_CVMS) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Retrieval of CVM-S failed\n");
    return(1);
  }

  printf("Add GTL Model Ely\n");
  if (ucvm_add_model(UCVM_MODEL_ELY) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Retrieval of Ely failed\n");
    return(1);
  }

  /* Change GTL interpolation function from default (linear) to Ely interpolation */
  if (ucvm_assoc_interp(UCVM_MODEL_ELY, 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");
  pnt1.coord[0] = -119.0;
  pnt1.coord[1] = 31.0;
  pnt1.coord[2] = 2000.0;

  printf("Query Model\n");
  if (ucvm_query(nn, &pnt1, &data1) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Query UCVM failed\n");
    return(1);
  }
 
  printf("Results\n");
  printf("source=%d, vp=%lf, vs=%lf, rho=%lf\n",
         data1.cmb.source, data1.cmb.vp, data1.cmb.vs, data1.cmb.rho);
</pre>


= Source Code =

The UCVM source and cvm2mesh mesh generator may be checked out from SVN with these commands:

 UCVM: svn co https://source.usc.edu/svn/ucvm/trunk

 cvm2mesh: svn co https://source.usc.edu/svn/cvm2mesh/trunk


= Implementation Details =

* Models are queried in the order they are enabled in the interface. The material properties for a particular (lon,lat) point are from the first model in the ordered list to return valid values.
* Only lon,lat,dep and lon,lat,elev coordinates are currently supported
* No smoothing between crustal models is performed. They are simply tiled.
* Projections are performed with the Proj.4 package
* Depth is defined as the offset from the free surface (ground/air interface, ground/water interface) in meters, positive down. Negative depths are not supported. Elevation is defined as meters offset from MSL, positive up.


= Future Improvements =

* Addition of other regional models
* Addition of additional GTLs
* Bindings for Fortran, C++


= Science Issues =


== Overlapping Models ==

Imagine the scenario outlined below, where the user wishes to combine two models, a SoCal model and a NoCal model:

[[File:State-wide-Overlapping-Models.png]]

The models may overlap in ways which makes merging them difficult.
*For a point that falls within the Kern County region, simply interpolating between the two models may not work if NoCal reports water properties (vp, rho, no vs) and the SoCal model reports soil/rock. No interpolation is possible in this case. To deal with this situation, there are several options:
**Coordinate edits to each model to bring their material properties into better agreement within the overlap region.
**Crop one or both models to remove the overlap, and smooth them into the California background model.
**Create a new “Transition Model” that covers Kern County and surrounding area that interpolates/averages the the two other models in a scientifically acceptable way. Register this new model in the API, and give it priority over the other two models. In effect, tile the Transition Model, the NoCal Model, and the SoCal Model.
**Allow the models to overlap with discontinuities. This is currently how the UCVM API handles overlap.


== Projection Distortion ==

Several issues with map projections come into play:
* Distortion in projections on large scales. Any state-wide model that supports querying by UTM or other projection coordinates must account for and minimize distortion.
* Inconsistent handling of projections within models. Each model generally has its own internal projection. For example, CVM-H uses a UTM projection. The projection codes used across all models should be standardized on the Proj.4 projection package to avoid small differences in the handling of coordinates. This may require resampling of the data inside the models.


== Standardized Handling of Elevation ==

All models that support query by elevation should use a standard DEM derived from the same source.


== Standardized Handling of Depth ==

Depth can be defined in a number of ways, with a reference point that is the ground/water interface or water/air interface or MSL, and positive down versus positive up. In fact, different regional models do define it differently. CVM-S/CVM-H defines depth as distance from ground/air interface, positive down, negative depths not supported. The USGS Bay Are model (cencalvm) defines depth as disance from the ground/air and water/air interface, positive up. The LinThurber model defines depth as offset from MSL, positive up. UCVM currently defines depth in the CVM-S convention and enforces this definition on the models by modifying how they are queried if necessary.


== GTL ==

If a state-wide GTL is developed, the GTL within each underlying model must be stripped away.