Remove absolute/relative Timelines distinction

Author: LourensVeen

ymmsl/v0_2/ports.py

@@ -8,30 +8,31 @@
 class Timeline:
     """Identify a timeline on which a port sends or receives.
 
-    Timeline objects describe when a port sends or receives, either relative to a parent
-    timeline that calls the component they're a part of, or by describing the whole list
-    of components calling each other from the root timeline down.
-
-    A component c1 that is not called by any other component will have its F_INIT and
-    O_F ports (if any) on the root timeline, which is represented by ':'. If c1's
-    implementation has a loop in which it sends on an O_I port and receives on an S
-    port, then those ports are on a subtimeline, which is named after the component by
-    default, ':c1'.
-
-    If we add a component c2 and connect its F_INIT and O_F to those ports, then we
-    create a macro-micro type coupling. The F_INIT and O_F ports of c2 will then be on
-    timeline ':c1', because they'll receive and send at the exact points in simulated
-    time that c1's O_I and S ports send and receive.
-
-    If c2 has its own O_I and S ports, then those will be on timeline ':c1:c2', this
-    being the concatenation of the parent timeline and the relative timeline within c2.
-
-    Some implementations may have more than one set of O_I/S ports, on which they
-    communicate at different rates. In that case, each port should be given a local
-    relative timeline explicitly. In the above example, if c1's O_I and S ports were
-    specified to be on local relative timeline 'tl1', then their full relative timeline
-    is 'c1.tl' and their absolute timeline is ':c1.tl`, putting c2's O_I and S ports on
-    ':c1.tl:c2' unless they too have an explicit timeline designation.
+    A timeline is a stretch of time with a beginning and an end that is subdivided into
+    zero or more time steps that step from one intermediate time point to the next.
+
+    F_INIT ports receive at the beginning of the timeline, O_F ports send at the end of
+    the timeline, O_I ports send at the first and intermediate points on the timeline,
+    and S ports receive at intermediate and the last time point of the timeline.
+
+    Timeline objects are used to annotate components and ports, to describe which
+    timeline they're on.
+
+    For components, the timeline depends on where in a call hierarchy the component
+    sits. A component ``c1`` that is not called (via an O_I to F_INIT conduit) by any
+    other model has timeline ``c1``, relative to the model it's in. If ``c2`` is called
+    by ``c1``, then it is in timeline ``c2`` relative to its *parent timeline* ``c1``,
+    and in ``c1:c2`` relative to the model. If ``c1`` dispatches (O_F to F_INIT) to
+    ``c3``, then ``c3``'s parent timeline is the same as ``c1``'s parent timeline, which
+    is the empty model timeline, putting component ``c3`` into timeline ``c3``.
+
+    Ports are on the timeline of the component they're associated with. Some components
+    however have multiple sets of O_I/S ports, on which they communicate at different
+    rates. Each group of such ports is annotated, using this class, with a timeline
+    annotation naming the sub-timeline that port is on. If an O_I port on component
+    ``c1`` is annotated with ``tl1``, then that port will be on timeline ``c1.tl1``
+    rather than on ``c1``, and if it were on ``c2`` then the full timeline would be
+    ``c1:c2.tl1``.
 
     Timelines have a technical representation as a list of References, and a string
     representation in which those References are joined using colons.
@@ -41,14 +42,11 @@ class Timeline:
     def __init__(self, timeline: str) -> None: ...
 
     @overload
-    def __init__(
-        self, timeline: Sequence[str | Reference], absolute: bool = True
-    ) -> None: ...
+    def __init__(self, timeline: Sequence[str | Reference]) -> None: ...
 
     def __init__(
         self,
         timeline: str | Sequence[str | Reference],
-        absolute: bool = True,
     ) -> None:
         """Create a Timeline.
 
@@ -60,32 +58,21 @@ def make_new_reference(x: str | Reference) -> Reference:
             return Reference(str(x))
 
         if isinstance(timeline, str):
+            timeline = timeline.strip(":")
             if timeline == "":
-                self.absolute = False
-                parts: Sequence[str | Reference] = []
-            elif timeline == ":":
-                self.absolute = True
-                parts = []
-            else:
-                self.absolute = False
-                if timeline[0] == ":":
-                    self.absolute = True
-                    timeline = timeline[1:]
-
-                parts = timeline.split(":")
+                self._parts = []
+                return
 
-            self._parts = list(map(make_new_reference, parts))
+            timeline = timeline.split(":")
 
-        else:
-            self.absolute = absolute
-            self._parts = list(map(make_new_reference, timeline))
+        self._parts = list(map(make_new_reference, timeline))
 
     def __eq__(self, other: Any) -> bool:
         """Compare with another Timeline or a string for equality."""
         if isinstance(other, str):
             return str(self) == other
         elif isinstance(other, Timeline):
-            return self.absolute == other.absolute and self._parts == other._parts
+            return self._parts == other._parts
         return NotImplemented
 
     def __hash__(self) -> int:
@@ -103,8 +90,7 @@ def __lt__(self, other: Any) -> bool:
 
     def __str__(self) -> str:
         """Return the string representation of this Timeline."""
-        anchor = ":" if self.absolute else ""
-        return anchor + ":".join(map(str, self._parts))
+        return ":".join(map(str, self._parts))
 
     def __repr__(self) -> str:
         """Return a representation of the object."""
@@ -138,16 +124,12 @@ def __iter__(self) -> Iterator[Reference]:
         yield from self._parts
 
     def __add__(self, other: Any) -> "Timeline":
-        """Concatenate this timeline with another (relative!) Timeline."""
+        """Concatenate this timeline with another Timeline."""
         if isinstance(other, Timeline):
-            if other.absolute:
-                raise ValueError(
-                    "Cannot concatenate an absolute Timeline onto another one"
-                )
-            return Timeline(self._parts + other._parts, self.absolute)
+            return Timeline(self._parts + other._parts)
 
         if isinstance(other, Reference):
-            return Timeline(self._parts + [other], self.absolute)
+            return Timeline(self._parts + [other])
 
         return NotImplemented
 
@@ -159,19 +141,16 @@ def parent(self) -> "Timeline":
             RuntimeError if this is the root and there is no parent."""
         if not self._parts:
             raise RuntimeError("The root timeline does not have a parent")
-        return Timeline(self._parts[:-1], self.absolute)
+        return Timeline(self._parts[:-1])
 
     def relative_to(self, other: "Timeline") -> "Timeline":
         """Compute a version of this timeline relative to `other`.
 
-        Both timelines must be absolute, and the other timeline must be a parent
-        timeline of this one.
+        The other timeline must be a parent timeline of this one.
         """
-        if not self.absolute or not other.absolute:
-            raise ValueError("Both timelines must be absolute")
         if self._parts[: len(other)] != other._parts:
             raise ValueError(f"{self} is not a subtimeline of {other}")
-        return Timeline(self._parts[len(other) :], False)
+        return Timeline(self._parts[len(other) :])
 
 
 class Port:

ymmsl/v0_2/tests/test_ports.py

@@ -9,54 +9,41 @@
 
 def test_create_empty_timeline() -> None:
     tl = Timeline("")
-    assert tl.absolute is False
     assert len(tl._parts) == 0
 
 
 def test_create_root_timeline() -> None:
     tl = Timeline(":")
-    assert tl.absolute is True
     assert len(tl._parts) == 0
 
 
-def test_create_absolute_timeline() -> None:
-    tl = Timeline(":timeline")
-    assert tl.absolute is True
-    assert len(tl._parts) == 1
-    assert tl._parts[0] == "timeline"
-
-
-def test_create_relative_timeline() -> None:
+def test_create_timeline() -> None:
     tl = Timeline("timeline")
-    assert tl.absolute is False
     assert len(tl._parts) == 1
     assert tl._parts[0] == "timeline"
 
 
 def test_create_full_timeline() -> None:
     tl = Timeline("c1.a:c2.b:c3:c4")
-    assert tl.absolute is False
     assert len(tl._parts) == 4
     assert tl._parts == ["c1.a", "c2.b", "c3", "c4"]
 
 
-def test_create_absolute_from_list_of_str() -> None:
-    tl = Timeline(["c1.a", "c2.b", "c3", "c4"], True)
-    assert tl.absolute is True
+def test_create_from_list_of_str() -> None:
+    tl = Timeline(["c1.a", "c2.b", "c3", "c4"])
     assert len(tl._parts) == 4
     assert tl._parts == ["c1.a", "c2.b", "c3", "c4"]
 
 
-def test_create_relative_from_list_of_ref() -> None:
-    tl = Timeline([Ref("c1"), Ref("c2.a")], False)
-    assert tl.absolute is False
+def test_create_from_list_of_ref() -> None:
+    tl = Timeline([Ref("c1"), Ref("c2.a")])
     assert len(tl._parts) == 2
     assert tl._parts == ["c1", "c2.a"]
 
 
 def test_timeline_equality() -> None:
     tl1 = Timeline(":c0:c1:c2.a")
-    tl2 = Timeline(["c0", "c1", "c2.a"], True)
+    tl2 = Timeline(["c0", "c1", "c2.a"])
     assert tl1 == tl2
 
     tl2._parts[1] = Reference("c1.x")
@@ -65,26 +52,14 @@ def test_timeline_equality() -> None:
     tl1._parts[1] = Reference("c1.x")
     assert tl1 == tl2
 
-    tl2.absolute = False
-    assert tl1 != tl2
-
-    tl1.absolute = False
-    assert tl1 == tl2
-
-    tl2.absolute = True
-    assert tl1 != tl2
-
 
 def test_timeline_to_str() -> None:
-    tl = Timeline([Ref("c1"), Ref("c2.a"), Ref("c3")], False)
+    tl = Timeline([Ref("c1"), Ref("c2.a"), Ref("c3")])
     assert str(tl) == "c1:c2.a:c3"
 
-    tl.absolute = True
-    assert str(tl) == ":c1:c2.a:c3"
-
 
 def test_timeline_indexing() -> None:
-    tl = Timeline(":c0:c1:c2.p:c3.q")
+    tl = Timeline("c0:c1:c2.p:c3.q")
     assert len(tl) == 4
     assert isinstance(tl[0], Reference)
     assert tl[0] == "c0"
@@ -98,20 +73,17 @@ def test_timeline_indexing() -> None:
     with pytest.raises(IndexError):
         tl[4]
 
+    assert tl[0:2] == "c0:c1"
+    assert tl[1:3] == "c1:c2.p"
+
 
 def test_timeline_concatenation() -> None:
-    tl1 = Timeline(":c1:c2.a")
+    tl1 = Timeline("c1:c2.a")
     tl2 = Timeline("c3.b:c4")
     tl3 = tl1 + tl2
 
-    assert tl3.absolute is True
     assert len(tl3._parts) == 4
-    assert tl3 == Timeline(":c1:c2.a:c3.b:c4")
-
-    tl2.absolute = True
-
-    with pytest.raises(ValueError):
-        tl1 + tl2
+    assert tl3 == Timeline("c1:c2.a:c3.b:c4")
 
 
 def test_timeline_concatenate_empty() -> None:
@@ -133,20 +105,14 @@ def test_timeline_parent() -> None:
         _ = Timeline(":").parent
 
     assert Timeline("a:b").parent == Timeline("a")
-    assert Timeline(":a:b").parent == Timeline(":a")
 
 
 def test_timeline_relative_to() -> None:
-    assert Timeline(":a:b:c").relative_to(Timeline(":a:b")) == Timeline("c")
-    assert Timeline(":a:b:c").relative_to(Timeline(":a")) == Timeline("b:c")
-
-    with pytest.raises(ValueError, match="absolute"):
-        Timeline("a:b").relative_to(Timeline(":a"))
-    with pytest.raises(ValueError, match="absolute"):
-        Timeline(":a:b").relative_to(Timeline("a"))
+    assert Timeline("a:b:c").relative_to(Timeline("a:b")) == Timeline("c")
+    assert Timeline("a:b:c").relative_to(Timeline("a")) == Timeline("b:c")
 
     with pytest.raises(ValueError, match="subtimeline"):
-        Timeline(":a:b").relative_to(Timeline(":b"))
+        Timeline("a:b").relative_to(Timeline("b"))
 
 
 def test_create_empty_ports() -> None:

ymmsl/v0_2/tests/test_timeline_resolver.py

@@ -29,15 +29,15 @@ def test_consistent_configuration(timelines_configuration: Configuration) -> Non
 def test_dispatch(timelines_configuration: Configuration) -> None:
     model = timelines_configuration.models[Ref("dispatch")]
     resolve_timelines(model)
-    assert model.components[Ref("first")].timeline == ":first"
-    assert model.components[Ref("second")].timeline == ":second"
+    assert model.components[Ref("first")].timeline == "first"
+    assert model.components[Ref("second")].timeline == "second"
 
 
 def test_macromicro(timelines_configuration: Configuration) -> None:
     model = timelines_configuration.models[Ref("macromicro")]
     resolve_timelines(model)
-    assert model.components[Ref("macro")].timeline == Timeline(":macro")
-    assert model.components[Ref("micro")].timeline == Timeline(":macro:micro")
+    assert model.components[Ref("macro")].timeline == Timeline("macro")
+    assert model.components[Ref("micro")].timeline == Timeline("macro:micro")
 
 
 def test_cycle(timelines_configuration: Configuration) -> None:
@@ -48,8 +48,8 @@ def test_cycle(timelines_configuration: Configuration) -> None:
 def test_reducer(timelines_configuration: Configuration) -> None:
     model = timelines_configuration.models[Ref("reducer")]
     resolve_timelines(model)
-    assert model.components[Ref("first")].timeline == Timeline(":first")
-    assert model.components[Ref("second")].timeline == Timeline(":second")
+    assert model.components[Ref("first")].timeline == Timeline("first")
+    assert model.components[Ref("second")].timeline == Timeline("second")
 
 
 def test_only_reducer(timelines_configuration: Configuration) -> None:
@@ -58,8 +58,8 @@ def test_only_reducer(timelines_configuration: Configuration) -> None:
     del model.conduits[0]
     assert model.conduits[0].filters == [ConduitFilter("last")]
     resolve_timelines(model)
-    assert model.components[Ref("first")].timeline == Timeline(":first")
-    assert model.components[Ref("second")].timeline == Timeline(":second")
+    assert model.components[Ref("first")].timeline == Timeline("first")
+    assert model.components[Ref("second")].timeline == Timeline("second")
 
 
 def test_too_many_reducers(timelines_configuration: Configuration) -> None:
@@ -77,9 +77,9 @@ def test_inconsistent_timelines(timelines_configuration: Configuration) -> None:
 def test_repeaters(timelines_configuration: Configuration) -> None:
     model = timelines_configuration.models[Ref("repeaters")]
     resolve_timelines(model)
-    assert model.components[Ref("macro")].timeline == Timeline(":macro")
-    assert model.components[Ref("meso")].timeline == Timeline(":macro:meso")
-    assert model.components[Ref("micro")].timeline == Timeline(":macro:meso:micro")
+    assert model.components[Ref("macro")].timeline == Timeline("macro")
+    assert model.components[Ref("meso")].timeline == Timeline("macro:meso")
+    assert model.components[Ref("micro")].timeline == Timeline("macro:meso:micro")
 
 
 def test_too_many_repeaters(timelines_configuration: Configuration) -> None:
@@ -106,10 +106,10 @@ def test_repeater_and_too_many_reducers(timelines_configuration: Configuration)
 def test_repeater_after_reducer(timelines_configuration: Configuration) -> None:
     model = timelines_configuration.models[Ref("repeater_reducer")]
     resolve_timelines(model)
-    assert model.components[Ref("macro1")].timeline == Timeline(":macro1")
-    assert model.components[Ref("macro2")].timeline == Timeline(":macro2")
-    assert model.components[Ref("micro1")].timeline == Timeline(":macro1:micro1")
-    assert model.components[Ref("micro2")].timeline == Timeline(":macro2:micro2")
+    assert model.components[Ref("macro1")].timeline == Timeline("macro1")
+    assert model.components[Ref("macro2")].timeline == Timeline("macro2")
+    assert model.components[Ref("micro1")].timeline == Timeline("macro1:micro1")
+    assert model.components[Ref("micro2")].timeline == Timeline("macro2:micro2")
 
     # Remove filters on the last conduit to make the incoming timelines inconsistent
     model.conduits[-1].filters = []
@@ -123,9 +123,9 @@ def test_repeater_after_reducer_error(timelines_configuration: Configuration) ->
         resolve_timelines(model)
     model.conduits[-1].filters = []
     resolve_timelines(model)
-    assert model.components[Ref("macro")].timeline == Timeline(":macro")
-    assert model.components[Ref("micro1")].timeline == Timeline(":macro:micro1")
-    assert model.components[Ref("micro2")].timeline == Timeline(":macro:micro2")
+    assert model.components[Ref("macro")].timeline == Timeline("macro")
+    assert model.components[Ref("micro1")].timeline == Timeline("macro:micro1")
+    assert model.components[Ref("micro2")].timeline == Timeline("macro:micro2")
 
 
 def test_inconsistent_interact(timelines_configuration: Configuration) -> None:

ymmsl/v0_2/timeline_resolver.py

@@ -306,10 +306,10 @@ def timeline_for_port(
             port = self._all_ports[port_name]
             if port.timeline:
                 subtimeline = Timeline(
-                    [f"{component}.{name}" for name in port.timeline], False
+                    [f"{component}.{name}" for name in port.timeline]
                 )
             else:
-                subtimeline = Timeline([component], False)
+                subtimeline = Timeline([component])
 
             result = parent_tl + subtimeline