EppicSubsamplable

class PlasmaCalcs.hookups.eppic.eppic_subsampler.EppicSubsamplable(input_deck, *, read_mode='h5', **kw_super)

Bases: EppicDirectLoader, Subsamplable

manages subsampling of EPPIC output, and interpreting subsampled EPPIC output.

self.subsample() outputs to {self.dirname}/subsampling_result:

subsampled snapshots go to subsampling_result/parallel (assuming full_read_mode=’h5_2’)

subsampling info goes to subsampling_result/subsampling_info

Users may prefer the simpler version if just looking for simple slicing of snaps/x/y/z:

self.subsample_simple_slices() can easily serve this purpose.

self.subsampling_info by default reads info from {self.dirname}/subsampling_info.

If that directory doesn’t exist, it will be None, and assume there is no subsampling.

snap src objects for EPPIC will be Snap objects, not filepaths.

Methods

`__call__`(var, *args[, name, item, verbose])	returns value of var from self.
`__getitem__`(snapi)	sets self.snap, then returns self.
`__init_subclass__`(*[, dimension, dim_plural])	called when subclassing DimensionHaver; sets some useful attributes related to dimension.
`__iter__`()	equivalent to self.iter_snaps()
`__len__`()	equivalent to len(self.snaps)
`__setup_haver__`(dim_cls, **kw_super)	called by dim_cls.setup_haver(cls) when setting up cls so that it "has" dim_cls dimension.
`as_single_dimpoint`([values, dims])	return DimPoint with values for dims, but raise DimensionValueError if any value is_iterable_dim.
`assert_QN`()	asserts self.quasineutral.
`assign_dim_coords`(array, *dims[, skip])	assign all dimensions in self as coords for array.
`attach_extra_coords`(arr)	attach any self.extra_coords to array arr but only if it is an xarray.DataArray or xarray.Dataset
`check_pickle`([x])	checks that self (or, x, if provided) is pickleable, by pickling then unpickling.
`cls_help`([qstr, only, tree, modules, ...])	prints str for help with quants.
`cls_var_tree`(var, *[, missing_ok])	return QuantTree of MatchedQuantity objects from matching var and all dependencies,
`copy`()	returns a deep copy of self.
`current_n_dimpoints`([dims])	return number of points represented by current values of dims.
`current_n_existing_snaps`()	returns number of existing snaps, out of all snaps at self.snap.
`dim_values`([dims])	return dict of current values for dimensions in self.
`dims_apply`(funcname, *args_func[, dims])	apply funcname to each dimension in self, with args_func and kw_func.
`dims_get`(attr[, dims])	return dict of {dim: getattr(self.dimensions[dim], attr) for dim in dims}.
`direct_overrides_dynamic`()	returns dict of {var: override} for all overrides of self which depend on behavior_attrs of self.
`directly_loadable_vars`([snap])	return tuple of directly loadable variables.
`enumerate_dimpoints`([dims, all])	iterate through values of dims, yielding (idx, DimPoint) pairs.
`existing_snaps`()	return list of existing snaps.
`get_behavior`([keys])	return value of self.behavior.
`get_first_dimpoint`([dims, enumerate])	return DimPoint taking the first value of each dim in self.dimensions.
`get_load_direct_maindims_var`(var, *[, _match])	load maindims var directly (from files, cache, or setvars; see self.load_direct()).
`get_ncpu`()	returns ncpu, but if None, return multiprocessing.cpu_count() instead.
`get_ne`()	electron number density.
`get_set_or_cached`(var)	returns var if found in self.setvars or self.cache, with compatible behavior_attrs.
`get_vars`(vars, *args[, return_type, ...])	returns values of vars from self.
`has_var`(var)	return whether self can load var.
`help`([qstr, only, tree, modules, signature, ...])	prints str for help with quants.
`help_call_options`([search])	prints help for kw_call_options.
`help_quants_str`([qstr, only, tree, modules, ...])	returns str for help with quants.
`help_str`([qstr, only])	returns cls.help_quants_str(qstr=qstr, only=only, **kw).
`iter_dimpoints`([dims, all, restore, enumerate])	iterate through values of dims, returning DimPoints and setting dim values during iteration.
`kw_call_options`(*[, sorted])	returns list of kwarg names which can be used to set attrs self during self.__call__.
`load_across_dims`(loader, *args_loader[, ...])	return loader(...), iterating & joining across each dimension.
`load_across_dims_implied_by`(var, loader, ...)	return loader(...), iterating & joining across each dimension implied by var.
`load_direct`(var, args, *kw)	load var "directly", either from a file, self.setvars, self.direct_overrides,
`load_fromfile`(fromfile_var, *args[, snap])	return numpy array of fromfile_var, loaded directly from file.
`load_input`(fromfile_var, args, *kw)	load value of fromfile_var but when self.snap is INPUT_SNAP.
`load_subsampling_info`()	load subsampling info from {self.dirname}/subsampling_info.
`maintaining_attrs`(attrs, *attrs_as_flags)	returns context manager which restores attrs of self to their original values, upon exit.
`match_var`(var, *[, check])	match var from cls.KNOWN_VARS or cls.KNOWN_PATTERNS, or raise FormulaMissingError.
`match_var_loading_dims`(var, **kw_loading_dims)	return dims for loading var across.
`match_var_result_dims`(var, **kw_result_dims)	return dims which result of cls(var) will vary across.
`match_var_result_size`(var, *[, maindims])	return size (number of elements) which self(var) will have.
`match_var_tree`([var])	return QuantTree of MatchedQuantity objects from matching var and all dependencies,
`n_existing_snaps`()	returns number of existing snaps.
`on_changed_quasineutral`(*, old, new)	called when self.quasineutral changes.
`pop_dim_keys`(kw)	return ({key: kw.pop(key) for key in self.dimensions if key in kw}, kw).
`quant_tree`([var])	return QuantTree of MatchedQuantity objects from matching var and all dependencies,
`rawvar_load`(var, src)	load a single raw var from snap src.
`rawvar_load_and_subsample`(var, src, info)	returns var loaded and subsampled from src.
`rawvar_save`(var, data, dst)	saves a single raw var to snap dst.
`rawvars_loadable`(src)	returns list of all directly loadble vars within snap src.
`rawvars_loadable_across`([srcs])	returns dict of {src: [vars loadable from src]} for all snap srcs
`set_attrs`(**attrs)	sets these attrs in self.
`set_pop_dim_attrs`(kw)	set self.{key} = kw.pop(key) for each key in self.dimensions if key in kw.
`set_var`(var, value[, behavior_attrs, ...])	set var in self.
`set_var_internal`(var, value, behavior_attrs)	set var in self.
`snap_filepath`([snap])	convert snap to full file path for this snap.
`snap_src_to_filepath`(src)	convert snap src to filepath.
`subsample`(subsampling_info, *[, ...])	apply subsampling to all data indicated by subsampling_result_info.
`subsample_maindims_at_snaps`(*[, x, y, z, ...])	subsample same maindims but different snaps for different vars.
`subsample_maindims_simple`(*[, snap, x, y, z])	self.subsample(subsampling_info corresponding to slicing snaps and maindims, only).
`subsampler`(subsampling_info)	return self.subsampler_cls instance with self and subsampling_info.
`subsampling_info_maindims_at_snaps`(*[, x, ...])	SubsamplingInfo corresponding to subsampling maindims at different snaps.
`subsampling_info_maindims_simple`(*[, snap, ...])	SubsamplingInfo corresponding to slicing snaps and maindims, only.
`subsampling_snap_srcs`()	list of all snap srcs in self (before applying any subsampling).
`tree`([var])	return QuantTree of MatchedQuantity objects from matching var and all dependencies,
`unset_var`(var[, behavior_attrs, missing_ok])	remove var from self.setvars (but only at values stored with relevant behavior).
`unset_var_internal`(var, behavior_attrs[, ...])	unset var from self.setvars.
`using_at_call_depth`(depth, **attrs_and_values)	context manager for setting attrs_and_values but only while call_depth == depth.
`using_at_next_call_depth`(**attrs_and_values)	context manager for setting attrs_and_values but only while call_depth == self.call_depth + 1
`using_attrs`([attrs_as_dict, _unset_sentinel])	returns context manager which sets attrs of obj upon entry; restores original values upon exit.
`using_first_dimpoint`([dims])	return context manager which sets dimensions to their first values (when called); restore original on exit.
`where_loadable`([var, snaps, set])	returns snaps from self.snaps where 'n', 'flux', 'nvsqr', 'vdist', 'phi' values can be loaded,
`wheref_loadable`([var, snaps, set])	returns snaps from self.snaps where 'n', 'flux', 'nvsqr', 'vdist', 'phi' values can be loaded,
`_apply_subsampling_to_maindims_coords`(coords)	apply subsampling to maindims coords.
`_apply_subsampling_to_vdist_coords`(vcoords, ...)	apply subsampling to vdist coords for this fluid (a single Fluid)
`_apply_toplevel_scale_coords`(arr)	apply self.toplevel_scale_coords to arr, if nonempty, else return arr unchanged.
`_battrs_for_set_var_internal`(behavior_attrs)	returns behavior_attrs which will be used by set_var_internal, given these inputs.
`_battrs_for_unset_var_internal`(behavior_attrs)	returns behavior_attrs which will be used by unset_var_internal, given these inputs.
`_call_loader0_at_dimpoint`(dimpoint, loader0, ...)	return self._call_loader_at_dimpoint(dimpoint, loader0, ...).
`_call_loader_at_dimpoint`(dimpoint, loader, ...)	with self.using(*dimpoint): return loader(args_loader, **kw_loader)
`_call_postprocess`(result, *, var[, name, item])	postprocess result from self.__call__.
`_call_postprocess_toplevel`(result, *, var[, ...])	additional postprocessing for self.__call__ when call_depth=1.
`_check_files_readable`()	check that all files in self.dirname are readable (checks recursively inside directories too).
`_default_ncoarse`()	return default for ncoarse during self.load_across_dims.
`_default_ncpu`()	return default for ncpu during self.load_across_dims.
`_default_print_freq`()	returns default for print_freq.
`_default_subsampling_info`()	default value for self.subsampling_info: load from {self.dirname}/subsampling_info.
`_default_timeout`()	return default for timeout during self.load_across_dims.
`_default_title`()	default title for self.
`_get_dimensions_dict`()	return dict of dimensions in self; {dimension name: Dimension object}
`_get_maybe_missing_var`(var, *args[, ...])	return value of var, or None if FormulaMissingError and missing_vars 'ignore' or 'warn'.
`_get_subsampling_step`(x[, var])	get subsampling step for var along this direction.
`_h5_2_directly_loadable_vars`(*[, snap])	return tuple of directly loadable variables, for read_mode='h5_2'.
`_h5_2_filename`(*[, snap])	return name of file from which to load values, for read_mode='h5_2'.
`_h5_2_load_fromfile`(fromfile_var, *args__None)	return numpy array of var, loaded directly from file, using "h5_2" read_mode.
`_handle_typevar_nan`(*[, errmsg])	crash with TypevarNanError if self.typevar_crash_if_nan, else return 'nan'.
`_help_matches`(qstr, k, v)	returns whether qstr matches k or v, and thus should be displayed during self.help(qstr).
`_increment_call_depth`()	context manager for incrementing call_depth.
`_load_across_dims_postprocess`(arrs, dims, *, ...)	postprocessing results from load_across_dims, after all tasks have been completed.
`_load_across_dims_postprocess__arrs_to_nparr`(...)	returns single numpy array (with the data from arrs, which is an array of arrays).
`_load_across_dims_postprocess__broadcast_shapes`(...)	handles array broadcasting for _load_across_dims_postprocess.
`_openpmd_directly_loadable_vars`(*[, snap])	return tuple of directly loadable variables, for read_mode='openpmd'.
`_openpmd_load_fromfile`(eppic_var, *args__None)	return numpy array of var, loaded directly from file, using "openpmd" read_mode.
`_pop_kw_call_options`(kw)	pop all self.kw_call_options() from kw, returning dict of popped options.
`_provided_val`(var[, _val, _known_vals])	returns the value of var, either from _known_vals or _val.
`_repr_contents`()	return list of contents to go in repr of self.
`_special_dims_shifters`(dimnames, _shift_special)	return (dict for self.using(...), dict for result.isel(...)) to _shift_special_dims.
`_var_for_load_fromfile`(varname_internal)	return var, suitably adjusted to pass into load_fromfile().

Attributes

`KNOWN_PATTERNS`
`KNOWN_SETTERS`
`KNOWN_VARS`
`array_MBmax`	UNSET, None, or number
`assign_behavior_attrs`	whether to assign self.behavior values as attrs of result when calling self.
`assign_behavior_attrs_max_call_depth`	max call_depth at which to assign_behavior_attrs to result,
`assign_behavior_attrs_skip_xr`	whether to use include_xr=False if self.assign_behavior_attrs,
`assign_snap_along`	alias to self.snap_dim.assign_coord_along
`assign_snap_coord`	alias to self.snap_dim.assign_coord
`behavior`	dict of {attr: self.attr} for attr in self.behavior_attrs.
`behavior_attrs`	list of attrs in self which control behavior of self.
`call_depth`	depth of the current call to self.
`call_depth_manager`	stores the value of call_depth, and helps to manage attrs dependent on call_depth value.
`cls_behavior_attrs`
`current_n_snap`	alias to self.snap_dim.current_n
`dimensions`	dict of dimensions in self; {dimension name: Dimension object}.
`dims`	return dict of current values for dimensions in self.
`direct_overrides`	dict of {var: override} for all overrides of self which don't depend on behavior_attrs of self.
`dirname`	abspath to directory containing data for this DirectLoader.
`enable_fromfile`	bool: whether self.load_fromfile is enabled during self.load_direct.
`enumerate_snap`	alias to self.snap_dim.enumerate
`enumerate_snaps`	alias to self.snap_dim.enumerate_values
`extra_coords`	dict of {coord_name: coord_value} to attach to outputs of self(var).
`full_read_mode`	full read_mode, including hdf_output_arrays information.
`get`	alias to __call__
`iter_snap`	alias to self.snap_dim.iter
`iter_snaps`	alias to self.snap_dim.iter_values
`iter_snaps_partition`	alias to self.snap_dim.iter_partition
`join_snaps`	alias to self.snap_dim.join_along
`known_pattern`
`known_setter`
`known_var`
`maintaining`	alias to maintaining_attrs
`nGbytes`	number of gigabytes across all files in self.dirname (and subdirectories).
`nMbytes`	number of megabytes across all files in self.dirname (and subdirectories).
`nbytes`	number of bytes across all files in self.dirname (and subdirectories)
`ncoarse`	int
`ncpu`	None or int
`nondim_behavior_attrs`	list of attrs in self which control behavior of self, but which are NOT in self.dimensions.
`notes_dirname`	'abspath to directory containing plots/notes for a DirectLoader.
`print_freq`	None, or number (possibly negative or 0)
`print_freq_explicit`	like self.print_freq, but converts UNSET to value based on self.verbose,
`quasineutral`	tells whether self is in quasineutral mode.
`read_mode`	mode telling which files to read.
`set`	alias to set_var
`setvar`	alias to set_var
`setvars`	VarCache of vars set via self.set_var().
`snap`	alias to self.snap_dim.v
`snap_dim`	snap dimension for SnapHaver.
`snap_is_iterable`	alias to self.snap_dim.is_iterable
`snap_list`	alias to self.snap_dim.list
`snap_type`	alias to self.snap_dim.get_type
`snapdir`	directory containing the snapshot files.
`snaps`	alias to self.snap_dim.values
`subsampling_info`	SubsamplingInfo telling how existing data was subsampled from prior data.
`take_snap`	alias to self.snap_dim.take
`take_snaps`	alias to self.snap_dim.take_along
`timeout`	None or int
`title`	title to help distinguish this calculator from others.
`toplevel_scale_coords`	dict of {coord_name: coord_scaling} to apply to top-level outputs of self(var).
`typevar_crash_if_nan`	bool.
`unique_notes_dirname`	abspath to directory containing plots/notes for a DirectLoader,
`unset`	alias to unset_var
`using`	alias to using_attrs

__call__(var, *args, name=UNSET, item=False, verbose=UNSET, **kw)

returns value of var from self.

result is probably an xarray.DataArray, but not guaranteed.

var: str or iterable of strs.: Name of the var(s) to load. E.g. ‘n’ for number density, or [‘n’, ‘u’] for number density & velocity.

If multiple vars: returns an xarray.Dataset of all vars, via self.get_vars.

Determine how to load each var, as follows:

- (caching) if var in self.cache, with matching self.behavior_attrs, use value from cache.

[TODO] - caching not yet implemented. May allow for better efficiency.

- (setvars) if var in self.setvars, with matching self.behavior_attrs, use value from setvars.

[TODO] - improve set_var functionality.

set_var will allow user to apply PlasmaCalcs calculations to arbitrary values,

not just values from one of the hookups. Useful for testing & quick calculations.

- (KNOWN_VARS) if var in self.KNOWN_VARS,

use the corresponding function to get it.

- (KNOWN_PATTERNS) if var matches a pattern from self.KNOWN_PATTERNS,

use the corresponding function to get it.

- (direct) attempt to load var “directly”, via self.load_direct.

load_direct will almost always end up loading values directly from a file (e.g., “data”).

However, there is one more chance for it to get intercepted: via direct_overrides.

- (direct_overrides) if var in self.direct_overrides, attempts self.direct_overrides[var].

The idea is to use direct_overrides when requiring alternate instructions for

what would otherwise be a “base” var.

E.g., ‘n’ may be a “base” var, but if quasineutral then ‘ne’ is not saved in a file;

so, base_overrides[<key for density>] may tell how to get ‘ne’.

Note: for overrides which depend on current state, use direct_overrides_dynamic.

For overrides which are “always” implemented (not toggled by other things), use direct_overrides.

- (fromfile) load_direct uses self.load_fromfile whenever direct_overrides is not applicable.

Those are checked in the order listed.

If none of those work, raise FormulaMissingError.
name: UNSET, None, or str: try to set result.name = name.

UNSET –> use name = var.
item: bool: if True, convert result to single value (e.g., python float) via result.item().

This will cause crash if result is not a single value;

it will also cause all metadata stored in the result to be lost.
verbose: UNSET, bool, or int: set self.verbose during this call to self.

UNSET –> use self.verbose (unchanged)

kw may additionally contain any keys from self.kw_call_options().

if it does, pop those values, and temporarily set the corresponding attr.

E.g.: self(‘n’, units=’si’, fluid=1)

–> temporarily set units=’si’, fluid=1, while getting ‘n’.

See self.help_call_options() for more details.

[EFF] passes _match=re.fullmatch(pattern, var) to the getter function,

if the match is from KNOWN_PATTERNS (but not if it is from KNOWN_VARS).

__getitem__(snapi): sets self.snap, then returns self.

Examples:

self[4] –> self.snap = 4

self[:5] –> self.snap = slice(0, 5)

self[-1] –> self.snap = -1

self[‘2’] –> self.snap = ‘2’

self[self.snaps[7]] –> self.snap = self.snaps[7]

self[[0,4,7,3]] –> self.snap = [0,4,7,3]

Note this is ‘smart’ in the same way that setting self.snap is ‘smart’;

will attempt self.snaps.get(snapi).

See help(self.snaps.get) for more details.

This enables “shorthand” syntax, e.g. self[3](‘n’) gets ‘n’ at self.snap=3.

classmethod __init_subclass__(*, dimension=None, dim_plural=None, **kw_super)

called when subclassing DimensionHaver; sets some useful attributes related to dimension.

dimension: str or None: name of dimension associated with this subclass.

if None, no particular dimension associated with this subclass.
dim_plural: str or None: plural form of dimension. if None, use str(dimension)+’s’.

Sets various attributes in cls:

cls._dimension = dimension,

cls._dim_plural = dim_plural,

cls._dim_types = dict of all {dimension name: Dimension subclass} from cls and cls.__bases__

(note - connecting self._dimension to this dict is not handled here;

it is handled by __setup_haver__ called by Dimension.setup_haver)

__iter__(): equivalent to self.iter_snaps()

__len__(): equivalent to len(self.snaps)

classmethod __setup_haver__(dim_cls, **kw_super): called by dim_cls.setup_haver(cls) when setting up cls so that it “has” dim_cls dimension.

_apply_subsampling_to_maindims_coords(coords): apply subsampling to maindims coords.

coords is a dict of {‘x’: xcoords, ‘y’: ycoords} possibly also ‘z’: zcoords.

[TODO] check that vars actually all have the same maindims, else, crash?

implementation now just assumes ‘den0’ exists and has same maindims as other vars.

_apply_subsampling_to_vdist_coords(vcoords, fluid): apply subsampling to vdist coords for this fluid (a single Fluid)

_apply_toplevel_scale_coords(arr): apply self.toplevel_scale_coords to arr, if nonempty, else return arr unchanged.

_battrs_for_set_var_internal(behavior_attrs, forall=[], *, ukey=None): returns behavior_attrs which will be used by set_var_internal, given these inputs.

see help(self.set_var_internal) for details.

_battrs_for_unset_var_internal(behavior_attrs, forall=[], *, ukey=None): returns behavior_attrs which will be used by unset_var_internal, given these inputs.

see help(self.unset_var_internal) for details.

_call_loader0_at_dimpoint(dimpoint, loader0, args_loader, *, nload, MBmax, **kw_loader): return self._call_loader_at_dimpoint(dimpoint, loader0, …).

Also does memory size check based on nload and MBmax.

intended for internal use only, inside load_across_dims.

arr0 is handled differently from other arrays in order to do some checks.

_call_loader_at_dimpoint(dimpoint, loader, args_loader, **kw_loader): with self.using(**dimpoint): return loader(*args_loader, **kw_loader)

_call_postprocess(result, *, var, name=UNSET, item=UNSET)

postprocess result from self.__call__. Called during self.__call__.

(self.call_depth inside here will tell depth of the current call; depth=1 for top level.)

result: any value, probably an xarray.DataArray: result from self.__call__, before postprocessing.
var, name, item: UNSET or value: passed directly from self.__call__.

The implementation here does the following (subclasses might override / add to this):

(1) if self.verbose >= 4, print a message about getting var.
(2) result = self.attach_extra_coords(result).
(3) if name was provided, set result.name = name, if possible.
(4) if self.assign_behavior_attrs at this call depth, do so now.
(5) if self.call_depth == 1, call self._call_postprocess_toplevel.
(6) if item, convert result to single value via result.item().

_call_postprocess_toplevel(result, *, var, name=UNSET, item=UNSET)

additional postprocessing for self.__call__ when call_depth=1.

called from self._call_postprocess, after doing other postprocessing, when call_depth=1.

result: any value, probably an xarray.DataArray: result from self.__call__, after other postprocessing (except item).
var, name, item: UNSET or value: passed directly from self.__call__.

Don’t need to handle these here because self._call_postprocess will handle it.

The implementation here does the following (subclasses might override / add to this):

(1) self._apply_toplevel_scale_coords (does nothing if self.toplevel_scale_coords is empty)

_check_files_readable(): check that all files in self.dirname are readable (checks recursively inside directories too).

return number of files checked, number of files readable, and number of files not readable.

print exceptions along the way if any files are not readable!

_default_ncoarse(): return default for ncoarse during self.load_across_dims. returns DEFAULTS.LOADING_NCOARSE

_default_ncpu(): return default for ncpu during self.load_across_dims. returns DEFAULTS.LOADING_NCPU

_default_print_freq(): returns default for print_freq. Here, returns UNSET; i.e., infer from self.verbose.

(See self.print_freq_explicit to get the actual value of print_freq.)

_default_subsampling_info(): default value for self.subsampling_info: load from {self.dirname}/subsampling_info.

_default_timeout(): return default for timeout during self.load_across_dims. returns DEFAULTS.LOADING_TIMEOUT

_default_title(): default title for self. Here, just returns os.path.basename(self.notes_dirname)

_get_dimensions_dict(): return dict of dimensions in self; {dimension name: Dimension object}

_get_maybe_missing_var(var, *args, missing_vars=UNSET, **kw)

return value of var, or None if FormulaMissingError and missing_vars ‘ignore’ or ‘warn’.

missing_vars: UNSET, ‘ignore’, ‘warn’, or ‘raise’: what to do if any var causes FormulaMissingError.

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

‘ignore’ –> return None.

‘warn’ –> return None, but also print a warning.

‘raise’ –> raise FormulaMissingError.

_get_subsampling_step(x, var='den0'): get subsampling step for var along this direction.

Crash with SubsamplingFormatError if subsampling mode for var exists but is not ‘slice’.

_h5_2_directly_loadable_vars(*, snap=None): return tuple of directly loadable variables, for read_mode=’h5_2’.

_h5_2_filename(*, snap=None)

return name of file from which to load values, for read_mode=’h5_2’.

snap: None, str, int, or Snap: the snapshot number to load.

if None, use self.snap.

_h5_2_load_fromfile(fromfile_var, *args__None, snap=None, **kw__None)

return numpy array of var, loaded directly from file, using “h5_2” read_mode.

This corresponds to h5 read mode with hdf_output_arrays=2.

fromfile_var: str: the name of the variable as stored in the snapshot.
snap: None, str, int, or Snap: the snapshot number to load.

if None, use self.snap.

Example:

fromfile_var=’fluxx1’, snap=7

–> h5py.File(‘parallel/parallel000007.h5’)[‘fluxx1’][:]

_handle_typevar_nan(*, errmsg=''): crash with TypevarNanError if self.typevar_crash_if_nan, else return ‘nan’.

if crashing, use error message:

errmsg + “nTo return ‘nan’ instead of crashing, set self.typevar_crash_if_nan=False.”

classmethod _help_matches(qstr, k, v)

returns whether qstr matches k or v, and thus should be displayed during self.help(qstr).

qstr: str: the str to match; from self.help(qstr)
k: varname: the varname to test for matches.

key from self.KNOWN_VARS.keys(), or key.str from self.KNOWN_PATTERNS.keys().
v: LoadableQuantity: the LoadableQuantity to test for matches.

value from self.KNOWN_VARS.values() or self.KNOWN_PATTERNS.values().

matches if any of these are true:

qstr == ‘’
qstr in k.split(‘_’)         # size limitation and split(‘_’) because, e.g. during help(‘n’),
len(qstr)>=3 and qstr in k   #    want vars related to number density, not all vars with the letter ‘n’.
qstr in module.split(‘.’)   (where, module == v.get_f_module(cls))
‘.’ in qstr and qstr in module
len(qstr)>=3 and qstr in value from module.split(‘.’)
len(qstr)>=3 and qstr in v.fname
re.fullmatch(k, qstr)  # if k is a Pattern

otherwise, does not match.

_increment_call_depth()

context manager for incrementing call_depth.

use “with self._increment_call_depth():” inside of __call__, e.g.:

def __call__(self, *args, **kw):

with self._increment_call_depth():

# do stuff; possibly including calling self again.

Equivalent to self.call_depth_manager.increment()

_load_across_dims_postprocess(arrs, dims, *, it_dimnames, assign_coords, isel=None): postprocessing results from load_across_dims, after all tasks have been completed.

i.e., after all arrays have been loaded, join them all together.

_load_across_dims_postprocess__arrs_to_nparr(arr0, arrs): returns single numpy array (with the data from arrs, which is an array of arrays).

_load_across_dims_postprocess__broadcast_shapes(arr0, arrs, it_dimnames)

handles array broadcasting for _load_across_dims_postprocess.

returns (arr0, arrs), but with all arrs having the same shape as arr0. Crash if not possible.

CAUTION: may edit arrs in-place.

(Won’t edit individual arrays’ data; just arrs which contains the arrays.)

NOTE: arr0 in result isn’t necessarily arrs.flat[0].: arr0 in result is the “model array”, used to model coords & dims on.

arr0 = first DataArray with size == max(size) across all arrays.

E.g. if array shapes are [(), (), (7,1), (1,3), (7,3), (7,3) ()],

then use arr0 = the first DataArray with shape (7,3).

if neither array with shape (7,3) is a DataArray (i.e., has coords…)

then crash instead (because we can’t properly assign coords to result.)

it_dimnames: list of names of iterable dimensions; sometimes included in error message.

_openpmd_directly_loadable_vars(*, snap=None): return tuple of directly loadable variables, for read_mode=’openpmd’.

_openpmd_load_fromfile(eppic_var, *args__None, snap=None, **kw__None)

return numpy array of var, loaded directly from file, using “openpmd” read_mode.

This corresponds to openpmd read mode.

eppic_var: str: the name of the variable as stored in the snapshot.
snap: None, str, int, or Snap: the snapshot number to load.

if None, use self.snap.

Example:

eppic_var=’fluxx1’, snap=7

–> zarr.open(‘data/000007/fields/fluid_2/fluxx1’)

_pop_kw_call_options(kw): pop all self.kw_call_options() from kw, returning dict of popped options.

_provided_val(var, _val=None, _known_vals={}): returns the value of var, either from _known_vals or _val.

if _val provided, return it; if ‘_{var}’ in _known_vals, return it;

if both provided, crash with InputConflictError (unless they are the same object),

else, return None.

Can use this internally to avoid redundant recalculations. (See e.g. VectorArithmeticLoader)

_repr_contents(): return list of contents to go in repr of self.

_special_dims_shifters(dimnames, _shift_special): return (dict for self.using(…), dict for result.isel(…)) to _shift_special_dims.

See docs of load_across_dims for more details.

_var_for_load_fromfile(varname_internal): return var, suitably adjusted to pass into load_fromfile().

Here:

append self.component if self._loading_component

append self.fluid.N if self._loading_fluid

E.g. ‘flux’ turns into ‘fluxz2’ when loading ‘z’ component and fluid 2.

property array_MBmax: UNSET, None, or number

maximum result size allowed, in Megabytes.

will raise a MemorySizeError if result size would be larger than this.

UNSET –> use DEFAULTS.ARRAY_MBYTES_MAX (default: 1000 MB).

None –> no limit.

Assumes that each result (at each dimpoint) will be the same size.

as_single_dimpoint(values=None, *, dims=None, **values_as_kw)

return DimPoint with values for dims, but raise DimensionValueError if any value is_iterable_dim.

values: None or dict: values to use for the dimpoint.

values will be joined with **values_as_kw; provided any of either will be equivalent.

E.g. can use values={‘fluid’: ‘e’} or use fluid=’e’.

if any are provided –> use values corresponding to self.{dim}=values[dim] for dim in dims.

else –> use values of self.{dim} for dim in dims. (equivalent: self.dims_apply(‘_as_single’, dims=dims))
dims: None or iterable of strs appearing in self.dimensions.keys(): dimensions to include.

None –> infer dimensions from keys of values (and values_as_kw).

if no values were provided (values=None, and empty values_as_kw),

use all dimensions from self.dimensions.keys().

additional kwargs provide other {dim: value} items.

Examples:

self.as_single_dimpoint() –> DimPoint({dim: self.{dim} for dim in self.dimensions})
self.as_single_dimpoint({‘fluid’: ‘e’}) –> DimPoint({‘fluid’: ‘e’})
self.as_single_dimpoint(fluid=’e’) –> DimPoint({‘fluid’: ‘e’})
self.as_single_dimpoint({‘fluid’: ‘e’}, snap=0) –> DimPoint({‘fluid’: ‘e’, ‘snap’: 0})
self.as_single_dimpoint(dims=[‘fluid’, ‘snap’]) –> DimPoint({‘fluid’: self.fluid, ‘snap’: self.snap})

assert_QN(): asserts self.quasineutral. if not self._assert_QN, instead does not assert self.quasineutral.

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.

assign_dim_coords(array, *dims, skip=[])

assign all dimensions in self as coords for array. (self.assign_{dim}_coord(array))

Assumes array is an xarray and does not have any dimensions in self.

(array is not edited directly; returns result of assigning coords.)

dims: iterable of dimensions in self: assign only these dimensions as coords. (use all dimensions if len(dims)==0)
skip: iterable of dimensions in self: do not assign these dimensions as coords.

property assign_snap_along: alias to self.snap_dim.assign_coord_along

property assign_snap_coord: alias to self.snap_dim.assign_coord

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.

check_pickle(x=None): checks that self (or, x, if provided) is pickleable, by pickling then unpickling.

Returns result of unpickling. Useful for debugging.

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: If provided, only get help for a subset of relevant quantities.

None –> get help with all quantities related to qstr.

‘VARS’ –> only get help with KNOWN_VARS.

‘PATTERNS’ –> only get help with KNOWN_PATTERNS.

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

‘EXACT’ –> only get help for the KNOWN_VAR exactly matching qstr.

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?

current_n_dimpoints(dims=None)

return number of points represented by current values of dims.

dims: None or iterable of strs appearing in self.dimensions.keys(): dimensions to consider. None –> use all dimensions.

E.g. current_n_dimpoints(self, dims=[‘fluid’, ‘snap’]) –> number of (fluid, snap) points;

e.g. 3 fluids and 2 snaps –> 6 points.

Note, for classes using maindims, maindims are not included in the number of dimpoints.

Equivalent to len(list(self.iter_dimpoints(dims=dims, current=True)))

current_n_existing_snaps(): returns number of existing snaps, out of all snaps at self.snap.

Equivalent to self.snap_dim.current_n_existing_for(self).

property current_n_snap: alias to self.snap_dim.current_n

dim_values(dims=None)

return dict of current values for dimensions in self.

dims: None or iterable: if provided, only include these dimensions.

Equivalent: DimRegion(self.dims_get(‘v’, dims=dims))

property dimensions: dict of dimensions in self; {dimension name: Dimension object}.

e.g. {‘fluid’: self.fluid_dim, ‘snap’: self.snap_dim, …}.

property dims: return dict of current values for dimensions in self. Equivalent: self.dim_values()

dims_apply(funcname, *args_func, dims=None, **kw_func)

apply funcname to each dimension in self, with args_func and kw_func.

dims: None or iterable of strs: if provided, only apply to these dimensions.

See also: dims_apply

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.

directly_loadable_vars(snap=None)

return tuple of directly loadable variables.

These are the variables that can be loaded directly from a file,

using the current full_read_mode.

snap: None, str, int, or Snap: the snapshot number to load. if None, use self.snap.

property dirname: abspath to directory containing data for this DirectLoader.

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

enumerate_dimpoints(dims=None, *, all=False): iterate through values of dims, yielding (idx, DimPoint) pairs.

idx is a dict of {dim: i} such that DimPoint values are {dim: dims[i] for dim,i in idx.items()}.

Also, during iteration, set self.{dim} = value, as with self.iter_dim.

Equivalent to self.iter_dimpoints(dims=dims, all=all, enumerate=True)

property enumerate_snap: alias to self.snap_dim.enumerate

property enumerate_snaps: alias to self.snap_dim.enumerate_values

existing_snaps(): return list of existing snaps. Equivalent to self.snaps.existing_snaps(self).

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 full_read_mode: full read_mode, including hdf_output_arrays information.

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_first_dimpoint(dims=None, *, enumerate=False)

return DimPoint taking the first value of each dim in self.dimensions.

dims: None or iterable of strs appearing in self.dimensions.keys(): dimensions to include. None –> use all dimensions.
enumerate: bool: whether to return (idx, DimPoint) instead of just DimPoint.

get_load_direct_maindims_var(var, *, _match=None): load maindims var directly (from files, cache, or setvars; see self.load_direct()).

var should be name of a directly loadable var (see self.directly_loadable_vars()).

Output always uses ‘raw’ units, regardless of self.units,

but coords are in self.coords_units (default: same as self.units).

get_ncpu(): returns ncpu, but if None, return multiprocessing.cpu_count() instead.

(This is for convenience; using None will also work with any methods defined here.)

get_ne(): electron number density. (ne qe) + sum_i (ni qi) = 0. (using qe < 0 convention)

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_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: If provided, only get help for a subset of relevant quantities.

None –> get help with all quantities related to qstr.

‘VARS’ –> only get help with KNOWN_VARS.

‘PATTERNS’ –> only get help with KNOWN_PATTERNS.

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

‘EXACT’ –> only get help for the KNOWN_VAR exactly matching qstr.

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: If provided, only get help for a subset of relevant quantities.

None –> get help with all quantities related to qstr.

‘VARS’ –> only get help with KNOWN_VARS.

‘PATTERNS’ –> only get help with KNOWN_PATTERNS.

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

‘EXACT’ –> only get help for the KNOWN_VAR exactly matching qstr.

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.

iter_dimpoints(dims=None, *, all=False, restore=True, enumerate=False)

iterate through values of dims, returning DimPoints and setting dim values during iteration.

DimPoints are dicts of {dim: value} for dim in dims, where not is_iterable_dim(value).

Also, during iteration, set self.{dim} = value, as with self.iter_dim.

dims: None or iterable of strs appearing in self.dimensions.keys(): dimensions to consider. None –> use all dimensions.
all: bool: whether to iterate through all possible values, or only the current values.

False –> iterate through current values (e.g., self.snap, self.fluid, …).

similar to itertools.product(self.iter_snap(), self.iter_fluid(), …)

True –> iterate through all possible values (e.g., self.snaps, self.fluid, …)

similar to itertools.product(self.iter_snaps(), self.iter_fluids(), …)

Equivalent to all=False if all dims are set to None, e.g. self.snap=None, …
restore: bool: whether to restore original dim values after iteration.
enumerate: bool, default False: whether to yield indices too, i.e. (idx, DimPoint) instead of just DimPoint.

idx would be a dict of {dim: i} such that DimPoint values are {dim: dims[i] for dim,i in idx.items()}.

property iter_snap: alias to self.snap_dim.iter

property iter_snaps: alias to self.snap_dim.iter_values

property iter_snaps_partition: alias to self.snap_dim.iter_partition

property join_snaps: alias to self.snap_dim.join_along

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_across_dims(loader, *args_loader, dims=[], assign_coords=None, loader0=None, _shift_special={}, **kw_loader)

return loader(…), iterating & joining across each dimension.

loader: callable of (*args_loader, **kw_loader) -> xarray.DataArray.: will call loader to get result values at each combination of dims values in self.

(loader will probably depend on dims values from self.)
dims: iterable of strs or Dimension objects: load across these Dimensions.

loads across the current values (when this method was called) of each dimension,

not necessarily “all” values. (e.g., self.snap, not self.snaps)

str values –> use self.dimensions[d] (where d is a str in dims).

len(dims)==0 –> just return loader(var, *args_loader, **kw_loader).

While loading, set dim.loading=True for each dim.
assign_coords: None or bool, default None: whether to dim.assign_coord for each result of loader, for each dimension.

None –> assign coord only if dim.name not already in array.coords.
loader0: None or callable: if provided, use loader0 to get the first array, then use loader for the rest.

Internally the first array’s .coords and .attrs are used to label the result;

however all other arrays do not need to be converted to xarray.
_shift_special: UNSET or dict of (dimstr: list of special values): workaround to encourage loader0 to be called on a “usual” case, not a special case.

if provided, and dimstr in dims, and d=self.dimensions[dimstr] has multiple values,

with special_value first, and at least one non-special value later, then

internally rearrange dim values order before loading,

then rearrange result back to original order (via indexing).

E.g. _shift_special=dict(snap=[INPUT_SNAP]) –> apply loader0 to the first non-INPUT_SNAP,

if there are any non-INPUT_SNAP snap values in snap, and ‘snap’ in dims.

— MULTIPROCESSING STRATEGY OPTIONS (from self) —

timeout: None or int: max duration, in seconds. Must be None or integer (due to limitations of signal.alarm method)

None –> no time limit.

Note: if time_limit is reached, will raise a TimeoutError and save the result so far.

(in this case, any not-yet-calculated values will each be RESULT_MISSING.)

# [TODO] make this happen, without making self un-picklable:

in case of crash, results so far can be found in self._latest_load_tasks.

Then possibly continued via:

results = self._latest_load_tasks(…, reset=False, skip_done=True)

result = self._load_across_dims_postprocess(results, dims, …)

# [TODO] if crashing and resuming is common, make that easier to do^

elf.timeout has not been set, use DEFAULTS.LOADING_TIMEOUT (default: None).
ncpu: None or int: max number of cpus to use for multiprocessing.

None –> use multiprocessing.cpu_count()

int –> use this value. if 0 or 1, do not use multiprocessing here.

Note: will actually use min(ncpu, number of calls to be made);

e.g. if ncpu=4 but len(arg_kw_tuples)=2, will only use 2 cpus.

elf.ncpu has not been set, use DEFAULTS.LOADING_NCPU (default: 1).
ncoarse: int: if >1, group tasks into groups of size ncoarse before performing them.

elf.ncoarse has not been set, use DEFAULTS.LOADING_NCOARSE (default: 1).
print_freq: None, or number (possibly negative or 0): >0 –> Minimum number of seconds between progress updates.

=0 –> print every progress update.

<0 –> never print progress updates.

None –> use DEFAULTS.PROGRESS_UPDATES_PRINT_FREQ

elf.print_freq has not been set, infer from self.verbose if it exists,

use DEFAULTS.PROGRESS_UPDATES_PRINT_FREQ (default: 2).

additional args & kwargs are passed as loader(*args_loader, **kw_loader).

load_across_dims_implied_by(var, loader, *args_loader, assign_coords=None, _min_split=1, **kw_loader)

return loader(…), iterating & joining across each dimension implied by var.

Equivalent to self.load_across_dims(loader, …, dims=self.match_var_loading_dims(var)).

var: str: variable which implies dims to load across, via self.match_var_loading_dims(var).
loader: callable of (*args_loader, **kw_loader) -> xarray.DataArray.: will call loader to get result values at each combination of dims values in self.

(loader will probably depend on dims values from self.)
assign_coords: None or bool, default None: whether to dim.assign_coord for each result of loader, for each dimension.

None –> assign coord only if dim.name not already in array.coords.
_min_split: int, default 1: if an implied dim has current_n() < min_split, don’t load across it.

1 –> no minimum.

additional args & kwargs are passed as loader(*args_loader, **kw_loader).

load_direct(var, *args, **kw): load var “directly”, either from a file, self.setvars, self.direct_overrides,

or via self.load_input() if self.snap is INPUT_SNAP.

Steps:

1) attempt to get var from cache or self.setvars.

[EFF] only tries this if we are not self._inside_quantity_loader_call_logic,

to avoid redundant calls to self.get_set_or_cached.

2) adjust var name if appropriate, via new_varname = self._var_for_load_fromfile(var).

if new_varname != old varname, attempt to get new_varname from cache or setvars.

3) if self.snap is INPUT_SNAP, return self.load_input(new_varname).

4) super().load_direct(adjusted_var, *args, **kw),

which will use self.load_fromfile(…) unless any overrides apply here.

load_fromfile(fromfile_var, *args, snap=None, **kw)

return numpy array of fromfile_var, loaded directly from file.

use self.full_read_mode to determine which file(s) / how to read them.

fromfile_var: str: the name of the variable to read, adjusted appropriately for loading fromfile.

E.g., use ‘fluxz2’, not ‘flux’, to get flux for fluid 2 and component z.

See also: self._var_for_load_fromfile().
snap: None, str, int, or Snap: the snapshot number to load. if None, use self.snap.

Example:

fromfile_var=’fluxx1’, snap=7, read_mode=’h5_2’

–> h5py.File(‘parallel/parallel000007.h5’)[‘fluxx1’][:]

load_input(fromfile_var, *args, **kw): load value of fromfile_var but when self.snap is INPUT_SNAP.

[Not implemented for this subclass; loading direct when self.snap is INPUT_SNAP will crash]

(optional; subclass can override in order to implement INPUT_SNAP functionality.

see EppicCalculator.load_input() for an example.)

load_subsampling_info(): load subsampling info from {self.dirname}/subsampling_info.

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 nGbytes: number of gigabytes across all files in self.dirname (and subdirectories).

== self.nbytes / 1024**3

property nMbytes: number of megabytes across all files in self.dirname (and subdirectories).

== self.nbytes / 1024**2

n_existing_snaps(): returns number of existing snaps. Equivalent to self.snap_dim.n_existing_for(self).

property nbytes: number of bytes across all files in self.dirname (and subdirectories)

property ncoarse: int

if >1, group tasks into groups of size ncoarse before performing them.

property ncpu

None or int

max number of cpus to use for multiprocessing.
None –> use multiprocessing.cpu_count()
int –> use this value. if 0 or 1, do not use multiprocessing here.

Note: will actually use min(ncpu, number of calls to be made);: e.g. if ncpu=4 but len(arg_kw_tuples)=2, will only use 2 cpus.

see also: self.get_ncpu() to read actual number of cpus when self.ncpu is None.

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

property notes_dirname: ‘abspath to directory containing plots/notes for a DirectLoader.

Might be the same directory as self.dirname, but doesn’t need to be;

can explicitly set self.notes_dirname = value, if desired.

If not set, use notes_dirname == self.dirname,

unless self.dirname ends with one of the self._INDICATES_NOTES_DIRNAME options.

E.g. dirname == ‘path/to/dir0’ –> notes_dirname == ‘path/to/dir0’.

E.g. dirname == ‘path/to/dir1/_sim’ –> notes_dirname == ‘path/to/dir1’.

E.g. dirname == ‘path/to/dir1/_check0’ –> notes_dirname == ‘path/to/dir1’.

See also: self.unique_notes_dirname

on_changed_quasineutral(*, old, new): called when self.quasineutral changes.

default behavior: do nothing.

pop_dim_keys(kw): return ({key: kw.pop(key) for key in self.dimensions if key in kw}, kw).

property print_freq: None, or number (possibly negative or 0)

>0 –> Minimum number of seconds between progress updates.

=0 –> print every progress update.

<0 –> never print progress updates.

None –> use DEFAULTS.PROGRESS_UPDATES_PRINT_FREQ

property print_freq_explicit: like self.print_freq, but converts UNSET to value based on self.verbose,

UNSET –> result depends on self.verbose:

False or <=0 –> -1

True or (>=1 and <5) –> None

>=5 –> 0 (i.e. print every progress update)

if self.verbose doesn’t exist –> None

if result would be None, instead give DEFAULTS.PROGRESS_UPDATES_PRINT_FREQ.

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 quasineutral: tells whether self is in quasineutral mode.

rawvar_load(var, src): load a single raw var from snap src.

Used by subsampling routines. Basically just calls self.load_fromfile.

rawvar_load_and_subsample(var, src, info): returns var loaded and subsampled from src.

rawvar_save(var, data, dst): saves a single raw var to snap dst.

crash if this would require overwriting any existing data at dst.

rawvars_loadable(src): returns list of all directly loadble vars within snap src.

Used by subsampling routines. Basically just calls self.directly_loadable_vars.

rawvars_loadable_across(srcs=None): returns dict of {src: [vars loadable from src]} for all snap srcs

The implementation here just calls rawvars_loadable for each src.

if srcs is None, use self.subsampling_snap_srcs().

property read_mode: mode telling which files to read.

Currently, must be ‘h5’ or ‘h5_2’

Maybe other modes will be added at some point.

Options:

‘h5’ –> read from .h5 files,

determine file format based on input_deck[‘hdf_output_arrays’].

‘h5_2’ –> read from .h5 files,

assuming input_deck[‘hdf_output_arrays’]==2.

property set: alias to set_var

set_attrs(**attrs): sets these attrs in self.

set_pop_dim_attrs(kw): set self.{key} = kw.pop(key) for each key in self.dimensions if key in kw.

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.

property snap: alias to self.snap_dim.v

property snap_dim: snap dimension for SnapHaver.

snap_dim_cls: alias of SnapDimension

snap_filepath(snap=None)

convert snap to full file path for this snap.

snap: None, str, int, or Snap: the snapshot number to load.

if None, use self.snap.

property snap_is_iterable: alias to self.snap_dim.is_iterable

property snap_list: alias to self.snap_dim.list

snap_src_to_filepath(src): convert snap src to filepath. Returns self.snap_filepath(src).

property snap_type: alias to self.snap_dim.get_type

property snapdir: directory containing the snapshot files.

If self.full_read_mode==’h5_2’ or ‘h5_3’ or ‘h5_4’,

this is ‘{self.dirname}/parallel’.

Otherwise, this will crash with a NotImplementedError.

property snaps: alias to self.snap_dim.values

subsample(subsampling_info, *, subsampled_data_exist_ok=False)

apply subsampling to all data indicated by subsampling_result_info.

returns SubsamplingResultPathManager with relevant paths.

(results will be saved to paths determined by SubsamplingResultPathManager;

probably ‘subsampling_result’ at the same directory-level as target.snapdir.)

Never overwrites any of the pre-subsampling data.

By default, refuses to overwrite any existing data at all.

subsampling_info: SubsamplingInfo, str, or json-like dict: str –> path to load subsampling info from.

can be filename or directory. see SubsamplingInfo.load for details.

dict –> subsampling info in json-like format, see SubsamplingInfo for details.
subsampled_data_exist_ok: bool: whether it is okay for subsampled data file(s) to already exist before saving any data. Default False.

(Doesn’t interact with any subsampling_info files.)

subsample_maindims_at_snaps(*, x=None, y=None, z=None, den=UNSET, flux=UNSET, nvsqr=UNSET, phi=UNSET, others=None, **kw_subsample)

subsample same maindims but different snaps for different vars.

x, y, z: None or slice: slice for this main dim.
den, flux, nvsqr, phi: UNSET, None or slice: slice for snaps for this variable.

None –> do NOT slice snaps for this variable (but still slice maindims!)
others: None or slice: slice snaps for whichever of den, flux, nvsqr, and phi are UNSET.

None –> do not slice snaps (but still slice maindims!)

subsample_maindims_simple(*, snap=None, x=None, y=None, z=None, **kw_subsample)

self.subsample(subsampling_info corresponding to slicing snaps and maindims, only).

snap, x, y, z: None or slice: slice for this dim.

subsampler(subsampling_info): return self.subsampler_cls instance with self and subsampling_info.

See help(self.subsample) for details on subsampling_info.

subsampler_cls: alias of Subsampler

property subsampling_info: SubsamplingInfo telling how existing data was subsampled from prior data.

By default, this info will be loaded from {self.dirname}/subsampling_info.

subsampling_info_cls: alias of SubsamplingInfo

subsampling_info_maindims_at_snaps(*, x=None, y=None, z=None, den=UNSET, flux=UNSET, nvsqr=UNSET, phi=UNSET, others=None, as_json=False)

SubsamplingInfo corresponding to subsampling maindims at different snaps.

x, y, z: None or slice: slice for this main dim. All maindims variables will be sliced according to this.
den, flux, nvsqr, phi: UNSET, None or slice: slice for snaps for this variable.

None –> do not slice snaps for this variable (but still slice maindims!)
others: None or slice: slice snaps for whichever of den, flux, nvsqr, and phi are UNSET.

None –> do not slice snaps (but still slice maindims!)
as_json: bool: if True, return json for info instead of converting to SubsamplingInfo object.

(Could be useful if you want to use this json as a starting point then make small edits)

subsampling_info_maindims_simple(*, snap=None, x=None, y=None, z=None, as_json=False)

SubsamplingInfo corresponding to slicing snaps and maindims, only.

snap, x, y, z: None or slice: slice for this dim.
as_json: bool: if True, return json for info instead of converting to SubsamplingInfo object.

(Could be useful if you want to use this json as a starting point then make small edits)

subsampling_info_path_manager_cls: alias of SubsamplingInfoPathManager

subsampling_snap_srcs(): list of all snap srcs in self (before applying any subsampling).

Here, just returns self.snaps.

property take_snap: alias to self.snap_dim.take

property take_snaps: alias to self.snap_dim.take_along

property timeout

None or int

max duration, in seconds. Must be None or integer (due to limitations of signal.alarm method)

None –> no time limit.

Note: if time_limit is reached, will raise a TimeoutError and save the result so far.: (in this case, any not-yet-calculated values will each be RESULT_MISSING.)

property title

title to help distinguish this calculator from others.

E.g. might want to add self.title to plots.

Default: os.path.basename(self.dirname) if self.notes_dirname == self.dirname,: else basename(self.notes_dirname) + basename(self.dirname),

except skip basename(self.dirname) if ‘_sim’.

Examples of default behavior:

‘/path/to/dir0’ –> ‘dir0’.
‘/path/to/dir1/_sim’ –> ‘dir1’.
‘/path/to/dir1/_check0’ –> ‘dir1_check0’.

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 unique_notes_dirname: abspath to directory containing plots/notes for a DirectLoader,

probably not shared by DirectLoaders corresponding to any other data.

(E.g. if

Might be the same directory as self.dirname, but doesn’t need to be;

can explicitly set self.notes_dirname = value, if desired.

If not set, use unique_notes_dirname = self.dirname,

unless dirname ends with one of the self._INDICATES_UNIQUE_NOTES_DIRNAME options.

E.g. dirname == ‘path/to/dir0’ –> unique_notes_dirname == ‘path/to/dir0’.

E.g. dirname == ‘path/to/dir1/_sim’ –> unique_notes_dirname == ‘path/to/dir1’.

E.g. dirname == ‘path/to/dir1/_check0’ –> unique_notes_dirname == ‘path/to/dir1/_check0’.

See also: self.notes_dirname

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.

using_first_dimpoint(dims=None)

return context manager which sets dimensions to their first values (when called); restore original on exit.

Useful for testing a single code at a single dimpoint without needing to set each dimension individually.

dims: None or iterable of strs appearing in self.dimensions.keys(): dimensions to include. None –> use all dimensions.

where_loadable(var=None, snaps=None, *, set=False)

returns snaps from self.snaps where ‘n’, ‘flux’, ‘nvsqr’, ‘vdist’, ‘phi’ values can be loaded,

for ALL fluids in self.fluids.

Equivalent:

with self.using(fluid=None):

return self.wheref_loadable(var=var, snaps=snaps)

[EFF] method is IMPLICIT, based on var_out_subcycling details for each fluid.

Does not actually check the files directly, because it’s expensive to do that.

[TODO] account for subsampling_info too.

var: None, list of str, str from (‘n’, ‘flux’, ‘nvsqr’, ‘vdist’, ‘phi’), or ‘all’: None –> return dict of answer for each of those vars

‘all’ –> return SnapList where all vars are loadable.

list –> return SnapList where all vars in list are loadable.

str –> return SnapList for this var only.
snaps: None, ‘current’, ‘current_range’, ‘current_n’, or SnapList: the snaps to consider.

None –> self.snaps.

‘current’ –> self.snap

‘current_range’ –> self.snaps.select_between(self.snap[0].t, self.snap[-1].t)

‘current_n’ –> ‘current_range’, but evently downsample result size similar to current n snap.

(note: even downsampling isn’t always possible; result size won’t exactly match.

useful if you want “roughly N snaps”. See example below.)

E.g. if self.snap [10,20,30,…,200] (len=19), and self.snaps [0,…,300] (len=301),

checking where_loadable(var) which is available every 4 snaps, result will be:

None –> [0,4,8,…,300] (len=76)

‘current’ –> [20,40,…,200] (len=10) # because 10,30,50,… aren’t divisible by 4

‘current_range’ –> [12,16,20,…,200] (len=48)

‘current_n’ –> [12,20,28,…,200] (len=24)

# because interprets_fractional_indexing(slice(None,None,1/19), L=48)

# gives slice(0, None, 2), which is then applied to current_range result.
set: bool: if True, also set self.snap = result.

wheref_loadable(var=None, snaps=None, *, set=False)

returns snaps from self.snaps where ‘n’, ‘flux’, ‘nvsqr’, ‘vdist’, ‘phi’ values can be loaded,

for all fluids currently in self.fluid (for non-phi vars).

[EFF] method is IMPLICIT, based on var_out_subcycling details for each fluid.

Does not actually check the files directly, because it’s expensive to do that.

[TODO] account for subsampling_info too.

var: None, list of str, str from (‘n’, ‘flux’, ‘nvsqr’, ‘vdist’, ‘phi’), or ‘all’: None –> return dict of answer for each of those vars

‘all’ –> return SnapList where all vars are loadable.

list –> return SnapList where all vars in list are loadable.

str –> return SnapList for this var only.
snaps: None, ‘current’, ‘current_range’, ‘current_n’, or SnapList: the snaps to consider.

None –> self.snaps.

‘current’ –> self.snap

‘current_range’ –> self.snaps.select_between(self.snap[0].t, self.snap[-1].t)

‘current_n’ –> ‘current_range’, but evently downsample result size similar to current n snap.

(note: even downsampling isn’t always possible; result size won’t exactly match.

useful if you want “roughly N snaps”. See example below.)

E.g. if self.snap [10,20,30,…,200] (len=19), and self.snaps [0,…,300] (len=301),

checking where_loadable(var) which is available every 4 snaps, result will be:

None –> [0,4,8,…,300] (len=76)

‘current’ –> [20,40,…,200] (len=10) # because 10,30,50,… aren’t divisible by 4

‘current_range’ –> [12,16,20,…,200] (len=48)

‘current_n’ –> [12,20,28,…,200] (len=24)

# because interprets_fractional_indexing(slice(None,None,1/19), L=48)

# gives slice(0, None, 2), which is then applied to current_range result.
set: bool: if True, also set self.snap = result.