[Feature] TimeArray (in progress)

[jpmoutinho]

NOTE: On second thought, this is probably not going to be needed!

Here I draft a proposal of a TimeArray, which represented a sorted list of values (using sortedcontainers) to be used in a piecewise linear pulse specification. It includes some logic for convenience, to be reviewed. I will continue working on this together with the actual piecewise primitive itself, and update here any changes made. Feedback welcome in the meantime.

This I considered but did not add:

• Force the first value to be 0.0.

Behaviour

t = TimeArray([0.0, 1.0, 2.0])
print(t)

> TimeArray([0.0, 1.0, 2.0])

Values and lists of values can be inserted to the "middle" of the array (in place).

t.insert(0.2)
print(t)

> TimeArray([0.0, 0.2, 1.0, 2.0])

t.insert([0.2, 0.5])
print(t)

> TimeArray([0.0, 0.2, 0.2, 0.5, 1.0, 2.0])

Values and lists of values can be "forcefully" appended, which adds the last value to the new values.

t.append(0.6)
print(t)

> TimeArray([0.0, 0.2, 0.2, 0.5, 1.0, 2.0, 2.6])

t.append([0.4, 0.6])
print(t)

> TimeArray([0.0, 0.2, 0.2, 0.5, 1.0, 2.0, 2.6, 3.0, 3.2])

The + operator behaves as insert but without changing in place:

t + 0.5

> TimeArray([0.0, 0.2, 0.2, 0.5, 0.5, 1.0, 2.0, 2.6, 3.0, 3.2])

t + [0.35, 0.55]

> TimeArray([0.0, 0.2, 0.2, 0.35, 0.5, 0.55, 1.0, 2.0, 2.6, 3.0, 3.2])

The * operator multiplies all values

t * 2

> TimeArray([0.0, 0.4, 0.4, 1.0, 2.0, 4.0, 5.2, 6.0, 6.4])

Source code

from sortedcontainers import SortedList
from typing import Union, Iterable

Real = Union[float | int]
Numeric = Union[complex | float | int]

class TimeArray(SortedList):
    """
    An array representing time values.
    """
    
    def __init__(self, iterable: Iterable):
        super().__init__([float(i) for i in iterable])
    
    def insert(self, item: Real | Iterable):
        """Inserts a value or list of values into the time array."""
        if isinstance(item, Real):
            self.add(item)
        elif isinstance(item, Iterable):
            for val in item:
                self.add(val)
        else:
            raise NotImplementedError

    def append(self, item: Real | Iterable):
        """Appends a value or list of values to the end of the time array."""
        last_value = self[-1]
        if isinstance(item, Real):
            self.insert(item + last_value)
        elif isinstance(item, Iterable):
            self.insert([val + last_value for val in item])
        else:
            raise NotImplementedError

    def __add__(self, other: Real | Iterable):
        if isinstance(other, Real):
            return super().__add__([other])
        if isinstance(other, Iterable):
            return super().__add__(other)

    def __mul__(self, other: Real):
        return TimeArray([other * val for val in self])