Version 3.2.0 – 2021/02/10

Posted on

The major new feature in this update is a Python interface! Note that there is a minimum requirement of Python 3.6.

The Python interface can be installed using pip (see instructions in the README), and as it contains the required C++ GeoTess and RSTT libraries inside of the module package, itself, if you install it via pip, you will not need to set any path variables—it should “just work”.

Alternatively, an extracted version of the module is stored in the $RSTT_ROOT/lib directory, so if you do not want to pip install the RSTT module, just set the $SRTT_ROOT environment variable, and use the Python code at the top of usage_examples/python_example.py in your own programs to load the module. The example Python code has been written to recognize $RSTT_ROOT, $RSTT_HOME, $SLBM_ROOT, and $SLBM_HOME as potential search paths.

This update also makes a considerable number of other changes under-the-hood, mostly in the path-dependent uncertainty RSTT model file format. The new model format is compatible with the new version of GeoTess (v2.6.1) and will be the permanent new binary format going forward. The format introduced in v3.1.0 with the pdu2020012Du model is no longer supported, and that model has been converted to the new format and renamed to pdu202009Du. The new versions of GeoTess, GeoTess Builder, and GeoTess Explorer, contain robust new methods to interact with these new model files, including resampling the grid and extracting and replacing the PDU data. The old models (e.g., rstt201404um) are still supported for backwards compatibility.

Other miscellaneous changes and fixes:

  • Henceforth, path-dependent uncertainty will be referred to as “PDU”, and the old 1D distance-dependent uncertainties (i.e., path-independent uncertainty) will be called “PIU”. This naming convention is concise and convenient.
  • Improved the path situation. The Java and Python usage examples contain well-commented code demonstrating how to load the proper files provided one of these environmental variables is set: $RSTT_ROOT, $RSTT_HOME, $SLBM_ROOT, and $SLBM_HOME.
  • Added a getModelObject method to the C++ SlbmInterface object. Previously it was difficult to get access to the GeoTessModelSLBM that contained all the model information; instead, you had to go through the Grid class.
  • Added getters for the great circle information in C++ SlbmInterface.
  • Overloaded literally every C++ method, where possible, that passed or returned arrays with new merthods that take vectors, instead. These new methods no longer require you to pre-allocate arrays or pass in the existing or anticipated size of arrays. Instead, vectors will be expanded as needed, and the length of the vectors you pass in is easily determined by code.
  • Added an isEqual method in the C++ and Python SlbmInterface to compare the velocity model and/or great circle loaded into an SlbmInterface object.
  • Overloaded the == operator in C++ and Python to call isEqual, so two SlbmInterface objects can be easily compared.
  • Added a modelsEqual static method to every interface, which takes two model pathnames as strings for input and tests whether they are equal. This function works on both *.geotess files as well as directories containing a geotessmodel file following the old v3 model format.
  • Implemented read/write functionality for the new PDU models into SLBM model format v3, callable via saveVelocityModel.
  • Removed SLBMVersion.h. This file was never used.
  • Updated internal version of GeoTess to v2.6.1.
  • Many small improvements to the files in usage_examples. These are intended to help new and old users, alike, to base their own programs on.
  • Resampled the new pdu202009Du model (don’t forget that it’s just pdu2020012Du reformatted into the new file format) down to a resolution of 30° and named it unittest.geotess. This is a very small model file (a few hundred kilobytes) that is useful for testing.
  • Replaced all of the tests for all of the interfaces to use the new unittest.geotess file. The old tests were hard-coded to use rstt201404um, which is both old and a fairly large file to keep around just for testing. The new tests are called “unit tests”, but they don’t rely on any unit testing frameworks. They’re just short, simple programs that ensure that the travel time and uncertainty computed for a single great circle matches what it is supposed to be.
  • Since v3.1.0, there have been tens of thousands of changes to the C++ codebase. These changes include numerous small bugfixes, dozens of convenient new overloaded functions in the C++ SlbmInterface, and substantially rewritten architecture for the new model type.