=========
Changelog
=========

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

The format is based on `Keep a Changelog <https://keepachangelog.com/>`_,
and this project adheres to `Semantic Versioning <https://semver.org/>`_.

[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:

.. code-block:: bash

   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:

.. list-table::
   :header-rows: 1

   * - 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**:

.. code-block:: text

   DT = 2.0
   TAU0 = 0.005
   RNDAY = 1.0

**Cocoa YAML**:

.. code-block:: yaml

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

   physics:
     tau0: 0.005