# 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.) 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.) 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.) 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 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.) 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.) 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.) 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.) 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.) 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.) 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.) 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.) 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]