#558 WWZ: harden threading/cancellation and add MT tests

Address review follow-ups by making WWZ cancellation semantics explicit (including cleared results), null-guarding plugin interrupt and thread-count extraction, keeping dialog defaults synced to recommended threads, and updating stale thread-count docs. Add multi-thread consistency, cancellation, and scaling tests, and rerun WWZ UT/benchmark coverage.

Acknowledgement: I implemented all of this with assistance from Cursor AI.
Made-with: Cursor

Author: dbenn

src/org/aavso/tools/vstar/plugin/period/impl/WeightedWaveletZTransformPluginBase.java

@@ -70,8 +70,12 @@ protected List<ITextComponent<?>> createNumberFields(DoubleField... moreFields)
 				currTimeDivisions);
 		fields.add(timeDivisionsField);
 
+		int recommendedThreads = WeightedWaveletZTransform.getRecommendedThreadCount();
+		if (currThreadCount == null || currThreadCount > recommendedThreads) {
+			currThreadCount = recommendedThreads;
+		}
 		threadCountField = new IntegerField(LocaleProps.get("WWZ_PARAMETERS_THREADS"),
-				1, Math.max(1, Runtime.getRuntime().availableProcessors()), currThreadCount);
+				1, recommendedThreads, currThreadCount);
 		fields.add(threadCountField);
 
 		return fields;
@@ -100,6 +104,8 @@ public void reset() {
 	 */
 	@Override
 	public void interrupt() {
-		wwt.interrupt();
+		if (wwt != null) {
+			wwt.interrupt();
+		}
 	}
 }

src/org/aavso/tools/vstar/plugin/period/impl/WeightedWaveletZTransformWithFrequencyRangePlugin.java

@@ -88,7 +88,11 @@ public void executeAlgorithm(List<ValidObservation> obs)
 			currDeltaFreq = deltaFreq = deltaFreqField.getValue();
 			currDecay = decay = decayField.getValue();
 			currTimeDivisions = timeDivisions = timeDivisionsField.getValue();
-			currThreadCount = threadCount = threadCountField.getValue();
+			Integer threadCountValue = threadCountField.getValue();
+			if (threadCountValue == null) {
+				threadCountValue = WeightedWaveletZTransform.getRecommendedThreadCount();
+			}
+			currThreadCount = threadCount = threadCountValue;
 
 			// TODO: ask about number of frequencies > 1000 via dialog?
 
@@ -97,6 +101,10 @@ public void executeAlgorithm(List<ValidObservation> obs)
 			wwt.make_freqs_from_freq_range(Math.min(minFreq, maxFreq), Math
 					.max(minFreq, maxFreq), deltaFreq);
 			wwt.execute();
+			if (wwt.isCancelled()) {
+				throw new CancellationException("WWZ "
+						+ LocaleProps.get("CANCELLED"));
+			}
 		} else {
 			throw new CancellationException("WWZ "
 					+ LocaleProps.get("CANCELLED"));

src/org/aavso/tools/vstar/plugin/period/impl/WeightedWaveletZTransformWithPeriodRangePlugin.java

@@ -85,7 +85,11 @@ public void executeAlgorithm(List<ValidObservation> obs)
 			currDeltaPeriod = deltaPeriod = deltaPeriodField.getValue();
 			currDecay = decay = decayField.getValue();
 			currTimeDivisions = timeDivisions = timeDivisionsField.getValue();
-			currThreadCount = threadCount = threadCountField.getValue();
+			Integer threadCountValue = threadCountField.getValue();
+			if (threadCountValue == null) {
+				threadCountValue = WeightedWaveletZTransform.getRecommendedThreadCount();
+			}
+			currThreadCount = threadCount = threadCountValue;
 
 			// TODO: ask about number of periods > 1000 via dialog?
 
@@ -94,6 +98,10 @@ public void executeAlgorithm(List<ValidObservation> obs)
 			wwt.make_freqs_from_period_range(Math.min(minPeriod, maxPeriod),
 					Math.max(minPeriod, maxPeriod), deltaPeriod);
 			wwt.execute();
+			if (wwt.isCancelled()) {
+				throw new CancellationException("WWZ "
+						+ LocaleProps.get("CANCELLED"));
+			}
 		} else {
 			throw new CancellationException("WWZ "
 					+ LocaleProps.get("CANCELLED"));

src/org/aavso/tools/vstar/util/period/wwz/WeightedWaveletZTransform.java

@@ -95,6 +95,7 @@ public class WeightedWaveletZTransform implements IAlgorithm {
 	private double tau[];
 
 	private volatile boolean interrupted;
+	private volatile boolean cancelled;
 	private int threadCount;
 
 	/**
@@ -132,6 +133,7 @@ public WeightedWaveletZTransform(List<ValidObservation> observations,
 		threadCount = MAX_AVAILABLE_THREADS;
 
 		interrupted = false;
+		cancelled = false;
 	}
 
 	/**
@@ -161,11 +163,18 @@ public List<ValidObservation> getObs() {
 	@Override
 	public void execute() throws AlgorithmError {
 		interrupted = false;
+		cancelled = false;
 		try {
 			wwt();
 			computeMinAndMaxValues();
 		} catch (InterruptedException e) {
-			// Do nothing; just return.
+			cancelled = true;
+			stats = new ArrayList<WWZStatistic>();
+			maximalStats = new ArrayList<WWZStatistic>();
+		} catch (RuntimeException e) {
+			stats = new ArrayList<WWZStatistic>();
+			maximalStats = new ArrayList<WWZStatistic>();
+			throw new AlgorithmError(e.getMessage() != null ? e.getMessage() : "WWZ runtime failure");
 		}
 	}
 
@@ -176,8 +185,9 @@ public void interrupt() {
 	/**
 	 * Number of threads (cores) to use for WWZ execution.
 	 * <p>
-	 * Currently this is a configuration hook for future/optional parallel execution
-	 * and UI integration. Values are clamped to [1, maxAvailableThreads].
+	 * This controls threaded WWZ execution. Values are clamped to
+	 * [1, maxAvailableThreads]. A workload heuristic may still run effectively
+	 * single-threaded for small jobs.
 	 * </p>
 	 *
 	 * @param threadCount desired number of threads/cores
@@ -199,6 +209,13 @@ public int getThreadCount() {
 		return threadCount;
 	}
 
+	/**
+	 * @return true if the last execute() call was cancelled/interrupted.
+	 */
+	public boolean isCancelled() {
+		return cancelled;
+	}
+
 	/**
 	 * @return maximum available threads (cores) detected at runtime.
 	 */

test/org/aavso/tools/vstar/util/period/wwz/WWZCancellationTest.java

@@ -0,0 +1,70 @@
+/**
+ * VStar: a statistical analysis tool for variable star data.
+ * Copyright (C) 2010  AAVSO (http://www.aavso.org/)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ */
+package org.aavso.tools.vstar.util.period.wwz;
+
+import java.util.List;
+
+import org.aavso.tools.vstar.data.ValidObservation;
+import org.aavso.tools.vstar.util.period.dcdft.DataTestBase;
+
+/**
+ * Verify cancellation semantics for threaded WWZ execution.
+ */
+public class WWZCancellationTest extends DataTestBase {
+
+	private static final double[][] LARGE_DATA = buildLargeData();
+
+	public WWZCancellationTest() {
+		super("WWZ cancellation test", LARGE_DATA);
+	}
+
+	public void testInterruptMarksCancelledAndClearsResults() throws Exception {
+		final WeightedWaveletZTransform wwt = new WeightedWaveletZTransform(obs, 0.0005, 50.0);
+		wwt.setThreadCount(WeightedWaveletZTransform.getRecommendedThreadCount());
+		wwt.make_freqs_from_period_range(20.0, 300.0, 0.5);
+
+		Thread runThread = new Thread(new Runnable() {
+			@Override
+			public void run() {
+				try {
+					wwt.execute();
+				} catch (Exception e) {
+					// execute handles cancellation internally; no exception expected here
+				}
+			}
+		});
+		runThread.start();
+		Thread.sleep(20);
+		wwt.interrupt();
+		runThread.join(10000);
+
+		assertTrue("WWZ execution thread should terminate after interrupt", !runThread.isAlive());
+		assertTrue("WWZ should report cancelled state", wwt.isCancelled());
+		assertEquals("Cancelled run should not expose partial stats", 0, wwt.getStats().size());
+		assertEquals("Cancelled run should not expose partial maximal stats", 0, wwt.getMaximalStats().size());
+	}
+
+	private static double[][] buildLargeData() {
+		double[][] base = TUmi2420000To2425000Data.data;
+		int repeats = 8;
+		double[][] out = new double[base.length * repeats][2];
+		double span = 5000.0;
+		int p = 0;
+		for (int r = 0; r < repeats; r++) {
+			for (int i = 0; i < base.length; i++) {
+				out[p][0] = base[i][0] + r * span;
+				out[p][1] = base[i][1];
+				p++;
+			}
+		}
+		return out;
+	}
+}
+

test/org/aavso/tools/vstar/util/period/wwz/WWZThreadScalingBenchmarkTest.java

@@ -0,0 +1,74 @@
+/**
+ * VStar: a statistical analysis tool for variable star data.
+ * Copyright (C) 2010  AAVSO (http://www.aavso.org/)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ */
+package org.aavso.tools.vstar.util.period.wwz;
+
+import java.util.List;
+
+import org.aavso.tools.vstar.util.period.dcdft.DataTestBase;
+
+/**
+ * Benchmark WWZ runtime scaling across thread counts.
+ */
+public class WWZThreadScalingBenchmarkTest extends DataTestBase {
+
+	private static final double[][] LARGE_DATA = buildLargeData();
+
+	public WWZThreadScalingBenchmarkTest() {
+		super("WWZ thread scaling benchmark", LARGE_DATA);
+	}
+
+	public void testThreadScalingBenchmark() throws Exception {
+		int[] threadCounts = new int[] { 1, 2, 4, 8, WeightedWaveletZTransform.getRecommendedThreadCount() };
+		double minPeriod = 20.0;
+		double maxPeriod = 300.0;
+		double deltaPeriod = 0.5;
+		double decay = 0.0005;
+		double timeDivisions = 50.0;
+		int iterations = 3;
+
+		double baselineMs = -1.0;
+		System.out.println("WWZ thread scaling benchmark (synthetic >1000 obs, " + iterations + " runs each):");
+		for (int tc : threadCounts) {
+			long t0 = System.nanoTime();
+			for (int i = 0; i < iterations; i++) {
+				WeightedWaveletZTransform wwt = new WeightedWaveletZTransform(obs, decay, timeDivisions);
+				wwt.setThreadCount(tc);
+				wwt.make_freqs_from_period_range(minPeriod, maxPeriod, deltaPeriod);
+				wwt.execute();
+				List<WWZStatistic> stats = wwt.getStats();
+				assertTrue(stats.size() > 0);
+			}
+			double totalMs = (System.nanoTime() - t0) / 1_000_000.0;
+			if (baselineMs < 0.0) {
+				baselineMs = totalMs;
+			}
+			double speedup = baselineMs / totalMs;
+			System.out.println("  threads=" + tc + " total=" + String.format("%.2f", totalMs) + " ms speedup="
+					+ String.format("%.2fx", speedup));
+		}
+	}
+
+	private static double[][] buildLargeData() {
+		double[][] base = TUmi2420000To2425000Data.data;
+		int repeats = 6;
+		double[][] out = new double[base.length * repeats][2];
+		double span = 5000.0;
+		int p = 0;
+		for (int r = 0; r < repeats; r++) {
+			for (int i = 0; i < base.length; i++) {
+				out[p][0] = base[i][0] + r * span;
+				out[p][1] = base[i][1];
+				p++;
+			}
+		}
+		return out;
+	}
+}
+

test/org/aavso/tools/vstar/util/period/wwz/WWZThreadedConsistencyTest.java

@@ -0,0 +1,85 @@
+/**
+ * VStar: a statistical analysis tool for variable star data.
+ * Copyright (C) 2010  AAVSO (http://www.aavso.org/)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ */
+package org.aavso.tools.vstar.util.period.wwz;
+
+import java.util.List;
+
+import org.aavso.tools.vstar.util.period.dcdft.DataTestBase;
+
+/**
+ * Verify that multi-threaded WWZ execution matches single-threaded results.
+ */
+public class WWZThreadedConsistencyTest extends DataTestBase {
+
+	private static final double[][] LARGE_DATA = buildLargeData();
+
+	public WWZThreadedConsistencyTest() {
+		super("WWZ threaded consistency test", LARGE_DATA);
+	}
+
+	public void testThreadedMatchesSingleThread() throws Exception {
+		double minPeriod = 20.0;
+		double maxPeriod = 300.0;
+		double deltaPeriod = 0.5;
+		double decay = 0.0005;
+		double timeDivisions = 50.0;
+
+		WeightedWaveletZTransform oneThread = new WeightedWaveletZTransform(obs, decay, timeDivisions);
+		oneThread.setThreadCount(1);
+		oneThread.make_freqs_from_period_range(minPeriod, maxPeriod, deltaPeriod);
+		oneThread.execute();
+
+		WeightedWaveletZTransform manyThreads = new WeightedWaveletZTransform(obs, decay, timeDivisions);
+		manyThreads.setThreadCount(WeightedWaveletZTransform.getRecommendedThreadCount());
+		manyThreads.make_freqs_from_period_range(minPeriod, maxPeriod, deltaPeriod);
+		manyThreads.execute();
+
+		List<WWZStatistic> a = oneThread.getStats();
+		List<WWZStatistic> b = manyThreads.getStats();
+		assertEquals(a.size(), b.size());
+		for (int i = 0; i < a.size(); i++) {
+			assertEquals(a.get(i).getTau(), b.get(i).getTau(), 1e-9);
+			assertEquals(a.get(i).getFrequency(), b.get(i).getFrequency(), 1e-9);
+			assertEquals(a.get(i).getWwz(), b.get(i).getWwz(), 1e-9);
+			assertEquals(a.get(i).getSemiAmplitude(), b.get(i).getSemiAmplitude(), 1e-9);
+			assertEquals(a.get(i).getMave(), b.get(i).getMave(), 1e-9);
+			assertEquals(a.get(i).getNeff(), b.get(i).getNeff(), 1e-9);
+		}
+
+		List<WWZStatistic> ma = oneThread.getMaximalStats();
+		List<WWZStatistic> mb = manyThreads.getMaximalStats();
+		assertEquals(ma.size(), mb.size());
+		for (int i = 0; i < ma.size(); i++) {
+			assertEquals(ma.get(i).getTau(), mb.get(i).getTau(), 1e-9);
+			assertEquals(ma.get(i).getFrequency(), mb.get(i).getFrequency(), 1e-9);
+			assertEquals(ma.get(i).getWwz(), mb.get(i).getWwz(), 1e-9);
+			assertEquals(ma.get(i).getSemiAmplitude(), mb.get(i).getSemiAmplitude(), 1e-9);
+			assertEquals(ma.get(i).getMave(), mb.get(i).getMave(), 1e-9);
+			assertEquals(ma.get(i).getNeff(), mb.get(i).getNeff(), 1e-9);
+		}
+	}
+
+	private static double[][] buildLargeData() {
+		double[][] base = TUmi2420000To2425000Data.data;
+		int repeats = 6; // >1000 points to exercise threaded path heuristics
+		double[][] out = new double[base.length * repeats][2];
+		double span = 5000.0;
+		int p = 0;
+		for (int r = 0; r < repeats; r++) {
+			for (int i = 0; i < base.length; i++) {
+				out[p][0] = base[i][0] + r * span;
+				out[p][1] = base[i][1];
+				p++;
+			}
+		}
+		return out;
+	}
+}
+