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 Mesh Preparation for details.

How do I convert ADCIRC input files to Cocoa format?

See the 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:

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