4 \page MEDCouplingArrayPage MEDCoupling Arrays
8 \section MEDCouplingArrayIntro Introduction
10 One of the most basic concept mainly used all over MEDCoupling is
13 This concept is used all over
14 \ref medcoupling "MEDCoupling", \ref paramedmem "ParaMEDMEM", \ref medloader "MEDLoader" modules so it should be correctly
15 handled to play well with \ref MEDCouplingMeshesPage "Meshes" and \ref MEDCouplingFieldsPage "Fields".
17 \ref ParaMEDMEM::DataArray "DataArrays" are the atomic element of potentially heavy in memory objects in \ref medcoupling "MEDCoupling", \ref paramedmem "ParaMEDMEM" and \ref medloader "MEDLoader".
19 There are for the moment two types of arrays :
20 - double precision float (64 bits) array incarnated by \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble class".
21 - signed integer (32 bits) array incarnated by \ref ParaMEDMEM::DataArrayInt "DataArrayInt class".
23 \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt" classes inherits from
24 \ref ParaMEDMEM::DataArray "DataArray" \b non \b instantiable \b class that factorizes some common methods of inherited instantiable classes.
26 In the rest of the documentation \b DataArray will be used for both \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt".
28 \section MEDCouplingArrayBasics Basics concepts of the DataArrays.
30 It will be presented in this section common concept shared by the two classes to \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt".
32 \subsection MEDCouplingArrayBasicsName Name
34 A \ref ParaMEDMEM::DataArray "DataArray" instance has an attribute **name**.
36 **name** is particularly useful for \ref ParaMEDMEM::DataArray "DataArray" representing profiles, families, groups, fields in MEDLoader.
37 But excepted these useful usecases, **name** attribute is often ignored when \ref ParaMEDMEM::DataArray "DataArrays" are aggregated (field array, connectivity, coordinates) in a bigger object.
38 Whatever the usage of the **name** attribute of \ref ParaMEDMEM::DataArray "DataArrays", all methods in ParaMEDMEM::DataArrayDouble and ParaMEDMEM::DataArrayInt class deal with **name** as they do for components names.
40 \subsection MEDCouplingArrayBasicsTuplesAndCompo Raw data, tuples and components of DataArrays.
42 The main goal of \ref ParaMEDMEM::DataArray "DataArray" is to store contiguous vector of atomical elements with same basic datatype (signed integers, double precision...). This vector of atomical elements is called **raw data** of \ref ParaMEDMEM::DataArray "DataArray".
44 The size of this vector of data is called <em>"number of elements"</em>. So the number of bytes stored by a \ref ParaMEDMEM::DataArray "DataArray" instance, is equal to
45 the product of the __number of elements__ * __constant size of DataType__ .
47 As \ref ParaMEDMEM::DataArray "DataArray" instances are designed to store vector fields, tensor fields, coordinate of nodes, the notion of _components_ has been added.
49 So, \ref ParaMEDMEM::DataArray "DataArrays" have an additional attribute that is number of components that represent the size of a contiguous set of atomical elements.
50 The vector of atomical elements stored into \ref ParaMEDMEM::DataArray "DataArrays" are grouped in contiguous memory set of atomical elements having each same size.
52 The contiguous set of atomical elements is called **tuple**. And each **tuple** stored in raw data, has a length exactly equal to the number of components of
53 \ref ParaMEDMEM::DataArray "DataArray" storing it.
58 N_{elements}=N_{tuples}*N_{components}.
62 N_{bytes}=N_{elements}*sizeof(DataType)=N_{tuples}*N_{components}*sizeof(DataType).
65 In other words, **raw data** of \ref ParaMEDMEM::DataArray "DataArrays" can be seen as a dense matrix, whose number of components would be the row size and number of tuples
66 would be the column size. In this point of view of \ref ParaMEDMEM::DataArray "DataArrays" a **tuple** is represented by the corresponding row in the dense matrix.
68 Typically in the **raw data** of \ref ParaMEDMEM::DataArray "DataArrays" **number of tuples** is highly bigger than **number of components** !
70 To finish, raw data is stored tuples by tuples, in another words, in **full interlace mode**, which is the natural storage strategy in C/C++ world.
72 For example, let's consider a DataArray having 3 components (called *x* for the first component, *y* for the second, and *z* for the third) and composed by 5 tuples.
73 \n The *raw data* of the DataAarray instance will be organized in memory like that : \f$ x_0,y_0,z_0,x_1,y_1,z_1,x_2,y_2,z_2,x_3,y_3,z_3,x_4,y_4,z_4 \f$.
76 \subsection MEDCouplingArrayBasicsCompoName Information on components name.
78 As seen in the sub section above, a \ref ParaMEDMEM::DataArray "DataArray" instance has a defined number of components.
80 There is an information attached to each of these components constituting the \ref ParaMEDMEM::DataArray "DataArray".
82 This information is concretely a string of characters that allows, if needed, to give information about the corresponding component.
84 The format chosen in **MEDCoupling** for information on is "MY_COMPO_INFO [MYUNIT]". If needed, the unit attached to the component
85 should be put between "[" and "]" after the information of the components after one space character.
87 \subsection MEDCouplingArrayBasicsTimeLabel DataArrays and TimeLabel.
89 \ref ParaMEDMEM::DataArray "DataArrays instances" can consume big amount of data in memory so they inherit from \ref MEDCouplingTimeLabelPage "TimeLabel".
90 So in C++ it is a good practice to use :
91 - \c getConstPointer method in readonly access.
92 - \c getPointer method only if write is needed.
94 If the user in C++ or Python wants to modify intensively its **big** \ref ParaMEDMEM::DataArray "DataArray" instance **not** using raw data pointer it is better to invoke
95 \c setIJSilent just after invocation of \c declareAsNew instead of calling \c setIJ method that will increment time label of \ref ParaMEDMEM::DataArray "DataArray" instance
98 \c setIJ method usage should be reduced to little modification sessions.
100 \section MEDCouplingArrayBuildFromScratch Building an array from scratch
102 Here is a description of typical usages of \ref ParaMEDMEM::DataArrayDouble "MEDCoupling arrays".
104 \ref MEDCouplingArraySteps1 "Here is a C++ example."<br>
105 \ref MEDCouplingArraySteps0 "Here is a Python example."<br>
108 \section MEDCouplingArrayBasicsCopy Copy DataArrays.
110 As \ref ParaMEDMEM::DataArray "DataArrays" are the atomic entity of potentially big memory objects into \ref medcoupling "MEDCoupling"
111 , \ref ParaMEDMEM::DataArray "DataArrays" introduces concepts of copy and comparison that will be used by aggregating classes.
113 For more complex objects (that aggregate themselves big objects)
114 like ParaMEDMEM::MEDCouplingFieldDouble the concept of copy (shallow or deep) is less straight forward because which aggregated subobjects are copied or not.
116 \subsection MEDCouplingArrayBasicsCopyDeep Deep copy of DataArray
118 As for all potentially heavy memory consumer objects in \ref medcoupling "MEDCoupling", \ref ParaMEDMEM::DataArray "DataArrays" implement
119 method \c deepCpy. This method deeply copies an instance. The life cycle of the returned object is *fully* independent from the instance on which the method
120 \c deepCpy has been invoked.
122 \ref cpp_mcdataarray_deepcopy "Here is a C++ example."<br>
124 \subsection MEDCouplingArrayBasicsCopyShallow Shallow copy of DataArray
126 As \ref ParaMEDMEM::DataArray "DataArrays" are the atomic entity of potentially big memory objects into \ref medcoupling "MEDCoupling", the shallow copy
127 simply returns the same object with the reference counter incremented.
129 \ref cpp_mcdataarray_shallowcopy "Here is a C++ example."<br>
132 \section MEDCouplingArrayBasicsCompare Compare DataArrays.
134 Comparison is \ref medcoupling "MEDCoupling" is a concept highly sensitive because big amount of tests uses this to state about the success or the fail of these tests.
135 There are two types of comparison :
137 - strict, that compares strictly all the non mutable attributes (state sensitive). Methods to perform this strict comparison are :
138 - ParaMEDMEM::DataArrayInt::isEqual
139 - ParaMEDMEM::DataArrayDouble::isEqual.
141 - less strict, that focus only on non string attributes. Methods to perform less strict comparison are :
142 - ParaMEDMEM::DataArrayInt::isEqualWithoutConsideringStr
143 - ParaMEDMEM::DataArrayDouble::isEqualWithoutConsideringStr
145 \section MEDCouplingArrayFill Filling DataArray with values
147 Both DataArrayDouble and DataArrayInt provide comfort methods that
148 fill the array with some values. These methods are:
149 - ParaMEDMEM::DataArrayInt::fillWithZero and
150 ParaMEDMEM::DataArrayDouble::fillWithZero which assigns zero to all
152 - ParaMEDMEM::DataArrayInt::fillWithValue and
153 ParaMEDMEM::DataArrayDouble::fillWithValue which assigns a certain value to all
155 - ParaMEDMEM::DataArrayInt::iota() and
156 ParaMEDMEM::DataArrayDouble::iota() which assigns incrementing values to all
159 \section MEDCouplingArrayRenumbering Array renumbering
161 Here is presented all it is necessary to know concerning renumbering.
162 Renumbering is intensely required in %MEDLoader in %ParaMEDMEM. One of the user of renumbering is MED file for I/O where cells are sorted by type.
163 But it is also used on operations of node cell merging. It is also used in parallel mode when splitting of mesh is needed...
165 Formally a renumbering is a mathematical application that can be surjective, injective or bijective. This application is defined using an instance of
166 \ref ParaMEDMEM::DataArrayInt "DataArrayInt". There are different ways to define this application.
168 \subsection MEDCouplingArrayRenumberingO2N Old to new mode
170 The old to new mode is particularly recommended for surjective and bijective application. This is typically the case of \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "MEDCouplingUMesh::mergeNodes" method.
171 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "mergeNodes" that reduces the number of nodes from 5 nodes to 3 nodes.\n
172 In old to new mode the array \b MySurjection that specifies this surjection will have 5 tuples and 1 component. The content of the 5*1 values will be in {0,1,2}.\n
174 If \b MySujection equals [2,1,0,1,2], it means that :
176 - old id #0 will have new id equal to 2
177 - old id #1 will have new id equal to 1
178 - old id #2 will have new id equal to 0
179 - old id #3 will have new id equal to 1 like old id #1
180 - old id #4 will have new id equal to 2 like old id #0
182 This is the most common mode of renumbering in MEDCoupling because there is more methods implying renumbering that reduce the number of entities than method that increase number of entities.
184 Method in old to new mode that works on bijective applications :
186 - \ref ParaMEDMEM::DataArrayDouble::renumber "DataArrayDouble::renumber"
187 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlace"
189 Method in old to new mode that works on surjective applications :
191 - \ref ParaMEDMEM::DataArrayDouble::renumberAndReduce "DataArrayDouble::renumberAndReduce"
193 Sometimes the format old to new for surjections can be replaced by another format with 2 arrays. Less compact in memory. The \ref ParaMEDMEM::DataArrayInt::changeSurjectiveFormat "DataArrayInt::changeSurjectiveFormat" method performs that.
195 \subsection MEDCouplingArrayRenumberingN2O New to old mode
197 The new to old mode is particularly recommended for strictly injective and bijective permutations. This is particularly useful for methods that increase the number of entities like for example
198 \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "MEDCouplingUMesh::simplexize".\n
199 All non static methods in \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" or \ref ParaMEDMEM::DataArrayInt "DataArrayInt" having as last letter \b R (meaning Reversed) in capital works with
201 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "simplexize" that increases the number of cell from 4 cells to 6 cells.\n
202 In new to old mode the array \b MyInjection that specifies this injection will have 6 tuples and 1 component. The content of the 5*1 values will be in {0,1,2,3}.\n
203 If \b MyInjection equals [2,0,1,1,3,0] it means that :
205 - new id #0 comes from old id 2
206 - new id #1 comes from old id 0
207 - new id #2 comes from old id 1
208 - new id #3 comes from old id 1
209 - new id #4 comes from old id 3
210 - new id #5 comes from old id 0
212 Method in new to old mode that works on bijective applications :
214 - \ref ParaMEDMEM::DataArrayDouble::renumberR "DataArrayDouble::renumberR"
215 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlaceR"
217 Method in new to old mode that works on surjective applications :
219 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId "DataArrayDouble::selectByTupleId"
220 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleIdSafe "DataArrayDouble::selectByTupleIdSafe"
221 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId2 "DataArrayDouble::selectByTupleId2"
222 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleRanges "DataArrayDouble::selectByTupleRanges"
224 \section MEDCouplingArrayApplyFunc Application of a function on DataArrayDouble instances.
226 This section is only dedicated for \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble instances".
228 It is possible to apply to \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble instance" a function given by a string.
230 There are different API for applyFunc* methods of \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble class".
232 \subsection MEDCouplingArrayApplyFuncExpr Expressions supported
234 In order to reduce as much as possible dependencies, a little dynamic formula interpreter has been developed into INTERP_KERNEL.
235 This dynamic expression evaluator can deal the following exhaustive list :
237 - +,-,*,^ (^ for exponent 3^2==9)
238 - sin,cos,tan,sqrt,abs,exp,max,min,ln (neper logarithm), log (neper logarithm), log10 (decimal logarithm),
242 The expression evaluator is also sensitive to the following var pattern : IVec, JVec, KVec, LVec,... ,ZVec
244 - IVec stands for unitary vector [1,0,0,0,...]
245 - JVec stands for unitary vector [0,1,0,0,...]
246 - KVec stands for unitary vector [0,0,1,0,...]
249 The dynamic expression evaluator works tuple by tuple through the *raw data* of DataArrayDouble instance.
251 The principle of the dynamic expression evaluator is the following :
253 - Given the input string a compilation tree is built whose leaves are either constants or variables.
254 At this phase only syntax errors are thrown.
255 \anchor MEDCouplingArrayApplyFuncExprA1
256 - Then given the computed tree, a link phase is performed to accelerate evaluation. At this phase the incoherence between the number of
257 components and the number of variables are detected.
259 - The given the preprocessed tree given an input tuple a preallocated tuple is fed with the result of the evaluation.
260 At this last phase only mathematical errors are thrown (division by 0, log(0), sqrt of a negative number ...)
262 \subsection MEDCouplingArrayApplyFunc0 applyFunc method with only one parameter
264 This method produces a newly allocated DataArrayDouble instance having exactly the same number of components **and** number of tuples than the instance on which the
265 \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method is applied.
267 **This method is useful when the evaluation expression do not need to consider the components of each tuple separately**.
269 That's why this method of \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method with one parameter accepts at most only one variable.
271 If it is not the case an exception is thrown as seen here :
273 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_1
275 Let's take a very simple example on a DataArrayDouble instance \c d having 4 tuples and 2 components.
277 In the next example the expression contains only one variable : \c smth.
278 So \c smth represent a tuple of size 2.
280 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_2
282 As the example shows, the output \c d1 has 2 components as \c d.
284 Whereas all the components of the input of \c d be not considered separately, it is also, possible with \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method with one parameter
285 to build an output having same number of components than input but where components in input are treated separately.
287 Let's build an example using DataArrayDouble instance \c d defined just above.
289 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_3
291 In this example using IVec and JVec it is possible to differentiate output in component #0 and output in component #1 for DataArrayDouble instance \c d2.
293 \subsection MEDCouplingArrayApplyFunc1 applyFunc method with only two parameters
295 This method also returns a newly allocated DataArrayDouble instance having the same number of tuples than the DataArrayDouble instance on which \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const applyFunc method is called, but the contrary to previous \ref MEDCouplingArrayApplyFunc0 "applyFunc with one parameter version" here the number of components is set by the user.
297 The big difference with \ref MEDCouplingArrayApplyFunc0 "applyFunc method with one parameter" seen above is that here components of tuples are treated separately.
299 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const here.
301 Here the number of variables appearing in the expression should be equal at most to the number of component of the DataArrayDouble instance on which \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const applyFunc method is called.
303 Let's consider the following DataArrayDouble having 4 tuples with 3 components called dd.
305 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_4
307 If you intend to create a new DataArrayDouble instance called \c dd1 having only one component that is the result of the sum of first component and the square root of the second component and the third component
308 the invocation should be something like this :
310 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_5
312 \warning In the expression \c "f+sqrt(g)+h", there are 3 variables \c {"g","h","f"}. As seen \ref MEDCouplingArrayApplyFuncExprA1 "in link phase in expression evaluator" it is needed to match a variable to
313 the component id. The strategy of expression evaluator is the following. Sort ascendingly variables using their names and affect component id following this sorted list. It leads to :
314 - \c f will be attached to component #0 of \c dd
315 - \c g will be attached to component #1 of \c dd
316 - \c h will be attached to component #2 of \c dd
318 Considering the previous warning, let's try to perform an application of function to compute in a DataArrayDouble instance called \c dd2 starting by adding component #0 and component #2
320 \nThe expression \c "a+c" will add component #0 to component #1 as seen in warning section !!!! It can appear silly, but this strategy has been chosen in order to support different set of variables.
321 \n \ref ParaMEDMEM::DataArrayDouble::applyFunc2 "applyFunc2" and \ref ParaMEDMEM::DataArrayDouble::applyFunc3 "applyFunc3" methods have been developed to remedy to that feature that can be surprising.
322 \n These two methods are explained respectively \ref MEDCouplingArrayApplyFunc2 "here for applyFunc2" and \ref MEDCouplingArrayApplyFunc3 "here for applyFunc3".
324 Whatever it is possible to find a workaround using \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const applyFunc with 2 parameters.
325 \n Here is a solution to compute \c dd2 :
327 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_6
329 \subsection MEDCouplingArrayApplyFunc2 applyFunc2 method
331 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc2 here.
333 This method is very close to \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters".
335 The only difference is the mapping between variables found in expression and tuple id. Rather than using rank in string sorting as \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters uses" here the component information are considered.
337 Let's consider DataArrayDouble instance \c ddd constituted with 4 tuples containing each 3 components. The components are named respectively \c {"Y","AA","GG"} with following different units attached on them.
339 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_7
341 To compute the sum of the first component (component #0) and the third component (component #2) simply do that :
343 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_8
345 \subsection MEDCouplingArrayApplyFunc3 applyFunc3 method
347 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc3 here.
349 This method is very close to \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters" and \ref MEDCouplingArrayApplyFunc2 "applyFunc2".
351 The only difference is the mapping between variables found in expression and tuple id. Rather than using rank in string sorting as in \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters uses" or the component information as in \ref MEDCouplingArrayApplyFunc2 "applyFunc2", here an explicit vector is given in input.
353 Let's consider DataArrayDouble instance \c ddd constituted with 4 tuples containing each 3 components. To add first component (component #0) and the third component (component #2) simply do that :
355 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_9