PlasmaCalcs.tools.xarray_tools.xarray_grids.xarray_grid

PlasmaCalcs.tools.xarray_tools.xarray_grids.xarray_grid(min=None, max=None, N=None, name='grid', *, step=None, span=None, ratio=None, logspace=None, logstep=None, inclusive=(True, True), reverse=False, dim=None, math_coord=False, N_max=UNSET, N_min=UNSET)

create and return a grid, via XarrayGrid(…).grid().

(If you want to inspect the grid-making process more closely, use XarrayGrid instead)

XarrayGrid docs copied below for convenience:

———————————————

class to help with making xarray.DataArray grids.

call self (e.g.: self()) or self.grid() to get the grid as an xarray.DataArray.

intended to be “immutable” after creation;

altering self.min, self.max or other attrs may produce unexpected results.

Inputs and outputs will always be in linear space (even if logspace=True)!

— Params related to lims —

min: None, number, DataArray, or callable

min value (or array of min values)

None –> infer from max and other params.

callable f –> infer min = f(max)

max: None, number, DataArray, or callable

max value (or array of max values)

None –> infer from min and other params.

callable f –> infer max = f(min)

span: None or number

max - min. None = “unspecified”.

only allowed if min or max is None.

ratio: None or number

max / min. None = “unspecified”.

only allowed if min or max is None.

— Params related to grid size & spacing —

N: None or number

number of points in grid. None = “unspecified”

step: None or number

step size between points (in linear space). None = “unspecified”

if provided, implies logspace=False.

logspace: None or bool

whether the grid will be evenly spaced in log-space.

None –> True if provided logstep; False if provided N or step.

True –> must have provided N or logstep.

False –> must have provided N or step.

logstep: None or number

step size between points, in log-space (base 10). None = “unspecified”

if provided, implies logspace=True.

inclusive: tuple of 2 bools

whether to include min and max in the output.

reverse: bool

whether to reverse the output when creating grid.

Equivalent to using result.isel(grid_dim=slice(None, None, -1)),

but replacing ‘grid_dim’ with the appropriate name.

— Other params —

name: str

result.name; also result.assign_coords({name:result})

(ops with result keep coords[name], e.g. result + 10, or result * other_array)

dim: None or str

grid dimension. For scalar min & max, dim=name works great & intuitively.

However, when self.array_lims, dim cannot equal name,

because result will be n+1 dimensional (n=ndims from max-min),

so setting result.assign_coords({name:result}) would fail if name is a dim.

None –> dim=name if not self.array_lims else ‘{name}_dim’

str –> use dim.format(name=name).

math_coord: bool or str

whether to add coord related to the grid-producing math, if self.array_lims.

default name ‘{name}_normed’, with values a 1D array from 0 to 1, such that:

if linspace, result = min + (max - min) * coord

if logspace, result = 10**(log10(min)+(log10(max)-log10(min))*coord)

str –> use this coord, after doing math_coord.format(name=name).

N_min: UNSET, None or number

if provided, tells minimum allowed number of points in grid.

None –> no minimum. UNSET –> use type(self).N_min (default=2)

N_max: UNSET, None or number

if provided, tells maximum allowed number of points in grid.

None –> no maximum. UNSET –> use type(self).N_max (default=1e8)

— notes about result coords —

result.name = name

result.coords[name] == result.

result.dims = [dim, *dims from min and/or max (broadcasted appropriately)]

If inputs are scalars:

dim = name, unless explicitly provided dim.

Either way, then use dim.format(name=name).

result.dims = [dim]

if dim == name, no additional coords added to result,

otherwise, add coord: result[name] = result.

If inputs are arrays,

dim = ‘{name}_dim’ unless explicitly provided.

Either way, then use dim.format(name=name).

result.dims = [dim, *dims from min and/or max]

dim == name is NOT allowed.

always add coord: result[name] = result

if math_coord=True, may also add coord ‘{name}_normed’

— bookkeeping - values computed during init —

(__init__ computes these. Here is some documentation about what they mean.)

self.step_param: ‘N’, ‘step’, or ‘logstep’

tells which step-related param was provided.

(exactly 1 of these must be provided, else will crash.)

self.array_lims: bool

tells whether min or max is an array.