.. _cocoa-tools:

=====================
Cocoa Tools (Python)
=====================

Cocoa's Python tooling ships as one installable package, ``cocoa-tools``, in
``utils/cocoa_tools``. It provides three commands:

.. list-table::
   :header-rows: 1
   :widths: 22 22 56

   * - Command
     - Python package
     - Purpose
   * - ``cocoa-mesh-tools``
     - ``cocoa_mesh_tools``
     - Convert ADCIRC meshes, group flat mesh files, reorder meshes for GPU
       performance, and compute the mesh id (:ref:`converting-from-adcirc`,
       :ref:`element-ordering`, :ref:`mesh-identification`)
   * - ``cocoa-ocean3d``
     - ``cocoa_ocean3d``
     - Build the baroclinic nodal forcing file from HYCOM GOFS 3.1
       (:ref:`ocean3d-pipeline`)
   * - ``cocoa-plot``
     - ``cocoa_plot``
     - Plot output, peak, and mesh files on their unstructured mesh
       (:ref:`cocoa-plot` below)

Each command also runs as ``python -m <package>`` (for example
``python -m cocoa_mesh_tools``).

Installation
============

From a Cocoa checkout:

.. code-block:: bash

   pip install utils/cocoa_tools

This installs the three packages, the three commands, and their dependencies:
``numpy``, ``netCDF4``, ``gsw``, ``xarray``, ``matplotlib``, and ``cartopy``.
Python 3.10 or newer is required. The Cocoa containers have it installed, so
the commands are on ``PATH`` there (see :doc:`../getting_started/container`).

The package version follows Cocoa's. The mesh id computed by
``cocoa_mesh_tools`` must match Cocoa's C++ implementation byte for byte, and
the tools read and write files Cocoa consumes, so use the ``cocoa-tools`` from
the same Cocoa release (or checkout) as the model.

cocoa-mesh-tools
================

.. code-block:: bash

   cocoa-mesh-tools from_adcirc --mesh fort.14 [--attributes fort.13] \
       [--sal fort.24.nc] --output mesh.nc [--reorder [elements-only|all]]
   cocoa-mesh-tools group_variables --mesh flat.nc --output mesh.nc
   cocoa-mesh-tools reorder --mesh mesh.nc --output reordered.nc [--renumber-nodes]
   cocoa-mesh-tools checksum mesh.nc [--write] [--json]
   cocoa-mesh-tools checksum mesh.nc --verify

``from_adcirc`` converts ADCIRC fort.14 / fort.13 / fort.24 files to a Cocoa
mesh; ``group_variables`` re-groups a flat mesh netCDF into the grouped layout;
``reorder`` sorts elements (and, with ``--renumber-nodes``, renumbers nodes in
reverse Cuthill-McKee order) for GPU memory locality; ``checksum`` computes,
writes, or verifies the mesh id. ``from_adcirc`` and ``group_variables`` end
with a summary of the mesh they wrote and warn about elements out of GPU order
and nodal attributes Cocoa does not read; ``group_variables`` also warns about
source variables it did not copy. ``reorder`` reports the ordering before and
after, the file size, and the new mesh id. See :doc:`mesh_preparation` for the
mesh format and each step.

cocoa-ocean3d
=============

.. code-block:: bash

   cocoa-ocean3d download --time 2020-08-01T12:00 --server ftp --out ts.nc
   cocoa-ocean3d compute --input ts.nc --out structured.nc
   cocoa-ocean3d regrid --input structured.nc --mesh mesh.nc --out forcing.nc
   cocoa-ocean3d all --start 2020-08-01T00:00 --end 2020-08-05T00:00 \
       --step-hours 24 --mesh mesh.nc --out forcing.nc [--with-velocity]

The forcing file carries the mesh id of the mesh it was regridded onto, which
Cocoa checks at startup. See :doc:`baroclinic_coupling` for the products, the
file format, and the configuration that reads it.

.. _cocoa-plot:

cocoa-plot
==========

``cocoa-plot`` renders any Cocoa output, peak, or mesh file on its
unstructured mesh. It reads the mesh and variable metadata from the file, so
it needs no per-file configuration; ``--list`` reports what a file contains.

.. code-block:: bash

   cocoa-plot cocoa_output.nc --list

   # a single snapshot, or a peak field from the *_peak.nc file
   cocoa-plot cocoa_output.nc -v zeta -t -1 -o zeta.png
   cocoa-plot cocoa_output_peak.nc -v zeta_max -o peak.png

   # velocity magnitude with arrows, zoomed to a region
   cocoa-plot cocoa_output.nc -v velocity --vectors \
       --extent -98 -80 18 31 -o velocity.png

   # the mesh itself (quadrilaterals drawn as quadrilaterals)
   cocoa-plot mesh.nc -v mesh -o mesh.png

   # every 10th snapshot as numbered stills, or as a movie
   cocoa-plot cocoa_output.nc -v zeta --every 10 -o zeta.png
   cocoa-plot cocoa_output.nc -v zeta --every 10 --fps 12 -o zeta.mp4

Global meshes are detected from the domain extent and drawn in a Robinson
projection with the antimeridian handled; ``--projection`` selects another.
Movie output is chosen by the extension (``.mp4``, ``.mov``, ``.webm``,
``.mkv``, ``.gif``); the video formats need ``ffmpeg`` on ``PATH`` (it is in
the containers). ``--help`` lists the full set of options.

Coastlines come from cartopy's Natural Earth data, which cartopy downloads on
first use. On a machine with no outbound network, set ``CARTOPY_DATA_DIR`` to
a cache populated elsewhere or pass ``--no-coastline``; the containers carry a
pre-fetched cache.

Python API
==========

The packages are importable as libraries, for example:

.. code-block:: python

   from cocoa_mesh_tools import compute_mesh_fingerprint, reorder

   print(compute_mesh_fingerprint("mesh.nc").mesh_id)
   reorder("mesh.nc", "mesh_reordered.nc", renumber_nodes=True)

Tests
=====

.. code-block:: bash

   cd utils/cocoa_tools
   python -m pytest -q

The suite runs from a checkout without installing; the mesh tools tests read
committed meshes from the repository's ``test/data`` directory.