Add InstantClock and VariableInstantClock support

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/core/Resources.java

@@ -1,11 +1,13 @@
 package gov.nasa.jpl.aerie.contrib.streamline.core;
 
 import gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks.Clock;
+import gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks.InstantClock;
 import gov.nasa.jpl.aerie.merlin.framework.Condition;
 import gov.nasa.jpl.aerie.merlin.framework.Scoped;
 import gov.nasa.jpl.aerie.merlin.protocol.types.Duration;
 import gov.nasa.jpl.aerie.merlin.protocol.types.Unit;
 
+import java.time.Instant;
 import java.util.Collection;
 import java.util.Objects;
 import java.util.Optional;
@@ -20,6 +22,7 @@
 import static gov.nasa.jpl.aerie.contrib.streamline.debugging.Dependencies.addDependency;
 import static gov.nasa.jpl.aerie.contrib.streamline.debugging.Naming.*;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks.Clock.clock;
+import static gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks.InstantClockResources.addToInstant;
 import static gov.nasa.jpl.aerie.merlin.framework.ModelActions.*;
 import static gov.nasa.jpl.aerie.merlin.protocol.types.Duration.ZERO;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.Discrete.discrete;
@@ -38,22 +41,26 @@ private Resources() {}
    *   This method is idempotent; calling it multiple times is the same as calling it once.
    * </p>
    */
-  public static void init() {
-    currentTime();
+  public static void init(Instant planStart) {
+    CLOCK = resource(clock(ZERO));
+    ABSOLUTE_CLOCK = name(addToInstant(planStart, CLOCK), "Global Absolute Simulation Clock");
   }
 
   // TODO if Aerie provides either a `getElapsedTime` method or dynamic allocation of Cells, we can avoid this mutable static variable
-  private static Resource<Clock> CLOCK = resource(clock(ZERO));
+  private static Resource<Clock> CLOCK;
+  private static Resource<InstantClock> ABSOLUTE_CLOCK;
   public static Duration currentTime() {
-    try {
-      return currentValue(CLOCK);
-    } catch (Scoped.EmptyDynamicCellException | IllegalArgumentException e) {
-      // If we're running unit tests, several simulations can happen without reloading the Resources class.
-      // In that case, we'll have discarded the clock resource we were using, and get the above exception.
-      // REVIEW: Is there a cleaner way to make sure this resource gets (re-)initialized?
-      CLOCK = resource(clock(ZERO));
-      return currentValue(CLOCK);
-    }
+    return currentValue(CLOCK);
+  }
+  public static Instant currentInstant() {
+    return currentValue(ABSOLUTE_CLOCK);
+  }
+
+  public static Resource<Clock> simulationClock() {
+    return CLOCK;
+  }
+  public static Resource<InstantClock> absoluteClock() {
+    return ABSOLUTE_CLOCK;
   }
 
   public static <D> D currentData(Resource<D> resource) {

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/Registrar.java

@@ -15,6 +15,8 @@
 import gov.nasa.jpl.aerie.merlin.protocol.types.RealDynamics;
 import gov.nasa.jpl.aerie.merlin.protocol.types.Unit;
 
+import java.time.Instant;
+
 import static gov.nasa.jpl.aerie.contrib.streamline.core.Reactions.whenever;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.Resources.currentData;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.Resources.currentValue;
@@ -54,8 +56,8 @@ public enum ErrorBehavior {
     Throw
   }
 
-  public Registrar(final gov.nasa.jpl.aerie.merlin.framework.Registrar baseRegistrar, final ErrorBehavior errorBehavior) {
-    Resources.init();
+  public Registrar(final gov.nasa.jpl.aerie.merlin.framework.Registrar baseRegistrar, final Instant planStart, final ErrorBehavior errorBehavior) {
+    Resources.init(planStart);
     Logging.init(baseRegistrar);
     this.baseRegistrar = baseRegistrar;
     this.errorBehavior = errorBehavior;

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/InstantClock.java

@@ -0,0 +1,26 @@
+package gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks;
+
+import gov.nasa.jpl.aerie.contrib.streamline.core.Dynamics;
+import gov.nasa.jpl.aerie.merlin.protocol.types.Duration;
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+
+import static gov.nasa.jpl.aerie.merlin.protocol.types.Duration.addToInstant;
+
+/**
+ * A variation on {@link Clock} that represents an absolute {@link Instant}
+ * instead of a relative {@link Duration}.
+ */
+public record InstantClock(Instant extract) implements Dynamics<Instant, InstantClock> {
+    @Override
+    public InstantClock step(Duration t) {
+        return new InstantClock(addToInstant(extract, t));
+    }
+
+    // TODO - this method belongs somewhere else...
+    //  Making it package-private at least lets us move it later without dependency issues outside the library.
+    static Duration durationBetween(Instant start, Instant end) {
+        return Duration.of(ChronoUnit.MICROS.between(start, end), Duration.MICROSECONDS);
+    }
+}

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/InstantClockResources.java

@@ -0,0 +1,56 @@
+package gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks;
+
+import gov.nasa.jpl.aerie.contrib.streamline.core.*;
+import gov.nasa.jpl.aerie.contrib.streamline.core.monads.ResourceMonad;
+import gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.Discrete;
+import gov.nasa.jpl.aerie.merlin.protocol.types.Duration;
+
+import java.time.Instant;
+
+import static gov.nasa.jpl.aerie.contrib.streamline.core.MutableResource.resource;
+import static gov.nasa.jpl.aerie.contrib.streamline.core.monads.ResourceMonad.map;
+import static gov.nasa.jpl.aerie.contrib.streamline.debugging.Naming.name;
+import static gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.DiscreteResources.constant;
+
+public class InstantClockResources {
+    /**
+     * Create an absolute clock that starts now at the given start time.
+     */
+    public static MutableResource<InstantClock> absoluteClock(Instant startTime) {
+        return resource(new InstantClock(startTime));
+    }
+
+    public static Resource<InstantClock> addToInstant(Instant zeroTime, Resource<Clock> relativeClock) {
+        return addToInstant(constant(zeroTime), relativeClock);
+    }
+
+    public static Resource<InstantClock> addToInstant(Resource<Discrete<Instant>> zeroTime, Resource<Clock> relativeClock) {
+        return name(
+                map(zeroTime, relativeClock, (zero, clock) ->
+                        new InstantClock(Duration.addToInstant(zero.extract(), clock.extract()))),
+                "%s + %s",
+                zeroTime,
+                relativeClock);
+    }
+
+    public static Resource<Clock> relativeTo(Resource<InstantClock> clock, Resource<Discrete<Instant>> zeroTime) {
+        return name(ResourceMonad.map(clock, zeroTime, (c, t) -> new Clock(InstantClock.durationBetween(t.extract(), c.extract()))),
+                "%s relative to %s", clock, zeroTime);
+    }
+
+    public static Resource<Discrete<Boolean>> lessThan(Resource<InstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return ClockResources.lessThan(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> lessThanOrEquals(Resource<InstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return ClockResources.lessThanOrEquals(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> greaterThan(Resource<InstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return ClockResources.greaterThan(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> greaterThanOrEquals(Resource<InstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return ClockResources.greaterThanOrEquals(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+}

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/VariableInstantClock.java

@@ -0,0 +1,19 @@
+package gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks;
+
+import gov.nasa.jpl.aerie.contrib.streamline.core.Dynamics;
+import gov.nasa.jpl.aerie.merlin.protocol.types.Duration;
+
+import java.time.Instant;
+
+import static gov.nasa.jpl.aerie.merlin.protocol.types.Duration.addToInstant;
+
+/**
+ * A variation on {@link VariableClock} that represents an absolute {@link Instant}
+ * instead of a relative {@link Duration}.
+ */
+public record VariableInstantClock(Instant extract, int multiplier) implements Dynamics<Instant, VariableInstantClock> {
+    @Override
+    public VariableInstantClock step(Duration t) {
+        return new VariableInstantClock(addToInstant(extract, t.times(multiplier)), multiplier);
+    }
+}

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/VariableInstantClockEffects.java

@@ -0,0 +1,33 @@
+package gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks;
+
+import gov.nasa.jpl.aerie.contrib.streamline.core.MutableResource;
+
+import java.time.Instant;
+
+import static gov.nasa.jpl.aerie.contrib.streamline.core.monads.DynamicsMonad.effect;
+import static gov.nasa.jpl.aerie.contrib.streamline.debugging.Naming.name;
+
+public final class VariableInstantClockEffects {
+    private VariableInstantClockEffects() {}
+
+    /**
+     * Stop the clock without affecting the current time.
+     */
+    public static void pause(MutableResource<VariableInstantClock> clock) {
+        clock.emit("Pause", effect($ -> new VariableInstantClock($.extract(), 0)));
+    }
+
+    /**
+     * Start the clock without affecting the current time.
+     */
+    public static void start(MutableResource<VariableInstantClock> clock) {
+        clock.emit("Start", effect($ -> new VariableInstantClock($.extract(), 1)));
+    }
+
+    /**
+     * Reset the clock to the given time, without affecting how fast it's running.
+     */
+    public static void reset(MutableResource<VariableInstantClock> clock, Instant newTime) {
+        clock.emit(name(effect($ -> new VariableInstantClock(newTime, $.multiplier())), "Reset to %s", newTime));
+    }
+}

contrib/src/main/java/gov/nasa/jpl/aerie/contrib/streamline/modeling/clocks/VariableInstantClockResources.java

@@ -0,0 +1,42 @@
+package gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks;
+
+import gov.nasa.jpl.aerie.contrib.streamline.core.Resource;
+import gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.Discrete;
+import gov.nasa.jpl.aerie.merlin.protocol.types.Duration;
+
+import java.time.Instant;
+
+import static gov.nasa.jpl.aerie.contrib.streamline.core.monads.ResourceMonad.map;
+import static gov.nasa.jpl.aerie.contrib.streamline.debugging.Naming.name;
+import static gov.nasa.jpl.aerie.contrib.streamline.modeling.clocks.InstantClock.durationBetween;
+import static gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.DiscreteResources.constant;
+
+public final class VariableInstantClockResources {
+    private VariableInstantClockResources() {}
+
+    public static Resource<VariableClock> relativeTo(Resource<VariableInstantClock> clock, Resource<Discrete<Instant>> zeroTime) {
+        return name(map(clock, zeroTime, (c, t) ->
+                        new VariableClock(durationBetween(c.extract(), t.extract()), c.multiplier())),
+                "%s relative to %s", clock, zeroTime);
+    }
+
+    public static Resource<Discrete<Boolean>> lessThan(Resource<VariableInstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return VariableClockResources.lessThan(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> lessThanOrEquals(Resource<VariableInstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return VariableClockResources.lessThanOrEquals(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> greaterThan(Resource<VariableInstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return VariableClockResources.greaterThan(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<Discrete<Boolean>> greaterThanOrEquals(Resource<VariableInstantClock> clock, Resource<Discrete<Instant>> threshold) {
+        return VariableClockResources.greaterThanOrEquals(relativeTo(clock, threshold), constant(Duration.ZERO));
+    }
+
+    public static Resource<VariableClock> between(Resource<VariableInstantClock> start, Resource<VariableInstantClock> end) {
+        return map(start, end, (s, e) -> new VariableClock(durationBetween(s.extract(), e.extract()), e.multiplier() - s.multiplier()));
+    }
+}

contrib/src/test/java/gov/nasa/jpl/aerie/contrib/streamline/core/CellRefV2Test.java

@@ -9,10 +9,11 @@
 import org.junit.jupiter.api.TestInstance.Lifecycle;
 import org.junit.jupiter.api.extension.ExtendWith;
 
+import java.time.Instant;
+
 import static gov.nasa.jpl.aerie.contrib.streamline.core.CellRefV2.autoEffects;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.CellRefV2.commutingEffects;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.CellRefV2.noncommutingEffects;
-import static gov.nasa.jpl.aerie.contrib.streamline.core.MutableResource.resource;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.Resources.currentValue;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.Discrete.discrete;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.monads.DiscreteDynamicsMonad.effect;
@@ -27,10 +28,11 @@ class MutableResourceTest {
   @TestInstance(Lifecycle.PER_CLASS)
   class NonCommutingEffects {
     public NonCommutingEffects(final Registrar registrar) {
-      Resources.init();
+      Resources.init(Instant.EPOCH);
+      cell = MutableResource.resource(discrete(42), noncommutingEffects());
     }
 
-    private final MutableResource<Discrete<Integer>> cell = MutableResource.resource(discrete(42), noncommutingEffects());
+    private final MutableResource<Discrete<Integer>> cell;
 
     @Test
     void gets_initial_value_if_no_effects_are_emitted() {
@@ -66,10 +68,11 @@ void throws_exception_when_concurrent_effects_are_applied() {
   @TestInstance(Lifecycle.PER_CLASS)
   class CommutingEffects {
     public CommutingEffects(final Registrar registrar) {
-      Resources.init();
+      Resources.init(Instant.EPOCH);
+      cell = MutableResource.resource(discrete(42), commutingEffects());
     }
 
-    private final MutableResource<Discrete<Integer>> cell = MutableResource.resource(discrete(42), commutingEffects());
+    private final MutableResource<Discrete<Integer>> cell;
 
     @Test
     void gets_initial_value_if_no_effects_are_emitted() {
@@ -108,11 +111,12 @@ void applies_concurrent_effects_in_any_order() {
   @ExtendWith(MerlinExtension.class)
   @TestInstance(Lifecycle.PER_CLASS)
   class AutoEffects {
-    public AutoEffects(final Registrar registrar) {
-      Resources.init();
+    public AutoEffects() {
+      Resources.init(Instant.EPOCH);
+      cell = MutableResource.resource(discrete(42), autoEffects());
     }
 
-    private final MutableResource<Discrete<Integer>> cell = MutableResource.resource(discrete(42), autoEffects());
+    private final MutableResource<Discrete<Integer>> cell;
 
     @Test
     void gets_initial_value_if_no_effects_are_emitted() {

contrib/src/test/java/gov/nasa/jpl/aerie/contrib/streamline/debugging/DependenciesTest.java

@@ -1,7 +1,7 @@
 package gov.nasa.jpl.aerie.contrib.streamline.debugging;
 
-import gov.nasa.jpl.aerie.contrib.streamline.core.MutableResource;
 import gov.nasa.jpl.aerie.contrib.streamline.core.Resource;
+import gov.nasa.jpl.aerie.contrib.streamline.core.Resources;
 import gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.Discrete;
 import gov.nasa.jpl.aerie.contrib.streamline.modeling.discrete.DiscreteResources;
 import gov.nasa.jpl.aerie.contrib.streamline.modeling.polynomial.Polynomial;
@@ -11,6 +11,8 @@
 import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.extension.ExtendWith;
 
+import java.time.Instant;
+
 import static gov.nasa.jpl.aerie.contrib.streamline.core.MutableResource.resource;
 import static gov.nasa.jpl.aerie.contrib.streamline.core.monads.ResourceMonad.*;
 import static gov.nasa.jpl.aerie.contrib.streamline.modeling.polynomial.Polynomial.polynomial;
@@ -21,12 +23,22 @@
 @ExtendWith(MerlinExtension.class)
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 class DependenciesTest {
-  Resource<Discrete<Boolean>> constantTrue = DiscreteResources.constant(true);
-  Resource<Polynomial> constant1234 = constant(1234);
-  Resource<Polynomial> constant5678 = constant(5678);
-  Resource<Polynomial> polynomialCell = resource(polynomial(1));
-  Resource<Polynomial> derived = map(constantTrue, constant1234, constant5678,
-                                     (b, x, y) -> b.extract() ? x : y);
+  public DependenciesTest() {
+    Resources.init(Instant.EPOCH);
+
+    constantTrue = DiscreteResources.constant(true);
+    constant1234 = constant(1234);
+    constant5678 = constant(5678);
+    polynomialCell = resource(polynomial(1));
+    derived = map(constantTrue, constant1234, constant5678,
+                                       (b, x, y) -> b.extract() ? x : y);
+  }
+
+  Resource<Discrete<Boolean>> constantTrue;
+  Resource<Polynomial> constant1234;
+  Resource<Polynomial> constant5678;
+  Resource<Polynomial> polynomialCell;
+  Resource<Polynomial> derived;
 
   @Test
   void constants_are_named_by_their_value() {