|
|
| (15 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| | = Overview = | | = Overview = |
| | | | |
| − | The Unified California Velocity Model API (UCVM API) is a programming interface that allows the user to directly | + | 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. |
| − | query multiple velocity models in a program. The API currently support these models: | |
| | | | |
| | + | This document has been superseded by the [[UCVM User Guide]]. |
| | | | |
| − | Crustal Models:
| + | This page now remains as a collection point for outstanding science issues. Significant science issues remain to be resolved. Please see the Science Issues section below. |
| − | * [[CVM-S]]
| |
| − | * [[CVM-H]]
| |
| − | * USGS Central California
| |
| − | * Hadley-Kanamori 1D
| |
| − | * [[Lin Thurber CVM]] California Statewide
| |
| − | * Rob Graves Cape Mendocino
| |
| − | * 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 at 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 disrepancies 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, by label or by ucvm_model_t */
| |
| − | int ucvm_add_model(const char *label);
| |
| − | int ucvm_add_user_model(ucvm_model_t *m);
| |
| − | | |
| − | /* 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. Pre-defined models include CVM-S, CVM-H, CenCal, Lin-Thurber, Rob Graves Cape Mendocino, 1D, and Ely GTL. These models may be enabled by calling <code>ucvm_add_model()</code> with their string identifier as listed in ucvm_dtypes.h.
| |
| − | * The programmer may also define their own models and integrate them into UCVM. A user model is defined by creating the init(), finalize(), version(), setparam(), 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.
| |
| − | * Multiple models may be registered, and they are queried in order of registration.
| |
| − | | |
| − | | |
| − | === 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>
| |
| − | | |
| − | | |
| − | Models (both crustal and GTL) are specified with a <code>ucvm_model_t</code> structure:
| |
| − | <pre>
| |
| − | /* Model */
| |
| − | typedef struct ucvm_model_t
| |
| − | {
| |
| − | char label[UCVM_MAX_LABEL_LEN];
| |
| − | ucvm_mtype_t mtype;
| |
| − | 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 (*setparam)(int param, ...);
| |
| − | int (*query)(ucvm_ctype_t cmode,
| |
| − | int n, ucvm_point_t *pnt,
| |
| − | ucvm_data_t *data);
| |
| − | } ucvm_model_t;
| |
| − | </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>
| |
| − | | |
| − | | |
| − | = Example Usage of API =
| |
| − | | |
| − | == 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-H\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>
| |
| | | | |
| | | | |
| Line 324: |
Line 20: |
| | | | |
| | * 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. | | * 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 | + | * Only lon,lat,dep and lon,lat,elev coordinates are currently supported |
| − | * No smoothing between models is performed. They are simply tiled. | + | * No smoothing between crustal models is performed. They are simply tiled. |
| | * Projections are performed with the Proj.4 package | | * 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. | + | * 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 = | | = Future Improvements = |
| | | | |
| − | * Allow query by elevation
| |
| | * Addition of other regional models | | * Addition of other regional models |
| − | * Addition of additional GTLs | + | * Addition of other GTLs |
| | + | * Addition of other DEMs, VS30 maps |
| | * Bindings for Fortran, C++ | | * Bindings for Fortran, C++ |
| | | | |
