1 package net.bmahe.genetics4j.gpu.spec;
2
3 import java.util.function.Predicate;
4
5 import org.immutables.value.Value;
6
7 import net.bmahe.genetics4j.core.spec.AbstractEAExecutionContext;
8 import net.bmahe.genetics4j.gpu.opencl.model.Device;
9 import net.bmahe.genetics4j.gpu.opencl.model.Platform;
10
11 /**
12 * GPU-specific execution context that extends the core EA framework with OpenCL device selection capabilities.
13 *
14 * <p>GPUEAExecutionContext extends {@link AbstractEAExecutionContext} to include GPU-specific execution parameters
15 * required for OpenCL device discovery and selection. This context combines traditional EA execution settings
16 * (population size, termination criteria) with GPU-specific device filtering capabilities.
17 *
18 * <p>Key GPU-specific additions:
19 * <ul>
20 * <li><strong>Platform filtering</strong>: Predicates for selecting appropriate OpenCL platforms</li>
21 * <li><strong>Device filtering</strong>: Predicates for selecting compatible OpenCL devices</li>
22 * <li><strong>Multi-device support</strong>: Automatic discovery and utilization of multiple GPU devices</li>
23 * <li><strong>Hardware abstraction</strong>: Device-agnostic configuration with runtime device selection</li>
24 * </ul>
25 *
26 * <p>Device selection workflow:
27 * <ol>
28 * <li><strong>Platform discovery</strong>: Enumerate all available OpenCL platforms</li>
29 * <li><strong>Platform filtering</strong>: Apply platform predicates to select compatible platforms</li>
30 * <li><strong>Device enumeration</strong>: Discover devices for each selected platform</li>
31 * <li><strong>Device filtering</strong>: Apply device predicates to select suitable devices</li>
32 * <li><strong>Context creation</strong>: Create OpenCL contexts for selected devices</li>
33 * </ol>
34 *
35 * <p>Common filtering patterns:
36 *
37 * <pre>{@code
38 * // Select only GPU devices with sufficient memory
39 * GPUEAExecutionContext<Double> context = GPUEAExecutionContext.<Double>builder()
40 * .populationSize(2000)
41 * .termination(Generations.of(100))
42 *
43 * // Platform filtering - prefer full OpenCL profiles
44 * .platformFilter(platform -> platform.profile() == PlatformProfile.FULL_PROFILE)
45 *
46 * // Device filtering - GPU devices with at least 2GB memory
47 * .deviceFilter(device -> device.type() == DeviceType.GPU && device.globalMemSize() >= 2L * 1024 * 1024 * 1024)
48 *
49 * .build();
50 *
51 * // Select any available compute device (GPUs or CPUs)
52 * GPUEAExecutionContext<Double> flexibleContext = GPUEAExecutionContext.<Double>builder()
53 * .populationSize(1000)
54 * .termination(FitnessTarget.of(0.95))
55 *
56 * // Accept any platform
57 * .platformFilter(platform -> true)
58 *
59 * // Prefer GPUs but accept CPUs as fallback
60 * .deviceFilter(device -> device.type() == DeviceType.GPU || device.type() == DeviceType.CPU)
61 *
62 * .build();
63 * }</pre>
64 *
65 * <p>Performance optimization through device selection:
66 * <ul>
67 * <li><strong>Compute capability</strong>: Filter devices by OpenCL version and feature support</li>
68 * <li><strong>Memory capacity</strong>: Ensure devices have sufficient memory for population size</li>
69 * <li><strong>Compute units</strong>: Prefer devices with more parallel processing units</li>
70 * <li><strong>Memory bandwidth</strong>: Select devices optimized for data-intensive operations</li>
71 * </ul>
72 *
73 * <p>Multi-device strategies:
74 * <ul>
75 * <li><strong>Load balancing</strong>: Automatic population distribution across selected devices</li>
76 * <li><strong>Heterogeneous computing</strong>: Utilize both GPU and CPU devices simultaneously</li>
77 * <li><strong>Fault tolerance</strong>: Graceful degradation when devices become unavailable</li>
78 * <li><strong>Resource optimization</strong>: Efficient utilization of available compute resources</li>
79 * </ul>
80 *
81 * <p>Default behavior:
82 * <ul>
83 * <li><strong>Platform acceptance</strong>: All platforms accepted by default</li>
84 * <li><strong>Device acceptance</strong>: All devices accepted by default</li>
85 * <li><strong>Discovery process</strong>: Automatic enumeration of available hardware</li>
86 * <li><strong>Validation</strong>: Runtime validation ensures at least one device is selected</li>
87 * </ul>
88 *
89 * @param <T> the type of fitness values used in the evolutionary algorithm
90 * @see AbstractEAExecutionContext
91 * @see Platform
92 * @see Device
93 * @see net.bmahe.genetics4j.gpu.GPUFitnessEvaluator
94 */
95 @Value.Immutable
96 public abstract class GPUEAExecutionContext<T extends Comparable<T>> extends AbstractEAExecutionContext<T> {
97
98 /**
99 * Returns the predicate used to filter OpenCL platforms during device discovery.
100 *
101 * <p>Platform filtering allows selective use of OpenCL platforms based on vendor, version, profile, or other
102 * platform characteristics. This enables optimization for specific hardware configurations or requirements.
103 *
104 * <p>Common filtering criteria:
105 * <ul>
106 * <li><strong>Profile support</strong>: Filter by FULL_PROFILE vs EMBEDDED_PROFILE</li>
107 * <li><strong>Vendor preference</strong>: Select platforms from specific vendors</li>
108 * <li><strong>Version requirements</strong>: Ensure minimum OpenCL version support</li>
109 * <li><strong>Extension support</strong>: Filter platforms with required extensions</li>
110 * </ul>
111 *
112 * @return the platform filtering predicate (default accepts all platforms)
113 */
114 @Value.Default
115 public Predicate<Platform> platformFilters() {
116 return platform -> true;
117 }
118
119 /**
120 * Returns the predicate used to filter OpenCL devices during device discovery.
121 *
122 * <p>Device filtering enables selection of appropriate compute devices based on type, capabilities, memory, and
123 * performance characteristics. This allows optimization for specific workload requirements and hardware constraints.
124 *
125 * <p>Common filtering criteria:
126 * <ul>
127 * <li><strong>Device type</strong>: GPU, CPU, ACCELERATOR, or combinations</li>
128 * <li><strong>Memory capacity</strong>: Minimum global or local memory requirements</li>
129 * <li><strong>Compute units</strong>: Minimum parallel processing capability</li>
130 * <li><strong>OpenCL version</strong>: Required feature support level</li>
131 * <li><strong>Extensions</strong>: Specific OpenCL extension requirements</li>
132 * </ul>
133 *
134 * @return the device filtering predicate (default accepts all devices)
135 */
136 @Value.Default
137 public Predicate<Device> deviceFilters() {
138 return device -> true;
139 }
140
141 /**
142 * Creates a new builder for constructing GPU EA execution contexts.
143 *
144 * <p>The builder provides a fluent interface for specifying both core EA execution parameters and GPU-specific
145 * device selection criteria. Type safety is ensured through generic parameterization.
146 *
147 * @param <U> the type of fitness values for the execution context
148 * @return a new builder instance for creating GPU EA execution contexts
149 */
150 public static <U extends Comparable<U>> ImmutableGPUEAExecutionContext.Builder<U> builder() {
151 return ImmutableGPUEAExecutionContext.builder();
152 }
153 }