matrix_functions.h
1 /****************************************************************************** 2 * @file matrix_functions.h 3 * @brief Public header file for CMSIS DSP Library 4 * @version V1.10.0 5 * @date 08 July 2021 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 /** 113 * @brief Instance structure for the floating-point matrix structure. 114 */ 115 typedef struct 116 { 117 uint16_t numRows; /**< number of rows of the matrix. */ 118 uint16_t numCols; /**< number of columns of the matrix. */ 119 float32_t *pData; /**< points to the data of the matrix. */ 120 } arm_matrix_instance_f32; 121 122 /** 123 * @brief Instance structure for the floating-point matrix structure. 124 */ 125 typedef struct 126 { 127 uint16_t numRows; /**< number of rows of the matrix. */ 128 uint16_t numCols; /**< number of columns of the matrix. */ 129 float64_t *pData; /**< points to the data of the matrix. */ 130 } arm_matrix_instance_f64; 131 132 /** 133 * @brief Instance structure for the Q7 matrix structure. 134 */ 135 typedef struct 136 { 137 uint16_t numRows; /**< number of rows of the matrix. */ 138 uint16_t numCols; /**< number of columns of the matrix. */ 139 q7_t *pData; /**< points to the data of the matrix. */ 140 } arm_matrix_instance_q7; 141 142 /** 143 * @brief Instance structure for the Q15 matrix structure. 144 */ 145 typedef struct 146 { 147 uint16_t numRows; /**< number of rows of the matrix. */ 148 uint16_t numCols; /**< number of columns of the matrix. */ 149 q15_t *pData; /**< points to the data of the matrix. */ 150 } arm_matrix_instance_q15; 151 152 /** 153 * @brief Instance structure for the Q31 matrix structure. 154 */ 155 typedef struct 156 { 157 uint16_t numRows; /**< number of rows of the matrix. */ 158 uint16_t numCols; /**< number of columns of the matrix. */ 159 q31_t *pData; /**< points to the data of the matrix. */ 160 } arm_matrix_instance_q31; 161 162 /** 163 * @brief Floating-point matrix addition. 164 * @param[in] pSrcA points to the first input matrix structure 165 * @param[in] pSrcB points to the second input matrix structure 166 * @param[out] pDst points to output matrix structure 167 * @return The function returns either 168 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 169 */ 170 arm_status arm_mat_add_f32( 171 const arm_matrix_instance_f32 * pSrcA, 172 const arm_matrix_instance_f32 * pSrcB, 173 arm_matrix_instance_f32 * pDst); 174 175 /** 176 * @brief Q15 matrix addition. 177 * @param[in] pSrcA points to the first input matrix structure 178 * @param[in] pSrcB points to the second input matrix structure 179 * @param[out] pDst points to output matrix structure 180 * @return The function returns either 181 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 182 */ 183 arm_status arm_mat_add_q15( 184 const arm_matrix_instance_q15 * pSrcA, 185 const arm_matrix_instance_q15 * pSrcB, 186 arm_matrix_instance_q15 * pDst); 187 188 /** 189 * @brief Q31 matrix addition. 190 * @param[in] pSrcA points to the first input matrix structure 191 * @param[in] pSrcB points to the second input matrix structure 192 * @param[out] pDst points to output matrix structure 193 * @return The function returns either 194 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 195 */ 196 arm_status arm_mat_add_q31( 197 const arm_matrix_instance_q31 * pSrcA, 198 const arm_matrix_instance_q31 * pSrcB, 199 arm_matrix_instance_q31 * pDst); 200 201 /** 202 * @brief Floating-point, complex, matrix multiplication. 203 * @param[in] pSrcA points to the first input matrix structure 204 * @param[in] pSrcB points to the second input matrix structure 205 * @param[out] pDst points to output matrix structure 206 * @return The function returns either 207 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 208 */ 209 arm_status arm_mat_cmplx_mult_f32( 210 const arm_matrix_instance_f32 * pSrcA, 211 const arm_matrix_instance_f32 * pSrcB, 212 arm_matrix_instance_f32 * pDst); 213 214 /** 215 * @brief Q15, complex, matrix multiplication. 216 * @param[in] pSrcA points to the first input matrix structure 217 * @param[in] pSrcB points to the second input matrix structure 218 * @param[out] pDst points to output matrix structure 219 * @return The function returns either 220 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 221 */ 222 arm_status arm_mat_cmplx_mult_q15( 223 const arm_matrix_instance_q15 * pSrcA, 224 const arm_matrix_instance_q15 * pSrcB, 225 arm_matrix_instance_q15 * pDst, 226 q15_t * pScratch); 227 228 /** 229 * @brief Q31, complex, matrix multiplication. 230 * @param[in] pSrcA points to the first input matrix structure 231 * @param[in] pSrcB points to the second input matrix structure 232 * @param[out] pDst points to output matrix structure 233 * @return The function returns either 234 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 235 */ 236 arm_status arm_mat_cmplx_mult_q31( 237 const arm_matrix_instance_q31 * pSrcA, 238 const arm_matrix_instance_q31 * pSrcB, 239 arm_matrix_instance_q31 * pDst); 240 241 /** 242 * @brief Floating-point matrix transpose. 243 * @param[in] pSrc points to the input matrix 244 * @param[out] pDst points to the output matrix 245 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 246 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 247 */ 248 arm_status arm_mat_trans_f32( 249 const arm_matrix_instance_f32 * pSrc, 250 arm_matrix_instance_f32 * pDst); 251 252 /** 253 * @brief Floating-point matrix transpose. 254 * @param[in] pSrc points to the input matrix 255 * @param[out] pDst points to the output matrix 256 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 257 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 258 */ 259 arm_status arm_mat_trans_f64( 260 const arm_matrix_instance_f64 * pSrc, 261 arm_matrix_instance_f64 * pDst); 262 263 /** 264 * @brief Floating-point complex matrix transpose. 265 * @param[in] pSrc points to the input matrix 266 * @param[out] pDst points to the output matrix 267 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 268 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 269 */ 270 arm_status arm_mat_cmplx_trans_f32( 271 const arm_matrix_instance_f32 * pSrc, 272 arm_matrix_instance_f32 * pDst); 273 274 275 /** 276 * @brief Q15 matrix transpose. 277 * @param[in] pSrc points to the input matrix 278 * @param[out] pDst points to the output matrix 279 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 280 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 281 */ 282 arm_status arm_mat_trans_q15( 283 const arm_matrix_instance_q15 * pSrc, 284 arm_matrix_instance_q15 * pDst); 285 286 /** 287 * @brief Q15 complex matrix transpose. 288 * @param[in] pSrc points to the input matrix 289 * @param[out] pDst points to the output matrix 290 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 291 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 292 */ 293 arm_status arm_mat_cmplx_trans_q15( 294 const arm_matrix_instance_q15 * pSrc, 295 arm_matrix_instance_q15 * pDst); 296 297 /** 298 * @brief Q7 matrix transpose. 299 * @param[in] pSrc points to the input matrix 300 * @param[out] pDst points to the output matrix 301 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 302 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 303 */ 304 arm_status arm_mat_trans_q7( 305 const arm_matrix_instance_q7 * pSrc, 306 arm_matrix_instance_q7 * pDst); 307 308 /** 309 * @brief Q31 matrix transpose. 310 * @param[in] pSrc points to the input matrix 311 * @param[out] pDst points to the output matrix 312 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 313 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 314 */ 315 arm_status arm_mat_trans_q31( 316 const arm_matrix_instance_q31 * pSrc, 317 arm_matrix_instance_q31 * pDst); 318 319 /** 320 * @brief Q31 complex matrix transpose. 321 * @param[in] pSrc points to the input matrix 322 * @param[out] pDst points to the output matrix 323 * @return The function returns either <code>ARM_MATH_SIZE_MISMATCH</code> 324 * or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 325 */ 326 arm_status arm_mat_cmplx_trans_q31( 327 const arm_matrix_instance_q31 * pSrc, 328 arm_matrix_instance_q31 * pDst); 329 330 /** 331 * @brief Floating-point matrix multiplication 332 * @param[in] pSrcA points to the first input matrix structure 333 * @param[in] pSrcB points to the second input matrix structure 334 * @param[out] pDst points to output matrix structure 335 * @return The function returns either 336 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 337 */ 338 arm_status arm_mat_mult_f32( 339 const arm_matrix_instance_f32 * pSrcA, 340 const arm_matrix_instance_f32 * pSrcB, 341 arm_matrix_instance_f32 * pDst); 342 343 /** 344 * @brief Floating-point matrix multiplication 345 * @param[in] pSrcA points to the first input matrix structure 346 * @param[in] pSrcB points to the second input matrix structure 347 * @param[out] pDst points to output matrix structure 348 * @return The function returns either 349 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 350 */ 351 arm_status arm_mat_mult_f64( 352 const arm_matrix_instance_f64 * pSrcA, 353 const arm_matrix_instance_f64 * pSrcB, 354 arm_matrix_instance_f64 * pDst); 355 356 /** 357 * @brief Floating-point matrix and vector multiplication 358 * @param[in] pSrcMat points to the input matrix structure 359 * @param[in] pVec points to vector 360 * @param[out] pDst points to output vector 361 */ 362 void arm_mat_vec_mult_f32( 363 const arm_matrix_instance_f32 *pSrcMat, 364 const float32_t *pVec, 365 float32_t *pDst); 366 367 /** 368 * @brief Q7 matrix multiplication 369 * @param[in] pSrcA points to the first input matrix structure 370 * @param[in] pSrcB points to the second input matrix structure 371 * @param[out] pDst points to output matrix structure 372 * @param[in] pState points to the array for storing intermediate results 373 * @return The function returns either 374 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 375 */ 376 arm_status arm_mat_mult_q7( 377 const arm_matrix_instance_q7 * pSrcA, 378 const arm_matrix_instance_q7 * pSrcB, 379 arm_matrix_instance_q7 * pDst, 380 q7_t * pState); 381 382 /** 383 * @brief Q7 matrix and vector multiplication 384 * @param[in] pSrcMat points to the input matrix structure 385 * @param[in] pVec points to vector 386 * @param[out] pDst points to output vector 387 */ 388 void arm_mat_vec_mult_q7( 389 const arm_matrix_instance_q7 *pSrcMat, 390 const q7_t *pVec, 391 q7_t *pDst); 392 393 /** 394 * @brief Q15 matrix multiplication 395 * @param[in] pSrcA points to the first input matrix structure 396 * @param[in] pSrcB points to the second input matrix structure 397 * @param[out] pDst points to output matrix structure 398 * @param[in] pState points to the array for storing intermediate results 399 * @return The function returns either 400 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 401 */ 402 arm_status arm_mat_mult_q15( 403 const arm_matrix_instance_q15 * pSrcA, 404 const arm_matrix_instance_q15 * pSrcB, 405 arm_matrix_instance_q15 * pDst, 406 q15_t * pState); 407 408 /** 409 * @brief Q15 matrix and vector multiplication 410 * @param[in] pSrcMat points to the input matrix structure 411 * @param[in] pVec points to vector 412 * @param[out] pDst points to output vector 413 */ 414 void arm_mat_vec_mult_q15( 415 const arm_matrix_instance_q15 *pSrcMat, 416 const q15_t *pVec, 417 q15_t *pDst); 418 419 /** 420 * @brief Q15 matrix multiplication (fast variant) for Cortex-M3 and Cortex-M4 421 * @param[in] pSrcA points to the first input matrix structure 422 * @param[in] pSrcB points to the second input matrix structure 423 * @param[out] pDst points to output matrix structure 424 * @param[in] pState points to the array for storing intermediate results 425 * @return The function returns either 426 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 427 */ 428 arm_status arm_mat_mult_fast_q15( 429 const arm_matrix_instance_q15 * pSrcA, 430 const arm_matrix_instance_q15 * pSrcB, 431 arm_matrix_instance_q15 * pDst, 432 q15_t * pState); 433 434 /** 435 * @brief Q31 matrix multiplication 436 * @param[in] pSrcA points to the first input matrix structure 437 * @param[in] pSrcB points to the second input matrix structure 438 * @param[out] pDst points to output matrix structure 439 * @return The function returns either 440 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 441 */ 442 arm_status arm_mat_mult_q31( 443 const arm_matrix_instance_q31 * pSrcA, 444 const arm_matrix_instance_q31 * pSrcB, 445 arm_matrix_instance_q31 * pDst); 446 447 /** 448 * @brief Q31 matrix multiplication 449 * @param[in] pSrcA points to the first input matrix structure 450 * @param[in] pSrcB points to the second input matrix structure 451 * @param[out] pDst points to output matrix structure 452 * @param[in] pState points to the array for storing intermediate results 453 * @return The function returns either 454 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 455 */ 456 arm_status arm_mat_mult_opt_q31( 457 const arm_matrix_instance_q31 * pSrcA, 458 const arm_matrix_instance_q31 * pSrcB, 459 arm_matrix_instance_q31 * pDst, 460 q31_t *pState); 461 462 /** 463 * @brief Q31 matrix and vector multiplication 464 * @param[in] pSrcMat points to the input matrix structure 465 * @param[in] pVec points to vector 466 * @param[out] pDst points to output vector 467 */ 468 void arm_mat_vec_mult_q31( 469 const arm_matrix_instance_q31 *pSrcMat, 470 const q31_t *pVec, 471 q31_t *pDst); 472 473 /** 474 * @brief Q31 matrix multiplication (fast variant) for Cortex-M3 and Cortex-M4 475 * @param[in] pSrcA points to the first input matrix structure 476 * @param[in] pSrcB points to the second input matrix structure 477 * @param[out] pDst points to output matrix structure 478 * @return The function returns either 479 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 480 */ 481 arm_status arm_mat_mult_fast_q31( 482 const arm_matrix_instance_q31 * pSrcA, 483 const arm_matrix_instance_q31 * pSrcB, 484 arm_matrix_instance_q31 * pDst); 485 486 /** 487 * @brief Floating-point matrix subtraction 488 * @param[in] pSrcA points to the first input matrix structure 489 * @param[in] pSrcB points to the second input matrix structure 490 * @param[out] pDst points to output matrix structure 491 * @return The function returns either 492 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 493 */ 494 arm_status arm_mat_sub_f32( 495 const arm_matrix_instance_f32 * pSrcA, 496 const arm_matrix_instance_f32 * pSrcB, 497 arm_matrix_instance_f32 * pDst); 498 499 /** 500 * @brief Floating-point matrix subtraction 501 * @param[in] pSrcA points to the first input matrix structure 502 * @param[in] pSrcB points to the second input matrix structure 503 * @param[out] pDst points to output matrix structure 504 * @return The function returns either 505 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 506 */ 507 arm_status arm_mat_sub_f64( 508 const arm_matrix_instance_f64 * pSrcA, 509 const arm_matrix_instance_f64 * pSrcB, 510 arm_matrix_instance_f64 * pDst); 511 512 /** 513 * @brief Q15 matrix subtraction 514 * @param[in] pSrcA points to the first input matrix structure 515 * @param[in] pSrcB points to the second input matrix structure 516 * @param[out] pDst points to output matrix structure 517 * @return The function returns either 518 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 519 */ 520 arm_status arm_mat_sub_q15( 521 const arm_matrix_instance_q15 * pSrcA, 522 const arm_matrix_instance_q15 * pSrcB, 523 arm_matrix_instance_q15 * pDst); 524 525 /** 526 * @brief Q31 matrix subtraction 527 * @param[in] pSrcA points to the first input matrix structure 528 * @param[in] pSrcB points to the second input matrix structure 529 * @param[out] pDst points to output matrix structure 530 * @return The function returns either 531 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 532 */ 533 arm_status arm_mat_sub_q31( 534 const arm_matrix_instance_q31 * pSrcA, 535 const arm_matrix_instance_q31 * pSrcB, 536 arm_matrix_instance_q31 * pDst); 537 538 /** 539 * @brief Floating-point matrix scaling. 540 * @param[in] pSrc points to the input matrix 541 * @param[in] scale scale factor 542 * @param[out] pDst points to the output matrix 543 * @return The function returns either 544 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 545 */ 546 arm_status arm_mat_scale_f32( 547 const arm_matrix_instance_f32 * pSrc, 548 float32_t scale, 549 arm_matrix_instance_f32 * pDst); 550 551 /** 552 * @brief Q15 matrix scaling. 553 * @param[in] pSrc points to input matrix 554 * @param[in] scaleFract fractional portion of the scale factor 555 * @param[in] shift number of bits to shift the result by 556 * @param[out] pDst points to output matrix 557 * @return The function returns either 558 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 559 */ 560 arm_status arm_mat_scale_q15( 561 const arm_matrix_instance_q15 * pSrc, 562 q15_t scaleFract, 563 int32_t shift, 564 arm_matrix_instance_q15 * pDst); 565 566 /** 567 * @brief Q31 matrix scaling. 568 * @param[in] pSrc points to input matrix 569 * @param[in] scaleFract fractional portion of the scale factor 570 * @param[in] shift number of bits to shift the result by 571 * @param[out] pDst points to output matrix structure 572 * @return The function returns either 573 * <code>ARM_MATH_SIZE_MISMATCH</code> or <code>ARM_MATH_SUCCESS</code> based on the outcome of size checking. 574 */ 575 arm_status arm_mat_scale_q31( 576 const arm_matrix_instance_q31 * pSrc, 577 q31_t scaleFract, 578 int32_t shift, 579 arm_matrix_instance_q31 * pDst); 580 581 /** 582 * @brief Q31 matrix initialization. 583 * @param[in,out] S points to an instance of the floating-point matrix structure. 584 * @param[in] nRows number of rows in the matrix. 585 * @param[in] nColumns number of columns in the matrix. 586 * @param[in] pData points to the matrix data array. 587 */ 588 void arm_mat_init_q31( 589 arm_matrix_instance_q31 * S, 590 uint16_t nRows, 591 uint16_t nColumns, 592 q31_t * pData); 593 594 /** 595 * @brief Q15 matrix initialization. 596 * @param[in,out] S points to an instance of the floating-point matrix structure. 597 * @param[in] nRows number of rows in the matrix. 598 * @param[in] nColumns number of columns in the matrix. 599 * @param[in] pData points to the matrix data array. 600 */ 601 void arm_mat_init_q15( 602 arm_matrix_instance_q15 * S, 603 uint16_t nRows, 604 uint16_t nColumns, 605 q15_t * pData); 606 607 /** 608 * @brief Floating-point matrix initialization. 609 * @param[in,out] S points to an instance of the floating-point matrix structure. 610 * @param[in] nRows number of rows in the matrix. 611 * @param[in] nColumns number of columns in the matrix. 612 * @param[in] pData points to the matrix data array. 613 */ 614 void arm_mat_init_f32( 615 arm_matrix_instance_f32 * S, 616 uint16_t nRows, 617 uint16_t nColumns, 618 float32_t * pData); 619 620 621 622 /** 623 * @brief Floating-point matrix inverse. 624 * @param[in] src points to the instance of the input floating-point matrix structure. 625 * @param[out] dst points to the instance of the output floating-point matrix structure. 626 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 627 * If the input matrix is singular (does not have an inverse), then the algorithm terminates and returns error status ARM_MATH_SINGULAR. 628 */ 629 arm_status arm_mat_inverse_f32( 630 const arm_matrix_instance_f32 * src, 631 arm_matrix_instance_f32 * dst); 632 633 634 /** 635 * @brief Floating-point matrix inverse. 636 * @param[in] src points to the instance of the input floating-point matrix structure. 637 * @param[out] dst points to the instance of the output floating-point matrix structure. 638 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 639 * If the input matrix is singular (does not have an inverse), then the algorithm terminates and returns error status ARM_MATH_SINGULAR. 640 */ 641 arm_status arm_mat_inverse_f64( 642 const arm_matrix_instance_f64 * src, 643 arm_matrix_instance_f64 * dst); 644 645 /** 646 * @brief Floating-point Cholesky decomposition of Symmetric Positive Definite Matrix. 647 * @param[in] src points to the instance of the input floating-point matrix structure. 648 * @param[out] dst points to the instance of the output floating-point matrix structure. 649 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 650 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 651 * If the matrix is ill conditioned or only semi-definite, then it is better using the LDL^t decomposition. 652 * The decomposition is returning a lower triangular matrix. 653 */ 654 arm_status arm_mat_cholesky_f64( 655 const arm_matrix_instance_f64 * src, 656 arm_matrix_instance_f64 * dst); 657 658 /** 659 * @brief Floating-point Cholesky decomposition of Symmetric Positive Definite Matrix. 660 * @param[in] src points to the instance of the input floating-point matrix structure. 661 * @param[out] dst points to the instance of the output floating-point matrix structure. 662 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 663 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 664 * If the matrix is ill conditioned or only semi-definite, then it is better using the LDL^t decomposition. 665 * The decomposition is returning a lower triangular matrix. 666 */ 667 arm_status arm_mat_cholesky_f32( 668 const arm_matrix_instance_f32 * src, 669 arm_matrix_instance_f32 * dst); 670 671 /** 672 * @brief Solve UT . X = A where UT is an upper triangular matrix 673 * @param[in] ut The upper triangular matrix 674 * @param[in] a The matrix a 675 * @param[out] dst The solution X of UT . X = A 676 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 677 */ 678 arm_status arm_mat_solve_upper_triangular_f32( 679 const arm_matrix_instance_f32 * ut, 680 const arm_matrix_instance_f32 * a, 681 arm_matrix_instance_f32 * dst); 682 683 /** 684 * @brief Solve LT . X = A where LT is a lower triangular matrix 685 * @param[in] lt The lower triangular matrix 686 * @param[in] a The matrix a 687 * @param[out] dst The solution X of LT . X = A 688 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 689 */ 690 arm_status arm_mat_solve_lower_triangular_f32( 691 const arm_matrix_instance_f32 * lt, 692 const arm_matrix_instance_f32 * a, 693 arm_matrix_instance_f32 * dst); 694 695 696 /** 697 * @brief Solve UT . X = A where UT is an upper triangular matrix 698 * @param[in] ut The upper triangular matrix 699 * @param[in] a The matrix a 700 * @param[out] dst The solution X of UT . X = A 701 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 702 */ 703 arm_status arm_mat_solve_upper_triangular_f64( 704 const arm_matrix_instance_f64 * ut, 705 const arm_matrix_instance_f64 * a, 706 arm_matrix_instance_f64 * dst); 707 708 /** 709 * @brief Solve LT . X = A where LT is a lower triangular matrix 710 * @param[in] lt The lower triangular matrix 711 * @param[in] a The matrix a 712 * @param[out] dst The solution X of LT . X = A 713 * @return The function returns ARM_MATH_SINGULAR, if the system can't be solved. 714 */ 715 arm_status arm_mat_solve_lower_triangular_f64( 716 const arm_matrix_instance_f64 * lt, 717 const arm_matrix_instance_f64 * a, 718 arm_matrix_instance_f64 * dst); 719 720 721 /** 722 * @brief Floating-point LDL decomposition of Symmetric Positive Semi-Definite Matrix. 723 * @param[in] src points to the instance of the input floating-point matrix structure. 724 * @param[out] l points to the instance of the output floating-point triangular matrix structure. 725 * @param[out] d points to the instance of the output floating-point diagonal matrix structure. 726 * @param[out] p points to the instance of the output floating-point permutation vector. 727 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 728 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 729 * The decomposition is returning a lower triangular matrix. 730 */ 731 arm_status arm_mat_ldlt_f32( 732 const arm_matrix_instance_f32 * src, 733 arm_matrix_instance_f32 * l, 734 arm_matrix_instance_f32 * d, 735 uint16_t * pp); 736 737 /** 738 * @brief Floating-point LDL decomposition of Symmetric Positive Semi-Definite Matrix. 739 * @param[in] src points to the instance of the input floating-point matrix structure. 740 * @param[out] l points to the instance of the output floating-point triangular matrix structure. 741 * @param[out] d points to the instance of the output floating-point diagonal matrix structure. 742 * @param[out] p points to the instance of the output floating-point permutation vector. 743 * @return The function returns ARM_MATH_SIZE_MISMATCH, if the dimensions do not match. 744 * If the input matrix does not have a decomposition, then the algorithm terminates and returns error status ARM_MATH_DECOMPOSITION_FAILURE. 745 * The decomposition is returning a lower triangular matrix. 746 */ 747 arm_status arm_mat_ldlt_f64( 748 const arm_matrix_instance_f64 * src, 749 arm_matrix_instance_f64 * l, 750 arm_matrix_instance_f64 * d, 751 uint16_t * pp); 752 753 #ifdef __cplusplus 754 } 755 #endif 756 757 #endif /* ifndef _MATRIX_FUNCTIONS_H_ */