# API¶

## Axis¶

class xgcm.Axis(ds, axis_name, periodic=True, default_shifts={}, coords=None)[source]

An object that represents a group of coodinates that all lie along the same physical dimension but at different positions with respect to a grid cell. There are four possible positions:

 Center
|------o-------|------o-------|------o-------|------o-------|
[0]            [1]            [2]            [3]

Left
|------o-------|------o-------|------o-------|------o-------|
[0]            [1]            [2]            [3]

Right
|------o-------|------o-------|------o-------|------o-------|
[0]            [1]            [2]            [3]

Inner
|------o-------|------o-------|------o-------|------o-------|
[0]            [1]            [2]

Outer
|------o-------|------o-------|------o-------|------o-------|
[0]            [1]            [2]            [3]            [4]


The center position is the only one without the c_grid_axis_shift attribute, which must be present for the other four. However, the actual value of c_grid_axis_shift is ignored for inner and outer, which are differentiated by their length.

__init__(self, ds, axis_name, periodic=True, default_shifts={}, coords=None)[source]

Create a new Axis object from an input dataset.

Parameters
dsxarray.Dataset

Contains the relevant grid information. Coordinate attributes should conform to Comodo conventions [1].

axis_namestr

The name of the axis (should match axis attribute)

periodicbool, optional

Whether the domain is periodic along this axis

default_shiftsdict, optional

Default mapping from and to grid positions (e.g. {‘center’: ‘left’}). Will be inferred if not specified.

coordsdict, optional

Mapping of axis positions to coordinate names (e.g. {‘center’: ‘XC’, ‘left: ‘XG’})

References

1

Comodo Conventions http://pycomodo.forge.imag.fr/norm.html

cumsum(self, da, to=None, boundary=None, fill_value=0.0)[source]

Cumulatively sum a DataArray, transforming to the intermediate axis position.

Parameters
daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_cumxarray.DataArray

The cumsummed data

diff(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[source]

Difference neighboring points to the intermediate grid point.

Parameters
daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

interp(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[source]

Interpolate neighboring points to the intermediate grid point along this axis.

Parameters
daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The interpolated data

max(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[source]

Maximum of neighboring points on intermediate grid point.

Parameters
%(neighbor_binary_func.parameters.no_f)s
Returns
da_ixarray.DataArray

The differenced data

min(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[source]

Minimum of neighboring points on intermediate grid point.

Parameters
daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

## Grid¶

class xgcm.Grid(ds, check_dims=True, periodic=True, default_shifts={}, face_connections=None, coords=None, metrics=None)[source]

An object with multiple xgcm.Axis objects representing different independent axes.

__init__(self, ds, check_dims=True, periodic=True, default_shifts={}, face_connections=None, coords=None, metrics=None)[source]

Create a new Grid object from an input dataset.

Parameters
dsxarray.Dataset

Contains the relevant grid information. Coordinate attributes should conform to Comodo conventions [1].

check_dimsbool, optional

Whether to check the compatibility of input data dimensions before performing grid operations.

periodic{True, False, list}

Whether the grid is periodic (i.e. “wrap-around”). If a list is specified (e.g. ['X', 'Y']), the axis names in the list will be be periodic and any other axes founds will be assumed non-periodic.

default_shiftsdict

A dictionary of dictionaries specifying default grid position shifts (e.g. {'X': {'center': 'left', 'left': 'center'}})

face_connectionsdict

Grid topology

coordsdict, optional

Excplicit specification of axis coordinates, e.g {'X': {'center': 'XC', 'left: 'XG'}}. Each key should be the name of an axis. The value should be a dictionary mapping positions (e.g. 'left') to names of coordinates in ds.

metricsdict, optional

Specification of grid metrics

References

1

Comodo Conventions http://pycomodo.forge.imag.fr/norm.html

cumsum(self, da, axis, **kwargs)[source]

Cumulatively sum a DataArray, transforming to the intermediate axis position.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The cumsummed data

derivative(self, da, axis, **kwargs)[source]

Take the centered-difference derivative along specified axis.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differentiated data

diff(self, da, axis, **kwargs)[source]

Difference neighboring points to the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

diff_2d_vector(self, vector, **kwargs)[source]

Difference a 2D vector to the intermediate grid point. This method is only necessary for complex grid topologies.

Parameters
vectordict

A dictionary with two entries. Keys are axis names, values are vector components along each axis.

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
vector_diffdict

A dictionary with two entries. Keys are axis names, values are differenced vector components along each axis

get_metric(self, array, axes)[source]

Find the metric variable associated with a set of axes for a particular array.

Parameters
arrayxarray.DataArray

The array for which we are looking for a metric. Only its dimensions are considered.

axesiterable

A list of axes for which to find the metric.

Returns
metricxarray.DataArray

A metric which can broadcast against array

interp(self, da, axis, **kwargs)[source]

Interpolate neighboring points to the intermediate grid point along this axis.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The interpolated data

interp_2d_vector(self, vector, **kwargs)[source]

Interpolate a 2D vector to the intermediate grid point. This method is only necessary for complex grid topologies.

Parameters
vectordict

A dictionary with two entries. Keys are axis names, values are vector components along each axis.

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
vector_interpdict

A dictionary with two entries. Keys are axis names, values are interpolated vector components along each axis

max(self, da, axis, **kwargs)[source]

Maximum of neighboring points on the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The maximal data

min(self, da, axis, **kwargs)[source]

Minimum of neighboring points on the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

• None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.

• ‘fill’: Set values outside the array boundary to fill_value (i.e. a Neumann boundary condition.)

• ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The minimal data

## autogenerate¶

xgcm.autogenerate.generate_axis(ds, axis, name, axis_dim, pos_from='center', pos_to='left', boundary_discontinuity=None, pad='auto', new_name=None, attrs_from_scratch=True)[source]

Creates c-grid dimensions (or coordinates) along an axis of

Parameters
dsxarray.Dataset

Dataset with gridinformation used to construct c-grid

axisstr

The appropriate xgcm axis. E.g. ‘X’ for longitudes.

namestr

The name of the variable in ds, providing the original grid.

axis_dimstr

The dimension of ds[name] corresponding to axis. If name itself is a dimension, this should be equal to name.

pos_from{‘center’,’left’,’right’}, optional

Position of the gridpoints given in ‘ds’.

pos_to{‘left’,’center’,’right’}, optional

Position of the gridpoints to be generated.

boundary_discontinuity{None, float}, optional

If specified, marks the value of discontinuity across boundary, e.g. 360 for global longitude values and 180 for global latitudes.

If specified, determines the padding to be applied across boundary. If float is specified, that value is used as padding. Auto attempts to pad linearly extrapolated values. Can be useful for e.g. depth coordinates (to reconstruct 0 depth). Can lead to unexpected values when coordinate is multidimensional.

new_namestr, optional

Name of the inferred grid variable. Defaults to name+’_’+pos_to’

attrs_from_scratchbool, optional

Determines if the attributes are created from scratch. Should be enabled for dimensions and deactivated for multidimensional coordinates. These can only be calculated after the dims are created.

xgcm.autogenerate.generate_grid_ds(ds, axes_dims_dict, axes_coords_dict=None, position=None, boundary_discontinuity=None, pad='auto', new_name=None)[source]

Add c-grid dimensions and coordinates (optional) to observational Dataset

Parameters
dsxarray.Dataset

Dataset with gridinformation used to construct c-grid

axes_dims_dictdict

Dict with information on the dimension in ds corrsponding to the xgcm axis. E.g. {‘X’:’lon’,’Y’:’lat’}

axes_coords_dictdict, optional

Dict with information on the coordinates in ds corrsponding to the xgcm axis. E.g. {‘X’:’geolon’,’Y’:’geolat’}

position{None,tuple, dict}, optional

Position of the gridpoints given in ‘ds’ and the desired position to be generated. Defaults to (‘center’,’left’). Can be a tuple like (‘center’,’left’), or a dict with corresponding axes (e.g. {‘X’:(‘center’,’left’),’Z’:(‘left’,’center’)})

boundary_discontinuity{None, float, dict}, optional

Specifies the discontinuity at the boundary to wrap e.g. longitudes without artifacts. Can be defined globally (for all fields defined in axes_dims_dict and axes_coords_dict) {float, None} or per dataset variable (dict e.g. {‘longitude’:360,’latitude’:180})