1 package net.bmahe.genetics4j.gpu.opencl.model;
2
3 import java.util.Set;
4
5 import org.immutables.value.Value;
6 import org.jocl.cl_platform_id;
7
8 /**
9 * Represents an OpenCL platform providing access to compute devices and their capabilities.
10 *
11 * <p>Platform encapsulates the information about an OpenCL platform, which is a vendor-specific implementation of the
12 * OpenCL specification. Each platform represents a collection of OpenCL devices (CPUs, GPUs, accelerators) provided by
13 * a single vendor with consistent runtime behavior.
14 *
15 * <p>Key platform characteristics include:
16 * <ul>
17 * <li><strong>Vendor identification</strong>: Platform vendor (AMD, NVIDIA, Intel, etc.)</li>
18 * <li><strong>Capability profile</strong>: FULL_PROFILE or EMBEDDED_PROFILE feature support</li>
19 * <li><strong>Version support</strong>: OpenCL specification version implemented</li>
20 * <li><strong>Extension support</strong>: Additional features beyond the core specification</li>
21 * <li><strong>Device count</strong>: Number of compute devices available on this platform</li>
22 * </ul>
23 *
24 * <p>Platform selection considerations:
25 * <ul>
26 * <li><strong>Vendor optimization</strong>: Different vendors may optimize for different workloads</li>
27 * <li><strong>Feature requirements</strong>: Embedded profiles may lack required features</li>
28 * <li><strong>Version compatibility</strong>: Newer OpenCL versions provide additional features</li>
29 * <li><strong>Extension dependencies</strong>: Some algorithms may require specific extensions</li>
30 * <li><strong>Device availability</strong>: Platforms must have compatible devices</li>
31 * </ul>
32 *
33 * <p>Common filtering patterns:
34 *
35 * <pre>{@code
36 * // Select platforms with full OpenCL profile support
37 * Predicate<Platform> fullProfileFilter = platform -> platform.profile() == PlatformProfile.FULL_PROFILE;
38 *
39 * // Select platforms from specific vendors
40 * Predicate<Platform> vendorFilter = platform -> platform.vendor()
41 * .toLowerCase()
42 * .contains("nvidia")
43 * || platform.vendor()
44 * .toLowerCase()
45 * .contains("amd");
46 *
47 * // Select platforms with minimum OpenCL version
48 * Predicate<Platform> versionFilter = platform -> {
49 * String version = platform.version();
50 * return version.contains("2.") || version.contains("3.");
51 * };
52 *
53 * // Select platforms with required extensions
54 * Predicate<Platform> extensionFilter = platform -> platform.extensions()
55 * .contains("cl_khr_fp64");
56 *
57 * // Combine filters for comprehensive platform selection
58 * Predicate<Platform> combinedFilter = fullProfileFilter.and(versionFilter)
59 * .and(platform -> platform.numDevices() > 0);
60 * }</pre>
61 *
62 * <p>Platform discovery workflow:
63 * <ol>
64 * <li><strong>Enumeration</strong>: System discovers all available OpenCL platforms</li>
65 * <li><strong>Information query</strong>: Platform properties are read from OpenCL runtime</li>
66 * <li><strong>Model creation</strong>: Platform objects are created with discovered information</li>
67 * <li><strong>Filtering</strong>: User-defined predicates select appropriate platforms</li>
68 * <li><strong>Device discovery</strong>: Selected platforms are queried for available devices</li>
69 * </ol>
70 *
71 * <p>Performance implications:
72 * <ul>
73 * <li><strong>Driver optimization</strong>: Platform vendors optimize for their hardware</li>
74 * <li><strong>Memory models</strong>: Different platforms may have different memory hierarchies</li>
75 * <li><strong>Kernel compilation</strong>: Platform-specific optimizations during compilation</li>
76 * <li><strong>Runtime behavior</strong>: Platform-specific scheduling and resource management</li>
77 * </ul>
78 *
79 * <p>Error handling considerations:
80 * <ul>
81 * <li><strong>Platform availability</strong>: Platforms may become unavailable at runtime</li>
82 * <li><strong>Version compatibility</strong>: Kernels may require specific OpenCL versions</li>
83 * <li><strong>Extension support</strong>: Missing extensions may cause compilation failures</li>
84 * <li><strong>Device enumeration</strong>: Platform may have no compatible devices</li>
85 * </ul>
86 *
87 * @see Device
88 * @see PlatformProfile
89 * @see net.bmahe.genetics4j.gpu.spec.GPUEAExecutionContext#platformFilters()
90 * @see net.bmahe.genetics4j.gpu.opencl.PlatformUtils
91 */
92 @Value.Immutable
93 public interface Platform {
94
95 /**
96 * Returns the native OpenCL platform identifier.
97 *
98 * @return the OpenCL platform ID for low-level operations
99 */
100 cl_platform_id platformId();
101
102 /**
103 * Returns the OpenCL profile supported by this platform.
104 *
105 * @return the platform profile (FULL_PROFILE or EMBEDDED_PROFILE)
106 */
107 PlatformProfile profile();
108
109 /**
110 * Returns the OpenCL version string supported by this platform.
111 *
112 * @return the OpenCL version (e.g., "OpenCL 2.1")
113 */
114 String version();
115
116 /**
117 * Returns the platform name provided by the vendor.
118 *
119 * @return the human-readable platform name
120 */
121 String name();
122
123 /**
124 * Returns the platform vendor name.
125 *
126 * @return the vendor name (e.g., "NVIDIA Corporation", "AMD")
127 */
128 String vendor();
129
130 /**
131 * Returns the set of OpenCL extensions supported by this platform.
132 *
133 * @return set of extension names (e.g., "cl_khr_fp64", "cl_khr_global_int32_base_atomics")
134 */
135 Set<String> extensions();
136
137 /**
138 * Returns the number of OpenCL devices available on this platform.
139 *
140 * @return the count of devices that can be used for computation
141 */
142 int numDevices();
143
144 /**
145 * Creates a new builder for constructing Platform instances.
146 *
147 * @return a new builder for creating platform objects
148 */
149 static ImmutablePlatform.Builder builder() {
150 return ImmutablePlatform.builder();
151 }
152 }