PlasmaCalcs.addons.tfbi.tfbi_loader.TfbiLoader

class PlasmaCalcs.addons.tfbi.tfbi_loader.TfbiLoader

Bases: QuantityLoader

quantities related to the Thermal Farley Buneman Instability.

NOTE: for simple calculations, consider using maindims_means=True!

To solve TFBI theory, you can use the following pattern:

import tfbi_theory as tt
import PlasmaCalcs as pc
cc = … # any PlasmaCalculator object from PlasmaCalcs.
ds0 = cc.tfbi_ds()
kp = tt.kPickerLowres(ds0)
dsk = kp.get_ds()   # copy of ds0, but with ds[‘k’] = k from kPicker.
drel = tt.TfbiDisprelC.from_ds(dsk)
dsR = drel.solve()  # copy of dsk, but with ds[‘omega’] = solution to TFBI theory!

Notes:

if cc has more than ~4 ions, you will want to drop some or group them somehow.

e.g. for MhdMultifluidCalculator, before calling tfbi_ds():

cc.use_mix_heavy_ions(0.3, m_mean_mode=’density’)

You can also pick ions directly during cc.tfbi_ds().

e.g. for Bifrost chromosphere analysis, where n[He_II] < 1e-6 * ne, I use:

cc.tfbi_ds(ions=[i for i in cc.fluids if i.q==1 and i!=’He_II’])

After finishing solving, you might want to save the result,

e.g. dsR.pc.save(‘filename’) saves result to ‘filename.pcxarr’;

can load it later via pc.xarray_load(‘filename.pcxarr’).

__init__()

Methods

`__init__`()
`attach_extra_coords`(arr)
`cls_help`([qstr, only, tree, modules, ...])
`cls_var_tree`(var, *[, missing_ok])
`copy`()
`direct_overrides_dynamic`()
`get_behavior`([keys])
`get_cached_tfbi_vs_EBspeed`()
`get_set_or_cached`(var)
`get_tfbi_EBspeed_grid`()
`get_tfbi_EBspeed_thresh`()
`get_tfbi_E_thresh`()
`get_tfbi_all`(**kw_get_vars)
`get_tfbi_extras`(**kw_get_vars)
`get_tfbi_fscale`()
`get_tfbi_fscale_rel`()
`get_tfbi_inputs`(**kw_get_vars)
`get_tfbi_omega`(*[, kw_tfbi_solve])
`get_tfbi_omega_ds`(*[, kw_tfbi_solve])
`get_tfbi_vs_EBspeed`()
`get_vars`(vars, *args[, return_type, ...])
`has_var`(var)
`help`([qstr, only, tree, modules, signature, ...])
`help_call_options`([search])
`help_quants_str`([qstr, only, tree, modules, ...])
`help_str`([qstr, only])
`kw_call_options`(*[, sorted])
`load_direct`(var, args, *kw)
`load_fromfile`(var, args, *kw)
`maintaining_attrs`(attrs, *attrs_as_flags)
`match_var`(var, *[, check])
`match_var_loading_dims`(var, **kw_loading_dims)
`match_var_result_dims`(var, **kw_result_dims)
`match_var_result_size`(var, *[, maindims])
`match_var_tree`([var])
`quant_tree`([var])
`set_E_un0_perpmod_B`(value, **kw)
`set_mod_B`(value, **kw)
`set_var`(var, value[, behavior_attrs, ...])
`set_var_internal`(var, value, behavior_attrs)
`solve_tfbi_vs_EBspeed`(*[, Mbytes_max, cache])
`tfbi_ds`([ions, all, output_mask])
`tfbi_mask`(*[, kappae, ionfrac, kappai, set])
`tfbi_solver`([ions])
`tree`([var])
`unset_var`(var[, behavior_attrs, missing_ok])
`unset_var_internal`(var, behavior_attrs[, ...])
`using_at_call_depth`(depth, **attrs_and_values)
`using_at_next_call_depth`(**attrs_and_values)
`using_attrs`([attrs_as_dict, _unset_sentinel])

Attributes

`KNOWN_PATTERNS`
`KNOWN_SETTERS`
`KNOWN_VARS`
`TFBI_EXTRAS`
`TFBI_VARS`
`assign_behavior_attrs`
`assign_behavior_attrs_max_call_depth`
`assign_behavior_attrs_skip_xr`
`behavior`
`behavior_attrs`
`call_depth`
`call_depth_manager`
`cls_behavior_attrs`
`direct_overrides`
`enable_fromfile`
`extra_coords`
`get`
`known_pattern`
`known_setter`
`known_var`
`maintaining`
`nondim_behavior_attrs`
`set`
`setvar`
`setvars`
`tfbi_EBspeed_grid_size`
`tfbi_growth_thresh`
`toplevel_scale_coords`
`typevar_crash_if_nan`
`unset`
`using`

property assign_behavior_attrs: whether to assign self.behavior values as attrs of result when calling self.

False –> don’t use self.behavior code architecture to assign attrs.

True –> equivalent to ‘nondefault’

‘nondefault’ –> self.behavior.assign_nondefault_attrs(result)

(for brevity, it does not assign behavior attrs with “default” value.)

‘all’ –> self.behavior.assign_attrs(result).

[EFF] only assigns attrs at call_depth >= self.assign_behavior_attrs_max_call_depth.

(default: only assigns attrs at call_depth=1, i.e. at top level.

property assign_behavior_attrs_max_call_depth: max call_depth at which to assign_behavior_attrs to result,

if self.assign_behavior_attrs indicates to assign behavior attrs.

default 1, i.e. only assign if at top level.

Use None to indicate “no max detph”.

property assign_behavior_attrs_skip_xr: whether to use include_xr=False if self.assign_behavior_attrs,

during self.behavior.assign_nondefault_attrs.

Use this if you want to assign behavior attrs EXCEPT array-valued behavior attrs.

attach_extra_coords(arr): attach any self.extra_coords to array arr but only if it is an xarray.DataArray or xarray.Dataset

property behavior: dict of {attr: self.attr} for attr in self.behavior_attrs. Note dims are separate;

dims go in behavior.dims. E.g. Behavior({‘units’:’si’,…}, dims={‘snap’:0,…}).

property behavior_attrs: list of attrs in self which control behavior of self.

Here, returns self.cls_behavior_attrs.

Subclasses could override if any behavior attrs are not known at the class-level,

e.g. if MySubclass’s list of behavior attrs varies between instances of MySubclass.

property call_depth: depth of the current call to self. depth = number of calls to self from within self.

E.g., call_depth while calculating gyrofrequency:

# call_depth == 0, for any code run here (outside any call to self).

self(‘gyrof’)

# call_depth == 1, for any code run here (inside ‘gyrof’ call but not inside deeper calls).

q = self(‘q’)

# call_depth == 2, for code inside ‘q’ call.

mod_B = self(‘mod_B’)

# call_depth == 2, for code inside ‘mod_B’ call.

self(‘B’)

# call_depth == 3, for code inside ‘B’ call.

m = self(‘m’)

# call_depth == 2, for code inside ‘m’ call.

result = q * mod_B / m

Cannot be set directly; can only be manipulated via self.call_depth_manager.

property call_depth_manager: stores the value of call_depth, and helps to manage attrs dependent on call_depth value.

classmethod cls_help(qstr=None, only=None, *, tree=None, modules=False, signature=False, doc=True, dense=False, print=True, **kw)

prints str for help with quants. Fails for any quants which depend on present values of a cls instance.

qstr: None or str: None –> tells info about this class & how to use this function.

in particular, tells that quants are stored cls.KNOWN_VARS and cls.KNOWN_PATTERNS,

and describes behavior of calling help with a string.

str –> return str for help with all quants related to str.

use empty str to get help for all quants.
only: None or str: None –> get help with all quantities related to qstr.

‘VARS’ or ‘vars’ –> only get help with KNOWN_VARS.

‘PATTERNS’ or ‘patterns’ –> only get help with KNOWN_PATTERNS.

‘TREE’ or ‘tree’ –> only get help with quantities in cls.cls_var_tree(str).

if provided when qstr is None, treat qstr as ‘’ instead.
tree: None or bool: How much help to give for quantities in cls.cls_var_tree(qstr).

False –> don’t even check cls.cls_var_tree(qstr).

True –> help for all quantities in cls.cls_var_tree.

None –> help for quantities in cls.cls_var_tree(qstr).flat_branches_until_vars()

i.e. patterns & vars in tree but ignore any nodes with LoadableVar ancestors.

e.g. qstr=’mean_mod_beta’ –> help with ‘mean_(.+)’, ‘mod_(.+)’, and ‘beta’,

but no help with dependencies of ‘beta’ (‘q’, ‘mod_B’, ‘m’).
modules: bool: Whether to include modules in result.

If True, result will be grouped into sections with modules written at top.
signature: signature: bool: whether to include line with signature in help string.

e.g. “help_str(f, *, module=True, signature=True, indent=None)”
doc: doc: bool: whether to include lines with docstring in help string.

e.g. “return str for help(f).” … and all the other docs in here.
dense: bool: Whether to reduce whitespace in result.

E.g. True –> no newlines between functions. False –> one newline between functions.
print: bool: whether to print the result. If False, return the result instead of printing.

classmethod cls_var_tree(var, *, missing_ok=False)

return QuantTree of MatchedQuantity objects from matching var and all dependencies,

using self.KNOWN_VARS and self.KNOWN_PATTERNS when searching for matches.

missing_ok: bool: whether to be lenient sometimes when missing details that would allow to fully determine deps.

see help(MatchedQuantity.dep_vars) for more details.

copy(): returns a deep copy of self.

[TODO] implement something less hacky than using the pickle module?

property direct_overrides: dict of {var: override} for all overrides of self which don’t depend on behavior_attrs of self.

For example, if user wants to set an override (or if setvars sets an override?), it will be here.

See also: self.direct_overrides_dynamic().

direct_overrides_dynamic(): returns dict of {var: override} for all overrides of self which depend on behavior_attrs of self.

property enable_fromfile: bool: whether self.load_fromfile is enabled during self.load_direct.

If False, raise QuantCalcError if load_direct can’t get value without load_fromfile().

property extra_coords: dict of {coord_name: coord_value} to attach to outputs of self(var).

Useful if planning to join the output of self(var) with output from a different QuantityLoader.

E.g. self.extra_coords={‘run’: ‘run 0’} and other.extra_coords={‘run’: ‘run 1’},

then xr.concat([self(‘n’), other(‘n’)], ‘run’) gives ‘n’ from self AND other.

(this is nice if self and other have same values for dims. Otherwise, might struggle.)

property get: alias to __call__

get_behavior(keys=None)

return value of self.behavior.

keys: None or iterable: if provided, only include these attrs.

from nondim_behavior_attrs, or dims.

get_cached_tfbi_vs_EBspeed()

return a previously-computed tfbi solution across EBspeed grid.

Expects solution to live in _tfbi_vs_EBspeed_file(); default:

{self.unique_notes_dirname}/_pc_tfbi/EBspeed_{logmin:.4g}_{logmax:.4g}_{logstep:.4g}.pcxarr

CAUTION: the implementation here assumes self.tfbi_EBspeed_grid_size is enough to uniquely specify the result;: e.g. if there is a different result at each snapshot of self, that will not be understood here.

get_set_or_cached(var): returns var if found in self.setvars or self.cache, with compatible behavior_attrs.

otherwise, raise CacheNotApplicableError.

if var is found in self.setvars and has relevant, but not matching behavior_attrs,

self.load_across_dims will be used to load the value.

get_tfbi_EBspeed_grid(): return a 1D grid of EBspeed values with constant logstep.

determines logmin, logmax, logstep (base 10) from self.tfbi_EBspeed_grid_size.

result’s name & EBspeed grid dim is always ‘EBspeed’.

get_tfbi_EBspeed_thresh(): threshold EBspeed for TFBI to grow. NaN if no growth predicted across the EBspeed grid considered.

Assumes user has already run self.solve_tfbi_vs_EBspeed().

If not, consider doing:

copied = self.copy()

copied.set_attrs(maindims_means=True, snap=0) # or some other way to downsample…

copied.solve_tfbi_vs_EBspeed()

equivalent to tfbi_vs_EBspeed.pc.min_coord_where(‘EBspeed’, tfbi_vs_EBspeed.it.growth_kmax()>0)

get_tfbi_E_thresh(): threshold E_un0_perpmag_B for TFBI to grow. NaN if no growth predicted across the EBspeed grid considered.

Equivalent: self(‘tfbi_EBspeed_thresh’) * self(‘mod_B’).

Assumes user has already run self.solve_tfbi_vs_EBspeed().

See self.help(‘tfbi_EBspeed_thresh’) for more details.

get_tfbi_all(**kw_get_vars): returns xarray.Dataset of values relevant to TFBI theory.

This includes tfbi_inputs (required for theory) and tfbi_extras (optional)

Results depend on self.fluid. May want to call as self(‘tfbi_all’, fluid=CHARGED).

get_tfbi_extras(**kw_get_vars): returns xarray.Dataset of values relevant to TFBI theory but not necessary for inputs.

Currently this just includes:

‘eqperp_lmfp’: each fluid’s collisional mean free path at its “equilibrium” temperature,

after considering zeroth order heating due to E_un0_perpmag_B.

‘SF_n’: sum of number densities of all species (including neutrals)

‘n’: number densities of each specie in self.fluid.

‘n_n’: number density of neutral fluid.

‘n*kappa’: number density times kappa.

TFBI dispersion relation terms scale with n*kappa for each fluid,

so this quantity roughly estimates the relative importance of each fluid.

Results depend on self.fluid. May want to call as self(‘tfbi_extras’, fluid=CHARGED).

get_tfbi_fscale(): tfbi_fscale = n * kappa

tfbi dispersion relation sums terms proportional to n * kappa, for each fluid.

get_tfbi_fscale_rel(): tfbi_fscale_rel = tfbi_fscale(this fluid) / tfbi_fscale(electrons).

get_tfbi_inputs(**kw_get_vars): returns xarray.Dataset of values to input to the tfbi theory.

“global” scalars (no dependence on component nor fluid)

‘mod_B’: |magnetic field|

‘E_un0_perpmag_B’: |E_un0 perp to B|. E_un0 = electric field in u_neutral=0 frame.

‘kB’: boltzmann constant. kB * T = temperature in energy units.

‘T_n’: temperature of neutrals.

‘m_n’: mass of neutrals.

scalars which depend on fluid. Note: checks self.fluid, not self.fluids.

‘m’: mass of all non-neutral fluids

‘nusn’: collision frequency between fluid and neutrals.

‘skappa’: signed magnetization parameter; q |B| / (m nusn)

‘eqperp_ldebye’: each fluid’s debye length at its “equilibrium” temperature,

after considering zeroth order heating due to E_un0_perpmag_B.

Results depend on self.fluid. May want to call as self(‘tfbi_inputs’, fluid=CHARGED).

get_tfbi_omega(*, kw_tfbi_solve={}, **kw_tfbi_solver)

Thermal Farley Buneman Instability roots with largest imaginary part at each point in self.

Equivalent: self.tfbi_solver(**kw_tfbi_solver).solve(**kw_solve)[‘omega’].

Can provide kwargs, e.g. self(‘tfbi_omega’, ions=[‘H_II’, ‘C_II’], kw_tfbi_solve=dict(ncpu=1)).

For more control, use self.tfbi_solver() directly.

For even more control, use the pattern described in help(self.tfbi_solver_cls).

Recommended: consider using ‘tfbi_omega_ds’ instead of ‘tfbi_omega’.: ‘tfbi_omega_ds’ gives the full Dataset of all values relevant to the solution.

‘tfbi_omega’ just gives the DataArray of omega, which is harder to inspect later.

get_tfbi_omega_ds(*, kw_tfbi_solve={}, **kw_tfbi_solver): Thermal Farley Buneman Instability solution at each point in self.

Equivalent: self.tfbi_solver(**kw_tfbi_solver).solve(**kw_solve).

Can provide kwargs, e.g. self(‘tfbi_omega_ds’, ions=[‘H_II’, ‘C_II’], kw_tfbi_solve=dict(ncpu=1)).

For more control, use self.tfbi_solver() directly.

For even more control, use the pattern described in help(self.tfbi_solver_cls).

get_tfbi_vs_EBspeed()

return tfbi solution across EBspeed grid. Load saved result if it exists, else save result to file.

CAUTION: the implementation here might self.set(‘E_un0_perpmod_B’, self(‘mod_B’) * EBspeed) | [TODO] avoid changing self.setvars… (or, at least, restore previous self.setvars afterwards.)

CAUTION: the implementation here assumes self.tfbi_EBspeed_grid_size is enough to uniquely specify the result;: e.g. if there is a different result at each snapshot of self, that will not be understood here.

Equivalent: self.solve_tfbi_vs_EBspeed(cache=’caches’)

get_vars(vars, *args, return_type='dataset', missing_vars=UNSET, **kw)

returns values of vars from self.

result is probably an xarray.Dataset, but not guaranteed; also depends on return_type.

Equivalent to self(vars, *args, return_type=’dataset’, **kw).

(Actually, self(vars, …) will call self.get_vars(vars, …).)

vars: iterable of strs: Names of the vars to load. [‘n’, ‘u’] for number density & velocity.

if any of these vars returns a return_type object, expand its keys,

e.g. if ‘myDSvar’ returns dataset with ‘myvar1’, ‘myvar2’,

then [‘n’, ‘myDSvar’] gives dataset with ‘n’, ‘myvar1’, ‘myvar2’.
return_type: ‘dataset’ or ‘dict’: if ‘dataset’, return result as xarray.Dataset.

the data_var names will be the same as the var names.

if ‘dict’, return result as dict of {var: value}.
missing_vars: UNSET, ‘ignore’, ‘warn’, or ‘raise’: what to do if any vars cause FormulaMissingError.

UNSET –> use self.missing_vars if it exists, else ‘raise’.

‘ignore’ –> ignore missing vars, and don’t include them in the result.

‘warn’ –> ignore missing vars, but print a warning.

‘raise’ –> raise FormulaMissingError if any vars are missing.

additional args & kwargs are passed to self(…).

has_var(var): return whether self can load var. True if self.match_var(var) is found, else False.

Subclasses might override, to include checks for whether var can be loaded from data.

[TODO] also check if var in self.cache or self.setvars.

help(qstr=None, only=None, *, tree=None, modules=False, signature=False, doc=True, dense=False, print=True)

prints str for help with quants.

qstr: None or str: None –> tells info about this class & how to use this function.

in particular, tells that quants are stored cls.KNOWN_VARS and cls.KNOWN_PATTERNS,

and describes behavior of calling help with a string.

str –> return str for help with all quants related to str.

use empty str to get help for all quants.
only: None or str: None –> get help with all quantities related to qstr.

‘VARS’ or ‘vars’ –> only get help with KNOWN_VARS.

‘PATTERNS’ or ‘patterns’ –> only get help with KNOWN_PATTERNS.

‘TREE’ or ‘tree’ –> only get help with quantities in cls.cls_var_tree(str).

if provided when qstr is None, treat qstr as ‘’ instead.
tree: None or bool: How much help to give for quantities in cls.cls_var_tree(qstr).

False –> don’t even check cls.cls_var_tree(qstr).

True –> help for all quantities in cls.cls_var_tree.

None –> help for quantities in cls.cls_var_tree(qstr).flat_branches_until_vars()

i.e. patterns & vars in tree but ignore any nodes with LoadableVar ancestors.

e.g. qstr=’mean_mod_beta’ –> help with ‘mean_(.+)’, ‘mod_(.+)’, and ‘beta’,

but no help with dependencies of ‘beta’ (‘q’, ‘mod_B’, ‘m’).
modules: bool: Whether to include modules in result.

If True, result will be grouped into sections with modules written at top.
signature: signature: bool: whether to include line with signature in help string.

e.g. “help_str(f, *, module=True, signature=True, indent=None)”
doc: doc: bool: whether to include lines with docstring in help string.

e.g. “return str for help(f).” … and all the other docs in here.
dense: bool: Whether to reduce whitespace in result.

E.g. True –> no newlines between functions. False –> one newline between functions.

help_call_options(search=None): prints help for kw_call_options.

if search is provided, only print help for keys containing search.

classmethod help_quants_str(qstr=None, only=None, *, tree=None, modules=True, signature=False, doc=True, dense=False, _instance=None)

returns str for help with quants.

qstr: None or str: None –> tells info about this class & how to use this function.

in particular, tells that quants are stored cls.KNOWN_VARS and cls.KNOWN_PATTERNS,

and describes behavior of calling help with a string.

str –> return str for help with all quants related to str.

use empty str to get help for all quants.
only: None or str: None –> get help with all quantities related to qstr.

‘VARS’ or ‘vars’ –> only get help with KNOWN_VARS.

‘PATTERNS’ or ‘patterns’ –> only get help with KNOWN_PATTERNS.

‘TREE’ or ‘tree’ –> only get help with quantities in cls.cls_var_tree(str).

if provided when qstr is None, treat qstr as ‘’ instead.
tree: None or bool: How much help to give for quantities in cls.cls_var_tree(qstr).

False –> don’t even check cls.cls_var_tree(qstr).

True –> help for all quantities in cls.cls_var_tree.

None –> help for quantities in cls.cls_var_tree(qstr).flat_branches_until_vars()

i.e. patterns & vars in tree but ignore any nodes with LoadableVar ancestors.

e.g. qstr=’mean_mod_beta’ –> help with ‘mean_(.+)’, ‘mod_(.+)’, and ‘beta’,

but no help with dependencies of ‘beta’ (‘q’, ‘mod_B’, ‘m’).
modules: bool: Whether to include modules in result.

If True, result will be grouped into sections with modules written at top.
signature: signature: bool: whether to include line with signature in help string.

e.g. “help_str(f, *, module=True, signature=True, indent=None)”
doc: doc: bool: whether to include lines with docstring in help string.

e.g. “return str for help(f).” … and all the other docs in here.
dense: bool: Whether to reduce whitespace in result.

E.g. True –> no newlines between functions. False –> one newline between functions.
_instance: None or QuantityLoader instance: if provided, use _instance.match_var_tree() instead of cls.cls_var_tree().

classmethod help_str(qstr=None, only=None, **kw): returns cls.help_quants_str(qstr=qstr, only=only, **kw).

cls.help() calls help_str.

subclasses might overwrite help_str, but probably won’t touch help_quants_str.

kw_call_options(*, sorted=True): returns list of kwarg names which can be used to set attrs self during self.__call__.

(see self.__call__ for more details).

Here, returns list(self.behavior_attrs) + list(self._extra_kw_for_quantity_loader_call)

load_direct(var, *args, **kw): load var “directly”, from some source which is not known by the main part of PlasmaCalcs.

Attempt the following, returning the first successful attempt:

- return self.direct_overrides[var](self, *args, **kw).

- return self.direct_overrides_dynamic()[var](self, *args, **kw).

- use self.load_fromfile.

return the result (probably a numpy array, but not guaranteed).

Examples:

load Bx directly from a file

load n for H+, using a different module which somehow gives nH+

(PlasmaCalcs doesn’t need to know where the value came from.)

if used an override, instead of loading from file,

set self._load_direct_used_override = var.

Otherwise, set it to None.

This might be used, e.g., to determine if the output came directly from a file or not.

load_fromfile(var, *args, **kw): load var directly from a file. Other methods should usually use load_direct, instead.

the implementation here just raises LoadingNotImplementedError;

subclasses should implement this method in order to load any values from files.

property maintaining: alias to maintaining_attrs

maintaining_attrs(*attrs, **attrs_as_flags): returns context manager which restores attrs of self to their original values, upon exit.

E.g. maintaining_attrs(obj, ‘attr1’, ‘attr2’, attr3=True, attr4=False)

–> will restore upon exit, original values of obj.attr1, attr2, and attr3, but not attr4.

classmethod match_var(var, *, check=['KNOWN_VARS', 'KNOWN_PATTERNS'])

match var from cls.KNOWN_VARS or cls.KNOWN_PATTERNS, or raise FormulaMissingError.

returns result=MatchedQuantity(var, loadable, _match=_match) where:

loadable is the LoadableQuantity associated with this var,

_match is:

None, if var in cls.KNOWN_VARS;

re.fullmatch(pattern, var), if var matches any pattern in cls.KNOWN_PATTERNS.

if var matches multiple patterns, only the first matching pattern is used.

Uses MatchedVar if match from KNOWN_VARS, MatchedPattern if from KNOWN_PATTERNS.

(note that both MatchedVar and MatchedPattern subclass MatchedQuantity.)

check: str or list of str from [‘KNOWN_VARS’, ‘KNOWN_PATTERNS’]: where to check for matches. Default is to check KNOWN_VARS and KNOWN_PATTERNS.

E.g. to only check KNOWN_PATTERNS, use check=[‘KNOWN_PATTERNS’].

loadable and _match can be retrieved via result.loadable and result._match.

match_var_loading_dims(var, **kw_loading_dims): return dims for loading var across.

Result will probably vary across these dims (but not guaranteed, if any dependency uses reduces_dims.)

These are all Dimension dims, not maindims. (E.g. ‘fluid’ and ‘snap’, but not ‘x’, ‘y’, ‘z’).

Equivalent: self.match_var_tree(var).loading_dims(**kw_loading_dims)

match_var_result_dims(var, **kw_result_dims): return dims which result of cls(var) will vary across.

These are all Dimension dims, not maindims. (E.g. ‘fluid’ and ‘snap’, but not ‘x’, ‘y’, ‘z’).

Equivalent: cls.match_var_tree(var).result_dims(**kw_result_dims)

match_var_result_size(var, *, maindims=True, **kw_result_dims)

return size (number of elements) which self(var) will have.
(Efficient; doesn’t actually get self(var).)
Depends on current values of relevant dims. (E.g., self.fluid, not self.fluids)

maindims: bool: if True, include maindims_shape when calculating size.

match_var_tree(var=UNSET, **kw_quant_tree_from_quantity_loader): return QuantTree of MatchedQuantity objects from matching var and all dependencies,

using self.KNOWN_VARS and self.KNOWN_PATTERNS when searching for matches.

var must be provided; var=UNSET will raise an error (helpful if tried calling this as a classmethod).

See also: type(self).cls_var_tree, for the classmethod version of this function.

Most of the time it is possible to get tree without any details from self,

but sometimes not. e.g. when getting collision frequencies, self.fluid affects deps.

additional kwargs will be passed to QuantTree.from_quantity_loader(…),

which passes kwargs from self.kw_call_options() into self.using(**kw) while getting deps.

matched_pattern_cls: alias of MatchedPattern

matched_var_cls: alias of MatchedVar

property nondim_behavior_attrs: list of attrs in self which control behavior of self, but which are NOT in self.dimensions.

quant_tree(var=UNSET, **kw_quant_tree_from_quantity_loader): return QuantTree of MatchedQuantity objects from matching var and all dependencies,

using self.KNOWN_VARS and self.KNOWN_PATTERNS when searching for matches.

var must be provided; var=UNSET will raise an error (helpful if tried calling this as a classmethod).

See also: type(self).cls_var_tree, for the classmethod version of this function.

Most of the time it is possible to get tree without any details from self,

but sometimes not. e.g. when getting collision frequencies, self.fluid affects deps.

additional kwargs will be passed to QuantTree.from_quantity_loader(…),

which passes kwargs from self.kw_call_options() into self.using(**kw) while getting deps.

quant_tree_cls: alias of QuantTree

property set: alias to set_var

set_E_un0_perpmod_B(value, **kw): set E_un0_perpmod_B to this value. Also sets E_un0_perpmag_B.

set_mod_B(value, **kw): set mod_B to this value. Also sets mag_B, mod2_B, and mag2_B.

set_var(var, value, behavior_attrs=None, forall=[], *, ukey=None, forced=False, **kw_using)

set var in self. When later doing self(var) to get var, return the set value,

but only if self.behavior is compatible with the relevant parts of self.behavior when var was set.

This function will use, if it exists:

self.KNOWN_SETTERS[var](self, value, behavior_attrs, forall=forall)

Otherwise, calls:

self.set_var_internal(var, value, self.behavior_attrs, forall=forall)

var: str: the var to set in self.
value: number, xarray, iterable or 1D array, array with shape matching self.maindims_shape.: the value to set var to.

number –> set var to this number.

xarray –> set var to this xarray.

[TODO](not yet implemented) iterable or 1D array –> set var to these values along dim=’testing’.

[TODO](not yet implemented) array with shape matching self.maindims_shape –> set var to this array.
behavior_attrs: None or list: tells which attrs from self control behavior of the set var.

The set var will only be retrieved when behavior_attrs of self are compatible.

E.g. set_var(‘n’, [‘fluid’, ‘snap’]) –> saves ‘n’ in cache with current fluid & snap.

Will only load ‘n’ if self.fluid and self.snap == cached fluid and snap for ‘n’.

if var in self.KNOWN_SETTERS, cannot provide behavior_attrs here.

else, use self.behavior_attrs if None.
forall: list of strings: if provided, tells which attrs of self do NOT control the behavior of the set var.

E.g. forall=[‘snap’] –> ‘snap’ will NOT be included in behavior_attrs.

(anything in behavior_attrs AND forall will be removed from the final behavior_attrs)
ukey: None or str: if provided, tells string to give to UnitsManager when converting value’s units.

When ukey is known, setting value in any unit system will enable to read it in all unit systems.

E.g. set_var(‘n’, 1e10, …, ukey=’n’, units=’si’)

–> self(‘n’, units=’raw’) == self(‘n’, units=’si’) * self.u(‘u’, ‘raw’, convert_from=’si’)

if not provided, value will be associated with current unit system;

attempted to read value in any other unit system will not used the cached value set here.

E.g. set_var(‘u’, 1e10, …, units=’si’) # ukey not provided

–> self(‘u’, units=’raw’) –> uses self’s other logic for getting ‘u’, not from setvars.

note: if provided, ‘units’ will be added to behavior_attrs if not already in there.
forced: bool, default True: handles the case where self.KNOWN_SETTERS[var] doesn’t exist. In that case…

True –> set var in self, anyway.

False –> crash; raise FormulaMissingError

additional kwargs, if provided, go to self.using(**kw) during the operation.

returns list of set quantities.

set_var_internal(var, value, behavior_attrs, forall=[], *, ukey=None)

set var in self. KNOWN_SETTERS functions may wish to use this method.

(KNOWN_SETTERS functions should NOT use self.set_var, to avoid recursion issue.)

This function has the internal logic for self.set_var;

set_var calls set_var_internal when self.KNOWN_SETTERS[var] not provided.

var: str: the var to set in self.
value: number, xarray, iterable or 1D array, array with shape matching self.maindims_shape.: the value to set var to. See help(self.set_var) for more info.
behavior_attrs: list of strings: the behavior attrs relevant to setting this var;

getting var only gives value when current behavior attrs values are compatible with the cached ones.
forall: list of strings: if provided, tells which behavior attrs do NOT control the behavior of the set var.

e.g. behavior_attrs=[‘snap’, ‘fluid’], forall=[‘snap’] –> use [‘fluid’], only.
ukey: None or str: if provided, tells string to give to UnitsManager when converting value’s units;

when ukey is provided, can retrieve value in any unit system (probably ‘si’ or ‘raw’).

when ukey not provided, if ‘units’ in used behavior attrs, can only retrieve value in that unit system.

property setvar: alias to set_var

property setvars: VarCache of vars set via self.set_var(). Returns these values when appropriate,

i.e. whenever self.behavior is compatible with the behavior in the cache.

To empty the cache, use self.setvars.clear() to empty the cache.

solve_tfbi_vs_EBspeed(*, Mbytes_max=True, cache='caches', **kw_solve)

solve tfbi across EBspeed grid from self(‘tfbi_EBspeed_grid’).

CAUTION: the implementation here might self.set(‘E_un0_perpmod_B’, self(‘mod_B’) * EBspeed) | [TODO] avoid changing self.setvars… (or, at least, restore previous self.setvars afterwards.)

Suggestion: use self.setvars.clear() after calling this function.

Mbytes_max: bool or number: maxmimum allowed data size [in MB] of self(‘tfbi_inputs’), before setting EBspeed grid.

(helps prevent accidental requests to solve too many points at once.)

(ignored if cache implies to load from existing cached file.)

True –> use default: DEFAULTS.ADDONS.TFBI_EBSPEED_INPUTS_MBYTES_MAX (default: 0.1).

False or None –> no maximum
cache: ‘caches’, ‘cache’, ‘cached’, or False: controls how & whether to handle cache the result.

cached results go to self._tfbi_vs_EBspeed_file(); default:

{self.unique_notes_dirname}/_pc_tfbi/EBspeed_{logmin:.4g}_{logmax:.4g}_{logstep:.4g}.pcxarr

where logmin, logmax, logstep are from self.tfbi_EBspeed_grid_size

‘caches’ –> read from saved file if it exists. Else, solve and save to file.

‘cache’ –> solve and save to file. Saved file must not exist yet (else, crash).

‘cached’ –> read from saved file. Saved file must exist (else, crash).

False –> solve and return result, but do not save to file nor check if file exists.

additional kwargs are passed to self.tfbi_solver().solve(**kw)

property tfbi_EBspeed_grid_size: (logmin, logmax, logstep) for self(‘tfbi_EBspeed_grid’); log is base 10.

Default: DEFAULTS.ADDONS.TFBI_EBSPEED_LOGMIN, LOGMAX, LOGSTEP; (default: (3, 4, 0.01)).

tfbi_ds(ions=None, *, all=True, output_mask=True, **kw_get_var)

returns Dataset of all the values needed & relevant to TFBI theory.

Equivalent: self(‘tfbi_all’, fluid=[electron, *ions], masking=True, …)

ions: None or specifier of multiple fluids (e.g. slice, or list of strs): list of ions to use. None –> self.fluids.ions()
all: bool: whether to include ‘tfbi_all’, or only ‘tfbi_inputs’.

With only ‘tfbi_inputs’, the theory is still solvable, but harder to inspect later.
output_mask: bool: whether to store_mask in results, if self.masking (and self.mask is not None)

additional kwargs passed to self(…)

property tfbi_growth_thresh: threshold for confirming “yes there is tfbi growth predicted here”, during self(‘tfbi_E_thresh’).

growth must be larger than (not equal to) this value, to confirm growth.

0.0 is the theoretical threshold. A small positive value (e.g. 0.001) helps to avoid tiny errors.

The default is DEFAULTS.ADDONS.TFBI_GROWTH_THRESH (default: 0.001).

tfbi_mask(*, kappae=1, ionfrac=0.001, kappai=1, set=True)

set & return self.mask appropriate for TFBI.

kappae: None or number, default 1: lower limit for kappae; mask points with kappae smaller than this value.

(kappae = |qe| |B| / (me nuen))

Internally, loaded as ‘kappa’ with fluid=’e’.

TFBI probably only matters when electrons are magnetized –> kappae >> 1.

Applying TFBI theory to kappae masked points would still be fine,

but will probably always say “instability doesn’t grow there”.

None –> no mask on kappae
ionfrac: None or number: upper limit for ionfrac; mask points with ionfrac larger than this value.

(ionfrac = ne / ntotal)

Internally, loaded as ‘SF_ionfrac’ if available,

else ne/(ne+n_neutral), with ne from self(‘n’, fluid=self.fluids.get_electron()).

(Note: checked in Bifrost: SF_ionfrac uses SF_n = sum of element densities.

SF_n does not include ne.

The formula SF_ionfrac = ne/(ne+nn) uses ne as a proxy for sum(ni),

which will be okay unless there are twice+ ionized species.)

TFBI assumes weakly ionized.

E_un0 also assumes weakly ionized, when self.assume_un=’u’.

Applying TFBI theory to ionfrac masked points would be a big issue,

as it could lead to many false positives,

where physical effects not included in the theory damp out the TFBI.

None –> no mask on ionfrac.
kappai: None or number, default 1: upper limit for min kappai; mask points with all kappai larger than this value.

(kappai = |qi| |B| / (mi nuin))

Internally, loaded as ‘kappa’ with fluid=ions, then take min across fluids.

TFBI probably only matters when at least 1 ion species is demagnetized –> kappai < 1.

Applying TFBI theory to kappai masked points would still be fine,

but will probably always say “instability doesn’t grow there”.

None –> no mask on kappai.
set: bool: whether to set self.mask = result.

if False, only returns the result, without also setting self.mask.

tfbi_solver(ions=None, **kw_solver)

return TfbiSolver object for solving TFBI theory based on values in self.

all inputs here get passed to TfbiSolver. Equivalent: TfbiSolver(self, …).

docs for TfbiSolver copied below for convenience:
————————————————-
high-level interface for solving TFBI theory across many physical parameters.

Call TfbiSolver to solve TFBI.

Example:

import PlasmaCalcs as pc
cc = pc.PlasmaCalculator(…)   # <– your PlasmaCalculator of choice
solver = pc.TfbiSolver(cc)
solution = solver()             # alias: solver.solve()

solution is an xarray.Dataset with all relevant quantities (see TfbiLoader.get_tfbi_all),

and ‘omega’ telling roots with largest imaginary part.

If you need more precise control over the solving process, use the pattern:

import tfbi_theory as tt
import PlasmaCalcs as pc
cc = … # any PlasmaCalculator object from PlasmaCalcs.
ds0 = cc.tfbi_ds()
kp = tt.kPickerLowres(ds0)
dsk = kp.get_ds()   # copy of ds0, but with ds[‘k’] = k from kPicker.
drel = tt.TfbiDisprelC.from_ds(dsk)
dsR = drel.solve()  # copy of dsk, but with ds[‘omega’] = solution to TFBI theory!

TfbiSolver internally stores self.cc, ds0, kp, dsk, drel, and dsR,

as defined by the pattern above.

cc: PlasmaCalculator: PlasmaCalculator object used to load the data.

Should be a TfbiLoader subclass. (PlasmaCalculator satisfies this by default,

assuming successful import SymSolver and import tfbi_theory.)
ions: None or specifier of multiple fluids (e.g. slice, or list of strs): None –> use cc.fluids.ions()

print warning if this specifies more than DEFAULTS.ADDONS.TFBI_MAX_NUM_IONS ions

(default: 5), because then solving will be slow and may be inaccurate.

ions are determined when called, not during __init__.
kres: ‘low’, ‘mid’, or ‘high’: resolution in k-space. Tells which self.kPicker_cls to use.

‘low’ –> tfbi_theory.kPickerLowres. Recommended if solving across many points.

‘mid’ –> tfbi_theory.kPickerMidres. Recommended if solving across a few points.

‘high’ –> tfbi_theory.kPickerHighres. Recommended if solving at only 1 point.
mod, lmod, ang: UNSET or dict: passed directly to kPicker if provided. Can specify k values other than the defaults.

see help(self.kPicker_cls) for more details.
tfbi_all: bool: whether to compute all relevant tfbi vars, ds0 = cc(‘tfbi_all’).

False –> compute only the necessary vars, ds0 = cc(‘tfbi_inputs’).
drel_cls: None, str, or class: tfbi_theory class to use for solving TFBI theory.

None –> use self.drel_cls default: tt.TfbiDisprelC

str –> use getattr(tt, drel_cls) to get the class.

tfbi_solver_cls: alias of TfbiSolver

property toplevel_scale_coords: dict of {coord_name: coord_scaling} to apply to top-level outputs of self(var).

(Never applies to internal calls of self(var), only applies at self.call_depth==1.)

Useful if making plots and want to scale coords by some factor.

E.g., self.toplevel_scale_coords = {‘t’: 1000} to convert s to ms.

CAUTION: coord units labels will remain unaffected.

tree(var=UNSET, **kw_quant_tree_from_quantity_loader): return QuantTree of MatchedQuantity objects from matching var and all dependencies,

using self.KNOWN_VARS and self.KNOWN_PATTERNS when searching for matches.

var must be provided; var=UNSET will raise an error (helpful if tried calling this as a classmethod).

See also: type(self).cls_var_tree, for the classmethod version of this function.

Most of the time it is possible to get tree without any details from self,

but sometimes not. e.g. when getting collision frequencies, self.fluid affects deps.

additional kwargs will be passed to QuantTree.from_quantity_loader(…),

which passes kwargs from self.kw_call_options() into self.using(**kw) while getting deps.

property typevar_crash_if_nan: bool. whether to crash methods if typevar output would be ‘nan’.

False –> return NaN when typevar gives ‘nan’, instead of crashing.

“typevar” here refers to any var used for checking which formula to use, from various options,

e.g. ‘ntype’ in MhdMultifluidLoader or ‘ionfrac_type’ in MhdIonizationLoader.

The relevant methods can check if self.typevar_crash_if_nan before returning a ‘nan’ result.

property unset: alias to unset_var

unset_var(var, behavior_attrs=[], *, missing_ok=True, **kw_using)

remove var from self.setvars (but only at values stored with relevant behavior).

[TODO] define rules for which vars unset which other vars…

e.g. for eppic right now, set_var(‘n’) sets ‘den’ but not ‘n’;

unset_var(‘n’) unsets nothing… but should probably alias to unset_var(‘den’).

behavior_attrs: list of strings: only remove cached values where self.behavior matches cached behavior for these attrs.

if empty, remove all cached values for var, regardless of associated behavior.
missing_ok: bool: whether it is okay for there to be zero matching cached values for var.

raise CacheNotApplicableError if missing_ok=False when there are no matching cached values.

additional kwargs, if provided, go to self.using(**kw) during the operation.

return list of CachedQuantity objects which were removed from self.setvars.

unset_var_internal(var, behavior_attrs, forall=[], *, ukey=None, missing_ok=True)

unset var from self.setvars.

KNOWN_SETTERS functions may wish to use this method, to unset dependent values.

E.g. if u depends on n, and n is changed, may wish to unset the value of u.

behavior_attrs: list of strings: the behavior attrs relevant to setting this var.
forall: list of strings: if provided, tells which behavior attrs to ignore when unsetting the var.
ukey: None or string: if provided, ignore ‘units’ behavior attr when unsetting the var

(due to assuming that ukey was provided when setting the var,

hence that the set var could be retrieved in any units system)
missing_ok: bool: whether it is okay for there to be zero matching cached values for var.

raise CacheNotApplicableError if missing_ok=False when there are no matching cached values.

return list of CachedQuantity objects which were removed from self.setvars.

property using: alias to using_attrs

using_at_call_depth(depth, **attrs_and_values): context manager for setting attrs_and_values but only while call_depth == depth.

E.g.:

with self.using_at_call_depth(3, verbose=3):

self(‘sgyrof’)

# while self.call_depth == 3 inside of this ‘with’ block, uses self.verbose=3.

# but everywhere else, uses original value of verbose.

# assuming originally verbose=False (or unset), this example will print:

| | (call_depth=2) get var=’q’

| | (call_depth=2) get var=’mod_B’

| | (call_depth=2) get var=’m’

# compare this to simply using self.verbose=3, which would print:

| (call_depth=1) get var=’sgyrof’

| | (call_depth=2) get var=’q’

| | (call_depth=2) get var=’mod_B’

| | | (call_depth=3) get var=’B_dot_B’

| | | | (call_depth=4) get var=’B_xyz’

| | | | | (call_depth=5) get var=’B’

| | (call_depth=2) get var=’m’

Equivalent to self.call_depth_manager.using_obj_attrs_at(depth, **attrs_and_values)

using_at_next_call_depth(**attrs_and_values): context manager for setting attrs_and_values but only while call_depth == self.call_depth + 1

Equivalent to self.using_at_call_depth(self.call_depth + 1, **attrs_and_values).

(Also equivalent to self.call_depth_manager.using_obj_attrs_at_next(**attrs_and_values).)

using_attrs(attrs_as_dict={}, _unset_sentinel=ATTR_UNSET, **attrs_and_values)

returns context manager which sets attrs of obj upon entry; restores original values upon exit.

_unset_sentinel: any value, default ATTR_UNSET: upon entry, delete any attrs with value _unset_sentinel (compared via ‘is’).

E.g. using_attrs(obj, _unset_sentinel=None, x=None) –> del obj.x upon entry.