Summary of changes relative to SCECCode UCVM

[Brad Aagaard]

Issues and resolutions

Improve autotools integration - ec03398

1. Makefiles assume gcc compiler suite and a Linux operating system

   Use libtool to build libraries.
   libtool supports static and shared libraries on most modern Unix operating systems, including Linux and macOS.

2. Installation involves multiple Python scripts plus autotools

   Use autotools for installation, including libraries and models.
   Download models directly to install location, when possible, using curl.

Libraries are installed in model directories models can be installed in different locations - 95bf744

Install all libraries under $prefix/lib
Install all models under $prefix/share/ucvm/model (can be customized using --datarootdir=DIRECTORY)

Outdated Proj is used without datum files - 7dece9e

Update use of Proj to current API and latest version (8.2.1).
Install datum files along with Proj.

Note Proj 8.2.1 adds sqlite and libtiff as dependencies.
These are now built along with Proj. projsync requires libcurl, which I assumed would be available from the operating system.

Cleanup plugin model interface - e7f29a1

1. Plugin models are only given coordinates in depth

   Add surface elevation to coordinates array passed to plug in models.
   This allows plugin models to convert depth to elevation if needed by the underlying model API.

2. Plugin model interface used extra function calls

   Use ucvmapi_ prefix for required functions for UCVM plugin model interface.
   Eliminate get_* functions with direct assignment of plugin model functions to variables (function names are addresses so no need to get address of function names).

3. Plugin model interface uses structs defined in UCVM

   Create header file ucvm_plugin_dtypes.h that defines the entities needed for the plugin interface.
   This file can be included by plugin interface implementations.

Plugin models may need user parameters during initialize - aede0fa

Refactor plugin model creation into `create()`, `_set_parameter()`, and `_initialize()`.
This allows model parameters to be passed from the user `conf` file down to the plugin model so they can be set during the initialization process.

Issues not resolved

• Models are downloaded from a Globus URL. It would be much better to have models archived in a public repository, such as Zenodo.
• Refactor ucvm_dtypes.h. Much of the information is used in separate, small pieces of code. For example, move constants (sizes) useful in plugin models to ucvm_constants.h. Move model labels to ucvm_models.h.
• Some models, e.g., cvmh/vx, still rely on their own geographic coordinate conversion routines. It would be best if all models use Proj. This may require redoing the georeferencing of some models, if they were originally georeferenced using less accurate information.
• Suporting static plugin models requires that the code know the names of the plugin models and the interface functions. Are static plugin models actually needed?
• CCA library depends on Uthe CVM Vs30 map that is part of UCVM. It also defines its own structs that mirror those in UCVM; this is very fragile. It would be better to have CCA depend on UCVM and use the plugin header files to ensure compatible interfaces. If necessary, the plugin interface could be made available for download as a few header files (no compiling needed).
• Proj strongly recommends using EPGS codes, when possible, to define the geographic coordinate systems. "PROJ strings are a poor way of describing a CRS, and more precise its geodetic datum." Latitude (x) and longitude (y) in the WGS84 datum is EPSG:4326.
• For best performance, minimize copying information to/from structures for function arguments; copy into data structures once and reuse as much as possible. In some places passing a few scalars instead of copying to/from a structure would be more efficient.
• Use density instead of rho for clarity, especially for non-native English speakers.

Documentation

Layout

• All libraries installed to $prefix/lib
• All models installed to $prefix/share/ucvm (directory can be changed using --datarootdir=DIRECTORY).

Plugin models

• Coordinates for queries are passed to plugin models as latitude (WGS84), longitude (WGS84), depth (m).
• Interface functions have prefix ucvmapi_*.
• Model creation involves _create(), _set_parameter(), _initialize().

Coding Style

• Reformatted files using uncrustify.
• Use "if(!ptr)" instead of "if(ptr == NULL)" and "if(boolean_var)" instead of "if(boolean_var == 1)".
• Use full words for variable names. Justification: increases readability, avoids ambiguity when coding, makes it easier to search (try searching for variable "n").
• Code should be self-documenting (boolean variables should be clear what "true" means; no need to add comments for self-documenting code).
• Maximum line length should be 100-120, not 80 (too restrictive; legacy from printing code and small monitors). Using the debugger is easier if statements are all on one line.