Download, Build, and Run

This section provides instructions on how to download, build, run, and test the TRITON project.

Downloading TRITON

TRITON is a C++ project managed with Git. To obtain the source code, clone the repository using the following command:

git clone https://code.ornl.gov/hydro/triton.git
cd triton
git submodule update --init --recursive

Building TRITON

Prerequisites:

CMake: Version 3.16 or higher.
C++ Compiler: A C++17 compatible compiler.
MPI: MPI libraries with C++ bindings.

Optional:

CUDA, HIP, or SYCL for GPU acceleration
GDAL (Geospatial Data Abstraction Library) for GeoTIFF images

Build Steps:

Create a build directory: It’s recommended to build TRITON out-of-source.
```
mkdir build
cd build
```
Run CMake:

TRITON uses CMake as its build system. User can control TRITON build and execution through providing command-line arguments to cmake.

Note

If you have already built TRITON, several files generated by the CMake build system may interfere with your new build process. We recommend removing all files generated during the previous build by running the triton_clean.sh script. You may edit the script if you prefer to keep certain files.

The following examples show how to run cmake command to select a compiler and a backend to build TRITON on your system:

# create and change to the TRITON build directory
mkdir build
cd build

###############################
# CMake Command-line examples #
###############################

# the default compiler and backend are selected for the host OS
cmake ..

# the default compiler and backend are selected for the Frontier system
# Several systems are predefined. You can define the compiler, backend,
# and other settings for your system. See "Machine Configuration File" for details.
cmake .. -DMACHINE=frontier

# the Cray compiler and default backend are selected for the host OS
cmake .. -DCOMPILER=cray

# the default compiler and HIP backend are selected for the host OS
cmake .. -DBACKEND=HIP

# the default compiler and HIP backend are selected for the Frontier system
cmake .. -DMACHINE=frontier -DBACKEND=HIP

# the Cray compiler and HIP backend are selected for the Frontier system
cmake .. -DMACHINE=frontier -DCOMPILER=cray -DBACKEND=HIP

Note

In addition to the MACHINE, COMPILER, and BACKEND arguments, users can control compilation and execution by adding more arguments such as COMPILER_FLAGS. See the CMake Command-line Arguments for more details.

Build TRITON:

After completing the CMake configuration phase, run triton_build.sh in build directory to compile TRITON:

# assuming a Linux system

cd build
./triton_build.sh

Once the compilation task is successfuly done, triton.exe will be generated in the build directory.

Running TRITON

To run TRITON, in addition to compiling the TRITON executable, several preparatory steps are required: 1) preparing input data, 2) creating a simulation configuration file, and 3) executing the TRITON executable on your system. See the TRITON Setup for instructions on creating a simulation configuration file and the Running TRITON for details on running TRITON.

The following example commands demonstrate how to use triton_run.sh script and to run several pre-configured simulation cases

# assuming a Linux system
cd build

# runs an pre-selected example case, Allatoona
./triton_run.sh

# runs Circular Dambreak case
./triton_run.sh ./input/circular/circular_dambreak.cfg

# runs Paraboloid case
./triton_run.sh ./input/paraboloid/paraboloid.cfg

Testing TRITON Installation

If you enabled TRITON ctest during the CMake configuration by adding -DBUILD_TESTS=ON command-line argument , you can run the project’s tests using CTest.

cd build
./triton_ctest.sh

See the CMake Command-line Arguments for more details on additional arguments and environment variable support.