Cocoa Tools (Python)

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

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 (Converting from ADCIRC Format, Element Ordering, Mesh Identification)
`cocoa-ocean3d`	`cocoa_ocean3d`	Build the baroclinic nodal forcing file from HYCOM GOFS 3.1 (Preprocessor pipeline)
`cocoa-plot`	`cocoa_plot`	Plot output, peak, and mesh files on their unstructured mesh (cocoa-plot below)

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

Installation

From a Cocoa checkout:

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 Containers).

The package version follows Cocoa’s. The mesh id computed by cocoa_mesh_tools must match Cocoa’s C++ implementation exactly, 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

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 Mesh Preparation for the mesh format and each step.

cocoa-ocean3d

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 Baroclinic Coupling for the products, the file format, and the configuration that reads it.

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.

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:

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

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.