Difference between revisions of "UCVM API"

From SCECpedia
Jump to navigationJump to search
Line 120: Line 120:
 
== UCVM Interface ==
 
== UCVM Interface ==
  
UCVM provides an interface for querying Vp, Vs, and rho from any user-defined model. Models are described by the <code>ucvm_model_t</code> structure. Pre-defined model constructors for CVM-S, CVM-H, CenCal, and 1D are provided to allow the programmer to easily use these velocity models. Once a model is fully described in a <code>ucvm_model_t</code>, it can be registered for use with the <code>ucvm_add_model()</code> function and queried with the <code>ucvm_query()</code> function. Multiple models may be registered, and they are queried in order of registration. Here is the complete interface from the header file (/include/ucvm.h):
+
UCVM provides an interface for querying Vp, Vs, and rho from any user-defined model. Models are described by the <code>ucvm_model_t</code> structure. Pre-defined models are defined for CVM-S, CVM-H, CenCal, and 1D to allow the programmer to easily use these velocity models. These models may be enabled by calling <code>ucvm_add_model()</code> with their string identifier.
  
 
<pre>
 
<pre>
 +
/* Predefined models */
 +
#define UCVM_MODEL_CVMH "cvmh"
 +
#define UCVM_MODEL_CVMS "cvms"
 +
#define UCVM_MODEL_CENCAL "cencalvm"
 +
#define UCVM_MODEL_1D "1d"
 +
 
/* Initializer */
 
/* Initializer */
 
int ucvm_init(const char *config);
 
int ucvm_init(const char *config);
Line 132: Line 138:
 
int ucvm_query_mode(ucvm_ctype_t c);
 
int ucvm_query_mode(ucvm_ctype_t c);
  
/* Enable specific model, return new model id */
+
/* Enable specific model, by label or by ucvm_model_t */
int ucvm_add_model(ucvm_model_t *m, int *id);
+
int ucvm_add_model(const char *label);
 +
int ucvm_add_user_model(ucvm_model_t *m);
  
 
/* Get label for a model */
 
/* Get label for a model */
Line 140: Line 147:
 
/* Get version for a model */
 
/* Get version for a model */
 
int ucvm_model_version(int m, char *ver, int len);
 
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 */
 
/* Query underlying models */
Line 148: Line 152:
 
</pre>
 
</pre>
  
 +
The programmer may also define their own models and integrate them into UCVM. A user model is defined by creating the init(), finalize(), version(), and query() functions for the model, and populating the <code>ucvm_model_t</code> structure with these function pointers and some additional record keeping information. Once a model is fully described in a <code>ucvm_model_t</code>, it can be registered for use with the <code>ucvm_add_user_model()</code> function and queried with the <code>ucvm_query()</code> function.
  
To use the pre-defined CVM-S/CVM-H/CenCal/1D constructors, include the appropriate header file listed below in your code, link the UCVM /lib/libucvm_*.a and appropriate model library files (eg: libvxapi.a for CVM-H), and call the appropriate <code>ucvm_*_get_model()</code> function with an empty model structure. The filled-in <code>ucvm_model_t</code> structure may then be passed into <code>ucvm_add_model()</code> to enable that model.
+
Multiple models may be registered, and they are queried in order of registration.
 
 
<pre>
 
  /include/ucvm_cvms.h:
 
 
 
  /* Fill model m struct with CVM-S configuration */
 
  ucvm_cvms_get_model(ucvm_model_t *m);
 
 
 
  /include/ucvm_cvmh.h:
 
 
 
  /* Fill model m struct with CVM-H configuration */
 
  ucvm_cvmh_get_model(ucvm_model_t *m);
 
 
 
  /include/ucvm_cencal.h:
 
 
 
  /* Fill model m struct with CenCal configuration */
 
  ucvm_cencal_get_model(ucvm_model_t *m);
 
 
 
  /include/ucvm_1d.h:
 
 
 
  /* Fill model m struct with 1D configuration */
 
  ucvm_1d_get_model(ucvm_model_t *m);
 
</pre>
 
 
 
The programmer may define their own constructors, and therefore define their own models, by creating a C source wrapper that defines the init(), finalize(), version(), and query() functions for their model, and a <code>ucvm_*_get_model()</code> function for populating a new <code>ucvm_model_t</code> structure with the model information.
 
  
  
Line 216: Line 197:
 
   ucvm_prop_t *prop1;
 
   ucvm_prop_t *prop1;
 
    
 
    
  int num_models;
 
  ucvm_model_t models[UCVM_MAX_MODELS];
 
  int model_ids[UCVM_MAX_MODELS];
 
 
 
   printf("Init\n");
 
   printf("Init\n");
 
   if (ucvm_init("./ucvm.conf") != UCVM_CODE_SUCCESS) {
 
   if (ucvm_init("./ucvm.conf") != UCVM_CODE_SUCCESS) {
Line 232: Line 209:
 
   }
 
   }
 
    
 
    
   printf("Get Model\n");
+
   printf("Add Model CVM-S\n");
   if (ucvm_cvms_get_model(&(models[0])) != UCVM_CODE_SUCCESS) {
+
   if (ucvm_add_model(UCVM_MODEL_CVMS) != UCVM_CODE_SUCCESS) {
 
     fprintf(stderr, "Retrieval of CVM-S failed\n");
 
     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);
 
     return(1);
 
   }
 
   }
Line 250: Line 222:
 
   }
 
   }
  
   printf("Query Models\n");
+
   printf("Query Model\n");
 
   if (ucvm_query(nn, pnt1, prop1) != UCVM_CODE_SUCCESS) {
 
   if (ucvm_query(nn, pnt1, prop1) != UCVM_CODE_SUCCESS) {
 
     fprintf(stderr, "Query CVM failed\n");
 
     fprintf(stderr, "Query CVM failed\n");

Revision as of 04:21, 24 March 2011

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
  • Any user-defined model that can be encapsulated in a C header and source/library file

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 CVMs 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 and USC HPCC.

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

Data Types and Definitions

The following data types are defined in the API (/include/ucvm_dtypes.h):

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

UCVM provides an interface for querying Vp, Vs, and rho from any user-defined model. Models are described by the ucvm_model_t structure. Pre-defined models are defined for CVM-S, CVM-H, CenCal, and 1D to allow the programmer to easily use these velocity models. These models may be enabled by calling ucvm_add_model() with their string identifier.

/* Predefined models */
#define UCVM_MODEL_CVMH "cvmh"
#define UCVM_MODEL_CVMS "cvms"
#define UCVM_MODEL_CENCAL "cencalvm"
#define UCVM_MODEL_1D "1d"

/* 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, by label or by ucvm_model_t */
int ucvm_add_model(const char *label);
int ucvm_add_user_model(ucvm_model_t *m);

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

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

The programmer may also define their own models and integrate them into UCVM. A user model is defined by creating the init(), finalize(), version(), and query() functions for the model, and populating the ucvm_model_t structure with these function pointers and some additional record keeping information. Once a model is fully described in a ucvm_model_t, it can be registered for use with the ucvm_add_user_model() function and queried with the ucvm_query() function.

Multiple models may be registered, and they are queried in order of registration.


UCVM Grid Interface

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

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

The following code snippet illustrates how the API is used:

  int i;
  int nn = NUM_POINTS;
  ucvm_point_t *pnt1;
  ucvm_prop_t *prop1;
  
  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 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 Model\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);
  }


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 coordinates are currently supported
  • No smoothing between models is performed. They are simply tiled.
  • Projections are performed with the Proj.4 package


Future Improvements

  • Addition of a high resolution state-wide DEM to allow query by elevation
  • Addition of other regional models
  • Addition of one or more 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:

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.


GTL

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