Talk:UCVM API

I would suggest a much simpler, more flexible API. For simplicity I am using C++ but this can be translated to C. I personally prefer the main code in C++ for modularity coupled with C and Fortran bindings for use from multiple languages. I would keep the UCVM layer as thin as possible and have its responsibilities be to simply broker which CVM is queried. It could simply determine which CVM to query and pass off the query to that CVM. Regions between detailed seismic velocity models would have to be handled by a background or region specific intermediate model.

The UCVM API should use geographic coordinates (lon, lat, elevation with horizontal (e.g. WHS84) and vertical (e.g., MSL) datums wrt MSL) for accurate georeferencing over any scale. The broker layer would only need to know the geographic bounding box and depth range of the CVMs to which it provides access. Indicating the horizontal and vertical datums could be handled by a relatively simply object that is setup to be consistent with a geographic projection library. I created one that works with Proj.4.

As a starting point, I would set the flags for the various databases outside the UCVM, although it probably wouldn't be too difficult to come up with a short list of flags. The danger is a proliferation of lots of flags/settings that are not actually common across the CVMs.

 /** Open the database and prepare for querying.
  *
  * @param db Array of detailed DB to use in queries.
  * @param numDB Number of detailed DB.
  */
 void open(const CVMDB* db,
           const int numDB);

 /// Close the database.
 void close(void);

 /** Set values to be returned by queries.
  *
  * @pre Must call open() before queryVals()
  *
  * @param names Names of values to be returned in queries
  * @param numVals Number of values to be returned in queries
  */
 void queryVals(const char* const* names,
                const int numVals);

 /** Query the database.
  *
  * @note vals should be preallocated to accommodate numVals values.
  *
  * @pre Must call open() before query().
  *
  * @param vals Array for computed values (output from query), must be
  *   allocated BEFORE calling query().
  * @param numVals Number of values expected (size of pVals array)
  * @param coords Coordinates of point for query [numDims].
  * @param numDims Number of dimensions for coordinates.
  * @param csQuery Coordinate system of coordinates. [Separate object that wraps Proj.4 or other geographic projection library]
  *
  * @returns 0 on success, 1 on failure (i.e., could not interpolate)
  */
 int query(double* vals,
           const int numVals,
           const double* coords,
           const int numDims,
           const CoordSys* csQuery);

 /** Perform multiple queries of the database.
  *
  * @note vals should be preallocated to accommodate numVals values
  * at numLocs locations.
  *
  * @note err should be preallocated to accommodate numLocs values.
  *
  * @pre Must call open() before query().
  *
  * @param vals Array for computed values (output from query), must be
  *   allocated BEFORE calling query() [numLocs*numVals].
  * @param numLocsV Number of locations.
  * @param numValsV Number of values expected.
  * @param err Array for error flag values (output from query), must be
  *   allocated BEFORE calling query() [numLocs].
  * @param numLocsE Number of locations.
  * @param coords Coordinates of point for query [numLocs*numDims].
  * @param numLocsC Number of locations.
  * @param numDimsC Number of dimensions for coordinates.
  * @param csQuery Coordinate system of coordinates.
  */
 void multiquery(double* vals,
                 const int numLocsV,
                 const int numValsV,
                 int* err,
                 const int numLocsE,
                 const double* coords,
                 const int numLocsC,
                 const int numDimsC,
                 const CoordSys* csQuery);