.. 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 coastal ocean circulation model built on the numerical formulation of
the ADCIRC model. It solves the 2D depth-integrated shallow water equations on
unstructured triangular finite element meshes, using Trilinos for the explicit
and preconditioned iterative solvers and Kokkos for host and device execution:
one source builds for multi-core CPUs and for NVIDIA and AMD GPUs (see
:ref:`supported-hardware` and :doc:`user_guide/performance`).

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/baroclinic_coupling
   user_guide/elemental_slope_limiter
   user_guide/global_simulations
   user_guide/parallel_execution
   user_guide/checkpoint
   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