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
      • Thrust Stream-Compaction Fast Path
      • Compile
      • Install
    • Verifying the Installation
  • Containers
    • Image Families and Naming
    • Supported Architectures
    • Running the Container
    • Selecting a Variant
    • Running a Simulation
    • Converting ADCIRC Meshes
    • 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
    • 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
      • 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

User Guide

  • Overview
    • Model Capabilities
    • Physical Processes
      • Hydrodynamics
      • Forcing Mechanisms
      • Bottom Friction
      • Wetting and Drying
    • Computational Features
      • GPU Acceleration
      • Scalable 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
      • Drag Law
      • Scale Factors
    • File Format Details
      • CF-Compliant NetCDF
      • OWI ASCII
      • OWI NetCDF
    • Combining Meteorological and Tidal Forcing
    • Wind Reduction
      • Directional Roughness Reduction
      • Canopy Coefficient
      • Processing Order
    • Diagnostics
    • Complete Example
  • 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
    • 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 Nesting
    • 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
    • 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
    • Getting Started
    • Development Environment
      • Prerequisites
      • Setup
    • Code Style
      • C++ Style
      • Naming Conventions
    • Commit Messages
    • Pull Request Process
    • Testing Requirements
    • Documentation
    • Code Review
    • License
    • Questions?

Additional Resources

  • Changelog
    • [Unreleased]
      • Added
      • Changed
      • Deprecated
      • Removed
      • Fixed
      • Security
    • 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
    • Shallow Water Equations
    • Wetting and Drying
    • Software Documentation
Cocoa
  • Search

© Copyright 2026, Zach Cobell.

Built with Sphinx using a theme provided by Read the Docs.
v: main
Versions
0.2.0b0
0.1.0
main (dev)