
/*! ****************************************************************************
\ingroup FILTER_ANALYSIS_GROUP
\fn int freqs(double* b, double* a, int ord, double* w, int n, complex_t *h)

\brief Расчет комплексного коэффициента передачи 
\f$ H(j \omega) \f$ аналогового фильтра.

Функция рассчитывает значения комплексного коэффициента передачи 
\f$ H(j \omega)\f$ аналогового фильтра, заданного коэффициентами 
передаточной функции \f$ H(s) \f$:

\f[
  H(s) = \frac  {\sum_{k = 0}^{N} b_k  s^k}
      {\sum_{m = 0}^{N} a_m  s^m},
\f]
где \f$ N \f$ - порядок фильтра (параметр `ord`).

Комплексный коэффициент передачи рассчитывается путем 
подстановки \f$ s = j \omega \f$.

\param[in]  b
Указатель на вектор коэффициентов числителя 
передаточной функции \f$ H(s) \f$. \n 
Размер вектора `[ord+1 x 1]`. \n \n 


\param[in]  a
Указатель на вектор коэффициентов знаменателя 
передаточной функции \f$ H(s) \f$. \n 
Размер вектора `[ord+1 x 1]`. \n \n 


\param[in]  ord
Порядок фильтра. Количество коэффициентов числителя и 
знаменателя передаточной функции \f$ H(s) \f$ 
равно `ord+1`. \n \n 


\param[in]  w
Указатель на вектор значений циклической частоты \f$ \omega \f$ (рад/с), 
для которого будет рассчитан комплексный 
коэффициент передачи \f$ H(j \omega) \f$. \n 
Размер вектора `[n x 1]`. \n \n 


\param[in]  n
Размер вектора циклической частоты `w`. \n \n 


\param[out]  h
Указатель на вектор комплексного коэффициента передачи \f$ H(j \omega) \f$, 
рассчитанного для циклической частоты `w`. \n 
Размер вектора `[n x 1]`. \n 
Память должна быть выделена. \n  \n

\return
`RES_OK` Комплексноый коэффициент передачи рассчитан успешно. \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки". \n

\author
Бахурин Сергей
www.dsplib.org
***************************************************************************** */







/*! ****************************************************************************
\ingroup FILTER_ANALYSIS_GROUP
\fn int filter_freq_resp(double* b, double* a, int ord, double* w, int n, 
        int flag, double* mag, double* phi, double* tau)

\brief
Расчет амплитудно-частотной (АЧХ), фазочастотной характеристик (ФЧХ), а также 
группового времени запаздывания (ГВЗ) цифрового или аналогового или фильтра.

Функция рассчитывает АЧХ, ФЧХ и ГВЗ аналогового или цифрового фильтра, заданного 
передаточной характеристикой \f$H(s)\f$, или \f$H(z)\f$ соответственно

\param[in]  b
Указатель на вектор коэффициентов числителя 
передаточной функции \f$ H(s) \f$. \n 
Размер вектора `[ord+1 x 1]`. \n \n 

\param[in]  a
Указатель на вектор коэффициентов знаменателя 
передаточной функции \f$ H(s) \f$. \n 
Размер вектора `[ord+1 x 1]`. \n \n 

\param[in]  ord
Порядок фильтра. Количество коэффициентов 
числителя и знаменателя передаточной
функции \f$ H(s) \f$ равно `ord+1`. \n  \n 

\param[in]  w
Указатель на вектор значений циклической частоты  \f$ \omega \f$ (рад/с), 
для которого будет рассчитаны  АЧХ, ФЧХ и ГВЗ аналогового фильтра, 
если установлен  флаг `DSPL_FLAG_ANALOG`. \n
В случае если флаг `DSPL_FLAG_ANALOG` не установлен, то  вектор частоты `w` 
используется как нормированная частота комплексного коэффициента передачи 
\f$ H \left(\mathrm{e}^{j\omega} \right) \f$  цифрового фильтра. \n
В этом случае характеристика цифрового фильтра является 
\f$ 2\pi \f$-периодической, и вектор частоты может содержать 
произвольные значения, однако целесообразно задавать 
его от 0 до \f$ \pi \f$, а такжет от 0 до \f$ 2\pi \f$, или 
от \f$ -\pi \f$ до \f$ \pi \f$. \n
Размер вектора `[n x 1]`. \n \n 
 
\param[in]  n
Размер вектора циклической частоты `w`. \n  \n 

\param[in]  flag
Комбинация флагов, которые задают расчет параметров: \n 
\verbatim
DSPL_FLAG_ANALOG  Коэффициенты относятся к аналоговому фильтру
DSPL_FLAG_LOGMAG  АЧХ рассчитывать в логарифмическом масштабе
DSPL_FLAG_UNWRAP  раскрывать периодичность ФЧХ
\endverbatim

\param[out]  mag
Указатель на вектор АЧХ. \n 
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n
Если указатель `NULL`, то расчет АЧХ не производится. \n \n

\param[out]  phi
Указатель на вектор ФЧХ. \n 
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n
Если указатель `NULL`, то расчет ФЧХ не производится. \n \n

\param[out]  tau
Указатель на вектор ГВЗ. \n 
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n
Если указатель `NULL`, то расчет ГВЗ не производится. \n \n

\return
`RES_OK`  Параметры фильтра рассчитаны успешно. \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки". \n

Пример использования функции `filter_freq_resp`:

\include butter_ap_test.c

Результат работы программы:

\verbatim
b[ 0] =   1.002   a[ 0] =   1.002
b[ 1] =   0.000   a[ 1] =   2.618
b[ 2] =   0.000   a[ 2] =   3.418
b[ 3] =   0.000   a[ 3] =   2.615
b[ 4] =   0.000   a[ 4] =   1.000
\endverbatim
\n

В каталоге `dat` будут созданы три файла: \n

\verbatim
butter_ap_test_mag.txt    АЧХ фильтра
butter_ap_test_phi.txt    ФЧХ фильтра
butter_ap_test_tau.txt    ГВЗ фильтра
\endverbatim

Кроме того программа GNUPLOT произведет построение следующих графиков 
по сохраненным в файлах данным:

\image html butter_ap_test.png

\author
Бахурин Сергей
www.dsplib.org
***************************************************************************** */










/*! ****************************************************************************
\ingroup FILTER_ANALYSIS_GROUP
\fn int freqz(double* b, double* a, int ord, double* w, int n, complex_t *h)

\brief  Расчет комплексного коэффициента передачи 
  \f$ H \left(e^{j \omega} \right)\f$ цифрового фильтра.

Функция рассчитывает значения комплексного коэффициента передачи 
\f$ H \left(e^{j \omega} \right)\f$  цифрового фильтра, заданного 
коэффициентами передаточной функции \f$H(z)\f$:

\f[
H(z) = \frac  {\sum_{k = 0}^{N} b_k  z^{-k}}
    {\sum_{m = 0}^{N} a_m z^{-m}},
\f]

где \f$N\f$ --- порядок фильтра (параметр `ord`). \n

Комплексный коэффициент передачи рассчитывается путем 
подстановки \f$z = e^{j \omega} \f$. \n

  
\param[in]  b
Указатель на вектор коэффициентов числителя 
передаточной функции \f$H(z)\f$. \n
Размер вектора `[ord+1 x 1]`. \n \n

\param[in]  a
Указатель на вектор коэффициентов знаменателя 
передаточной функции \f$H(z)\f$. \n
Размер вектора `[ord+1 x 1]`. \n \n
      
\param[in]  ord
Порядок фильтра. Количество коэффициентов числителя и знаменателя 
передаточной функции \f$H(z)\f$ равно `ord+1`. \n \n
      
\param[in]  w
Указатель на вектор значений  нормированной циклической частоты \f$\omega\f$, 
для которого будет рассчитан комплексный коэффициент передачи 
\f$ H \left(e^{j \omega} \right)\f$. \n
Размер вектора `[n x 1]`. \n \n
      
\param[in]  n
Размер вектора нормированной циклической частоты `w`. \n \n

\param[out]  h
Указатель на вектор комплексного коэффициента передачи 
\f$ H \left(e^{j \omega} \right)\f$, рассчитанного для 
циклической частоты `w`. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n \n


\return
`RES_OK` Комплексный коэффициент передачи расcчитан успешно. \n
В противном случае \ref ERROR_CODE_GROUP "код ошибки". \n

\note
Комплексный коэффициент передачи \f$ H \left(e^{j \omega} \right)\f$ 
цифрового фильтра представляет собой \f$ 2 \pi-\f$периодическую функцию 
нормированной циклической частоты \f$\omega\f$.
Поэтому анализ цифровых фильтров целесообразно вести на одном периоде 
повторения \f$ H \left(e^{j \omega} \right)\f$, т.е. в интервале 
\f$\omega\f$ от 0 до \f$2 \pi\f$, или от \f$-\pi\f$ до \f$ \pi\f$.  \n
Кроме того известно, что для фильтра с вещественными коэффициентами 
\f$ H \left(e^{j \omega} \right) = H^* \left(e^{-j \omega} \right)\f$,
а значит, анализ цифрового фильтра с вещественными коэффициентами 
достаточно вести для нормированной частоты \f$\omega\f$ от 0 до \f$\pi\f$.

\author
Бахурин Сергей
www.dsplib.org
***************************************************************************** */
