GPUEAConfiguration.java

package net.bmahe.genetics4j.gpu.spec;

import java.util.Arrays;

import org.immutables.value.Value;

import net.bmahe.genetics4j.core.spec.AbstractEAConfiguration;
import net.bmahe.genetics4j.core.spec.chromosome.ChromosomeSpec;
import net.bmahe.genetics4j.core.spec.mutation.MutationPolicy;
import net.bmahe.genetics4j.gpu.spec.fitness.OpenCLFitness;

/**
 * GPU-specific evolutionary algorithm configuration that extends the core EA framework with OpenCL capabilities.
 * 
 * <p>GPUEAConfiguration extends {@link AbstractEAConfiguration} to include GPU-specific settings required
 * for OpenCL-based fitness evaluation. This configuration combines traditional EA parameters (selection,
 * mutation, crossover) with GPU-specific components like OpenCL programs and specialized fitness functions.
 * 
 * <p>Key GPU-specific additions:
 * <ul>
 * <li><strong>OpenCL Program</strong>: Specifies kernel source code, build options, and compilation settings</li>
 * <li><strong>GPU Fitness Function</strong>: Specialized fitness implementation that leverages OpenCL execution</li>
 * <li><strong>Kernel Integration</strong>: Automatic coordination between EA framework and OpenCL kernels</li>
 * </ul>
 * 
 * <p>Configuration workflow:
 * <ol>
 * <li><strong>Core EA setup</strong>: Define chromosome specs, selection policies, mutation rates</li>
 * <li><strong>OpenCL program</strong>: Specify kernel source code and compilation options</li>
 * <li><strong>GPU fitness</strong>: Implement fitness evaluation using OpenCL primitives</li>
 * <li><strong>Integration</strong>: Combine components into complete GPU-accelerated EA system</li>
 * </ol>
 * 
 * <p>Example configuration:
 * <pre>{@code
 * // Define OpenCL program with kernel source
 * Program optimizationKernels = Program.ofResource("/kernels/tsp_fitness.cl")
 *     .withBuildOption("-DCITY_COUNT=100")
 *     .withBuildOption("-DLOCAL_SIZE=256");
 * 
 * // Create GPU-specific fitness function
 * OpenCLFitness<Double> gpuFitness = new TSPGPUFitness();
 * 
 * // Build complete GPU EA configuration
 * GPUEAConfiguration<Double> config = GPUEAConfiguration.<Double>builder()
 *     // Core EA components
 *     .chromosomeSpecs(intPermutationSpec)
 *     .parentSelectionPolicy(Tournament.of(3))
 *     .combinationPolicy(OrderCrossover.build())
 *     .mutationPolicies(SwapMutation.of(0.1))
 *     .replacementStrategy(Elitism.builder().offspringRatio(0.8).build())
 *     
 *     // GPU-specific components
 *     .program(optimizationKernels)
 *     .fitness(gpuFitness)
 *     .build();
 * }</pre>
 * 
 * <p>OpenCL integration benefits:
 * <ul>
 * <li><strong>Performance</strong>: Massive parallelism for fitness evaluation</li>
 * <li><strong>Scalability</strong>: Handle large populations efficiently</li>
 * <li><strong>Hardware utilization</strong>: Leverage GPU compute units</li>
 * <li><strong>Memory bandwidth</strong>: High-throughput data processing</li>
 * </ul>
 * 
 * <p>Configuration validation:
 * <ul>
 * <li><strong>Program completeness</strong>: Ensures all required kernels are specified</li>
 * <li><strong>Fitness compatibility</strong>: Validates fitness function matches program interface</li>
 * <li><strong>Resource requirements</strong>: Checks memory and compute requirements are feasible</li>
 * </ul>
 * 
 * <p>Builder pattern usage:
 * <ul>
 * <li><strong>Type safety</strong>: Generic builder ensures fitness type consistency</li>
 * <li><strong>Validation</strong>: Build-time validation of configuration completeness</li>
 * <li><strong>Convenience methods</strong>: Simplified specification of chromosome and mutation arrays</li>
 * <li><strong>Immutability</strong>: Thread-safe configuration objects</li>
 * </ul>
 * 
 * @param <T> the type of fitness values produced by the GPU fitness function
 * @see AbstractEAConfiguration
 * @see Program
 * @see OpenCLFitness
 * @see net.bmahe.genetics4j.gpu.GPUEASystemFactory
 */
@Value.Immutable
public abstract class GPUEAConfiguration<T extends Comparable<T>> extends AbstractEAConfiguration<T> {

	/**
	 * Returns the OpenCL program specification containing kernel source code and build options.
	 * 
	 * <p>The program defines the OpenCL kernels that will be compiled and executed on GPU devices
	 * for fitness evaluation. This includes source code, build flags, and kernel definitions
	 * required for the evolutionary algorithm execution.
	 * 
	 * @return the OpenCL program specification for kernel compilation
	 */
	public abstract Program program();

	/**
	 * Returns the GPU-specific fitness function that implements evaluation using OpenCL.
	 * 
	 * <p>The fitness function encapsulates the logic for evaluating individual solutions
	 * using GPU acceleration. It coordinates data transfer, kernel execution, and result
	 * extraction for efficient parallel fitness computation.
	 * 
	 * @return the OpenCL fitness function for GPU-accelerated evaluation
	 */
	public abstract OpenCLFitness<T> fitness();

	public static class Builder<T extends Comparable<T>> extends ImmutableGPUEAConfiguration.Builder<T> {

		public final GPUEAConfiguration.Builder<T> chromosomeSpecs(final ChromosomeSpec... elements) {
			return this.chromosomeSpecs(Arrays.asList(elements));
		}

		public final GPUEAConfiguration.Builder<T> mutationPolicies(final MutationPolicy... elements) {
			return this.mutationPolicies(Arrays.asList(elements));
		}
	}

	/**
	 * Creates a new builder for constructing GPU EA configurations.
	 * 
	 * <p>The builder provides a fluent interface for specifying both core EA components
	 * and GPU-specific settings. Type safety is ensured through generic parameterization.
	 * 
	 * @param <U> the type of fitness values for the EA configuration
	 * @return a new builder instance for creating GPU EA configurations
	 */
	public static <U extends Comparable<U>> Builder<U> builder() {
		return new Builder<>();
	}
}