Cocoa
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
Docker Container
Image Families and Naming
Supported Architectures
Running the Container
Selecting a Variant
Running a Simulation
Converting ADCIRC Meshes
Mounting Data Volumes
Non-Interactive Execution
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
Index
Index
v: 0.2.0b0
Versions
0.2.0b0
0.1.0
main (dev)