updated README and doc

# 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)

## 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

- [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

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

## 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/`.

- [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

```

## 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)

Running TRITON using Docker

==================================

Docker images can be run on most systems, including Linux, macOS, and Windows. To do so, the host machine must have Docker Engine (Docker) installed. This section provides step-by-step instructions on running TRITON using Docker for all supported operating systems. 

TRITON Docker image can be downloaded from Docker Hub using the following command:

.. code-block:: bash

      Basin- and watershed-scale flood simulations.

   .. grid-item-card:: Forecasting

   .. grid-item-card:: Inundation forecasting

      :text-align: center

      .. image:: _static/triton_5.png

      Short-term flood forecasts for emergency response.

   .. grid-item-card:: Probabilistic mapping

   .. grid-item-card:: Probabilistic inundation mapping

      :text-align: center

      .. image:: _static/probabilistic.png

         :alt: Probabilistic flood hazard mapping

         :class: doc-hero

      Ensemble-based hazard and uncertainty maps.

      Ensemble-based hazard maps.

   .. grid-item-card:: Dam-break scenarios

   .. grid-item-card:: Dam-break simulations

      :text-align: center

      .. image:: _static/taum_sauk.png

         :alt: Dam break flood wave

         :class: doc-hero

      High-resolution dam-break and levee-breach simulations.

      High-resolution dam-break simulations.

Project Website

.. toctree::

   :maxdepth: 1

   :caption: Configure and Run

   :caption: Configure

   :hidden:

   simulation_setup

2.  **Run CMake:**

TRITON uses CMake as its build system. User can control TRITON build and execution through providing command-line arguments to `cmake`. Several examples are shown below:

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:

.. code-block:: bash

   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

    cd build

    ./triton_build.sh

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

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

Running TRITON

--------------

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.

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.

.. code-block:: bash