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

	/**

	 * 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 final GPUEAConfiguration.Builder<T> chromosomeSpecs(final ChromosomeSpec... elements) {

		}

		public final GPUEAConfiguration.Builder<T> mutationPolicies(final MutationPolicy... 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() {

	}

}

Mutations