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
$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:
- Added a
getModelObjectmethod to the C++
SlbmInterfaceobject. Previously it was difficult to get access to the
GeoTessModelSLBMthat contained all the model information; instead, you had to go through the
- Added getters for the great circle information in C++
- 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
isEqualmethod in the C++ and Python
SlbmInterfaceto compare the velocity model and/or great circle loaded into an
- Overloaded the
==operator in C++ and Python to call
isEqual, so two
SlbmInterfaceobjects can be easily compared.
- Added a
modelsEqualstatic method to every interface, which takes two model pathnames as strings for input and tests whether they are equal. This function works on both
*.geotessfiles as well as directories containing a
geotessmodelfile following the old v3 model format.
- Implemented read/write functionality for the new PDU models into SLBM model format v3, callable via
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
pdu202009Dumodel (don’t forget that it’s just
pdu2020012Dureformatted 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.geotessfile. 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.