Cocoa Logo

Getting Started

  • Installation
    • Prerequisites
      • Compilers
      • Build System
      • Required Libraries
      • Automatically Fetched Dependencies
      • Optional Dependencies
    • Building from Source
      • Clone the Repository
      • Configure with CMake
      • CMake Options
      • Floating-Point Precision
      • Stream Compaction
      • Compile
      • Install
    • Verifying the Installation
  • Containers
    • Image Families and Naming
    • Supported Architectures
    • Running the Container
    • Selecting a Variant
    • Running a Simulation
    • Converting ADCIRC Meshes
    • Plotting Results
    • Mounting Data Volumes
    • Non-Interactive Execution
    • Running with Singularity / Apptainer
    • Building the Container
  • Quick Start
    • Command-Line Usage
    • Simulation Flow
    • Running a Simulation
      • Examples
    • Example Configuration
    • Expected Output
    • Next Steps
  • Configuration
    • Configuration File Structure
    • Validation
    • Mesh Section
      • Coordinate Rotation (Global Meshes)
    • Simulation Section
    • Initial Conditions Section
    • Physics Section
      • Spatially-Varying Parameters
        • Wind Reduction
      • Wetting and Drying Algorithm
    • Numeric Section
      • Linear Solver Configuration
    • Forcing Section
      • Ramp Configuration
      • Meteorological Forcing
      • External File Inclusion
      • Flow Boundary Forcing
      • Tidal Potential Forcing
      • Tidal Boundary Forcing
      • Self-Attraction and Loading (SAL)
    • Output Section
    • Diagnostics Section
    • Checkpoint Section
    • Complete Example
    • Duration Syntax
    • Unit Conventions
    • Environment Variables
    • Schema Reference

User Guide

  • Overview
    • Physical Processes
    • Computational Features
      • Hardware Support
      • Solvers
  • Mesh Preparation
    • Mesh Requirements
    • Mesh Format
      • Dimensions
      • Required Variables
    • Mesh Identification
      • Format
      • Order independence
      • Where it appears
      • Computing and verifying the id
    • Nodal Attributes
      • Available Nodal Attributes
        • Manning’s n (mannings_n_at_sea_floor)
        • Tau0 (primitive_weighting_in_continuity_equation)
        • Surface Submergence State (surface_submergence_state)
        • Directional Effective Roughness (surface_directional_effective_roughness_length)
        • Surface Canopy Coefficient (surface_canopy_coefficient)
    • Converting from ADCIRC Format
      • Script Location
      • Usage
      • What Gets Converted
    • Adding Nodal Attributes
    • Mesh Generation Tools
    • Complete NetCDF Format Reference
  • Boundary Conditions
    • Boundary Types
      • Open Ocean Boundaries
      • Land Boundaries
      • Flow Boundaries
        • Configuration
      • Weir Boundaries
        • Weir Configuration
  • Tidal Forcing
    • Astronomical Tide Potential
      • Configuration
    • Self-Attraction and Loading (SAL)
      • Preparing SAL Data
      • Configuration
        • Auto Mode
        • Manual Mode
    • Harmonic Constituents
      • Common Tidal Constituents
      • Boundary Configuration
      • Spatially Varying Amplitudes
    • Ramp-up Period
  • Meteorological Forcing
    • Overview
    • Supported File Formats
    • Configuration
      • Enabling Meteorological Forcing
      • CF NetCDF Format
      • OWI ASCII Format
      • OWI NetCDF Format
      • GRIB2 Format
      • Composing Multiple Sources
        • Per-entry wind_reduction
        • Domains with a vortex
        • Activation Ramp
        • The full stack: a worked storm configuration
      • Domain Time Windows
      • Drag Law
      • Scale Factors
    • File Format Details
      • CF-Compliant NetCDF
      • OWI ASCII
      • OWI NetCDF
    • Parametric Vortex (GAHM)
      • Theory
        • Holland profile and its limitation
        • Gradient-wind generalization
        • Per-quadrant isotach fit
        • Azimuthal composition
        • Translation asymmetry
        • From theory to code
      • Vortex Configuration
        • Vortex-only
        • Composed with a gridded background
        • Multiple storms
        • Blend ring
      • Physics conventions
        • Ten-minute wind
        • Southern Hemisphere
        • Solve-once, interpolate-packs
      • Track input (ATCF)
        • Best-track files
        • Weak and incomplete tracks
        • Forecast tracks
        • Estimating a missing central pressure
      • Verification workflow
    • Ice Concentration
      • Lupkes drag blend
      • Conventions
        • Fraction, not percent
        • Sentinel Semantics
        • Per-Source Explicit Presence
        • The Ramp Deliberately Does Not Apply
      • Ice Configuration
        • Validator Failure Modes
      • Output Variable
      • Testing
      • Deviations from the Reference Implementation
    • Combining Meteorological and Tidal Forcing
    • Wind Reduction
      • Directional Roughness Reduction
      • Canopy Coefficient
      • Per-source application
      • Processing Order
    • Diagnostics
    • Complete Example
  • Baroclinic Coupling
    • Overview
    • Theory
      • Baroclinic pressure gradient
      • Free-surface correction
      • Internal-tide wave drag
      • De-tiding
      • Dispersion as friction
      • Positive-semidefinite clamp
    • Preprocessor pipeline
    • Configuration
    • Nodal forcing file
    • Regression checks
    • Checkpoint format
  • Elemental Slope Limiter
    • Overview
      • When to use it
    • Theory
      • Elemental elevation gradient
      • Activation rule
      • Patch-average replacement
      • When it runs in the time step
    • Configuration
      • Constant threshold
      • Per-node thresholds from the mesh
      • Disabled (default)
    • Sentinels
    • Reporting
    • Deviations from ADCIRC
      • Stateless per-step activation
      • Dynamic area normalizer
      • Finite-amplitude assumption
      • No per-node output or hotstart persistence
      • Condensed-node (VEW) skip omitted
    • See also
  • Global Simulations
    • Overview
    • When to Use Coordinate Rotation
    • Configuration
      • Basic Global Mesh Setup
      • Global Mesh with Coordinate Rotation
      • Choosing a Pole Location
    • Understanding Rotation Effects
      • Coordinates
      • Coriolis Parameter
      • Tidal Potential
      • Velocities
    • Projection Selection
    • Complete Example
    • See Also
  • Parallel Execution
    • Execution Modes Overview
    • Serial Execution
    • OpenMP Parallelism
    • GPU Execution
    • MPI Distributed Parallelism
      • Requirements
      • Basic MPI Execution
    • Mesh Partitioning
      • Partition File Format
      • Automatic Partition Naming
    • Creating Partition Files
      • Pre-computing Partitions
      • Partition Caching
    • Example Partition Visualization
    • Internal Weir Pairs Across Partitions
    • Command Line Reference
      • Cocoa Options
      • Kokkos Options
  • Checkpoint / Restart
    • Overview
    • Configuration
      • Writing Checkpoints
      • Restarting from a Checkpoint
    • Workflow
    • Checkpoint Contents
    • Considerations
  • Output Files
    • Output Configuration
    • Compression
    • Variable Selection
    • Output Variables
      • Time-Series Variables
      • Peak Variables
    • Output Mode
      • Split Mode (Default)
      • Combined Mode
    • NetCDF File Structure
    • Reading Output Files
      • Python (xarray)
      • Python (netCDF4)
  • Performance
    • Benchmark Configuration
    • Implicit Solver Results
    • Explicit Solver Results
    • CPU-MPI Scaling
  • Test Cases
    • Channel with Flow
    • Channel with Sommerfeld Radiation Boundary and Specified Flow
    • Western North Atlantic (WNAT)
    • Global Ocean

Theory

  • Governing Equations
    • Derivation
    • Conservation Laws
      • Mass Conservation
      • Momentum
    • Term Descriptions
    • Bottom Friction
      • Internal Tide Friction
    • Coriolis Parameter
  • Coordinate Systems
    • Overview
    • Available Projections
      • Equidistant Cylindrical (Default)
      • Equal Area
      • Mercator
      • Miller Cylindrical
      • Gall Stereographic
    • Scale Factor System
      • General Scale Factor Formulas
    • Application in Equations
      • GWCE Stiffness Matrix
      • GWCE Mass Matrix
      • Momentum Equations
    • Configuration
    • Global Mesh Support
      • Prime Meridian Crossing
      • Coordinate Rotation
    • Implementation Files
  • Generalized Wave Continuity Equation (GWCE)
    • Motivation
    • GWCE Derivation
    • Momentum Terms (J Vector)
    • Discretized J Vector Assembly
    • GWCE Parameter (\(\tau_0\))
    • Coordinate Systems
    • Finite Element Discretization
    • Time Discretization
    • Wet/Dry Integration
    • Boundary Conditions
    • Lumped vs Consistent Mass Matrix
    • Implementation Files
  • Momentum Equations
    • Governing Equations
    • Coordinate Systems
    • Time Discretization
    • Per-Node 2x2 System
    • Bottom Friction (TKM Tensor)
    • RHS Forcing Terms (Continuous)
    • Discretized RHS Assembly
    • Land Boundary Conditions
    • Flux Computation
    • Implementation Files
  • Meteorological Forcing
    • Wind Stress
      • Surface Wind Drag
      • Wind Stress Limiter
      • Application in the Momentum Equations
      • Application in the GWCE
    • Atmospheric Pressure Gradient
      • Application in the GWCE
      • Application in the Momentum Equations
    • Meteorological Ramp
    • Temporal Interpolation
    • Spatial Interpolation
      • Multi-Domain Composition
      • Cadence Interpolation onto the Union Time Axis
      • Activation Window Fade
    • Wind Reduction
      • Directional Roughness Reduction
      • Canopy Coefficient
    • Physical Constants
    • Implementation Files
  • Astronomical Tides
    • Physical Basis
      • Degree-2 Equilibrium Tide
      • Higher-Order Terms
    • Jean Meeus Algorithms
      • Julian Day and Time
      • Moon Position (Chapter 47)
      • Sun Position (Chapter 25)
      • Sidereal Time (Chapter 12)
      • Nutation and Obliquity (Chapter 22)
    • Coordinate Transformations
      • Ecliptic to Equatorial
      • Hour Angle and Zenith Angle
    • Earth Elasticity
    • Implementation Details
    • References
  • Numerical Methods
    • Spatial Discretization
      • Finite Element Mesh
      • Shape Functions
      • Mass Matrix
    • Temporal Discretization
      • Time Integration Scheme
    • Linear Solver
      • Assembly Pattern: Scatter-to-Gather
      • System Assembly
      • Iterative Solver
      • Preconditioning
      • Convergence Criteria
    • Numerical Stability
      • CFL Condition
      • Numerical Diffusion
    • Floating-Point Precision
  • Wetting and Drying
    • Algorithm Overview
    • Node Status
    • Element Status
    • Depth Thresholds
    • Phase Details
      • Nodal Drying (D1)
      • Nodal Wetting (W1)
      • Elemental Drying (DE1)
      • Active Element Count
      • Landlocked Drying (D2)
    • Slope Limiter (ALPHA)
    • Data Structures
      • WetDryData
      • Node-to-Element Connectivity
    • Implementation Files

Developer Guide

  • Architecture
    • High-Level Overview
      • Source Library Dependencies
      • Data Container Hierarchy
    • GWCE Solver Selection
    • Directory Structure
    • Namespace Organization
    • Meteorological Forcing Pipeline
      • Pipeline Stages
      • Ring Buffer
      • Meteorological Input Distribution
  • Extending the Model
    • Adding a Nodal Attribute
      • Step 1: Register the Enum
      • Step 2: Initialize the Attribute
      • Step 3: Access in Kernels
      • Step 4: Add Configuration
      • Step 5: Update Tests
      • Vector (Multi-Component) Attributes
      • Optional Attributes
    • Adding a Physics Contribution
      • Architecture
        • Concepts
      • Step-by-Step Guide
        • Step 1: Data Storage
        • Step 2: GWCE Contribution
        • Step 3: Momentum Contribution
        • Step 4: Wire Into GWCE Kernel
        • Step 5: Wire Into Momentum Kernel
        • Step 6: Populate the Data
        • Step 7: Ghost Exchange (if needed)
        • Step 8: Configuration and Build
    • Reference: Existing Contributions
    • Adding a Meteorological File Format
      • Architecture Overview
      • Step 1: Add the Format Enum
      • Step 2: Create the Reader Class
      • Step 3: Register in the Factory
      • Step 4: Add Configuration Parsing
      • Step 5: Update CMakeLists.txt
      • Key Data Structures
      • Reference: Existing Readers
  • Trilinos Integration
    • Trilinos Type Aliases
      • LinearAlgebraTypes
      • SolverTypes
    • GWCE Matrix Assembly
      • Graph Construction
      • Matrix Assembly Pattern
      • Boundary Condition Application
    • Linear Solver Configuration
      • Solver Configuration
      • Residual Scaling Options
      • Solver Setup
      • Jacobi Preconditioner
      • Solving
    • Vector Operations
      • Built-in Vector Operations
    • Elevation Penalty Computation
    • Implementation Files
  • Benchmarking
    • Building
    • Running Benchmarks
    • Available Benchmarks
    • Scaling Analysis
    • Benchmark Mesh Generation
    • Regression Tracking
    • Adding New Benchmarks
    • Source Organization
  • Testing
    • Test Framework
    • Building and Running Tests
    • Test Files
    • Test Data
    • Catch2 Assertions
    • Writing New Tests
    • Compile-Time Tests
    • Integration Tests
    • Debugging Failed Tests
  • Contributing
    • Contribution Policy
    • Building and Testing
    • Where to Start

Additional Resources

  • Changelog
    • [0.4.0] - 2026-08-15
      • Added
      • Changed
      • Fixed
      • Performance
    • [0.3.1] - 2026-07-27
      • Changed
      • Fixed
    • [0.3.0] - 2026-07-20
      • Added
      • Changed
      • Performance
      • Removed
      • Fixed
    • [0.2.0b0] - 2026-06-29
      • Added
      • Changed
      • Removed
      • Fixed
      • Performance
    • Migration Guide
      • Migrating from ADCIRC
        • Converting Mesh Files
        • Configuration Files
  • Frequently Asked Questions
    • General Questions
      • What is Cocoa?
      • How does Cocoa relate to ADCIRC?
      • What hardware does Cocoa support?
    • Installation Questions
      • What are the minimum requirements?
      • Do I need a GPU to run Cocoa?
    • Usage Questions
      • Can I use my existing ADCIRC meshes?
      • How do I convert ADCIRC input files to Cocoa format?
    • Performance Questions
      • Why is my simulation slow?
      • How do I profile Cocoa?
      • How much speedup can I expect?
    • Troubleshooting
      • The simulation crashes immediately
      • The solver doesn’t converge
      • Results differ from ADCIRC
    • Still Having Issues?
  • References
    • ADCIRC and GWCE
    • Finite Element Methods
    • Kokkos
    • Trilinos
    • Wind Stress and Atmospheric Forcing
    • Sea Ice Drag
    • Shallow Water Equations
    • Wetting and Drying
    • Parametric Tropical Cyclone Vortex
    • Tropical Cyclone Wind-Pressure Relationships
    • Baroclinic Coupling
    • Software Documentation
Cocoa
  • Search

© Copyright 2026, Zach Cobell.

Built with Sphinx using a theme provided by Read the Docs.
v: 0.4.0
Versions
0.4.0
0.3.1
0.3.0
main (dev)