00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2012 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_array.h 00022 \brief Interface description of array component. 00023 00024 An array in OpenDA is an N-dimensional Matrix of values. 00025 In a similar wat as in Matlab and Octave a vector is a special case of a Matrix/Array. 00026 00027 */ 00028 00029 #ifndef CTA_ARRAY_H 00030 #define CTA_ARRAY_H 00031 #include "cta_system.h" 00032 #include "cta_handles.h" 00033 #include "cta_datatypes.h" 00034 /* Function Handle */ 00035 #ifdef __cplusplus 00036 extern "C" { 00037 #endif 00038 00039 typedef CTA_Handle CTA_Array; 00040 00041 /** \brief Free Array instance 00042 * 00043 * \param h IO handle of Array instance CTA_NULL on return 00044 * \return error status: CTA_OK if successful 00045 */ 00046 CTAEXPORT int CTA_Array_Free(CTA_Array *h); 00047 00048 /** \brief Create a new Array instance and fill with given values 00049 * 00050 * \param values I values of new Array 00051 * \param nDimensions I Number of dimensions of new array 00052 * \param dimensions I Number of elements in each dimension 00053 * \param h O Array handle of new instance 00054 * \return error status: CTA_OK if successful 00055 */ 00056 CTAEXPORT int CTA_Array_CreateAsDoubles(double *values, int nDimensions, int *dimensions, CTA_Array *h); 00057 00058 /** \brief Get number of dimensions, eg 1 for a vector and 2 for a matrix 00059 * \param h I Array handle 00060 * \return rank of the array 00061 */ 00062 CTAEXPORT int CTA_Array_getNumberOfDimensions(CTA_Array h); 00063 00064 /** \brief Get the sizes of the individual dimensions 00065 * \param h I Array handle 00066 * \param nDimensions O size of array, eg 2 for the array [[3,4,10],[3,4,10]] 00067 * 00068 * \return error status: CTA_OK if successful 00069 */ 00070 CTAEXPORT int CTA_Array_getnDimensions(CTA_Array h, int *nDimensions); 00071 00072 /** \brief Get the size of the array for each dimension. 00073 * The length of the return value equals the number of dimensions. 00074 * 00075 * \param h I Array handle 00076 * \param dimensions O size of array, eg [3,4,10] 00077 * \return error status: CTA_OK if successful 00078 */ 00079 CTAEXPORT int CTA_Array_getDimensions(CTA_Array h, int *dimensions); 00080 00081 /** \brief Total number of elements in an array. 00082 * This is equal to the product of the values returned by getDimension and is thus just for c 00083 * 00084 * \param h I Array handle 00085 * \return error status: CTA_OK if successful 00086 */ 00087 CTAEXPORT int CTA_Array_length(CTA_Array h); 00088 00089 /** \brief Get all values of an array. 00090 * The values are guaranteed be a copy if 00091 * copyValues==true or may be a reference if copyValues==false. 00092 * Note that the values are never guaranteed to be a reference and can not be used 00093 * to change the array. 00094 * 00095 * \param h I Array handle 00096 * \param values O Values from the array 00097 * \return error status: CTA_OK if successful 00098 */ 00099 CTAEXPORT int CTA_Array_getValuesAsDoubles(CTA_Array h, double *values); 00100 00101 /** \brief Get a part of the values from the array. 00102 * Eg let a=[[1,2,3][4,5,6]] then getValuesAsDoubles(1,2) 00103 * returns [2,3] 00104 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00105 * \param h I Array handle 00106 * \param firstIndex I firstIndex of selection 00107 * \param lastIndex I lastIndex of selection 00108 * \param values O Values from the array 00109 * \return error status: CTA_OK if successful 00110 */ 00111 CTAEXPORT int CTA_Array_getValuesAsDoubles_indexrange(CTA_Array h, int firstIndex, int lastIndex, double *values); 00112 00113 /** \brief Get a value from an array for specific indices. 00114 * Eg let a=[[1,2,3][4,5,6]] then getValueAsDouble(5) 00115 * returns 6 00116 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00117 * \param h I Array handle 00118 * \param index I index specifier 00119 * \param value O double value at the specific indices 00120 * \return error status: CTA_OK if successful 00121 */ 00122 CTAEXPORT int CTA_Array_getValueAsDoubles_index(CTA_Array h, int index, double *value); 00123 00124 /** \brief Get a value from an array for specific indices. 00125 * Eg let a=[[1,2,3][4,5,6]] then getValueAsDouble([1,2]) 00126 * returns 6 00127 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00128 * \param h I Array handle 00129 * \param nIndices I length of array of indices indices 00130 * \param indices I indices of value 00131 * \param value O value from array 00132 * \return error status: CTA_OK if successful 00133 */ 00134 CTAEXPORT int CTA_Array_getValueAsDouble_indices(CTA_Array h, int nIndices, int* indices, double *value); 00135 00136 /** \brief Set the values of this array. 00137 * \param h I Array handle 00138 * \param values I the values as an array of doubles 00139 * \param length I length of array values 00140 * \return error status: CTA_OK if successful 00141 */ 00142 CTAEXPORT int CTA_Array_setValuesAsDoubles(CTA_Array h, double *values, int length); 00143 00144 /** \brief Set a value from an array for specific indices. 00145 * Eg let a=[[1,2,3][4,5,6]] then setValueAsDouble([1,2],60.) 00146 * results in a=[[1,2,3][4,5,60.]] 00147 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00148 * \param h I Array handle 00149 * \param nIndices I length of array indices 00150 * \param indices I index specifier 00151 * \param value I values at the specific indices 00152 * \return error status: CTA_OK if successful 00153 */ 00154 CTAEXPORT int CTA_Array_setValueAsDouble_indices(CTA_Array h, int nIndices, int *indices, double value); 00155 00156 /** \brief Set part of the values of this array. 00157 * Let a=[[1,2,3][4,5,6]] then setValuesAsDoubles(1,2,[20,30]) will result in a=[[1,20,30][4,5,6]] 00158 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00159 * \param h I Array handle 00160 * \param firstIndex I specifies the start of the selection 00161 * \param lastIndex I specifies the end of the selection 00162 * \param values I that will replace the selected range of numbers 00163 * \return error status: CTA_OK if successful 00164 */ 00165 CTAEXPORT int CTA_Array_setValuesAsDoubles_indexrange(CTA_Array h, int firstIndex, int lastIndex, double *values); 00166 00167 /** \brief Get a value from an array for specific indices. 00168 * Eg let a=[[1,2,3][4,5,6]] then setValueAsDouble(5,60.) 00169 * results in a=[[1,2,3][4,5,60.]] 00170 * Note that negative values are allowed to denote counting from the end, is -1 denotes the last value. 00171 * \param h I Array handle 00172 * \param index I index specifier 00173 * \param value I value that will replace the selected number 00174 * \return error status: CTA_OK if successful 00175 */ 00176 CTAEXPORT int CTA_Array_setValueAsDouble_index(CTA_Array h, int index, double value); 00177 00178 /** \brief Set whole vector equal to a constant value. 00179 * Note: This method can only be used if all elements of the vector 00180 * have the same data type. 00181 * \param h I Array handle 00182 * \param value I value to set 00183 * \return error status: CTA_OK if successful 00184 */ 00185 CTAEXPORT int CTA_Array_setConstant(CTA_Array h, double value); 00186 00187 /** \brief Perform a values += alpha * axpyValues</c> operation on each value in this array. 00188 * \param h I Array handle 00189 * \param alpha I The <c>alpha</c> in <c>state variable += alpha * vector</c>. 00190 * \param axpyValues I the values for the axpy-operation on all values in this array. 00191 * \return error status: CTA_OK if successful 00192 */ 00193 CTAEXPORT int CTA_Array_axpyOnValues(CTA_Array h, double alpha, double *axpyValues); 00194 00195 /** \brief Multiply each value in this array with the corresponding multiplication factor. 00196 * \param h I Array handle 00197 * \param multiplicationFactors I the multiplication factors for all array values. 00198 * \return error status: CTA_OK if successful 00199 */ 00200 CTAEXPORT int CTA_Array_multiplyValues(CTA_Array h, double *multiplicationFactors); 00201 00202 /** \brief Change the dimensions of an array. The new array should have the same length 00203 * \param h I Array handle 00204 * \param nDimensions I length of array dimensions 00205 * \param dimensions I new dimensions of array 00206 * \return error status: CTA_OK if successful 00207 */ 00208 CTAEXPORT int CTA_Array_reshape(CTA_Array h, int nDimensions, int *dimensions); 00209 00210 00211 /** \brief Get part of the array by selection of a subset in one dimension. 00212 * Eg. a=[[1,2,3],[4,5,6]] a.getSlice(0,0) returns [1,2,3] 00213 * Note that the number of dimensions IS reduced by one. 00214 * \param h I Array handle 00215 * \param dimension I Dimension to make selection in 00216 * \param index I Element in dimension that is selected 00217 * \param h_out O new Array with selected selection 00218 * \return error status: CTA_OK if successful 00219 */ 00220 CTAEXPORT int CTA_Array_getSlice(CTA_Array h, int dimension, int index, CTA_Array *h_out); 00221 00222 /** \brief Get part of the array by selection of a subset in one dimension. 00223 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] a.getSlice(0,0,1) returns [[1,2],[3,4]] 00224 * Note that the number of dimensions is NOT reduced by one. 00225 * \param h I Array handle 00226 * \param dimension I Dimension to make selection in 00227 * \param minIndex I start of range to select 00228 * \param maxIndex I end of range to select 00229 * \param h_out O new Array with selected selection 00230 * \return error status: CTA_OK if successful 00231 */ 00232 CTAEXPORT int CTA_Array_getSlice_range(CTA_Array h, int dimension, int minIndex, int maxIndex, CTA_Array *h_out); 00233 00234 /** \brief Get part of the array by selection of a subset in one dimension. 00235 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] a.getSlice(0,0,1) returns [1,2,3,4] 00236 * \param h I Array handle 00237 * \param dimension I Dimension to make selection in 00238 * \param minIndex I start of range to select 00239 * \param maxIndex I end of range to select 00240 * \param values O selected values 00241 * \return error status: CTA_OK if successful 00242 */ 00243 CTAEXPORT int CTA_Array_getSliceAsDoubles_range(CTA_Array h, int dimension, int minIndex, int maxIndex, double *values); 00244 00245 00246 /** \brief Set the values of a part of an array. 00247 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] and a.setSlice([11,12,13],1,1) 00248 * sets the second column a=[[1,11,3],[4,12,6],[7,13,9]] 00249 * Note that the dimension of the slice is one smaller than for the array. 00250 * \param h I Array handle 00251 * \param slice I Values to set 00252 * \param dimension I Dimension that is replaced 00253 * \param index I Index of selected dimension to replace 00254 * \return error status: CTA_OK if successful 00255 */ 00256 CTAEXPORT int CTA_Array_setSliceAsDoubles(CTA_Array h, double *slice, int dimension, int index); 00257 00258 00259 /** \brief Set the values of a part of an array. 00260 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] and a.setSlice([11,12,13],1,1) 00261 * sets the second column a=[[1,11,3],[4,12,6],[7,13,9]] 00262 * Note that the dimension of the slice is one smaller than for the array. 00263 * \param h I Array handle 00264 * \param slice_h I Values to set 00265 * \param dimension I Dimension that is replaced 00266 * \param index I Index of selected dimension to replace 00267 * \return error status: CTA_OK if successful 00268 */ 00269 CTAEXPORT int CTA_Array_setSliceAsArray(CTA_Array h, CTA_Array slice_h, int dimension, int index); 00270 00271 /** \brief Set the values of a part of an array. 00272 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] and a.setSlice([[11,12,13],[14,15,16]],1,1,2) 00273 * sets the second and third columns a=[[1,11,14],[4,12,15],[7,13,16]] 00274 * Note that the dimension of the slice is the same as for the array. 00275 * \param h I Array handle 00276 * \param slice_h I Values to set 00277 * \param dimension I Dimension that is replaced 00278 * \param minIndex I Start of range in Dimension to be replaced 00279 * \param maxIndex I End of range in Dimension to be replaced 00280 * \return error status: CTA_OK if successful 00281 */ 00282 CTAEXPORT int CTA_Array_setSliceAsArray_range(CTA_Array h, CTA_Array slice_h, int dimension, int minIndex, int maxIndex); 00283 00284 /** \brief Set the values of a part of an array. 00285 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] and a.setSlice([11,12,13,14,15,16],1,1,2) 00286 * sets the second and third columns a=[[1,11,14],[4,12,15],[7,13,16]] 00287 * Note that the dimension of the slice is the same as for the array. 00288 * \param h I Array handle 00289 * \param slice I Values to set 00290 * \param dimension I Dimension that is replaced 00291 * \param minIndex I Start of range in Dimension to be replaced 00292 * \param maxIndex I End of range in Dimension to be replaced 00293 * \return error status: CTA_OK if successful 00294 */ 00295 CTAEXPORT int CTA_Array_setSliceAsDoubles_range(CTA_Array h, double *slice, int dimension, int minIndex, int maxIndex); 00296 00297 /** \brief Convert indices in multiple dimensions to position in the one-dimensional array as 00298 * returned eg by getValuesAsDoubles 00299 * Eg. a=[[1,2,3],[4,5,6],[7,8,9]] then valueIndex([1,0]) returns 3 which points to the value 4 here. 00300 * \param h I Array handle 00301 * \param nIndices I length of indices 00302 * \param indices I indices of element 00303 * \param index O position of element 00304 * \return error status: CTA_OK if successful 00305 */ 00306 CTAEXPORT int CTA_Array_valueIndex(CTA_Array h, int nIndices, int *indices, int *index); 00307 00308 00309 #ifdef __cplusplus 00310 } 00311 #endif 00312 00313 00314 00315 00316 00317 #endif