Changelog

All notable changes to Cocoa will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.3.0] - 2026-07-20

Added

  • GAHM parametric hurricane vortex forcing (cocoa_vortex), with ATCF b-deck parsing and missing-central-pressure estimation.

  • GRIB2 meteorological forcing via ecCodes (cocoa_ENABLE_GRIB).

  • Multi-source meteorological composition: self-contained domains: entries, per-source wind reduction, and per-source activation ramps.

  • Full OWI NWS13 support.

  • Grouped mesh NetCDF format with a content-based fingerprint (mesh_id); utils/cocoa_mesh_tools.py converts and checksums.

  • Configuration schema validation on valijson (JSON Schema draft-07), with the schema embedded in the binary and reproduced in the user guide.

  • External YAML inclusion at designated configuration nodes.

  • Checkpoint/restart rework: timestamped single files, format version 3.

  • Google Benchmark suite with scaling analysis, compile-gated in CI.

  • New dependencies: valijson and CLI11 (CPM-fetched); ecCodes (optional, GRIB builds only).

Changed

  • Asynchronous I/O is now always on. Output is delivered on a background writer thread and meteorological input is pre-read ahead of need, overlapping file access with computation in every run. MPI is initialized with MPI_THREAD_FUNNELED to support this; a run aborts at startup if the MPI build cannot provide it.

  • Command-line parsing moved to CLI11: --option=value spellings now work, malformed values fail loudly, and --help/--version follow standard Unix formatting.

  • Boolean configuration values must be true/false; the YAML 1.1 spellings are rejected.

  • CF NetCDF pressure units are read from the file and required.

  • “Hot start” is now “checkpoint” throughout the configuration and docs.

Performance

  • Explicit solver per-step host stalls eliminated, worth roughly 13-15% throughput on a 1.57M-node hurricane case with meteorology; momentum nodal assembly reduced from three sweeps to one; wet/dry list compaction with no per-step device allocation; cached MPI ghost staging and device-direct boundary forcing scatter.

Deprecated

  • N/A

Removed

  • The --asyncio command-line flag and its modes. Asynchronous output is now unconditional, so there is no mode to select. The dedicated-MPI-I/O-rank mode (--asyncio=mpi) has been removed; all ranks now participate in computation.

  • The A/B checkpoint file pair and the FNV-1a mesh topology checksum, superseded by timestamped checkpoints and mesh_id.

Fixed

  • MPI runs fail fast on rank-local errors instead of hanging peers until walltime.

  • Land-boundary normals at multi-string junction nodes average the per-string normals (a documented deviation from ADCIRC’s last-wins).

  • Binary-inexact time steps (e.g. 0.1 s) no longer drop the final step.

Security

  • N/A

Migration Guide

Migrating from ADCIRC

Converting Mesh Files

Cocoa uses NetCDF format for mesh files instead of ADCIRC’s fort.14/fort.13 format. A conversion script is provided in the utils directory:

python utils/cocoa_mesh_tools.py from_adcirc \
    --mesh fort.14 \
    --attributes fort.13 \
    --output mesh.nc

Arguments:

  • --mesh: ADCIRC mesh file (fort.14) - required

  • --attributes: ADCIRC nodal attributes file (fort.13) - optional

  • --output: Output NetCDF file path - required

Configuration Files

Cocoa uses YAML configuration files instead of ADCIRC’s fort.15 format. Key differences:

ADCIRC Parameter

Cocoa Equivalent

DT

simulation.time_step

TAU0

physics.tau0

STATIM

simulation.start_time

RNDAY

simulation.end_time

Note

In ADCIRC, a negative TAU0 value triggers spatially-varying computation. In Cocoa, tau0 must always be a positive constant value.

Example conversion:

ADCIRC fort.15:

DT = 2.0
TAU0 = 0.005
RNDAY = 1.0

Cocoa YAML:

simulation:
  time_step: 2s
  start_time: 2025-01-01
  end_time: 2025-01-02

physics:
  tau0: 0.005