API

Axis

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

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)

Create a new Axis object from an input dataset.

Parameters:
ds : xarray.Dataset

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

axis_name : str

The name of the axis (should match axis attribute)

periodic : bool, optional

Whether the domain is periodic along this axis

default_shifts : dict, optional

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

coords : dict, 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)

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

Parameters:
da : xarray.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_cum : xarray.DataArray

The cumsummed data

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

Difference neighboring points to the intermediate grid point.

Parameters:
da : xarray.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_i : xarray.DataArray

The differenced data

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

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

Parameters:
da : xarray.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_i : xarray.DataArray

The interpolated data

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

Maximum of neighboring points on intermediate grid point.

Parameters:
%(neighbor_binary_func.parameters.no_f)s
Returns:
da_i : xarray.DataArray

The differenced data

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

Minimum of neighboring points on intermediate grid point.

Parameters:
da : xarray.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_i : xarray.DataArray

The differenced data

Grid

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

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)

Create a new Grid object from an input dataset.

Parameters:
ds : xarray.Dataset

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

check_dims : bool, 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_shifts : dict

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

face_connections : dict

Grid topology

coords : dict, 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.

References

[1]Comodo Conventions http://pycomodo.forge.imag.fr/norm.html
cumsum(self, da, axis, **kwargs)

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

Parameters:
axis : str

Name of the axis on which to act

da : xarray.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_i : xarray.DataArray

The cumsummed data

diff(self, da, axis, **kwargs)

Difference neighboring points to the intermediate grid point.

Parameters:
axis : str

Name of the axis on which to act

da : xarray.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_i : xarray.DataArray

The differenced data

diff_2d_vector(self, vector, **kwargs)

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

Parameters:
vector : dict

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

da : xarray.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_diff : dict

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

interp(self, da, axis, **kwargs)

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

Parameters:
axis : str

Name of the axis on which to act

da : xarray.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_i : xarray.DataArray

The interpolated data

interp_2d_vector(self, vector, **kwargs)

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

Parameters:
vector : dict

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

da : xarray.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_interp : dict

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

max(self, da, axis, **kwargs)

Maximum of neighboring points on the intermediate grid point.

Parameters:
axis : str

Name of the axis on which to act

da : xarray.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_i : xarray.DataArray

The maximal data

min(self, da, axis, **kwargs)

Minimum of neighboring points on the intermediate grid point.

Parameters:
axis : str

Name of the axis on which to act

da : xarray.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_i : xarray.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)

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

Parameters:
ds : xarray.Dataset

Dataset with gridinformation used to construct c-grid

axis : str

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

name : str

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

axis_dim : str

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.

pad : {‘auto’, None, float}, optional

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_name : str, optional

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

attrs_from_scratch : bool, 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)

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

Parameters:
ds : xarray.Dataset

Dataset with gridinformation used to construct c-grid

axes_dims_dict : dict

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

axes_coords_dict : dict, 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})

pad : {‘auto’, None, float}, optional

Specifies the padding at the boundary to extend values past the boundary. 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. {‘z’:’auto’,’latitude’:0.0})

new_name : str, optional

Name of the inferred grid variable. Defaults to name+’_’+position[1]