feat: add cursor notion to retrieve measures based on timestamp

Author: metacosm

measure/src/main/java/net/laprun/sustainability/power/measure/Cursor.java

@@ -0,0 +1,109 @@
+package net.laprun.sustainability.power.measure;
+
+import java.time.Duration;
+import java.util.Arrays;
+
+public enum Cursor {
+    ;
+
+    public static PartialCursor cursorOver(long[] timestamps, long timestamp, Duration duration, long initialOffset,
+            long averagePeriodHint) {
+        // adjusted timestamp for modding
+        System.out.println(Arrays.toString(timestamps));
+        System.out.println("timestamp = " + timestamp);
+        final var timestampForDiv = timestamp - initialOffset;
+        final var durationAsMs = duration.toMillis();
+        System.out.println("durationAsMs = " + durationAsMs);
+
+        // cannot find an interval for a timestamp that is before the recording started
+        if (timestampForDiv < 0) {
+            return PartialCursor.empty;
+        }
+
+        if (timestamps.length < 2) {
+            // if we don't have a sample period, use the full measure
+            double ratio = 1.0;
+            if (averagePeriodHint > 0) {
+                ratio = (double) durationAsMs / averagePeriodHint;
+            }
+            return new PartialCursor(0, 0, ratio, ratio);
+        }
+
+        // estimate sample period based on 2 samples interval
+        if (averagePeriodHint <= 0) {
+            averagePeriodHint = timestamps[1] - timestamps[0];
+        }
+
+        // first, find potential first sample based on timestamp
+        int startIndex = (int) Math.floorDiv(timestampForDiv, averagePeriodHint);
+        System.out.println("startIndex = " + startIndex);
+        int endIndex = (int) Math.floorDiv(timestampForDiv + durationAsMs, averagePeriodHint);
+        System.out.println("endIndex = " + endIndex);
+
+        if (startIndex == endIndex) {
+            final long previousTimestamp = startIndex == 0 ? initialOffset : timestamps[startIndex - 1];
+            final long slotDuration = timestamps[startIndex] - previousTimestamp;
+            var ratio = (double) durationAsMs / slotDuration;
+            return new PartialCursor(startIndex, endIndex, ratio, -1);
+        }
+
+        // get the index with the timestamp right after the one we're looking for since what we're interested in is the portion of the measure that gets recorded after the timestamp we want
+        long afterTimestamp = timestamps[startIndex];
+        final long startOffset = afterTimestamp - timestamp;
+        double startRatio = 0;
+        if (startOffset > 0) {
+            startRatio = (double) startOffset / (afterTimestamp - timestamps[startIndex - 1]);
+        }
+
+        // look for the index that records the first timestamp that's after the one we're looking for added to the duration
+        afterTimestamp = timestamps[endIndex];
+        final long slotDuration = afterTimestamp - timestamps[endIndex - 1];
+        final long endOffset = slotDuration - (afterTimestamp - timestamp - durationAsMs);
+        double endRatio = 0;
+        if (endOffset > 0) {
+            endRatio = (double) endOffset / slotDuration;
+        }
+
+        return new PartialCursor(startIndex, endIndex, startRatio, endRatio);
+    }
+
+    public record PartialCursor(int startIndex, int endIndex, double firstMeasureRatio, double lastMeasureRatio) {
+
+        public static final PartialCursor empty = new PartialCursor(-1, -1, 0.0, 0.0);
+
+        public double sum(double[] values) {
+            if (values == null || values.length == 0 || this == empty || values.length < startIndex + endIndex) {
+                return 0.0;
+            }
+
+            if (startIndex == endIndex) {
+                return values[startIndex] * firstMeasureRatio;
+            }
+
+            double sum = values[startIndex] * firstMeasureRatio;
+            for (int i = startIndex + 1; i < endIndex; i++) {
+                sum += values[i];
+            }
+            sum += values[endIndex] * lastMeasureRatio;
+
+            return sum;
+        }
+
+        public double[] viewOf(double[] values) {
+            if (values == null || values.length == 0 || this == empty || values.length < startIndex + endIndex) {
+                return new double[0];
+            }
+
+            if (startIndex == endIndex) {
+                return new double[] { values[startIndex] * firstMeasureRatio };
+            }
+
+            final int len = endIndex - startIndex + 1;
+            final double[] view = new double[len];
+            view[0] = values[startIndex] * firstMeasureRatio;
+            System.arraycopy(values, startIndex + 1, view, 1, len - 1 - 1);
+            view[len - 1] = values[endIndex] * lastMeasureRatio;
+            return view;
+        }
+    }
+}

measure/src/main/java/net/laprun/sustainability/power/measure/OngoingPowerMeasure.java

@@ -139,4 +139,8 @@ public synchronized TimestampedMeasures getNthTimestampedMeasures(int n) {
         }
         return new TimestampedMeasures(timestamps[n], result);
     }
+
+    public Cursor.PartialCursor getCursorOver(long timestamp, Duration duration) {
+        return Cursor.cursorOver(timestamps, timestamp, duration, startedAt, samplePeriod);
+    }
 }

measure/src/test/java/net/laprun/sustainability/power/measure/CursorTest.java

@@ -0,0 +1,54 @@
+package net.laprun.sustainability.power.measure;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.time.Duration;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+class CursorTest {
+
+    @ParameterizedTest
+    @ValueSource(longs = { -1, 0, 100, 98, 105 })
+    void cursorOverSimple(long periodHint) {
+        final var timestamps = new long[] { 100, 200, 300, 400, 500, 600, 700, 800, 900 };
+
+        final var cursor = Cursor.cursorOver(timestamps, 225, Duration.ofMillis(540 - 225), 0,
+                periodHint);
+
+        assertEquals(2, cursor.startIndex());
+        assertEquals(5, cursor.endIndex());
+        assertEquals(0.75, cursor.firstMeasureRatio(), 0.0001);
+        assertEquals(0.4, cursor.lastMeasureRatio(), 0.0001);
+
+        final var measures = new double[] { 100, 200, 300, 400, 500, 600, 700, 800, 900 };
+        assertEquals(300 * 0.75 + 400 + 500 + 0.4 * 600, cursor.sum(measures), 0.0001);
+        final double[] view = cursor.viewOf(measures);
+        assertEquals(4, view.length);
+        assertEquals(300 * 0.75, view[0], 0.0001);
+        assertEquals(400, view[1], 0.0001);
+        assertEquals(500, view[2], 0.0001);
+        assertEquals(600 * 0.4, view[3], 0.0001);
+    }
+
+    @Test
+    void cursorOverOneMeasure() {
+        final var timestamps = new long[] { 100, 200, 300, 400, 500, 600, 700, 800, 900 };
+
+        final var cursor = Cursor.cursorOver(timestamps, 1, Duration.ofMillis(10), 0,
+                100);
+
+        assertEquals(0, cursor.startIndex());
+        assertEquals(0, cursor.endIndex());
+        assertEquals(0.1, cursor.firstMeasureRatio(), 0.0001);
+        assertEquals(-1, cursor.lastMeasureRatio(), 0.0001);
+
+        final var measures = new double[] { 100, 200, 300, 400, 500, 600, 700, 800, 900 };
+        assertEquals(100 * 0.1, cursor.sum(measures), 0.0001);
+        final double[] view = cursor.viewOf(measures);
+        assertEquals(1, view.length);
+        assertEquals(100 * 0.1, view[0], 0.0001);
+    }
+}