diff --git a/dspl/src/filter_fir.c b/dspl/src/filter_fir.c index ea693a6..180d335 100644 --- a/dspl/src/filter_fir.c +++ b/dspl/src/filter_fir.c @@ -283,7 +283,7 @@ DSPL_FILTER_BSTOP - режекторный фильтр. \n \param[out] h -Указатель на вектор коэффициентов линейно-фазового КИХ-фильтраю \f$H(z)\f$. \n +Указатель на вектор коэффициентов линейно-фазового КИХ-фильтра \f$H(z)\f$. \n Размер вектора `[ord+1 x 1]`. \n Память должна быть выделена. \n \n @@ -307,9 +307,9 @@ DSPL_FILTER_BSTOP - режекторный фильтр. \include fir_linphase_test.c -Программа расчитывает коэффициенты и АЧХ линейно-фазовых КИХ-фильтрова нижних, +Программа расчитывает коэффициенты и АЧХ линейно-фазовых КИХ-фильтров нижних, верхних частот, полосовых и режекторных с применением различных весовых окон: -прямоугольное, Хемминга, Илэкмана и Блэкмана-Харриса. \n +прямоугольное, Хемминга, Блэкмана и Блэкмана-Харриса. \n Полученные АЧХ выводятся на график \image html fir_linphase_test.png diff --git a/dspl/src/matrix.c b/dspl/src/matrix.c index 1e0a383..391eb14 100644 --- a/dspl/src/matrix.c +++ b/dspl/src/matrix.c @@ -247,7 +247,6 @@ int DSPL_API matrix_eye(double* a, int n, int m) #ifdef DOXYGEN_ENGLISH - /*! **************************************************************************** \ingroup SPEC_MATH_LINALG_GROUP \fn int matrix_eye_cmplx(complex_t* a, int n, int m) @@ -324,7 +323,84 @@ int DSPL_API matrix_eye_cmplx(complex_t* a, int n, int m) #ifdef DOXYGEN_ENGLISH +/*! **************************************************************************** +\ingroup SPEC_MATH_LINALG_GROUP +\fn int matrix_mul(double* a, int na, int ma, double* b, int nb, int mb, + double* c) +\brief Matrix multiplication. +The function calculates the product of matrices \f$\mathbf{C} = \mathbf{AB}\f$, +here \f$\mathbf{A}\f$ -- matrix contains \f$N_A\f$ rows and +\f$M_A\f$ columns, \f$\mathbf{B}\f$ -- matrix contains \f$N_B\f$ rows and +\f$M_B\f$ columns, product matrix \f$\mathbf{C} = \mathbf{AB}\f$ + contains\f$N_A\f$ rows and \f$M_B\f$ columns. + +\note +Matrix multiplication requires the equality \f$M_A = N_B\f$. \n +Function uses BLAS subroutine `dgemm`. + + +\param[in] a +Pointer to the input matrix \f$\mathbf{A}\f$ size `na x ma`. \n +Matrix must be located in memory as column-major array. \n \n + +\param[in] na +Matrix `a` rows number. \n\n + +\param[in] ma +Matrix `a` columns number. \n\n + +\param[in] b +Pointer to the input matrix \f$\mathbf{B}\f$ size `nb x mb`. \n +Matrix must be located in memory as column-major array. \n \n + +\param[in] nb +Matrix `b` rows number. \n +Necessary equality `ma = nb`. \n\n + +\param[in] mb +Matrix `a` columns number. \n\n + +\param[out] c +Pointer to the output matrix \f$\mathbf{С} = \mathbf{AB}\f$.\n +Matrix size is `na x mb`. \n +Memory must be allocated. \n\n + +\return +`RES_OK` --- function is calculated successfully. \n +Else \ref ERROR_CODE_GROUP "error code". \n + +Example: +\include matrix_mul.c + +The program forms and multiplies two matrices. +The original matrices and their product are printed. + +The result of the program: +\verbatim + +A = [ % size [4 x 5] type: real +0.00, 4.00, 8.00, 12.00, 16.00; +1.00, 5.00, 9.00, 13.00, 17.00; +2.00, 6.00, 10.00, 14.00, 18.00; +3.00, 7.00, 11.00, 15.00, 19.00;]; + +B = [ % size [5 x 3] type: real +0.00, 5.00, 10.00; +1.00, 6.00, 11.00; +2.00, 7.00, 12.00; +3.00, 8.00, 13.00; +4.00, 9.00, 14.00;]; + +C = [ % size [4 x 3] type: real +120.00, 320.00, 520.00; +130.00, 355.00, 580.00; +140.00, 390.00, 640.00; +150.00, 425.00, 700.00;]; +\endverbatim + +\author Sergey Bakhurin www.dsplib.org +***************************************************************************** */ #endif #ifdef DOXYGEN_RUSSIAN /*! **************************************************************************** diff --git a/dspl/src/polyval.c b/dspl/src/polyval.c index 0b23d06..7df35f0 100644 --- a/dspl/src/polyval.c +++ b/dspl/src/polyval.c @@ -68,7 +68,67 @@ int DSPL_API poly_z2a_cmplx(complex_t* z, int nz, int ord, complex_t* a) #ifdef DOXYGEN_ENGLISH +/*! **************************************************************************** +\ingroup SPEC_MATH_COMMON_GROUP +\fn int polyroots(double* a, int ord, complex_t* r, int* info) +\brief Function calculates real polynomial roots. +Function calculates roots of the real polynomial \f$P_N(x)\f$ order \f$N\f$ +with `a` coefficient vector size `[(N+1) x 1]`. +\f[ + P_N(x) = a_0 + a_1 x + a_2 x^2 + a_3 x^3 + ... a_N x^N. +\f] + +The roots of the polynomial are calculated as eigenvalues of the polynomial +companion matrix. To calculate the eigenvalues, +a subroutine of the LAPACK package is used. + + +\param[in] a +Pointer to the vector of coefficients. \n +Vector size is `[ord+1 x 1]`. \n +Coefficient `a[0]` corresponds to the \f$a_0\f$ polynomial coefficient. \n +Coefficient `a[ord]` cannot be zero. \n \n + +\param[in] ord +Polynomial order \f$N\f$. \n \n + +\param[out] r +Pointer to the polynomial roots vector. \n +Vector size is `[ord x 1]`. \n +Memory must be allocated. \n +The roots of a real polynomial can be either real or form simple +or multiple complex conjugate pairs of roots. Therefore, the output +root vector is of a complex data type. \n \n + +\param[out] info +Pointer to the LAPACK subroutine error code. \n +This code is returned by the LAPACK subroutine and translated through +this variable for analysis.. \n\n + +\return +`RES_OK` --- roots are calculated successfully. \n +Else \ref ERROR_CODE_GROUP "code error". + +Example: + +\include polyroots_test.c + +This program calculates the roots of the polynomial +\f[ +P(x) = 2 + 2x + x^2 +\f] +and prints the calculated roots. +The result of the program: + +\verbatim +Error code: 0x00000000 +r[0] = -1.00000 1.00000 j +r[1] = -1.00000-1.00000 j +\endverbatim + +\author Sergey Bakhurin. www.dsplib.org +***************************************************************************** */ #endif #ifdef DOXYGEN_RUSSIAN /*! **************************************************************************** @@ -99,7 +159,11 @@ int DSPL_API poly_z2a_cmplx(complex_t* z, int nz, int ord, complex_t* a) \param[out] r Указатель на вектор комплексных корней полинома. \n Размер вектора `[ord x 1]`. \n -Память должна быть выделена. \n \n +Память должна быть выделена. \n +Корни вещественного полинома могут быть как вещественными, +так и образовывать простые или кратные комплексно-сопряженные пары корней. +Поэтому выходной вектор корней имеет комплексный тип данных. +\n \n \param[out] info Указатель наа код возврата пакета LAPACK. \n diff --git a/dspl/src/psd.c b/dspl/src/psd.c index 782511f..7fb29ad 100644 --- a/dspl/src/psd.c +++ b/dspl/src/psd.c @@ -251,7 +251,118 @@ exit_label: #endif #ifdef DOXYGEN_RUSSIAN +/*! **************************************************************************** +\ingroup PSD_GROUP +\fn int psd_bartlett_cmplx(complex_t* x, int n, int nfft, + fft_t* pfft, double fs, + int flag, double* ppsd, double* pfrq) +\brief Непараметрическая оценка спектральной плотности мощности (СПМ) +комплексного сигнала методом Бартлетта. +Функция рассчитывает спектральную плотность мощности \f$ X(f) \f$ +выборки сигнала длительности \$n \$ отсчетов методом Бартлетта: +\f[ + X(f) = \frac{1}{N F_s } \sum_{p = 0}^{P-1}\left| \sum_{m = 0}^{n_{FFT}-1} + x(m+p \cdot n_{\text{FFT}}) \exp + \left( -j 2\pi f m \right) \right|^2, +\f] +где \f$ F_s \f$ -- частота +дискретизации (Гц), \f$P = n/n_{\text{FFT}}\f$ -- количество сегментов +смещений выборки сигналов размера \f$n_{FFT}\f$. + + +При использовании \f$n_{FFT} = n\f$ оценка Бартлетта переходит +в стандартную периодограмму. + +Расчет спектральной плотности мощности ведется при помощи алгоритмов быстрого +преобразования Фурье, для дискретной сетки частот от 0 Гц до \f$ F_s \f$ Гц +(по умолчанию), или от \f$-F_s /2 \f$ до \f$F_s /2 \f$, если установлен флаг +расчета двусторонней СПМ. + +\note Метод Бартлетта возвращает асимптотически несмещенную, +состоятельную оценку СПМ (уровень флуктуаций шумовой СПМ + уменьшается с ростом длины выборки `n` при фиксированной `nfft`). + +\param[in] x +Указатель на входной вектор комплексного сигнала \f$x(m)\f$, +\f$ m = 0 \ldots n-1 \f$. \n +Размер вектора `[n x 1]`. \n \n + +\param[in] n +Размер вектора входного сигнала. +Также размер выходного вектора СПМ и +вектора частоты также равны `n`.\n\n + + +\param[in] nfft +Размер сегмента.\n +Размер выходного вектора СПМ, и соответствующего ей вектора частоты.\n\n + + +\param[in] pfft +Указатель на структуру \ref fft_t. \n +Указатель может быть `NULL`. В этом случае объект структуры будет +создан внутри функции и удален перед завершением.\n +Если предполагается многократный вызов функции, то рекомендуется создать +объект \ref fft_t и передавать в функцию, чтобы не +создавать его каждый раз. \n\n + +\param[in] fs +частота дискретизации выборки исходного сигнала (Гц). \n\n + +\param[in] flag +Комбинация битовых флагов, задающих режим расчета: +\verbatim +DSPL_FLAG_LOGMAG - СПМ считать в логарифмическом масштабе в единицах дБ/Гц +DSPL_FLAG_PSD_TWOSIDED - двусторонняя СПМ (от -Fs/2 до Fs/2) +\endverbatim + +\param[in, out] ppsd +Указатель на вектор СПМ рассчитанных по входному сигналу $x$. \n +Размер вектора `[n x 1]`. \n +Память должна быть выделена. \n\n + +\param[in, out] pfrq +Указатель на вектор частоты, соответствующей +значениям рассчитанного вектора СПМ. \n +Размер вектора `[n x 1]`. \n +Указатель может быть `NULL`,в этом случае вектор частоты не +рассчитывается и не возвращается. \n\n + +\return +`RES_OK` если расчет произведен успешно. \n +В противном случае \ref ERROR_CODE_GROUP "код ошибки". \n \n + +Пример оценок СПМ методом Бартлетта: + +\include psd_bartlett_test_cmplx.c + +Программа производит расчет СПМ сигнала, состоящего из двух комплексных +экспонент на фоне белого гауссова шума. +Расчет ведется по выборкe длины 8192 отсчета при длине сегмента `nfft` +128, 1024 и 8192 отсчетов. + +Рассчитанные СПМ выводятся на графики: + +`n = 8192, nfft = 8192`: +\image html psd_bartlett_cmplx_8192.png + +`n = 8192, nfft = 1024`: +\image html psd_bartlett_cmplx_1024.png + +`n = 8192, nfft = 128`: +\image html psd_bartlett_cmplx_128.png + + +Можно видеть, что метод Бартлетта позволяет снизить +уровень флуктуация шума с увеличением количества сегментов. +Однако наблюдается эффект растекания спектра, который существенно ухудшает +динамический диапазон анализа. + +Для более качественной оценки СПМ смотри функцию \ref psd_welch_cmplx + +\author Бахурин Сергей www.dsplib.org +***************************************************************************** */ #endif int DSPL_API psd_bartlett_cmplx(complex_t* x, int n, int nfft, fft_t* pfft, double fs, @@ -407,8 +518,8 @@ exit_label: Подробнее смотри описание функции \ref window. \n\n \param[in] win_param -Параметр оконной функциии. \n -Данный параметр применяется только для парамтрических типов окон +Параметр оконной функции. \n +Данный параметр применяется только для параметрических типов окон (смотри описание функции \ref window).\n Для непараметрических функций игнорируется. \n\n