PlasmaCalcs.tools.xarray_tools.xarray_grids.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.

__init__(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)

Methods

__init__([min, max, N, name, step, span, ...])
array_grid()
get_N()
get_N_full()
get_lims()
init_labels(*, name, dim, math_coord)
init_lims(*, min, max, span, ratio)
init_step_params(*, N, step, logspace, ...)
math_grid01()
scalar_grid()

Attributes

DEFAULT_DIM
NORMED_COORD
N_max
N_min
grid

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