2 \page medcoupling MEDCoupling
4 \section MEDCouplingIntro Introduction
6 \ref medcoupling "MEDCoupling" is a library (\b libmedcoupling.so or \b medcoupling.dll) fully written in C++ and wrapped to be called in Python too.
8 \ref medcoupling "MEDCoupling" C++ library implements a data structure which is the result of the following tradeoff :
10 - Compliant with coupling :
11 - Fields definition defined enough to perform well defined interpolation
12 - exchangeable through process as well in parallel case in SPMD paradigm ( \ref paramedmem "ParaMEDMEM" ), as in distributed paradigm using CORBA.
13 - minimize as much as possible the number of prerequisites needed to use it ; So \ref medcoupling "MEDCoupling" only depends from
14 \ref interpkernel "INTERP_KERNEL library"
15 - light enough to be agile in order to :
16 - maximize the amount of algorithms being applied on it
17 - to ease implementation of clients of \ref medcoupling "MEDCoupling".
18 - large enough to be used for MED file I/O.
19 - compliant with VTK visualization DataStructure
20 - integrate HPC constraints (compact structures, limitation of copies and launching of CPU consuming algorithms only when absolutely needed ).
21 - compliant with ICOCO API
23 The \ref medcoupling "MEDCoupling" data structure is \b fully \b independant from those implemented in MEDMEM.
25 \ref medcoupling "MEDCoupling" implements a set of algorithms linked to the data structure.
27 \section MEDCouplingMainConc Main Concepts
29 Here are listed basic concepts present into \ref medcoupling "MEDCoupling".
31 For beginners in \ref medcoupling "MEDCoupling" world, it is advisable to read the following concepts in the same order than the underlying list.
33 - \subpage MEDCouplingArrayPage "DataArrays"
34 - \subpage MEDCouplingMeshesPage "Meshes"
35 - \subpage MEDCouplingFieldsPage "Fields"
36 - \subpage MEDCouplingFieldTemplatesPage "Field templates"
37 - \subpage MEDCouplingTimeLabelPage "Time labels"
42 \page MEDCouplingMeshesPage Meshes in MEDCoupling
44 \section MEDCouplingMeshes Common concept shared by all type of Meshes in MEDCoupling
46 A mesh has a the following properties :
49 - **a dimension (called mesh dimension) and only one** (it implies that \b all cells constituting
50 mesh have the same dimension)
51 - a space dimension (relative to coordinates)
55 In MEDCoupling library there is no presence of faces nor edges.
57 As a mesh has one dimension and only once, that is to say every cells in
58 mesh have the same dimension called MeshDimension.
61 MEDMEM vocabulary of faces and edges \b do \b not \b exist \b anymore here in
64 For exemple a mesh with a meshDimension equal to 1, have \b cells of type
65 NORM_SEG2. An another exemple, a mesh with a meshDimension equal
66 to 2, have \b cells of type
67 NORM_TRI3 and NORM_POLYGON for example.
69 The class that incarnates the concept described above is :
70 \ref ParaMEDMEM::MEDCouplingMesh.
72 \section MEDCouplingMeshesAvailInstan Available instaciable mesh types in MEDCoupling
74 - \subpage MEDCouplingUMeshPage "Unstructured meshes"
75 - \subpage MEDCouplingCMeshPage "Cartesian meshes"
76 - \subpage MEDCouplingExtrudedPage "3D Extruded meshes"
79 \page MEDCouplingFieldsPage Fields in MEDCoupling
83 \section MEDCouplingFields Field concept
85 A field in MEDCoupling point of view, is a structure that allows to
86 store a discretization of a physical value on a defined discretized spatial and
87 possibly temporal support.
89 The spatial support is a \ref MEDCouplingMeshesPage "mesh".
90 A field is lying on an entity that will be specified by the spatial
91 discretization of the field. For exemple a field on node will lie on
92 all nodes of its mesh.
94 A field on cell will lie on all cells of its mesh.
96 Fields in MEDCoupling follow the two following rules :
98 - A field will lie on \b ALL entities of its spatial support (\ref MEDCouplingMeshesPage "mesh").
99 - A field has \b only \b one spatial support (\ref MEDCouplingMeshesPage "mesh") on its temporal support.
101 The main properties of a field are :
104 - spatial support which is a \ref MEDCouplingMeshesPage "mesh"
105 - a \ref MEDCouplingSpatialDisc "spatial discretization"
106 - a description of intrinsic nature of the values of field (see \ref NatureOfField). This is important for conservative interpolation (see \ref TableNatureOfField).
107 - a temporal discretization that specifies, if it exists, the time interval on which the field is covering, and how.
108 - number of components
110 This definition of field in MEDCoupling allows an instance of field to
111 know at any point inside its spatial-temporal support the value.
113 The class that incarnates the concept described above is : \ref ParaMEDMEM::MEDCouplingFieldDouble.
115 Some of most important implemented methods are :
117 - \ref ParaMEDMEM::MEDCouplingFieldDouble::getNumberOfComponents "getNumberOfComponents"
118 - \ref ParaMEDMEM::MEDCouplingFieldDouble::getValueOn "getValueOn"
119 - \ref ParaMEDMEM::MEDCouplingFieldDouble::applyFunc "applyFunc"
120 - \ref ParaMEDMEM::MEDCouplingFieldDouble::addFields "cross instances operations"
121 \section MEDCouplingSpatialDisc Spatial discretization concept
123 This is the concept that makes the link, independantly from temporal
124 discretization, between the field and its spatial support(\ref MEDCouplingMeshesPage "mesh"). This
125 concept allows the field to make a check and interpretation of an
126 array of values given a spatial support (\ref MEDCouplingMeshesPage "mesh").
128 The abstract class that incarnates the concept is : \ref ParaMEDMEM::MEDCouplingFieldDiscretization.
130 The most important pure virtual methods are :
132 - \ref ParaMEDMEM::MEDCouplingFieldDiscretization::getNumberOfTuples "getnumberOfTuples"
133 - \ref ParaMEDMEM::MEDCouplingFieldDiscretization::getValueOn "getValueOn"
134 - \ref ParaMEDMEM::MEDCouplingFieldDiscretization::getMeasureField "getMeasureField"
136 \section MEDCouplingTemporalDisc Temporal discretization concept
138 This information allows, independantly from spatial discretization, to
139 associate a time interval, if it exists, on which the field will be
140 defined. This concept is able to give the value at any time of
141 the definition interval (if any).
143 The abstract class \ref ParaMEDMEM::MEDCouplingTimeDiscretization
144 incarnates this described concept.
146 This classes and its subclasses are responsible in storing the arrays
147 of the aggregating field.
149 The most important methods are :
151 - \ref ParaMEDMEM::MEDCouplingTimeDiscretization::setTime "setTime" and \ref ParaMEDMEM::MEDCouplingTimeDiscretization::getTime "getTime"
152 - \ref ParaMEDMEM::MEDCouplingTimeDiscretization::getArray "getArray" and \ref ParaMEDMEM::MEDCouplingTimeDiscretization::setArray "setArray"
153 - \ref ParaMEDMEM::MEDCouplingTimeDiscretization::getArraysForTime "getArraysForTime"
154 - \ref ParaMEDMEM::MEDCouplingTimeDiscretization::getValueForTime "getValueForTime"
156 \section MEDCouplingFirstSteps3 Building a field from scratch
158 Here we will make the assumption that an instance of \c MEDCouplingMesh called \c mesh has been created ( to know more about mesh creation \ref MEDCouplingUMeshStdBuild "click here" ).
160 \subsection MEDCouplingFirstSteps3OnCellsNoTS Create a tensor field with 9 components on cells with no time step
162 \subpage medcouplingcppexamplesFieldDoubleBuild1 "Here the C++ implementation."
164 \subpage medcouplingpyexamplesFieldDoubleBuild1 "Here the Python implementation."
166 \subsection MEDCouplingFirstSteps3OnNodesNoTS Create a scalar field on nodes with no time step
168 \subpage medcouplingcppexamplesFieldDoubleBuild2 "Here the C++ implementation."
170 \subpage medcouplingpyexamplesFieldDoubleBuild2 "Here the Python implementation."
172 \subsection MEDCouplingFirstSteps3OnCellsWTS Create a 2 components-vector field on cells with one time step and no interval
174 \subpage medcouplingcppexamplesFieldDoubleBuild3 "Here the C++ implementation."
176 \subpage medcouplingpyexamplesFieldDoubleBuild3 "Here the Python implementation."
178 \subsection MEDCouplingFirstSteps3OnCellsCTI Create a 3 components-vector field on nodes with a time interval where field remains constant on this time interval
180 \subpage medcouplingcppexamplesFieldDoubleBuild4 "Here the C++ implementation."
182 \subpage medcouplingpyexamplesFieldDoubleBuild4 "Here the Python implementation."
184 \section MEDCouplingSecondStep0 Operations on Fields
186 Here we will make the assumption that an instance of \ref ParaMEDMEM::MEDCouplingMesh "MEDCouplingMesh"
187 called \c mesh has been created with spaceDim==2.
189 \subpage medcouplingcppexamplesFieldDoubleBuild5 "Here a C++ example of more advanced use of MEDCouplingFieldDouble instances".
191 \subpage medcouplingpyexamplesFieldDoubleBuild5 "Here a Python example of more advanced use of MEDCouplingFieldDouble instances".
197 \page MEDCouplingArrayPage MEDCoupling Arrays
201 \section MEDCouplingArrayIntro Introduction
203 One of the most basic concept mainly used all over MEDCoupling is
206 This concept is used all over
207 \ref medcoupling "MEDCoupling", \ref paramedmem "ParaMEDMEM", \ref medloader "MEDLoader" modules so it should be correctly
208 handled to play well with \ref MEDCouplingMeshesPage "Meshes" and \ref MEDCouplingFieldsPage "Fields".
210 \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".
212 There are for the moment two types of arrays :
213 - double precision float (64 bits) array incarnated by \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble class".
214 - signed integer (32 bits) array incarnated by \ref ParaMEDMEM::DataArrayInt "DataArrayInt class".
216 \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt" classes inherits from
217 \ref ParaMEDMEM::DataArray "DataArray" \b non \b instanciable \b class that factorizes some common methods of inherited instanciable classes.
219 In the rest of the documentation \b DataArray will be used for both \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt".
221 \section MEDCouplingArrayBasics Basics concepts of the DataArrays.
223 It will be presented in this section common concept shared by the two classes to \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt".
225 \subsection MEDCouplingArrayBasicsName Name
227 A \ref ParaMEDMEM::DataArray "DataArray" instance has an attribute **name**.
229 **name** is particulary useful for \ref ParaMEDMEM::DataArray "DataArray" representing profiles, families, groups, fields in MEDLoader.
230 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.
231 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.
233 \subsection MEDCouplingArrayBasicsTuplesAndCompo Raw data, tuples and components of DataArrays.
235 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".
237 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
238 the product of the __number of elements__ * __constant size of DataType__ .
240 As \ref ParaMEDMEM::DataArray "DataArray" instances are designed to store vector fields, tensor fields, coordinate of nodes, the notion of _components_ has been added.
242 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.
243 The vector of atomical elements stored into \ref ParaMEDMEM::DataArray "DataArrays" are grouped in contiguous memory set of atomical elements having each same size.
245 The contiguous set of atomical elements is called **tuple**. And each **tuple** stored in raw data, have each a length exactly equal to the number of components of
246 \ref ParaMEDMEM::DataArray "DataArray" storing it.
251 N_{elements}=N_{tuples}*N_{components}.
255 N_{bytes}=N_{elements}*sizeof(DataType)=N_{tuples}*N_{components}*sizeof(DataType).
258 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
259 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.
261 Typically in the **raw data** of \ref ParaMEDMEM::DataArray "DataArrays" **number of tuples** is highly bigger than **number of components** !
263 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.
265 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.
266 \n The *raw data* of the DataAarray instance will be organized in momory 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$.
269 \subsection MEDCouplingArrayBasicsCompoName Information on components name.
271 As seen in the sub section above, a \ref ParaMEDMEM::DataArray "DataArray" instance has a defined number of components.
273 Their is an information attached to each of these components constiting the \ref ParaMEDMEM::DataArray "DataArray".
275 This information is concretely a string of caracters that allows, if needed, to give information about the conresponding component.
277 The format chosen in **MEDCoupling** for information on is "MY_COMPO_INFO [MYUNIT]". If needed, the unit attached to the component
278 should be put between "[" and "]" after the information of the components after one space caracter.
280 \subsection MEDCouplingArrayBasicsTimeLabel DataArrays and TimeLabel.
282 \ref ParaMEDMEM::DataArray "DataArrays instances" can consume big amount of data in memory so they inherit from \subpage MEDCouplingTimeLabelPage "TimeLabel".
283 So in C++ it is a good practice to use :
284 - \c getConstPointer method in readonly access.
285 - \c getPointer method only if write is needed.
287 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
288 \c setIJSilent just after invokation of \c declareAsNew instead of calling \c setIJ method that will increment time label of \ref ParaMEDMEM::DataArray "DataArray" instance
291 \c setIJ method usage should be reduced to little modification sessions.
293 \section MEDCouplingArraySteps0 Building an array from scratch in Python
295 \subsection MEDCouplingArraySteps0Double Building an double array from scratch in Python
297 Let's consider a list of floats \c dataDouble.
299 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_0
301 The easiest way to build the \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble instance" called \c arrayDouble simply call :
303 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_1bis
305 An another way is to do that :
307 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_1
309 \subsection MEDCouplingArraySteps0Int Building an int array from scratch in Python
311 Let's consider a list of ints \c dataInt.
313 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_2
315 The easiest way to build the \ref ParaMEDMEM::DataArrayInt "DataArrayInt instance" called \c arrayInt simply call :
317 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_3bis
319 An another way is to do that :
321 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayBuild1_3
324 \section MEDCouplingArraySteps1 Building an array from scratch in C++
326 Here is a description of typical usages of \ref ParaMEDMEM::DataArrayDouble "MEDCoupling arrays".
328 In this example we will create arrays with 12 tuples constituted each
329 of 3 components. These arrays will be created using different ways.\n
331 The following code is only based using \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble"
332 but the use of \ref ParaMEDMEM::DataArrayInt "DataArrayInt" is strictly equivalent.
334 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_0
336 \subsection MEDCouplingArraySteps1NCNO Building an array from scratch in C++, no copy no ownership
338 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_1
340 \subsection MEDCouplingArraySteps1NCWCPPO Building an array from scratch in C++, no copy with C++ ownership
342 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_2
344 \subsection MEDCouplingArraySteps1NCWCO Building an array from scratch in C++, no copy with C ownership
346 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_3
348 \subsection MEDCouplingArraySteps1WC Building an array from scratch in C++, with copy
350 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_4
352 \section MEDCouplingArrayBasicsCopy Copy DataArrays.
354 As \ref ParaMEDMEM::DataArray "DataArrays" are the atomic entity of potentially big memory objects into \ref medcoupling "MEDCoupling"
355 , \ref ParaMEDMEM::DataArray "DataArrays" introduces concepts of copy and comparison that will be used by aggregating classes.
357 For more complex objects (that aggregate themselves big objects)
358 like ParaMEDMEM::MEDCouplingFieldDouble the concept of copy (shallow or deep) is less straight forward because which aggregated subobjects are copied or not.
360 \subsection MEDCouplingArrayBasicsCopyDeep Deep copy of DataArray
362 As for all potentially heavy memory consumer objects in \ref medcoupling "MEDCoupling", \ref ParaMEDMEM::DataArray "DataArrays" implement
363 method \c deepCpy. This method deeply copies an instance. The life cycle of the returned object is *fully* independant from the instance on which the method
364 \c deepCpy has been invoked.
366 To perform a deep copy of a DataArray instance simply invoke :
368 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_5
372 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_5bis
374 \c myCoordsCpy is the deep copy of \c myCoords so they are independant and their *raw data* has been deeply copied.
376 So it leads to the following behaviour :
377 \anchor MEDCouplingArrayBasicsCopyDeepTestEqual
379 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_6
381 As \c myCoordsCpy is a copy object it needs to be deallocated in C++ like \c myCoords.
383 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_7
385 \subsection MEDCouplingArrayBasicsCopyShallow Shallow copy of DataArray
387 As \ref ParaMEDMEM::DataArray "DataArrays" are the atomic entity of potentially big memory objects into \ref medcoupling "MEDCoupling", the shallow copy
388 simply returns the same object with the reference counter incremented.
390 To perform a shallow copy of a DataArray instance simply invoke :
392 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_8
394 \c myCoordsCpy is the shallow copy of \c myCoords so they share the same *raw data*. In reality they are the same object.
395 So it leads to the following behaviour to compare with the deep copy :
397 \anchor MEDCouplingArrayBasicsCopyShallowTestEqual
399 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_9
401 So here the content of \c myCoords and \c myCoordsCpy are linked, contrary to the deep copy case.
403 As \c myCoordsCpy is a copy object, in C++, it needs to be deallocated.
405 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_10
407 \subsection MEDCouplingArrayBasicsCopyDeepAssign Assignation by deep copy of DataArray
409 We start by building a instance of ParaMEDMEM::DataArrayDouble allocated or not. Here, instance is not allocated, only built empty.
411 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_11
413 Then, \c myCoordsCpy is assigned with the content of \c myCoords.
415 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_12
417 Then \c myCoordsCpy is a deep copy of \c myCoords except that the instance of ParaMEDMEM::DataArrayDouble is those specified.
418 But the behaviour is the same than those seen for \ref MEDCouplingArrayBasicsCopyDeepTestEqual "deep copy".
420 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_13
422 As always, in C++, \c myCoordsCpy is an object whose life cycle is fully independant from \c myCoords so decrement is needed.
424 \snippet MEDCouplingExamplesTest.cxx CppSnippetDataArrayBuild1_14
426 \section MEDCouplingArrayBasicsCompare Compare DataArrays.
428 Comparison is \ref medcoupling "MEDCoupling" is a concept highly sensitive because big amount of tests uses this to state about the sucess or the fail of these tests.
429 There are two types of comparison :
431 - strict, that compares strictly all the non mutable attributes (state sensitive). Methods to perform this strict comparison are :
432 - ParaMEDMEM::DataArrayInt::isEqual
433 - ParaMEDMEM::DataArrayDouble::isEqual.
435 - less strict, that focus only on non string attributes. Methods to perform less strict comparison are :
436 - ParaMEDMEM::DataArrayInt::isEqualWithoutConsideringStr
437 - ParaMEDMEM::DataArrayDouble::isEqualWithoutConsideringStr
439 \section MEDCouplingArrayFill Filling DataArray with values
441 Both DataArrayDouble and DataArrayInt provide comfort methods that
442 fill the array with some values. These methods are:
443 - ParaMEDMEM::DataArrayInt::fillWithZero and
444 ParaMEDMEM::DataArrayDouble::fillWithZero which assigns zero to all
446 - ParaMEDMEM::DataArrayInt::fillWithValue and
447 ParaMEDMEM::DataArrayDouble::fillWithValue which assigns a certain value to all
449 - ParaMEDMEM::DataArrayInt::iota() and
450 ParaMEDMEM::DataArrayDouble::iota() which assigns incrementing values to all
453 \section MEDCouplingArrayRenumbering Array renumbering
455 Here is presented all it is necessary to know concerning renumbering.
456 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.
457 But it is also used on operations of node cell merging. It is also used in parallel mode when splitting of mesh is needed...
459 Formally a renumbering is a mathematical application that can be surjective, injective or bijective. This application is defined using an instance of
460 \ref ParaMEDMEM::DataArrayInt "DataArrayInt". There are different ways to define this application.
462 \subsection MEDCouplingArrayRenumberingO2N Old to new mode
464 The old to new mode is particulary recommanded for surjective and bijective application. This is typically the case of \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "MEDCouplingUMesh::mergeNodes" method.
465 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::mergeNodes "mergeNodes" that reduces the number of nodes from 5 nodes to 3 nodes.\n
466 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
468 If \b MySujection equals [2,1,0,1,2], it means that :
470 - old id #0 will have new id equal to 2
471 - old id #1 will have new id equal to 1
472 - old id #2 will have new id equal to 0
473 - old id #3 will have new id equal to 1 like old id #1
474 - old id #4 will have new id equal to 2 like old id #0
476 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.
478 Method in old to new mode that works on bijective applications :
480 - \ref ParaMEDMEM::DataArrayDouble::renumber "DataArrayDouble::renumber"
481 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlace"
483 Method in old to new mode that works on surjective applications :
485 - \ref ParaMEDMEM::DataArrayDouble::renumberAndReduce "DataArrayDouble::renumberAndReduce"
487 Sometimes the format old to new for sujections can be replaced by another format with 2 arrays. Less compact in memory. The \ref ParaMEDMEM::DataArrayInt::changeSurjectiveFormat "DataArrayInt::changeSurjectiveFormat" method performs that.
489 \subsection MEDCouplingArrayRenumberingN2O New to old mode
491 The new to old mode is particulary recommanded for strictly injective and bijective permutations. This is particulary usefull for methods that increase the number of entities like for example
492 \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "MEDCouplingUMesh::simplexize".\n
493 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
495 Let's consider a call to \ref ParaMEDMEM::MEDCouplingUMesh::simplexize "simplexize" that increases the number of cell from 4 cells to 6 cells.\n
496 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
497 If \b MyInjection equals [2,0,1,1,3,0] it means that :
499 - new id #0 comes from old id 2
500 - new id #1 comes from old id 0
501 - new id #2 comes from old id 1
502 - new id #3 comes from old id 1
503 - new id #4 comes from old id 3
504 - new id #5 comes from old id 0
506 Method in new to old mode that works on bijective applications :
508 - \ref ParaMEDMEM::DataArrayDouble::renumberR "DataArrayDouble::renumberR"
509 - \ref ParaMEDMEM::DataArrayDouble::renumberInPlace "DataArrayDouble::renumberInPlaceR"
511 Method in new to old mode that works on surjective applications :
513 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId "DataArrayDouble::selectByTupleId"
514 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleIdSafe "DataArrayDouble::selectByTupleIdSafe"
515 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleId2 "DataArrayDouble::selectByTupleId2"
516 - \ref ParaMEDMEM::DataArrayDouble::selectByTupleRanges "DataArrayDouble::selectByTupleRanges"
518 \section MEDCouplingArrayApplyFunc Application of a function on DataArrayDouble instances.
520 This section is only dedicated for \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble instances".
522 It is possible to apply to \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble instance" a function given by a string.
524 There are different API for applyFunc* methods of \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble class".
526 \subsection MEDCouplingArrayApplyFuncExpr Expressions supported
528 In order to reduce as much as possible dependancies, a little dynamic formula interpretor has been developped into INTERP_KERNEL.
529 This dynamic expression evaluator can deal the following exhaustive list :
531 - +,-,*,^ (^ for exponent 3^2==9)
532 - sin,cos,tan,sqrt,abs,exp,max,min,ln (neper logarithm), log (neper logarithm), log10 (decimal logarithm),
536 The expression evaluator is also sensitive to the following var pattern : IVec, JVec, KVec, LVec,... ,ZVec
538 - IVec stands for unitary vector [1,0,0,0,...]
539 - JVec stands for unitary vector [0,1,0,0,...]
540 - KVec stands for unitary vector [0,0,1,0,...]
543 The dynamic expression evaluator works tuple by tuple through the *raw data* of DataArrayDouble instance.
545 The principle of the dynamic expression evaluator is the following :
547 - Given the input string a compilation tree is built whose leaves are either constants or variables.
548 At this phase only syntax errors are thrown.
549 \anchor MEDCouplingArrayApplyFuncExprA1
550 - Then given the computed tree, a link phase is performed to accelerate evaluation. At this phase the incoherence between the number of
551 components and the number of variables are detected.
553 - The given the preprocessed tree given an input tuple a preallocated tuple is fed with the result of the evaluation.
554 At this last phase only mathematical errors are thrown (division by 0, log(0), sqrt of a negative number ...)
556 \subsection MEDCouplingArrayApplyFunc0 applyFunc method with only one parameter
558 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
559 \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method is applied.
561 **This method is useful when the evaluation expression do not need to consider the components of each tuple separately**.
563 That's why this method of \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method with one parameter accepts at most only one variable.
565 If it is not the case an exception is thrown as seen here :
567 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_1
569 Let's take a very simple example on a DataArrayDouble instance \c d having 4 tuples and 2 components.
571 In the next example the expression contains only one variable : \c smth.
572 So \c smth represent a tuple of size 2.
574 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_2
576 As the example shows, the output \c d1 has 2 components as \c d.
578 Whereas all the components of the input of \c d be not considered separetely, it is also, possible with \ref ParaMEDMEM::DataArrayDouble::applyFunc(const char *) const applyFunc method with one parameter
579 to build an output having same number of components than input but where components in input are treated separetely.
581 Let's build an example using DataArrayDouble instance \c d defined just above.
583 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_3
585 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.
587 \subsection MEDCouplingArrayApplyFunc1 applyFunc method with only two parameters
589 This method alse 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 pervious \ref MEDCouplingArrayApplyFunc0 "applyFunc with one parameter version" here the number of components is set by the user.
591 The big difference with \ref MEDCouplingArrayApplyFunc0 "applyFunc method with one parameter" seen above is that here components of tuples are treated separately.
593 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const here.
595 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.
597 Let's consider the following DataArrayDouble having 4 tuples with 3 components called dd.
599 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_4
601 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 le square root of the second component and the thrid component
602 the invokation should be something like this :
604 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_5
606 \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
607 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 :
608 - \c f will be attached to component #0 of \c dd
609 - \c g will be attached to component #1 of \c dd
610 - \c h will be attached to component #2 of \c dd
612 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
614 \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.
615 \n \ref ParaMEDMEM::DataArrayDouble::applyFunc2 "applyFunc2" and \ref ParaMEDMEM::DataArrayDouble::applyFunc3 "applyFunc3" methods have been developped to remedy to that feature that can be surprising.
616 \n These two methods are explained respectively \ref MEDCouplingArrayApplyFunc2 "here for applyFunc2" and \ref MEDCouplingArrayApplyFunc3 "here for applyFunc3".
618 Whatever it is possible to find a workaround using \ref ParaMEDMEM::DataArrayDouble::applyFunc(int,const char *) const applyFunc with 2 parameters.
619 \n Here is a solution to compute \c dd2 :
621 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_6
623 \subsection MEDCouplingArrayApplyFunc2 applyFunc2 method
625 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc2 here.
627 This method is very close to \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters".
629 The only different 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.
631 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.
633 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_7
635 To compute the sum of the first component (component #0) and the third component (component #2) simply do that :
637 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_8
639 \subsection MEDCouplingArrayApplyFunc3 applyFunc3 method
641 The method that implements it is \ref ParaMEDMEM::DataArrayDouble::applyFunc3 here.
643 This method is very close to \ref MEDCouplingArrayApplyFunc1 "applyFunc method with only two parameters" and \ref MEDCouplingArrayApplyFunc2 "applyFunc2".
645 The only different 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.
647 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 :
649 \snippet MEDCouplingExamplesTest.py PySnippetDataArrayApplyFunc1_9
654 \defgroup NatureOfField Nature of a field
656 \section IntExtFields Overview: intensive and extensive field
658 \c NatureOfField is an enum which helps determining some physical significance of the field and affects the choice of the interpolation formula (see \ref TableNatureOfField).
659 It has five possible values:
660 - "NoNature", the default value, does not allow the use of any interpolation tools
662 - \ref TableNatureOfFieldExampleConservVol "ConservativeVolumic", for intensive field with the maximum principle favored over conservativity. Relevant for temperature, pression fields.
664 - \ref TableNatureOfFieldExampleRevIntegral "RevIntegral", for intensive field with the conservativity favored over maximum principle. Relevant for power density fields.
666 - \ref TableNatureOfFieldExampleIntegral "Integral", for extensive field with the maximum principle favored over conservativity. Relevant for power fields.
668 - \ref TableNatureOfFieldExampleIntegralGlobConstraint "IntegralGlobConstraint", for extensive fields with conservativity favored over the maximum principle. Relevant for power fields.
670 The first two correspond to intensive fields, the last two correspond to extensive fields.
672 By an intensive field we mean a field that represent an intensive physical variable such as density (\f$kg.m^{-3}\f$), power density (\f$W.m^{-3}\f$), temperature (\f$K\f$) or pressure (\f$Pa\f$). Typically the physical value doesn't scale with the size of the underlying geometry.
673 By extensive (or integral) field we mean a field that represents an extensive physical quantity such as mass (\f$kg\f$), volume (\f$m^3\f$), a momentum (\f$kg.m.s^{-1}\f$) or power \f$(W\f$).
674 Typically the field value scales linearly with respect to the underlying geometry size.
675 For fields with a P0 representation (cell based), conservativity formulas are different depending on whether the field is extensive or intensive (see \ref InterpKerP0P0Int and \ref InterpKerP0P0Ext).
676 Those two notions are themselves split into two sub-categories.
677 Indeed in some cases (e.g. non \ref MeshOverlap "overlapping meshes"), it is impossible to fulfill both the conservation principle and the maximum principle during the interpolation. The nature of the fields determine the formula to be used for non overlapping cells and thus the property that we will be satisfied.
678 Finally we consider that fields with P1 or P2 representations are necessarily intensive.
682 In order to employ the various \ref interptools, you have to specify the nature of your field.
683 When the source and target meshes do not overlap, different treatments will be employed depending on the nature of the source and target fields.
684 You can specify the nature of the field when you create a \ref medcoupling field with the following constructor:
686 MEDCouplingFieldDouble(NatureOfField n, MEDCouplingTimeDiscretization *td, MEDCouplingFieldDiscretization *type);
689 If you read or copy an already existing field, or later after its creation, you may want to change/set its nature.
690 In order to do so, you can use the function
693 void setNature(NatureOfField nat);
700 const char sourceFileName[]="source.med";
701 MEDCouplingFieldDouble *sourceField=MEDLoader::ReadFieldCell(sourceFileName,"Source_Mesh",0,"Density",/*iteration*/0,/*order*/0);
702 const char targetFileName[]="target.med";
703 MEDCouplingUMesh *med_target_mesh=MEDLoader::ReadUMeshFromFile(targetFileName,"Target_Mesh",0);
705 sourceField->setNature(ConservativeVolumic);
712 \page MEDCouplingUMeshPage Unstructured meshes in MEDCoupling
716 An unstructured mesh in \ref medcoupling MEDCoupling is defined by :
718 - a point clouds where the explicit coordinates of each point must be specified (inherited from \subpage MEDCouplingPointSetPage "MEDCouplingPointSet class").
719 - nodal connectivity that specifies for each cell, the points in the previous point clouds that constitutes the cell.
721 As unstructured mesh is dynamically defined enough, this class is also used by MEDCoupling to instanciate degenerated meshes as :
723 - points cloud only meshes. This type of mesh will have mesh dimension 0.
724 - abstract meshes containing only one cell that covers a potentially
725 infinite space. This abstract mesh is used as support of fields
726 containing only one integrated value. This is typically used to
727 represent fields used by system code. This type of mesh will have
728 mesh dimension equal to -1.
730 The norm used for cells connectivity of different types, is the same as specified in MED file except
731 that connectivities are in represented in \b C \b format and \b not \b in \b FORTRAN \b format !
733 The class that incarnates the described concept is : ParaMEDMEM::MEDCouplingUMesh.
734 \n This class inherits from ParaMEDMEM::MEDCouplingPointSet abstract class.
735 \n So \ref MEDCouplingUMeshPage "MEDCouplingUMesh" inherits from all \ref MEDCouplingPointSetPage "point set features".
737 \section MEDCouplingUMeshStdBuild Standard building of an unstructured mesh from scratch
739 The described method here is called standard, because no special knowledge of underneath nodal connectivity is needed here.
740 This method of building unstructured mesh is easiest but not the most CPU/memory efficient one.
742 All of exemples given here make the assumption that the \c ParaMEDMEM namespace is visible ( by calling for example \c using \c namespace \c ParaMEDMEM; ).
744 Here we will create a mesh with spacedim==3 and meshdim==2. \b mesh contains 5 cells (with geometric type INTERP_KERNEL::NORM_TRI3, INTERP_KERNEL::NORM_QUAD4)
747 You can notice that it is possible to mix cell types as long as the dimension of cell is exactly equal to meshDim to respect \ref MEDCouplingMeshes "this rule".
749 \subpage medcouplingcppexamplesUmeshStdBuild1 "Here is the C++ implementation."
751 \subpage medcouplingpyexamplesUmeshStdBuild1 "Here is the Python implementation."
753 \section MEDCouplingUMeshNodalConnectivity How MEDCouplingUMesh stores its nodal connectivity.
755 \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh class" stores its nodal connectivity into 2 arrays.
757 - The first one, the biggest is ParaMEDMEM::MEDCouplingUMesh::_nodal_connectivity.
758 - The second one, the less big is ParaMEDMEM::MEDCouplingUMesh::_nodal_connectivity_index.
760 \image html MEDCouplingUMeshConn.png "Nodal connectivity storage into MEDCouplingUMesh class"
761 \image latex MEDCouplingUMeshConn.eps "Nodal connectivity storage into MEDCouplingUMesh class"
763 \note The last value of the nodal connectivity index points to an invalid memory place. It is not an error, simply as for standard C++, all ranges
764 are given in format [\b begin,\b end) where \b begin is included and \b end excluded.
766 \section MEDCouplingUMeshAdvBuild Advanced building of an unstructured mesh from scratch
768 Here we are going to build the mesh in a more advanced manner. This method expects that the user knows the storage format underlying ParaMEDMEM::MEDCouplingUMesh.
770 The same mesh than \ref MEDCouplingUMeshStdBuild "in the standard section above" is going to be implemented using advanced method.
772 \subpage medcouplingcppexamplesUmeshAdvBuild1 "Here the C++ implementation."
774 \subpage medcouplingpyexamplesUmeshAdvBuild1 "Here the Python implementation."
779 \page MEDCouplingPointSetPage Point set meshes in MEDCoupling
781 This is a \b non \b instanciable class that implements many algorithm working only on a set of points without any connectivity aspect.
782 The presence of this class is only for factorization reasons.
784 The class that incarnates this concept in \ref medcoupling "MEDCoupling" is : \ref ParaMEDMEM::MEDCouplingPointSet.
785 Instanciable class ParaMEDMEM::MEDCouplingUMesh inherits from ParaMEDMEM::MEDCouplingPointSet.
787 Some of most important implemented methods by \ref ParaMEDMEM::MEDCouplingPointSet "MEDCouplingPointSet" class are :
789 - \ref ParaMEDMEM::MEDCouplingPointSet::getSpaceDimension "getSpaceDimension"
790 - \ref ParaMEDMEM::MEDCouplingPointSet::getNumberOfNodes "getNumberOfNodes"
791 - \ref ParaMEDMEM::MEDCouplingPointSet::rotate "rotate"
792 - \ref ParaMEDMEM::MEDCouplingPointSet::translate "translate"
793 - \ref ParaMEDMEM::MEDCouplingPointSet::scale "scale"
794 - \ref ParaMEDMEM::MEDCouplingPointSet::findCommonNodes "findCommonNodes"
795 - \ref ParaMEDMEM::MEDCouplingPointSet::renumberNodes "renumberNodes"
796 - \ref ParaMEDMEM::MEDCouplingPointSet::getBoundingBox "getBoundingBox"
800 \page MEDCouplingCMeshPage Cartesian meshes in MEDCoupling
802 A cartesian mesh is a mesh that represents structured mesh whose nodes are arranged along axes of trihedron.
804 To instanciate an object of this type, only n arrays are needed.
806 In this type of mesh space dimension \b and mesh dimension are equals and the value is n ( with n in [1,2,3] ).
808 The n arrays will have only one component and the values contained in these arrays will be ascendantly sorted.
810 The class that incarnates the described concept is : ParaMEDMEM::MEDCouplingCMesh.
812 \section MEDCouplingCMeshStdBuild Standard building of a cartesian mesh from scratch
814 Let's present an exemple of a 2D cartesian mesh.
816 \subpage medcouplingcppexamplesCmeshStdBuild1 "Here the C++ implementation."
818 \subpage medcouplingpyexamplesCmeshStdBuild1 "Here the Python implementation."
823 \page MEDCouplingExtrudedPage 3D Extruded meshes in MEDCoupling
825 An extruded mesh is a mesh also called 2.5 D.
827 It a convolution of 2D unstructured mesh with 1D unstructured mesh.
829 The problem is that this type of mesh is not managed by any file format that's why to build an instance of this mesh you need 3D unstructured mesh and a 2D
830 unstructured mesh lying on the same coordinates.
832 The advantage of this structure is that the interpolation time is highly improved.
834 This class is also useful for users that want to map the 3D unstructured mesh cell ids level by level along an axe.
836 The class that incarnates this concept in MEDCoupling is : \ref ParaMEDMEM::MEDCouplingExtrudedMesh.
840 \page MEDCouplingFieldTemplatesPage Field templates in MEDCoupling
842 This concept appears in ICOCO API.
843 field template is the adequate datastructure to perform costly interpolation matrix computation as \ref RemapperClasses "Remapper class" does.
844 So, a field template can be seen as field without double values. The double values are only used for light matrix vector multiplication.
846 Concretely a field template is a pair containing :
848 - a \ref MEDCouplingMeshesPage "mesh"
849 - a spatial discretization (on cells, on nodes, on gauss points (including localizations, reference elements), )
854 \page MEDCouplingTimeLabelPage Time label in MEDCoupling
856 Time label is a **non instanciable** class whose each objects consuming potentially big amount of memory inherit from.
857 The class that incarnates this concept is ParaMEDMEM::TimeLabel.
859 Here some of examples of classes that inherit from \ref ParaMEDMEM::TimeLabel "TimeLabel" class :
861 - ParaMEDMEM::DataArrayInt, ParaMEDMEM::DataArrayDouble
862 - ParaMEDMEM::MEDCouplingMesh
863 - ParaMEDMEM::MEDCouplingFieldDouble
866 This class is in charge to store a 32 bits unsigned integer called time label, that allows the user to know easily, if an heavy object in memory has been modified or not.
868 The usage is simple :
870 - call ParaMEDMEM::TimeLabel::getTimeOfThis a first time to retrieve a reference. Store the returned unsigned integer.
871 - when you need to know if the instance inheriting from ParaMEDMEM::TimeLabel has changed or not simply invoke ParaMEDMEM::TimeLabel::getTimeOfThis again and compare with the stored value.
872 If the value is different, the instance has changed, if not the instance has **not** changed.
874 The virtual call to ParaMEDMEM::TimeLabel::updateTime change the behaviour of ParaMEDMEM::TimeLabel::getTimeOfThis it is a bug, so please notify the bug into the salome forum.