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 Hardware Support 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)

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 Mesh Preparation and Cocoa Tools (Python) 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:

The mesh is small. A GPU needs a large problem to hide latency.
The time step is smaller than the CFL condition requires.
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:

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 Performance for the benchmark results.

Troubleshooting

The simulation crashes immediately

Check:

Mesh file path is correct
All required configuration options are specified
Sufficient GPU memory is available

The solver doesn’t converge

Try:

Reducing time step
Checking mesh quality
Verifying boundary conditions
Increasing solver iterations

Results differ from ADCIRC

Check that both runs use:

Same mesh and bathymetry
Same time step and parameters
Same tidal constituents and phases
Consistent coordinate systems
Same wetting rule: set physics.wetting_velocity to match the fort.15 &wetDryControl namelist (see 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