xgcm.as_grid_ufunc#
- xgcm.as_grid_ufunc(signature: str = '', boundary_width: Optional[Mapping[str, Tuple[int, int]]] = None, **kwargs) Callable[source]#
Decorator which turns a numpy ufunc into a “grid-aware ufunc”.
- Parameters
- ufunccallable
Function to call like func(*args, **kwargs) on numpy-like unlabeled arrays (.data). Passed directly on to xarray.apply_ufunc.
- signaturestring
Grid universal function signature. Specifies the xgcm.Axis names and positions for each input and output variable, e.g.,
"(X:center)->(X:left)"fordiff_center_to_left(a).- boundary_widthDict[str: Tuple[int, int], optional
The widths of the boundaries at the edge of each array. Supplied in a mapping of the form {axis_name: (lower_width, upper_width)}.
- boundary{None, ‘fill’, ‘extend’, ‘extrapolate’, dict}, optional
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 Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)
‘extrapolate’: Set values by extrapolating linearly from the two points nearest to the edge
Optionally a dict mapping axis name to separate values for each axis can be passed.
- fill_value{float, dict}, optional
The value to use in boundary conditions with boundary=’fill’. Optionally a dict mapping axis name to separate values for each axis can be passed. Default is 0.
- dask{“forbidden”, “allowed”, “parallelized”}, default: “forbidden”
How to handle applying to objects containing lazy data in the form of dask arrays. Passed directly on to xarray.apply_ufunc.
- map_overlapbool, optional
Whether or not to automatically apply the function along chunked core dimensions using dask.array.map_overlap. Default is False. If True, will need to be accompanied by dask=’allowed’.
- **kwargs
Keyword arguments are passed directly onto xarray.apply_ufunc. (As such then kwargs should not be xarray data objects, as they will not be subject to alignment, nor downcast to numpy-like arrays.)
- Returns
- grid_ufunccallable
Function which consumes and produces xarray objects, whose xgcm Axis names and positions must conform to the pattern specified by signature. Function has an additional positional argument grid, of type xgcm.Grid, and another additional positional argument axis, of type Sequence[Tuple[str]], so that func’s new signature is func(grid, *args, axis, **kwargs). The grid and axis arguments are passed on to apply_grid_ufunc.