SnapList

class PlasmaCalcs.dimensions.snaps.SnapList(*args_list, istart=None, **kw_list)

Bases: DimensionValueList, ArraySelectableChildHaver

list of snaps

Methods

__getitem__(ii, **kw_new)	return self[ii], giving element from self if int(ii) possible, else new instance of type(self).
__init_subclass__(*[, array_selectable_child])	called when subclassing ArraySelectableChildHaver; sets cls.select_.
append(object, /)	Append object to the end of the list.
array_equals(other)	tells whether self == other (which is assumed to be a numpy array or xarray.DataArray).
clear()	Remove all items from list.
copy()	Return a shallow copy of the list.
copy_add_t(t_add)	create a copy of self but with t values for all snaps increased by t_add
count(value, /)	Return number of occurrences of value.
datetimestamp(calculator, **kw_datetimestamp)	return array of datetimestamp for each snap in self, for this calculator.
existing_snaps(calculator)	return list like self but skipping any snaps where snap.file_snap(calculator) is MISSING_SNAP.
exists_for(calculator)	return array of snap.exists_for(calculator) for each snap in self.
extend(iterable, /)	Extend list by appending elements from the iterable.
file_path(calculator)	returns array of file_path for each snap in self, for this calculator.
file_s(calculator)	return array of file_s for each snap in self, for this calculator.
file_snap(calculator)	return array of file_snap for each snap in self, for this calculator.
from_array(array)	return SnapList from 0D or 1D array.
from_dict(int_to_element)	return DimensionValueList from dict of {i: element}.
from_dicts(dicts, *[, istart])	return cls instance from iterable of dicts
from_lists(**kw_lists)	return DimensionValueList from zipping these lists of kwarg values.
from_strings(strings)	return cls instance from iterable of strings.
get(key)	return element(s) corresponding to key.
index(value[, start, stop])	Return first index of value.
indices(key, *[, return_get, to_list])	return indices of element(s) corresponding to key, during self.get(key).
insert(index, object, /)	Insert object before index.
inserted(i, element, **kw_new)	return copy of self but with element inserted at i.
iter_pairs([other, ordered, allow_same, ...])	iterator over all possible pairs of (value from self, value from other).
lookup(key, *[, unique_missing_ok, ...])	return element given int, str, or element in self.
lookup_dict()	return dict for looking up elements given int or str (or element) in self.
pairs([other, ordered, allow_same, get_attr])	list of all possible pairs of (value from self, value from other).
pop([index])	Remove and return item at index (default last).
popped(key, *[, return_indices])	return (self.get(key), self.without_i(indices corresponding to key)).
remove(value, /)	Remove first occurrence of value.
reverse()	Reverse *IN PLACE*.
select_after(x)	returns self[i] such that self.t[i] is closest to x, but not smaller than x.
select_all_after(x)	returns self[i:] such that self.t[j] > x, for all j >= i.
select_all_before(x)	returns self[:i] such that self.t[j] < x, for all j < i.
select_before(x)	returns self[i] such that self.t[i] is closest to x, but not larger than x.
select_between(x1, x2)	returns the list of self[i] such that x1 <= self.t[i] <= x2.
select_closest(x[, force_relative])	returns self[i] such that self.t[i] is closest to x.
select_i_after(x)	returns the index of the value in self.t closest to x, but not smaller than x.
select_i_before(x)	returns the index of the value in self.t closest to x, but not larger than x.
select_i_between(x1, x2)	returns the list of indices for all values in self.t with x1 <= value <= x2.
select_i_closest(x[, force_relative])	returns the index of the value in self.t which is closest to x.
serialize()	return serialization of self, into a list of dictionaries.
sort(*[, key, reverse])	Sort the list in ascending order and return None.
to_dict()	returns a list of dictionaries,
unique(*[, istart])	return DimensionValueList of unique elements from self.
unique_from(elements, *elements_as_args[, ...])	return DimensionValueList of unique elements from elements.
where(f, *[, single])	return element(s) where f(element)==True.
with_istart([istart])	return new DimensionValueList with elements reindexed, starting from istart.
without(key, **kw_init)	return a copy of self but dropping element(s) corresponding to key.
without_i(i, **kw_init)	return a copy of self but dropping elements currently at these indices.
_assert_array_equals(other)	raise DimensionValueError unless self.array_equals(other).
_assert_single(vals, *[, meaning])	assert len(vals)==1.
_display_contents(f1[, f2, thresh1, thresh2])	return str to display self's contents, probably using f1(element) for each element.
_new(*args, **kw)	return new instance of type(self), with these args and kw.
_repr_simple()	return simple repr for self; includes type, len, and a repr_simple for a few elements.
_short_repr()	return a shorter repr of self; just includes type & len.

Attributes

array_selectable_child
ndim
reindexed	alias to with_istart
s
size
t

__getitem__(ii, **kw_new)

return self[ii], giving element from self if int(ii) possible, else new instance of type(self).

classmethod __init_subclass__(*, array_selectable_child=None, **kw_super)

called when subclassing ArraySelectableChildHaver; sets cls.select_… methods.

array_selectable_child: None or str

attribute name of child object which will be used for select_… methods.

if None, no select_… methods will be added.

the select_… methods are:

select_i_closest, select_closest,

select_i_before, select_before, select_all_before,

select_i_after, select_after, select_all_after,

select_i_between, select_between

also sets self.array_selectable_child = array_selectable_child, for bookkeeping reasons.

_assert_array_equals(other)

raise DimensionValueError unless self.array_equals(other).

classmethod _assert_single(vals, *, meaning='value')

assert len(vals)==1. Raise DimensionKeyError if len==0; DimensionValueError if len>=2.

meaning can be provided to clarify what vals should represent, in case of crash;

error message will be ‘expected exactly 1 {meaning}, but got {len(vals)}’.

The implementation here is equivalent to cls.value_type._assert_single(vals, meaning=meaning).

_dimension_key_error

alias of SnapKeyError

_dimension_value_error

alias of SnapValueError

_display_contents(f1, f2=<class 'str'>, *, thresh1=4, thresh2=UNSET)

return str to display self’s contents, probably using f1(element) for each element.

f1: callable of element -> str

“full-ish” repr for each element. Reasonable to use a detailed repr.

Gets called if only showing a few elements from self,

i.e. if len(self) <= thresh1, or if len(self) > thresh2.

(when len(self) > thresh2, result tells only len(self), self[0], self[1], and self[-1])

f2: callable of element -> str

abbreviated repr for each element. Should return short string.

Gets called if showing a decent number of elements from self,

i.e. if thresh1 < len(self) <= thresh2.

thresh1: int, see above

thresh2: UNSET or int, see above.

If UNSET, use DEFAULTS.DIMENSION_VALUE_LIST_DISPLAY_MAXLEN

(to see repr for all entries in self consider using list(self).)

_new(*args, **kw)

return new instance of type(self), with these args and kw.

_repr_simple()

return simple repr for self; includes type, len, and a repr_simple for a few elements.

if less than 4 elements, just uses repr_simple for the elements (doesn’t include len).

_short_repr()

return a shorter repr of self; just includes type & len.

append(object, /)

Append object to the end of the list.

array_equals(other)

tells whether self == other (which is assumed to be a numpy array or xarray.DataArray).

return False if other.ndim >= 2, or other.size != len(self).

Else, compare via np.all(other == self) (or, other.values == self, for xarray.)

(Extremely convenient if comparing to xarray DataArray or numpy array,

with potentially unknown size / dimensionality.

Also, convenient if “self” might be DimensionValue instead,

because DimensionValue also provides an array_equals method.)

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

copy_add_t(t_add)

create a copy of self but with t values for all snaps increased by t_add

count(value, /)

Return number of occurrences of value.

datetimestamp(calculator, **kw_datetimestamp)

return array of datetimestamp for each snap in self, for this calculator.

Here, just returns array of [snap.datetimestamp(calculator, **kw_datetimestamp) for snap in self].

existing_snaps(calculator)

return list like self but skipping any snaps where snap.file_snap(calculator) is MISSING_SNAP.

The length of this result might be different from the length of self.

exists_for(calculator)

return array of snap.exists_for(calculator) for each snap in self.

extend(iterable, /)

Extend list by appending elements from the iterable.

file_path(calculator)

returns array of file_path for each snap in self, for this calculator.

Here, just returns array of [snap.file_path(calculator) for snap in self].

file_s(calculator)

return array of file_s for each snap in self, for this calculator.

Here, just returns array of [snap.file_s(calculator) for snap in self].

file_snap(calculator)

return array of file_snap for each snap in self, for this calculator.

Here, just returns array of [snap.file_snap(calculator) for snap in self])

classmethod from_array(array)

return SnapList from 0D or 1D array.

array values should be Snap objects, strings, or ints.

Snap objects –> use as-is

strings –> use Snap(s, i=i) for i in range(len(array))

ints –> use Snap(i=i) for i in array

if array is a DataArray with ‘t’ coord and any value is not a Snap,

use the corresponding t value when creating the Snap objects.

classmethod from_dict(int_to_element)

return DimensionValueList from dict of {i: element}.

See also: cls.from_dicts()

classmethod from_dicts(dicts, *, istart=UNSET, **kw_value_init)

return cls instance from iterable of dicts

values will all be DimensionValue objects, with type == cls.value_type.

dicts: iterable of dicts

each one corresponds to one (cls.value_type) object in result.

istart: UNSET, None, or int

mode for inferring i values if needed.

UNSET –> dicts[k] uses i=dicts[k][‘i’] if it exists, else i=k.

None –> use i from dict if it exists, else None.

int –> dicts[k] uses i=istart+k, ignoring any ‘i’ provided in dict.

additional kwargs will be passed to cls.value_type.__init__

(in case of conflict with any dicts values, use dicts values).

classmethod from_lists(**kw_lists)

return DimensionValueList from zipping these lists of kwarg values.

E.g. from_lists(s=[‘e’, ‘H’, ‘H+’], q=[-1, 0, 1]) is equivalent to

cls.from_dicts([dict(s=’e’, q=-1), dict(s=’H’, q=0), dict(s=’H+’, q=1)])

classmethod from_strings(strings)

return cls instance from iterable of strings. (i will be determined automatically.)

Equivalent to cls(cls.value_type(s, i) for i, s in enumerate(strings)).

get(key)

return element(s) corresponding to key.

key: None, int, str, element, DimensionSpecialValueSpecifier, range, slice, or tuple/list

Some keys will look up and return corresponding element(s):

nonnegative int, str, or element –> return corresponding element.

DimensionSpecialValueSpecifier spec –> return spec.getter(self).

tuple/list –> return tuple/list(self.get(k) for k in key),

flattening any term which would otherwise become a DimensionValueList.

(e.g. [ELECTRON, IONS] –> [e, ion1, ion2, ion3], not [e, [ion1, ion2, ion3]])

range –> return type(self)(self.get(k) for k in key).

Other keys will index self using the usual list-like indexing rules:

None –> return self, unchanged.

negative int –> return self[key], i.e. the key’th element, counting from end.

slice –> return self[key], i.e. apply this slice to self.

Note that the result will have the same type as self.

Note that this supports interprets_fractional_indexing,

e.g. slice(0.3, 0.7) will slice(len(self) * 0.3, len(self) * 0.7).

if any element in a tuple or list is not in self,

keep it unchanged if it is a UniqueDimensionValue,

else raise DimensionKeyError.

Note that the result will always be single element, a tuple, a list, or a DimensionValueList.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

indices(key, *, return_get=False, to_list=False)

return indices of element(s) corresponding to key, during self.get(key).

to_list: bool.

True –> return [index] instead of index, if self.get(key) is a single DimensionValue.

return_get: bool

True –> return (indices, self.get(key)) instead of just indices.

result will have same length as self.get(key); self[result[i]] is self.get(key)[i].

insert(index, object, /)

Insert object before index.

inserted(i, element, **kw_new)

return copy of self but with element inserted at i. kwargs passed to new self.__init__.

iter_pairs(other=None, *, ordered=False, allow_same=True, get_attr=None)

iterator over all possible pairs of (value from self, value from other).

other: None or iterable (probably DimensionValueList)

None –> use other = self, i.e. just get pairings from within self.

ordered: bool

whether to only return pairs (A,B) with A <= B.

allow_same: bool

whether to allow pairs (A,B) with A == B.

get_attr: None

attr to return from objects, instead of returning the objects themselves.

E.g. return_attr=’s’ –> pairs will be like (A.s, B.s) instead of (A, B).

lookup(key, *, unique_missing_ok=False, handle_special=True)

return element given int, str, or element in self. raise DimensionKeyError if key not in self.

unique_missing_ok: bool

whether it is okay for self to be missing key if key is a UniqueDimensionValue.

if True and key is a UniqueDimensionValue, return key instead of raising error.

handle_special: bool

whether to handle DimensionSpecialValueSpecifier in special way,

i.e. if key is a DimensionSpecialValueSpecifier, return key.getter(self).

lookup_dict()

return dict for looking up elements given int or str (or element) in self.

uses caching; assumes int(element) & str(element) never changes for any element.

pairs(other=None, *, ordered=False, allow_same=True, get_attr=None)

list of all possible pairs of (value from self, value from other).

other: None or iterable (probably DimensionValueList)

None –> use other = self, i.e. just get pairings from within self.

ordered: bool

whether to only return pairs (A,B) with A <= B.

allow_same: bool

whether to allow pairs (A,B) with A == B.

get_attr: None

attr to return from objects, instead of returning the objects themselves.

E.g. return_attr=’s’ –> pairs will be like (A.s, B.s) instead of (A, B).

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

popped(key, *, return_indices=False, **kw_init)

return (self.get(key), self.without_i(indices corresponding to key)).

see help(self.get) for details on allowed keys.

return_indices: bool

if True, also return the indices (as a list) of the popped element(s),

i.e. return (indices, popped element(s), self.without_i(…), self with elements removed).

index will be None if no elements were removed.

kw_init are used when making the copy of self. E.g. use istart=0 to make the copy start at 0.

See also: self.without(), which just returns self with elements removed.

property reindexed

alias to with_istart

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse *IN PLACE*.

select_after(x)

returns self[i] such that self.t[i] is closest to x, but not smaller than x.

If x is iterable, [self.select_after(y) for y in x].

If self supports fancy indexing, will use self[indices],

otherwise use type(self)[self[i] for i in indices].

select_all_after(x)

returns self[i:] such that self.t[j] > x, for all j >= i.

select_all_before(x)

returns self[:i] such that self.t[j] < x, for all j < i.

select_before(x)

returns self[i] such that self.t[i] is closest to x, but not larger than x.

If x is iterable, [self.select_before(y) for y in x].

If self supports fancy indexing, will use self[indices],

otherwise use type(self)[self[i] for i in indices].

select_between(x1, x2)

returns the list of self[i] such that x1 <= self.t[i] <= x2.

select_closest(x, force_relative=None)

returns self[i] such that self.t[i] is closest to x.

If x is iterable, [self.select_closest(y) for y in x].

If self supports fancy indexing, will use self[indices],

otherwise use type(self)[self[i] for i in indices].

force_relative: None, ‘before’, ‘after’, ‘equal’, or ‘isclose’

whether to also force a certain relationship between result and x:

result <= x (if ‘before),

result >= x (if ‘after’),

result == x (if ‘equal’),

np.isclose(result, x, atol=0) (if ‘isclose’).

select_i_after(x)

returns the index of the value in self.t closest to x, but not smaller than x.

If x is iterable, [self.select_i_after(y) for y in x].

select_i_before(x)

returns the index of the value in self.t closest to x, but not larger than x.

If x is iterable, [self.select_i_before(y) for y in x].

select_i_between(x1, x2)

returns the list of indices for all values in self.t with x1 <= value <= x2.

select_i_closest(x, force_relative=None)

returns the index of the value in self.t which is closest to x.

If x is iterable, [self.select_i_closest(y) for y in x].

force_relative: None, ‘before’, ‘after’, ‘equal’, or ‘isclose’

whether to also force a certain relationship between result and x:

result <= x (if ‘before),

result >= x (if ‘after’),

result == x (if ‘equal’),

np.isclose(result, x, atol=0) (if ‘isclose’).

serialize()

return serialization of self, into a list of dictionaries.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the

order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them,

ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_dict()

returns a list of dictionaries,

each dictionary corresponds to each DimensionValue in the DimensionValueList.

unique(*, istart=None)

return DimensionValueList of unique elements from self.

equality checked via element.equal_except_i, i.e. ignore index.

(if all elements are unique, return self, else return new DimensionValueList.)

istart: None or int. int –> use result[k].with_i(istart + k) for all k.

classmethod unique_from(elements, *elements_as_args, istart=None)

return DimensionValueList of unique elements from elements.

equality checked via element.equal_except_i, i.e. ignore index.

elements: iterable of DimensionValue of cls.value_type.

or, single DimensionValue, in which case treat it as first arg,

and can provide more elements as additional args.

istart: None or int. int –> use result[k].with_i(istart + k) for all k.

value_type

alias of Snap

where(f, *, single=False)

return element(s) where f(element)==True.

f: callable of element -> bool

function to apply to each element in self.

single: bool

whether to return a single element instead of a DimensionValueList.

if True, ensure exactly one element satisfied f(element)==True, else crash.

with_istart(istart=0)

return new DimensionValueList with elements reindexed, starting from istart.

elements with incorrect i will be replaced with copies.

if istart is None, just return self, unchanged.

without(key, **kw_init)

return a copy of self but dropping element(s) corresponding to key.

see help(self.get) for details on allowed keys.

See also: self.popped(), which additionally returns the popped elements.

without_i(i, **kw_init)

return a copy of self but dropping elements currently at these indices.

i: int or iterable of int. indices to remove.

kw_init are passed to __init__ when making the copy of self.