PlasmaCalcs.addons.instability_tools.instability_xarray_accessor.itDatasetAccessor

class PlasmaCalcs.addons.instability_tools.instability_xarray_accessor.itDatasetAccessor(xarray_obj)

Bases: itAccessor

Accessor for instability theory tools on Datasets.

__init__(xarray_obj)

Methods

`__init__`(xarray_obj)
`register`(f_or_name, *[, aliases, totype, _name])
`register_attr`(name, value, *[, totype])

Attributes

`GROWMAP`
`GROWPLOT_WRAP`
`GROW_VMAX`
`GROW_VMIN`
`T_from_ldebye`
`access_type`
`access_type_to_cls`
`accessor_name`
`alias_registry`
`at_growmax`
`attrs_registry`
`grows`
`growth`
`growth_kmax`
`growthplot`
`growthplots`
`has_kdims_polar`
`has_kmod_coord`
`k`
`k_at_growmax`
`kang`
`kang_at_growmax`
`kang_dim`
`kdims`
`khat`
`khat_at_growmax`
`klims_phys`
`klims_physical`
`klines`
`kmod`
`kmod_at_growmax`
`kmod_coord`
`kmod_dim`
`kw_growthplot`
`mod_vphase`
`nonk_dims`
`omega_real`
`registered_aliases`
`registered_attrs`
`registered_methods`
`registry`
`smod_vphase`
`stack_nonk`
`stack_nonk_dims`
`tfbi0_index`
`tfbi0_index_isel`
`tfbi0_index_order`
`tfbi0_index_str`
`tfbi0_order`
`tfbi0_params`
`tfbi0_params_str`
`tfbi0i`
`tfbi0isel`
`tfbi0istr`
`tfbi0keys`
`tfbi0params`
`tfbi0str`
`vphase`
`where_grows`
`where_nogrows`

T_from_ldebye

caller of function xarray_T_from_ldebye in module PlasmaCalcs.addons.tfbi.tfbi_misc

xarray_T_from_ldebye(ds, ldebye=None, *, n=None, eps0=None, q=None, kB=None)

return T given ldebye. ldebye**2 = eps0 * kB * T / (n * q**2)

–> T = ldebye**2 * n * q**2 / (eps0 * kB)

ds: xarray.Dataset

dataset to use for inputs. Must contain ldebye data.

ldebye, n, eps0, q, kB: None, str, or value

None –> use default lookups (see below) for variable names from ds.

str –> name of variable in ds representing this physical quantity

value –> directly use this value.

quantity meanings:

ldebye: debye length n: number density (of each fluid, if multiple fluids) eps0: vacuum permittivity q: charge (of each fluid, if multiple fluids with different charges) kB: boltzmann constant

default lookups (if not provided explicitly, use first available):

ldebye: ‘ldebye’, ‘eqperp_ldebye’ n: ‘n’ eps0: ‘eps0’, DEFAULTS.PHYSICAL.CONSTANTS_SI[‘qe’] q: ‘q’, ‘qe’, ‘abs_qe’, DEFAULTS.PHYSICAL.CONSTANTS_SI[‘eps0’] kB: ‘kB’, DEFAULTS.PHYSICAL.CONSTANTS_SI[‘kB’]

at_growmax

caller of function xarray_at_growmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_at_growmax(array, growth=None)

returns array where growth rate is maxxed across k dims from array.

array: xarray.DataArray, or xarray.Dataset

result == array.isel(location where growth is maxxed across k dims).

if growth is None, array also tells growth rates via array.it.growth.

growth: None, xarray.DataArray or xarray.Dataset

None –> use array.it.growth

DataArray –> growth rates (if real) or omega (if complex).

Dataset –> get growth from ds[‘omega’].imag.

grows: caller of function xarray_grows in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_grows(array)

returns boolean array telling where input growth rate (maxxed across k) > 0.

Equivalent: xarray_growth_kmax(array) > 0.

growth = array if real DataArray; imag(array) if complex DataArray; ds[‘omega’].imag if Dataset.

property growth: growth rate. ds[‘omega’].rename(‘imag_omega’).

growth_kmax: caller of function xarray_growth_kmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_growth_kmax(array)

returns growth rate, maxxed across k dims.

For DataArrays, assumes array is an array of growth rates (if real) or omega (if complex).

For Datasets, gets growth from ds[‘omega’].

growthplot

caller of function xarray_growthplot in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_growthplot(array, *, klines=None, **kw)

like array.pc.image, but with default kwargs from kw_growthplot.

Also, plots array.it.growth.

(E.g. if array is complex, use array.imag instead.

and if array is actually a Dataset, use array[‘omega’].imag instead.)

klines: None, bool, or dict

whether to plot lines representing mean free paths, and debye lengths.

None –> True if input was a Dataset; False if it was a DataArray.

(cannot infer klims from DataArray of growth values.)

if dict, use as kwargs for xarray_klines.

growthplots

caller of function xarray_growthplots in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_growthplots(array, *, klines=None, **kw)

like array.pc.subplots, but with default kwargs from kw_growthplot.

Also, plots array.it.growth.

(E.g. if array is complex, use array.imag instead.

and if array is actually a Dataset, use array[‘omega’].imag instead.)

Also, if array has kdims, and has only 1 nonk_dim, use defaults:

row = the nonkdim,

wrap = 6 if array.sizes[nonk dim] > 6. (actually itAccessor.GROWPLOT_WRAP; default 6.)

klines: None, bool, Dataset, dict, or tuple of (Dataset, dict)

whether to plot lines representing mean free paths, and debye lengths, on each subplot.

None –> True if input was a Dataset; False if it was a DataArray.

(cannot infer klims from DataArray of growth values.)

Dataset –> use to infer klims. Use only default kwargs for xarray_klines.

dict –> use as kwargs for xarray_klines. infer klims from array input (must be a Dataset).

tuple –> (Dataset, dict). use dataset to infer klims; use dict as xarray_klines kwargs.

Internally, uses different kwarg defaults than xarray_klines. Defaults here:

label = ‘{shortvar} ({fluid})’

add_legend = True for axs[0,0], False for all other plots.

log = infer from ylabel of top-left ax (if direction==’h’, else xlabel of bottom left.)

property has_kdims_polar: whether the object has 2D polar kdims. I.e. one kmod_dim, and one kang_dim.

property has_kmod_coord: whether the object has a kmod coordinate. I.e. one of [‘kmod’, ‘log_kmod’].

k: caller of function xarray_k in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_k(array)

returns wavevector as a vector in the x-y plane.

(result will still have z component, but its value will be 0 everywhere.)

k_at_growmax: caller of function xarray_k_at_growmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_k_at_growmax(array)

returns k (vector) where growth rate is maxxes across k.

result varies with ‘component’, with x corresponding to kang = 0 degrees,

and z not included (i.e., assumes k is 2D in the x-y plane).

property kang: wavevector angle. array[‘kang’].

kang_at_growmax: caller of function xarray_kang_at_growmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_kang_at_growmax(array)

returns kang where growth rate is maxxed across k.

growth = array if real DataArray; imag(array) if complex DataArray; ds[‘omega’].imag if Dataset.

property kang_dim: name of the dimension associated with wavevector angle.

E.g. ‘kang’.

Checks: [‘kang’]

property kdims: list of dimensions associated with wavevector. E.g. [‘kmod_dim’, ‘kang’].

Checks: [‘kmod_dim’, ‘log_kmod_dim’, ‘kmod’, ‘log_kmod’, ‘kang’]

khat: caller of function xarray_khat in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_khat(array)

returns unit vector in the kang direction.

khat_at_growmax: caller of function xarray_khat_at_growmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_khat_at_growmax(array)

returns khat for kang where growth rate is maxxed across k.

growth = array if real DataArray; imag(array) if complex DataArray; ds[‘omega’].imag if Dataset.

property klims_phys: alias to klims_physical

klims_physical

caller of function xarray_klims_physical in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_klims_physical(ds, *, to_simple=False)

return copy of dataset, but also having the physical values limiting k.
if ds has ‘ldebye’, result[‘kdebye’] = 2*pi/ldebye.
if ds has ‘lmfp’, result[‘kmfp’] = 2*pi/lmfp.

(similarly, recognizes ‘eqperp_ldebye’ and ‘eqperp_lmfp’;

result keys would be ‘eqperp_kdebye’ and ‘eqperp_kmfp’.)

if result does not have anything to indicate any klims_physical in it, raise InputError.

to_simple: bool

whether to instead return result as a dict containing:

(if any debye length specifiers exist in ds):

‘kdebye_lim’: result[kdebye var]

‘kdebye_var’: kdebye var name

(if any mean free path specifiers exist in ds):

‘kmfp_lim’: result[kmfp var]

‘kmfp_var’: kmfp var name

In this case, if multiple specifiers exist, crash.

klines

caller of function xarray_klines in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_klines(ds, *, log=None, mfp={‘lw’: 2, ‘color’: ‘blue’}, debye={‘lw’: 2, ‘color’: ‘red’}, fluids=None, fluid_styles=UNSET, direction=’h’, label=’({val:.3g}) {log}{shortvar} ({fluid})’, add_legend=True, legend_kw=UNSET, **kw_line)

draw lines representing mean free path, and debye length, on a plot with a |k| axis.

ds: Dataset

dataset containing klims_physical values. (see: xarray_klims_physical)

(at least one of: ‘ldebye’, ‘lmfp’, ‘eqperp_ldebye’, ‘eqperp_lmfp’,

‘kdebye’, ‘kmfp’, ‘eqperp_kdebye’, ‘eqperp_kmfp’.)

log: None or bool

whether to plot log10 of values, instead of just the values themselves.

None –> True if plt.gca() axis label has ‘log_’ in it, else False.

(ylabel if direction says axhline; else xlabel.)

mfp: dict or False

style to apply to mean free path lines.

False –> don’t plot mean free path lines.

debye: dict or False

style to apply to debye length lines.

False –> don’t plot debye length lines.

fluids: None, ‘min’, ‘max’, or (‘min’, ‘max’)

None –> plot lines for each fluid.

‘min’ –> plot line for only 1 fluid, whichever makes line at smallest |k|

‘max’ –> plot line for only 1 fluid, whichever makes line at largest |k|

(‘min’, ‘max’) –> plot ‘min’ and ‘max’ lines.

note: to plot an arbitrary subset of fluids, just use ds.isel(fluid=…) beforehand.

fluid_styles: UNSET or dict of lists

styles to ensure fluid lines appear visually distinct.

E.g. {‘ls’: [‘-’, ‘–’, ‘:’]} –> use ls=’-’ for first fluid, ‘–’ for next, etc.

UNSET –> use DEFAULTS.PLOT.TIMELINES_CYCLE1; default is a dict of different linestyles.

direction: ‘h’, ‘v’, ‘horizontal’, or ‘vertical’

direction to plot lines.

‘h’ or ‘horizontal’ –> plt.axhline

‘v’ or ‘vertical’ –> plt.axvline

label: str

label for each line. will be hit by .format(…) with the following kwargs:

‘log’: ‘log10 ‘ if log else ‘’.

‘var’: variable name. ‘kdebye’, ‘kmfp’, ‘eqperp_kdebye’, or ‘eqperp_kmfp’.

‘kvar’: alias to ‘var’

‘lvar’: length variable name. E.g. ‘ldbeye’ instead of ‘kdebye’.

‘pubvar’: variable suitable for publication. ‘k Debye’ or ‘k mean free path’

‘shortvar’: shorthand variable name. ‘debye’ or ‘mfp’

‘fluid’: fluid name

‘val’: value at which the line is plotted

add_legend: bool

whether to plt.legend()

legend_kw: UNSET or dict

kwargs to pass to plt.legend().

UNSET –> use DEFAULTS.ADDONS.GROWTHPLOT_LEGEND_KW

additional kwargs go to plt.axhline or plt.axvline.

property kmod: wavevector magnitude. probably array[kmod_coord]. 10**result if kmod_coord starts with ‘log_’.

kmod_at_growmax: caller of function xarray_kmod_at_growmax in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_kmod_at_growmax(array)

returns kmod where growth rate is maxxed across k.

growth = array if real DataArray; imag(array) if complex DataArray; ds[‘omega’].imag if Dataset.

property kmod_coord: name of the coordinate associated with wavevector magnitude.

E.g. ‘kmod’.

Checks: [‘kmod’, ‘log_kmod’].

property kmod_dim: name of the dimension associated with wavevector magnitude.

E.g. ‘kmod_dim’.

Checks: [‘kmod_dim’, ‘log_kmod_dim’, ‘kmod’, ‘log_kmod’]

kw_growthplot: caller of function xarray_kw_growthplot in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_kw_growthplot(array, **kw_override)

returns kwargs to use for a growth rate plot (using imshow-style kwargs).

if array has_kdims_polar, use default polar=True,

and default y=array.it.kmod_coord if it starts with ‘log’, else ‘log_{kmod_coord}’,

if using polar=True, use default axsize of (2,3), and grid=True.

mod_vphase: caller of function xarray_mod_vphase in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_mod_vphase(array)

returns magnitude of phase velocity: mod_vphase = |real(omega)| / |k|.

Phase velocity tells wave propagation speed. Group velocity tells wave envelope speed.

For DataArrays, assumes array is an array of real(omega) if real, or omega (if complex).

For Datasets, gets omega from ds[‘omega’].

See also: smod_phase, vphase.

property nonk_dims: list of dimensions associated with ds[‘omega’] but excluding kdims.

Guaranteed to be sorted into alphabetical order.

property omega_real: real part of omega. ds[‘omega’].rename(‘real_omega’).

classmethod register(f_or_name, *, aliases=[], totype=UNSET, _name=None)

attaches method which applies f(self.obj, *args, **kw) to xr.DataArray.pc.{name}, then returns f.

(in general, use cls.accessor_name, not necessarily ‘pc’; ‘pc’ is for pcAccessor.)

This ensures f can be accessed via xr.DataArray.pc.{name} or xr.Dataset.pc.{name}.

pcAccessor.register –> available on both DataArrays and Datasets.
pcArrayAccessor.register –> available on DataArrays only.
pcDatasetAccessor.register –> available on Datasets only.

f_or_name: str or callable: str –> returns a function: f -> register(f, name=f_or_name)

callable –> register this function then return it.

will be registered at _name if provided, else at f.__name__.

This enables this method to be used directly as a decorator, or as a decorator factory.
aliases: list of str: aliases for f. Create alias property for each of these.
totype: UNSET, None, ‘array’, or ‘dataset’: which type of xarray objects the registered method applies to.

UNSET –> use cls.access_type.

None –> methods apply to both DataArrays and Datasets.

‘array’ –> methods apply to DataArrays only

‘dataset’ –> methods apply to Datasets only.
_name: str, optional: name to register f at. If not provided, use f.__name__.

Not intended to be provided directly.

Examples (using pcAccessor subclass for concreteness):

@pcAccessor.register

def my_method1(xarray_object, arg1):

print(arg1)

print(xarray_obj)

xr.DataArray(data).pc.my_method1(7) # prints 7 then prints DataArray(data).

xr.Dataset(data).pc.my_method1(5) # prints 5 then prints Dataset(data).

@pcAccessor.register(name=’my_method2’, totype=’array’)

def xarray_my_method2(xarray_object):

print(xarray_object * 10)

xr.DataArray(data).pc.my_method2() # prints 10*DataArray(data).

xr.Dataset(data).pc.my_method2() # crashes; my_method2 not registered to datasets.

classmethod register_attr(name, value, *, totype=UNSET)

register cls.{name} = value, using a similar interface as cls.register.

when totype is UNSET, this is equivalent to:

cls.{name} = value; cls.attrs_registry[name] = (cls.access_type, value),

when totype is provided, use cls=cls.access_type_to_cls[totype], instead.

returns value, after doing setattr(cls, name, value)

totype: UNSET, None, ‘array’, or ‘dataset’: which type of xarray objects the registered attr applies to.

UNSET –> use cls.access_type.

None –> methods apply to both DataArrays and Datasets.

‘array’ –> methods apply to DataArrays only

‘dataset’ –> methods apply to Datasets only.

Examples (using pcAccessor subclass for concreteness):

pcAccessor.register_attr(‘MY_CONSTANT1’, 7)
pcAccessor.register_attr(‘MY_CONSTANT2’, 5, totype=’array’)
pcAccessor.register_attr(‘nMbytes’, property(lambda self: self.obj.nbytes/1024**2))
arr = xr.DataArray(some_data)
ds  = xr.Dataset(other_data)
arr.pc.MY_CONSTANT1  # == 7
ds.pc.MY_CONSTANT1   # == 7
arr.pc.MY_CONSTANT2  # == 5
ds.pc.MY_CONSTANT2   # crashes; MY_CONSTANT2 not registered to datasets.
arr.pc.nMbytes       # == DataArray(data).nbytes/1024**2
ds.pc.nMbytes        # == Dataset(data).nbytes/1024**2

smod_vphase: caller of function xarray_smod_vphase in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_smod_vphase(array)

returns signed magnitude of phase velocity: smod_vphase = real(omega) / |k|.

(result’s sign is same sign as real(omega).)

Phase velocity tells wave propagation speed. Group velocity tells wave envelope speed.

For DataArrays, assumes array is an array of real(omega) if real, or omega (if complex).

For Datasets, gets omega from ds[‘omega’].

See also: mod_vphase, vphase.

property stack_nonk: alias to stack_nonk_dims

stack_nonk_dims

caller of function xarray_stack_nonk_dims in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_stack_nonk_dims(growth, target=None, stackdim=’nonk’, *, order=None)

return target stacked along nonk dims.

growth: DataArray or Dataset

xarray object containing growth info.

real DataArray –> growth tells growth rates.

complex DataArray –> growth tells omega; rates = omega.imag.

Dataset –> growth rates = ds[‘omega’].imag

target: None, str, DataArray, or Dataset

xarray object of interest.

stackdim: str

name of the new stacked dimension.

order: None or list of str

if provided, prefer dimensions in this order.

all dims not in order will be sorted alphabetically.

Examples:

dsR = xr.Dataset(…)  # dataset containing omega and maybe some other values
dsR.it.nonk_stack()   # dataset, stacking all nonk_dims
dsR.it.nonk_stack(array)   # array, stacking all nonk_dims

property tfbi0_index: alias to tfbi0i

property tfbi0_index_isel: alias to tfbi0isel

property tfbi0_index_order: alias to tfbi0_order

property tfbi0_index_str: alias to tfbi0istr

property tfbi0_order: standard order of parameters within “type-0” tfbi hypercube, i.e.:

(‘EBspeed’, ‘Tgrid’, ‘ionfrac_H’, ‘kappae’, ‘ngrid’)

property tfbi0_params: alias to tfbi0params

property tfbi0_params_str: alias to tfbi0str

tfbi0i: caller of function tfbi0_index in module PlasmaCalcs.addons.tfbi.tfbi_misc

tfbi0_index(array)

returns a 5-tuple of indexes corresponding to this point within “type-0” tfbi hypercube.

indexes from coords: (‘EBspeed_index’, ‘Tgrid_index’, ‘ionfrac_H_index’, ‘kappae_index’, ‘ngrid_index’)

tfbi0isel: caller of function tfbi0_index_isel in module PlasmaCalcs.addons.tfbi.tfbi_misc

tfbi0_index_isel(array, tfbii0)

returns a dict of {param: index} given the 5 indexes within “type-0” tfbi hypercube.

Result has keys: (‘EBspeed’, ‘Tgrid’, ‘ionfrac_H’, ‘kappae’, ‘ngrid’),

tfbii0: 5-tuple of indexes for those 5 params, in that order ^

tfbi0istr: caller of function tfbi0_index_str in module PlasmaCalcs.addons.tfbi.tfbi_misc

tfbi0_index_str(array)

returns a string of indexes corresponding to this point within “type-0” tfbi hypercube.

indexes from coords: (‘EBspeed_index’, ‘Tgrid_index’, ‘ionfrac_H_index’, ‘kappae_index’, ‘ngrid_index’)

Format will be like: (0,0,0,0,0)

property tfbi0keys: alias to tfbi0_order

tfbi0params: caller of function tfbi0_params in module PlasmaCalcs.addons.tfbi.tfbi_misc

tfbi0_params(array)

returns a dict of {param: value} for a point within “type-0” tfbi hypercube.

Result has keys: (‘EBspeed’, ‘Tgrid’, ‘ionfrac_H’, ‘kappae’, ‘ngrid’)

if param values are DataArray scalars, use .item() to convert to scalars.

tfbi0str: caller of function tfbi0_params_str in module PlasmaCalcs.addons.tfbi.tfbi_misc

tfbi0_params_str(array, fmt=’.3g’)

returns a string telling param values for a point within “type-0” tfbi hypercube.

Result looks like: EBspeed=val, Tgrid=val, ionfrac_H=val, kappae=val, ngrid=val

vphase: caller of function xarray_vphase in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_vphase(array)

returns phase velocity (vector): vphase = (real(omega) / |k|) * khat.

Phase velocity tells wave propagation speed. Group velocity tells wave envelope speed.

For DataArrays, assumes array is an array of real(omega) if real, or omega (if complex).

For Datasets, gets omega from ds[‘omega’].

See also: smod_vphase, mod_vphase.

where_grows

caller of function xarray_where_grows in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_where_grows(growth, target=None, *, drop=UNSET)

return target where growth > 0. Roughly: target.where(xarray_grows(growth)).

(or, growth.where(xarray_grows(growth)) if target is None).

growth: DataArray or Dataset

xarray object containing growth info.

real DataArray –> growth tells growth rates.

complex DataArray –> growth tells omega; rates = omega.imag.

Dataset –> growth rates = ds[‘omega’].imag

target: None, str, DataArray, or Dataset

xarray object of interest.

result tells target.where(grows).

drop: UNSET or bool

whether to drop as many nan values as possible from the result.

UNSET –> True if growth_kmax has ndim==1, else False.

(when growth_kmax has ndim==1, it’s a list of points, easy to fully drop nans.

when ndim>=2, might not be able to drop all the nans,

e.g. if (x,y)=(0,0) is nan but (0,1) and (1,0) are not, cannot drop (0,0).)

Examples:

dsR = xr.Dataset(…)  # dataset containing omega and maybe some other values
dsR.it.where_grows()   # dataset where growth rate > 0 for any k. (i.e. dataset where dsR.it.grows())
dsR.it.where_grows(drop=False)   # dataset where_grows() but keep all nan regions.
dsR.it.where_grows(array)   # array where dsR.it.grows().
# array where dsR.it.grows(), but assign array coords’ original indexes as coords.
#  e.g. if ‘_mask_stack’ in array coords, result will have ‘_mask_stack_index’ too.
dsR.it.where_grows(array.pc.index_coords())

where_nogrows

caller of function xarray_where_nogrows in module PlasmaCalcs.addons.instability_tools.instability_theory_tools

xarray_where_nogrows(growth, target=None, *, drop=UNSET)

return target where growth <= 0. Roughly: target.where(~xarray_grows(growth)).

(or, growth.where(~xarray_grows(growth)) if target is None).

growth: DataArray or Dataset

xarray object containing growth info.

real DataArray –> growth tells growth rates.

complex DataArray –> growth tells omega; rates = omega.imag.

Dataset –> growth rates = ds[‘omega’].imag

target: None, str, DataArray, or Dataset

xarray object of interest.

result tells target.where(~grows).

drop: UNSET or bool

whether to drop as many nan values as possible from the result.

see xarray_where_grows (or itAccessor.where_grows.f) for more details.