========================== Frequently Asked Questions ========================== General Questions ----------------- What is Cocoa? ^^^^^^^^^^^^^^ Cocoa (Coastal and Ocean Circulation on Accelerators) solves the 2D shallow water equations with finite elements on GPUs and multi-core CPUs. How does Cocoa relate to ADCIRC? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Cocoa implements ADCIRC's numerical formulation (the Generalized Wave Continuity Equation) in new C++ code that runs on GPUs. Its results are meant to match ADCIRC's. What hardware does Cocoa support? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ NVIDIA GPUs, AMD GPUs, multi-core CPUs, and a serial backend for debugging. See :ref:`supported-hardware` for the execution backend used by each. Installation Questions ---------------------- What are the minimum requirements? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - C++20 compiler (GCC 11+, Clang 14+) - CMake 3.23+ - Trilinos 17+ (includes Kokkos 5.0+, Tpetra, Belos, Ifpack2) :doc:`getting_started/installation` carries the full per-compiler table, including the CUDA, SYCL and ROCm host-compiler minimums. Do I need a GPU to run Cocoa? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ No. Cocoa runs on CPUs through OpenMP, but it is fastest on GPUs. Usage Questions --------------- Can I use my existing ADCIRC meshes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Cocoa uses NetCDF UGRID format meshes. ADCIRC fort.14 meshes (with their fort.13 nodal attributes and fort.24 SAL file) must first be converted with ``cocoa-mesh-tools from_adcirc``, part of the ``cocoa-tools`` package. See :doc:`user_guide/mesh_preparation` and :doc:`user_guide/cocoa_tools` 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. The mesh is small. A GPU needs a large problem to hide latency. 2. The time step is smaller than the CFL condition requires. 3. The linear solver takes many iterations. Watch the ``Iter`` column of the progress table and the ``numeric.linear_solver`` settings. 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 was 2.9--6.3x faster than ADCIRC running on 128 CPU cores (implicit and explicit solvers, respectively) when measured in June 2026, and newer GPUs widen the gap. See :doc:`user_guide/performance` for the 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ Check that both runs use: 1. Same mesh and bathymetry 2. Same time step and parameters 3. Same tidal constituents and phases 4. Consistent coordinate systems 5. Same wetting rule: set ``physics.wetting_velocity`` to match the fort.15 ``&wetDryControl`` namelist (see :ref:`Wetting Velocity `) 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