GPUEAExecutionContext.java
package net.bmahe.genetics4j.gpu.spec;
import java.util.function.Predicate;
import org.immutables.value.Value;
import net.bmahe.genetics4j.core.spec.AbstractEAExecutionContext;
import net.bmahe.genetics4j.gpu.opencl.model.Device;
import net.bmahe.genetics4j.gpu.opencl.model.Platform;
/**
* GPU-specific execution context that extends the core EA framework with OpenCL device selection capabilities.
*
* <p>GPUEAExecutionContext extends {@link AbstractEAExecutionContext} to include GPU-specific execution
* parameters required for OpenCL device discovery and selection. This context combines traditional EA
* execution settings (population size, termination criteria) with GPU-specific device filtering capabilities.
*
* <p>Key GPU-specific additions:
* <ul>
* <li><strong>Platform filtering</strong>: Predicates for selecting appropriate OpenCL platforms</li>
* <li><strong>Device filtering</strong>: Predicates for selecting compatible OpenCL devices</li>
* <li><strong>Multi-device support</strong>: Automatic discovery and utilization of multiple GPU devices</li>
* <li><strong>Hardware abstraction</strong>: Device-agnostic configuration with runtime device selection</li>
* </ul>
*
* <p>Device selection workflow:
* <ol>
* <li><strong>Platform discovery</strong>: Enumerate all available OpenCL platforms</li>
* <li><strong>Platform filtering</strong>: Apply platform predicates to select compatible platforms</li>
* <li><strong>Device enumeration</strong>: Discover devices for each selected platform</li>
* <li><strong>Device filtering</strong>: Apply device predicates to select suitable devices</li>
* <li><strong>Context creation</strong>: Create OpenCL contexts for selected devices</li>
* </ol>
*
* <p>Common filtering patterns:
* <pre>{@code
* // Select only GPU devices with sufficient memory
* GPUEAExecutionContext<Double> context = GPUEAExecutionContext.<Double>builder()
* .populationSize(2000)
* .termination(Generations.of(100))
*
* // Platform filtering - prefer full OpenCL profiles
* .platformFilter(platform -> platform.profile() == PlatformProfile.FULL_PROFILE)
*
* // Device filtering - GPU devices with at least 2GB memory
* .deviceFilter(device ->
* device.type() == DeviceType.GPU &&
* device.globalMemSize() >= 2L * 1024 * 1024 * 1024)
*
* .build();
*
* // Select any available compute device (GPUs or CPUs)
* GPUEAExecutionContext<Double> flexibleContext = GPUEAExecutionContext.<Double>builder()
* .populationSize(1000)
* .termination(FitnessTarget.of(0.95))
*
* // Accept any platform
* .platformFilter(platform -> true)
*
* // Prefer GPUs but accept CPUs as fallback
* .deviceFilter(device ->
* device.type() == DeviceType.GPU ||
* device.type() == DeviceType.CPU)
*
* .build();
* }</pre>
*
* <p>Performance optimization through device selection:
* <ul>
* <li><strong>Compute capability</strong>: Filter devices by OpenCL version and feature support</li>
* <li><strong>Memory capacity</strong>: Ensure devices have sufficient memory for population size</li>
* <li><strong>Compute units</strong>: Prefer devices with more parallel processing units</li>
* <li><strong>Memory bandwidth</strong>: Select devices optimized for data-intensive operations</li>
* </ul>
*
* <p>Multi-device strategies:
* <ul>
* <li><strong>Load balancing</strong>: Automatic population distribution across selected devices</li>
* <li><strong>Heterogeneous computing</strong>: Utilize both GPU and CPU devices simultaneously</li>
* <li><strong>Fault tolerance</strong>: Graceful degradation when devices become unavailable</li>
* <li><strong>Resource optimization</strong>: Efficient utilization of available compute resources</li>
* </ul>
*
* <p>Default behavior:
* <ul>
* <li><strong>Platform acceptance</strong>: All platforms accepted by default</li>
* <li><strong>Device acceptance</strong>: All devices accepted by default</li>
* <li><strong>Discovery process</strong>: Automatic enumeration of available hardware</li>
* <li><strong>Validation</strong>: Runtime validation ensures at least one device is selected</li>
* </ul>
*
* @param <T> the type of fitness values used in the evolutionary algorithm
* @see AbstractEAExecutionContext
* @see Platform
* @see Device
* @see net.bmahe.genetics4j.gpu.GPUFitnessEvaluator
*/
@Value.Immutable
public abstract class GPUEAExecutionContext<T extends Comparable<T>> extends AbstractEAExecutionContext<T> {
/**
* Returns the predicate used to filter OpenCL platforms during device discovery.
*
* <p>Platform filtering allows selective use of OpenCL platforms based on vendor,
* version, profile, or other platform characteristics. This enables optimization
* for specific hardware configurations or requirements.
*
* <p>Common filtering criteria:
* <ul>
* <li><strong>Profile support</strong>: Filter by FULL_PROFILE vs EMBEDDED_PROFILE</li>
* <li><strong>Vendor preference</strong>: Select platforms from specific vendors</li>
* <li><strong>Version requirements</strong>: Ensure minimum OpenCL version support</li>
* <li><strong>Extension support</strong>: Filter platforms with required extensions</li>
* </ul>
*
* @return the platform filtering predicate (default accepts all platforms)
*/
@Value.Default
public Predicate<Platform> platformFilters() {
return (platform) -> true;
}
/**
* Returns the predicate used to filter OpenCL devices during device discovery.
*
* <p>Device filtering enables selection of appropriate compute devices based on
* type, capabilities, memory, and performance characteristics. This allows
* optimization for specific workload requirements and hardware constraints.
*
* <p>Common filtering criteria:
* <ul>
* <li><strong>Device type</strong>: GPU, CPU, ACCELERATOR, or combinations</li>
* <li><strong>Memory capacity</strong>: Minimum global or local memory requirements</li>
* <li><strong>Compute units</strong>: Minimum parallel processing capability</li>
* <li><strong>OpenCL version</strong>: Required feature support level</li>
* <li><strong>Extensions</strong>: Specific OpenCL extension requirements</li>
* </ul>
*
* @return the device filtering predicate (default accepts all devices)
*/
@Value.Default
public Predicate<Device> deviceFilters() {
return (device) -> true;
}
/**
* Creates a new builder for constructing GPU EA execution contexts.
*
* <p>The builder provides a fluent interface for specifying both core EA execution
* parameters and GPU-specific device selection criteria. Type safety is ensured
* through generic parameterization.
*
* @param <U> the type of fitness values for the execution context
* @return a new builder instance for creating GPU EA execution contexts
*/
public static <U extends Comparable<U>> ImmutableGPUEAExecutionContext.Builder<U> builder() {
return ImmutableGPUEAExecutionContext.builder();
}
}