==========================
Frequently Asked Questions
==========================

General Questions
-----------------

What is Cocoa?
^^^^^^^^^^^^^^

Cocoa (Coastal and Ocean Circulation on Accelerators) solves the 2D shallow
water equations using finite element methods. It is designed for high
performance on modern GPU and CPU architectures.

How does Cocoa relate to ADCIRC?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cocoa implements the same numerical formulation as ADCIRC (the Generalized
Wave Continuity Equation) but is written from scratch in modern C++ with
GPU support. It aims for numerical compatibility with ADCIRC while achieving
better performance on GPUs.

What hardware does Cocoa support?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cocoa supports:

- NVIDIA GPUs (via CUDA)
- AMD GPUs (via HIP)
- Multi-core CPUs (via OpenMP)
- Serial execution (for debugging)

Installation Questions
----------------------

What are the minimum requirements?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- C++20 compiler (GCC 11+, Clang 14+)
- CMake 3.16+
- Trilinos 17+ (includes Kokkos 5.0+, Tpetra, Belos, Ifpack2)

Do I need a GPU to run Cocoa?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

No. Cocoa can run on CPUs using OpenMP. However, the best performance
is achieved on GPUs.

Usage Questions
---------------

Can I use my existing ADCIRC meshes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cocoa uses NetCDF UGRID format meshes. ADCIRC fort.14 meshes must first be
converted to NetCDF format. See :doc:`user_guide/mesh_preparation` for details.

How do I convert ADCIRC input files to Cocoa format?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See the :doc:`changelog` for a migration guide. The main difference is that
Cocoa uses YAML configuration files instead of fort.15.

Performance Questions
---------------------

Why is my simulation slow?
^^^^^^^^^^^^^^^^^^^^^^^^^^

Common causes:

1. **Data transfers**: Ensure data stays on the GPU
2. **Small mesh**: GPUs need large problems to hide latency
3. **Time step too small**: Check CFL condition
4. **Solver iterations**: Check preconditioner effectiveness

How do I profile Cocoa?
^^^^^^^^^^^^^^^^^^^^^^^

For NVIDIA GPUs:

.. code-block:: bash

   nsys profile ./cocoa -i config.yaml
   ncu --set full ./cocoa -i config.yaml

How much speedup can I expect?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Speedup depends on problem size and hardware. On a 1.5M-node mesh, a single
NVIDIA V100 GPU is 2.9--6.3x faster than ADCIRC running on 128 CPU cores
(implicit and explicit solvers, respectively), and newer GPUs widen the
gap further. See :doc:`user_guide/performance` for detailed benchmark
results.

Troubleshooting
---------------

The simulation crashes immediately
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Check:

1. Mesh file path is correct
2. All required configuration options are specified
3. Sufficient GPU memory is available

The solver doesn't converge
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Try:

1. Reducing time step
2. Checking mesh quality
3. Verifying boundary conditions
4. Increasing solver iterations

Results differ from ADCIRC
^^^^^^^^^^^^^^^^^^^^^^^^^^

Ensure:

1. Same mesh and bathymetry
2. Identical time step and parameters
3. Same tidal constituents and phases
4. Consistent coordinate systems

Still Having Issues?
--------------------

- Check the GitHub issues for known problems
- Open a new issue with a minimal reproducible example
- Include version numbers and hardware information