XarrayGrid

class PlasmaCalcs.tools.xarray_tools.xarray_grids.XarrayGrid(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_min=UNSET, N_max=UNSET)

Bases: object

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.

Methods

`__call__`()	return grid from self.
`array_grid`()	return grid from array min to array max, with self.get_N() points along grid dimension.
`get_N`()	return N, appropriate given self.inclusive.
`get_N_full`()	return N as if inclusive=(True, True).
`get_lims`()	return (self.min, self.max), inferring (from span or ratio) if needed.
`init_labels`(*, name, dim, math_coord)	initialize self.name, dim, and math_coord, using defaults if needed.
`init_lims`(*, min, max, span, ratio)	initialize self.min, max, span, and ratio.
`init_step_params`(*, N, step, logspace, ...)	initialize N, step, logspace, logstep, inclusive from kwargs.
`math_grid01`()	return XarrayGrid(0, 1, N=self.get_N()).grid(), maybe removing endpoints (see: inclusive),
`scalar_grid`()	return grid from scalar min to scalar max, with int(self.get_N()) points.
`_adjust_if_nonint_N`(min, max, N, inclusive)	returns min, max, N, and inclusive; adjusted appropriately if N is not an integer.

Attributes

`DEFAULT_DIM`
`NORMED_COORD`
`N_max`
`N_min`
`grid`	alias to __call__

__call__(): return grid from self.

_adjust_if_nonint_N(min, max, N, inclusive): returns min, max, N, and inclusive; adjusted appropriately if N is not an integer.

(if N is an integer, returns min, max, N unchanged.)

(N should be N_full, i.e. the value of N as if inclusive=(True, True); e.g. from self.get_N_full())

The adjustment depends on self.inclusive.

if inclusive = (True, True), crash.

else, use original step (or logstep) while dropping the input value for max or min.

(if inclusive=(False, True), keep original max, adjust original min;

else, adjust original max, keep original min.)

N will always be rounded down to the nearest integer.

array_grid(): return grid from array min to array max, with self.get_N() points along grid dimension.

fails with InputError if min and max are both not arrays (i.e. not self.array_lims)

get_N()

return N, appropriate given self.inclusive.

might return a non-integer; if that occurs, self.grid() will handle it properly.

get_N_full(): return N as if inclusive=(True, True). infer N if needed,

and ensuring actual N is within acceptable range N_min < N < N_max.

might return a non-integer; if that occurs, self.grid() will handle it properly.

get_lims(): return (self.min, self.max), inferring (from span or ratio) if needed.

property grid: alias to __call__

init_labels(*, name, dim, math_coord): initialize self.name, dim, and math_coord, using defaults if needed.

result depends on whether self.min and max are arrays (i.e. self.array_lims).

See help(type(self)) for more details.

init_lims(*, min, max, span, ratio): initialize self.min, max, span, and ratio. Also calls callables.

Also sets self.array_lims = bool (True if min or max is an array).

Also, if provided min and max, but np.any(min > max), raise InputConflictError.

init_step_params(*, N, step, logspace, logstep, inclusive): initialize N, step, logspace, logstep, inclusive from kwargs.

Also sets self.step_param = ‘N’, ‘step’, or ‘logstep’

math_grid01(): return XarrayGrid(0, 1, N=self.get_N()).grid(), maybe removing endpoints (see: inclusive),

and labeled for helping with array_grid().

scalar_grid(): return grid from scalar min to scalar max, with int(self.get_N()) points.

fails with InputError if min or max are arrays (i.e. if self.array_lims.)