00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2005 Nils van Velzen 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 */ 00019 00020 /** 00021 \file cta_matrix.h 00022 \brief The interface description of the COSTA matrix component. For user implementation see cta_usr_matrix.h. 00023 00024 CTA_Matrix is the default class implementation for matrices. 00025 */ 00026 00027 #ifndef CTA_MATRIX_H 00028 #define CTA_MATRIX_H 00029 #include "cta_system.h" 00030 #include "cta_handles.h" 00031 #include "cta_datatypes.h" 00032 #include "cta_functions.h" 00033 #include "cta_vector.h" 00034 00035 /* Function Handle */ 00036 typedef CTA_Handle CTA_Matrix; 00037 typedef CTA_Handle CTA_MatClass; 00038 00039 /* parameters for different functions */ 00040 #define CTA_MATRIX_CREATE_SIZE ( 1) 00041 #define CTA_MATRIX_CREATE_INIT ( 2) 00042 #define I_CTA_MATRIX_GETVALS ( 4) 00043 #define I_CTA_MATRIX_GETVAL ( 5) 00044 #define I_CTA_MATRIX_SETCOL ( 6) 00045 #define I_CTA_MATRIX_SETVALS ( 7) 00046 #define I_CTA_MATRIX_SETVAL ( 8) 00047 #define I_CTA_MATRIX_SETCONST ( 9) 00048 #define I_CTA_MATRIX_FREE (10) 00049 #define I_CTA_MATRIX_EXPORT (11) 00050 #define I_CTA_MATRIX_GER (12) 00051 #define I_CTA_MATRIX_INV (13) 00052 #define I_CTA_MATRIX_GEMV (14) 00053 #define I_CTA_MATRIX_GEMM (15) 00054 #define I_CTA_MATRIX_AXPY (16) 00055 #define CTA_MATRIX_NUMFUNC (17) 00056 00057 #ifdef __cplusplus 00058 extern "C" { 00059 #endif 00060 00061 /** \brief Create a new class (=implementation) of a COSTA matrix component. 00062 * 00063 * \param name I name of the new matrix class 00064 * \param h_func I COSTA function handles for functions that implement class, 00065 * missing functions must have value CTA_NULL 00066 * \param hmatcl O receives handle of new matrix class 00067 * \return error status: CTA_OK if successful 00068 */ 00069 CTAEXPORT int CTA_Matrix_DefineClass(const char *name, 00070 const CTA_Func h_func[CTA_MATRIX_NUMFUNC], 00071 CTA_MatClass *hmatcl); 00072 00073 /** \brief Duplicate a matrix instance. 00074 * 00075 * \note Only size, data type and class type are duplicated, the values are not 00076 * copied. 00077 * 00078 * \param hmat1 I handle of matrix to be duplicated 00079 * \param hmat2 O receives handle of duplicate matrix, empty handle before calling 00080 * \return error status: CTA_OK if successful 00081 */ 00082 CTAEXPORT int CTA_Matrix_Duplicate(CTA_Matrix hmat1, CTA_Matrix *hmat2); 00083 00084 /** \brief Create a new matrix. 00085 * 00086 * \note 00087 * 00088 * \param hmatcl I matrix class of new matrix 00089 * \param m I number of rows 00090 * \param n I number of columns 00091 * \param datatype I datatype of elements in matrix 00092 * \param userdata IO userdata for creation (depends on class) 00093 * \param hmat O receives handle of new matrix 00094 * \return error status: CTA_OK if successful 00095 */ 00096 CTAEXPORT int CTA_Matrix_Create(CTA_MatClass hmatcl, const int m, const int n, 00097 CTA_Datatype datatype, CTA_Handle userdata, CTA_Matrix *hmat); 00098 00099 /* *\brief Get size of matrix. 00100 * 00101 * \note 00102 * 00103 * \param hmat I handle of matrix 00104 * \param m O receives number of rows 00105 * \param n O receives number of columns 00106 * \return error status: CTA_OK if successful 00107 */ 00108 CTAEXPORT int CTA_Matrix_GetSize(CTA_Matrix hmat, int *m, int *n); 00109 00110 /** \brief Get datatype of matrix 00111 * 00112 * \note 00113 * 00114 * \param hmat I handle of matrix 00115 * \param datatype O receives data type of matrix 00116 * \return error status: CTA_OK if successful 00117 */ 00118 CTAEXPORT int CTA_Matrix_GetDatatype(CTA_Matrix hmat, CTA_Datatype *datatype); 00119 00120 /** \brief Get copy of all values in matrix. 00121 * 00122 * \note The elements in the matrix are returned column-wise 00123 * (FORTRAN matrix representation) 00124 * 00125 * \param hmat I handle of matrix 00126 * \param vals O copy of values in matrix 00127 * \param m I number of rows of vals (must be the same as for the matrix) 00128 * \param n I number of columns of vals (must be the same as for the matrix) 00129 * \param datatype I data type of *vals, must be the same as data type of matrix elements 00130 * \return error status: CTA_OK if successful 00131 */ 00132 CTAEXPORT int CTA_Matrix_GetVals(CTA_Matrix hmat, void *vals, int m, int n, 00133 CTA_Datatype datatype); 00134 00135 /** \brief Get copy of single value in the matrix. 00136 * 00137 * \note Counting of the indices starts from 1. 00138 * \param hmat I handle of matrix 00139 * \param val O receives copy of value in matrix 00140 * \param m I row index of value to be copied 00141 * \param n I column index of value to be copied 00142 * \param datatype I data type of *val, must be the same as data type of matrix elements 00143 * \return error status: CTA_OK if successful 00144 */ 00145 CTAEXPORT int CTA_Matrix_GetVal (CTA_Matrix hmat, void *val , int m, int n, 00146 CTA_Datatype datatype); 00147 00148 /** \brief Set whole matrix to one single value. 00149 * 00150 * \note 00151 * \param hmat IO handle of matrix 00152 * \param val I value that must be set 00153 * \param datatype I data type of *val, must be the same as data type of matrix elements 00154 * \return error status: CTA_OK if successful 00155 */ 00156 CTAEXPORT int CTA_Matrix_SetConstant(CTA_Matrix hmat, void *val, CTA_Datatype datatype); 00157 00158 /** \brief Set values of a single column of the matrix. 00159 * 00160 * \note Counting of the indices starts from 1. 00161 * \param hmat IO handle of matrix 00162 * \param n I index of matrix column to set 00163 * \param hvec I handle of COSTA vector the values have to be set to, length must be the same as number of rows of matrix 00164 * \return error status: CTA_OK if successful 00165 */ 00166 CTAEXPORT int CTA_Matrix_SetCol(CTA_Matrix hmat, int n, CTA_Vector hvec); 00167 00168 /** \brief Set all values of the matrix. 00169 * 00170 * \note The elements in vals should be column-wise 00171 * (FORTRAN matrix representation) 00172 * \param hmat IO handle of matrix 00173 * \param vals I copy of values in matrix 00174 * \param m I number of rows of vals (must be the same as for the matrix) 00175 * \param n I number of columns of vals (must be the same as for the matrix) 00176 * \param datatype I data type of vals 00177 * \return error status: CTA_OK if successful 00178 */ 00179 CTAEXPORT int CTA_Matrix_SetVals(CTA_Matrix hmat, void *vals, int m, int n, 00180 CTA_Datatype datatype); 00181 00182 /** \brief Set a single value in the matrix. 00183 * 00184 * \param hmat IO handle of matrix 00185 * \param val I value to be set at position (m,n) 00186 * \param m I row index 00187 * \param n I column index 00188 * \param datatype I data type of *val, must be the same as data type of matrix elements 00189 * \return error status: CTA_OK if successful 00190 */ 00191 CTAEXPORT int CTA_Matrix_SetVal(CTA_Matrix hmat, void *val, int m, int n, 00192 CTA_Datatype datatype); 00193 00194 /** \brief Export a matrix. 00195 * 00196 * \note CTA_DEFAULT_MATRIX supports exporting to:\n 00197 * file (usedoc is handle of COSTA file)\n 00198 * 00199 * \param hmat I handle of matrix 00200 * \param usedoc I configuration of output 00201 * \return error status: CTA_OK if successful 00202 */ 00203 CTAEXPORT int CTA_Matrix_Export(CTA_Matrix hmat, CTA_Handle usedoc); 00204 00205 00206 /** \brief Perform a rank 1 operation A:=alpha*x*y'+A 00207 * 00208 * \param hmat IO handle of matrix A 00209 * \param alpha I scalar 00210 * \param vx I vector x 00211 * \param vy I vector y 00212 * \return error status: CTA_OK if successful 00213 * \note it is allowed that are the same object (*vx==*vy) 00214 */ 00215 CTAEXPORT int CTA_Matrix_Ger(CTA_Matrix hmat, double alpha, CTA_Vector vx, 00216 CTA_Vector vy); 00217 00218 00219 /** \brief Compute inverse of a square matrix A:=inv(A) 00220 * 00221 * \param hmat IO handle of matrix A 00222 * \return error status: CTA_OK if successful 00223 * 00224 */ 00225 CTAEXPORT int CTA_Matrix_Inv(CTA_Matrix hmat); 00226 00227 /** \brief Perform the matrix multiplication y:=alpha*OP(A)*x+beta*y 00228 * where op(X)=X, X^T 00229 * 00230 * \param hmat I handle of matrix (A from the equation above) 00231 * \param trans I transpose flag CTA_TRUE/CTA_FALSE for matrix A 00232 * \param alpha I scalar 00233 * \param vx I vector x 00234 * \param beta I scalar 00235 * \param vy IO vector y 00236 * \return error status: CTA_OK if successful 00237 * \note it is allowed that vectors are the same object (*vx==*vy) 00238 */ 00239 CTAEXPORT int CTA_Matrix_Gemv(CTA_Matrix hmat, int trans, double alpha, 00240 CTA_Vector vx, double beta, CTA_Vector vy); 00241 00242 /** \brief Perform the matrix multication C:=alpha*op(A)*op(B)+beta*C 00243 where op(X)=X, X^T 00244 * 00245 * \param mC IO handle of matrix C 00246 * \param transa I transpose flag CTA_TRUE/CTA_FALSE for matrix A 00247 * \param transb I transpose flag CTA_TRUE/CTA_FALSE for matrix A 00248 * \param alpha I scalar 00249 * \param mA I handle of matrix A 00250 * \param mB I handle of matrix B 00251 * \param beta I scalar 00252 * \return error status: CTA_OK if successful 00253 */ 00254 CTAEXPORT int CTA_Matrix_Gemm(CTA_Matrix mC, int transa, int transb, double alpha, 00255 CTA_Matrix mA, CTA_Matrix mB, double beta); 00256 00257 /** \brief Perform the matrix addition Y:=alpha*X+Y 00258 * 00259 * \param mY IO handle of matrix Y 00260 * \param alpha I scalar 00261 * \param mX I handle of matrix X 00262 * \return error status: CTA_OK if successful 00263 */ 00264 CTAEXPORT int CTA_Matrix_Axpy(CTA_Matrix mY, double alpha, CTA_Matrix mX); 00265 00266 00267 /** \brief Computes the eigenvalues and optionally the eigenvectors 00268 * of a general matrix A 00269 * 00270 * The computed eigenvectors are normalized to have Euclidean norm 00271 * equal to 1 and largest component real. 00272 * 00273 * \param A I Matrix A 00274 * \param eigvals O Vector with eigenvalues 00275 * \param eigvecs O Matrix with eigenvalues. The eigenvectors are 00276 * not computed when eigvecs in CTA_NULL on entry 00277 * \return error status: CTA_OK if successful 00278 * \note the eigenvalues can be complex. Since COSTA does not yet support 00279 * complex vectors, only the real part of the eigenvalues is 00280 * returned. 00281 */ 00282 CTAEXPORT int CTA_Matrix_EigVals(CTA_Matrix A, CTA_Vector eigvals, CTA_Matrix eigvecs); 00283 00284 00285 /** \brief Free the matrix object 00286 * 00287 * \Note hmat=CTA_NULL is allowed 00288 * 00289 * \param hmat IO handle of matrix, replaced by CTA_NULL on return. 00290 * \return error status: CTA_OK if successful 00291 */ 00292 CTAEXPORT int CTA_Matrix_Free(CTA_Matrix *hmat); 00293 00294 #ifdef __cplusplus 00295 } 00296 #endif 00297 #endif
1.6.1