command = new ArrayList<>();
command.add(javaExecutable);
command.add("-Xms" + heap);
command.add("-Xmx" + heap);
command.add("-cp");
command.add(classpath);
command.add(BacktestPerformanceTuningHarness.class.getName());
command.addAll(childArgs);
ProcessBuilder builder = new ProcessBuilder(command);
builder.redirectErrorStream(true);
Process process = builder.start();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
String line;
while ((line = reader.readLine()) != null) {
LOG.info(line);
}
}
int exitCode = process.waitFor();
if (exitCode != 0) {
throw new IllegalStateException("Child JVM exited with code=" + exitCode + " for heap=" + heap);
}
}
}
private static String javaExecutablePath() {
String javaHome = System.getProperty("java.home");
String executable = isWindows() ? "java.exe" : "java";
return Path.of(javaHome, "bin", executable).toString();
}
private static boolean isWindows() {
String osName = System.getProperty("os.name");
return osName != null && osName.toLowerCase(Locale.ROOT).contains("win");
}
private static BarSeries loadSeries(String jsonOhlcResourceFile) {
try (InputStream resourceStream = BacktestPerformanceTuningHarness.class.getClassLoader()
.getResourceAsStream(jsonOhlcResourceFile)) {
if (resourceStream == null) {
LOG.error("Resource not found: {}", jsonOhlcResourceFile);
return null;
}
return JsonFileBarSeriesDataSource.DEFAULT_INSTANCE.loadSeries(resourceStream);
} catch (IOException ex) {
LOG.error("IOException while loading resource: {} - {}", jsonOhlcResourceFile, ex.getMessage());
return null;
}
}
/**
* Determines if performance has degraded non-linearly between two runs.
*
* Non-linear behavior is detected when either:
*
* - GC overhead exceeds the threshold (default: 25% of total runtime)
* - Normalized slowdown ratio exceeds the threshold (default: 1.25x)
*
*
* The normalized slowdown ratio is calculated as:
*
*
{@code
* (runtimeRatio / workRatio)
* }
*
* where runtimeRatio is the ratio of runtimes and workRatio is the ratio of
* work units (strategies × bars). A value greater than 1.0 indicates that
* runtime increased faster than work, suggesting non-linear scaling.
*
* This method is used during tuning to identify the point where increasing
* strategy count or bar count causes performance to degrade beyond expected
* linear scaling.
*
* @param previous The previous run result (baseline)
* @param current The current run result (to compare against baseline)
* @param thresholds The thresholds for detecting non-linear behavior
* @return true if non-linear behavior is detected, false otherwise
* @throws NullPointerException If any parameter is null
*/
static boolean isNonLinear(RunResult previous, RunResult current, Thresholds thresholds) {
Objects.requireNonNull(previous, "previous must not be null");
Objects.requireNonNull(current, "current must not be null");
Objects.requireNonNull(thresholds, "thresholds must not be null");
if (previous.workUnits() <= 0 || current.workUnits() <= 0) {
return false;
}
if (previous.runtimeStats().overallRuntime().isZero() || current.runtimeStats().overallRuntime().isZero()) {
return false;
}
double workRatio = current.workUnits() / (double) previous.workUnits();
double runtimeRatio = current.runtimeStats().overallRuntime().toNanos()
/ (double) previous.runtimeStats().overallRuntime().toNanos();
double normalizedSlowdown = runtimeRatio / workRatio;
double gcOverhead = current.gcOverhead();
boolean gcNonLinear = gcOverhead >= thresholds.gcOverheadThreshold();
boolean slowdownNonLinear = normalizedSlowdown >= thresholds.slowdownRatioThreshold();
if (gcNonLinear || slowdownNonLinear) {
LOG.info("Non-linear check: gcOverhead={} (threshold={}), slowdown={} (threshold={})",
formatPercent(gcOverhead), formatPercent(thresholds.gcOverheadThreshold()),
String.format(Locale.ROOT, "%.3f", normalizedSlowdown),
String.format(Locale.ROOT, "%.3f", thresholds.slowdownRatioThreshold()));
return true;
}
return false;
}
private static String formatPercent(double value) {
return String.format(Locale.ROOT, "%.2f%%", value * 100d);
}
private static long elapsedMillis(long startedNanos) {
return TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startedNanos);
}
private static void writeJson(Path path, JsonObject object) throws IOException {
Files.createDirectories(path.getParent());
Files.writeString(path, PRETTY_GSON.toJson(object) + System.lineSeparator(), StandardCharsets.UTF_8);
}
static String shortSha256(String value) {
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(value.getBytes(StandardCharsets.UTF_8));
StringBuilder builder = new StringBuilder();
for (int i = 0; i < 8; i++) {
builder.append(String.format(Locale.ROOT, "%02x", hash[i]));
}
return builder.toString();
} catch (NoSuchAlgorithmException ex) {
throw new IllegalStateException("SHA-256 is unavailable", ex);
}
}
/**
* Slices a bar series to contain only the last N bars.
*
* If barCount is 0, negative, or greater than or equal to the available bars,
* the original series is returned unchanged. Otherwise, returns a sub-series
* containing the last barCount bars.
*
* This is useful for testing performance with different dataset sizes without
* loading multiple files.
*
* @param series The bar series to slice
* @param barCount The number of bars to keep (0 or negative = keep all)
* @return A sub-series containing the last barCount bars, or the original
* series if no slicing is needed
* @throws NullPointerException If series is null
*/
static BarSeries sliceToLastBars(BarSeries series, int barCount) {
Objects.requireNonNull(series, "series must not be null");
if (barCount <= 0) {
return series;
}
int availableBars = series.getBarCount();
if (barCount >= availableBars) {
return series;
}
int endExclusive = series.getEndIndex() + 1;
int startIndex = Math.max(0, endExclusive - barCount);
return series.getSubSeries(startIndex, endExclusive);
}
/**
* Applies a maximum bar count hint to a bar series for indicator caching
* optimization.
*
* The maximum bar count hint controls the size of the indicator cache window.
* When set, indicators will only cache values for the most recent N bars,
* reducing memory usage for large datasets.
*
* If maximumBarCountHint is 0 or negative, the original series is returned
* unchanged. If it matches the series' current maximum bar count, the original
* series is returned. Otherwise, returns a wrapper that overrides
* {@link BarSeries#getMaximumBarCount()}.
*
* This is useful for testing the impact of indicator caching on performance and
* memory usage.
*
* @param series The bar series to wrap
* @param maximumBarCountHint The maximum bar count hint (0 = disabled, use
* series default)
* @return A series with the maximum bar count hint applied, or the original
* series if no change is needed
* @throws NullPointerException If series is null
*/
static BarSeries applyMaximumBarCountHint(BarSeries series, int maximumBarCountHint) {
Objects.requireNonNull(series, "series must not be null");
if (maximumBarCountHint <= 0) {
return series;
}
if (maximumBarCountHint == series.getMaximumBarCount()) {
return series;
}
return new MaxBarCountHintSeries(series, maximumBarCountHint);
}
/**
* Creates a variety of strategies using NetMomentumIndicator with different
* parameter combinations for performance testing.
*
* Generates strategies by systematically varying:
*
* - RSI bar count: 7 to 49 (increment: 7)
* - Momentum timeframe: 100 to 400 (increment: 100)
* - Oversold threshold: -2000 to 0 (increment: 250)
* - Overbought threshold: 0 to 1500 (increment: 250)
* - Decay factor: 0.9 to 1.0 (increment: 0.02)
*
*
* This generates approximately 10,416 unique strategy combinations. When fewer
* strategies are requested, the method samples from this grid. When more are
* requested, it repeats the grid with different repetition markers.
*
* Strategies use:
*
* - Entry rule: CrossedUpIndicatorRule when NetMomentumIndicator crosses
* above oversold threshold
* - Exit rule: CrossedDownIndicatorRule when NetMomentumIndicator crosses
* below overbought threshold
*
*
* Strategies that share the same RSI, Net Momentum timeframe, and decay factor
* reuse the same indicator graph. The underlying cached indicators are
* thread-safe, and sharing them keeps this benchmark focused on rule thresholds
* instead of repeatedly recomputing identical momentum series.
*
* @param series The bar series to use for indicator
* calculations
* @param requestedStrategyCount The number of strategies to create. Use -1 for
* full grid, or a positive number to sample that
* many strategies
* @return A list of strategies to test
* @throws NullPointerException If series is null
* @throws IllegalArgumentException If requestedStrategyCount is zero
*/
static List createStrategies(BarSeries series, int requestedStrategyCount) {
Objects.requireNonNull(series, "series cannot be null");
int effectiveTarget;
if (requestedStrategyCount < 0) {
effectiveTarget = Integer.MAX_VALUE;
} else if (requestedStrategyCount == 0) {
throw new IllegalArgumentException("requestedStrategyCount must not be zero");
} else {
effectiveTarget = requestedStrategyCount;
}
List strategies = new ArrayList<>(requestedStrategyCount > 0 ? requestedStrategyCount : 10_416);
ClosePriceIndicator closePriceIndicator = new ClosePriceIndicator(series);
Map rsiIndicators = new LinkedHashMap<>();
Map netMomentumIndicators = new LinkedHashMap<>();
int created = 0;
int repetition = 0;
while (created < effectiveTarget) {
boolean fullGrid = requestedStrategyCount < 0;
boolean addedAny = false;
for (int rsiBarCount = RSI_BARCOUNT_MIN; rsiBarCount <= RSI_BARCOUNT_MAX; rsiBarCount += RSI_BARCOUNT_INCREMENT) {
for (int timeFrame = MOMENTUM_TIMEFRAME_MIN; timeFrame <= MOMENTUM_TIMEFRAME_MAX; timeFrame += MOMENTUM_TIMEFRAME_INCREMENT) {
for (int oversoldThreshold = OVERSOLD_THRESHOLD_MIN; oversoldThreshold <= OVERSOLD_THRESHOLD_MAX; oversoldThreshold += OVERSOLD_THRESHOLD_INCREMENT) {
for (int overboughtThreshold = OVERBOUGHT_THRESHOLD_MIN; overboughtThreshold <= OVERBOUGHT_THRESHOLD_MAX; overboughtThreshold += OVERBOUGHT_THRESHOLD_INCREMENT) {
if (oversoldThreshold >= overboughtThreshold) {
continue;
}
for (double decayFactor = DECAY_FACTOR_MIN; decayFactor <= DECAY_FACTOR_MAX; decayFactor += DECAY_FACTOR_INCREMENT) {
try {
int currentRsiBarCount = rsiBarCount;
int currentTimeFrame = timeFrame;
double currentDecayFactor = decayFactor;
NetMomentumIndicator netMomentumIndicator = netMomentumIndicators
.computeIfAbsent(
netMomentumKey(currentRsiBarCount, currentTimeFrame,
currentDecayFactor),
ignored -> NetMomentumIndicator
.forRsiWithDecay(
rsiIndicators.computeIfAbsent(currentRsiBarCount,
key -> new RSIIndicator(closePriceIndicator,
key)),
currentTimeFrame, currentDecayFactor));
Strategy strategy = createStrategy(netMomentumIndicator, currentRsiBarCount,
currentTimeFrame, oversoldThreshold, overboughtThreshold,
currentDecayFactor, repetition);
strategies.add(strategy);
created++;
addedAny = true;
if (created >= effectiveTarget) {
return strategies;
}
} catch (Exception e) {
LOG.debug(
"Skipping invalid strategy combination: rsiBarCount={}, timeFrame={}, oversoldThreshold={}, overboughtThreshold={}, decayFactor={}: {}",
rsiBarCount, timeFrame, oversoldThreshold, overboughtThreshold, decayFactor,
e.getMessage());
}
}
}
}
}
}
if (fullGrid) {
break;
}
if (!addedAny) {
break;
}
repetition++;
}
return strategies;
}
private static String netMomentumKey(int rsiBarCount, int timeFrame, double decayFactor) {
return rsiBarCount + "|" + timeFrame + "|" + String.format(Locale.ROOT, "%.8f", decayFactor);
}
/**
* Creates a single strategy using NetMomentumIndicator with the specified
* parameters.
*
* The strategy uses:
*
* - RSI indicator with the specified bar count
* - NetMomentumIndicator wrapping the RSI with the specified timeframe and
* decay factor
* - Entry rule: Buy when NetMomentumIndicator crosses above the oversold
* threshold
* - Exit rule: Sell when NetMomentumIndicator crosses below the overbought
* threshold
*
*
* The repetition parameter is used to create multiple strategies with the same
* parameters when more strategies are requested than the grid can provide. It's
* included in the strategy name for identification.
*
* @param series The bar series to use for indicator calculations
* @param rsiBarCount The number of bars to use for RSI calculation
* (must be positive)
* @param timeFrame The timeframe for NetMomentumIndicator (must be
* positive)
* @param oversoldThreshold The oversold threshold for entry signals
* @param overboughtThreshold The overbought threshold for exit signals
* @param decayFactor The decay factor for NetMomentumIndicator
* (typically 0.9 to 1.0)
* @param repetition The repetition number (0 for first occurrence,
* incremented for repeats)
* @return A new strategy with the specified parameters
* @throws NullPointerException If series is null
* @throws IllegalArgumentException If rsiBarCount or timeFrame is not positive
*/
static Strategy createStrategy(BarSeries series, int rsiBarCount, int timeFrame, int oversoldThreshold,
int overboughtThreshold, double decayFactor, int repetition) {
Objects.requireNonNull(series, "series cannot be null");
ClosePriceIndicator closePriceIndicator = new ClosePriceIndicator(series);
RSIIndicator rsiIndicator = new RSIIndicator(closePriceIndicator, rsiBarCount);
NetMomentumIndicator netMomentumIndicator = NetMomentumIndicator.forRsiWithDecay(rsiIndicator, timeFrame,
decayFactor);
return createStrategy(netMomentumIndicator, rsiBarCount, timeFrame, oversoldThreshold, overboughtThreshold,
decayFactor, repetition);
}
private static Strategy createStrategy(NetMomentumIndicator netMomentumIndicator, int rsiBarCount, int timeFrame,
int oversoldThreshold, int overboughtThreshold, double decayFactor, int repetition) {
Objects.requireNonNull(netMomentumIndicator, "netMomentumIndicator cannot be null");
if (rsiBarCount <= 0) {
throw new IllegalArgumentException("rsiBarCount should be positive");
}
if (timeFrame <= 0) {
throw new IllegalArgumentException("timeFrame should be positive");
}
Rule entryRule = new CrossedUpIndicatorRule(netMomentumIndicator, oversoldThreshold);
Rule exitRule = new CrossedDownIndicatorRule(netMomentumIndicator, overboughtThreshold);
String suffix = repetition > 0 ? " (rep=" + repetition + ")" : "";
String strategyName = "Entry Crossed Up: {rsiBarCount=" + rsiBarCount + ", timeFrame=" + timeFrame
+ ", oversoldThreshold=" + oversoldThreshold + "}, Exit Crossed Down: {rsiBarCount=" + rsiBarCount
+ ", timeFrame=" + timeFrame + ", overboughtThreshold=" + overboughtThreshold + ", decayFactor="
+ decayFactor + "}" + suffix;
return new BaseStrategy(strategyName, entryRule, exitRule);
}
private static void logTopStrategies(BacktestExecutionResult result, int topK) {
AnalysisCriterion netProfitCriterion = new NetProfitCriterion();
AnalysisCriterion expectancyCriterion = new ExpectancyCriterion();
List topStrategies = result.getTopStrategies(topK, netProfitCriterion, expectancyCriterion);
LOG.debug("=== Top {} Strategies ===", topStrategies.size());
for (int i = 0; i < topStrategies.size(); i++) {
TradingStatement statement = topStrategies.get(i);
Strategy strategy = statement.getStrategy();
Num netProfit = statement.getCriterionScore(netProfitCriterion)
.orElseGet(() -> netProfitCriterion.calculate(result.barSeries(), statement.getTradingRecord()));
Num expectancy = statement.getCriterionScore(expectancyCriterion)
.orElseGet(() -> expectancyCriterion.calculate(result.barSeries(), statement.getTradingRecord()));
LOG.debug("{}. {}", (i + 1), strategy.getName());
LOG.debug(" Net Profit: {}", netProfit);
LOG.debug(" Expectancy: {}", expectancy);
LOG.debug(" Positions: {}", statement.getTradingRecord().getPositionCount());
}
}
private static void logUsage() {
StringJoiner usage = new StringJoiner(System.lineSeparator());
usage.add("BacktestPerformanceTuningHarness - performance harness");
usage.add("");
usage.add("Run once (default):");
usage.add(" --strategies (default: full grid ~10,416)");
usage.add(" --barCount (default: full series)");
usage.add(" --maxBarCountHint (0 disables; default: 0)");
usage.add(" --executionMode full|topK (default: full)");
usage.add(" --topK (default: 20)");
usage.add(" --progress (enable progress+memory logging)");
usage.add("");
usage.add("Throughput control matrix:");
usage.add(" --throughputControl");
usage.add(" --throughputOutputDir ");
usage.add(" --matrixStrategyCounts (default: 250,500,1000)");
usage.add(" --matrixBarCounts (default: 500,1000; accepts full)");
usage.add(" --matrixMaxBarCountHints (default: 0)");
usage.add(" --parallelism (default: 1)");
usage.add("");
usage.add("Tune in current JVM:");
usage.add(" --tune");
usage.add(" --tuneStrategyStart (default: " + DEFAULT_TUNE_STRATEGY_START + ")");
usage.add(" --tuneStrategyStep (default: " + DEFAULT_TUNE_STRATEGY_STEP + ")");
usage.add(" --tuneStrategyMax (default: " + DEFAULT_TUNE_STRATEGY_MAX + ")");
usage.add(" --tuneBarCounts (default: 500,1000,2000,full)");
usage.add(" --tuneMaxBarCountHints (default: 0,512,1024,2048)");
usage.add(" --nonlinearGcOverhead <0..1> (default: " + DEFAULT_NONLINEAR_GC_OVERHEAD + ")");
usage.add(" --nonlinearSlowdownRatio (default: " + DEFAULT_NONLINEAR_SLOWDOWN_RATIO + ")");
usage.add(" --gcBetweenRuns (default: true)");
usage.add("");
usage.add("Tune across heaps (fork child JVM per heap):");
usage.add(" --tuneHeaps (e.g. 4g,8g,16g)");
LOG.info(System.lineSeparator() + usage);
}
/**
* Formats a byte count as a human-readable string with appropriate units.
*
* Formats bytes using binary units (KiB, MiB, GiB, TiB) with 2 decimal places.
* Examples:
*
* - 1023 bytes → "1023 B"
* - 1024 bytes → "1.00 KiB"
* - 1048576 bytes → "1.00 MiB"
*
*
* @param bytes The number of bytes to format
* @return A formatted string with appropriate unit (B, KiB, MiB, GiB, or TiB)
*/
static String formatBytes(long bytes) {
if (bytes < 1024) {
return bytes + " B";
}
double value = bytes;
String[] units = new String[] { "B", "KiB", "MiB", "GiB", "TiB" };
int unitIndex = 0;
while (value >= 1024d && unitIndex < units.length - 1) {
value /= 1024d;
unitIndex++;
}
return String.format(Locale.ROOT, "%.2f %s", value, units[unitIndex]);
}
}
/**
* Execution mode for backtest runs.
*
* - {@link #FULL_RESULT}: Execute all strategies and return full results for
* all strategies
* - {@link #KEEP_TOP_K}: Execute all strategies but only keep results for the
* top K performers (more memory-efficient for large strategy counts)
*
*/
enum ExecutionMode {
/** Execute all strategies and return full results. */
FULL_RESULT,
/** Execute all strategies but only keep top K results. */
KEEP_TOP_K
}
/**
* Configuration for a single backtest run.
*
* @param strategyCount Number of strategies to test (-1 for full grid)
* @param barCount Number of bars to use (0 or negative for full
* series)
* @param maximumBarCountHint Maximum bar count hint for indicator caching (0 to
* disable)
* @param executionMode Execution mode (FULL_RESULT or KEEP_TOP_K)
* @param topK Number of top strategies to keep when using
* KEEP_TOP_K mode
* @param progress Whether to enable progress logging with memory
* information
*/
record RunOnceConfig(int strategyCount, int barCount, int maximumBarCountHint, ExecutionMode executionMode, int topK,
boolean progress) {
}
/**
* Thresholds for detecting non-linear performance behavior.
*
* @param gcOverheadThreshold GC overhead threshold (0.0 to 1.0, e.g., 0.25 =
* 25% of runtime)
* @param slowdownRatioThreshold Normalized slowdown ratio threshold (e.g., 1.25
* = 25% slowdown)
*/
record Thresholds(double gcOverheadThreshold, double slowdownRatioThreshold) {
String describe() {
return String.format(Locale.ROOT, "{gcOverhead=%s, slowdownRatio>=%.3f}", formatPercent(gcOverheadThreshold),
slowdownRatioThreshold);
}
private static String formatPercent(double value) {
return String.format(Locale.ROOT, "%.2f%%", value * 100d);
}
}
record TunePlan(List strategyCounts, List variants, ExecutionMode executionMode, int topK,
boolean progress, boolean gcBetweenRuns) {
static TunePlan fromCli(HarnessCli cli, int fullBarCount) {
List strategyCounts = cli.buildTuneStrategyCounts();
List variants = cli.buildSeriesVariants(fullBarCount);
return new TunePlan(strategyCounts, variants, cli.executionMode, cli.topK, cli.progress, cli.gcBetweenRuns);
}
String describe() {
return String.format(Locale.ROOT, "{strategyCounts=%s, variants=%d, executionMode=%s, topK=%d}", strategyCounts,
variants.size(), executionMode, topK);
}
}
record SeriesVariant(int barCount, int maximumBarCountHint) {
BarSeries apply(BarSeries baseSeries) {
return BacktestPerformanceTuningHarness.sliceToLastBars(baseSeries, barCount);
}
String describeLabel() {
return String.format(Locale.ROOT, "barCount=%s, maxBarCountHint=%s",
barCount <= 0 ? "full" : Integer.toString(barCount),
maximumBarCountHint <= 0 ? "default" : Integer.toString(maximumBarCountHint));
}
String describe(BarSeries series) {
return String.format(Locale.ROOT, "{barCount=%s, maxBarCountHint=%s, effectiveBars=%d}",
barCount <= 0 ? "full" : Integer.toString(barCount),
maximumBarCountHint <= 0 ? "default" : Integer.toString(maximumBarCountHint),
series.getEndIndex() - series.getBeginIndex() + 1);
}
}
record VariantTuningResult(SeriesVariant variant, RunResult lastLinear, RunResult firstNonLinear) {
}
record BacktestRuntimeStats(Duration overallRuntime, Duration minStrategyRuntime, Duration maxStrategyRuntime,
Duration averageStrategyRuntime, Duration medianStrategyRuntime, String runtimeReportJson) {
static BacktestRuntimeStats from(org.ta4j.core.backtest.BacktestRuntimeReport report) {
return new BacktestRuntimeStats(report.overallRuntime(), report.minStrategyRuntime(),
report.maxStrategyRuntime(), report.averageStrategyRuntime(), report.medianStrategyRuntime(),
report.toString());
}
}
record RunOutcome(BacktestExecutionResult result, RunResult runResult) {
}
/**
* Host metadata captured with a stable hashed host identifier so benchmark
* artifacts can be shared without exposing local machine names.
*/
record HostTelemetry(String hostId, String osName, String osArch, String osVersion, int logicalProcessors,
long maxMemoryBytes, String javaVersion, String javaVmName) {
static HostTelemetry capture() {
return new HostTelemetry(detectHostId(), System.getProperty("os.name", "unknown"),
System.getProperty("os.arch", "unknown"), System.getProperty("os.version", "unknown"),
Runtime.getRuntime().availableProcessors(), Runtime.getRuntime().maxMemory(),
System.getProperty("java.version", "unknown"), System.getProperty("java.vm.name", "unknown"));
}
private static String detectHostId() {
String hostname = detectHostname();
return "unknown".equals(hostname) ? hostname
: "sha256:" + BacktestPerformanceTuningHarness.shortSha256(hostname);
}
private static String detectHostname() {
try {
return InetAddress.getLocalHost().getHostName();
} catch (UnknownHostException ex) {
return "unknown";
}
}
}
record ThroughputMatrixCell(String cellId, int strategyCount, int barCount, int maximumBarCountHint,
ExecutionMode executionMode, int topK) {
RunOnceConfig toRunOnceConfig(boolean progress) {
return new RunOnceConfig(strategyCount, barCount, maximumBarCountHint, executionMode, topK, progress);
}
JsonObject toJson() {
return BacktestPerformanceTuningHarness.GSON.toJsonTree(this).getAsJsonObject();
}
}
record ThroughputCellResult(ThroughputMatrixCell cell, RunResult runResult, long wallTimeMs) {
JsonObject toJson() {
JsonObject object = new JsonObject();
object.add("cell", cell.toJson());
object.add("runResult", BacktestPerformanceTuningHarness.GSON.toJsonTree(runResult));
object.addProperty("wallTimeMs", wallTimeMs);
object.addProperty("strategyBuildWallTimeMs", runResult.strategyBuildDuration().toMillis());
object.addProperty("backtestRuntimeMs", runResult.runtimeStats().overallRuntime().toMillis());
return object;
}
}
record ThroughputControlPlan(String dataset, Path outputDir, List cells, String parallelism,
int resolvedParallelism, ExecutionMode executionMode, int topK, boolean progress, boolean gcBetweenRuns,
String specFingerprint) {
static ThroughputControlPlan fromCli(HarnessCli cli, int fullBarCount) {
List cells = cli.buildThroughputCells(fullBarCount);
int resolvedParallelism = resolveParallelism(cli.parallelism, cells.size());
StringJoiner fingerprintSource = new StringJoiner("|");
fingerprintSource.add(cli.ohlcResourceFile)
.add(cli.executionMode.name())
.add(Integer.toString(cli.topK))
.add(cli.parallelism)
.add(Integer.toString(resolvedParallelism))
.add(Boolean.toString(cli.progress))
.add(Boolean.toString(cli.gcBetweenRuns));
cells.forEach(cell -> fingerprintSource.add(cell.toString()));
Path outputDir = cli.throughputOutputDir == null ? Path.of(".agents", "benchmarks", "backtest-throughput",
"matrix-" + Instant.now().toString().replace(':', '-')) : cli.throughputOutputDir;
return new ThroughputControlPlan(cli.ohlcResourceFile, outputDir.toAbsolutePath().normalize(), cells,
cli.parallelism, resolvedParallelism, cli.executionMode, cli.topK, cli.progress, cli.gcBetweenRuns,
BacktestPerformanceTuningHarness.shortSha256(fingerprintSource.toString()));
}
JsonObject toManifest(HostTelemetry host) {
JsonObject object = new JsonObject();
object.addProperty("schemaVersion", 1);
object.addProperty("createdAt", Instant.now().toString());
object.addProperty("dataset", dataset);
object.addProperty("specFingerprint", specFingerprint);
object.addProperty("parallelism", parallelism);
object.addProperty("resolvedParallelism", resolvedParallelism);
object.addProperty("executionMode", executionMode.name());
object.addProperty("topK", topK);
object.addProperty("progress", progress);
object.addProperty("gcBetweenRuns", gcBetweenRuns);
object.add("host", BacktestPerformanceTuningHarness.GSON.toJsonTree(host));
JsonArray cellArray = new JsonArray();
cells.forEach(cell -> cellArray.add(cell.toJson()));
object.add("cells", cellArray);
return object;
}
private static int resolveParallelism(String rawParallelism, int cellCount) {
int cells = Math.max(1, cellCount);
String raw = rawParallelism == null || rawParallelism.isBlank() ? "1" : rawParallelism.trim();
if ("auto".equalsIgnoreCase(raw)) {
int processors = Math.max(1, Runtime.getRuntime().availableProcessors());
int withHeadroom = Math.max(1, (int) Math.ceil(processors * 0.50d));
return Math.min(cells, withHeadroom);
}
int parsed = Integer.parseInt(raw);
if (parsed <= 0) {
throw new IllegalArgumentException("--parallelism must be positive or auto");
}
return Math.min(cells, parsed);
}
}
/**
* Aggregates additive throughput telemetry for fixed backtest matrix runs.
*/
final class ThroughputMatrixPerformanceTracker {
private final List cells = new ArrayList<>();
synchronized void record(ThroughputCellResult cell) {
cells.add(Objects.requireNonNull(cell, "cell"));
}
synchronized JsonObject cellsJson() {
JsonObject root = new JsonObject();
JsonArray cellArray = new JsonArray();
for (ThroughputCellResult cell : cells) {
cellArray.add(cell.toJson());
}
root.add("cells", cellArray);
return root;
}
synchronized JsonObject toJson(long totalWallTimeMs, ThroughputControlPlan plan, HostTelemetry host) {
int cellCount = cells.size();
int hypothesisCount = 0;
long sumCellWallTimeMs = 0L;
long strategyBuildWallTimeMs = 0L;
long backtestRuntimeMs = 0L;
JsonArray cellArray = new JsonArray();
for (ThroughputCellResult cell : cells) {
RunResult runResult = cell.runResult();
hypothesisCount += runResult.strategyCount();
sumCellWallTimeMs += cell.wallTimeMs();
strategyBuildWallTimeMs += runResult.strategyBuildDuration().toMillis();
backtestRuntimeMs += runResult.runtimeStats().overallRuntime().toMillis();
cellArray.add(cell.toJson());
}
JsonObject root = new JsonObject();
root.addProperty("schemaVersion", 1);
root.addProperty("completedAt", Instant.now().toString());
root.addProperty("dataset", plan.dataset());
root.addProperty("specFingerprint", plan.specFingerprint());
root.addProperty("parallelism", plan.parallelism());
root.addProperty("resolvedParallelism", plan.resolvedParallelism());
root.addProperty("executionMode", plan.executionMode().name());
root.addProperty("topK", plan.topK());
root.addProperty("progress", plan.progress());
root.addProperty("gcBetweenRuns", plan.gcBetweenRuns());
root.addProperty("totalWallTimeMs", totalWallTimeMs);
root.addProperty("sumCellWallTimeMs", sumCellWallTimeMs);
root.addProperty("strategyBuildWallTimeMs", strategyBuildWallTimeMs);
root.addProperty("backtestRuntimeMs", backtestRuntimeMs);
root.addProperty("cellCount", cellCount);
root.addProperty("hypothesisKind", "strategy");
root.addProperty("hypothesisCount", hypothesisCount);
root.addProperty("cellsPerMinute", perMinute(cellCount, totalWallTimeMs));
root.addProperty("hypothesesPerMinute", perMinute(hypothesisCount, totalWallTimeMs));
root.add("host", BacktestPerformanceTuningHarness.GSON.toJsonTree(host));
JsonObject phases = new JsonObject();
JsonObject matrix = new JsonObject();
matrix.addProperty("cellCount", cellCount);
matrix.addProperty("hypothesisCount", hypothesisCount);
matrix.addProperty("sumCellWallTimeMs", sumCellWallTimeMs);
matrix.add("cells", cellArray);
phases.add("backtest", matrix);
root.add("phases", phases);
return root;
}
private static double perMinute(long count, long wallTimeMs) {
return wallTimeMs <= 0L ? count * 60_000.0d : count * 60_000.0d / wallTimeMs;
}
}
/**
* Results from a single backtest run, including performance metrics.
*
* @param executionMode The execution mode used
* @param strategyCount Number of strategies tested
* @param barCount Actual number of bars used
* @param maximumBarCountHintRequested The maximum bar count hint that was
* requested
* @param maximumBarCountHintEffective The effective maximum bar count hint
* applied
* @param barCountRequested The bar count that was requested (0 =
* full series)
* @param strategyBuildDuration Time taken to build all strategies
* @param runtimeStats Runtime statistics from the backtest
* execution
* @param workUnits Total work units (strategies × bars)
* @param gcDelta GC statistics delta (after - before)
* @param heapBefore Heap snapshot before execution
* @param heapAfter Heap snapshot after execution
* @param numFactory The NumFactory class name used
*/
record RunResult(ExecutionMode executionMode, int strategyCount, int barCount, int maximumBarCountHintRequested,
int maximumBarCountHintEffective, int barCountRequested, Duration strategyBuildDuration,
BacktestRuntimeStats runtimeStats, long workUnits, GcSnapshot gcDelta, HeapSnapshot heapBefore,
HeapSnapshot heapAfter, String numFactory) {
String toJson() {
return BacktestPerformanceTuningHarness.GSON.toJson(this);
}
double gcOverhead() {
if (runtimeStats.overallRuntime().isZero()) {
return 0d;
}
return gcDelta.collectionTime().toNanos() / (double) runtimeStats.overallRuntime().toNanos();
}
String describeSweetSpot() {
return String.format(Locale.ROOT,
"{strategies=%d, bars=%d, barCount=%s, maxBarCountHint=%s (effective=%s), heapMax=%s, overallRuntime=%s, gcOverhead=%s}",
strategyCount, barCount, barCountRequested <= 0 ? "full" : Integer.toString(barCountRequested),
maximumBarCountHintRequested <= 0 ? "default" : Integer.toString(maximumBarCountHintRequested),
Integer.toString(maximumBarCountHintEffective),
BacktestPerformanceTuningHarness.formatBytes(heapAfter.maxBytes()), runtimeStats.overallRuntime(),
String.format(Locale.ROOT, "%.2f%%", gcOverhead() * 100d));
}
}
record HeapSnapshot(long maxBytes, long committedBytes, long usedBytes) {
static HeapSnapshot capture() {
MemoryUsage heap = ManagementFactory.getMemoryMXBean().getHeapMemoryUsage();
return new HeapSnapshot(Runtime.getRuntime().maxMemory(), heap.getCommitted(), heap.getUsed());
}
}
record GcSnapshot(long collections, Duration collectionTime) {
static GcSnapshot capture() {
long count = 0;
long timeMillis = 0;
for (GarbageCollectorMXBean bean : ManagementFactory.getGarbageCollectorMXBeans()) {
long beanCount = bean.getCollectionCount();
if (beanCount >= 0) {
count += beanCount;
}
long beanTime = bean.getCollectionTime();
if (beanTime >= 0) {
timeMillis += beanTime;
}
}
return new GcSnapshot(count, Duration.ofMillis(timeMillis));
}
GcSnapshot delta(GcSnapshot before) {
return new GcSnapshot(collections - before.collections, collectionTime.minus(before.collectionTime));
}
}
/**
* A wrapper around a BarSeries that overrides the maximum bar count hint for
* indicator caching.
*
* This wrapper is used during performance tuning to test the impact of
* different maximum bar count hints on performance and memory usage. It
* delegates all BarSeries operations to the underlying series but overrides
* {@link #getMaximumBarCount()} to return the specified hint.
*
* The maximum bar count hint cannot be changed after construction
* (setMaximumBarCount throws UnsupportedOperationException) since this is a
* hint-only override for benchmarking purposes.
*/
final class MaxBarCountHintSeries implements BarSeries {
private static final long serialVersionUID = 4398573823756330718L;
private final BarSeries delegate;
private final int maximumBarCountHint;
MaxBarCountHintSeries(BarSeries delegate, int maximumBarCountHint) {
this.delegate = Objects.requireNonNull(delegate, "delegate must not be null");
this.maximumBarCountHint = maximumBarCountHint;
}
@Override
public NumFactory numFactory() {
return delegate.numFactory();
}
@Override
public BarBuilder barBuilder() {
return delegate.barBuilder();
}
@Override
public String getName() {
return delegate.getName();
}
@Override
public Bar getBar(int i) {
return delegate.getBar(i);
}
@Override
public int getBarCount() {
return delegate.getBarCount();
}
@Override
public List getBarData() {
return delegate.getBarData();
}
@Override
public int getBeginIndex() {
return delegate.getBeginIndex();
}
@Override
public int getEndIndex() {
return delegate.getEndIndex();
}
@Override
public int getMaximumBarCount() {
return maximumBarCountHint;
}
@Override
public void setMaximumBarCount(int maximumBarCount) {
throw new UnsupportedOperationException("Maximum bar count is a hint-only override for benchmarking");
}
@Override
public int getRemovedBarsCount() {
return delegate.getRemovedBarsCount();
}
@Override
public void addBar(Bar bar, boolean replace) {
delegate.addBar(bar, replace);
}
@Override
public void addTrade(Num tradeVolume, Num tradePrice) {
delegate.addTrade(tradeVolume, tradePrice);
}
@Override
public void addPrice(Num price) {
delegate.addPrice(price);
}
@Override
public BarSeries getSubSeries(int startIndex, int endIndex) {
return delegate.getSubSeries(startIndex, endIndex);
}
}
final class HarnessCli {
boolean help;
boolean tune;
boolean throughputControl;
boolean progress;
boolean gcBetweenRuns = true;
int topK = BacktestPerformanceTuningHarness.DEFAULT_TOP_K;
int barCount;
int strategyCount = -1;
int maximumBarCountHint;
int tuneStrategyStart = BacktestPerformanceTuningHarness.DEFAULT_TUNE_STRATEGY_START;
int tuneStrategyStep = BacktestPerformanceTuningHarness.DEFAULT_TUNE_STRATEGY_STEP;
int tuneStrategyMax = BacktestPerformanceTuningHarness.DEFAULT_TUNE_STRATEGY_MAX;
double nonlinearGcOverheadThreshold = BacktestPerformanceTuningHarness.DEFAULT_NONLINEAR_GC_OVERHEAD;
double nonlinearSlowdownRatioThreshold = BacktestPerformanceTuningHarness.DEFAULT_NONLINEAR_SLOWDOWN_RATIO;
String ohlcResourceFile = BacktestPerformanceTuningHarness.DEFAULT_OHLC_RESOURCE_FILE;
String parallelism = "1";
Path throughputOutputDir;
ExecutionMode executionMode = ExecutionMode.FULL_RESULT;
List tuneBarCounts = List.of();
List tuneMaxBarCountHints = List.of();
List tuneHeaps = List.of();
List matrixStrategyCounts = List.of();
List matrixBarCounts = List.of();
List matrixMaxBarCountHints = List.of();
static HarnessCli parse(String[] args) {
HarnessCli cli = new HarnessCli();
if (args == null || args.length == 0) {
return cli;
}
for (int i = 0; i < args.length; i++) {
String arg = args[i];
switch (arg) {
case "-h", "--help" -> cli.help = true;
case "--tune" -> cli.tune = true;
case "--throughputControl", "--throughput-control" -> cli.throughputControl = true;
case "--progress" -> cli.progress = true;
case "--gcBetweenRuns" -> cli.gcBetweenRuns = true;
case "--noGcBetweenRuns" -> cli.gcBetweenRuns = false;
case "--topK" -> cli.topK = Integer.parseInt(requireValue(args, ++i, arg));
case "--bars", "--barCount" -> cli.barCount = Integer.parseInt(requireValue(args, ++i, arg));
case "--strategies" -> cli.strategyCount = Integer.parseInt(requireValue(args, ++i, arg));
case "--maxBarCountHint" -> cli.maximumBarCountHint = Integer.parseInt(requireValue(args, ++i, arg));
case "--dataset" -> cli.ohlcResourceFile = requireValue(args, ++i, arg);
case "--executionMode" -> cli.executionMode = parseExecutionMode(requireValue(args, ++i, arg));
case "--parallelism" -> cli.parallelism = parseParallelism(requireValue(args, ++i, arg));
case "--throughputOutputDir", "--throughput-output-dir" ->
cli.throughputOutputDir = Path.of(requireValue(args, ++i, arg));
case "--matrixStrategyCounts", "--matrix-strategy-counts" ->
cli.matrixStrategyCounts = parseCsvPositiveInts(requireValue(args, ++i, arg), arg);
case "--matrixBarCounts", "--matrix-bar-counts" ->
cli.matrixBarCounts = parseCsvBarCounts(requireValue(args, ++i, arg), arg);
case "--matrixMaxBarCountHints", "--matrix-max-bar-count-hints" ->
cli.matrixMaxBarCountHints = parseCsvNonNegativeInts(requireValue(args, ++i, arg), arg);
case "--tuneStrategyStart" -> cli.tuneStrategyStart = Integer.parseInt(requireValue(args, ++i, arg));
case "--tuneStrategyStep" -> cli.tuneStrategyStep = Integer.parseInt(requireValue(args, ++i, arg));
case "--tuneStrategyMax" -> cli.tuneStrategyMax = Integer.parseInt(requireValue(args, ++i, arg));
case "--tuneBarCounts" -> cli.tuneBarCounts = parseCsvBarCounts(requireValue(args, ++i, arg), arg);
case "--tuneMaxBarCountHints" ->
cli.tuneMaxBarCountHints = parseCsvNonNegativeInts(requireValue(args, ++i, arg), arg);
case "--nonlinearGcOverhead" ->
cli.nonlinearGcOverheadThreshold = Double.parseDouble(requireValue(args, ++i, arg));
case "--nonlinearSlowdownRatio" ->
cli.nonlinearSlowdownRatioThreshold = Double.parseDouble(requireValue(args, ++i, arg));
case "--tuneHeaps" -> cli.tuneHeaps = parseCsvStrings(requireValue(args, ++i, arg));
default -> throw new IllegalArgumentException("Unknown argument: " + arg);
}
}
if (!cli.tuneHeaps.isEmpty()) {
cli.tune = true;
}
return cli;
}
List toChildTuneArgs() {
List args = new ArrayList<>();
args.add("--tune");
args.add("--dataset");
args.add(ohlcResourceFile);
args.add("--executionMode");
args.add(executionMode == ExecutionMode.KEEP_TOP_K ? "topK" : "full");
args.add("--topK");
args.add(Integer.toString(topK));
args.add("--tuneStrategyStart");
args.add(Integer.toString(tuneStrategyStart));
args.add("--tuneStrategyStep");
args.add(Integer.toString(tuneStrategyStep));
args.add("--tuneStrategyMax");
args.add(Integer.toString(tuneStrategyMax));
if (!tuneBarCounts.isEmpty()) {
args.add("--tuneBarCounts");
args.add(joinCsvInts(tuneBarCounts));
}
if (!tuneMaxBarCountHints.isEmpty()) {
args.add("--tuneMaxBarCountHints");
args.add(joinCsvInts(tuneMaxBarCountHints));
}
args.add("--nonlinearGcOverhead");
args.add(Double.toString(nonlinearGcOverheadThreshold));
args.add("--nonlinearSlowdownRatio");
args.add(Double.toString(nonlinearSlowdownRatioThreshold));
if (progress) {
args.add("--progress");
}
if (gcBetweenRuns) {
args.add("--gcBetweenRuns");
} else {
args.add("--noGcBetweenRuns");
}
return args;
}
List buildTuneStrategyCounts() {
if (tuneStrategyStart <= 0 || tuneStrategyStep <= 0 || tuneStrategyMax <= 0) {
throw new IllegalArgumentException("Tune strategy counts must be positive");
}
if (tuneStrategyStart > tuneStrategyMax) {
throw new IllegalArgumentException("tuneStrategyStart must be <= tuneStrategyMax");
}
List counts = new ArrayList<>();
for (int strategies = tuneStrategyStart; strategies <= tuneStrategyMax; strategies += tuneStrategyStep) {
counts.add(strategies);
}
return counts;
}
List buildSeriesVariants(int fullBarCount) {
List variants = new ArrayList<>();
List barCounts = tuneBarCounts.isEmpty() ? List.of(500, 1_000, 2_000, 0) : tuneBarCounts;
for (int barCount : barCounts) {
int normalized = barCount <= 0 ? 0 : Math.min(barCount, fullBarCount);
variants.add(new SeriesVariant(normalized, 0));
}
List hints = tuneMaxBarCountHints.isEmpty() ? List.of(0, 512, 1_024, 2_048) : tuneMaxBarCountHints;
for (int hint : hints) {
if (hint < 0) {
continue;
}
variants.add(new SeriesVariant(0, hint));
}
return dedupeVariants(variants);
}
List buildThroughputCells(int fullBarCount) {
List strategyCounts = matrixStrategyCounts.isEmpty()
? BacktestPerformanceTuningHarness.DEFAULT_MATRIX_STRATEGY_COUNTS
: matrixStrategyCounts;
strategyCounts = dedupeIntegers(strategyCounts);
List barCounts = matrixBarCounts.isEmpty() ? BacktestPerformanceTuningHarness.DEFAULT_MATRIX_BAR_COUNTS
: matrixBarCounts;
barCounts = dedupeIntegers(barCounts);
List maximumBarCountHints = matrixMaxBarCountHints.isEmpty()
? BacktestPerformanceTuningHarness.DEFAULT_MATRIX_MAX_BAR_COUNT_HINTS
: matrixMaxBarCountHints;
maximumBarCountHints = dedupeIntegers(maximumBarCountHints);
List cells = new ArrayList<>();
for (int strategyCount : strategyCounts) {
for (int rawBarCount : barCounts) {
int barCount = rawBarCount <= 0 ? 0 : Math.min(rawBarCount, fullBarCount);
for (int maximumBarCountHint : maximumBarCountHints) {
String cellId = "s" + strategyCount + "-b" + (barCount <= 0 ? "full" : barCount) + "-m"
+ maximumBarCountHint;
cells.add(new ThroughputMatrixCell(cellId, strategyCount, barCount, maximumBarCountHint,
executionMode, topK));
}
}
}
return cells;
}
private static List dedupeIntegers(List values) {
List deduped = new ArrayList<>();
for (Integer candidate : values) {
if (!deduped.contains(candidate)) {
deduped.add(candidate);
}
}
return deduped;
}
private List dedupeVariants(List variants) {
List deduped = new ArrayList<>();
for (SeriesVariant candidate : variants) {
boolean exists = false;
for (SeriesVariant existing : deduped) {
if (existing.barCount() == candidate.barCount()
&& existing.maximumBarCountHint() == candidate.maximumBarCountHint()) {
exists = true;
break;
}
}
if (!exists) {
deduped.add(candidate);
}
}
return deduped;
}
private static ExecutionMode parseExecutionMode(String raw) {
String normalized = raw == null ? "" : raw.trim().toLowerCase(Locale.ROOT);
return switch (normalized) {
case "topk", "top_k", "keeptopk", "keep_top_k" -> ExecutionMode.KEEP_TOP_K;
case "full", "all", "full_result", "fullresult" -> ExecutionMode.FULL_RESULT;
default -> throw new IllegalArgumentException("Unknown executionMode: " + raw);
};
}
private static String requireValue(String[] args, int index, String flag) {
if (index >= args.length) {
throw new IllegalArgumentException("Missing value for " + flag);
}
return args[index];
}
private static List parseCsvStrings(String value) {
if (value == null || value.isBlank()) {
return List.of();
}
return Arrays.stream(value.split(",")).map(String::trim).filter(part -> !part.isEmpty()).toList();
}
private static String parseParallelism(String value) {
String normalized = value == null ? "" : value.trim().toLowerCase(Locale.ROOT);
if ("auto".equals(normalized)) {
return normalized;
}
int parsed = Integer.parseInt(normalized);
if (parsed <= 0) {
throw new IllegalArgumentException("--parallelism must be positive or auto");
}
return Integer.toString(parsed);
}
private static List parseCsvBarCounts(String value, String flag) {
if (value == null || value.isBlank()) {
return List.of();
}
List values = Arrays.stream(value.split(","))
.map(String::trim)
.filter(part -> !part.isEmpty())
.map(part -> parseBarCount(part, flag))
.toList();
return values;
}
private static int parseBarCount(String value, String flag) {
if ("full".equalsIgnoreCase(value)) {
return 0;
}
int parsed = Integer.parseInt(value);
if (parsed < 0) {
String source = flag == null ? "bar count" : flag;
throw new IllegalArgumentException(source + " values must be >= 0 or full");
}
return parsed;
}
private static List parseCsvPositiveInts(String value, String flag) {
return parseCsvBoundedInts(value, flag, 1);
}
private static List parseCsvNonNegativeInts(String value, String flag) {
return parseCsvBoundedInts(value, flag, 0);
}
private static List parseCsvBoundedInts(String value, String flag, int minimum) {
if (value == null || value.isBlank()) {
return List.of();
}
List values = Arrays.stream(value.split(","))
.map(String::trim)
.filter(part -> !part.isEmpty())
.map(Integer::parseInt)
.toList();
for (int parsed : values) {
if (parsed < minimum) {
throw new IllegalArgumentException(flag + " values must be >= " + minimum);
}
}
return values;
}
private static String joinCsvInts(List values) {
return values.stream().map(Object::toString).reduce((left, right) -> left + "," + right).orElse("");
}
}