Eigen  5.0.1-dev+master
 
Loading...
Searching...
No Matches
Assign_AOCL.h
1/*
2 * This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
5 *
6 * Assign_AOCL.h - AOCL Vectorized Math Dispatch Layer for Eigen
7 *
8 * Copyright (c) 2025, Advanced Micro Devices, Inc. All rights reserved.
9 *
10 * Description:
11 * ------------
12 * This file implements a high-performance dispatch layer that automatically
13 * routes Eigen's element-wise mathematical operations to AMD Optimizing CPU
14 * Libraries (AOCL) Vector Math Library (VML) functions when beneficial for
15 * performance.
16 *
17 * The dispatch system uses C++ template specialization to intercept Eigen's
18 * assignment operations and redirect them to AOCL's VRDA functions, which
19 * provide optimized implementations for AMD Zen architectures.
20 *
21 * Key Features:
22 * -------------
23 * 1. Automatic Dispatch: Seamlessly routes supported operations to AOCL without
24 * requiring code changes in user applications
25 *
26 * 2. Performance Optimization: Uses AOCL VRDA functions optimized for Zen
27 * family processors with automatic SIMD instruction selection (AVX2, AVX-512)
28 *
29 * 3. Threshold-Based Activation: Only activates for vectors larger than
30 * EIGEN_AOCL_VML_THRESHOLD (default: 128 elements) to avoid overhead on
31 * small vectors
32 *
33 * 4. Precision-Specific Handling:
34 * - Double precision: AOCL VRDA vectorized functions
35 * - Single precision: Scalar fallback (preserves correctness)
36 *
37 * 5. Memory Layout Compatibility: Ensures direct memory access and compatible
38 * storage orders between source and destination for optimal performance
39 *
40 * Supported Operations:
41 * ---------------------
42 * UNARY OPERATIONS (vector → vector):
43 * - exp(), exp2(), sin(), cos(), sqrt(), cbrt(), abs(), log(), log10(), log2()
44 *
45 * BINARY OPERATIONS (vector op vector → vector):
46 * - +, pow(), max(), min()
47 *
48 * Template Specialization Mechanism:
49 * -----------------------------------
50 * The system works by specializing Eigen's Assignment template for:
51 * 1. CwiseUnaryOp with scalar_*_op functors (unary operations)
52 * 2. CwiseBinaryOp with scalar_*_op functors (binary operations)
53 * 3. Dense2Dense assignment context with AOCL-compatible traits
54 *
55 * Dispatch conditions (all must be true):
56 * - Source and destination are contiguous arrays (direct access, unit inner stride, linear access)
57 * - Compatible storage orders (both row-major or both column-major)
58 * - Vector size ≥ EIGEN_AOCL_VML_THRESHOLD or Dynamic size
59 * - Supported data type (currently double precision for VRDA)
60 *
61 * Integration Example:
62 * --------------------
63 * // Standard Eigen code - no changes required
64 * VectorXd x = VectorXd::Random(10000);
65 * VectorXd y = VectorXd::Random(10000);
66 * VectorXd result;
67 *
68 * // These operations are automatically dispatched to AOCL:
69 * result = x.array().exp(); // → amd_vrda_exp()
70 * result = x.array().sin(); // → amd_vrda_sin()
71 * result = x.array() + y.array(); // → amd_vrda_add()
72 * result = x.array().pow(y.array()); // → amd_vrda_pow()
73 *
74 * Configuration:
75 * --------------
76 * Required preprocessor definitions:
77 * - EIGEN_USE_AOCL_ALL or EIGEN_USE_AOCL_MT: Enable AOCL integration
78 * - EIGEN_USE_AOCL_VML: Enable Vector Math Library dispatch
79 *
80 * Compilation Requirements:
81 * -------------------------
82 * Include paths:
83 * - AOCL headers: -I${AOCL_ROOT}/include
84 * - Eigen headers: -I/path/to/eigen
85 *
86 * Link libraries:
87 * - AOCL MathLib: -lamdlibm
88 * - Standard math: -lm
89 *
90 * Compiler flags:
91 * - Optimization: -O3 (required for inlining)
92 * - Architecture: -march=znver5 or -march=native
93 * - Vectorization: -mfma -mavx512f (if supported)
94 *
95 * Platform Support:
96 * ------------------
97 * - Primary: Linux x86_64 with AMD Zen family processors
98 * - Compilers: GCC 8+, Clang 10+, AOCC (recommended)
99 * - AOCL Version: 4.0+ (with VRDA support)
100 *
101 * Error Handling:
102 * ---------------
103 * - Graceful fallback to scalar operations for unsupported configurations
104 * - Compile-time detection of AOCL availability
105 * - Runtime size and alignment validation with eigen_assert()
106 *
107 * Developer:
108 * ----------
109 * Name: Sharad Saurabh Bhaskar
110 * Email: shbhaska@amd.com
111 * Organization: Advanced Micro Devices, Inc.
112 */
113// SPDX-License-Identifier: MPL-2.0
114
115#ifndef EIGEN_ASSIGN_AOCL_H
116#define EIGEN_ASSIGN_AOCL_H
117
118namespace Eigen {
119namespace internal {
120
121// The AOCL calls take one contiguous array per operand: unit inner stride and linear access, which a block of a
122// larger matrix or a map with an outer stride lacks.
123template <typename Xpr>
124struct aocl_is_contiguous
125 : bool_constant<(int(Xpr::Flags) & DirectAccessBit) && int(Xpr::InnerStrideAtCompileTime) == 1 &&
126 (int(evaluator<Xpr>::Flags) & LinearAccessBit)> {};
127
128// Traits for unary operations.
129template <typename Dst, typename Src>
130class aocl_assign_traits {
131 private:
132 enum {
133 DstIsContiguous = aocl_is_contiguous<Dst>::value,
134 SrcIsContiguous = aocl_is_contiguous<Src>::value,
135 StorageOrdersAgree = (int(Dst::IsRowMajor) == int(Src::IsRowMajor)),
136 InnerSize = Dst::IsVectorAtCompileTime ? int(Dst::SizeAtCompileTime)
137 : (Dst::Flags & RowMajorBit) ? int(Dst::ColsAtCompileTime)
138 : int(Dst::RowsAtCompileTime),
139 LargeEnough = (InnerSize == Dynamic) || (InnerSize >= EIGEN_AOCL_VML_THRESHOLD)
140 };
141
142 public:
143 enum {
144 EnableAoclVML = DstIsContiguous && SrcIsContiguous && StorageOrdersAgree && LargeEnough,
145 Traversal = LinearTraversal
146 };
147};
148
149// Traits for binary operations (e.g., add, pow).
150template <typename Dst, typename Lhs, typename Rhs>
151class aocl_assign_binary_traits {
152 private:
153 enum {
154 DstIsContiguous = aocl_is_contiguous<Dst>::value,
155 LhsIsContiguous = aocl_is_contiguous<Lhs>::value,
156 RhsIsContiguous = aocl_is_contiguous<Rhs>::value,
157 StorageOrdersAgree =
158 (int(Dst::IsRowMajor) == int(Lhs::IsRowMajor)) && (int(Dst::IsRowMajor) == int(Rhs::IsRowMajor)),
159 InnerSize = Dst::IsVectorAtCompileTime ? int(Dst::SizeAtCompileTime)
160 : (Dst::Flags & RowMajorBit) ? int(Dst::ColsAtCompileTime)
161 : int(Dst::RowsAtCompileTime),
162 LargeEnough = (InnerSize == Dynamic) || (InnerSize >= EIGEN_AOCL_VML_THRESHOLD)
163 };
164
165 public:
166 enum { EnableAoclVML = DstIsContiguous && LhsIsContiguous && RhsIsContiguous && StorageOrdersAgree && LargeEnough };
167};
168
169// Unary operation dispatch for float (scalar fallback).
170#define EIGEN_AOCL_VML_UNARY_CALL_FLOAT(EIGENOP) \
171 template <typename DstXprType, typename SrcXprNested> \
172 struct Assignment<DstXprType, CwiseUnaryOp<scalar_##EIGENOP##_op<float>, SrcXprNested>, assign_op<float, float>, \
173 Dense2Dense, std::enable_if_t<aocl_assign_traits<DstXprType, SrcXprNested>::EnableAoclVML>> { \
174 using SrcXprType = CwiseUnaryOp<scalar_##EIGENOP##_op<float>, SrcXprNested>; \
175 static void run(DstXprType &dst, const SrcXprType &src, const assign_op<float, float> &func) { \
176 resize_if_allowed(dst, src, func); \
177 eigen_assert(dst.rows() == src.rows() && dst.cols() == src.cols()); \
178 Eigen::Index n = dst.size(); \
179 if (n <= 0) return; \
180 const float *input = reinterpret_cast<const float *>(src.nestedExpression().data()); \
181 float *output = reinterpret_cast<float *>(dst.data()); \
182 for (Eigen::Index i = 0; i < n; ++i) { \
183 output[i] = std::EIGENOP(input[i]); \
184 } \
185 } \
186 };
187
188// Unary operation dispatch for double (AOCL vectorized).
189#define EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(EIGENOP, AOCLOP) \
190 template <typename DstXprType, typename SrcXprNested> \
191 struct Assignment<DstXprType, CwiseUnaryOp<scalar_##EIGENOP##_op<double>, SrcXprNested>, assign_op<double, double>, \
192 Dense2Dense, std::enable_if_t<aocl_assign_traits<DstXprType, SrcXprNested>::EnableAoclVML>> { \
193 using SrcXprType = CwiseUnaryOp<scalar_##EIGENOP##_op<double>, SrcXprNested>; \
194 static void run(DstXprType &dst, const SrcXprType &src, const assign_op<double, double> &func) { \
195 resize_if_allowed(dst, src, func); \
196 eigen_assert(dst.rows() == src.rows() && dst.cols() == src.cols()); \
197 Eigen::Index n = dst.size(); \
198 eigen_assert(n <= INT_MAX && "AOCL does not support arrays larger than INT_MAX"); \
199 if (n <= 0) return; \
200 const double *input = reinterpret_cast<const double *>(src.nestedExpression().data()); \
201 double *output = reinterpret_cast<double *>(dst.data()); \
202 int aocl_n = internal::convert_index<int>(n); \
203 AOCLOP(aocl_n, const_cast<double *>(input), output); \
204 } \
205 };
206
207// Instantiate unary calls for float (scalar).
208// EIGEN_AOCL_VML_UNARY_CALL_FLOAT(exp)
209
210// Instantiate unary calls for double (AOCL vectorized).
211EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(exp2, amd_vrda_exp2)
212EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(exp, amd_vrda_exp)
213EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(sin, amd_vrda_sin)
214EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(cos, amd_vrda_cos)
215EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(sqrt, amd_vrda_sqrt)
216EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(cbrt, amd_vrda_cbrt)
217EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(abs, amd_vrda_fabs)
218EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(log, amd_vrda_log)
219EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(log10, amd_vrda_log10)
220EIGEN_AOCL_VML_UNARY_CALL_DOUBLE(log2, amd_vrda_log2)
221
222// Binary operation dispatch for float (scalar fallback).
223#define EIGEN_AOCL_VML_BINARY_CALL_FLOAT(EIGENOP, STDFUNC) \
224 template <typename DstXprType, typename LhsXprNested, typename RhsXprNested> \
225 struct Assignment< \
226 DstXprType, CwiseBinaryOp<scalar_##EIGENOP##_op<float, float>, LhsXprNested, RhsXprNested>, \
227 assign_op<float, float>, Dense2Dense, \
228 std::enable_if_t<aocl_assign_binary_traits<DstXprType, LhsXprNested, RhsXprNested>::EnableAoclVML>> { \
229 using SrcXprType = CwiseBinaryOp<scalar_##EIGENOP##_op<float, float>, LhsXprNested, RhsXprNested>; \
230 static void run(DstXprType &dst, const SrcXprType &src, const assign_op<float, float> &func) { \
231 resize_if_allowed(dst, src, func); \
232 eigen_assert(dst.rows() == src.rows() && dst.cols() == src.cols()); \
233 Eigen::Index n = dst.size(); \
234 if (n <= 0) return; \
235 const float *lhs = reinterpret_cast<const float *>(src.lhs().data()); \
236 const float *rhs = reinterpret_cast<const float *>(src.rhs().data()); \
237 float *output = reinterpret_cast<float *>(dst.data()); \
238 for (Eigen::Index i = 0; i < n; ++i) { \
239 output[i] = STDFUNC(lhs[i], rhs[i]); \
240 } \
241 } \
242 };
243
244// Binary operation dispatch for double (AOCL vectorized).
245#define EIGEN_AOCL_VML_BINARY_CALL_DOUBLE(EIGENOP, AOCLOP) \
246 template <typename DstXprType, typename LhsXprNested, typename RhsXprNested> \
247 struct Assignment< \
248 DstXprType, CwiseBinaryOp<scalar_##EIGENOP##_op<double, double>, LhsXprNested, RhsXprNested>, \
249 assign_op<double, double>, Dense2Dense, \
250 std::enable_if_t<aocl_assign_binary_traits<DstXprType, LhsXprNested, RhsXprNested>::EnableAoclVML>> { \
251 using SrcXprType = CwiseBinaryOp<scalar_##EIGENOP##_op<double, double>, LhsXprNested, RhsXprNested>; \
252 static void run(DstXprType &dst, const SrcXprType &src, const assign_op<double, double> &func) { \
253 resize_if_allowed(dst, src, func); \
254 eigen_assert(dst.rows() == src.rows() && dst.cols() == src.cols()); \
255 Eigen::Index n = dst.size(); \
256 eigen_assert(n <= INT_MAX && "AOCL does not support arrays larger than INT_MAX"); \
257 if (n <= 0) return; \
258 const double *lhs = reinterpret_cast<const double *>(src.lhs().data()); \
259 const double *rhs = reinterpret_cast<const double *>(src.rhs().data()); \
260 double *output = reinterpret_cast<double *>(dst.data()); \
261 int aocl_n = internal::convert_index<int>(n); \
262 AOCLOP(aocl_n, const_cast<double *>(lhs), const_cast<double *>(rhs), output); \
263 } \
264 };
265
266// Instantiate binary calls for float (scalar).
267// EIGEN_AOCL_VML_BINARY_CALL_FLOAT(sum, std::plus<float>) // Using scalar_sum_op for addition
268// EIGEN_AOCL_VML_BINARY_CALL_FLOAT(pow, std::pow)
269
270// Instantiate binary calls for double (AOCL vectorized).
271EIGEN_AOCL_VML_BINARY_CALL_DOUBLE(sum, amd_vrda_add) // Using scalar_sum_op for addition
272EIGEN_AOCL_VML_BINARY_CALL_DOUBLE(pow, amd_vrda_pow)
273EIGEN_AOCL_VML_BINARY_CALL_DOUBLE(max, amd_vrda_fmax)
274EIGEN_AOCL_VML_BINARY_CALL_DOUBLE(min, amd_vrda_fmin)
275
276} // namespace internal
277} // namespace Eigen
278
279#endif // EIGEN_ASSIGN_AOCL_H
constexpr unsigned int RowMajorBit
Definition Constants.h:71