Skip to content

What's New

v0.10.0 (unreleased)

New Features

Bug Fixes

  • Grid.get_metric (and the operations built on it, e.g. Grid.integrate and Grid.average) no longer emits spurious "Metric ... being interpolated ..." UserWarnings when an exact-position metric combination exists but is not the first candidate tried. The search now looks for an exact-position match across all candidate combinations before falling back to interpolation, and warns at most once. The returned metric is unchanged (#758). By Henri Drake.

  • Axis now raises a ValueError immediately if the same dimension name is assigned to more than one position (e.g. {'center': 'x', 'outer': 'x'}), rather than silently accepting the invalid configuration (#634). By Mike German.

Breaking Changes

  • Removed the periodic argument of xgcm.Grid. Boundary behavior is now controlled exclusively by the boundary argument. Migrate as follows: periodic=True → boundary="periodic"; periodic=False → boundary="fill" (the previous implicit mapping); and the per-axis list form periodic=["X"] → a per-axis dict, e.g. boundary={"X": "periodic", "Y": "fill"}. Passing periodic= now raises an informative ValueError naming the replacement.

The default boundary semantics have also changed: previously a Grid constructed without any boundary specification defaulted to periodic along every axis (silently wrapping), which was the root of several boundary-condition bugs. Now, an axis with no boundary specified applies no boundary condition: operations that require padding along such an axis raise an informative error instead of silently wrapping. Pass boundary="periodic" to recover the old wrap-around behavior. This makes the default explicitly non-periodic and fixes cases where a declared non-periodic axis could still wrap. (#746; closes #195, #509, #604, #624, #625) By Henri Drake. Supersedes earlier work by Julius Busecke in #626.

  • Removed the deprecated keep_coords keyword argument from grid operations (Grid.interp, Grid.diff, Grid.min, Grid.max, Grid.cumsum, etc.) and from apply_as_grid_ufunc. The behavior is now always that formerly given by keep_coords=True: coordinates compatible with the output (including non-dimension coordinates) are preserved. Note that this silently changes the default output of Grid.interp, Grid.diff, Grid.min, Grid.max, Grid.cumsum, Grid.derivative, and Grid.cumint, which previously dropped non-dimension coordinates from the result and now retains them. Passing keep_coords= now raises a ValueError (#382, #745). By Henri Drake.

  • Axis is no longer importable from the top-level xgcm namespace, making effective the removal announced in v0.9.0; internal use continues via xgcm.axis.Axis (#405, #557, #743). By Henri Drake.

Internal Changes

  • Advertise Python 3.12 and 3.13 support by adding their Programming Language :: Python trove classifiers, and drop the unused future dependency (the package was never imported; only the stdlib from __future__ is used) (#744). By Henri Drake.

  • Migrate development workflow to Pixi (#691) By Nick Hodgskin.

  • Improve xgcm import speed by lazy-loading the transform module, reducing import time from 3.4s to 0.8s (#697) By Nick Hodgskin.

Documentation

  • Reword the "Metrics" note in grid_ufuncs.md to a stable, non-promissory statement: metrics are not automatically supplied to grid ufuncs, so pass any needed metric explicitly as an input (#744). By Henri Drake.

  • Migrate documentation to mkdocs (#691) By Nick Hodgskin.

  • Document which environment runs the documentation notebooks (transform.ipynb, grid_metrics.ipynb). The existing docs pixi environment now bundles Jupyter Lab and can be launched with pixi run notebooks, and the notebooks and contributor guide note the required dependencies (#667).

  • xgcm now follows Intended Effort Versioning (EffVer); the policy is documented in the contributor guide and advertised by a README badge (#679, #680, #742). By Nick Hodgskin and Henri Drake.

Bugfixes

  • Respect the fill_value bound on the @as_grid_ufunc decorator (or passed to GridUFunc). It was silently dropped in GridUFunc.__call__ — only a call-time fill_value took effect, so a bound value fell through to the apply_as_grid_ufunc default of 0. The bound value is now forwarded (and still overridable at call time), mirroring the other bound boundary kwargs (#652, #710). By Vincent Gao.

  • Fix xgcm.padding.pad(..., other_component=...) (and hence vector Grid.diff/Grid.interp) silently ignoring the vector rotation when the component is passed as a bare DataArray rather than a {axis_name: DataArray} dict. On a face_connections grid the bare form padded the component scalar-style, so the halo across a rotated (axis-swapping) or reversed seam was wrong and no error was raised — e.g. on ECCO LLC90 the global convergence sum of the advective heat flux was -1.6e9 (bare) versus 0 (dict). The bare form now recovers the component's axis from its own staggering and runs the same rotation/sign-flip logic as the dict form, giving identical output, and raises a clear error when the axis cannot be inferred (e.g. a cell-centre field) (#748). By Henri Drake.

  • Fix Grid.transform(..., method="conservative") falsely raising NotImplementedError ("not yet supported for multi-dimensional targets") when a 1-dimensional target was combined with an explicit target_dim longer than one character: the guard tested the length of the dimension name instead of the number of target dimensions (#741). By Henri Drake.

  • Preserve the input DataArray's dimension order in the output of apply_as_grid_ufunc (and the Grid.apply_as_grid_ufunc method). Previously xarray.apply_ufunc moved the operated-on core dimension to the end and never moved it back, so an input with dims ('tile', 'j', 'i') came back as ('tile', 'i', 'j'). The output now follows the input ordering (with the core dim renamed in-place if it changes grid position) (#533).

  • Grid operations (e.g. Grid.interp, Grid.diff, Grid.cumsum) no longer drop or clobber non-core coordinates carried on the input DataArray. Padding strips all coordinates and they were only restored from the grid's own dataset, so a coordinate that lived on the input but not on the grid (e.g. a time coordinate) was lost, and a coordinate present on both was overwritten with the grid's (possibly stale) copy. Coordinates on non-core dimensions are now preserved from the input array (first input wins for repeated names), while the newly position-shifted core-dim coordinate still comes from the grid (#496, #575).

  • Fix TypeError: dict.copy() takes no keyword arguments when applying vector grid ufuncs (e.g. diff_2d_vector, interp_2d_vector) on grids without face connections. A vector component supplied as a {axis_name: DataArray} dict was forwarded unchanged by xgcm.padding.pad to the basic padding routine _pad_basic (which expects a DataArray); pad now unpacks the inner DataArray on the non-face-connection path, mirroring the existing face-connection path (#581). By Henri Drake.

  • Fix diff_2d_vector/interp_2d_vector (and the equivalent vector-component Grid.diff/Grid.interp) on grids with face connections when a vector component is a dask array chunked into more than one chunk along its core dimension. The map_overlap path now derives the output chunk spec from the padded, rechunked array, so face-connection padding that rechunks non-core dimensions no longer raises ValueError: Dimension 0 has 2 blocks, adjust_chunks specified with 1 blocks (#708). By Henri Drake.

  • Fix non-deterministic, hash-seed-dependent halo values in face-connection padding that could yield incorrect results across a face-connection seam between runs (#713). By Henri Drake.

v0.9.0 (2025/08/20)

New Features

  • Methods for autoparsing of dataset metadata to construct a xgcm.Grid class have been added. Currently these include restructred functionality for the COMODO conventions (already in xgcm) and the addition of SGRID conventions (#109, #559). By Jack Atkinson.

  • Vertical coordinate transformations are now also supported for multi-dimensional targets, for example a terrain-following (spatially varying) vertical coordinate. This feature currently only works with the linear interpolation method (#614, #642). By Nora Loose.

Breaking Changes

  • All computation methods on the xgcm.Axis class have been removed, in favour of using the corresponding methods on the xgcm.Grid object. The xgcm.Axis class has also been removed from public API. (#405, #557). By Thomas Nicholas.

  • All functionality for generating c-grid dimensions on incomplete datasets via Grid.autogenerate, was removed (#557). By Julius Busecke.

Internal Changes

Documentation

Bugfixes

  • Fix bug in xgcm.transform.transform that violated tracer conservation when using conservative interpolation in the presence of nans. (#635) By Julius Busecke.

  • Fix bug in xgcm.padding._maybe_rename_grid_positions where dimensions were assumed to have coordinate values leading to errors with ECCO data. (#531, #595, #597). By Julius Busecke.

  • Remove remaining mentions of extrapolate as boundary option (#602). By Julius Busecke.

  • Fix broken docs build due to broken backwards compatibility in sphinx extensions (#631) By Julius Busecke.

  • Fix bug that did not allow to create grids with faceconnections if the face dimension was coordinate-less. (#616, #616). By Julius Busecke.

v0.8.1 (2022/11/22)

New Features

Breaking Changes

Internal Changes

  • Rewrote cumsum to use a different code path from apply_as_grid_ufunc internally, which makes it less susceptible to subtle bugs like the one reported in #507. (#558). By Thomas Nicholas.

Documentation

  • Improved error message to suggest rechunking to a single chunk when trying to perform disallowed operations along chunked core dims. By Thomas Nicholas.

Bugfixes

v0.8.0 (2022/06/14)

New Features

Breaking Changes

Internal Changes

Documentation

Bugfixes

v0.7.0 (2022/4/20)

New Features

  • Turn numpy-style ufuncs into grid-aware "grid-ufuncs" via new functions apply_as_grid_ufunc and as_grid_ufunc. (#362, #344) By Thomas Nicholas.

  • Padding of vector fields for complex topologies via a dictionary-like syntax has been added (#459). By Julius Busecke.

Breaking Changes

Internal Changes

  • All computation methods on the Grid object are now re-routed through apply_as_grid_ufunc. By Thomas Nicholas.

Documentation

v0.6.1 (2022/02/15)

Documentation

  • Switch RTD build to use mamba for increased speed and reduced memory useage (#401). By Julius Busecke.

Internal Changes

v0.6.0 (2021/11/03)

New Features

  • Grid.set_metrics now enables adding metrics to a grid object (#336, #199). By Dianne Deauna under the SIParCS internship.

  • Grid.get_metric refactored, and now incorporates Grid.interp_like to allow for automatic interpolation of missing metrics from available values on surrounding positions (#345, #354). By Dianne Deauna.[^siparcs]

  • Grid.set_metrics enables overwriting of previously assigned metrics to a grid object, and allows for multiple metrics on the same axes (must be different dimensions) (#351, #199). By Dianne Deauna.[^siparcs]

  • Grid.interp_like enables users to interpolate arrays onto the grid positions of another array, and can specify boundary conditions and fill values (#234 , #343, #350). By Dianne Deauna.[^siparcs]

  • Better input checking when creating a grid object avoids creating grid positions on dataset coordinates which are not 1D (#208, #358). By Julius Busecke.

[^siparcs]: under the SIParCS internship

Breaking Changes

Documentation

Internal Changes

  • Fixed metrics tests so some tests that previously did not run now do run, and refactored the metrics tests. By Tom Nicholas.[^siparcs]

  • Enabled type checking on the repository with mypy. By Tom Nicholas.[^siparcs]

  • Removed dependency on docrep, which as docrep 2.7 used a GPL licence, implicitly changed the license of xGCM. Therefore xGCM now has a valid MIT license, instead of accidentally being a GPL licence as it was before. (#308, #384) By Tom Nicholas.[^siparcs]

Deprecations

  • The keep_coords kwarg is now deprecated, and will be removed in the next version. (#382) By Tom Nicholas.[^siparcs]

v0.5.2 (2021/5/27)

Bug fixes

  • Raise more useful errors when datasets are provided as arguments to grid.transform (#329, #328). By Julius Busecke.

Documentation

v0.5.1 (2020/10/16)

Bug fixes

v0.5.0 (2020/9/28)

New Features

Bug fixes

v0.4.0 (2020/9/2)

New Features

  • Support for keeping compatible coordinates in most Grid operations (#186). By Aurélien Ponte.

  • Support for specifying default boundary and fill_value in the xgcm.Grid constructor. Default values can be overridden in individual method calls (e.g. Grid.interp) as usual. By Deepak Cherian.

Bug fixes

Internal Changes

v0.3.0 (31 January 2020)

This release adds support for model grid metrics , bug fixes and extended documentation.

Breaking changes

New Features

  • Support for 'grid-aware' average and cumsum using Grid.average and Grid.cumsum (#162). By Julius Busecke.

  • Support for 'grid-aware' integration using Grid.integrate (#130). By Julius Busecke.

Bug fixes

Documentation

Internal Changes

v0.2.0 (21 March 2019)

Changes not documented for this release

v0.1.0 (13 July 2014)

Changes not documented for this release

Initial release.