Add auto-bucket sizing logic for interval histograms

- Modified `getIntervalHistogram` to support auto-calculating bucket sizes when `bucketSizeNs` is set to `-1` or omitted.
- Implemented `autoBucketSizeNs` to calculate bucket sizes approximating 64 buckets, rounded to human-readable values (1/2/5 × 10^k).
- Updated validation logic to allow `-1` as a valid input for bucket size.
- Enhanced tests to cover auto-sizing and snapping behavior.

Author: Christian

src/main/java/com/ammann/entropy/resource/EventsResource.java

@@ -428,8 +428,9 @@ public Response getEventRate(
             description =
                     "Returns a histogram of frequencies for intervals between decay events."
                         + " Requires at least 100 intervals for meaningful statistical analysis."
-                        + " Default bucket size (100ns) is optimized for radioactive decay"
-                        + " intervals in the 2-10µs range.")
+                        + " When bucketSizeNs is omitted (or set to -1) the server auto-selects"
+                        + " a bucket size that targets approximately 64 buckets across the"
+                        + " observed interval range, rounded to a 1/2/5 × 10^k value.")
     @APIResponses({
         @APIResponse(
                 responseCode = "200",
@@ -442,19 +443,21 @@ public Response getIntervalHistogram(
             @Parameter(description = "Start of time window (ISO-8601)") @QueryParam("from")
                     String from,
             @Parameter(description = "End of time window (ISO-8601)") @QueryParam("to") String to,
-            @Parameter(description = "Bucket size in nanoseconds (must be positive, default: 100)")
+            @Parameter(
+                            description =
+                                    "Bucket size in nanoseconds. Pass -1 (or omit) for"
+                                            + " auto-sizing based on the observed interval range.")
                     @QueryParam("bucketSizeNs")
-                    @DefaultValue("100")
+                    @DefaultValue("-1")
                     int bucketSizeNs) {
 
         LOG.debugf(
                 "Interval histogram request: from=%s, to=%s, bucketSize=%d",
                 from, to, bucketSizeNs);
 
-        // Validate bucket size to prevent division by zero and negative values
-        if (bucketSizeNs <= 0) {
+        if (bucketSizeNs != -1 && bucketSizeNs <= 0) {
             throw ValidationException.invalidParameter(
-                    "bucketSizeNs", bucketSizeNs, "positive integer");
+                    "bucketSizeNs", bucketSizeNs, "positive integer or -1 for auto");
         }
 
         TimeWindow window = parseTimeWindow(from, to);
@@ -464,11 +467,19 @@ public Response getIntervalHistogram(
             throw ValidationException.insufficientData("intervals", 100, intervals.size());
         }
 
+        int effectiveBucketSizeNs = bucketSizeNs;
+        if (effectiveBucketSizeNs == -1) {
+            effectiveBucketSizeNs = autoBucketSizeNs(intervals);
+            LOG.debugf(
+                    "Auto-selected bucketSizeNs=%d for %d intervals",
+                    effectiveBucketSizeNs, intervals.size());
+        }
+
         Map<Long, Integer> histogram =
-                entropyStatisticsService.createHistogram(intervals, bucketSizeNs);
+                entropyStatisticsService.createHistogram(intervals, effectiveBucketSizeNs);
         IntervalHistogramDTO response =
                 IntervalHistogramDTO.from(
-                        histogram, intervals, bucketSizeNs, window.start, window.end);
+                        histogram, intervals, effectiveBucketSizeNs, window.start, window.end);
 
         LOG.infof(
                 "Histogram: %d buckets from %d intervals (min=%dns, max=%dns)",
@@ -551,4 +562,45 @@ public Response getFilterOptions() {
 
         return Response.ok(new EventFilterOptionsDTO(batchIds, channels)).build();
     }
+
+    /**
+     * Picks a bucket size that yields roughly {@link #AUTO_HISTOGRAM_TARGET_BUCKETS} buckets
+     * across the observed interval range, snapped to a 1/2/5 × 10^k mantissa so bucket edges
+     * are human-readable. Floors at {@link #AUTO_HISTOGRAM_MIN_BUCKET_NS} so fine-grained
+     * entropy sources do not collapse into a single bucket.
+     */
+    static int autoBucketSizeNs(List<Long> intervals) {
+        long min = Long.MAX_VALUE;
+        long max = Long.MIN_VALUE;
+        for (long v : intervals) {
+            if (v < min) min = v;
+            if (v > max) max = v;
+        }
+        long range = Math.max(1L, max - min);
+        double ideal = (double) range / AUTO_HISTOGRAM_TARGET_BUCKETS;
+        if (ideal < AUTO_HISTOGRAM_MIN_BUCKET_NS) {
+            return AUTO_HISTOGRAM_MIN_BUCKET_NS;
+        }
+
+        // Snap ``ideal`` up to the next value in the 1/2/5 × 10^k series.
+        double exponent = Math.floor(Math.log10(ideal));
+        double pow = Math.pow(10.0, exponent);
+        double mantissa = ideal / pow;
+        double snapped;
+        if (mantissa <= 1.0) {
+            snapped = 1.0 * pow;
+        } else if (mantissa <= 2.0) {
+            snapped = 2.0 * pow;
+        } else if (mantissa <= 5.0) {
+            snapped = 5.0 * pow;
+        } else {
+            snapped = 10.0 * pow;
+        }
+
+        long bucket = Math.max(AUTO_HISTOGRAM_MIN_BUCKET_NS, (long) snapped);
+        return (int) Math.min(bucket, Integer.MAX_VALUE);
+    }
+
+    private static final int AUTO_HISTOGRAM_TARGET_BUCKETS = 64;
+    private static final int AUTO_HISTOGRAM_MIN_BUCKET_NS = 100;
 }

src/test/java/com/ammann/entropy/resource/EventsResourceTest.java

@@ -331,10 +331,42 @@ void getIntervalHistogramUsesDefaultBucketSize() {
                         start.toString(), start.plusSeconds(10).toString(), 100);
         IntervalHistogramDTO dto = (IntervalHistogramDTO) response.getEntity();
 
-        // Verify default bucket size is used when not specified
+        // Verify explicit bucket size is honored when passed.
         assertThat(dto.bucketSizeNs()).isEqualTo(100);
     }
 
+    @Test
+    @TestTransaction
+    void getIntervalHistogramAutoSizesWhenBucketSizeIsMinusOne() {
+        EntropyData.deleteAll();
+        EventsResource resource = buildResource();
+
+        // TestDataFactory builds events with a fixed 1500 ns stride, so all intervals
+        // collapse to a single value (range=0). The auto-sizer must degrade gracefully
+        // and return the minimum floor of 100 ns rather than throwing or returning 0.
+        Instant start = Instant.parse("2024-01-01T00:00:00Z");
+        List<EntropyData> events = TestDataFactory.buildSequentialEvents(150, 1_000L, start);
+        EntropyData.persist(events);
+
+        var response =
+                resource.getIntervalHistogram(
+                        start.toString(), start.plusSeconds(10).toString(), -1);
+        IntervalHistogramDTO dto = (IntervalHistogramDTO) response.getEntity();
+
+        assertThat(dto.bucketSizeNs()).isEqualTo(100);
+        assertThat(dto.totalIntervals()).isEqualTo(149L);
+    }
+
+    @Test
+    void autoBucketSizeNsSnapsToNiceValues() {
+        // Range 6_400_000 ns → ideal ~100_000 → snaps to 100_000
+        assertThat(EventsResource.autoBucketSizeNs(List.of(0L, 6_400_000L))).isEqualTo(100_000);
+        // Range 12_800 ns → ideal 200 → snaps to 200
+        assertThat(EventsResource.autoBucketSizeNs(List.of(0L, 12_800L))).isEqualTo(200);
+        // Tiny range clamps to minimum bucket (100 ns)
+        assertThat(EventsResource.autoBucketSizeNs(List.of(0L, 10L))).isEqualTo(100);
+    }
+
     @Test
     @TestTransaction
     void getIntervalHistogramCustomBucketSize() {