=========
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/>`_.

[Unreleased]
------------

Added
^^^^^

- N/A

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.

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.

Fixed
^^^^^

- N/A

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