xhycom 0.1.0

xarray interface for HYCOM a.b binary output files

xhycom

xhycom integrates HYCOM model output with xarray — giving every field a name, coordinates, units, and lazy out-of-memory access, directly from the native .ab format.

Installation

pip install git+https://github.com/nansencenter/xhycom.git

Dependencies: numpy, xarray, cftime, dask, xgcm — no Fortran compiler or external binary readers required. This covers reading, lazy/out-of-memory loading, and vertical regridding.

Horizontal regridding additionally needs xESMF, whose ESMF/esmpy backend is conda-forge only. ci/environment-regrid.yml creates the environment and pip installs xhycom itself (in editable mode) into it in one step:

conda env create -f ci/environment-regrid.yml
conda activate hycom-analysis-env

See Installation for details, including setup on the Olivia and Betzy HPC clusters.

Quick example

import xhycom

# Single snapshot — auto-detects file type, attaches lon/lat/time/dens
ds = xhycom.open_dataset("archv.2020_001_00", grid="regional.grid")
ds["temp"].isel(time=0, k=0).plot()

# Multi-year time series — lazy, out-of-memory, no data loaded until .compute()
ds = xhycom.open_mfdataset("data/", grid="regional.grid", chunks={"time": 1})
ds["temp"].isel(k=0).mean("time").compute()

Documentation

Full documentation — why xarray, worked examples, API reference, and a how-it-works guide — is at https://xhycom.readthedocs.io.