GPL + CeCILL Header change
[scilab.git] / scilab / modules / linear_algebra / includes / eigen.h
1 /*
2  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  * Copyright (C) 2009 - DIGITEO - Bernard HUGUENEY
4  *
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  * === LICENSE_END ===
14  *
15  */
16 #ifndef EIGEN_H
17 #define EIGEN_H
18
19 #include "doublecomplex.h"
20 #include "dynlib_linear_algebra.h"
21 /*
22  * Functions used to compute eigen values (and possibly eigen vectors) of one [complex|real] [un]symmetric matrix.
23  * We use 4 different functions because for e;fficiency reasons, API had to be different :
24  * 1) eigen vectors for symmetric matrix are computed in place in the same memory location as the argument matrix
25  * 2) complex eigen values for unsymmetric matrix are computed either in 'c' format (for real argument matrix) or 'z' format (complex argument matrix)
26  *
27  * @param pData double[complex]* in (& out for symmetric) argument matrix data, for symmetric, is also use to output eigen vectors
28  * @param iCols int nb of rows/cols of matrix
29  * @param computeEigenVectors int (boolean semantics) only need for symmetric : indicates weither eigenvectors should be computed
30  *
31  * out :
32  * eigen values either real or complex in 'z' format
33  * @param pEigenValues double[complex]* output eigen values
34  *
35  *  or complex in 'c' format
36  * @param pEigenValuesReal double* output eigen values real part
37  * @param pEigenValuesImg double* output eigen values imaginary part
38  *
39  * for unsymmetric cases, output complex eigen vectors either in 'z' format (complex argument)
40  * @param pEigenVectors doublecomplex* output eigen vectors
41  *
42  * or in 'c' format (real argument)
43  * @param pEigenVectorsReal double* output eigen vectors real part
44  * @param pEigenVectorsImg double* output eigen vectors imaginary part
45  *
46  */
47 LINEAR_ALGEBRA_IMPEXP int iEigen1ComplexSymmetricM(doublecomplex* pData, int iCols, int computeEigenVectors, double* pEigenValues);
48 LINEAR_ALGEBRA_IMPEXP int iEigen1RealSymmetricM(double* pData, int iCols, int computeEigenVectors, double* pEigenValues);
49
50 LINEAR_ALGEBRA_IMPEXP int iEigen1ComplexM(doublecomplex* pData, int iCols, doublecomplex* pEigenValues, doublecomplex* pEigenVectors);
51 LINEAR_ALGEBRA_IMPEXP int iEigen1RealM(double* pData, int iCols, double* pEigenValuesReal, double* pEigenValuesImg, double* pEigenVectorsReal, double* pEigenVectorsImg);
52
53 /*
54  * With 2 lhs, eigenvalues are expanded from a 1D vector to the diagonal of a matrix.
55  * The resulting matrix is a diagonal one: m[i,j]=0. for i!=j .
56  * For efficiency reasons, we also convert from 'z' to 'c' format at the same time. In this case, conversion cannont be done in place.
57  *
58  * /!\ For the real case, expansion is done in place, so obviously the memory must have been reserved accordingly /!\
59  * (i.e for the iCols x iCols matrix, not only the iCols x 1 vector.)
60  *
61  * @param pData double[complex]* : input  (&output for real) pData[0:iCols[ contains diagonal elements
62  * @param iCols int : input nb of elements
63  *
64  * out:
65  * @param  pRMatrix double* real part of the diagonal output matrix
66  * @param  pIMatrix double* imaginary part of the diagonal output matrix
67  */
68 LINEAR_ALGEBRA_IMPEXP void expandToDiagonalOfMatrix(double* pData, int iCols);
69 LINEAR_ALGEBRA_IMPEXP void expandZToDiagonalOfCMatrix(doublecomplex const* pZVector, int iCols, double* pRMatrix, double* pIMatrix);
70
71
72
73 /*
74  * Functions used to compute eigen values (and possibly eigen vectors) of two [complex|real]  matrix.
75  *
76  * @param pData1 double[complex]* in argument1 matrix data
77  * @param pData2 double[complex]* in argument2 matrix data
78  *
79  * @param iCols int nb of rows/cols of matrix
80  *
81  * out : when something should not be computed (depending on lhs), output buffer ptr is NULL
82  *
83  * Alpha is either
84  * in 'z' format for complex matrix
85  * @param pAlpha doublecomplex*
86  *
87  * or 'c' format for real matrix
88  *
89  * @param pAlphaReal double*
90  * @param pAlphaImg double*
91  *
92  *
93  * @param pBeta double[complex]*
94  *
95  * L and R are either
96  * in 'z' format for complex matrix
97  * @param pL doublecomplex*
98  * @param pR doublecomplex*
99  *
100  * or 'c' format for real matrix
101  *
102  * @param pLReal double*
103  * @param pLImg double*
104  * @param pRReal double*
105  * @param pRImg double*
106  *
107  */
108
109 LINEAR_ALGEBRA_IMPEXP int iEigen2ComplexM(doublecomplex* pData1, doublecomplex* pData2, int iCols
110         , doublecomplex* pAlpha, doublecomplex* pBeta, doublecomplex* pR, doublecomplex* pL);
111 LINEAR_ALGEBRA_IMPEXP int iEigen2RealM(double* pData1, double* pData2, int iCols
112                                        , double* pAlphaReal, double* pAlphaImg, double* pBeta, double* pRReal, double* pRimg, double* pLReal, double* pLImg);
113
114 #endif