interprets_fractional_indexing

PlasmaCalcs.tools.arrays.interprets_fractional_indexing(indexer, L=None, *, rounding=UNSET): interprets any fractional values, i.e. non-integers between -1 and 1.

returns indexer in “canonical” form, no longer containing any fractional values.

If indexer contains no fractional values, return indexer unchanged.

indexer: None, int, slice, iterable, or non-integer between -1 and 1.

indexer to interpret; might contain fractional value(s), i.e. non-integers between -1 and 1.

any fractional values will be converted to value*(L+1), then rounded to an integer.

rounding method is determined by rounding, unless indexer is a slice,

in which case rounding for start & stop is handled differently.

fractional values might appear in any of the following ways:

- as an individual float, e.g. 0.3

- as a float inside an iterable, e.g. [0, 0.25, 0.5, 0.75, 1]

- as a float inside a slice, e.g. slice(0, -0.1, 0.02)

“fractional” is tested via (-1 < value < 1) and (value != 0).

L: None or int

length of the object being indexed. Required if any fractional values provided.

None –> if any fractional values provided, raise InputMissingError.

L must be >= 2. [TODO] handle L=1 case (have all fractional values imply 0).

rounding: UNSET, ‘round’, ‘floor’, ‘ceil’ or ‘int’

method to use for rounding fractional values to integers, except for slice.start or slice.stop.

UNSET –> use DEFAULTS.FRACTIONAL_INDEX_ROUNDING (default: floor)

‘round’ –> as per builtins.round(). round to nearest integer, ties toward even integers.

‘int’ –> as per builtins.int(). round towards 0.

‘floor’ –> as per math.floor(). round towards negative infinity.

‘ceil’ –> as per math.ceil(). round towards positive infinity.

Rounding for slice.start and start.stop will ALWAYS include all indices between start*(L-1) and stop*(L-1)

For positive (or None) step, this means: round all numbers toward +infinity.

Examples (floats here are after multiplying input by L-1, e.g. 0.1 * 153 –> 15.3):

slice(15.3, 29.2, 1) –> slice(16, 30, 1) # 15.3, [16, 17, …, 29], 29.2

slice(-29.2, -15.3, 1) –> slice(-29, -15, 1) # -29.2, [-29, -28, …, -16], -15.3

slice(15.3, -15.3, 1) –> slice(16, -15, 1) # 15.3, [16, 18, …, -17, -16], -15.3

slice(-29.2, 100.1, 1) –> slice(-29, 101, 1) # -29.2, [-29, -28, …, 99, 100], 100.1

For negative step, this means: round all numbers toward -infinity.

Examples (floats here are after multiplying input by L-1, e.g. 0.1 * 153 –> 15.3):

slice(29.2, 15.3, -1) –> slice(29, 15, -1) # 29.2, [29, 28, …, 17, 16], 15.3

slice(-15.3, -29.2, -1) –> slice(-16, -30, -1) # -15.3, [-16, -17, …, -28, -29], -29.2

slice(-15.3, 15.3, -1) –> slice(-16, 15, -1) # -15.3, [-16, -17, …, 16, 15], 15.3

slice(100.1, -29.2, -1) –> slice(100, -30, -1) # 100.1, [100, 99, …, -28, -29], -29.2

Rounding mode for slice.step is determined by rounding, applying to step*L (not L-1).

however if this causes step=0, instead use step=1 or step=-1, based on sign of original step.

— Examples —

# [TODO] update these when considering N = L-1 is what is actually being multiplied.

interprets_fractional_indexing(0.5, L=10) –> 5

interprets_fractional_indexing(slice(0.2, 0.9, 0.1), L=10) –> slice(2, 9, 1)

interprets_fractional_indexing([0.2, 0.5, -3, 8, 7, 0.9], L=10) –> [2, 5, -3, 8, 7, 9]

interprets_fractional_indexing(0.23, L=10, rounding=’int’) –> 2

interprets_fractional_indexing(0.23, L=10, rounding=’ceil’) –> 3