View Javadoc
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
12   * implementation of the OpenCL specification. Each platform represents a collection of OpenCL
13   * devices (CPUs, GPUs, accelerators) provided by 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   * <pre>{@code
35   * // Select platforms with full OpenCL profile support
36   * Predicate<Platform> fullProfileFilter = platform -> 
37   *     platform.profile() == PlatformProfile.FULL_PROFILE;
38   * 
39   * // Select platforms from specific vendors
40   * Predicate<Platform> vendorFilter = platform -> 
41   *     platform.vendor().toLowerCase().contains("nvidia") ||
42   *     platform.vendor().toLowerCase().contains("amd");
43   * 
44   * // Select platforms with minimum OpenCL version
45   * Predicate<Platform> versionFilter = platform -> {
46   *     String version = platform.version();
47   *     return version.contains("2.") || version.contains("3.");
48   * };
49   * 
50   * // Select platforms with required extensions
51   * Predicate<Platform> extensionFilter = platform ->
52   *     platform.extensions().contains("cl_khr_fp64");
53   * 
54   * // Combine filters for comprehensive platform selection
55   * Predicate<Platform> combinedFilter = fullProfileFilter
56   *     .and(versionFilter)
57   *     .and(platform -> platform.numDevices() > 0);
58   * }</pre>
59   * 
60   * <p>Platform discovery workflow:
61   * <ol>
62   * <li><strong>Enumeration</strong>: System discovers all available OpenCL platforms</li>
63   * <li><strong>Information query</strong>: Platform properties are read from OpenCL runtime</li>
64   * <li><strong>Model creation</strong>: Platform objects are created with discovered information</li>
65   * <li><strong>Filtering</strong>: User-defined predicates select appropriate platforms</li>
66   * <li><strong>Device discovery</strong>: Selected platforms are queried for available devices</li>
67   * </ol>
68   * 
69   * <p>Performance implications:
70   * <ul>
71   * <li><strong>Driver optimization</strong>: Platform vendors optimize for their hardware</li>
72   * <li><strong>Memory models</strong>: Different platforms may have different memory hierarchies</li>
73   * <li><strong>Kernel compilation</strong>: Platform-specific optimizations during compilation</li>
74   * <li><strong>Runtime behavior</strong>: Platform-specific scheduling and resource management</li>
75   * </ul>
76   * 
77   * <p>Error handling considerations:
78   * <ul>
79   * <li><strong>Platform availability</strong>: Platforms may become unavailable at runtime</li>
80   * <li><strong>Version compatibility</strong>: Kernels may require specific OpenCL versions</li>
81   * <li><strong>Extension support</strong>: Missing extensions may cause compilation failures</li>
82   * <li><strong>Device enumeration</strong>: Platform may have no compatible devices</li>
83   * </ul>
84   * 
85   * @see Device
86   * @see PlatformProfile
87   * @see net.bmahe.genetics4j.gpu.spec.GPUEAExecutionContext#platformFilters()
88   * @see net.bmahe.genetics4j.gpu.opencl.PlatformUtils
89   */
90  @Value.Immutable
91  public interface Platform {
92  
93  	/**
94  	 * Returns the native OpenCL platform identifier.
95  	 * 
96  	 * @return the OpenCL platform ID for low-level operations
97  	 */
98  	cl_platform_id platformId();
99  
100 	/**
101 	 * Returns the OpenCL profile supported by this platform.
102 	 * 
103 	 * @return the platform profile (FULL_PROFILE or EMBEDDED_PROFILE)
104 	 */
105 	PlatformProfile profile();
106 
107 	/**
108 	 * Returns the OpenCL version string supported by this platform.
109 	 * 
110 	 * @return the OpenCL version (e.g., "OpenCL 2.1")
111 	 */
112 	String version();
113 
114 	/**
115 	 * Returns the platform name provided by the vendor.
116 	 * 
117 	 * @return the human-readable platform name
118 	 */
119 	String name();
120 
121 	/**
122 	 * Returns the platform vendor name.
123 	 * 
124 	 * @return the vendor name (e.g., "NVIDIA Corporation", "AMD")
125 	 */
126 	String vendor();
127 
128 	/**
129 	 * Returns the set of OpenCL extensions supported by this platform.
130 	 * 
131 	 * @return set of extension names (e.g., "cl_khr_fp64", "cl_khr_global_int32_base_atomics")
132 	 */
133 	Set<String> extensions();
134 
135 	/**
136 	 * Returns the number of OpenCL devices available on this platform.
137 	 * 
138 	 * @return the count of devices that can be used for computation
139 	 */
140 	int numDevices();
141 	
142 	/**
143 	 * Creates a new builder for constructing Platform instances.
144 	 * 
145 	 * @return a new builder for creating platform objects
146 	 */
147 	static ImmutablePlatform.Builder builder() {
148 		return ImmutablePlatform.builder();
149 	}
150 }