xhycom 0.1.0__tar.gz

xhycom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nora Loose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xhycom-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: xhycom
+Version: 0.1.0
+Summary: xarray interface for HYCOM a.b binary output files
+Author-email: Nora Loose <nora.loose@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nansencenter/xhycom
+Project-URL: Documentation, https://xhycom.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/nansencenter/xhycom/issues
+Project-URL: Source, https://github.com/nansencenter/xhycom
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: cftime
+Requires-Dist: dask
+Requires-Dist: xgcm
+Requires-Dist: numba
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: netCDF4; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: myst-nb; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Dynamic: license-file
+
+# xhycom
+
+[![Run Tests](https://github.com/nansencenter/xhycom/actions/workflows/tests.yml/badge.svg)](https://github.com/nansencenter/xhycom/actions/workflows/tests.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/nansencenter/xhycom/graph/badge.svg?token=5S1oNu39xE)](https://codecov.io/gh/nansencenter/xhycom)
+[![Documentation Status](https://readthedocs.org/projects/xhycom/badge/?version=latest)](https://xhycom.readthedocs.io/en/latest/?badge=latest)
+
+xhycom integrates HYCOM model output with [xarray](https://docs.xarray.dev) —
+giving every field a name, coordinates, units, and lazy out-of-memory access,
+directly from the native `.ab` format.
+
+## Installation
+
+```bash
+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](https://xesmf.readthedocs.io),
+whose ESMF/esmpy backend is conda-forge only. `ci/environment-regrid.yml` creates
+the environment and `pip install`s xhycom itself (in editable mode) into it in one
+step:
+
+```bash
+conda env create -f ci/environment-regrid.yml
+conda activate hycom-analysis-env
+```
+
+See [Installation](https://xhycom.readthedocs.io/en/latest/installation.html) for
+details, including setup on the Olivia and Betzy HPC clusters.
+
+## Quick example
+
+```python
+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](https://xhycom.readthedocs.io/en/latest/)**.

xhycom-0.1.0/README.md

@@ -0,0 +1,51 @@
+# xhycom
+
+[![Run Tests](https://github.com/nansencenter/xhycom/actions/workflows/tests.yml/badge.svg)](https://github.com/nansencenter/xhycom/actions/workflows/tests.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/nansencenter/xhycom/graph/badge.svg?token=5S1oNu39xE)](https://codecov.io/gh/nansencenter/xhycom)
+[![Documentation Status](https://readthedocs.org/projects/xhycom/badge/?version=latest)](https://xhycom.readthedocs.io/en/latest/?badge=latest)
+
+xhycom integrates HYCOM model output with [xarray](https://docs.xarray.dev) —
+giving every field a name, coordinates, units, and lazy out-of-memory access,
+directly from the native `.ab` format.
+
+## Installation
+
+```bash
+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](https://xesmf.readthedocs.io),
+whose ESMF/esmpy backend is conda-forge only. `ci/environment-regrid.yml` creates
+the environment and `pip install`s xhycom itself (in editable mode) into it in one
+step:
+
+```bash
+conda env create -f ci/environment-regrid.yml
+conda activate hycom-analysis-env
+```
+
+See [Installation](https://xhycom.readthedocs.io/en/latest/installation.html) for
+details, including setup on the Olivia and Betzy HPC clusters.
+
+## Quick example
+
+```python
+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](https://xhycom.readthedocs.io/en/latest/)**.

xhycom-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xhycom"
+version = "0.1.0"
+description = "xarray interface for HYCOM a.b binary output files"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Nora Loose", email = "nora.loose@gmail.com" }]
+requires-python = ">=3.8"
+dependencies = [
+    "numpy",
+    "xarray",
+    "cftime",
+    "dask",
+    "xgcm",
+    "numba",   # required by xgcm's Grid.transform for method="conservative"
+               # (regrid_vertical's default)
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+# Lateral regridding (regrid_horizontal / the full regrid wrapper) needs
+# xESMF.  Its ESMF/esmpy backend has no PyPI wheels, so it must come from
+# conda-forge -- there is no pip-only path, and it stays optional since it
+# can conflict with other ESMF installs on some platforms.  Ready-made env:
+#     conda env create -f ci/environment-regrid.yml
+dev = ["pytest", "pytest-cov", "netCDF4", "pre-commit"]
+docs = [
+    "sphinx",
+    "sphinx-book-theme",
+    "myst-nb",
+    "sphinx-copybutton",
+    "sphinx-design",
+]
+
+[project.urls]
+Homepage      = "https://github.com/nansencenter/xhycom"
+Documentation = "https://xhycom.readthedocs.io"
+"Bug Tracker" = "https://github.com/nansencenter/xhycom/issues"
+Source        = "https://github.com/nansencenter/xhycom"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xhycom*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# dask and xgcm are core dependencies, so reader/postprocess/vertical-regrid
+# tests run on the base + dev install. The lateral-regrid tests still
+# self-skip when xesmf is unavailable (conda-forge only, see above).
+
+[tool.coverage.run]
+source = ["xhycom"]
+omit = ["tests/*"]
+
+[tool.ruff]
+fix = true
+show-fixes = true
+line-length = 88
+exclude = ["docs"]
+
+[tool.ruff.lint]
+extend-select = ["I", "E", "W", "F", "D", "RUF", "UP"]
+ignore = ["E501", "D205", "D102", "D100", "D401", "D101", "D105", "D103", "D104", "UP040", "RUF043", "RUF059", "UP031", "RUF001", "RUF002", "RUF003", "RUF012"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"

xhycom-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xhycom-0.1.0/tests/test_postprocess.py

@@ -0,0 +1,146 @@
+"""Tests for xhycom.postprocess (unit conversions + derived fields)."""
+
+import numpy as np
+import pytest
+import xarray as xr
+
+import xhycom
+from xhycom._postprocess import _G, _ONEM, _reconcile_velocities, postprocess
+from xhycom._regrid import layer_centre_depth
+
+
+def test_ssh_converted_to_metres():
+    # srfhgt is geopotential g*eta; 1.5 m of SSH -> stored as g*1.5
+    srfhgt = xr.DataArray(
+        np.full((2, 3), _G * 1.5), dims=("y", "x"), name="srfhgt", attrs={"units": "Pa"}
+    )
+    out = postprocess(xr.Dataset({"srfhgt": srfhgt}))
+    np.testing.assert_allclose(out["srfhgt"].values, 1.5)
+    assert out["srfhgt"].attrs["units"] == "m"
+    assert "converted from" in out["srfhgt"].attrs["comment"]
+
+
+def test_thknss_converted_with_onem_not_g():
+    thknss = xr.DataArray(
+        np.full((1, 2, 2), 10.0 * _ONEM),
+        dims=("k", "y", "x"),
+        name="thknss",
+        attrs={"units": "Pa"},
+    )
+    out = postprocess(xr.Dataset({"thknss": thknss}))
+    np.testing.assert_allclose(out["thknss"].values, 10.0)
+    assert out["thknss"].attrs["units"] == "m"
+
+
+def test_area_added_from_scales():
+    ds = xr.Dataset(
+        {
+            "scpx": (("y", "x"), np.full((2, 2), 100.0)),
+            "scpy": (("y", "x"), np.full((2, 2), 200.0)),
+        }
+    )
+    out = postprocess(ds)
+    assert "area" in out
+    np.testing.assert_allclose(out["area"].values, 20000.0)
+    assert out["area"].attrs["units"] == "m2"
+
+
+def test_landmask_from_depth():
+    depth = xr.DataArray(
+        np.array([[10.0, np.nan], [5.0, 3.0]]),
+        dims=("y", "x"),
+        name="depth",
+        attrs={"units": "m"},
+    )
+    out = postprocess(xr.Dataset({"depth": depth}))
+    assert "landmask" in out
+    np.testing.assert_array_equal(out["landmask"].values, [[1, 0], [1, 1]])
+
+
+def test_idempotent_does_not_double_convert():
+    srfhgt = xr.DataArray(
+        np.full((2, 2), _G), dims=("y", "x"), name="srfhgt", attrs={"units": "Pa"}
+    )
+    once = postprocess(xr.Dataset({"srfhgt": srfhgt}))
+    twice = postprocess(once)
+    np.testing.assert_allclose(twice["srfhgt"].values, once["srfhgt"].values)
+
+
+def test_postprocess_exported():
+    assert xhycom.postprocess is postprocess
+
+
+def test_regrid_vertical_unit_aware_after_postprocess():
+    # thknss in Pa vs converted to m must yield identical layer-centre depths
+    thk_pa = xr.DataArray(
+        np.full((4, 1, 1), 10.0 * _ONEM),
+        dims=("k", "y", "x"),
+        name="thknss",
+        attrs={"units": "Pa"},
+    )
+    thk_m = postprocess(xr.Dataset({"thknss": thk_pa}))["thknss"]
+    z_pa = layer_centre_depth(thk_pa).values
+    z_m = layer_centre_depth(thk_m).values
+    np.testing.assert_allclose(z_pa, z_m)
+    np.testing.assert_allclose(z_pa[:, 0, 0], [5, 15, 25, 35], atol=1e-3)
+
+
+# ---------------------------------------------------------------------------
+# Velocity convention: archv stores baroclinic, archm stores total
+# ---------------------------------------------------------------------------
+def _vel_ds(archive_type, with_barotropic=True):
+    data = {
+        "u-vel.": xr.DataArray(np.full((2, 2, 2), 0.3), dims=("k", "y", "x")),
+        "v-vel.": xr.DataArray(np.full((2, 2, 2), -0.2), dims=("k", "y", "x")),
+    }
+    if with_barotropic:
+        data["u_btrop"] = xr.DataArray(np.full((2, 2), 0.1), dims=("y", "x"))
+        data["v_btrop"] = xr.DataArray(np.full((2, 2), 0.05), dims=("y", "x"))
+    return xr.Dataset(data, attrs={"archive_type": archive_type})
+
+
+def test_velocity_total_for_instantaneous_archive():
+    out = postprocess(_vel_ds("instantaneous"))
+    np.testing.assert_allclose(
+        out["u-vel."].values, 0.4
+    )  # 0.3 baroclinic + 0.1 barotropic
+    np.testing.assert_allclose(out["v-vel."].values, -0.15)
+    assert out["u-vel."].attrs["hycom_velocity"] == "total"
+    assert "barotropic" in out["u-vel."].attrs["comment"]
+
+
+def test_velocity_total_for_mean_archive():
+    out = postprocess(_vel_ds("mean"))
+    np.testing.assert_allclose(out["u-vel."].values, 0.3)  # already total, unchanged
+    assert out["u-vel."].attrs["hycom_velocity"] == "total"
+
+
+def test_velocity_left_baroclinic_without_barotropic():
+    with pytest.warns(UserWarning, match="baroclinic"):
+        out = postprocess(_vel_ds("instantaneous", with_barotropic=False))
+    np.testing.assert_allclose(out["u-vel."].values, 0.3)  # unchanged
+    assert out["u-vel."].attrs["hycom_velocity"] == "baroclinic"
+
+
+def test_velocity_reconcile_idempotent():
+    out = postprocess(postprocess(_vel_ds("instantaneous")))
+    np.testing.assert_allclose(out["u-vel."].values, 0.4)  # not 0.5
+
+
+def test_velocity_untouched_without_archive_type():
+    ds = xr.Dataset({"u-vel.": xr.DataArray(np.full((2, 2), 0.3), dims=("y", "x"))})
+    out = _reconcile_velocities(ds)
+    assert "hycom_velocity" not in out["u-vel."].attrs
+
+
+def test_augment_velocity_vars():
+    from xhycom import _augment_velocity_vars
+
+    aug, auto = _augment_velocity_vars(["temp", "u-vel.", "v-vel."], True)
+    assert set(auto) == {"u_btrop", "v_btrop"}
+    assert {"temp", "u-vel.", "v-vel.", "u_btrop", "v_btrop"} == set(aug)
+    assert _augment_velocity_vars(["u-vel."], False) == (["u-vel."], [])
+    assert _augment_velocity_vars(None, True) == (None, [])
+    assert _augment_velocity_vars(["temp"], True) == (["temp"], [])
+    aug2, auto2 = _augment_velocity_vars(["u-vel.", "u_btrop"], True)
+    assert auto2 == ["v_btrop"]

xhycom-0.1.0/tests/test_reader.py

@@ -0,0 +1,204 @@
+"""Reader tests against synthetic .ab fixtures (see conftest.py)."""
+
+import numpy as np
+import pytest
+
+import xhycom
+from xhycom._reader import detect_filetype, read_ave
+
+
+# ---------------------------------------------------------------------------
+# detect_filetype
+# ---------------------------------------------------------------------------
+def test_detect_filetype(grid_file, bathy_file, archive_file):
+    assert detect_filetype(grid_file[0]) == "grid"
+    assert detect_filetype(bathy_file[0]) == "bathy"
+    assert detect_filetype(archive_file) == "archv"
+
+
+# ---------------------------------------------------------------------------
+# Grid
+# ---------------------------------------------------------------------------
+def test_open_grid(grid_file):
+    base, fields = grid_file
+    ds = xhycom.open_dataset(base)
+    for name, arr in fields.items():
+        assert name in ds, name
+        np.testing.assert_allclose(ds[name].values, arr, rtol=1e-5)
+    assert ds["plon"].dims == ("y", "x")
+
+
+# ---------------------------------------------------------------------------
+# Bathymetry
+# ---------------------------------------------------------------------------
+def test_open_bathy_requires_grid(bathy_file):
+    with pytest.raises(ValueError, match="grid="):
+        xhycom.open_dataset(bathy_file[0])
+
+
+def test_open_bathy(bathy_file, grid_file):
+    base, depth = bathy_file
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(base, grid=grid)
+    wet = depth < 1e30
+    np.testing.assert_allclose(ds["depth"].values[wet], depth[wet], rtol=1e-5)
+    assert np.isnan(ds["depth"].values[0, 0])  # land point -> NaN
+    assert "lon" in ds.coords and "lat" in ds.coords
+
+
+# ---------------------------------------------------------------------------
+# Archive
+# ---------------------------------------------------------------------------
+def test_open_archive_structure(archive_file, grid_file):
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(archive_file, grid=grid)
+    assert set(ds["temp"].dims) == {"time", "k", "y", "x"}
+    assert ds["srfhgt"].dims == ("time", "y", "x")
+    np.testing.assert_array_equal(ds["k"].values, [1, 2, 3])
+    np.testing.assert_allclose(ds["dens"].values, [28.0, 29.0, 30.0])
+    # temp[k] == 10 - k
+    np.testing.assert_allclose(
+        ds["temp"].isel(time=0, y=0, x=0).values,
+        [9.0, 8.0, 7.0],
+        rtol=1e-5,
+    )
+    assert ds["time"].size == 1
+
+
+def test_open_archive_variables_filter(archive_file, grid_file):
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(archive_file, grid=grid, variables=["temp", "thknss"])
+    assert "temp" in ds and "thknss" in ds
+    assert "salin" not in ds
+
+
+def test_open_mfdataset_concats_time(archive_pair, grid_file):
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_mfdataset(archive_pair, grid=grid)
+    assert ds["time"].size == 2
+    assert ds["temp"].sizes["time"] == 2
+
+
+def test_open_mfdataset_lazy_chunks(archive_pair, grid_file):
+    pytest.importorskip("dask")
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_mfdataset(archive_pair, grid=grid, chunks={"time": 1})
+    assert ds["temp"].chunks is not None
+    np.testing.assert_allclose(
+        ds["temp"].isel(time=0, y=0, x=0).values,
+        [9.0, 8.0, 7.0],
+        rtol=1e-5,
+    )
+
+
+# ---------------------------------------------------------------------------
+# postprocess threaded through the real read path
+# ---------------------------------------------------------------------------
+def test_postprocess_through_open_archive(archive_file, grid_file):
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(archive_file, grid=grid, postprocess=True)
+    assert ds["srfhgt"].attrs["units"] == "m"
+    np.testing.assert_allclose(
+        ds["srfhgt"].isel(time=0, y=0, x=0).values, 0.5, rtol=1e-4
+    )
+    assert ds["thknss"].attrs["units"] == "m"
+    np.testing.assert_allclose(
+        ds["thknss"].isel(time=0, y=0, x=0).values, [10.0, 10.0, 10.0], rtol=1e-4
+    )
+
+
+def test_postprocess_through_open_grid(grid_file):
+    base, _ = grid_file
+    ds = xhycom.open_dataset(base, postprocess=True)
+    assert "area" in ds
+    np.testing.assert_allclose(ds["area"].values, 100.0 * 200.0, rtol=1e-5)
+
+
+def test_postprocess_through_open_bathy(bathy_file, grid_file):
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(bathy_file[0], grid=grid, postprocess=True)
+    assert "landmask" in ds
+    assert ds["landmask"].values[0, 0] == 0  # land
+    assert ds["landmask"].values[-1, -1] == 1  # ocean
+
+
+def test_archive_type_instantaneous(archive_file):
+    # The synthetic fixture writes a "... model day" header -> instantaneous archv.
+    ds = xhycom.open_dataset(archive_file)
+    assert ds.attrs["archive_type"] == "instantaneous"
+
+
+# ---------------------------------------------------------------------------
+# AVE (hycave/ensave monthly average)
+# ---------------------------------------------------------------------------
+def test_detect_filetype_ave(ave_file: str) -> None:
+    """AVE header (has 'iversn' + 'kdm   ') is distinguished from archv."""
+    assert detect_filetype(ave_file) == "ave"
+
+
+def test_open_ave_structure(ave_file: str, grid_file: tuple) -> None:
+    """2-D and 3-D AVE fields land on the expected dims; archive_type is set."""
+    grid = xhycom.open_dataset(grid_file[0])
+    ds = xhycom.open_dataset(ave_file, grid=grid)
+    assert "ssh" in ds
+    assert "temp" in ds
+    assert ds["ssh"].dims == ("time", "y", "x")
+    assert set(ds["temp"].dims) == {"time", "k", "y", "x"}
+    np.testing.assert_array_equal(ds["k"].values, [1, 2, 3])
+    assert ds["time"].size == 1
+    assert ds.attrs["archive_type"] == "time_average"
+
+
+def test_open_ave_time_from_filename(ave_file: str) -> None:
+    """Time coordinate is parsed from _YYYY_MM suffix, not from model-day (always 0)."""
+    import cftime
+
+    ds = xhycom.open_dataset(ave_file)
+    t = ds["time"].values[0]
+    assert isinstance(t, cftime.datetime)
+    assert t.year == 1991
+    assert t.month == 1
+    assert t.day == 1
+
+
+def test_open_ave_variables_filter(ave_file: str) -> None:
+    """variables= kwarg restricts which AVE fields are loaded."""
+    ds = xhycom.open_dataset(ave_file, variables=["temp"])
+    assert "temp" in ds
+    assert "ssh" not in ds
+
+
+def test_open_ave_no_time_without_pattern(tmp_path, grid_file: tuple) -> None:
+    """Basenames without _YYYY_MM suffix produce a Dataset with no time dim."""
+    from conftest import _write_ave
+
+    base = str(tmp_path / "EXPAVE_nodate")
+    _write_ave(base)
+    ds = xhycom.open_dataset(base)
+    assert "time" not in ds.dims
+
+
+def test_read_ave_public_api(ave_file: str) -> None:
+    """read_ave() is importable from xhycom._reader and returns a Dataset."""
+    ds = read_ave(ave_file)
+    assert "ssh" in ds and "temp" in ds
+
+
+def test_archive_type_mean(tp0):
+    # The bundled archm fixture writes a "... mean day" header -> mean archive,
+    # whose u-vel./v-vel. are already the total current.
+    ds = xhycom.open_dataset(tp0.archive, postprocess=True)
+    assert ds.attrs["archive_type"] == "mean"
+    assert ds["u-vel."].attrs["hycom_velocity"] == "total"
+
+
+def test_open_ave_chunks(ave_file: str) -> None:
+    """read_ave with chunks= loads lazily via Dask."""
+    pytest.importorskip("dask")
+    ds = read_ave(ave_file, chunks={"k": 1})
+    assert ds["temp"].chunks is not None
+    np.testing.assert_allclose(
+        ds["temp"].isel(time=0, y=0, x=0).values,
+        [9.0, 8.0, 7.0],
+        rtol=1e-5,
+    )