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<>();
 	}
 }