UCVM API - Revision history

Patrices at 19:47, 19 August 2011

2011-08-19T19:47:15Z

Patrices at 19:43, 19 August 2011

2011-08-19T19:43:31Z

Show changes

Patrices at 18:35, 19 August 2011

2011-08-19T18:35:25Z

Patrices at 16:59, 19 August 2011

2011-08-19T16:59:06Z

Patrices at 21:32, 5 July 2011

2011-07-05T21:32:40Z

Patrices at 20:12, 2 June 2011

2011-06-02T20:12:16Z

Patrices at 19:56, 2 June 2011

2011-06-02T19:56:31Z

Patrices at 19:31, 2 June 2011

2011-06-02T19:31:46Z

Patrices at 23:36, 17 May 2011

2011-05-17T23:36:50Z

Patrices at 18:28, 12 May 2011

2011-05-12T18:28:54Z

@@ Line 3: / Line 3: @@
 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 superceded by the [[UCVM User Guide]].
+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.

@@ Line 1: / Line 1: @@
 = 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. The [[UCVM User Guide]] lists the currently supported models. The API may also be easily extended to support any user-defined crustal or GTL model as long as that model can be expressed in a C header and source/library file. The API itself is written in the C language.
 Significant science issues remain to be resolved. Please see the Science Issues section below.

@@ Line 406: / Line 406: @@
+   }
-   printf("Add Crustal Model CVM-H\n");
+   printf("Add Crustal Model CVM-S\n");
    if (ucvm_add_model(UCVM_MODEL_CVMS) != UCVM_CODE_SUCCESS) {
      fprintf(stderr, "Retrieval of CVM-S failed\n");

@@ Line 7: / Line 7: @@
 Crustal Models:
 * [[CVM-S]]
 * [[CVM-H]]
 * USGS Central California

@@ Line 299: / Line 299: @@
 # UCVM model path
-ucvm_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/ucvm
+ucvm_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/ucvm
 # Coverage regions (currently disabled)
@@ Line 307: / Line 307: @@
 # Predefined model paths
-cvms_modelpath=/home/scec-00/patrices/opt/aftershock/cvms/src
+cvms_modelpath=/home/scec-00/USER/opt/aftershock/cvms/src
-cvmh_modelpath=/home/scec-00/patrices/opt/aftershock/cvmh/bin
+cvmh_modelpath=/home/scec-00/USER/opt/aftershock/cvmh/bin
-cencal_modelpath=/home/scec-00/patrices/opt/etree/USGSBayAreaVM-08.3.0.etree
+cencal_modelpath=/home/scec-00/USER/opt/etree/USGSBayAreaVM-08.3.0.etree
-cencal_extmodelpath=/home/scec-00/patrices/opt/etree/USGSBayAreaVMExt-08.3.0.etree
+cencal_extmodelpath=/home/scec-00/USER/opt/etree/USGSBayAreaVMExt-08.3.0.etree
-lin-thurber_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/lin-thurber
+lin-thurber_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/lin-thurber
-cmrg_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/cmrg
+cmrg_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/cmrg
-cmuetree_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/cmuetree
+cmuetree_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/cmuetree
 # User-defined models
 cybershake_interface=etree
-cybershake_modelpath=/home/scec-00/patrices/tmp/cybershake_1hz_250ms.e
+cybershake_modelpath=/home/scec-00/USER/tmp/cybershake_1hz_250ms.e
 cencal_p1_interface=patch
-cencal_p1_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p1.conf
+cencal_p1_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p1.conf
 cencal_p2_interface=patch
-cencal_p2_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p2.conf
+cencal_p2_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p2.conf
 cencal_p3_interface=patch
-cencal_p3_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p3.conf
+cencal_p3_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p3.conf
 cencal_p4_interface=patch
-cencal_p4_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p4.conf
+cencal_p4_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cencal_p4.conf
 cvmh_p1_interface=patch
-cvmh_p1_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p1.conf
+cvmh_p1_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p1.conf
 cvmh_p2_interface=patch
-cvmh_p2_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p2.conf
+cvmh_p2_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p2.conf
 cvmh_p3_interface=patch
-cvmh_p3_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p3.conf
+cvmh_p3_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p3.conf
 cvmh_p4_interface=patch
-cvmh_p4_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p4.conf
+cvmh_p4_modelpath=/home/scec-00/USER/opt/aftershock/ucvm/model/patch/cvmh_p4.conf
 # Model flags

← Older revision		Revision as of 19:56, 2 June 2011
Line 290:		Line 290:

	= Example Usage of API =		= Example Usage of API =
		+
		+	== Configuring UCVM ==
		+
		+	The following is an example ucvm.conf file showing model paths to all predefined models as well as several user-defined etrees and patches.
		+
		+	<pre>
		+	# UCVM config file
		+
		+	# UCVM model path
		+	ucvm_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/ucvm
		+
		+	# Coverage regions (currently disabled)
		+	#cvms_region=-122.0,30.0,-112.0,35.5
		+	#cvmh_region=-122.0,30.0,-112.0,35.5
		+	#cencal_region=-126.0,35.5,-119.0,40.0
		+
		+	# Predefined model paths
		+	cvms_modelpath=/home/scec-00/patrices/opt/aftershock/cvms/src
		+	cvmh_modelpath=/home/scec-00/patrices/opt/aftershock/cvmh/bin
		+	cencal_modelpath=/home/scec-00/patrices/opt/etree/USGSBayAreaVM-08.3.0.etree
		+	cencal_extmodelpath=/home/scec-00/patrices/opt/etree/USGSBayAreaVMExt-08.3.0.etree
		+	lin-thurber_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/lin-thurber
		+	cmrg_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/cmrg
		+	cmuetree_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/cmuetree
		+
		+	# User-defined models
		+	cybershake_interface=etree
		+	cybershake_modelpath=/home/scec-00/patrices/tmp/cybershake_1hz_250ms.e
		+	cencal_p1_interface=patch
		+	cencal_p1_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p1.conf
		+	cencal_p2_interface=patch
		+	cencal_p2_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p2.conf
		+	cencal_p3_interface=patch
		+	cencal_p3_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p3.conf
		+	cencal_p4_interface=patch
		+	cencal_p4_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cencal_p4.conf
		+	cvmh_p1_interface=patch
		+	cvmh_p1_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p1.conf
		+	cvmh_p2_interface=patch
		+	cvmh_p2_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p2.conf
		+	cvmh_p3_interface=patch
		+	cvmh_p3_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p3.conf
		+	cvmh_p4_interface=patch
		+	cvmh_p4_modelpath=/home/scec-00/patrices/opt/aftershock/ucvm/model/patch/cvmh_p4.conf
		+
		+	# Model flags
		+	cvmh_param=USE_1D_BKG,False
		+	</pre>

	== Basic Example with Crustal Model Only ==		== Basic Example with Crustal Model Only ==

@@ Line 72: / Line 72: @@
 int ucvm_finalize();
-/* Enable specific model, by label or by ucvm_model_t */
+/* Enable specific model(s), by string list, by label, or
 int ucvm_add_model(const char *label);
 int ucvm_add_user_model(ucvm_model_t *m, ucvm_modelconf_t *conf);
@@ Line 111: / Line 113: @@
 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, Ely GTL or any SCEC UCVM Etree. These models are enabled by calling <code>ucvm_add_model()</code> with their name string identifier as listed in either ucvm_dtypes.h (pre-defined) or in the UCVM configuration file (user-defined SCEC Etree).
+* Multiple models may be registered, and they are queried in order of registration.
 * The programmer may also define their own models and integrate them into UCVM. A user model interface is defined by creating the init(), finalize(), getversion(), getlabel(), setparam(), and query() functions for the model interface, and populating the <code>ucvm_model_t</code> structure with these function pointers and some additional record keeping information. Configuration information for a specific model instance of that interface is placed in a <code>ucvm_modelconf_t</code> structure. Once a model is fully described with a <code>ucvm_model_t</code> interface and a <code>ucvm_modelconf_t</code> configuration, it can be registered for use with the <code>ucvm_add_user_model()</code> function and queried with the <code>ucvm_query()</code> function.

@@ Line 12: / Line 12: @@
 * [[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
@@ Line 73: / Line 74: @@
 /* 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);
+int ucvm_add_user_model(ucvm_model_t *m, ucvm_modelconf_t *conf);
 /* Associate specific interp func with GTL model, by label
@@ Line 109: / Line 110: @@
 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.
+* Models are referenced either by a pre-defined string id or by a populated <code>ucvm_model_t</code> structure.
-* 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.
+* Pre-defined models include: CVM-S, CVM-H, CenCal, Lin-Thurber, Rob Graves Cape Mendocino, 1D, Ely GTL or any SCEC UCVM Etree. These models are enabled by calling <code>ucvm_add_model()</code> with their name string identifier as listed in either ucvm_dtypes.h (pre-defined) or in the UCVM configuration file (user-defined SCEC Etree).
 * Multiple models may be registered, and they are queried in order of registration.
@@ Line 155: / Line 157: @@
-Models (both crustal and GTL) are specified with a <code>ucvm_model_t</code> structure:
+Model interfaces (both crustal and GTL) are defined with a <code>ucvm_model_t</code> structure:
 <pre>
 /* Model */
 typedef struct ucvm_model_t
+{
    ucvm_mtype_t mtype;
    int (*init)(int id, ucvm_region_t *r, const char *config);
    int (*finalize)();
-   const char* (*version)();
+   int (*getversion)(int id, char *ver, int len);
-   int (*setparam)(int param, ...);
+  int (*getlabel)(int id, char *ver, int len);
-   int (*query)(ucvm_ctype_t cmode,
+   int (*setparam)(int id, int param, ...);
                 int n, ucvm_point_t *pnt,
                 ucvm_data_t *data);
@@ Line 230: / Line 230: @@
                             size_t n, const char *filename);
 </pre>
@@ Line 365: / Line 405: @@
 * Addition of additional GTLs
 * Bindings for Fortran, C++

@@ Line 369: / Line 369: @@
 === Etree Model Format ===
-* Variable resolution based off of Vs, max supported frequency, and points per wavelength. The resolution at any particular region will be dependent upon the local Vs value (relation shown below). However, a user-specified minimum Vs at Etree creation will clamp the resolution to a maximum value.
+* Variable resolution based off of Vs, max supported frequency, and points per wavelength. The resolution at any particular region will be dependent upon the local Vs value (relation shown below). However, a minimum Vs at Etree creation will clamp the resolution to a maximum value regardless of how low the local Vs is found to be.
 <pre>
 rez = vs / (ppwl * freq)