Introduction to XGCM

Introduction to XGCM#

Before we get started, you may choose to run this notebook on LEAP-Pangeo hub or Binder!

Xgcm is a python packge for working with the datasets produced by numerical General Circulation Models (GCMs) and similar gridded datasets that are amenable to finite volume analysis. In these datasets, different variables are located at different positions with respect to a volume or area element (e.g. cell center, cell face, etc.) xgcm solves the problem of how to interpolate and difference these variables from one position to another.

xgcm consumes and produces xarray data structures, which are coordinate and metadata-rich representations of multidimensional array data. xarray is ideal for analyzing GCM data in many ways, providing convenient indexing and grouping, coordinate-aware data transformations, and (via dask) parallel, out-of-core array computation. On top of this, xgcm adds an understanding of the finite volume Arakawa Grids commonly used in ocean and atmospheric models and differential and integral operators suited to these grids.

import xarray as xr
import numpy as np
import xgcm
from matplotlib import pyplot as plt

%matplotlib inline
plt.rcParams["figure.figsize"] = (10, 6)

Axis#

A fundamental concept in xgcm is the notion of an “axis”. An axis is a group of coordinates that all lie along the same physical dimension but describe different positions relative to a grid cell. There are currently five possible positions supported by xgcm.

center The variable values are located at the cell center.

left The variable values are located at the left (i.e. lower) face of the cell.

right The variable values are located at the right (i.e. upper) face of the cell.

inner The variable values are located on the cell faces, excluding both outer boundaries.

outer The variable values are located on the cell faces, including both outer boundaries.

The first three (center, left, and right) all have the same length along the axis dimension, while inner has one fewer point and outer has one extra point. These positions are visualized in the figure below.

https://xgcm.readthedocs.io/en/latest/_images/axis_positions.svg

Although it is technically possible to create an Axis directly, the recommended way to to use xgcm is by creating a single xgcm.Grid object, containing multiple axes for each physical dimension.

Let us now create a grid using ds. xarray has no idea that x_center and x_left are related to each other; they are subject to standard xarray broadcasting rules. When we create an xgcm.Grid, we need to specify that they are part of the same axis. We do this using the coords keyword argument, as follows:

from xgcm import Grid

grid = Grid(ds, coords={"X": {"center": "x_center", "left": "x_left"}})
grid

<xgcm.Grid>
X Axis (periodic, boundary=None):
  * center   x_center --> left
  * left     x_left --> center

The printed information about the grid indicates that xgcm has successfully understood the relative location of the different coordinates along the x axis. Because we did not specify the periodic keyword argument, xgcm assumed that the data is periodic along all axes. The arrows after each coordinate will be explained later.

If coords is not specified, xgcm looks for metadata in the coordinate attributes. The key attribute xgcm looks for is axis. When creating a new grid, xgcm will search through the dataset dimensions looking for dimensions with the axis attribute defined.

To determine the positions of the different coordinates, xgcm considers both the length of the coordinate variable and the c_grid_axis_shift attribute, which determines the position of the coordinate with respect to the cell center.

The only acceptable values of c_grid_axis_shift are -0.5 and 0.5. If the c_grid_axis_shift attribute attribute is absent, the coordinate is assumed to describe a cell center.

The cell center coordinate is identified first; the length of other coordinates relative to the cell center coordinate is used in conjunction with c_grid_axis_shift to infer the coordinate positions

length	c_grid_axis_shift	position
n	None	center
n	-0.5	left
n	0.5	right
n-1	0.5 / -0.5	inner
n+1	0.5 / -0.5	outer

grid = Grid(ds)
grid

<xgcm.Grid>
X Axis (periodic, boundary=None):
  * center   x_center --> left
  * left     x_left --> center

The arrows after each coordinate indicate the default shift positions for interpolation and difference operations: operating on the center coordinate (x_center) shifts to the left coordinate (x_left), and vice versa. What are these operations? To understand them deeper, we need to introduce the concept of Arakawa grids.

Arakawa grids#

Most finite volume ocean models use Arakawa Grids, in which different variables are offset from one another and situated at different locations with respect to the cell center and edge points. As an example, we will consider C-grid geometry. As illustrated in the figure below, C-grids place scalars (such as temperature) at the cell center and vector components (such as velocity) at the cell faces.

https://xgcm.readthedocs.io/en/latest/_images/grid2d_hv.svg

These grids present a dilemma for the xarray data model. The u and t points in the example above are located at different points along the x-axis, meaning they can’t be represented using a single coordinate. But they are clearly related and can be transformed via well defined interpolation and difference operators. One goal of xgcm is to provide these interpolation and difference operators.

The difference operator is defined as

\[\delta_x \phi = \phi_{x_{right}} - \phi_{x_{left}}\]

The interpolation operator is defined as

\[ \overline \phi = \frac{\phi_{x_{right}} + \phi_{x_{left}}}{2}\]

where \(\phi\) is a generic variable and \(x_{right}\) and \(x_{left}\) are the right and left positions of the variable along the x-axis.

Both operators return a variable that is shifted by half a gridpoint with respect to the input variable. With these two operators, the entire suite of finite volume vector calculus operations can be represented.