1 /****************************************************************************** 2 * @file statistics_functions.h 3 * @brief Public header file for CMSIS DSP Library 4 * @version V1.9.0 5 * @date 23 April 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 _STATISTICS_FUNCTIONS_H_ 28 #define _STATISTICS_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 #include "dsp/basic_math_functions.h" 37 #include "dsp/fast_math_functions.h" 38 39 #ifdef __cplusplus 40 extern "C" 41 { 42 #endif 43 44 45 /** 46 * @defgroup groupStats Statistics Functions 47 */ 48 49 /** 50 * @brief Computation of the LogSumExp 51 * 52 * In probabilistic computations, the dynamic of the probability values can be very 53 * wide because they come from gaussian functions. 54 * To avoid underflow and overflow issues, the values are represented by their log. 55 * In this representation, multiplying the original exp values is easy : their logs are added. 56 * But adding the original exp values is requiring some special handling and it is the 57 * goal of the LogSumExp function. 58 * 59 * If the values are x1...xn, the function is computing: 60 * 61 * ln(exp(x1) + ... + exp(xn)) and the computation is done in such a way that 62 * rounding issues are minimised. 63 * 64 * The max xm of the values is extracted and the function is computing: 65 * xm + ln(exp(x1 - xm) + ... + exp(xn - xm)) 66 * 67 * @param[in] *in Pointer to an array of input values. 68 * @param[in] blockSize Number of samples in the input array. 69 * @return LogSumExp 70 * 71 */ 72 73 74 float32_t arm_logsumexp_f32(const float32_t *in, uint32_t blockSize); 75 76 /** 77 * @brief Dot product with log arithmetic 78 * 79 * Vectors are containing the log of the samples 80 * 81 * @param[in] pSrcA points to the first input vector 82 * @param[in] pSrcB points to the second input vector 83 * @param[in] blockSize number of samples in each vector 84 * @param[in] pTmpBuffer temporary buffer of length blockSize 85 * @return The log of the dot product . 86 * 87 */ 88 89 90 float32_t arm_logsumexp_dot_prod_f32(const float32_t * pSrcA, 91 const float32_t * pSrcB, 92 uint32_t blockSize, 93 float32_t *pTmpBuffer); 94 95 /** 96 * @brief Entropy 97 * 98 * @param[in] pSrcA Array of input values. 99 * @param[in] blockSize Number of samples in the input array. 100 * @return Entropy -Sum(p ln p) 101 * 102 */ 103 104 105 float32_t arm_entropy_f32(const float32_t * pSrcA,uint32_t blockSize); 106 107 108 /** 109 * @brief Entropy 110 * 111 * @param[in] pSrcA Array of input values. 112 * @param[in] blockSize Number of samples in the input array. 113 * @return Entropy -Sum(p ln p) 114 * 115 */ 116 117 118 float64_t arm_entropy_f64(const float64_t * pSrcA, uint32_t blockSize); 119 120 121 /** 122 * @brief Kullback-Leibler 123 * 124 * @param[in] pSrcA Pointer to an array of input values for probability distribution A. 125 * @param[in] pSrcB Pointer to an array of input values for probability distribution B. 126 * @param[in] blockSize Number of samples in the input array. 127 * @return Kullback-Leibler Divergence D(A || B) 128 * 129 */ 130 float32_t arm_kullback_leibler_f32(const float32_t * pSrcA 131 ,const float32_t * pSrcB 132 ,uint32_t blockSize); 133 134 135 /** 136 * @brief Kullback-Leibler 137 * 138 * @param[in] pSrcA Pointer to an array of input values for probability distribution A. 139 * @param[in] pSrcB Pointer to an array of input values for probability distribution B. 140 * @param[in] blockSize Number of samples in the input array. 141 * @return Kullback-Leibler Divergence D(A || B) 142 * 143 */ 144 float64_t arm_kullback_leibler_f64(const float64_t * pSrcA, 145 const float64_t * pSrcB, 146 uint32_t blockSize); 147 148 149 /** 150 * @brief Sum of the squares of the elements of a Q31 vector. 151 * @param[in] pSrc is input pointer 152 * @param[in] blockSize is the number of samples to process 153 * @param[out] pResult is output value. 154 */ 155 void arm_power_q31( 156 const q31_t * pSrc, 157 uint32_t blockSize, 158 q63_t * pResult); 159 160 161 /** 162 * @brief Sum of the squares of the elements of a floating-point vector. 163 * @param[in] pSrc is input pointer 164 * @param[in] blockSize is the number of samples to process 165 * @param[out] pResult is output value. 166 */ 167 void arm_power_f32( 168 const float32_t * pSrc, 169 uint32_t blockSize, 170 float32_t * pResult); 171 172 173 /** 174 * @brief Sum of the squares of the elements of a Q15 vector. 175 * @param[in] pSrc is input pointer 176 * @param[in] blockSize is the number of samples to process 177 * @param[out] pResult is output value. 178 */ 179 void arm_power_q15( 180 const q15_t * pSrc, 181 uint32_t blockSize, 182 q63_t * pResult); 183 184 185 /** 186 * @brief Sum of the squares of the elements of a Q7 vector. 187 * @param[in] pSrc is input pointer 188 * @param[in] blockSize is the number of samples to process 189 * @param[out] pResult is output value. 190 */ 191 void arm_power_q7( 192 const q7_t * pSrc, 193 uint32_t blockSize, 194 q31_t * pResult); 195 196 197 /** 198 * @brief Mean value of a Q7 vector. 199 * @param[in] pSrc is input pointer 200 * @param[in] blockSize is the number of samples to process 201 * @param[out] pResult is output value. 202 */ 203 void arm_mean_q7( 204 const q7_t * pSrc, 205 uint32_t blockSize, 206 q7_t * pResult); 207 208 209 /** 210 * @brief Mean value of a Q15 vector. 211 * @param[in] pSrc is input pointer 212 * @param[in] blockSize is the number of samples to process 213 * @param[out] pResult is output value. 214 */ 215 void arm_mean_q15( 216 const q15_t * pSrc, 217 uint32_t blockSize, 218 q15_t * pResult); 219 220 221 /** 222 * @brief Mean value of a Q31 vector. 223 * @param[in] pSrc is input pointer 224 * @param[in] blockSize is the number of samples to process 225 * @param[out] pResult is output value. 226 */ 227 void arm_mean_q31( 228 const q31_t * pSrc, 229 uint32_t blockSize, 230 q31_t * pResult); 231 232 233 /** 234 * @brief Mean value of a floating-point vector. 235 * @param[in] pSrc is input pointer 236 * @param[in] blockSize is the number of samples to process 237 * @param[out] pResult is output value. 238 */ 239 void arm_mean_f32( 240 const float32_t * pSrc, 241 uint32_t blockSize, 242 float32_t * pResult); 243 244 245 /** 246 * @brief Variance of the elements of a floating-point vector. 247 * @param[in] pSrc is input pointer 248 * @param[in] blockSize is the number of samples to process 249 * @param[out] pResult is output value. 250 */ 251 void arm_var_f32( 252 const float32_t * pSrc, 253 uint32_t blockSize, 254 float32_t * pResult); 255 256 257 /** 258 * @brief Variance of the elements of a Q31 vector. 259 * @param[in] pSrc is input pointer 260 * @param[in] blockSize is the number of samples to process 261 * @param[out] pResult is output value. 262 */ 263 void arm_var_q31( 264 const q31_t * pSrc, 265 uint32_t blockSize, 266 q31_t * pResult); 267 268 269 /** 270 * @brief Variance of the elements of a Q15 vector. 271 * @param[in] pSrc is input pointer 272 * @param[in] blockSize is the number of samples to process 273 * @param[out] pResult is output value. 274 */ 275 void arm_var_q15( 276 const q15_t * pSrc, 277 uint32_t blockSize, 278 q15_t * pResult); 279 280 281 /** 282 * @brief Root Mean Square of the elements of a floating-point vector. 283 * @param[in] pSrc is input pointer 284 * @param[in] blockSize is the number of samples to process 285 * @param[out] pResult is output value. 286 */ 287 void arm_rms_f32( 288 const float32_t * pSrc, 289 uint32_t blockSize, 290 float32_t * pResult); 291 292 293 /** 294 * @brief Root Mean Square of the elements of a Q31 vector. 295 * @param[in] pSrc is input pointer 296 * @param[in] blockSize is the number of samples to process 297 * @param[out] pResult is output value. 298 */ 299 void arm_rms_q31( 300 const q31_t * pSrc, 301 uint32_t blockSize, 302 q31_t * pResult); 303 304 305 /** 306 * @brief Root Mean Square of the elements of a Q15 vector. 307 * @param[in] pSrc is input pointer 308 * @param[in] blockSize is the number of samples to process 309 * @param[out] pResult is output value. 310 */ 311 void arm_rms_q15( 312 const q15_t * pSrc, 313 uint32_t blockSize, 314 q15_t * pResult); 315 316 317 /** 318 * @brief Standard deviation of the elements of a floating-point vector. 319 * @param[in] pSrc is input pointer 320 * @param[in] blockSize is the number of samples to process 321 * @param[out] pResult is output value. 322 */ 323 void arm_std_f32( 324 const float32_t * pSrc, 325 uint32_t blockSize, 326 float32_t * pResult); 327 328 329 /** 330 * @brief Standard deviation of the elements of a Q31 vector. 331 * @param[in] pSrc is input pointer 332 * @param[in] blockSize is the number of samples to process 333 * @param[out] pResult is output value. 334 */ 335 void arm_std_q31( 336 const q31_t * pSrc, 337 uint32_t blockSize, 338 q31_t * pResult); 339 340 341 /** 342 * @brief Standard deviation of the elements of a Q15 vector. 343 * @param[in] pSrc is input pointer 344 * @param[in] blockSize is the number of samples to process 345 * @param[out] pResult is output value. 346 */ 347 void arm_std_q15( 348 const q15_t * pSrc, 349 uint32_t blockSize, 350 q15_t * pResult); 351 352 353 354 /** 355 * @brief Minimum value of a Q7 vector. 356 * @param[in] pSrc is input pointer 357 * @param[in] blockSize is the number of samples to process 358 * @param[out] result is output pointer 359 * @param[in] index is the array index of the minimum value in the input buffer. 360 */ 361 void arm_min_q7( 362 const q7_t * pSrc, 363 uint32_t blockSize, 364 q7_t * result, 365 uint32_t * index); 366 367 /** 368 * @brief Minimum value of absolute values of a Q7 vector. 369 * @param[in] pSrc is input pointer 370 * @param[in] blockSize is the number of samples to process 371 * @param[out] result is output pointer 372 * @param[in] index is the array index of the minimum value in the input buffer. 373 */ 374 void arm_absmin_q7( 375 const q7_t * pSrc, 376 uint32_t blockSize, 377 q7_t * result, 378 uint32_t * index); 379 380 381 /** 382 * @brief Minimum value of a Q15 vector. 383 * @param[in] pSrc is input pointer 384 * @param[in] blockSize is the number of samples to process 385 * @param[out] pResult is output pointer 386 * @param[in] pIndex is the array index of the minimum value in the input buffer. 387 */ 388 void arm_min_q15( 389 const q15_t * pSrc, 390 uint32_t blockSize, 391 q15_t * pResult, 392 uint32_t * pIndex); 393 394 /** 395 * @brief Minimum value of absolute values of a Q15 vector. 396 * @param[in] pSrc is input pointer 397 * @param[in] blockSize is the number of samples to process 398 * @param[out] pResult is output pointer 399 * @param[in] pIndex is the array index of the minimum value in the input buffer. 400 */ 401 void arm_absmin_q15( 402 const q15_t * pSrc, 403 uint32_t blockSize, 404 q15_t * pResult, 405 uint32_t * pIndex); 406 407 408 /** 409 * @brief Minimum value of a Q31 vector. 410 * @param[in] pSrc is input pointer 411 * @param[in] blockSize is the number of samples to process 412 * @param[out] pResult is output pointer 413 * @param[out] pIndex is the array index of the minimum value in the input buffer. 414 */ 415 void arm_min_q31( 416 const q31_t * pSrc, 417 uint32_t blockSize, 418 q31_t * pResult, 419 uint32_t * pIndex); 420 421 /** 422 * @brief Minimum value of absolute values of a Q31 vector. 423 * @param[in] pSrc is input pointer 424 * @param[in] blockSize is the number of samples to process 425 * @param[out] pResult is output pointer 426 * @param[out] pIndex is the array index of the minimum value in the input buffer. 427 */ 428 void arm_absmin_q31( 429 const q31_t * pSrc, 430 uint32_t blockSize, 431 q31_t * pResult, 432 uint32_t * pIndex); 433 434 435 /** 436 * @brief Minimum value of a floating-point vector. 437 * @param[in] pSrc is input pointer 438 * @param[in] blockSize is the number of samples to process 439 * @param[out] pResult is output pointer 440 * @param[out] pIndex is the array index of the minimum value in the input buffer. 441 */ 442 void arm_min_f32( 443 const float32_t * pSrc, 444 uint32_t blockSize, 445 float32_t * pResult, 446 uint32_t * pIndex); 447 448 /** 449 * @brief Minimum value of absolute values of a floating-point vector. 450 * @param[in] pSrc is input pointer 451 * @param[in] blockSize is the number of samples to process 452 * @param[out] pResult is output pointer 453 * @param[out] pIndex is the array index of the minimum value in the input buffer. 454 */ 455 void arm_absmin_f32( 456 const float32_t * pSrc, 457 uint32_t blockSize, 458 float32_t * pResult, 459 uint32_t * pIndex); 460 461 462 /** 463 * @brief Maximum value of a Q7 vector. 464 * @param[in] pSrc points to the input buffer 465 * @param[in] blockSize length of the input vector 466 * @param[out] pResult maximum value returned here 467 * @param[out] pIndex index of maximum value returned here 468 */ 469 void arm_max_q7( 470 const q7_t * pSrc, 471 uint32_t blockSize, 472 q7_t * pResult, 473 uint32_t * pIndex); 474 475 /** 476 * @brief Maximum value of absolute values of a Q7 vector. 477 * @param[in] pSrc points to the input buffer 478 * @param[in] blockSize length of the input vector 479 * @param[out] pResult maximum value returned here 480 * @param[out] pIndex index of maximum value returned here 481 */ 482 void arm_absmax_q7( 483 const q7_t * pSrc, 484 uint32_t blockSize, 485 q7_t * pResult, 486 uint32_t * pIndex); 487 488 489 /** 490 * @brief Maximum value of a Q15 vector. 491 * @param[in] pSrc points to the input buffer 492 * @param[in] blockSize length of the input vector 493 * @param[out] pResult maximum value returned here 494 * @param[out] pIndex index of maximum value returned here 495 */ 496 void arm_max_q15( 497 const q15_t * pSrc, 498 uint32_t blockSize, 499 q15_t * pResult, 500 uint32_t * pIndex); 501 502 /** 503 * @brief Maximum value of absolute values of a Q15 vector. 504 * @param[in] pSrc points to the input buffer 505 * @param[in] blockSize length of the input vector 506 * @param[out] pResult maximum value returned here 507 * @param[out] pIndex index of maximum value returned here 508 */ 509 void arm_absmax_q15( 510 const q15_t * pSrc, 511 uint32_t blockSize, 512 q15_t * pResult, 513 uint32_t * pIndex); 514 515 /** 516 * @brief Maximum value of a Q31 vector. 517 * @param[in] pSrc points to the input buffer 518 * @param[in] blockSize length of the input vector 519 * @param[out] pResult maximum value returned here 520 * @param[out] pIndex index of maximum value returned here 521 */ 522 void arm_max_q31( 523 const q31_t * pSrc, 524 uint32_t blockSize, 525 q31_t * pResult, 526 uint32_t * pIndex); 527 528 /** 529 * @brief Maximum value of absolute values of a Q31 vector. 530 * @param[in] pSrc points to the input buffer 531 * @param[in] blockSize length of the input vector 532 * @param[out] pResult maximum value returned here 533 * @param[out] pIndex index of maximum value returned here 534 */ 535 void arm_absmax_q31( 536 const q31_t * pSrc, 537 uint32_t blockSize, 538 q31_t * pResult, 539 uint32_t * pIndex); 540 541 /** 542 * @brief Maximum value of a floating-point vector. 543 * @param[in] pSrc points to the input buffer 544 * @param[in] blockSize length of the input vector 545 * @param[out] pResult maximum value returned here 546 * @param[out] pIndex index of maximum value returned here 547 */ 548 void arm_max_f32( 549 const float32_t * pSrc, 550 uint32_t blockSize, 551 float32_t * pResult, 552 uint32_t * pIndex); 553 554 /** 555 * @brief Maximum value of absolute values of a floating-point vector. 556 * @param[in] pSrc points to the input buffer 557 * @param[in] blockSize length of the input vector 558 * @param[out] pResult maximum value returned here 559 * @param[out] pIndex index of maximum value returned here 560 */ 561 void arm_absmax_f32( 562 const float32_t * pSrc, 563 uint32_t blockSize, 564 float32_t * pResult, 565 uint32_t * pIndex); 566 567 /** 568 @brief Maximum value of a floating-point vector. 569 @param[in] pSrc points to the input vector 570 @param[in] blockSize number of samples in input vector 571 @param[out] pResult maximum value returned here 572 @return none 573 */ 574 void arm_max_no_idx_f32( 575 const float32_t *pSrc, 576 uint32_t blockSize, 577 float32_t *pResult); 578 579 580 581 582 #ifdef __cplusplus 583 } 584 #endif 585 586 #endif /* ifndef _STATISTICS_FUNCTIONS_H_ */ 587