kopia lustrzana https://github.com/Dsplib/libdspl-2.0
added doc for some functions
rodzic
9bbb377775
commit
20df49c996
Plik binarny nie jest wyświetlany.
|
@ -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
|
||||
|
|
|
@ -246,7 +246,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)
|
||||
|
@ -323,7 +322,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
|
||||
/*! ****************************************************************************
|
||||
|
|
|
@ -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
|
||||
|
|
115
dspl/src/psd.c
115
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
|
||||
|
||||
|
|
Ładowanie…
Reference in New Issue