Commit 037d223a authored by Morales Hernandez, Mario's avatar Morales Hernandez, Mario
Browse files

Merge branch 'dev-output' into 'master'

TRITON v2: major src and doc updates

See merge request hydro/triton!6

Former-commit-id: 9ef29300
parents cee90615 cbe82a38
Loading
Loading
Loading
Loading
+1 −0
Original line number Diff line number Diff line
build
output
.DS_Store
.venv*
venv*
+17 −6
Original line number Diff line number Diff line
cmake_minimum_required(VERSION 3.16 FATAL_ERROR) # minimum CMake version to support Kokkos

set(TRITON_EXECUTABLE "triton.exe")

# put these before project(...)
include(cmake/util.cmake)
include(cmake/machine.cmake)
@@ -9,6 +11,8 @@ set_environment()
project(triton CXX)
set(CMAKE_CXX_STANDARD 17) # minimum C++ standard to support Kokkos

message(STATUS "CMAKE_CXX_COMPILER = ${CMAKE_CXX_COMPILER}")

# check if MPI is available
if(MACHINE STREQUAL Windows)
  find_package(MPI REQUIRED COMPONENTS CXX)
@@ -18,20 +22,27 @@ endif()
add_subdirectory(${TRITON_SOURCE_DIR}/external)

# build triton
process_target(triton.exe ./src/main.cpp)
target_include_directories(triton.exe PUBLIC ${Kokkos_INCLUDE_DIRS_RET})
add_build_and_run_scripts()
process_target(${TRITON_EXECUTABLE} ./src/main.cpp)
target_include_directories(${TRITON_EXECUTABLE} PUBLIC ${Kokkos_INCLUDE_DIRS_RET})

# add tools
if(${BUILD_TOOLS})
  add_subdirectory(${TRITON_SOURCE_DIR}/tools)
if (TRITON_ENABLE_GDAL)
  target_include_directories(${TRITON_EXECUTABLE} PUBLIC ${GDAL_INCLUDE_DIR})
  target_link_libraries(${TRITON_EXECUTABLE} PUBLIC ${GDAL_LIBRARY})
  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DTRITON_GDAL")
endif()

add_build_and_run_scripts()

# add tests
if(${BUILD_TESTS})
  find_package(Python3 COMPONENTS Interpreter REQUIRED)
  enable_testing()
  add_subdirectory(${TRITON_SOURCE_DIR}/test)
  add_test_script()
endif()

add_clean_script()

message(STATUS "CMAKE_CXX_FLAGS = ${CMAKE_CXX_FLAGS}")
message(STATUS "CMAKE_EXE_LINKER_FLAGS = ${CMAKE_EXE_LINKER_FLAGS}")
+1 −1
Original line number Diff line number Diff line
@@ -13,7 +13,7 @@ RUN apt-get update && apt-get install -y \
    python3-gdal

RUN rm -rf /app/triton/build && mkdir /app/triton/build
RUN cd /app/triton/build && cmake .. -DMACHINE=Linux -DBUILD_TESTS=ON -DBUILD_TOOLS=ON -DHAVE_GDAL=ON
RUN cd /app/triton/build && cmake .. -DMACHINE=Linux
RUN cd /app/triton/build && ./triton_build.sh
RUN for script in run build clean ctest; do \
      echo '#!/bin/bash' > /project/triton_${script}.sh && \
+7 −4
Original line number Diff line number Diff line
@@ -11,7 +11,7 @@ SPHINX_BUILD_DIR = $(DOCS_DIR)/_build/html

# Python executable for Sphinx (assuming virtual environment in .venv_triton)
# Adjust if your Python setup is different
PYTHON = $(shell which python)
PYTHON = $(shell command -v python3 || command -v python)  
VENV_PYTHON = $(CURDIR)/.venv_triton/bin/python

# Ensure the virtual environment's python is used if it exists
@@ -52,10 +52,13 @@ sphinx: $(SPHINX_BUILD_DIR)/index.html
doxygen: $(DOXYGEN_XML_DIR)/index.xml

docker_build:
	docker build -t triton-mpich:v3 .
	docker build -t triton:v1 .

docker_run:
	docker run --rm triton-mpich:v3 triton_run.sh
	mkdir -p output && \
	docker run --rm \
		-v "${PWD}/output:/app/triton/build/output" \
		triton:v1 triton_run.sh ./input/paraboloid/paraboloid.cfg

setup_pyenv:
	@echo ""
@@ -63,7 +66,7 @@ setup_pyenv:
	@echo ""
	@echo "python -m venv .venv_triton"
	@echo "source .venv_triton/bin/activate"
	@echo "pip install sphinx breathe exhale sphinx_rtd_theme"
	@echo "pip install sphinx breathe exhale sphinx_rtd_theme sphinx_design"
	@echo ""
	@echo "You also need to install Doxygen, for example: sudo apt install doxygen"

+37 −22
Original line number Diff line number Diff line
# TRITON Two-dimensional Runoff Inundation Toolkit for Operational Needs
# TRITON: Two-dimensional Runoff Inundation Toolkit for Operational Needs

TRITON is an open-source, high-performance software framework for 2D flood simulation. Its core is a computationally efficient, physics-based hydraulic model that operates on a regular, structured grid and solves the full 2D shallow water equations.

## Features

- **Cross-Platform & HPC Ready** Runs on single or multiple CPUs (OpenMP+MPI) and supports GPU acceleration (CUDA+MPI) for maximum computational efficiency.
- **Cross-platform and HPC ready**: Performance-portable via Kokkos. Runs on single or multiple CPUs (OpenMP + MPI) and supports GPU acceleration with Kokkos and MPI.
- **Flexible Forcing & Inputs** – Uses topographical data (e.g., DEM, LIDAR) on a uniform Cartesian grid and supports streamflow hydrographs, gridded runoff, or both as hydrological forcing.
- **Rich Output Options** – Produces water depth, 2D velocity maps, and unit discharge data, plus time series outputs at user-defined points and intervals.
- **Linux/Unix Native** – Built for Linux/Unix systems with input/output in ASCII or binary formats, along with tools for easy format conversion.
- **SI Units Standard** – Operates using the International System of Units (SI); users must convert to U.S. customary units if needed.
- **Rich Output Options** – Produces water depth maps, 2D velocity maps, and unit discharge data, plus time series outputs at user-defined points and intervals.
- **Linux/Unix Native** – Built for Linux/Unix systems with input/output in ascii, binary and geotiff format.
- **SI Units Standard** – Operates using the International System of Units (SI).

![Simulation Output](doc/_static/TRITON_output_example.jpg)

@@ -18,7 +18,6 @@ TRITON is an open-source, high-performance software framework for 2D flood simul
triton/
├── doc/           # User guides, API references, and technical documentation
├── src/           # Core simulation source code
├── tools/         # Tools for TRITON
├── external/      # Kokkos Git submodule
├── input/         # Sample simulation input data files
├── test/          # Regression test suite based on CTest
@@ -29,13 +28,15 @@ triton/

## Installation

TRITON can be built from source or run using a pre-built container.
TRITON can be built from source or run using a container.

### **Prerequisites**
- CMake ≥ 3.16
- C++17 or later compiler (GCC, Clang, or Intel)  
- [MPI](https://www.mpi-forum.org/) (for distributed runs)  
- Optional: CUDA, HIP, or SYCL for GPU acceleration  
CMake 3.16 or newer
C++17 compatible compiler
MPI libraries with C++ bindings
Optional: CUDA, HIP, or SYCL for GPU acceleration
Optional: GDAL for GeoTIFF support
Kokkos is included as a Git submodule. No system install is required.

### **Build Instructions**
```bash
@@ -44,7 +45,11 @@ cd triton
mkdir build && cd build
cmake ..
./triton_build.sh


```
On success, triton.exe is created in the build directory.
For more details on cmake configurationa and compiler flags, please see the documentation. 

### **Using Docker (Optional)**
```bash
@@ -56,9 +61,19 @@ docker pull grnydawn/triton-mpich

## Running a Simulation

Run a sample case using:
Run a sample case from the build directory using:
```bash
./trtion_run.sh
cd build

# run a pre-selected example case (Allatoona)
./triton_run.sh

# run Circular Dambreak
./triton_run.sh ./input/circular/circular_dambreak.cfg

# run Paraboloid
./triton_run.sh ./input/paraboloid/paraboloid.cfg

```

Simulation results will be stored in `output/`.
@@ -68,11 +83,11 @@ Simulation results will be stored in `output/`.
- [User Guide:T.B.D.]
- [API ReferenceT.B.D.]

Full documentation is also available at: [Triton Documentation](https://triton.ornl.gov/documentation)
Full documentation is also available at: [TRITON Documentation](https://triton.ornl.gov/documentation)

## Testing

Triton includes regression tests:
TRITON includes regression tests:
```bash
./triton_ctest.sh
```
@@ -90,16 +105,16 @@ We welcome contributions!

## License

Triton is released under the **3-Clause BSD License**. See [LICENSE](LICENSE) for more details.
TRITON is released under the **3-Clause BSD License**. See [LICENSE](LICENSE) for more details.

## Acknowledgments

Triton was developed by researchers and engineers at **[Your Organization]** with support from:
- [Funding Agency / Grant Info]
- [Partner Institutions]
Development of TRITON is supported by the U.S. Air Force Numerical Weather Modeling Program. TRITON used resources of the Oak Ridge Leadership Computing Facility at Oak Ridge National Laboratory, a U.S. Department of Energy user facility. Development is led by Oak Ridge National Laboratory, the University of Zaragoza (Spain), and Tennessee Technological University (Cookeville, TN).


## Contact

For questions, bug reports, or feature requests:
- Open an issue via GitLab: [Issues Page](https://code.ornl.gov/hydro/triton/-/issues)  
- Email: T.B.D.
Questions, bug reports, or feature requests:
- Open a GitLab issue: <https://code.ornl.gov/hydro/triton/-/issues>
- Submit a support ticket: <https://triton.ornl.gov/contact/>
- Email: [Mario Morales Hernandez](mailto:mmorales@unizar.es), [Sudershan Gangrade](mailto:gangrades@ornl.gov)
Loading