Difference between revisions of "UCVM API"

From SCECpedia
Jump to navigationJump to search
 
(43 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
= UCVM API =
+
= Overview =
−
== API Definitions ==
 
  
−
<pre>
+
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.
−
// 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
+
This document has been superseded by the [[UCVM User Guide]].
−
// directories
 
−
enumerated CVM_GTL_TYPES = {CVM_GTL_NONE, CVM_GTL_ALL, CVM_GTL_VS30}
 
  
−
// Supported model coordinates. Geo versus UTM, and depth versus elevation
+
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.
−
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
+
= Source Code =
−
// 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
 
−
</pre>
 
  
−
== API Functions ==
+
The UCVM source and cvm2mesh mesh generator may be checked out from SVN with these commands:
  
−
<pre>
+
UCVM: svn co https://source.usc.edu/svn/ucvm/trunk
−
// 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
+
cvm2mesh: svn co https://source.usc.edu/svn/cvm2mesh/trunk
−
// 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
+
= Implementation Details =
−
INT cvm_clear_models()
 
  
−
// Clear list of enabled GTLs
+
* 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.
−
INT cvm_clear_gtls()
+
* 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.
  
−
// 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
+
= Future Improvements =
−
// Returns an array of material properties data for those points.
 
−
CVM_DATA_ARRAY cvm_query_array(CVM_POINT_ARRAY point_array)
 
−
</pre>
 
−
 
 
−
= Example Usage of API in Pseudocode =
 
  
−
<pre>
+
* Addition of other regional models
−
INT FUNCTION main:
+
* Addition of other GTLs
−
// Initialize in serial mode
+
* Addition of other DEMs, VS30 maps
−
if cvm_init(stage_path=””, prestaged=False) == ERROR:
+
* Bindings for Fortran, C++
−
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
 
−
</pre>
 
−
 
 
−
= 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
 
  
−
 
+
= Science Issues =
−
= Issues =
+
 
  
 
== Overlapping Models ==
 
== Overlapping Models ==
−
Models may overlap in ways which makes merging them difficult. Imagine the scenario outlined on the right in the diagram below.
+
 
 +
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]]
 
[[File:State-wide-Overlapping-Models.png]]
−
+
 
−
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:
+
The models may overlap in ways which makes merging them difficult.
−
*Coordinate edits to each model to bring their material properties into better agreement within the overlap region.
+
*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:
−
*Crop one or both models to remove the overlap, and smooth them into the California background model.
+
**Coordinate edits to each model to bring their material properties into better agreement within the overlap region.
−
*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.
+
**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.

Latest revision as of 19:47, 19 August 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.

This document has been superseded by the UCVM User Guide.

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.


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 other GTLs
  • Addition of other DEMs, VS30 maps
  • 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.


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.

Retrieved from "https://strike.scec.org/scecwiki/index.php?title=UCVM_API&oldid=3281"