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.6.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.6.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;