UCVM API

UCVM API

API Definitions

// Supported models. This list may be specified in a configuration file, along with their installation 
// directories
enumerated CVM_MODEL_TYPES = {CVM_MODEL_NONE, CVM_MODEL_ALL, CVM_MODEL_BACKGROUND, CVM_MODEL_H63, CVM_MODEL_H62, CVM_MODEL_H10_12_0, CVM_MODEL_4, CVM_MODEL_ETREE}

// Supported GTLs. This list may be specified in a configuration file, along with their installation 
// directories
enumerated CVM_GTL_TYPES = {CVM_GTL_NONE, CVM_GTL_ALL, CVM_GTL_VS30}

// Supported model coordinates. Geo versus UTM, and depth versus elevation
enumerated CVM_COORD_TYPES = {CVM_COORD_GEO_DEPTH, CVM_COORD_GEO_ELEV, CVM_COORD_UTM_DEPTH, CVM_COORD_UTM_ELEV}

// A single query point (x, y, z). The API knows how to interpet the point with the coord_type flag
structure CVM_POINT = {DOUBLE x, DOUBLE y, DOUBLE z, CVM_COORD_TYPES coord_type}

// A single set of return data. Vp, Vs, and Rho may not be available, and this is denoted with the boolean
// flags. The source of the data is returned in model_id.
structure CVM_DATA = {DOUBLE vp, DOUBLE vs, DOUBLE rho, CVM_MODEL_TYPES model_id, BOOL vp_valid, BOOL vs_valid, BOOL, rho_valid}
ARRAY CVM_POINT_ARRAY = array of CVM_POINT
ARRAY CVM_DATA_ARRAY = array of CVM_DATA

API Functions

// Initialization routine. If the API is invoked in a serial program, stage_dir is set to “”. If invoked in 
// an MPI program or on a system with a HPFS, stage_path is a target directory available to the API for
// staging copies of the enabled models/GTLs. The stage_path arguments passed to the API within each 
// rank of an MPI program must be unique across all ranks.
// The prestaged flag denotes that the desired models have been pre-staged at stage_path and do not
// need to be copied again.
// Returns success or error.
INT cvm_init(STRING stage_path, BOOL prestaged)

// User selects which models they want to use. This function may be called multiple times for different
// model ids. Model preference is determined by the order in which they are enabled.
// Returns success or error.
INT cvm_enable_model(CVM_MODEL_TYPES model_id)

// User selects which GTLs they want to use. This function may be called multiple times for different
// GTL ids. GTL preference is determined by the order in which they are enabled.
// Returns success or error.
INT cvm_enable_gtl(CVM_GTL_TYPES gtl_id)

// Clear list of enabled models
INT cvm_clear_models()

// Clear list of enabled GTLs
INT cvm_clear_gtls()

// Query the enabled CVMs for the specified point.
// Returns the material properties data for that point.
CVM_DATA cvm_query(CVM_POINT point)

// Query the enabled CVMs for the specified array of points
// Returns an array of material properties data for those points.
CVM_DATA_ARRAY cvm_query_array(CVM_POINT_ARRAY point_array)

 

Example Usage of API in Pseudocode

INT FUNCTION main:
// Initialize in serial mode
if cvm_init(stage_path=””, prestaged=False) == ERROR:
	return ERROR
// Enable CVM-H 10.12.0
if cvm_enable(model_id=CVM_MODEL_H10_12_0) == ERROR:
	return ERROR
// Define a point
CVM_POINT p = {x=-120.0, y=34.25, z=-100.0, coord_type=CVM_COORD_GEO_DEPTH}
// Query the API for this point
CVM_DATA d = cvm_query(p)
if d.model_id == CVM_MODEL_NONE:
	print “Point not found”
	return ERROR
if d.vp_valid == False or d.vs_flag == False or d.rho_flag == False:
	print “Not all material properties defined”
	return ERROR
// Do something with these material properties
	return SUCCESS

 

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.