1================== 2Matrix Types 3================== 4 5.. contents:: 6 :local: 7 8.. _matrixtypes: 9 10Clang provides a C/C++ language extension that allows users to directly express 11fixed-size 2-dimensional matrices as language values and perform arithmetic on 12them. 13 14This feature is currently experimental, and both its design and its 15implementation are in flux. 16 17Draft Specification 18=================== 19 20Matrix Type 21----------- 22 23A matrix type is a scalar type with an underlying *element type*, a constant 24number of *rows*, and a constant number of *columns*. Matrix types with the same 25element type, rows, and columns are the same type. A value of a matrix type 26includes storage for ``rows * columns`` values of the *element type*. The 27internal layout, overall size and alignment are implementation-defined. 28 29The maximum of the product of the number of rows and columns is 30implementation-defined. If that implementation-defined limit is exceeded, the 31program is ill-formed. 32 33Currently, the element type of a matrix is only permitted to be one of the 34following types: 35 36* an integer type (as in C23 6.2.5p22), but excluding enumerated types, ``bool``, 37 and ``_BitInt`` types whose width is not a power of 2; 38* the standard floating types ``float`` or ``double``; 39* a half-precision floating point type, if one is supported on the target. 40 41Other types may be supported in the future. 42 43Matrix Type Attribute 44--------------------- 45 46Matrix types can be declared by adding the ``matrix_type`` attribute to the 47declaration of a *typedef* (or a C++ alias declaration). The underlying type 48of the *typedef* must be a valid matrix element type. The 49attribute takes two arguments, both of which must be integer constant 50expressions that evaluate to a value greater than zero. The first specifies the 51number of rows, and the second specifies the number of columns. The underlying 52type of the *typedef* becomes a matrix type with the given dimensions and an 53element type of the former underlying type. 54 55If a declaration of a *typedef-name* has a ``matrix_type`` attribute, then all 56declaration of that *typedef-name* shall have a matrix_type attribute with the 57same element type, number of rows, and number of columns. 58 59Standard Conversions 60-------------------- 61 62The standard conversions are extended as follows. Note that these conversions 63are intentionally not listed as satisfying the constraints for assignment, 64which is to say, they are only permitted as explicit casts, not as implicit 65conversions. 66 67A value of matrix type can be converted to another matrix type if the number of 68rows and columns are the same and the value's elements can be converted to the 69element type of the result type. The result is a matrix where each element is 70the converted corresponding element. 71 72A value of any real type (as in C23 6.2.5p14) can be converted to a matrix type 73if it can be converted to the element type of the matrix. The result is a 74matrix where all elements are the converted original value. 75 76If the number of rows or columns differ between the original and resulting 77type, the program is ill-formed. 78 79 80Arithmetic Conversions 81---------------------- 82 83The usual arithmetic conversions are extended as follows. 84 85Insert at the start: 86 87* If both operands are of matrix type, no arithmetic conversion is performed. 88* If one operand is of matrix type and the other operand is of a real type, 89 convert the real type operand to the matrix type 90 according to the standard conversion rules. 91 92Matrix Type Element Access Operator 93----------------------------------- 94 95An expression of the form ``E1 [E2] [E3]``, where ``E1`` has matrix type ``cv 96M``, is a matrix element access expression. Let ``T`` be the element type 97of ``M``, and let ``R`` and ``C`` be the number of rows and columns in ``M`` 98respectively. The index expressions shall have integral or unscoped 99enumeration type and shall not be uses of the comma operator unless 100parenthesized. The first index expression shall evaluate to a 101non-negative value less than ``R``, and the second index expression shall 102evaluate to a non-negative value less than ``C``, or else the expression has 103undefined behavior. If ``E1`` is a prvalue, the result is a prvalue with type 104``T`` and is the value of the element at the given row and column in the matrix. 105Otherwise, the result is a glvalue with type ``cv T`` and with the same value 106category as ``E1`` which refers to the element at the given row and column in 107the matrix. 108 109Programs containing a single subscript expression into a matrix are ill-formed. 110 111**Note**: We considered providing an expression of the form 112``postfix-expression [expression]`` to access columns of a matrix. We think 113that such an expression would be problematic once both column and row major 114matrixes are supported: depending on the memory layout, either accessing columns 115or rows can be done efficiently, but not both. Instead, we propose to provide 116builtins to extract rows and columns from a matrix. This makes the operations 117more explicit. 118 119Matrix Type Binary Operators 120---------------------------- 121 122Given two matrixes, the ``+`` and ``-`` operators perform element-wise addition 123and subtraction, while the ``*`` operator performs matrix multiplication. 124``+``, ``-``, ``*``, and ``/`` can also be used with a matrix and a scalar 125value, applying the operation to each element of the matrix. 126 127Earlier versions of this extension did not support division by a scalar. 128You can test for the availability of this feature with 129``__has_extension(matrix_types_scalar_division)``. 130 131For the expression ``M1 BIN_OP M2`` where 132 133* ``BIN_OP`` is one of ``+`` or ``-``, one of ``M1`` and ``M2`` is of matrix 134 type, and the other is of matrix type or real type; or 135* ``BIN_OP`` is ``*``, one of ``M1`` and ``M2`` is of matrix type, and the 136 other is of a real type; or 137* ``BIN_OP`` is ``/``, ``M1`` is of matrix type, and ``M2`` is of a real type: 138 139* The usual arithmetic conversions are applied to ``M1`` and ``M2``. [ Note: if ``M1`` or 140 ``M2`` are of a real type, they are broadcast to matrices here. — end note ] 141* ``M1`` and ``M2`` shall be of the same matrix type. 142* The result is equivalent to Res in the following where col is the number of 143 columns and row is the number of rows in the matrix type: 144 145.. code-block:: c++ 146 147 decltype(M1) Res; 148 for (int C = 0; C < col; ++C) 149 for (int R = 0; R < row; ++R) 150 Res[R][C] = M1[R][C] BIN_OP M2[R][C]; 151 152Given the expression ``M1 * M2`` where ``M1`` and ``M2`` are of matrix type: 153 154* The usual arithmetic conversions are applied to ``M1`` and ``M2``. 155* The type of ``M1`` shall have the same number of columns as the type of ``M2`` has 156 rows. The element types of ``M1`` and ``M2`` shall be the same type. 157* The resulting type, ``MTy``, is a matrix type with the common element type, 158 the number of rows of ``M1`` and the number of columns of ``M2``. 159* The result is equivalent to ``Res`` in the following where ``EltTy`` is the 160 element type of ``MTy``, ``col`` is the number of columns, ``row`` is the 161 number of rows in ``MTy`` and ``inner`` is the number of columns of ``M1``: 162 163.. code-block:: c++ 164 165 MTy Res; 166 for (int C = 0; C < col; ++C) { 167 for (int R = 0; R < row; ++R) { 168 EltTy Elt = 0; 169 for (int K = 0; K < inner; ++K) { 170 Elt += M1[R][K] * M2[K][C]; 171 } 172 Res[R][C] = Elt; 173 } 174 175All operations on matrix types match the behavior of the element type with 176respect to signed overflows. 177 178With respect to floating-point contraction, rounding and environment rules, 179operations on matrix types match the behavior of the elementwise operations 180in the corresponding expansions provided above. 181 182Operations on floating-point matrices have the same rounding and floating-point 183environment behavior as ordinary floating-point operations in the expression's 184context. For the purposes of floating-point contraction, all calculations done 185as part of a matrix operation are considered intermediate operations, and their 186results need not be rounded to the format of the element type until the final 187result in the containing expression. This is subject to the normal restrictions 188on contraction, such as ``#pragma STDC FP_CONTRACT``. 189 190For the ``+=``, ``-=`` and ``*=`` operators the semantics match their expanded 191variants. 192 193Matrix Type Builtin Operations 194------------------------------ 195 196Each matrix type supports a collection of builtin expressions that look like 197function calls but do not form an overload set. Here they are described as 198function declarations with rules for how to construct the argument list types 199and return type and the library description elements from 200[library.description.structure.specifications]/3 in the C++ standard. 201 202Definitions: 203 204* *M*, *M1*, *M2*, *M3* - Matrix types 205* *T* - Element type 206* *row*, *col* - Row and column arguments respectively. 207 208 209``M2 __builtin_matrix_transpose(M1 matrix)`` 210 211**Remarks**: The return type is a cv-unqualified matrix type that has the same 212element type as ``M1`` and has the same number of rows as ``M1`` has columns and 213the same number of columns as ``M1`` has rows. 214 215**Returns**: A matrix ``Res`` equivalent to the code below, where ``col`` refers to the 216number of columns of ``M``, and ``row`` to the number of rows of ``M``. 217 218**Effects**: Equivalent to: 219 220.. code-block:: c++ 221 222 M Res; 223 for (int C = 0; C < col; ++C) 224 for (int R = 0; R < row; ++R) 225 Res[C][R] = matrix[R][C]; 226 227 228``M __builtin_matrix_column_major_load(T *ptr, size_t row, size_t col, size_t columnStride)`` 229 230**Mandates**: ``row`` and ``col`` shall be integral constants greater than 0. 231 232**Preconditions**: ``columnStride`` is greater than or equal to ``row``. 233 234**Remarks**: The return type is a cv-unqualified matrix type with an element 235type of the cv-unqualified version of ``T`` and a number of rows and columns equal 236to ``row`` and ``col`` respectively. The parameter ``columnStride`` is optional 237and if omitted ``row`` is used as ``columnStride``. 238 239**Returns**: A matrix ``Res`` equivalent to: 240 241.. code-block:: c++ 242 243 M Res; 244 for (size_t C = 0; C < col; ++C) { 245 for (size_t R = 0; R < row; ++K) 246 Res[R][C] = ptr[R]; 247 ptr += columnStride 248 } 249 250 251``void __builtin_matrix_column_major_store(M matrix, T *ptr, size_t columnStride)`` 252 253**Preconditions**: ``columnStride`` is greater than or equal to the number of rows in ``M``. 254 255**Remarks**: The type ``T`` is the const-unqualified version of the matrix 256argument’s element type. The parameter ``columnStride`` is optional and if 257omitted, the number of rows of ``M`` is used as ``columnStride``. 258 259**Effects**: Equivalent to: 260 261.. code-block:: c++ 262 263 for (size_t C = 0; C < columns in M; ++C) { 264 for (size_t R = 0; R < rows in M; ++K) 265 ptr[R] = matrix[R][C]; 266 ptr += columnStride 267 } 268 269 270TODOs 271----- 272 273TODO: Does it make sense to allow M::element_type, M::rows, and M::columns 274where M is a matrix type? We don’t support this anywhere else, but it’s 275convenient. The alternative is using template deduction to extract this 276information. Also add spelling for C. 277 278Future Work: Initialization syntax. 279 280 281Decisions for the Implementation in Clang 282========================================= 283 284This section details decisions taken for the implementation in Clang and is not 285part of the draft specification. 286 287The elements of a value of a matrix type are laid out in column-major order 288without padding. 289 290We propose to provide a Clang option to override this behavior and allow 291contraction of those operations (e.g. *-ffp-contract=matrix*). 292 293TODO: Specify how matrix values are passed to functions. 294