UCVM Model Integration Guide

Introduction

UCVM 14.7.0 introduced a new interface designed to make installing and adding new models easier. Unlike previous versions of UCVM, starting with UCVM 14.7.0, UCVM will not need to know about the model at compile-time in order to make use of it. This means that model developers can more readily use UCVM's plotting utilities, meshing utilities, and other capabilities with their models.

Please note that this guide is only for systems that support dynamic linking. If you are on a system that only supports static linking, you will need to follow the steps at the end of the guide to make the model work with UCVM.

Interface Description

Directory Structure

UCVM searches and reads models that are installed in a standardized format. Suppose that you have UCVM installed in /home/user/ucvm-14.6.0. All models are installed in the "model" directory and must follow this format to be included:

/home/user/ucvm-14.7.0/model/[name]/lib/lib[name].so

So, if we are trying to install a model named "acme", we would need our shared object library to be at:

/home/user/ucvm-14.7.0/model/acme/lib/libacme.so

Basic Structures

All UCVM models work in the following basic manner:

1. Take as input latitude, longitude, and depth, with spherical earth co-ordinates using the WGS84 ellipsoid.
2. Return material properties for that point. The material properties consist of one or more of Vp (m/s), Vs (m/s), Density (g/cm^3), Qp, and/or Qs.

UCVM passes the input latitude, longitude, and depth through a structure which is defined as follows:

typedef struct basic_point_t {
    double longitude;    // Longitude in degrees
    double latitude;    // Latitude in degrees
    double depth;    // Depth in meters
} basic_point_t;

All models need to then read in points in the above format and return material properties in the following format:

typedef struct basic_properties_t {
    double vp;    // Vp in meters per second
    double vs;    // Vs in meters per second
    double rho;    // Density in grams per cubic centimeter
    double qp;    // Qp
    double qs;    // Qs
} basic_properties_t;

Model Operation

Models called from UCVM undergo the following lifecycle:

1. Initialization - during this period, the model is initialized and should load any necessary data to memory as disk can be relatively slow. It's also recommended that the model pre-compute as much as possible with regards to projections, coefficients, and so on.
2. Query - after models are initialized they must be ready to accept queries. Queries are arrays of the basic_point_t structure, as described in the structures section, and a pre-malloced pointer to an array of basic_properties_t, which will contain the material properties. If no properties are available, models are advised to return -1 for each of the entries in the basic_properties_t structure.
3. Finalize - models who are called to finalize must free up their resources.

Function Definitions

There are four functions that must be implemented:

int model_init(const char *dir, const char *label)
Description: Called to initialize the model and load whatever contents are necessary into memory.
Parameters:

• dir - The directory in which UCVM is located (e.g. /home/user/ucvm-14.7.0).
• label - The model name (e.g. acme). So the model's full directory is always [dir]/model/[label].

Returns: 0 if the model initialization worked, 1 if it didn't.