RSTT v3.2.1 User Manual

Tested on:

Compiling RSTT from source

In the latest versions of RSTT, no paths should need to be specified in any environment variables to compile and run. During the compilation process, the Makefiles will point to the correct library paths within the default directory structure. If you are having difficulty with strange errors related to paths during compilation, try and temporarily remove any remnants of past RSTT versions in environment variables such as $PATH, $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH, and $SLBM_ROOT or $SLBM_HOME.

When writing your own codes that utilize the RSTT libraries, you may find it useful to set one of the following environmental variables to the root directory of RSTT:

1. $RSTT_ROOT
2. $RSTT_HOME
3. $SLBM_ROOT
4. $SLBM_HOME

In both the Java and Python interfaces, RSTT will first attempt to load the appropriate libraries through default system paths. If that fails, they will fall back to searching the path provided in the above variables, in order.

Dependencies

MacOS

Below is a list of packages and software required to build all interfaces and documentation of RSTT from source. The version numbers listed are those that were used and tested in development. RSTT should compile and run on much older versions of these components.

The easiest way to satisfy these dependencies on MacOS is to use Mamba/conda-forge for Python and the Homebrew package manager for all other languages. Following that, you can install the necessary dependencies by running these commands in a terminal window from the main RSTT directory:

$ xcode-select --install
$ brew install temurin gfortran doxygen
$ conda env create -n rstt -f SLBM_Py_shell/environment.yml

Linux

Below is a list of packages and software required to build RSTT from source. The version numbers listed are not necessarily required to compile without error; they are simply those that were used and tested in development.

The easiest way to satisfy these dependencies on Linux, depending on your distro and package manager, is by running the appropriate commands below in a terminal window:

# C++, C
$ sudo apt install build-essential

# Fortran
$ sudo apt install gfortran

# Java
$ sudo apt install default-jdk default-jre

# Python (standard)
$ sudo apt install python3-pip python3-pip-whl python3-dev python3-pybind11 pybind11-dev

# Python (conda-forge)
$ conda env create -n rstt -f SLBM_Py_shell/environment.yml

# documentation
$ sudo apt install doxygen pandoc python3-sphinx python3-sphinx-autodoc-typehints python3-sphinx-rtd-theme

# enable additional package repo
$ sudo dnf config-manager --set-enabled crb         # RHEL 9
$ sudo dnf config-manager --set-enabled powertools  # RHEL 8

# C, C++
$ sudo dnf group install 'Development Tools'

# Fortran
$ sudo dnf install gcc-gfortran

# Java
$ sudo dnf install java-devel

# Python (stanard)
$ sudo dnf install python3-devel python3-wheel python3-pybind11 pybind11-devel

# Python (conda-forge)
$ conda env create -n rstt -f SLBM_Py_shell/environment.yml

# documentation
$ sudo dnf install doxygen pandoc python3-sphinx
$ sudo python3 -m pip install sphinx-autodoc-typehints sphinx-rtd-theme

Build instructions

RSTT is developed in C++, but it also has interfaces in C, Fortran, Java, and Python. RSTT is distributed in various precompiled forms on sandia.gov/rstt, but if you prefer—or need—to compile it from source, the Makefiles have been designed so that you need only compile the minimum amount of code necessary to use RSTT with your language of choice. Do note, however, that because RSTT is developed in C++, the core C++ libraries will have to be compiled regardless of whether or not you intend to use only the C, Fortran, Java, or Python interfaces.

To generally compile RSTT in any of its languages, use the commands, below:

For more granular-level control of the make process, you may use the following commands:

Usage examples

In the usage_examples directory, there is one example program for each of the languages supported by RSTT.

Each example program performs the same set of tasks and is written to be as simple as possible with extensive commenting. These programs are meant to be a starting point from which users may explore the documentation and write their own code.

To build and run each example, cd to usage_examples and run make.sh with any combination of arguments:

• cpp
• c
• fortran
• java
• python
• all

To see an example of how to build and run your own progam, open make.sh and view with your favorite text or source code editor. This shell script is extensively commented, and each language is sorted into compile and run segments.

Path troubleshooting

Care was taken to make linking to the RSTT libraries as painless as possible. For any of the languages, you can run usage_examples/make.sh, and it will print the compiling and run commands as they are executed so that you can see how the base libraries are included and linked during compilation. For example, these are the commands used to link and compile the Fortran usage example on MacOS,

# NOTE: $RSTT_ROOT = /path/to/rstt
$ gfortran -mcpu=native -Ddarwin -O1 -fno-underscoring -cpp -ffree-line-length-none -I$RSTT_ROOT/GeoTessCPP/include -I$RSTT_ROOT/SLBM/include -I$RSTT_ROOT/SLBM_Fort_shell/include -o fortran_example.o -c fortran_example.f90
$ gfortran -mcpu=native -Ddarwin -O1 -fno-underscoring -cpp -ffree-line-length-none -Wl,-rpath,$RSTT_ROOT/lib -o fortran_example fortran_example.o -lm -lstdc++ -L$RSTT_ROOT/lib -lgeotesscpp -lslbm -lslbmFshell

For Java programs, you have to ensure that libslbmjni is in your java.library.path, and that slbmjni.jar is in your classpath. When invoking your java command, this can be accomplished by

$ java -classpath .:/path/to/rstt/lib/slbmjni.jar -Djava.library.path=/path/to/rstt/lib example_java

For Python programs, you should either ensure that your Python module search path contains the RSTT lib folder, e.g.,

import sys
sys.path.append('/path/to/rstt/lib')

or you should install the compiled RSTT Python module,

$ python3 -m pip install --no-index --find-links=/path/to/rstt/SLBM_Py_shell/wheel rstt

The rstt Python module contains copies of libgeotesscpp and libslbm within the module structure, itself, and unless something goes wrong, it should load those internal copies by default.

Both the Python and Java usage examples also contain blocks of code to attempt to read the appropriate libraries using paths from environment variables if they fail to find them any other way. These code blocks are well-commented and are located in the static {} block in java_example.java and before the if __name__ == "__main__" in python_example.py. Both bits of code work the same way, which is to first attempt to load the correct libraries using a simple loadLibrary or import command, and if that fails they will search the paths delineated in the following environment variables, in order,

1. $RSTT_ROOT
2. $RSTT_HOME
3. $SLBM_ROOT
4. $SLBM_HOME

If you set one of these environment variables in your terminal ($ export RSTT_ROOT=/path/to/rstt) and simply copy and paste the described code blocks in the usage_examples/java_example.java and python_example.py into your own programs, you will not have to provide -Djava.library.path when invoking your java command, nor will you have to pip install the rstt module in Python—instead the rstt module will be imported from the rstt folder inside of /path/to/rstt/lib.

Contact Information

For questions/issues/comments about the software, please contact:

• Brian Young (Sandia National Laboratories)

For questions/issues/comments about the results returned by RSTT, please contact:

• Steve Myers (Lawrence Livermore National Laboratory)

• Mike Begnaud (Los Alamos National Laboratory)