chore: improve reproducibility

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/DefaultEvolutionaryAlgorithmPhaseFactory.java

@@ -75,6 +75,7 @@
 import ai.timefold.solver.core.impl.phase.AbstractPhaseFactory;
 import ai.timefold.solver.core.impl.phase.Phase;
 import ai.timefold.solver.core.impl.phase.PhaseFactory;
+import ai.timefold.solver.core.impl.solver.random.DelegatingSplittableRandomGenerator;
 import ai.timefold.solver.core.impl.solver.recaller.BestSolutionRecaller;
 import ai.timefold.solver.core.impl.solver.termination.PhaseTermination;
 import ai.timefold.solver.core.impl.solver.termination.SolverTermination;
@@ -178,19 +179,19 @@ public EvolutionaryAlgorithmPhase<Solution_> buildPhase(int phaseIndex, boolean
                 disableLogging(buildRefinmentPhase(solverConfigPolicy, solverTermination, isListVariable));
 
         ConstructionIndividualStrategy<Solution_, Score_> exploratoryConstructionIndividualStrategy =
-                buildConstructionIndividualPhase(workerConfig, workerConfig.getIndividualGeneratorConfig(),
+                buildConstructionIndividualPhase(solverConfigPolicy, workerConfig, workerConfig.getIndividualGeneratorConfig(),
                         deterministicBestFitConstructionPhase, shuffledFirstFitConstructionPhase, fasterLocalSearchPhase,
                         refinmentPhase, solutionStateManager, individualBuilder, exploratoryInheritanceRate, isListVariable);
         ConstructionIndividualStrategy<Solution_, Score_> conservativeConstructionIndividualStrategy =
-                buildConstructionIndividualPhase(workerConfig, workerConfig.getIndividualGeneratorConfig(),
+                buildConstructionIndividualPhase(solverConfigPolicy, workerConfig, workerConfig.getIndividualGeneratorConfig(),
                         deterministicBestFitConstructionPhase, shuffledFirstFitConstructionPhase, regularLocalSearchPhase,
                         refinmentPhase, solutionStateManager, individualBuilder, conservativeInheritanceRate, isListVariable);
 
         CrossoverStrategy<Solution_, Score_> exploratoryCrossoverStrategy =
-                buildCrossoverStrategy(fasterLocalSearchPhase, refinmentPhase, false, exploratoryInheritanceRate,
-                        isListVariable);
-        CrossoverStrategy<Solution_, Score_> conservativeCrossoverStrategy = buildCrossoverStrategy(regularLocalSearchPhase,
-                refinmentPhase, true, conservativeInheritanceRate, isListVariable);
+                buildCrossoverStrategy(solverConfigPolicy, fasterLocalSearchPhase, refinmentPhase, false,
+                        exploratoryInheritanceRate, isListVariable);
+        CrossoverStrategy<Solution_, Score_> conservativeCrossoverStrategy = buildCrossoverStrategy(solverConfigPolicy,
+                regularLocalSearchPhase, refinmentPhase, true, conservativeInheritanceRate, isListVariable);
 
         if (workerConfig.getExploratoryRate() != null && (workerConfig.getExploratoryRate() < 0.0
                 || workerConfig.getExploratoryRate() > 1.0)) {
@@ -224,12 +225,14 @@ SolutionStateManager<Solution_, Score_, State_> buildSolutionStateManager(boolea
     }
 
     private static <Solution_, Score_ extends Score<Score_>> CrossoverStrategy<Solution_, Score_> buildCrossoverStrategy(
-            Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase, boolean isComplex,
-            double inheritanceRate, boolean isListVariable) {
+            HeuristicConfigPolicy<Solution_> solverConfigPolicy, Phase<Solution_> localSearchPhase,
+            @Nullable Phase<Solution_> refinementPhase, boolean isComplex, double inheritanceRate, boolean isListVariable) {
+        var mainRandomGenerator = (DelegatingSplittableRandomGenerator) solverConfigPolicy.getRandom();
         if (isListVariable) {
-            return new ListOXCrossover<>(localSearchPhase, refinementPhase, inheritanceRate, !isComplex);
+            return new ListOXCrossover<>(localSearchPhase, refinementPhase, inheritanceRate, !isComplex,
+                    mainRandomGenerator.split());
         } else {
-            return new BasicOXCrossover<>(localSearchPhase, refinementPhase, inheritanceRate);
+            return new BasicOXCrossover<>(localSearchPhase, refinementPhase, inheritanceRate, mainRandomGenerator.split());
         }
     }
 
@@ -268,22 +271,24 @@ private static <Solution_> Phase<Solution_> buildShuffledConstructionHeuristicPh
 
     private static <Solution_, Score_ extends Score<Score_>, State_ extends SolutionState<Solution_, Score_>>
             ConstructionIndividualStrategy<Solution_, Score_>
-            buildConstructionIndividualPhase(EvolutionaryWorkerConfig workerConfig,
+            buildConstructionIndividualPhase(HeuristicConfigPolicy<Solution_> solverConfigPolicy,
+                    EvolutionaryWorkerConfig workerConfig,
                     @Nullable EvolutionaryIndividualGeneratorConfig individualGeneratorConfig,
                     Phase<Solution_> deterministicBestFitConstructionPhase, Phase<Solution_> shuffledFirstFitConstructionPhase,
                     Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase,
                     SolutionStateManager<Solution_, Score_, State_> solutionStateManager,
                     IndividualBuilder<Solution_, Score_> individualBuilder, double inheritanceRate, boolean isListVariable) {
         List<PhaseCommand<Solution_>> customIndividualPhaseCommandList =
                 buildPhaseCommandList(workerConfig, individualGeneratorConfig);
+        var mainRandomGenerator = (DelegatingSplittableRandomGenerator) solverConfigPolicy.getRandom();
         if (isListVariable) {
             return new ListRuinRecreateIndividualStrategy<>(customIndividualPhaseCommandList,
                     deterministicBestFitConstructionPhase, localSearchPhase, refinementPhase, solutionStateManager,
-                    individualBuilder, inheritanceRate);
+                    individualBuilder, inheritanceRate, mainRandomGenerator.split());
         } else {
             return new BasicRuinRecreateIndividualStrategy<>(customIndividualPhaseCommandList,
                     deterministicBestFitConstructionPhase, shuffledFirstFitConstructionPhase, localSearchPhase, refinementPhase,
-                    solutionStateManager, individualBuilder, inheritanceRate);
+                    solutionStateManager, individualBuilder, inheritanceRate, mainRandomGenerator.split());
         }
     }
 

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/crossover/basic/BasicOXCrossover.java

@@ -36,15 +36,15 @@
  */
 @NullMarked
 public record BasicOXCrossover<Solution_, Score_ extends Score<Score_>>(Phase<Solution_> localSearchPhase,
-        @Nullable Phase<Solution_> refinementPhase, double inheritanceRate) implements CrossoverStrategy<Solution_, Score_> {
+        @Nullable Phase<Solution_> refinementPhase, double inheritanceRate,
+        RandomGenerator workingRandom) implements CrossoverStrategy<Solution_, Score_> {
 
     @Override
     public CrossoverResult<Solution_, Score_> apply(CrossoverContext<Solution_, Score_> context) {
         var phaseScope = context.phaseScope();
         var solverScope = phaseScope.getSolverScope();
         var scoreDirector = phaseScope.<Score_> getScoreDirector();
-        generateOffspring(scoreDirector, context.firstIndividual(), context.secondIndividual(),
-                inheritanceRate, phaseScope.getWorkingRandom());
+        generateOffspring(scoreDirector, context.firstIndividual(), context.secondIndividual(), inheritanceRate, workingRandom);
         updateScope(phaseScope);
         applyPhases(phaseScope, localSearchPhase, refinementPhase);
         return new CrossoverResult<>(scoreDirector.cloneSolution(solverScope.getBestSolution()),

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/crossover/list/AbstractListCrossover.java

@@ -2,6 +2,7 @@
 
 import java.util.Objects;
 import java.util.Set;
+import java.util.random.RandomGenerator;
 
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.impl.domain.variable.ListVariableStateSupply;
@@ -27,12 +28,14 @@ public abstract sealed class AbstractListCrossover<Solution_, Score_ extends Sco
     final Phase<Solution_> localSearchPhase;
     final @Nullable Phase<Solution_> refinementPhase;
     final double inheritanceRate;
+    final RandomGenerator workingRandom;
 
-    AbstractListCrossover(Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase,
-            double inheritanceRate) {
+    AbstractListCrossover(Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase, double inheritanceRate,
+            RandomGenerator workingRandom) {
         this.localSearchPhase = localSearchPhase;
         this.refinementPhase = refinementPhase;
         this.inheritanceRate = inheritanceRate;
+        this.workingRandom = workingRandom;
     }
 
     /**

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/crossover/list/ListOXCrossover.java

@@ -45,8 +45,8 @@ public final class ListOXCrossover<Solution_, Score_ extends Score<Score_>>
     private final boolean applyBestFitFirstPhase;
 
     public ListOXCrossover(Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase,
-            double inheritanceRate, boolean applyBestFitFirstPhase) {
-        super(localSearchPhase, refinementPhase, inheritanceRate);
+            double inheritanceRate, boolean applyBestFitFirstPhase, RandomGenerator workingRandom) {
+        super(localSearchPhase, refinementPhase, inheritanceRate, workingRandom);
         this.applyBestFitFirstPhase = applyBestFitFirstPhase;
     }
 
@@ -63,7 +63,7 @@ public CrossoverResult<Solution_, Score_> apply(CrossoverContext<Solution_, Scor
             // Produce the offspring based on the two parents.
             generateOffspring(scoreDirector, listVariableStateSupply, listVariableDescriptor, listVariableModel,
                     valueRangeManager, context.firstIndividual(), context.secondIndividual(), inheritanceRate,
-                    applyBestFitFirstPhase, phaseScope.getWorkingRandom());
+                    applyBestFitFirstPhase, workingRandom);
             // We need to update the best solution, best score,
             // and initialized score to avoid inconsistencies in the next phases
             updateScope(phaseScope);

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/crossover/list/ListRXCrossover.java

@@ -45,8 +45,8 @@ public final class ListRXCrossover<Solution_, Score_ extends Score<Score_>>
     private final boolean applyBestFitFirstPhase;
 
     public ListRXCrossover(Phase<Solution_> localSearchPhase, @Nullable Phase<Solution_> refinementPhase,
-            double inheritanceRage, boolean applyBestFitFirstPhase) {
-        super(localSearchPhase, refinementPhase, inheritanceRage);
+            double inheritanceRage, boolean applyBestFitFirstPhase, RandomGenerator randomGenerator) {
+        super(localSearchPhase, refinementPhase, inheritanceRage, randomGenerator);
         this.applyBestFitFirstPhase = applyBestFitFirstPhase;
     }
 
@@ -64,8 +64,8 @@ public CrossoverResult<Solution_, Score_> apply(CrossoverContext<Solution_, Scor
             // The offspring is expected to inherit approximately 90% of their planning values from the first parent.
             // Some experiments have demonstrated that this approach is more effective in overconstrained models.
             generateOffspring(scoreDirector, listVariableStateSupply, listVariableDescriptor, listVariableMetaModel,
-                    valueRangeManager, context.firstIndividual(), context.secondIndividual(), phaseScope.getWorkingRandom(),
-                    inheritanceRate, applyBestFitFirstPhase);
+                    valueRangeManager, context.firstIndividual(), context.secondIndividual(), workingRandom, inheritanceRate,
+                    applyBestFitFirstPhase);
             // We need to update the best solution, best score,
             // and initialized score to avoid inconsistencies in the next phases
             updateScope(phaseScope);

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/decider/HybridGeneticSearchDecider.java

@@ -11,6 +11,7 @@
 import ai.timefold.solver.core.impl.evolutionaryalgorithm.common.state.SolutionState;
 import ai.timefold.solver.core.impl.evolutionaryalgorithm.population.DefaultPopulation;
 import ai.timefold.solver.core.impl.evolutionaryalgorithm.population.Population;
+import ai.timefold.solver.core.impl.solver.random.DelegatingSplittableRandomGenerator;
 
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -144,7 +145,8 @@ public void phaseStarted(EvolutionaryAlgorithmPhaseScope<Solution_> phaseScope)
             exploratoryRate = scaleLog < 427.0 ? 0.9 : 0.1;
         }
         this.worker = new HybridGeneticSearchWorker<>(HybridGeneticSearchWorkerContext.of(exploratoryRate, context),
-                bestSolutionUpdater, workerSolverScope.getWorkingRandom(), workerSolverScope);
+                bestSolutionUpdater, (DelegatingSplittableRandomGenerator) workerSolverScope.getWorkingRandom(),
+                workerSolverScope);
         this.worker.phaseStarted(phaseScope);
     }
 

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/decider/HybridGeneticSearchWorker.java

@@ -17,6 +17,7 @@
 import ai.timefold.solver.core.impl.evolutionaryalgorithm.population.individual.generator.ConstructionIndividualStrategy;
 import ai.timefold.solver.core.impl.phase.Phase;
 import ai.timefold.solver.core.impl.phase.scope.AbstractPhaseScope;
+import ai.timefold.solver.core.impl.solver.random.DelegatingSplittableRandomGenerator;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
 
 import org.jspecify.annotations.NullMarked;
@@ -45,18 +46,18 @@ public class HybridGeneticSearchWorker<Solution_, Score_ extends Score<Score_>,
 
     private final HybridGeneticSearchWorkerContext<Solution_, Score_, State_> context;
     private final BestSolutionUpdater<Solution_> bestSolutionUpdater;
-    private final RandomGenerator workingRandom;
+    private final RandomGenerator workerRandom;
     private final SolverScope<Solution_> ownSolverScope;
 
     @Nullable
     private State_ initialState;
 
     public HybridGeneticSearchWorker(HybridGeneticSearchWorkerContext<Solution_, Score_, State_> context,
-            BestSolutionUpdater<Solution_> bestSolutionUpdater, RandomGenerator workingRandom,
+            BestSolutionUpdater<Solution_> bestSolutionUpdater, DelegatingSplittableRandomGenerator workingRandom,
             SolverScope<Solution_> ownSolverScope) {
         this.context = context;
         this.bestSolutionUpdater = bestSolutionUpdater;
-        this.workingRandom = workingRandom;
+        this.workerRandom = workingRandom.split();
         this.ownSolverScope = ownSolverScope;
     }
 
@@ -84,8 +85,7 @@ public void generateIndividual(EvolutionaryAlgorithmPhaseScope<Solution_> shared
         var newIndividual = constructionStrategy.apply(stepScope);
         var addIndividual = true;
         var oldScore = newIndividual.getScore();
-        if (!newIndividual.getScore().raw().isFeasible()
-                && restoredPhaseScope.getSolverScope().getWorkingRandom().nextBoolean()) {
+        if (!newIndividual.getScore().raw().isFeasible() && workerRandom.nextBoolean()) {
             var clonedIndividual = newIndividual.clone(ownSolverScope.getScoreDirector());
             individualConsumer.accept(clonedIndividual);
             applyPhases(restoredPhaseScope, constructionStrategy.getLocalSearchPhase(),
@@ -124,8 +124,7 @@ public void applyCrossover(EvolutionaryAlgorithmStepScope<Solution_> sharedStepS
                 offspringResult.firstParentScore(), offspringResult.secondParentScore(), ownSolverScope.getScoreDirector());
         var addIndividual = true;
         var oldScore = offspringIndividual.getScore();
-        if (!offspringIndividual.getScore().raw().isFeasible()
-                && restoredPhaseScope.getSolverScope().getWorkingRandom().nextBoolean()) {
+        if (!offspringIndividual.getScore().raw().isFeasible() && workerRandom.nextBoolean()) {
             individualConsumer.accept(offspringIndividual.clone(ownSolverScope.getScoreDirector()));
             applyPhases(restoredPhaseScope, crossoverStrategy.getLocalSearchPhase(), crossoverStrategy.getRefinementPhase());
             if (restoredPhaseScope.<Score_> getBestScore().compareTo(oldScore) == 0) {
@@ -287,25 +286,21 @@ public static <Solution_> void applyPhases(AbstractPhaseScope<Solution_> phaseSc
     }
 
     private ConstructionIndividualStrategy<Solution_, Score_> pickConstructionIndividualStrategy() {
-        if (workingRandom.nextDouble(1) < context.exploratoryRate()) {
+        if (workerRandom.nextDouble(1) < context.exploratoryRate()) {
             return context.exploratoryConstructionIndividualStrategy();
         } else {
             return context.conservativeConstructionIndividualStrategy();
         }
     }
 
     private CrossoverStrategy<Solution_, Score_> pickCrossoverStrategy() {
-        if (workingRandom.nextDouble(1) < context.exploratoryRate()) {
+        if (workerRandom.nextDouble(1) < context.exploratoryRate()) {
             return context.exploratoryCrossoverStrategy();
         } else {
             return context.conservativeCrossoverStrategy();
         }
     }
 
-    protected RandomGenerator getWorkingRandom() {
-        return workingRandom;
-    }
-
     // ************************************************************************
     // Lifecycle methods
     // ************************************************************************

core/src/main/java/ai/timefold/solver/core/impl/evolutionaryalgorithm/population/AbstractPopulation.java

@@ -289,31 +289,25 @@ private double averageDiff(Individual<Solution_, Score_> individual, int size) {
         if (otherIndividualsCount == 0) {
             return 0.0;
         }
+        // Load and sort the diffs for deterministic floating-point summation
+        var diffs = new double[otherIndividualsCount];
+        var i = 0;
+        for (var diff : individualDiffMap.values()) {
+            diffs[i++] = diff;
+        }
+        Arrays.sort(diffs);
         // Hot path for a size of one
         if (size == 1) {
-            var min = Double.MAX_VALUE;
-            for (var diff : individualDiffMap.values()) {
-                if (diff < min) {
-                    min = diff;
-                }
-            }
-            return min;
+            return diffs[0];
         }
-        // All other individuals fit within the limit, so we can calculate the average without sorting
         if (otherIndividualsCount <= size) {
             var result = 0.d;
-            for (var diff : individualDiffMap.values()) {
+            for (var diff : diffs) {
                 result += diff;
             }
             return result / (double) otherIndividualsCount;
         }
-        // Sort the individuals ascending and compute only k nearst ones
-        var diffs = new double[otherIndividualsCount];
-        var i = 0;
-        for (var diff : individualDiffMap.values()) {
-            diffs[i++] = diff;
-        }
-        Arrays.sort(diffs);
+        // Compute only k nearest ones
         var result = 0.d;
         for (var j = 0; j < size; j++) {
             result += diffs[j];