

/*! ****************************************************************************
\ingroup SPEC_MATH_TRIG_GROUP
\fn int acos_cmplx(complex_t* x, int n, complex_t *y)
\brief  Арккосинус комплексного аргумента `x`

Функция рассчитывает значения арккосинуса комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
\textrm{Arccos}(x) = \frac{\pi}{2} - \textrm{Arcsin}(x) = 
\frac{\pi}{2} -j \textrm{Ln}\left( j x + \sqrt{1 - x^2} \right)
\f]  


\param[in]  x
Указатель на вектор аргумента комплексного арккосинуса. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n
    

\param[out] y
Указатель на вектор значений комплексного арккосинуса,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

\note
Функция может использоваться для расчета арккосинуса аргумента 
большего единицы, когда вещественная функция `acos` не определена.

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;
  
  acos_cmplx(x, 3, y);
  
  for(k = 0; k < 3; k++)
    printf("acos_cmplx(%.1f%+.1fj) = %.3f%+.3fj\n", 
             RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
\endcode 
\n

Результатом работы будет

\verbatim
acos_cmplx(1.0+2.0j) = 1.144-1.529j
acos_cmplx(3.0+4.0j) = 0.937-2.306j
acos_cmplx(5.0+6.0j) = 0.880-2.749j
\endverbatim

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








/*! ****************************************************************************
\ingroup SPEC_MATH_TRIG_GROUP
\fn int asin_cmplx(complex_t* x, int n, complex_t *y)
\brief  Арксинус комплексного аргумента `x`

Функция рассчитывает значения арксинуса комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
 \textrm{Arcsin}(x) = j \textrm{Ln}\left( j x + \sqrt{1 - x^2} \right)
\f]  


\param[in]  x
Указатель на вектор аргумента комплексного арксинуса. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n


\param[out] y
Указатель на вектор значений комплексного арксинуса,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

\note 
Функция может использоваться для расчета арксинуса аргумента 
большего единицы, когда вещественная функция `acos` не определена.

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;
  
  asin_cmplx(x, 3, y);  
  for(k = 0; k < 3; k++)
    printf("asin_cmplx(%.1f%+.1fj) = %.3f%+.3fj\n", 
            RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
\endcode 
\n

Результатом работы будет

\verbatim
asin_cmplx(1.0+2.0j) = 0.427+1.529j
asin_cmplx(3.0+4.0j) = 0.634+2.306j
asin_cmplx(5.0+6.0j) = 0.691+2.749j
\endverbatim

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



/*! ****************************************************************************
\ingroup SPEC_MATH_TRIG_GROUP
\fn int cos_cmplx(complex_t* x, int n, complex_t *y)
\brief  Косинус комплексного аргумента `x`

Функция рассчитывает значения косинуса комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
\textrm{cos}(x) = \frac{\exp(jx) + \exp(-jx)}{2} 
\f]  

\param[in]  x
Указатель на вектор аргумента комплексного косинуса. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n

\param[out] y
Указатель на вектор значений комплексного косинуса,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;
  
  cos_cmplx(x, 3, y);
  
  for(k = 0; k < 3; k++)
    printf("cos_cmplx(%.1f%+.1fj) = %9.3f%+9.3fj\n", 
            RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
  
 \endcode 
 \n

Результатом работы будет

\verbatim
cos_cmplx(1.0+2.0j) =     2.033   -3.052j
cos_cmplx(3.0+4.0j) =   -27.035   -3.851j
cos_cmplx(5.0+6.0j) =    57.219 +193.428j
\endverbatim

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






/*! ****************************************************************************
\ingroup SPEC_MATH_TRANSCEND
\fn int bessel_i0(double* x, int n, double* y)
\brief
Модифицированная функция Бесселя первого рода \f$ I_0(x)\f$

Функция рассчитывает значения функции для вещественного вектора `x`, 
который должен принимать неотрицательные значения. \n

\param[in]  x
Указатель на вектор переменной \f$ x \f$. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n 
\n

\param[in]  n
Размер входного вектора `x`. \n 
\n

\param[out] y
Указатель на вектор значений функции \f$ I_0(x)\f$. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n 
\n

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

\note
Используемый алгоритм описа в статье:
Rational Approximations for the Modified Bessel Function 
of the First Kind – I0(x) for Computations with Double Precision 
by PAVEL HOLOBORODKO on NOVEMBER 11, 2015 

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

\include bessel_i0.c

Данная программа рассчитывает значения функции \f$ I_0(x)\f$ переменной `x` 
в интервале \f$[0 \ 3]\f$. 
Рассчитанные данные сохраняются в текстовый файл `dat/dat0.txt` 
и выводятся на график `img/bessel_i0.png`

\image html bessel_i0.png


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






/*! ****************************************************************************
\ingroup SPEC_MATH_COMMON_GROUP
\fn int log_cmplx(complex_t* x, int n, complex_t *y)
\brief  Натуральный логарифм комплексного аргумента `x`

Функция рассчитывает значения натурального логарифма комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
\textrm{Ln}(x) = j \varphi + \ln(|x|), 
\f]  
где \f$\varphi\f$ --- фаза комплексного числа.

\param[in]  x
Указатель на комплексный вектор аргумента логарифма. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n
    

\param[out] y
Указатель на вектор значений комплексного логарифма,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;

  log_cmplx(x, 3, y);  

  for(k = 0; k < 3; k++)
    printf("log_cmplx(%.1f%+.1fj) = %.3f%+.3fj\n", 
            RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
   
 \endcode 
 \n

Результатом работы будет

\verbatim
log_cmplx(1.0+2.0j) = 0.805+1.107j
log_cmplx(3.0+4.0j) = 1.609+0.927j
log_cmplx(5.0+6.0j) = 2.055+0.876j
\endverbatim

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






/*! ****************************************************************************
\ingroup SPEC_MATH_TRIG_GROUP
\fn int sin_cmplx(complex_t* x, int n, complex_t *y)
\brief  Синус комплексного аргумента `x`

Функция рассчитывает значения синуса комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
\textrm{sin}(x) = \frac{\exp(jx) - \exp(-jx)}{2j} 
\f]  


\param[in]  x
Указатель на вектор аргумента комплексного синуса. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n
    

\param[out] y
Указатель на вектор значений комплексного синуса,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;
  
  sin_cmplx(x, 3, y);
  
  for(k = 0; k < 3; k++)
    printf("sin_cmplx(%.1f%+.1fj) = %9.3f%+9.3fj\n", 
            RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
  
 \endcode 
 \n

Результатом работы будет

\verbatim
sin_cmplx(1.0+2.0j) =     3.166   +1.960j
sin_cmplx(3.0+4.0j) =     3.854  -27.017j
sin_cmplx(5.0+6.0j) =  -193.430  +57.218j
\endverbatim

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





/*! ****************************************************************************
\ingroup SPEC_MATH_COMMON_GROUP
\fn int sinc(double* x, int n, double a, double* y)

\brief
Функция \f$ \textrm{sinc}(x,a) = \frac{\sin(ax)}{ax}\f$

Функция рассчитывает значения функции для вещественного вектора `x`.


\param[in]  x
Указатель на вектор переменной \f$ x \f$. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n 
\n

\param[in]  n
Размер входного вектора `x`. \n 
\n

\param[in]  a
Параметр функции \f$ \textrm{sinc}(x,a) = \frac{\sin(ax)}{ax}\f$. \n
\n


\param[out]  y
Указатель на вектор значений функции. \n
 Размер вектора `[n x 1]`. \n
 Память должна быть выделена. \n 
 \n


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

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



/*! ****************************************************************************
\ingroup SPEC_MATH_TRANSCEND
\fn int sine_int(double* x, int n, double* si)

\brief
Функция интегрального синуса

\f[ \textrm{Si}(x) = \int_{0}^{x} \frac{\sin(x)}{x} \, dx\f]

Функция рассчитывает значения функции для интегрального синуса 
для произвольного вещественного вектора `x`.


\param[in] x
Указатель на вектор переменной \f$ x \f$. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n
\n

\param[in] n
Размер входного вектора `x`. \n
\n


\param[out] si
Указатель на вектор значений функции интегрального синуса. \n
Размер вектора `[n x 1]`. \n
Память должна быть выделена. \n
\n

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

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

\include sine_int_test.c

Данная программа рассчитывает значения функции интегрального синуса и
функции \ref sinc для вектора переменной `x` 
в интервале \f$[-6\pi \ 6\pi]\f$. 
Рассчитанные данные сохраняются в текстовые файлы 
`dat/dat0.txt` и `dat/dat1.txt`

и выводятся на график `img/sine_int.png`

\image html sine_int.png

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





/*! ****************************************************************************
\ingroup SPEC_MATH_COMMON_GROUP
\fn int sqrt_cmplx(complex_t* x, int n, complex_t *y)
\brief  Квадратный корень из комплексного вектора `x` (поэлементный).

Функция рассчитывает значения квадратного корня комплексного аргумента, 
заданного вектором `x` длины `n`:  \n
\f[
y(k) = \sqrt{x(k)}, \qquad k = 0 \ldots n-1. 
\f]  


\param[in]  x
Указатель на вектор аргумента квадратного корня. \n
Размер вектора `[n x 1]`.  \n \n

\param[in]  n
Размер входного и выходного векторов `x` и `y`. \n \n
    

\param[out] y
Указатель на вектор значений комплексного корня,
соответствующего входному вектору `x`. \n
Размер массива `[n x 1]`.  \n
Память должна быть выделена.  \n \n

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

Например при выполнении следующего кода 
\code{.cpp}
  complex_t x[3] = {{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}};
  complex_t y[3];
  int k;
  
  sqrt_cmplx(x, 3, y);
  
  for(k = 0; k < 3; k++)
    printf("sqrt_cmplx(%.1f%+.1fj) = %.3f%+.3fj\n", 
            RE(x[k]), IM(x[k]), RE(y[k]), IM(y[k]));
 
\endcode 
\n

Результатом работы будет

\verbatim
sqrt_cmplx(1.0+2.0j) = 1.272+0.786j
sqrt_cmplx(3.0+4.0j) = 2.000+1.000j
sqrt_cmplx(5.0+6.0j) = 2.531+1.185j
\endverbatim

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


