GPUEASystemFactory.java

package net.bmahe.genetics4j.gpu;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.ForkJoinPool;

import net.bmahe.genetics4j.core.EASystem;
import net.bmahe.genetics4j.core.EASystemFactory;
import net.bmahe.genetics4j.gpu.spec.GPUEAConfiguration;
import net.bmahe.genetics4j.gpu.spec.GPUEAExecutionContext;

/**
 * Factory class for creating GPU-accelerated evolutionary algorithm systems
 * using OpenCL.
 * 
 * <p>
 * GPUEASystemFactory provides convenient factory methods for creating
 * {@link EASystem} instances
 * that leverage GPU acceleration through OpenCL for fitness evaluation. This
 * factory extends the
 * capabilities of the core EA framework to support high-performance computing
 * on graphics processors
 * and other OpenCL-compatible devices.
 * 
 * <p>
 * The factory handles the integration between GPU-specific configurations and
 * the core EA framework:
 * <ul>
 * <li><strong>GPU Configuration</strong>: Uses {@link GPUEAConfiguration} with
 * OpenCL program specifications</li>
 * <li><strong>Device Selection</strong>: Leverages
 * {@link GPUEAExecutionContext} for platform and device filtering</li>
 * <li><strong>GPU Evaluator</strong>: Creates specialized
 * {@link GPUFitnessEvaluator} for OpenCL fitness computation</li>
 * <li><strong>Resource Management</strong>: Coordinates executor services with
 * OpenCL resource lifecycle</li>
 * </ul>
 * 
 * <p>
 * GPU acceleration benefits:
 * <ul>
 * <li><strong>Massive parallelism</strong>: Evaluate hundreds or thousands of
 * individuals simultaneously</li>
 * <li><strong>Memory bandwidth</strong>: High-throughput data processing for
 * population-based algorithms</li>
 * <li><strong>Specialized hardware</strong>: Leverage dedicated compute units
 * optimized for parallel operations</li>
 * <li><strong>Energy efficiency</strong>: Often better performance-per-watt
 * compared to CPU-only execution</li>
 * </ul>
 * 
 * <p>
 * Common usage patterns:
 * 
 * <pre>{@code
 * // Define OpenCL kernel for fitness evaluation
 * Program fitnessProgram = Program.ofResource("/kernels/fitness.cl")
 * 		.withBuildOption("-DPROBLEM_SIZE=256");
 * 
 * // Configure GPU-specific EA settings
 * GPUEAConfiguration<Double> gpuConfig = GPUEAConfigurationBuilder.<Double>builder()
 * 		.chromosomeSpecs(chromosomeSpec)
 * 		.parentSelectionPolicy(Tournament.of(3))
 * 		.combinationPolicy(SinglePointCrossover.build())
 * 		.mutationPolicies(List.of(RandomMutation.of(0.1)))
 * 		.replacementStrategy(Elitism.builder()
 * 				.offspringRatio(0.8)
 * 				.build())
 * 		.program(fitnessProgram)
 * 		.fitness(myGPUFitness)
 * 		.build();
 * 
 * // Configure execution context with device preferences
 * GPUEAExecutionContext<Double> gpuContext = GPUEAExecutionContextBuilder.<Double>builder()
 * 		.populationSize(1000)
 * 		.termination(Generations.of(100))
 * 		.platformFilter(platform -> platform.profile() == PlatformProfile.FULL_PROFILE)
 * 		.deviceFilter(device -> device.type() == DeviceType.GPU)
 * 		.build();
 * 
 * // Create GPU-accelerated EA system
 * EASystem<Double> gpuSystem = GPUEASystemFactory.from(gpuConfig, gpuContext);
 * 
 * // Run evolution on GPU
 * EvolutionResult<Double> result = gpuSystem.evolve();
 * }</pre>
 * 
 * <p>
 * OpenCL integration considerations:
 * <ul>
 * <li><strong>Device compatibility</strong>: Ensure target devices support
 * required OpenCL features</li>
 * <li><strong>Memory management</strong>: GPU memory is typically limited
 * compared to system RAM</li>
 * <li><strong>Kernel optimization</strong>: GPU performance depends heavily on
 * kernel implementation</li>
 * <li><strong>Transfer overhead</strong>: Consider data transfer costs between
 * CPU and GPU memory</li>
 * </ul>
 * 
 * <p>
 * Performance optimization tips:
 * <ul>
 * <li><strong>Large populations</strong>: GPU acceleration benefits increase
 * with population size</li>
 * <li><strong>Complex fitness functions</strong>: More computation per
 * individual improves GPU utilization</li>
 * <li><strong>Minimize transfers</strong>: Keep data on GPU between generations
 * when possible</li>
 * <li><strong>Coalesced memory access</strong>: Design kernels for optimal
 * memory access patterns</li>
 * </ul>
 * 
 * @see GPUEAConfiguration
 * @see GPUEAExecutionContext
 * @see GPUFitnessEvaluator
 * @see net.bmahe.genetics4j.core.EASystemFactory
 * @see net.bmahe.genetics4j.gpu.opencl.model.Program
 */
public class GPUEASystemFactory {

	private GPUEASystemFactory() {
	}

	/**
	 * Creates a GPU-accelerated EA system with explicit thread pool management.
	 * 
	 * <p>
	 * This method provides full control over thread pool management while enabling
	 * GPU acceleration
	 * for fitness evaluation. The provided executor service is used for
	 * coordinating between CPU
	 * and GPU operations, managing asynchronous OpenCL operations, and handling
	 * concurrent access
	 * to OpenCL resources.
	 * 
	 * <p>
	 * The factory method performs the following operations:
	 * <ol>
	 * <li>Creates a specialized {@link GPUFitnessEvaluator} configured for OpenCL
	 * execution</li>
	 * <li>Integrates the GPU evaluator with the core EA framework</li>
	 * <li>Ensures proper resource management and cleanup for OpenCL contexts</li>
	 * </ol>
	 * 
	 * <p>
	 * Use this method when:
	 * <ul>
	 * <li>You need explicit control over thread pool configuration and
	 * lifecycle</li>
	 * <li>Integration with existing thread management systems is required</li>
	 * <li>Custom executor services are needed for performance tuning</li>
	 * <li>Resource-constrained environments require careful thread pool sizing</li>
	 * </ul>
	 * 
	 * @param <T>                   the type of fitness values, must be comparable
	 *                              for selection operations
	 * @param gpuEAConfiguration    the GPU-specific EA configuration with OpenCL
	 *                              program and fitness function
	 * @param gpuEAExecutionContext the GPU execution context with device selection
	 *                              and population parameters
	 * @param executorService       the thread pool for managing CPU-GPU
	 *                              coordination (caller responsible for shutdown)
	 * @return a fully configured {@link EASystem} with GPU acceleration
	 *         capabilities
	 * @throws IllegalArgumentException if any parameter is null
	 * @throws RuntimeException         if OpenCL initialization fails or no
	 *                                  compatible devices are found
	 */
	public static <T extends Comparable<T>> EASystem<T> from(final GPUEAConfiguration<T> gpuEAConfiguration,
			final GPUEAExecutionContext<T> gpuEAExecutionContext, final ExecutorService executorService) {

		final var gpuFitnessEvaluator = new GPUFitnessEvaluator<T>(gpuEAExecutionContext,
				gpuEAConfiguration,
				executorService);
		return EASystemFactory.from(gpuEAConfiguration, gpuEAExecutionContext, gpuFitnessEvaluator);
	}

	/**
	 * Creates a GPU-accelerated EA system using the common thread pool.
	 * 
	 * <p>
	 * This convenience method provides GPU acceleration without requiring explicit
	 * thread pool
	 * management. It automatically uses {@link ForkJoinPool#commonPool()} for
	 * CPU-GPU coordination,
	 * making it ideal for applications where thread pool management is not
	 * critical.
	 * 
	 * <p>
	 * This method is recommended for:
	 * <ul>
	 * <li>Rapid prototyping and experimentation with GPU acceleration</li>
	 * <li>Applications where default thread pool behavior is sufficient</li>
	 * <li>Educational purposes and demonstration code</li>
	 * <li>Simple GPU-accelerated applications without complex threading
	 * requirements</li>
	 * </ul>
	 * 
	 * <p>
	 * The common thread pool provides automatic parallelization and reasonable
	 * default
	 * behavior for most GPU acceleration scenarios. However, for production systems
	 * with
	 * specific performance requirements, consider using
	 * {@link #from(GPUEAConfiguration, GPUEAExecutionContext, ExecutorService)}
	 * with a custom thread pool.
	 * 
	 * @param <T>                   the type of fitness values, must be comparable
	 *                              for selection operations
	 * @param gpuEAConfiguration    the GPU-specific EA configuration with OpenCL
	 *                              program and fitness function
	 * @param gpuEAExecutionContext the GPU execution context with device selection
	 *                              and population parameters
	 * @return a fully configured {@link EASystem} with GPU acceleration using the
	 *         common thread pool
	 * @throws IllegalArgumentException if any parameter is null
	 * @throws RuntimeException         if OpenCL initialization fails or no
	 *                                  compatible devices are found
	 */
	public static <T extends Comparable<T>> EASystem<T> from(final GPUEAConfiguration<T> gpuEAConfiguration,
			final GPUEAExecutionContext<T> gpuEAExecutionContext) {
		final ExecutorService executorService = ForkJoinPool.commonPool();

		return from(gpuEAConfiguration, gpuEAExecutionContext, executorService);
	}
}






Active mutators

CONDITIONALS_BOUNDARY
CONSTRUCTOR_CALLS
EMPTY_RETURNS
EXPERIMENTAL_ARGUMENT_PROPAGATION
EXPERIMENTAL_BIG_DECIMAL
EXPERIMENTAL_BIG_INTEGER
EXPERIMENTAL_MEMBER_VARIABLE
EXPERIMENTAL_NAKED_RECEIVER
EXPERIMENTAL_REMOVE_SWITCH_MUTATOR_[0-99]
EXPERIMENTAL_SWITCH
FALSE_RETURNS
INCREMENTS
INLINE_CONSTS
INVERT_NEGS
MATH
NEGATE_CONDITIONALS
NON_VOID_METHOD_CALLS
NULL_RETURNS
PRIMITIVE_RETURNS
REMOVE_CONDITIONALS_EQUAL_ELSE
REMOVE_CONDITIONALS_EQUAL_IF
REMOVE_CONDITIONALS_ORDER_ELSE
REMOVE_CONDITIONALS_ORDER_IF
REMOVE_INCREMENTS
TRUE_RETURNS
VOID_METHOD_CALLS

Tests examined

Report generated by PIT 1.20.2

1		package net.bmahe.genetics4j.gpu;
2
3		import java.util.concurrent.ExecutorService;
4		import java.util.concurrent.ForkJoinPool;
5
6		import net.bmahe.genetics4j.core.EASystem;
7		import net.bmahe.genetics4j.core.EASystemFactory;
8		import net.bmahe.genetics4j.gpu.spec.GPUEAConfiguration;
9		import net.bmahe.genetics4j.gpu.spec.GPUEAExecutionContext;
10
11		/**
12		* Factory class for creating GPU-accelerated evolutionary algorithm systems
13		* using OpenCL.
14		*
15		* <p>
16		* GPUEASystemFactory provides convenient factory methods for creating
17		* {@link EASystem} instances
18		* that leverage GPU acceleration through OpenCL for fitness evaluation. This
19		* factory extends the
20		* capabilities of the core EA framework to support high-performance computing
21		* on graphics processors
22		* and other OpenCL-compatible devices.
23		*
24		* <p>
25		* The factory handles the integration between GPU-specific configurations and
26		* the core EA framework:
27		* <ul>
28		* <li><strong>GPU Configuration</strong>: Uses {@link GPUEAConfiguration} with
29		* OpenCL program specifications</li>
30		* <li><strong>Device Selection</strong>: Leverages
31		* {@link GPUEAExecutionContext} for platform and device filtering</li>
32		* <li><strong>GPU Evaluator</strong>: Creates specialized
33		* {@link GPUFitnessEvaluator} for OpenCL fitness computation</li>
34		* <li><strong>Resource Management</strong>: Coordinates executor services with
35		* OpenCL resource lifecycle</li>
36		* </ul>
37		*
38		* <p>
39		* GPU acceleration benefits:
40		* <ul>
41		* <li><strong>Massive parallelism</strong>: Evaluate hundreds or thousands of
42		* individuals simultaneously</li>
43		* <li><strong>Memory bandwidth</strong>: High-throughput data processing for
44		* population-based algorithms</li>
45		* <li><strong>Specialized hardware</strong>: Leverage dedicated compute units
46		* optimized for parallel operations</li>
47		* <li><strong>Energy efficiency</strong>: Often better performance-per-watt
48		* compared to CPU-only execution</li>
49		* </ul>
50		*
51		* <p>
52		* Common usage patterns:
53		*
54		* <pre>{@code
55		* // Define OpenCL kernel for fitness evaluation
56		* Program fitnessProgram = Program.ofResource("/kernels/fitness.cl")
57		* .withBuildOption("-DPROBLEM_SIZE=256");
58		*
59		* // Configure GPU-specific EA settings
60		* GPUEAConfiguration<Double> gpuConfig = GPUEAConfigurationBuilder.<Double>builder()
61		* .chromosomeSpecs(chromosomeSpec)
62		* .parentSelectionPolicy(Tournament.of(3))
63		* .combinationPolicy(SinglePointCrossover.build())
64		* .mutationPolicies(List.of(RandomMutation.of(0.1)))
65		* .replacementStrategy(Elitism.builder()
66		* .offspringRatio(0.8)
67		* .build())
68		* .program(fitnessProgram)
69		* .fitness(myGPUFitness)
70		* .build();
71		*
72		* // Configure execution context with device preferences
73		* GPUEAExecutionContext<Double> gpuContext = GPUEAExecutionContextBuilder.<Double>builder()
74		* .populationSize(1000)
75		* .termination(Generations.of(100))
76		* .platformFilter(platform -> platform.profile() == PlatformProfile.FULL_PROFILE)
77		* .deviceFilter(device -> device.type() == DeviceType.GPU)
78		* .build();
79		*
80		* // Create GPU-accelerated EA system
81		* EASystem<Double> gpuSystem = GPUEASystemFactory.from(gpuConfig, gpuContext);
82		*
83		* // Run evolution on GPU
84		* EvolutionResult<Double> result = gpuSystem.evolve();
85		* }</pre>
86		*
87		* <p>
88		* OpenCL integration considerations:
89		* <ul>
90		* <li><strong>Device compatibility</strong>: Ensure target devices support
91		* required OpenCL features</li>
92		* <li><strong>Memory management</strong>: GPU memory is typically limited
93		* compared to system RAM</li>
94		* <li><strong>Kernel optimization</strong>: GPU performance depends heavily on
95		* kernel implementation</li>
96		* <li><strong>Transfer overhead</strong>: Consider data transfer costs between
97		* CPU and GPU memory</li>
98		* </ul>
99		*
100		* <p>
101		* Performance optimization tips:
102		* <ul>
103		* <li><strong>Large populations</strong>: GPU acceleration benefits increase
104		* with population size</li>
105		* <li><strong>Complex fitness functions</strong>: More computation per
106		* individual improves GPU utilization</li>
107		* <li><strong>Minimize transfers</strong>: Keep data on GPU between generations
108		* when possible</li>
109		* <li><strong>Coalesced memory access</strong>: Design kernels for optimal
110		* memory access patterns</li>
111		* </ul>
112		*
113		* @see GPUEAConfiguration
114		* @see GPUEAExecutionContext
115		* @see GPUFitnessEvaluator
116		* @see net.bmahe.genetics4j.core.EASystemFactory
117		* @see net.bmahe.genetics4j.gpu.opencl.model.Program
118		*/
119		public class GPUEASystemFactory {
120
121		private GPUEASystemFactory() {
122		}
123
124		/**
125		* Creates a GPU-accelerated EA system with explicit thread pool management.
126		*
127		* <p>
128		* This method provides full control over thread pool management while enabling
129		* GPU acceleration
130		* for fitness evaluation. The provided executor service is used for
131		* coordinating between CPU
132		* and GPU operations, managing asynchronous OpenCL operations, and handling
133		* concurrent access
134		* to OpenCL resources.
135		*
136		* <p>
137		* The factory method performs the following operations:
138		* <ol>
139		* <li>Creates a specialized {@link GPUFitnessEvaluator} configured for OpenCL
140		* execution</li>
141		* <li>Integrates the GPU evaluator with the core EA framework</li>
142		* <li>Ensures proper resource management and cleanup for OpenCL contexts</li>
143		* </ol>
144		*
145		* <p>
146		* Use this method when:
147		* <ul>
148		* <li>You need explicit control over thread pool configuration and
149		* lifecycle</li>
150		* <li>Integration with existing thread management systems is required</li>
151		* <li>Custom executor services are needed for performance tuning</li>
152		* <li>Resource-constrained environments require careful thread pool sizing</li>
153		* </ul>
154		*
155		* @param <T> the type of fitness values, must be comparable
156		* for selection operations
157		* @param gpuEAConfiguration the GPU-specific EA configuration with OpenCL
158		* program and fitness function
159		* @param gpuEAExecutionContext the GPU execution context with device selection
160		* and population parameters
161		* @param executorService the thread pool for managing CPU-GPU
162		* coordination (caller responsible for shutdown)
163		* @return a fully configured {@link EASystem} with GPU acceleration
164		* capabilities
165		* @throws IllegalArgumentException if any parameter is null
166		* @throws RuntimeException if OpenCL initialization fails or no
167		* compatible devices are found
168		*/
169		public static <T extends Comparable<T>> EASystem<T> from(final GPUEAConfiguration<T> gpuEAConfiguration,
170		final GPUEAExecutionContext<T> gpuEAExecutionContext, final ExecutorService executorService) {
171
172	1 1. from : removed call to net/bmahe/genetics4j/gpu/GPUFitnessEvaluator::<init> → NO_COVERAGE	final var gpuFitnessEvaluator = new GPUFitnessEvaluator<T>(gpuEAExecutionContext,
173		gpuEAConfiguration,
174		executorService);
175	2 1. from : removed call to net/bmahe/genetics4j/core/EASystemFactory::from → NO_COVERAGE 2. from : replaced return value with null for net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE	return EASystemFactory.from(gpuEAConfiguration, gpuEAExecutionContext, gpuFitnessEvaluator);
176		}
177
178		/**
179		* Creates a GPU-accelerated EA system using the common thread pool.
180		*
181		* <p>
182		* This convenience method provides GPU acceleration without requiring explicit
183		* thread pool
184		* management. It automatically uses {@link ForkJoinPool#commonPool()} for
185		* CPU-GPU coordination,
186		* making it ideal for applications where thread pool management is not
187		* critical.
188		*
189		* <p>
190		* This method is recommended for:
191		* <ul>
192		* <li>Rapid prototyping and experimentation with GPU acceleration</li>
193		* <li>Applications where default thread pool behavior is sufficient</li>
194		* <li>Educational purposes and demonstration code</li>
195		* <li>Simple GPU-accelerated applications without complex threading
196		* requirements</li>
197		* </ul>
198		*
199		* <p>
200		* The common thread pool provides automatic parallelization and reasonable
201		* default
202		* behavior for most GPU acceleration scenarios. However, for production systems
203		* with
204		* specific performance requirements, consider using
205		* {@link #from(GPUEAConfiguration, GPUEAExecutionContext, ExecutorService)}
206		* with a custom thread pool.
207		*
208		* @param <T> the type of fitness values, must be comparable
209		* for selection operations
210		* @param gpuEAConfiguration the GPU-specific EA configuration with OpenCL
211		* program and fitness function
212		* @param gpuEAExecutionContext the GPU execution context with device selection
213		* and population parameters
214		* @return a fully configured {@link EASystem} with GPU acceleration using the
215		* common thread pool
216		* @throws IllegalArgumentException if any parameter is null
217		* @throws RuntimeException if OpenCL initialization fails or no
218		* compatible devices are found
219		*/
220		public static <T extends Comparable<T>> EASystem<T> from(final GPUEAConfiguration<T> gpuEAConfiguration,
221		final GPUEAExecutionContext<T> gpuEAExecutionContext) {
222	1 1. from : removed call to java/util/concurrent/ForkJoinPool::commonPool → NO_COVERAGE	final ExecutorService executorService = ForkJoinPool.commonPool();
223
224	2 1. from : replaced return value with null for net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE 2. from : removed call to net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE	return from(gpuEAConfiguration, gpuEAExecutionContext, executorService);
225		}
226		}
		Mutations
172		1.1 Location : from Killed by : none removed call to net/bmahe/genetics4j/gpu/GPUFitnessEvaluator::<init> → NO_COVERAGE
175		1.1 Location : from Killed by : none removed call to net/bmahe/genetics4j/core/EASystemFactory::from → NO_COVERAGE 2.2 Location : from Killed by : none replaced return value with null for net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE
222		1.1 Location : from Killed by : none removed call to java/util/concurrent/ForkJoinPool::commonPool → NO_COVERAGE
224		1.1 Location : from Killed by : none replaced return value with null for net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE 2.2 Location : from Killed by : none removed call to net/bmahe/genetics4j/gpu/GPUEASystemFactory::from → NO_COVERAGE

GPUEASystemFactory.java

Mutations

Active mutators

Tests examined