xgcm.apply_as_grid_ufunc
xgcm.apply_as_grid_ufunc#
- xgcm.apply_as_grid_ufunc(func: Callable, *args: Union[xarray.core.dataarray.DataArray, Dict[str, xarray.core.dataarray.DataArray]], axis: Optional[Sequence[Sequence[str]]] = None, grid: Optional[Grid] = None, signature: Union[str, xgcm.grid_ufunc._GridUFuncSignature] = '', boundary_width: Optional[Mapping[str, Tuple[int, int]]] = None, boundary: Optional[Union[str, Mapping[str, str]]] = None, fill_value: Optional[Union[float, Mapping[str, float]]] = None, keep_coords: bool = True, dask: Literal['forbidden', 'parallelized', 'allowed'] = 'forbidden', map_overlap: bool = False, pad_before_func: bool = True, other_component: Optional[Union[Dict[str, xarray.core.dataarray.DataArray], Sequence[Dict[str, xarray.core.dataarray.DataArray]]]] = None, **kwargs) List[Any][source]#
Apply a function to the given arguments in a grid-aware manner.
The relationship between xgcm axes on the input and output are specified by signature. Wraps xarray.apply_ufunc, but determines the core dimensions from the grid and signature passed.
- Parameters
- funcfunction
Function to call like func(*args, **kwargs) on numpy-like unlabeled arrays (.data).
Passed directly on to xarray.apply_ufunc.
- *argsxarray.DataArray
One or more input argument to apply the function to. Inputs can be either scalar fields (xr.Dataarray) Or vector components (Dictionaries mapping the axis parallel to the vector direction to an xr.Dataarray). If vector components are provided, complex grids may require input to other_component (see below).
- axisSequence[Sequence[str]], optional
Names of xgcm.Axes on which to act, for each array in args. Multiple axes can be passed as a sequence (e.g.
['X', 'Y']). Function will be executed over all Axes simultaneously, and each Axis must be present in the Grid.- gridxgcm.Grid
- The xgcm Grid object which contains the various xgcm.Axis named in the axis kwarg, with positions matching the
first half of the signature.
- signaturestring
Grid universal function signature. Specifies the relationship between xgcm.Axis positions before and after the operation for each input and output variable, e.g.,
signature="(X:center)->(X:left)"for ``func=diff_center_to_left(a)`.The axis names in the signature are dummy variables, so do not have to present in the Grid. Instead, these dummy variables will be identified with the actual named Axes in the axis kwarg in order of appearance. For instance,
"(Z:center)->(Z:left)"is equivalent to"(X:center)->(X:left)"- both choices of signature require only that there is exactly one xgcm.Axis name in axis which exists in Grid and starts on position center.- boundary_widthDict[str: Tuple[int, int]
The widths of the boundaries at the edge of each array. Supplied in a mapping of the form {dummy_axis_name: (lower_width, upper_width)}. The axis names here are again dummy variables, each of which must be present in the signature.
- 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’.
- pad_before_funcbool, optional
Whether padding should occur before applying func or after it. Default is True. (For no padding at all pass boundary_width=None).
- other_componentUnion[None, Dict[str,xr.DataArray], Sequence[Dict[str,xr.DataArray]]], default: None
Matching vector component for input provided as dictionary. Needed for complex vector padding. For multiple arguments, other_components needs to provide one element per input.
- **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
- results
The result of the call to xarray.apply_ufunc, but including the coordinates given by the signature, which are read from the grid. Output is either a single object or a tuple of such objects.