1 /****************************************************************************** 2 * @file matrix_functions.h 3 * @brief Public header file for CMSIS DSP Library 4 * @version V1.10.1 5 * @date 10 August 2022 6 * Target Processor: Cortex-M and Cortex-A cores 7 ******************************************************************************/ 8 /* 9 * Copyright (c) 2010-2020 Arm Limited or its affiliates. All rights reserved. 10 * 11 * SPDX-License-Identifier: Apache-2.0 12 * 13 * Licensed under the Apache License, Version 2.0 (the License); you may 14 * not use this file except in compliance with the License. 15 * You may obtain a copy of the License at 16 * 17 * www.apache.org/licenses/LICENSE-2.0 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 */ 25 26 27 #ifndef _MATRIX_FUNCTIONS_H_ 28 #define _MATRIX_FUNCTIONS_H_ 29 30 #include "arm_math_types.h" 31 #include "arm_math_memory.h" 32 33 #include "dsp/none.h" 34 #include "dsp/utils.h" 35 36 #ifdef __cplusplus 37 extern "C" 38 { 39 #endif 40 41 /** 42 * @defgroup groupMatrix Matrix Functions 43 * 44 * This set of functions provides basic matrix math operations. 45 * The functions operate on matrix data structures. For example, 46 * the type 47 * definition for the floating-point matrix structure is shown 48 * below: 49 * <pre> 50 * typedef struct 51 * { 52 * uint16_t numRows; // number of rows of the matrix. 53 * uint16_t numCols; // number of columns of the matrix. 54 * float32_t *pData; // points to the data of the matrix. 55 * } arm_matrix_instance_f32; 56 * </pre> 57 * There are similar definitions for Q15 and Q31 data types. 58 * 59 * The structure specifies the size of the matrix and then points to 60 * an array of data. The array is of size <code>numRows X numCols</code> 61 * and the values are arranged in row order. That is, the 62 * matrix element (i, j) is stored at: 63 * <pre> 64 * pData[i*numCols + j] 65 * </pre> 66 * 67 * \par Init Functions 68 * There is an associated initialization function for each type of matrix 69 * data structure. 70 * The initialization function sets the values of the internal structure fields. 71 * Refer to \ref arm_mat_init_f32(), \ref arm_mat_init_q31() and \ref arm_mat_init_q15() 72 * for floating-point, Q31 and Q15 types, respectively. 73 * 74 * \par 75 * Use of the initialization function is optional. However, if initialization function is used 76 * then the instance structure cannot be placed into a const data section. 77 * To place the instance structure in a const data 78 * section, manually initialize the data structure. For example: 79 * <pre> 80 * <code>arm_matrix_instance_f32 S = {nRows, nColumns, pData};</code> 81 * <code>arm_matrix_instance_q31 S = {nRows, nColumns, pData};</code> 82 * <code>arm_matrix_instance_q15 S = {nRows, nColumns, pData};</code> 83 * </pre> 84 * where <code>nRows</code> specifies the number of rows, <code>nColumns</code> 85 * specifies the number of columns, and <code>pData</code> points to the 86 * data array. 87 * 88 * \par Size Checking 89 * By default all of the matrix functions perform size checking on the input and 90 * output matrices. For example, the matrix addition function verifies that the 91 * two input matrices and the output matrix all have the same number of rows and 92 * columns. If the size check fails the functions return: 93 * <pre> 94 * ARM_MATH_SIZE_MISMATCH 95 * </pre> 96 * Otherwise the functions return 97 * <pre> 98 * ARM_MATH_SUCCESS 99 * </pre> 100 * There is some overhead associated with this matrix size checking. 101 * The matrix size checking is enabled via the \#define 102 * <pre> 103 * ARM_MATH_MATRIX_CHECK 104 * </pre> 105 * within the library project settings. By default this macro is defined 106 * and size checking is enabled. By changing the project settings and 107 * undefining this macro size checking is eliminated and the functions 108 * run a bit faster. With size checking disabled the functions always 109 * return <code>ARM_MATH_SUCCESS</code>. 110 */ 111 112 #define DEFAULT_HOUSEHOLDER_THRESHOLD_F64 (1.0e-16) 113 #define DEFAULT_HOUSEHOLDER_THRESHOLD_F32 (1.0e-12f) 114 115 /** 116 * @brief Instance structure for the floating-point matrix structure. 117 */ 118 typedef struct 119 { 120 uint16_t numRows; /**< number of rows of the matrix. */ 121 uint16_t numCols; /**< number of columns of the matrix. */ 122 float32_t *pData; /**< points to the data of the matrix. */ 123 } arm_matrix_instance_f32; 124 125 /** 126 * @brief Instance structure for the floating-point matrix structure. 127 */ 128 typedef struct 129 { 130 uint16_t numRows; /**< number of rows of the matrix. */ 131 uint16_t numCols; /**< number of columns of the matrix. */ 132 float64_t *pData; /**< points to the data of the matrix. */ 133 } arm_matrix_instance_f64; 134 135 /** 136 * @brief Instance structure for the Q7 matrix structure. 137 */ 138 typedef struct 139 { 140 uint16_t numRows; /**< number of rows of the matrix. */ 141 uint16_t numCols; /**< number of columns of the matrix. */ 142 q7_t *pData; /**< points to the data of the matrix. */ 143 } arm_matrix_instance_q7; 144 145 /** 146 * @brief Instance structure for the Q15 matrix structure. 147 */ 148 typedef struct 149 { 150 uint16_t numRows; /**< number of rows of the matrix. */ 151 uint16_t numCols; /**< number of columns of the matrix. */ 152 q15_t *pData; /**< points to the data of the matrix. */ 153 } arm_matrix_instance_q15; 154 155 /** 156 * @brief Instance structure for the Q31 matrix structure. 157 */ 158 typedef struct 159 { 160 uint16_t numRows; /**< number of rows of the matrix. */ 161 uint16_t numCols; /**< number of columns of the matrix. */ 162 q31_t *pData; /**< points to the data of the matrix. */ 163 } arm_matrix_instance_q31; 164 165 /** 166 * @brief Floating-point matrix addition. 167 * @param[in] pSrcA points to the first input matrix structure 168 * @param[in] pSrcB points to the second input matrix structure 169 * @param[out] pDst points to output matrix structure 170 * @return The function returns either 171 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 172 */ 173 arm_status arm_mat_add_f32( 174 const arm_matrix_instance_f32 * pSrcA, 175 const arm_matrix_instance_f32 * pSrcB, 176 arm_matrix_instance_f32 * pDst); 177 178 /** 179 * @brief Q15 matrix addition. 180 * @param[in] pSrcA points to the first input matrix structure 181 * @param[in] pSrcB points to the second input matrix structure 182 * @param[out] pDst points to output matrix structure 183 * @return The function returns either 184 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 185 */ 186 arm_status arm_mat_add_q15( 187 const arm_matrix_instance_q15 * pSrcA, 188 const arm_matrix_instance_q15 * pSrcB, 189 arm_matrix_instance_q15 * pDst); 190 191 /** 192 * @brief Q31 matrix addition. 193 * @param[in] pSrcA points to the first input matrix structure 194 * @param[in] pSrcB points to the second input matrix structure 195 * @param[out] pDst points to output matrix structure 196 * @return The function returns either 197 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 198 */ 199 arm_status arm_mat_add_q31( 200 const arm_matrix_instance_q31 * pSrcA, 201 const arm_matrix_instance_q31 * pSrcB, 202 arm_matrix_instance_q31 * pDst); 203 204 /** 205 * @brief Floating-point, complex, matrix multiplication. 206 * @param[in] pSrcA points to the first input matrix structure 207 * @param[in] pSrcB points to the second input matrix structure 208 * @param[out] pDst points to output matrix structure 209 * @return The function returns either 210 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 211 */ 212 arm_status arm_mat_cmplx_mult_f32( 213 const arm_matrix_instance_f32 * pSrcA, 214 const arm_matrix_instance_f32 * pSrcB, 215 arm_matrix_instance_f32 * pDst); 216 217 /** 218 * @brief Q15, complex, matrix multiplication. 219 * @param[in] pSrcA points to the first input matrix structure 220 * @param[in] pSrcB points to the second input matrix structure 221 * @param[out] pDst points to output matrix structure 222 * @return The function returns either 223 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 224 */ 225 arm_status arm_mat_cmplx_mult_q15( 226 const arm_matrix_instance_q15 * pSrcA, 227 const arm_matrix_instance_q15 * pSrcB, 228 arm_matrix_instance_q15 * pDst, 229 q15_t * pScratch); 230 231 /** 232 * @brief Q31, complex, matrix multiplication. 233 * @param[in] pSrcA points to the first input matrix structure 234 * @param[in] pSrcB points to the second input matrix structure 235 * @param[out] pDst points to output matrix structure 236 * @return The function returns either 237 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 238 */ 239 arm_status arm_mat_cmplx_mult_q31( 240 const arm_matrix_instance_q31 * pSrcA, 241 const arm_matrix_instance_q31 * pSrcB, 242 arm_matrix_instance_q31 * pDst); 243 244 /** 245 * @brief Floating-point matrix transpose. 246 * @param[in] pSrc points to the input matrix 247 * @param[out] pDst points to the output matrix 248 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 249 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 250 */ 251 arm_status arm_mat_trans_f32( 252 const arm_matrix_instance_f32 * pSrc, 253 arm_matrix_instance_f32 * pDst); 254 255 /** 256 * @brief Floating-point matrix transpose. 257 * @param[in] pSrc points to the input matrix 258 * @param[out] pDst points to the output matrix 259 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 260 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 261 */ 262 arm_status arm_mat_trans_f64( 263 const arm_matrix_instance_f64 * pSrc, 264 arm_matrix_instance_f64 * pDst); 265 266 /** 267 * @brief Floating-point complex matrix transpose. 268 * @param[in] pSrc points to the input matrix 269 * @param[out] pDst points to the output matrix 270 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 271 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 272 */ 273 arm_status arm_mat_cmplx_trans_f32( 274 const arm_matrix_instance_f32 * pSrc, 275 arm_matrix_instance_f32 * pDst); 276 277 278 /** 279 * @brief Q15 matrix transpose. 280 * @param[in] pSrc points to the input matrix 281 * @param[out] pDst points to the output matrix 282 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 283 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 284 */ 285 arm_status arm_mat_trans_q15( 286 const arm_matrix_instance_q15 * pSrc, 287 arm_matrix_instance_q15 * pDst); 288 289 /** 290 * @brief Q15 complex matrix transpose. 291 * @param[in] pSrc points to the input matrix 292 * @param[out] pDst points to the output matrix 293 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 294 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 295 */ 296 arm_status arm_mat_cmplx_trans_q15( 297 const arm_matrix_instance_q15 * pSrc, 298 arm_matrix_instance_q15 * pDst); 299 300 /** 301 * @brief Q7 matrix transpose. 302 * @param[in] pSrc points to the input matrix 303 * @param[out] pDst points to the output matrix 304 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 305 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 306 */ 307 arm_status arm_mat_trans_q7( 308 const arm_matrix_instance_q7 * pSrc, 309 arm_matrix_instance_q7 * pDst); 310 311 /** 312 * @brief Q31 matrix transpose. 313 * @param[in] pSrc points to the input matrix 314 * @param[out] pDst points to the output matrix 315 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 316 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 317 */ 318 arm_status arm_mat_trans_q31( 319 const arm_matrix_instance_q31 * pSrc, 320 arm_matrix_instance_q31 * pDst); 321 322 /** 323 * @brief Q31 complex matrix transpose. 324 * @param[in] pSrc points to the input matrix 325 * @param[out] pDst points to the output matrix 326 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 327 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 328 */ 329 arm_status arm_mat_cmplx_trans_q31( 330 const arm_matrix_instance_q31 * pSrc, 331 arm_matrix_instance_q31 * pDst); 332 333 /** 334 * @brief Floating-point matrix multiplication 335 * @param[in] pSrcA points to the first input matrix structure 336 * @param[in] pSrcB points to the second input matrix structure 337 * @param[out] pDst points to output matrix structure 338 * @return The function returns either 339 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 340 */ 341 arm_status arm_mat_mult_f32( 342 const arm_matrix_instance_f32 * pSrcA, 343 const arm_matrix_instance_f32 * pSrcB, 344 arm_matrix_instance_f32 * pDst); 345 346 /** 347 * @brief Floating-point matrix multiplication 348 * @param[in] pSrcA points to the first input matrix structure 349 * @param[in] pSrcB points to the second input matrix structure 350 * @param[out] pDst points to output matrix structure 351 * @return The function returns either 352 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 353 */ 354 arm_status arm_mat_mult_f64( 355 const arm_matrix_instance_f64 * pSrcA, 356 const arm_matrix_instance_f64 * pSrcB, 357 arm_matrix_instance_f64 * pDst); 358 359 /** 360 * @brief Floating-point matrix and vector multiplication 361 * @param[in] pSrcMat points to the input matrix structure 362 * @param[in] pVec points to vector 363 * @param[out] pDst points to output vector 364 */ 365 void arm_mat_vec_mult_f32( 366 const arm_matrix_instance_f32 *pSrcMat, 367 const float32_t *pVec, 368 float32_t *pDst); 369 370 /** 371 * @brief Q7 matrix multiplication 372 * @param[in] pSrcA points to the first input matrix structure 373 * @param[in] pSrcB points to the second input matrix structure 374 * @param[out] pDst points to output matrix structure 375 * @param[in] pState points to the array for storing intermediate results 376 * @return The function returns either 377 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 378 */ 379 arm_status arm_mat_mult_q7( 380 const arm_matrix_instance_q7 * pSrcA, 381 const arm_matrix_instance_q7 * pSrcB, 382 arm_matrix_instance_q7 * pDst, 383 q7_t * pState); 384 385 /** 386 * @brief Q7 matrix and vector multiplication 387 * @param[in] pSrcMat points to the input matrix structure 388 * @param[in] pVec points to vector 389 * @param[out] pDst points to output vector 390 */ 391 void arm_mat_vec_mult_q7( 392 const arm_matrix_instance_q7 *pSrcMat, 393 const q7_t *pVec, 394 q7_t *pDst); 395 396 /** 397 * @brief Q15 matrix multiplication 398 * @param[in] pSrcA points to the first input matrix structure 399 * @param[in] pSrcB points to the second input matrix structure 400 * @param[out] pDst points to output matrix structure 401 * @param[in] pState points to the array for storing intermediate results 402 * @return The function returns either 403 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 404 */ 405 arm_status arm_mat_mult_q15( 406 const arm_matrix_instance_q15 * pSrcA, 407 const arm_matrix_instance_q15 * pSrcB, 408 arm_matrix_instance_q15 * pDst, 409 q15_t * pState); 410 411 /** 412 * @brief Q15 matrix and vector multiplication 413 * @param[in] pSrcMat points to the input matrix structure 414 * @param[in] pVec points to vector 415 * @param[out] pDst points to output vector 416 */ 417 void arm_mat_vec_mult_q15( 418 const arm_matrix_instance_q15 *pSrcMat, 419 const q15_t *pVec, 420 q15_t *pDst); 421 422 /** 423 * @brief Q15 matrix multiplication (fast variant) for Cortex-M3 and Cortex-M4 424 * @param[in] pSrcA points to the first input matrix structure 425 * @param[in] pSrcB points to the second input matrix structure 426 * @param[out] pDst points to output matrix structure 427 * @param[in] pState points to the array for storing intermediate results 428 * @return The function returns either 429 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 430 */ 431 arm_status arm_mat_mult_fast_q15( 432 const arm_matrix_instance_q15 * pSrcA, 433 const arm_matrix_instance_q15 * pSrcB, 434 arm_matrix_instance_q15 * pDst, 435 q15_t * pState); 436 437 /** 438 * @brief Q31 matrix multiplication 439 * @param[in] pSrcA points to the first input matrix structure 440 * @param[in] pSrcB points to the second input matrix structure 441 * @param[out] pDst points to output matrix structure 442 * @return The function returns either 443 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 444 */ 445 arm_status arm_mat_mult_q31( 446 const arm_matrix_instance_q31 * pSrcA, 447 const arm_matrix_instance_q31 * pSrcB, 448 arm_matrix_instance_q31 * pDst); 449 450 /** 451 * @brief Q31 matrix multiplication 452 * @param[in] pSrcA points to the first input matrix structure 453 * @param[in] pSrcB points to the second input matrix structure 454 * @param[out] pDst points to output matrix structure 455 * @param[in] pState points to the array for storing intermediate results 456 * @return The function returns either 457 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 458 */ 459 arm_status arm_mat_mult_opt_q31( 460 const arm_matrix_instance_q31 * pSrcA, 461 const arm_matrix_instance_q31 * pSrcB, 462 arm_matrix_instance_q31 * pDst, 463 q31_t *pState); 464 465 /** 466 * @brief Q31 matrix and vector multiplication 467 * @param[in] pSrcMat points to the input matrix structure 468 * @param[in] pVec points to vector 469 * @param[out] pDst points to output vector 470 */ 471 void arm_mat_vec_mult_q31( 472 const arm_matrix_instance_q31 *pSrcMat, 473 const q31_t *pVec, 474 q31_t *pDst); 475 476 /** 477 * @brief Q31 matrix multiplication (fast variant) for Cortex-M3 and Cortex-M4 478 * @param[in] pSrcA points to the first input matrix structure 479 * @param[in] pSrcB points to the second input matrix structure 480 * @param[out] pDst points to output matrix structure 481 * @return The function returns either 482 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 483 */ 484 arm_status arm_mat_mult_fast_q31( 485 const arm_matrix_instance_q31 * pSrcA, 486 const arm_matrix_instance_q31 * pSrcB, 487 arm_matrix_instance_q31 * pDst); 488 489 /** 490 * @brief Floating-point matrix subtraction 491 * @param[in] pSrcA points to the first input matrix structure 492 * @param[in] pSrcB points to the second input matrix structure 493 * @param[out] pDst points to output matrix structure 494 * @return The function returns either 495 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 496 */ 497 arm_status arm_mat_sub_f32( 498 const arm_matrix_instance_f32 * pSrcA, 499 const arm_matrix_instance_f32 * pSrcB, 500 arm_matrix_instance_f32 * pDst); 501 502 /** 503 * @brief Floating-point matrix subtraction 504 * @param[in] pSrcA points to the first input matrix structure 505 * @param[in] pSrcB points to the second input matrix structure 506 * @param[out] pDst points to output matrix structure 507 * @return The function returns either 508 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 509 */ 510 arm_status arm_mat_sub_f64( 511 const arm_matrix_instance_f64 * pSrcA, 512 const arm_matrix_instance_f64 * pSrcB, 513 arm_matrix_instance_f64 * pDst); 514 515 /** 516 * @brief Q15 matrix subtraction 517 * @param[in] pSrcA points to the first input matrix structure 518 * @param[in] pSrcB points to the second input matrix structure 519 * @param[out] pDst points to output matrix structure 520 * @return The function returns either 521 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 522 */ 523 arm_status arm_mat_sub_q15( 524 const arm_matrix_instance_q15 * pSrcA, 525 const arm_matrix_instance_q15 * pSrcB, 526 arm_matrix_instance_q15 * pDst); 527 528 /** 529 * @brief Q31 matrix subtraction 530 * @param[in] pSrcA points to the first input matrix structure 531 * @param[in] pSrcB points to the second input matrix structure 532 * @param[out] pDst points to output matrix structure 533 * @return The function returns either 534 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 535 */ 536 arm_status arm_mat_sub_q31( 537 const arm_matrix_instance_q31 * pSrcA, 538 const arm_matrix_instance_q31 * pSrcB, 539 arm_matrix_instance_q31 * pDst); 540 541 /** 542 * @brief Floating-point matrix scaling. 543 * @param[in] pSrc points to the input matrix 544 * @param[in] scale scale factor 545 * @param[out] pDst points to the output matrix 546 * @return The function returns either 547 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 548 */ 549 arm_status arm_mat_scale_f32( 550 const arm_matrix_instance_f32 * pSrc, 551 float32_t scale, 552 arm_matrix_instance_f32 * pDst); 553 554 /** 555 * @brief Q15 matrix scaling. 556 * @param[in] pSrc points to input matrix 557 * @param[in] scaleFract fractional portion of the scale factor 558 * @param[in] shift number of bits to shift the result by 559 * @param[out] pDst points to output matrix 560 * @return The function returns either 561 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 562 */ 563 arm_status arm_mat_scale_q15( 564 const arm_matrix_instance_q15 * pSrc, 565 q15_t scaleFract, 566 int32_t shift, 567 arm_matrix_instance_q15 * pDst); 568 569 /** 570 * @brief Q31 matrix scaling. 571 * @param[in] pSrc points to input matrix 572 * @param[in] scaleFract fractional portion of the scale factor 573 * @param[in] shift number of bits to shift the result by 574 * @param[out] pDst points to output matrix structure 575 * @return The function returns either 576 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 577 */ 578 arm_status arm_mat_scale_q31( 579 const arm_matrix_instance_q31 * pSrc, 580 q31_t scaleFract, 581 int32_t shift, 582 arm_matrix_instance_q31 * pDst); 583 584 /** 585 * @brief Q31 matrix initialization. 586 * @param[in,out] S points to an instance of the floating-point matrix structure. 587 * @param[in] nRows number of rows in the matrix. 588 * @param[in] nColumns number of columns in the matrix. 589 * @param[in] pData points to the matrix data array. 590 */ 591 void arm_mat_init_q31( 592 arm_matrix_instance_q31 * S, 593 uint16_t nRows, 594 uint16_t nColumns, 595 q31_t * pData); 596 597 /** 598 * @brief Q15 matrix initialization. 599 * @param[in,out] S points to an instance of the floating-point matrix structure. 600 * @param[in] nRows number of rows in the matrix. 601 * @param[in] nColumns number of columns in the matrix. 602 * @param[in] pData points to the matrix data array. 603 */ 604 void arm_mat_init_q15( 605 arm_matrix_instance_q15 * S, 606 uint16_t nRows, 607 uint16_t nColumns, 608 q15_t * pData); 609 610 /** 611 * @brief Floating-point matrix initialization. 612 * @param[in,out] S points to an instance of the floating-point matrix structure. 613 * @param[in] nRows number of rows in the matrix. 614 * @param[in] nColumns number of columns in the matrix. 615 * @param[in] pData points to the matrix data array. 616 */ 617 void arm_mat_init_f32( 618 arm_matrix_instance_f32 * S, 619 uint16_t nRows, 620 uint16_t nColumns, 621 float32_t * pData); 622 623 /** 624 * @brief Floating-point matrix initialization. 625 * @param[in,out] S points to an instance of the floating-point matrix structure. 626 * @param[in] nRows number of rows in the matrix. 627 * @param[in] nColumns number of columns in the matrix. 628 * @param[in] pData points to the matrix data array. 629 */ 630 void arm_mat_init_f64( 631 arm_matrix_instance_f64 * S, 632 uint16_t nRows, 633 uint16_t nColumns, 634 float64_t * pData); 635 636 637 638 639 /** 640 * @brief Floating-point matrix inverse. 641 * @param[in] src points to the instance of the input floating-point matrix structure. 642 * @param[out] dst points to the instance of the output floating-point matrix structure. 643 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 644 * If the input matrix is singular (does not have an inverse), then the algorithm terminates and returns error status ARM_MATH_SINGULAR. 645 */ 646 arm_status arm_mat_inverse_f32( 647 const arm_matrix_instance_f32 * src, 648 arm_matrix_instance_f32 * dst); 649 650 651 /** 652 * @brief Floating-point matrix inverse. 653 * @param[in] src points to the instance of the input floating-point matrix structure. 654 * @param[out] dst points to the instance of the output floating-point matrix structure. 655 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 656 * If the input matrix is singular (does not have an inverse), then the algorithm terminates and returns error status ARM_MATH_SINGULAR. 657 */ 658 arm_status arm_mat_inverse_f64( 659 const arm_matrix_instance_f64 * src, 660 arm_matrix_instance_f64 * dst); 661 662 /** 663 * @brief Floating-point Cholesky decomposition of Symmetric Positive Definite Matrix. 664 * @param[in] src points to the instance of the input floating-point matrix structure. 665 * @param[out] dst points to the instance of the output floating-point matrix structure. 666 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 667 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 668 * If the matrix is ill conditioned or only semi-definite, then it is better using the LDL^t decomposition. 669 * The decomposition is returning a lower triangular matrix. 670 */ 671 arm_status arm_mat_cholesky_f64( 672 const arm_matrix_instance_f64 * src, 673 arm_matrix_instance_f64 * dst); 674 675 /** 676 * @brief Floating-point Cholesky decomposition of Symmetric Positive Definite Matrix. 677 * @param[in] src points to the instance of the input floating-point matrix structure. 678 * @param[out] dst points to the instance of the output floating-point matrix structure. 679 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 680 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 681 * If the matrix is ill conditioned or only semi-definite, then it is better using the LDL^t decomposition. 682 * The decomposition is returning a lower triangular matrix. 683 */ 684 arm_status arm_mat_cholesky_f32( 685 const arm_matrix_instance_f32 * src, 686 arm_matrix_instance_f32 * dst); 687 688 /** 689 * @brief Solve UT . X = A where UT is an upper triangular matrix 690 * @param[in] ut The upper triangular matrix 691 * @param[in] a The matrix a 692 * @param[out] dst The solution X of UT . X = A 693 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 694 */ 695 arm_status arm_mat_solve_upper_triangular_f32( 696 const arm_matrix_instance_f32 * ut, 697 const arm_matrix_instance_f32 * a, 698 arm_matrix_instance_f32 * dst); 699 700 /** 701 * @brief Solve LT . X = A where LT is a lower triangular matrix 702 * @param[in] lt The lower triangular matrix 703 * @param[in] a The matrix a 704 * @param[out] dst The solution X of LT . X = A 705 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 706 */ 707 arm_status arm_mat_solve_lower_triangular_f32( 708 const arm_matrix_instance_f32 * lt, 709 const arm_matrix_instance_f32 * a, 710 arm_matrix_instance_f32 * dst); 711 712 713 /** 714 * @brief Solve UT . X = A where UT is an upper triangular matrix 715 * @param[in] ut The upper triangular matrix 716 * @param[in] a The matrix a 717 * @param[out] dst The solution X of UT . X = A 718 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 719 */ 720 arm_status arm_mat_solve_upper_triangular_f64( 721 const arm_matrix_instance_f64 * ut, 722 const arm_matrix_instance_f64 * a, 723 arm_matrix_instance_f64 * dst); 724 725 /** 726 * @brief Solve LT . X = A where LT is a lower triangular matrix 727 * @param[in] lt The lower triangular matrix 728 * @param[in] a The matrix a 729 * @param[out] dst The solution X of LT . X = A 730 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 731 */ 732 arm_status arm_mat_solve_lower_triangular_f64( 733 const arm_matrix_instance_f64 * lt, 734 const arm_matrix_instance_f64 * a, 735 arm_matrix_instance_f64 * dst); 736 737 738 /** 739 * @brief Floating-point LDL decomposition of Symmetric Positive Semi-Definite Matrix. 740 * @param[in] src points to the instance of the input floating-point matrix structure. 741 * @param[out] l points to the instance of the output floating-point triangular matrix structure. 742 * @param[out] d points to the instance of the output floating-point diagonal matrix structure. 743 * @param[out] p points to the instance of the output floating-point permutation vector. 744 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 745 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 746 * The decomposition is returning a lower triangular matrix. 747 */ 748 arm_status arm_mat_ldlt_f32( 749 const arm_matrix_instance_f32 * src, 750 arm_matrix_instance_f32 * l, 751 arm_matrix_instance_f32 * d, 752 uint16_t * pp); 753 754 /** 755 * @brief Floating-point LDL decomposition of Symmetric Positive Semi-Definite Matrix. 756 * @param[in] src points to the instance of the input floating-point matrix structure. 757 * @param[out] l points to the instance of the output floating-point triangular matrix structure. 758 * @param[out] d points to the instance of the output floating-point diagonal matrix structure. 759 * @param[out] p points to the instance of the output floating-point permutation vector. 760 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 761 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 762 * The decomposition is returning a lower triangular matrix. 763 */ 764 arm_status arm_mat_ldlt_f64( 765 const arm_matrix_instance_f64 * src, 766 arm_matrix_instance_f64 * l, 767 arm_matrix_instance_f64 * d, 768 uint16_t * pp); 769 770 /** 771 @brief QR decomposition of a m x n floating point matrix with m >= n. 772 @param[in] pSrc points to input matrix structure. The source matrix is modified by the function. 773 @param[in] threshold norm2 threshold. 774 @param[out] pOutR points to output R matrix structure of dimension m x n 775 @param[out] pOutQ points to output Q matrix structure of dimension m x m 776 @param[out] pOutTau points to Householder scaling factors of dimension n 777 @param[inout] pTmpA points to a temporary vector of dimension m. 778 @param[inout] pTmpB points to a temporary vector of dimension n. 779 @return execution status 780 - \ref ARM_MATH_SUCCESS : Operation successful 781 - \ref ARM_MATH_SIZE_MISMATCH : Matrix size check failed 782 - \ref ARM_MATH_SINGULAR : Input matrix is found to be singular (non-invertible) 783 */ 784 785 arm_status arm_mat_qr_f32( 786 const arm_matrix_instance_f32 * pSrc, 787 const float32_t threshold, 788 arm_matrix_instance_f32 * pOutR, 789 arm_matrix_instance_f32 * pOutQ, 790 float32_t * pOutTau, 791 float32_t *pTmpA, 792 float32_t *pTmpB 793 ); 794 795 /** 796 @brief QR decomposition of a m x n floating point matrix with m >= n. 797 @param[in] pSrc points to input matrix structure. The source matrix is modified by the function. 798 @param[in] threshold norm2 threshold. 799 @param[out] pOutR points to output R matrix structure of dimension m x n 800 @param[out] pOutQ points to output Q matrix structure of dimension m x m 801 @param[out] pOutTau points to Householder scaling factors of dimension n 802 @param[inout] pTmpA points to a temporary vector of dimension m. 803 @param[inout] pTmpB points to a temporary vector of dimension n. 804 @return execution status 805 - \ref ARM_MATH_SUCCESS : Operation successful 806 - \ref ARM_MATH_SIZE_MISMATCH : Matrix size check failed 807 - \ref ARM_MATH_SINGULAR : Input matrix is found to be singular (non-invertible) 808 */ 809 810 arm_status arm_mat_qr_f64( 811 const arm_matrix_instance_f64 * pSrc, 812 const float64_t threshold, 813 arm_matrix_instance_f64 * pOutR, 814 arm_matrix_instance_f64 * pOutQ, 815 float64_t * pOutTau, 816 float64_t *pTmpA, 817 float64_t *pTmpB 818 ); 819 820 /** 821 @brief Householder transform of a floating point vector. 822 @param[in] pSrc points to the input vector. 823 @param[in] threshold norm2 threshold. 824 @param[in] blockSize dimension of the vector space. 825 @param[outQ] pOut points to the output vector. 826 @return beta return the scaling factor beta 827 */ 828 829 float32_t arm_householder_f32( 830 const float32_t * pSrc, 831 const float32_t threshold, 832 uint32_t blockSize, 833 float32_t * pOut 834 ); 835 836 /** 837 @brief Householder transform of a double floating point vector. 838 @param[in] pSrc points to the input vector. 839 @param[in] threshold norm2 threshold. 840 @param[in] blockSize dimension of the vector space. 841 @param[outQ] pOut points to the output vector. 842 @return beta return the scaling factor beta 843 */ 844 845 float64_t arm_householder_f64( 846 const float64_t * pSrc, 847 const float64_t threshold, 848 uint32_t blockSize, 849 float64_t * pOut 850 ); 851 852 #ifdef __cplusplus 853 } 854 #endif 855 856 #endif /* ifndef _MATRIX_FUNCTIONS_H_ */ 857