.. Cocoa documentation master file

====================================================
Cocoa: Coastal and Ocean Circulation on Accelerators
====================================================

.. image:: https://img.shields.io/badge/C++-20-blue.svg
   :alt: C++ Standard

Cocoa is a high-performance coastal ocean modeling system designed for modern GPU
architectures. Built on the proven numerical methods of the ADCIRC model, Cocoa
leverages Kokkos and Trilinos to achieve performance portability across diverse
computing platforms.

Key Features
------------

- **GPU Acceleration**: Native support for NVIDIA and AMD GPUs (see :doc:`user_guide/performance`)
- **Performance Portability**: Single codebase for CPUs, GPUs, and accelerators
- **Scalable Solvers**: Trilinos-based explicit and iterative solvers with preconditioning
- **Unstructured Meshes**: Triangular finite elements for complex coastal geometries

Quick Start
-----------

.. code-block:: bash

   # Build Cocoa
   mkdir build && cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release -DNETCDF_DIR=$(path) -DTrilinos_DIR=$(path)
   make -j8

   # Run a simulation
   ./cocoa -i simulation.yaml

Documentation
-------------

.. toctree::
   :maxdepth: 2
   :caption: Getting Started

   getting_started/installation
   getting_started/container
   getting_started/quick_start
   getting_started/configuration

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   user_guide/overview
   user_guide/mesh_preparation
   user_guide/boundary_conditions
   user_guide/tidal_forcing
   user_guide/meteorological_forcing
   user_guide/global_simulations
   user_guide/parallel_execution
   user_guide/hot_start
   user_guide/output_files
   user_guide/performance
   user_guide/test_cases

.. toctree::
   :maxdepth: 2
   :caption: Theory

   theory/governing_equations
   theory/coordinate_systems
   theory/gwce
   theory/momentum
   theory/meteorological_forcing
   theory/astronomical_tides
   theory/numerical_methods
   theory/wetdry

.. toctree::
   :maxdepth: 2
   :caption: Developer Guide

   developer/architecture
   developer/extending_model
   developer/trilinos_integration
   developer/benchmarking
   developer/testing
   developer/contributing

.. toctree::
   :maxdepth: 1
   :caption: Additional Resources

   changelog
   faq
   references

Indices and Tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Authors and Acknowledgments
---------------------------

**Lead Developer:**

- Zach Cobell

**Advisory:**

- Richard A. Luettich, Jr., University of North Carolina at Chapel Hill
- Joannes J. Westerink, University of Notre Dame
- Shintaro Bunya, University of North Carolina at Chapel Hill