libdspl-2.0/dspl/dox/ru/complex.dox

/*! ****************************************************************************
\ingroup TYPES_GROUP
\typedef complex_t
\brief Описание комплексного типа данных.

	Комплексный тип данных в библиотеке DSPL-2.0 определен как 
	массив из двух элементов типа `double`.
	При этом первый элемент массива определяет реальную часть 
	комплексного числа, а второй - мнимую.

	Например:

	\code
		complex_t z;
		z[0] =  1.0;
		z[1] = -2.0;
	\endcode 

	Переменная `z = 1-2j`, где `j` - мнимая единица.

	Для удобства работы с комплексными числами реализованы 
	специальные макросы: \ref RE, \ref IM, \ref ABSSQR

***************************************************************************** */









/*! *************************************************************************************************
	\ingroup TYPES_GROUP
	\def ABSSQR(x)
	\brief Макрос возвращает квадрат модуля комплексного числа `x`.

    Квадрата модуля комплексного числа \f$ x = a + j \cdot b \f$ равен:

    \f[
        |x|^2 = x \cdot x^* = a^2 + b^2. 
    \f]

    Например:
    \code
        complex_t z;
        double y;
        RE(z) =  1.0;
        IM(z) = -2.0;
        y = ABSSQR(z);               
    \endcode 

    Переменная `z = 1-2j`, где `j` - мнимая единица, а переменная `y = 5`.

   
 
	
**************************************************************************************************** */








/*! *************************************************************************************************
	\ingroup TYPES_GROUP
	\def IM(x)
	\brief Макрос определяющий мнимую часть комплексного числа.

    Например:
    \code
        complex_t z;
        RE(z) =  1.0;
        IM(z) = -2.0;        
    \endcode 

    Переменная `z = 1-2j`, где `j` - мнимая единица.

    Аналогично, макрос можно использовать для получения мнимой части комплексного числа:

     \code
        complex_t z = {3.0, -4.0};
        double    r;
        r = IM(z);
    \endcode    
    В данном примере переменная `z = 3-4i`, а в переменой `r` будет храниться число -4.
 
	
**************************************************************************************************** */










/*! *************************************************************************************************
	\ingroup TYPES_GROUP
	\def RE(x)
	\brief Макрос определяющий реальную часть комплексного числа.

    Например:
    \code
        complex_t z;
        RE(z) =  1.0;
        IM(z) = -2.0;        
    \endcode 

    Переменная `z = 1-2j`, где `j` - мнимая единица.

    Аналогично, макрос можно использовать для получения реальной части комплексного числа:

     \code
        complex_t z = {3.0, -4.0};
        double    r;
        r = RE(z);
    \endcode    
    В данном примере переменная `z = 3-4i`, а в переменой `r` будет храниться число 3.
 
	
**************************************************************************************************** */









/*! *************************************************************************************************
    \ingroup TYPES_GROUP
    \fn int re2cmplx(double* x, int n, complex_t *y)
    \brief Преобразование массива вещественных данных в массив комплексных данных.

    Функция заполняет реальные части массива `y` данных соответсвующими значениями 
    исходного вещественного массива `x`. <BR>  
    

    \param[in]  x   Указатель на массв вещественных данных.<BR>
                    Размер массива `[n x 1]`. <BR><BR>

    \param[in]  n   Размер массивов входных и выходных данных.<BR><BR>

    \param[out] y   Указатель на адрес массива комплексных данных.<BR>
                    Размер массива `[n x 1]`. <BR>
                    Память должна быть выделена. <BR><BR>


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



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

        re2cmplx(x, 3, y);
    \endcode 
    
    Значениям `y` будут присвоены значения:
  
    \verbatim	     
        y[0] = 1+0j;
        y[1] = 2+0j;
        y[2] = 3+0j.
    \endverbatim

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


**************************************************************************************************** */






/*! *************************************************************************************************
    \ingroup TYPES_GROUP
    \fn int cmplx2re(complex_t* x, int n, double *re, double *im)
    \brief  Преобразование массива комплексных данных в два массива
            вещественных данных, содержащих реальную и мнимую части 
            исходного массива

    Функция заполняет реальные массивы `re` и `im` соответсвующими значениями 
    ральной и мнимой частей исходного комплексного массива `x`. <BR>  
    

    \param[in]  x   Указатель на массв комплексных данных.<BR>
                    Размер массива `[n x 1]`. <BR><BR>

    \param[in]  n   Размер массивов входных и выходных данных.<BR><BR>

    \param[out] re  Указатель на адрес массива реальной части данных.<BR>
                    Размер массива `[n x 1]`. <BR>
                    Память должна быть выделена. <BR><BR>     

    \param[out] im  Указатель на адрес массива мнимой части данных.<BR>
                    Размер массива `[n x 1]`. <BR>
                    Память должна быть выделена. <BR><BR>

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

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

        cmplx2re(x, 3, re, im);
    \endcode 

    Элементам массивов `re`  и `im` будут присвоены значения:
  
    \verbatim
    re[0] = 1.0; im[0] = 2.0;
    re[1] = 3.0; im[1] = 4.0;
    re[2] = 5.0; im[2] = 6.0;
    \endverbatim

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


**************************************************************************************************** */