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:

• CVM-S
• CVM-H
• USGS Central California
• Hadley-Kanamori 1D

API

Data Types and Definitions

/* Maximum number of supported models */
#define UCVM_MAX_MODELS 10

/* Maximum projection description length */
#define UCVM_MAX_PROJ_LEN 256

/* Maximum model label length */
#define UCVM_MAX_LABEL_LEN 64

/* Maximum model version length */
#define UCVM_MAX_VERSION_LEN 64

/* Maximum path length */
#define UCVM_MAX_PATH_LEN 256

/* NO CVM flag */
#define UCVM_MODEL_NONE -1

/* Supported error codes */
typedef enum { UCVM_CODE_SUCCESS = 0, 
               UCVM_CODE_ERROR,
               UCVM_CODE_DATAGAP,
               UCVM_CODE_NODATA} ucvm_code_t;

/* Supported coordinate query modes */
typedef enum { UCVM_COORD_GEO_DEPTH = 0, 
               UCVM_COORD_UTM_DEPTH,
               UCVM_COORD_GEO_ELEV,
               UCVM_COORD_UTM_ELEV } ucvm_ctype_t;

/* Supported grid types */
typedef enum { UCVM_GRID_CELL_CENTER = 0, 
               UCVM_GRID_CELL_VERTEX} ucvm_gtype_t;

/* 3D point */
typedef struct ucvm_point_t 
{
  double coord[3];
} ucvm_point_t;

/* 3D dims */
typedef struct ucvm_dim_t 
{
  int dim[3];
} ucvm_dim_t;

/* Material properties */
typedef struct ucvm_prop_t 
{
  int model;
  double vp;
  double vs;
  double rho;
} ucvm_prop_t;

/* Region box */
typedef struct ucvm_region_t 
{
  ucvm_ctype_t cmode;
  double p1[3];
  double p2[3];
} ucvm_region_t;

/* Projection */
typedef struct ucvm_proj_t 
{
  char proj[UCVM_MAX_PROJ_LEN];
} ucvm_proj_t;

/* Projection transformation */
typedef struct ucvm_trans_t 
{
  double origin[3];
  double rotate;
  double translate[3];
  ucvm_gtype_t gtype;
} ucvm_trans_t;

/* Model */
typedef struct ucvm_model_t 
{
  char label[UCVM_MAX_LABEL_LEN];
  ucvm_region_t region;
  char config[UCVM_MAX_PATH_LEN];
  int (*init)(int id, ucvm_region_t *r, const char *config);
  int (*finalize)();
  const char* (*version)();
  int (*query)(ucvm_ctype_t cmode,
               int n, ucvm_point_t *pnt, 
               ucvm_prop_t *prop);
} ucvm_model_t;

UCVM Interface

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

/* Finalizer */
int ucvm_finalize();

/* Set query mode */
int ucvm_query_mode(ucvm_ctype_t c);

/* Enable specific model, return new model id */
int ucvm_add_model(ucvm_model_t *m, int *id);

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

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

/* Get model id from a label */
int ucvm_model_id(const char *label, int *id);

/* Query underlying models */
int ucvm_query(int n, ucvm_point_t *pnt, ucvm_prop_t *prop);

UCVM Grid Interface

/* 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);

Example Usage of API

  int i;
  int nn = NUM_POINTS;
  ucvm_point_t *pnt1;
  ucvm_prop_t *prop1;
  
  int num_models;
  ucvm_model_t models[UCVM_MAX_MODELS];
  int model_ids[UCVM_MAX_MODELS];

  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("Get Model\n");
  if (ucvm_cvms_get_model(&(models[0])) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Retrieval of CVM-S failed\n");
    return(1);
  }

  if (ucvm_add_model(&(models[0]), &(model_ids[0])) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Enable CVM-S failed\n");
    return(1);
  }

  printf("Create points\n");
  for (i = 0; i < NUM_POINTS; i++) {
    pnt1[i].coord[0] = -119.0;
    pnt1[i].coord[1] = 31.0;
    pnt1[i].coord[2] = 2000.0;
  }

  printf("Query Models\n");
  if (ucvm_query(nn, pnt1, prop1) != UCVM_CODE_SUCCESS) {
    fprintf(stderr, "Query CVM failed\n");
    return(1);
  }
 
  printf("Results\n");
  for (i = 0; i < NUM_POINTS; i++) {
    printf("%d: model=%d, vp=%lf, vs=%lf, rho=%lf\n", i, 
           prop1[i].model, prop1[i].vp, prop1[i].vs, prop1[i].rho);
  }

 

CVM API Implementation Details

• Contains unified high resolution (30m) DEM for the State of California and surrounding region. Necessary to support query by elevation for CVM-4 and the Vs30 derived GTL.
• Has low-rez (1km) default background model that supports query by elevation, and knowledge of water/soil/air. Soil regions use Hadley-Kanamori 1D. Water regions use constant water vp and density values, and vs is undefined. In air regions, all values are undefined.
• Models and GTLs are tiled, and order of precedence is determined by the order they are enabled. No interpolation or smoothing is performed on points that fall within multiple models/GTLs; the data from the most preferred model is returned.
• The API assumes all supported models blend into the California background model at their extents.
• The existing CVM-H topography may need to be resampled from the California DEM used in the API

 

Issues

Overlapping Models

Models may overlap in ways which makes merging them difficult. Imagine the scenario outlined on the right in the diagram below.

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.