2 \page medloader MEDLoader
6 \section MEDLoaderIntro Introduction
8 \ref medloader "MEDLoader" is a package in charge of loading from a file or write to a file
9 in MED format a \ref medcoupling data structure. The fact that these
10 functionalities are not merged in \ref medcoupling is explained by a
11 willingness of reducing as much as possible the dependencies of \ref medcoupling libraries.
13 As a MED file can combine several \ref medcoupling aspects in one (for example meshes in
14 MED file on different mesh dimension with families and groups) the API
15 of \ref medloader "MEDLoader" is much more rich than simply read and write.
17 \ref MEDCouplingMeshesPage "MEDCoupling mesh" is \b not as rich as a MED file mesh, and a \ref MEDCouplingFieldsPage "MEDCoupling field" is \b not as rich as a MED file field.
18 But it is possible to emulate with a very good fidelity a MED file mesh and a MED file field with a collection of MEDCoupling instances for each.
20 \section MEDLoader2Approaches Two approaches are available in MEDLoader : Advanced API, Basic API
22 \ref medloader "MEDLoader" module offers two different approaches to perform Read/Write from/to MED file.
24 - \ref MEDLoaderAdvApproach "advanced API approach"
25 - \ref MEDLoaderBasicApproach "basic API approach"
27 Whatever the approach(es) you choose, it is advisable to know main concepts of MED files \ref MEDLoaderMainC "that are quickly reminded here."
29 \subsection MEDLoaderAdvApproach Advanced API approach
31 \subpage MEDLoaderAdvancedAPIPage "A specific page dedicated to the advanced API is available here".
33 This approach is the most close to MED file. By using this advanced API approach the user will manipulates classes that represents MED file concepts.
35 It implies that the user should be informed about the \ref MEDLoaderMainC "MED file concepts", that do not exist in \ref medcoupling "MEDCoupling". For example :
37 - group/family in meshes
40 This is typically the case for a user that wants to precisely set/get mesh/group/family groups set on different level.
42 *That's why a set of classes representing a memory representation of MED file concepts are proposed by advanced API approach.*
44 *So All information contained in file is represented in advanced API class instances.*
46 The level of coherency check is variable across methods, to let to the user the maximal capacity of modification of its MED file data in memory.
48 This API is particularly recommended :
50 1. For users that want to repair a MED file (invalid family ids, invalid mesh dimension, mismatch of family ids, numbering cells/nodes array modification)
51 2. For users that want to operate directly on complex MED file objects (split of MED files for example, duplication of nodes).
53 \subsection MEDLoaderBasicApproach Basic API approach
55 \subpage MEDLoaderBasicAPIPage "A specific page dedicated to the basic API is available here".
57 This approach is less close to MED file concepts, but closer to \ref MEDCouplingMainConc "MEDCoupling concepts".
59 So, basic API, is simpler as show method MEDLoader::WriteUMesh that needs no special knowledge needed of MED file concepts to interact with MED files.
61 This API is in the form of a list of public static methods a class ParaMEDMEM::MEDLoader.
63 This simplicity has a cost, the I/O are not (cannot be) optimized.
65 As MED file concepts are more complex than MEDCoupling concepts, this approach is not the most relevant for specific MED file objects read/write.
67 - Manipulation of multi level MED file mesh is not easy to manipulate with basic approach
69 - Manipulation of partial fields in not easy to manipulate too with basic approach
72 \subsection MEDLoaderCohabitationApproach Cohabitation of the two approaches
74 The two approaches are \b NOT opposed, they are compatible each other so it is possible to mix them.
76 Typically it is possible to read rich information of a complex MED file using advanced API in read mode, and write a simpler MED file model
77 coming from a postprocessing of the complex input MED file data to a simple output MED file using basic API for writing.
79 \section MEDLoaderMainC Main concepts of MED files
81 Here we will describes some of basic concepts of MED files in order to
82 use the best methods proposed by \ref medloader "MEDLoader API".
84 \subsection BasicMEDLoaderAPIGen Basics in MED files
86 First of all **MEDLoader will not read MED files whose version is strictly lower than 2.2.**
88 For new comers in MED file world some of basics principles are recalled in the following graphic :
90 \image html MEDFileConcepts.png "Resumed MED file concepts"
92 Inside the parenthesis, there is multiplicity :
94 - + stands for [1,inf)
95 - * stands for [0,inf)
98 Each box are **independent in MED file format during read write session.**
100 **Boxes instances are linked each other only by red arrows using string as discriminating key.** It implies that empty names in basic concepts objects of MED file are forbidden.
102 There can be as many instance of boxes as wanted in a MED file.
104 **As it can be seen in MED file world, fields and meshes are sorted by geometric type**.
106 This specificity leads to a constraint during writing phase because some mesh operations may modify significantly the organization of geometric types during mesh/field operations.
107 \n Here some of operation that can alter the geometric type order of cells :
109 - aggregation of meshes
110 - aggregation of fields
111 - extraction of a part of meshes
112 - extraction of a part of fields
113 - partial polyhedrization of meshes
114 - unpolyhedronization of meshes
116 \section MEDLoaderCommonVoc Vocabulary used in MEDLoader
118 \subsection MEDLoaderCommonVocRelMeshDimMesh Relative mesh dimension in meshes
120 As it has been seen \ref BasicMEDLoaderAPIGen "above", all big arrays in fields and meshes (except coordinates) are sorted by geometric type, without any awareness of the dimension.
122 For example an unstructured mesh in MED file world can lie simultaneously on MED_TRI3, MED_POINT1, MED_POLYHED, MED_TETRA4..., \ref MEDCouplingMeshes "which is impossible in MEDCoupling" for manipulation reasons.
124 To connect the MED file world to the MEDLoader/MEDCoupling world the notion of **relative mesh dimension** has been introduced in \ref medloader "MEDLoader".
126 This concept of **relative mesh dimension** is used frequently in the \ref medloader "MEDLoader both APIs" ( \ref MEDLoaderBasicAPIPage "basic" and \ref MEDLoaderAdvancedAPIPage "advanced").
128 To explain the semantic of **relative mesh dimension** let's take the example of a mesh called \a myMesh in a MED file, containing MED_TRI3, MED_POINT1, MED_POLYHED, MED_TETRA4.
130 For each geometric type on which \a myMesh is defined the mesh dimension are :
132 - MED_TRI3 -> mesh dimension=2
133 - MED_POINT1 -> mesh dimension=0
134 - MED_POLYHED -> mesh dimension=3
135 - MED_TETRA4 -> mesh dimension=3
137 The mesh dimension of \a myMesh is equal to 3 ( \f max(2,0,3,3) ). The **relative mesh dimension** is equal to the difference between mesh dimension of geometric type and the mesh dimension
138 of the whole MED file dimension. It leads to the following **relative mesh dimension** :
140 - MED_TRI3 -> **relative mesh dimension** = -1
141 - MED_POINT1 -> **relative mesh dimension** = -3
142 - MED_POLYHED -> **relative mesh dimension** = 0
143 - MED_TETRA4 -> **relative mesh dimension** = 0
145 In \ref medloader "MEDLoader" all geometric information are then grouped relative dimension per relative dimension. It leads to the following geometric sorting of
146 MED file data structure of \a myMesh :
154 - nothing -> level **not** available for \a myMesh
158 The mesh dimension of \a myMesh is 3. The relative mesh dimensions available are 0, -1 and -3.
160 \subsection MEDLoaderCommonVocRelMeshDimField Relative mesh dimension in fields
162 As it has been seen previously in \ref MEDLoaderCommonVocRelMeshDimMesh "for meshes", the values of fields are sorted by levels too.
164 The principle is the same than those explained for meshes. The only difference is in the fact that it is possible for fields on cell and fields on Gauss points that mesh dimension of underlying mesh of a field is not always (but very often) equal to the dimension of geometric types on which this field is defined.
166 So it is advised, to compare the non empty level of a field **and** of its underlying mesh before trying to request heavy data from a MED file.
168 \subsection MEDLoaderCommonVocIterationOrder Iteration and order in MED file
170 As seen \ref BasicMEDLoaderAPIGen "above", fields in MED file can be defined on different time steps.
172 But there is a **major difference** with \ref medcoupling MEDCoupling concept in time steps. \ref medcoupling MEDCoupling is focused to the float value of time for interpolation reason.
174 \ref medloader MEDLoader and MED file are focused on pair of integer to precise a specific time steps.
176 This difference of point of view can be seen in the API where the order of returned parameters in python differs from MEDCouplingFieldDouble::getTime to MEDFileField1TS::getTime.
178 In MED file and so in \ref medloader MEDLoader the time steps are identified by a pair of integers called :
183 Order refers to sub iteration id, that is by default set to -1 in case of non use. A physical time with float type is attached to this pair of integer.
188 \page MEDLoaderBasicAPIPage Basic MEDLoader API.
192 The aim of this page is to present basic API of MEDLoader. The goal of
193 this basic API is to perform a read or a write in one shot without any
194 internal state. That's why the basic API of MEDLoader offers \b only \b static methods whose method names have the first
195 character in capital. You are intended to use these methods. The following
196 chapters will try to describe in details some of important ones.
198 The basic idea of MEDLoader is to exploit as much as possible MED
199 file capabilities to store MEDCoupling data file in a MED file and
200 reversely to load from a MED file into a MEDCoupling data structure.
201 Basically, the info on components of ParaMEDMEM::DataArrayDouble
203 instances are stores into components and units into MED files. The
204 name of meshes and fields are used by MEDLoader to use it as this into
205 MED file. A field f with \ref ParaMEDMEM::MEDCouplingTimeDiscretization
206 "time discretization" set to ONE_TIME, the value of
207 \c f->getTime(time,iteration,order) are used by MEDLoader to store
208 to identify the field into MED file. All strings used by MEDLoader to
209 use it into MED file should fulfill the rules of MED file where length
211 That's why the user should be aware of these constraints when trying to read/write a MED file using MEDLoader.
212 MEDLoader tries to manage that by protecting the user by throwing exceptions when the rules are not followed.
214 \section BasicMEDLoaderBasicAPIGlobalInfo Retrieving tiny global information from MED files using basic API
216 The MEDLoader::CheckFileForRead method will perform the check of that before any attempt of read.
217 A field is also discriminated by its name. The method MEDLoader::GetCellFieldNamesOnMesh and MEDLoader::GetNodeFieldNamesOnMesh are available to know all fields
218 respectively on cells and on nodes lying on a specified mesh.
220 A field is defined by several time steps discriminated by a pair of int
221 (iteration,order). It is \b not possible to store 2 time steps of a same
222 field having the same iteration and order
223 number. The floating point value attached on this couple of ids (iteration,order) is only present for information.
224 Static methods MEDLoader::GetCellFieldIterations and
225 MEDLoader::GetNodeFieldIterations return a vector of pair containing
226 each respectively iteration and order.
228 A time step of a field lies on one \b or \b more mesh(es) specified by its \b or \b their name. A time step of a field in
229 MED file could be defined on point \b and on cell \b and, \b or on Gauss points \b and, \b or on point per element.
231 This recalled specificities of MED file explains that it is necessary to specify each time, at field-read time, the type of field, the iteration and order number the mesh you are interested in.
233 Let's recall basic principles that explains some of the aspect of MEDLoade API.
234 \anchor MEDLoaderMeshNameConstraint MED file can contain several meshes. These meshes are
235 discriminated by their names (two meshes could not have the same
236 names). By the same way a MED file can contain several fields in MED.
237 So MEDLoader propose to you the MEDLoader::GetMeshNames method to
238 discover all the mesh names contained in your file.
240 \section BasicMEDLoaderBasicAPIMesh Reading and writing meshes in MED files using basic API
242 In MED file meshes could combine in one unstructured mesh cells that
243 have different dimension. For example it is possible to mix
244 MED_TETRA4, MED_TRIA6, MED_SEG2, MED_POINT1, MED_POLYGON,
245 MED_POLYHEDRA in a same mesh. In MEDCouplingUMesh such a mix is not
246 allowed as described \ref MEDCouplingUMeshes "here". So to \b read such mesh it
247 is important to know which meshdimension you are interested to. In API
248 the parameter \b meshDimRelToMax discreminates the meshdim you are
249 interested to relatively to the maximal dimension of cells contained
252 Let's take 2 examples :
254 - If you have a mesh called "MyMesh" in file "file1.med" with
255 MED_POLYGON, MED_TRI3, MED_SEG2 and MED_SEG3 : The max dimension of
256 cells is 2 (for MED_POLYGON and MED_TRI3). So if you want exclusively
257 cells with type MED_POLYGON and MED_TRI3 you should use :
259 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_9
261 If you are interested in MED_SEG2 and MED_SEG3 you should use :
263 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_10
265 The method MEDLoader::ReadUMeshDimFromFile could
266 help you to have this mesh dimension.
267 \anchor MEDLoaderExample2
268 - Consider an another mesh called "Example2" in file "file2.med"
269 containing MED_POLYHEDRA, MED_TETRA4, MED_QUAD8, MED_TRI6, MED_SEG2
270 and MED_POINT1. In this case you will have :
272 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_8
274 To get 3D cells (MED_POLYHEDRA and MED_TETRA4) you should type :
276 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_7
278 To get 2D cells (MED_TRI6 and MED_QUAD8) you should type :
280 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_4
282 To get 1D cells (MED_SEG2) you should type :
284 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_5
286 And finally for 0D cells (MED_POINT1) you will write :
288 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_6
290 To finish this subsection, it is important to know that MEDLoader
291 takes into account of the cell numbers stored in a mesh of a med
292 file. This renumbering allows MEDLoader to conserve the order of
293 MEDCoupling cells into the file. So if the renumbering of cells in MED
294 file is not correct an exception will be thrown.
296 \subsection BasicMEDLoaderAPIPoMesh Part of meshes in MED files
298 A mesh contains one or more families on nodes and/or on cells. A family is a partition
299 (mathematical sense) of the mesh it lies to. A family can be described
300 by an integer field on \b all nodes and on \b all cells of a same mesh.
301 All cells and nodes having the same ids defines this family. This id
302 is called the familyId. A family is discriminated by its id. MED file
303 attach a name to its id to be more user friendly. So by construction, 2 different
304 families could not share anything. The user can retrieve all the
305 families names available on a mesh with the static method MEDLoader::GetMeshFamiliesNames.
307 A group is a set of families. So groups can overlap each other,
308 contrary to families. Groups are also discriminated by a name. As for
309 families the static method to retrieves the groups of a specified mesh is MEDLoader::GetMeshGroupsNames.
311 MEDLoader allows you to retrieve the
312 corresponding "part of meshes" thanks to static methods
313 MEDLoader::ReadUMeshFromFamilies and MEDLoader::ReadUMeshFromGroups.
314 This method allows you to combine several families and groups in the
317 \subsection BasicMEDLoaderAPIField Reading a field at one time step in MED files
319 A field at one time step on one mesh, with one entity (cell, node)
320 lies on all mesh on a part of it. In this last case a definition of
321 a profile is needed. Even if the notions of profile on mesh and group
322 on mesh could appear close, these two concepts are totally
323 disconnected in MED file.
324 The aspect of profile is managed by MEDLoader, that is why this
325 aspect does not appear in the MEDLoader API.
326 So to retrieve a field on 3D cell called "F1Cell" in example file
327 \ref MEDLoaderExample2 "file2.med (seen in meshes section)" on a mesh "Example2" on time
328 step defined by iteration number 2 and iteration 3 the request will be :
330 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_12
332 To retrieve the same field (same iteration) on 2D cells only the call will be :
334 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_13
336 \subsection MEDLoaderMEDFieldsRead Reading several field time steps at a time in MED files
338 It is possible with MEDLoader to read several time steps of a field at
340 The advantage with this approach is to avoid to read and load several
341 time a same mesh. This is typically recommended to use the following
342 code when you desire to load all time steps of a field on cell "myField" lying on
343 same mesh "mesh1" in one shot :
345 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_11
347 \section MEDLoaderWriteMain Writing a MED file with MEDLoader
349 As MED file does, MEDLoader write process separates clearly
350 meshes from fields. The reason is that a common use case in write mode
351 is to write in a first time a mesh and then writes several time steps
352 of a same field in appended mode.
354 The fact that the write process is rarely in a one shot put a
355 constraint on API to precise to MEDLoader if you intend
356 to append data to an existing file, or if you want to create a new
357 file from scratch. This explains the presence of boolean parameter \b
358 writeFromScratch in API of MEDLoader starting with \b
361 If \b writeFromScratch parameter is set to \b true and if the file
362 already exists the file will be crashed and replaced by the new
363 corresponding data. If \b writeFromScratch parameter is set to \b false and if the
364 file does \b not \b exist the new file is created, but if the file
365 exists MEDLoader will enter in appended mode.
367 Two classes of MEDLoader write methods exists when \b writeFromScratch
370 - Methods \b MEDLoader::Write*Dep : The write operation is performed without any question in file. The
371 responsibility is let to the user because the MED file could be
372 corrupted. The advantage of this method is that it is faster
373 because no check is done.
374 - Methods \b MEDLoader::Write* : MEDLoader will not corrupt your file
375 by always trying to append data. The consequence of that is that a
376 read of part (and data processing) of MED file could be needed before any attempt of
377 writing. So these methods could be in some cases much time and memory consuming.
379 The behaviour of MEDLoader when \b writeFromScratch is set to false will be precised
380 for each \b MEDLoader::Write* methods is the next subsections.
382 \subsection MEDLoaderWriteMesh Writing one mesh in a MED file with MEDLoader
384 The first think to know is that MEDLoader is using the \b meshName in
385 ParaMEDMEM::MEDCouplingMesh instance to put it in MED file.
387 As explained in previous section \ref MEDLoaderMeshNameConstraint "here",
388 a mesh in MED file is discriminated by a name, so the \b meshName
389 \b should \b be \b non \b empty. If it is the case an
390 INTERP_KERNEL::Exception will be thrown.
392 To write one mesh \b myMesh with name \b "myMeshName" in a MED file \b "wfile1.med" the following code should be typed :
394 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_1
396 With the previous code, if "wFile1.med" file existed the file is
397 crashed and will contain after the call only the content of myMesh
400 If you desire to append a mesh in "wFile1.med" you should type :
402 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_2
404 With the previous code, if the "wFile1.med" had already a mesh called "myMeshName" an
405 INTERP_KERNEL::Exception will be thrown.
407 \subsection MEDLoaderWriteMeshes Writing several meshes in a MED file with MEDLoader
409 It could be interesting to write several meshes in one shot. Two
410 possiblities are possible :
412 - Write several instances of ParaMEDMEM::MEDCouplingUMesh
413 lying \b on \b same \b coords \b with \b different \b mesh \b dimension. In this case the
414 use of MEDLoader::WriteUMeshes is the method you should
415 use. Typically this method should be used to write such of file
416 defined \ref MEDLoaderExample2 "here".
417 This method first checks that all instances share the same
418 ParaMEDMEM::DataArrayDouble instance as coords. If not an
419 INTERP_KERNEL::Exception will be thrown and an invocation on
420 ParaMEDMEM::MEDCouplingPointSet::tryToShareSameCoords will be necessary.
422 - Write a partition of meshes having \b same \b mesh \b dimension, that is to say a set of
423 groups and families from given meshes. As in the previous case the
424 check of same coords will be done (if not an INTERP_KERNEL::Exception is
425 thrown). After this step this method will
426 merge (by preserving order in input) and will simplify the
427 merged mesh. After this operation, the groups will be constituted by
428 assigning the groups names with the corresponding names of
429 instance. That's why all meshes have to have a not empty name and
430 different each other. The method to use in this case is
431 MEDLoader::WriteUMeshesPartition.
433 For these 2 described methods the semantic of \b writeFromScratch when
434 \b false is the same, that is to say : no writing
435 (INTERP_KERNEL::Exception thrown) will be done if the
436 file already exists and contains already a mesh with name 'meshName'
437 for MEDLoader::WriteUMeshesPartition method and the name of the first
438 of the vector of unstructured meshes passed as first parameter of
439 MEDLoader::WriteUMeshes.
441 \subsection MEDLoaderWriteField Writing one time step of a field in a MED file with MEDLoader
443 To write \b one \b time \b step of a field from scratch with MEDLoader is to
444 use MEDLoader::WriteField method. The behaviour of this method depends
445 on the value of the \b writeFromScratch parameter :
447 - When \b writeFromScratch equals to \b true, this method performs two things, it
448 writes the underlying mesh and write the specified time step on it.
450 - When \b writeFromScatch equals to \b false, this method looks that
451 the underlying mesh exists (by looking the content of \c field->getMesh()->getName() ) in file. If not, the behaviour is the
452 same that previous case with \b writeFromScratch parameter set to
453 \b true. If the mesh already exists, MEDLoader reads the field and
454 tries to apply field on it. This operation could be rather time
455 consuming because a read operation is performed and a reorder
456 operation too. If the file already contains the same field at the
457 same time step (iteration and order ids) the corresponding time step
458 will be replaced by the field passed in parameter.
460 \subsection MEDLoaderWriteFields Writing several time steps of a field in a MED file with MEDLoader
462 To write a serie of time steps in a "file3.med" file lying on the same
463 unstructured mesh the typical code
464 to write is the following :
466 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_3
468 In the previous code, it is important to note that the values of pair
469 (iteration,order) should be different between two calls to avoid that
470 a call to MEDLoader::WriteFieldUsingAlreadyWrittenMesh overwrites a
472 An another important thing is the fact that \c f->getMesh() does not be
474 This method of writing presents the big advantage to be fast, because
475 no check neither read is performed by this method. That's why contrary
476 to other MEDLoader::Write* method the parameter of \b writeFromScratch
482 \page MEDLoaderAdvancedAPIPage Advanced MEDLoader API.
486 This method is much closer to MED file organization than \ref
487 MEDLoaderBasicAPI "basic MEDLoader API". All MED file
488 concepts are exposed to the user. As a consequence, this advanced
489 API is lead to change with MED file data model enhancement.
491 In reading mode, the user can scan entirely and directly the content of its MED file as it is organized in its MED file.
492 Inversely, in writing mode, the user can describe its data in the same
493 way that MED file does.
495 \section AdvMEDLoaderBasics Some of basics of advanced API
497 - Like basic %MEDLoader API there is a notion of \c meshDimRelToMax.
498 Each time This parameter appears in API, it will have the semantic
500 The value of the parameter \c meshDimRelToMax is at most in {0,-1,-2,-3}. This relative value specifies a level
501 relative to value returned by ParaMEDMEM::MEDFileMesh::getMeshDimension().
503 A mesh containing MED_TETRA4, MED_TRI3, MED_QUAD4 and MED_POINT1 has a meshDimension
504 equal to 3. For \c meshDimRelToMax equal to 0 the user will
505 deal with cells whose type has a dimension equal to 3+0, that is to
506 say here MED_TETRA4. For \c meshDimRelToMax equal to -1 the user will
507 deal with cells witch dimension equal to 3-1 that is to say MED_TRI3
510 An important method is ParaMEDMEM::MEDFileUMesh::getNonEmptyLevels() method. It returns all
511 non empty levels available. In the previous example, this method will
512 return {0,-1,-3}. -2 does not appear because no cells with dimension
513 equal to 1 (3-2) appear in MED file mesh (no MED_SEG2 not MED_SEG3).
515 - Besides notion of \c meshDimRelToMax there is notion of \c meshDimRelToMaxExt.
516 \c meshDimRelToMaxExt is simply an extension of \c meshDimRelToMax for
519 The parameter of \c meshDimRelToMaxExt appears in
520 \ref ParaMEDMEM::MEDFileUMesh "umesh advanced API" of %MEDLoader with the following semantics.
522 Some of MED file concepts are available both for cells and
523 nodes, (for example families, groups, numbering ) that's why for a simpler API this
524 concept has been introduced. \c meshDimRelToMaxExt parameter can take a value in at
526 1 stands for node and 0,-1,-2,-3 has exactly the
527 same semantic than those described in \c meshDimRelToMax described
530 - A parameter that also often appears in advanced %MEDLoader API is \c renum.
531 This parameter by default in advanced %MEDLoader API is set to \c
533 This parameter indicates if the user intend to take into account
534 of the renumbering array of cells of the current MED file mesh.
535 If no renumbering array is defined, this parameter is ignored by
538 If such renumbering exists and the \c renum parameter is
539 set to \c true, then the renumbering is taken into account. This is
540 exactly the behaviour of \ref MEDLoader::ReadUMeshFromFile "basic MEDLoader API".
541 If the user expects to ignore this renumbering even in case of
542 presence of renumbering array, false should be passed to \c renum
543 parameter. \b The \b parameter \b renum \b should \b be \b set \b with
544 \b caution \b for \b users \b concerned \b by \b cells \b orders.
546 - A last important parameter is the \c mode during writing. The
547 available values for the parameter \c mode are :
548 - 2 : for a write from scratch. If file already exists, file will be
549 erased and replace by the content of the instance on which \c write
550 method has been called.
551 - 1 : If the file does not exists equivalent to 2. If file already
552 exists, the write is done on APPEND mode. That is to say that no
553 data loss will occur. But in case that an element with same ids than
554 current instance already exists, the content is not written and an
556 - 0 : If the file does not exists equivalent to 2. If file already
557 exists write without any question. If an element with same ids
558 existed previously the content is overwritten by the content of the
559 current instance, that can lead to a file corruption.
561 \section AdvMEDLoaderAPIMeshesRW Dealing with Meshes with advanced API.
563 Contrary to the basic %MEDLoader API, here after reading process, the user
564 has to deal with a new instance of class that fits the MED file model.
565 To access to a MEDCoupling mesh the user should request this class
568 \subsection AdvMEDLoaderAPIMeshReading Reading a mesh.
570 The class that incarnates Read/Write mesh in MED file is ParaMEDMEM::MEDFileUMesh.
572 First of all, like basic %MEDLoader API, only MEDfile files whose version >= 2.2 are able
573 to be read with advanced API.
575 To read a mesh having the name \c meshName in file \c fileName the
576 following simple code has to be written :
580 MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName,meshName);
584 If the user do not know the name of the mesh inside MED file
585 'fileName' the following code should be written :
589 MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName);
593 In this case the first mesh (in MED file sense) found in \c fileName
596 Now the user can ask for mesh dimension of of \c myMedMesh instance by
597 calling \c myMedMesh->getMeshDimension(). This method returns the
598 highest level of present cell in MED file mesh \c myMedMesh.
599 This returned integer is computed and \b not those contained in MED file
604 - Retrieving a mesh at a specified relative level \c meshDimRelToMax=mdrm : simply call
605 - \c myMedMesh->getMeshAtLevel(mdrm)
606 - or \c myMedMesh->getLevel0Mesh() or \c
607 myMedMesh->getLevelM1Mesh(), or \c myMedMesh->getLevelM2Mesh()
608 depending on the value of mdrm
611 - Retrieving a family at a specified level :
612 - Either an array of node/cell id
613 - \c getFamilyArr method or \c getFamiliesArr
614 - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
615 - \c getFamily method or \c getFamilies
617 - Retrieving a group at a specified level :
618 - Either an array of node/cell id
619 - \c getGroupArr method or \c getGroupsArr
620 - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
621 - \c getGroup method or \c getGroups
623 - Retrieving family field array :
624 Method \c getFamilyFieldAtLevel retrieves for a specified extended level the
625 family id of each cell or node.
627 - Retrieving renumbering array :
628 Method \c getNumberFieldAtLevel returns, if it exists for a specified extended level, the
629 family id of each cell or node. If it does not exist an exception will
632 An important point is that families and groups are \b not sorted in
633 MED file. No sort is stored in MED file explicitly for Groups and
634 Families. Advanced %MEDLoader API, uses the same order than underlying
635 mesh at specified level.
637 \subsection AdvMEDLoaderAPIMeshReadingSampl Sample of reading a mesh.
639 Here a typical use of \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" instance.
643 const char fileName[]=...;
644 const char meshName[]=...;
645 MEDFileUMesh *medmesh=MEDFileUMesh::New(fileName,meshName);
646 std::vector<int> nel=medmesh->getNonEmptyLevels();
648 throw INTERP_KERNEL::Exception("The test is not good for my file ! Expecting a multi level mesh to play with !");
649 MEDCouplingUMesh *m0=medmesh->getMeshAtLevel(nel[1],false);
650 MEDCouplingUMesh *g1=medmesh->getGroup(nel[1],"mesh2",false);
651 DataArrayInt *dag1=medmesh->getGroupArr(nel[1],"mesh2",false);
652 MEDCouplingUMesh *g1bis=m0->buildPartOfMySelf(dag1->getConstPointer(),dag1->getConstPointer()+dag1->getNbOfElems());
653 g1bis->setName(dag1->getName());
654 if(!g1->isEqual(g1bis,1e-12))
655 throw INTERP_KERNEL::Exception("hmmmm :g1 and g1bis should be equal...");
664 \subsection AdvMEDLoaderAPIMeshWriting Writing a mesh.
666 The use is very symmetric to reading part. It is possible to either
667 build a \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh" instance from
668 scratch, or to work with an existing instance coming from a loading
671 One important point is that coordinates of a mesh are shared by all
672 cells whatever their level. That's why the
673 \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" instance
674 should be shared by all \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" used in input parameter of
675 set* methods. If the user intend to build a \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh" instance from
676 scratch, a call to \c setCoords should be done first.
679 Generally speaking traduce get* methods with set* methods have corresponding write semantic.
681 Some differences still exist :
683 - \c setMeshAtLevel, \c setMeshAtLevelOld simply call \c setMeshAtLevelGen with repectively \c newOrOld parameter
684 set to true and false. These method specifies if a renumbering computation is needed or not. \c setMeshAtLevelOld is faster
685 than \c setMeshAtLevel because no renumbering computation is done. If the user is not warranty about the order of its meshes to enter
686 it is better to use \c setMeshAtLevel method.
688 - Groups definition : Groups constitution is time consuming because of the stored mode chosen by MED file to store them. Groups definition
689 lead to a partition computation which is time/mem consuming that's why groups should be defined at once and not with addGroup one by one that will lead to
690 compute a partition for each appended group. One important point to note is that DataArrayInt instance given in input to define groups should have its name
691 set to the desired group name. If not an exception will be thrown, because MED file does not support groups with no name.
693 \subsection AdvMEDLoaderAPIMeshWritingSampl Sample of writing a mesh.
697 MEDCouplingUMesh *m=...; //m is a mesh with meshDim=2 spaceDim=2
698 MEDCouplingUMesh *m1=...; //m1 is a mesh with meshDim=1 spaceDim=2 same coords than m
699 MEDCouplingUMesh *m2=...; //m2 is a mesh with meshDim=0 spaceDim=2 same coords than m
700 MEDFileUMesh *mm=MEDFileUMesh::New();
701 mm->setName("mm");//name needed to be non empty
702 mm->setDescription("Description mm");
703 mm->setCoords(m1->getCoords());
704 mm->setMeshAtLevel(-1,m1,false);
705 mm->setMeshAtLevel(0,m,false);
706 mm->setMeshAtLevel(-2,m2,false);
707 DataArrayInt *g1=DataArrayInt::New();
710 const int val1[2]={1,3};
711 std::copy(val1,val1+2,g1->getPointer());
712 DataArrayInt *g2=DataArrayInt::New();
715 const int val2[3]={1,2,3};
716 std::copy(val2,val2+3,g2->getPointer());
718 std::vector<const DataArrayInt *> grps(2);
719 grps[0]=g1; grps[1]=g2;
720 mm->setGroupsAtLevel(0,grps,false);
730 \section AdvMEDLoaderAPIFieldRW Dealing with Fields with advanced API.
732 In advanced API fields have been developed using divide and conquer pattern to reproduce with the maximal fidelity the MED file field concept \ref BasicMEDLoaderAPIGen "seen here".
734 Here the list of classes in %MEDLoader advanced API top down sorted :
736 - Level 0 : ParaMEDMEM::MEDFileFields
737 - Level -1 : ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA
738 - Level -2 : ParaMEDMEM::MEDFileField1TSWithoutSDA
739 - Level -3 : ParaMEDMEM::MEDFileFieldPerMesh (present only for backward compatibility MED file 2.2)
740 - Level -4 : ParaMEDMEM::MEDFileFieldPerMeshPerType
741 - Level -5 : ParaMEDMEM::MEDFileFieldPerMeshPerTypePerDisc
744 In each level in tree of the cyan box of field is represented by a class. The only difference is that values are grouped in a single big array located
745 in level -2 (ParaMEDMEM::MEDFileField1TSWithoutSDA) in which each leaves (level -5) of MED file field
746 point to using a range [\a start, \a end).
748 As different time steps of a same field and different field inside a MED file can shared or not profiles (yellow box) and localization (red box) a manipulable field classes instance
749 (ParaMEDMEM::MEDFileField1TS and ParaMEDMEM::MEDFileFieldMultiTS) in advanced API are the result of a subclass of a data class
750 (respectively ParaMEDMEM::MEDFileField1TSWithoutSDA, ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA) and a instance of ParaMEDMEM::MEDFileFieldGlobsReal representing the shared data arrays (SDA)
751 at a specified scope inside the MED file.
753 \subsection AdvMEDLoaderAPIFieldR Reading a field
755 \subsubsection AdvMEDLoaderAPIFieldRC Reading a field defined on all entity
757 Fields defined on all entity are the most used and common fields in MED file world.
759 In this mode the user do **not** want to retrieve the entity ids of the constituting subsupport of the whole mesh because it has no sense.
761 Let's read a field on all entity called \a fieldName lying on a mesh called \a meshName in a MED file called \a fname at a iteration defined on time step defined
762 by \a iteration and \a order.
764 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldOnAllEntity1_1
766 To read it there are 3 main approaches :
768 - Use ParaMEDMEM::MEDFileField1TS class :
770 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldOnAllEntity1_3
772 - Use ParaMEDMEM::MEDFileFieldMultiTS class :
774 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldOnAllEntity1_4
776 - Use iteration ParaMEDMEM::MEDFileFieldMultiTS class :
778 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldOnAllEntity1_5
780 \subsubsection AdvMEDLoaderAPIFieldRP Reading a partial field
782 Let's read a partial field called \a fieldName lying on a mesh called \a meshName in a MED file called \a fname at a iteration defined on time step defined
783 by \a iteration and \a order.
785 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldPartial1_1
787 Fields defined partially on a meshes can been read using 2 main approaches :
789 - Either the user wants to retrieve it's field in %MEDCoupling sense, that is to say for interpolation, to evaluate such field on different points...
790 \n In this mode the link with the whole mesh is not useful for the user
792 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldPartial1_3
794 - Or the user wants to retrieve the binding (cell ids or node ids) with the whole mesh on which the partial field lies partially on.
796 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldPartial1_4
798 \ref medcoupling "MEDCoupling" allows to make bridges between the approaches. For example \a pfl \ref ParaMEDMEM::DataArrayInt "DataArrayInt instance" retrieved directly
799 from the file in the second approach can be retrieved starting from first approach.
801 Starting from mesh \a firstApproachMesh of read field in first approach \a fread, whith the whole mesh \a wholeMesh the profile \a pflComputed can be computed :
803 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldPartial1_5
805 Inversely, it is possible to rebuild field obtained in first approach starting from second approach :
807 \snippet MEDLoaderExamplesTest.py PySnippetReadFieldPartial1_6
809 \subsection AdvMEDLoaderAPIFieldW Writing a field
811 \subsubsection AdvMEDLoaderAPIFieldWC Writing a field defined on all entity
813 Fields defined on all entity are the most used and common fields in MED file world.
815 In this mode the user do **not** want to retrieve the entity ids of the constituting subsupport of the whole mesh because it has no sense.
817 Let's write a cell field on all entity called \a fieldName lying on a mesh called \a meshName in a MED file called \a fname at a iteration defined on time step defined
818 by \a iteration and \a order.
820 \snippet MEDLoaderExamplesTest.py PySnippetWriteFieldOnAllEntity1_2
822 We can see here that the necessity to deal with both mesh and field to write a field is exposed by the API. The mesh write mode is 2 to tell to MED file that is file already exists to scratch it.
823 The mode of write is 0 to simply add to the file the field specific part.
825 \subsubsection AdvMEDLoaderAPIFieldWP Writing a partial field
827 \snippet MEDLoaderExamplesTest.py PySnippetWriteFieldPartial1_2
829 To write a partial field \a f can have a **null mesh**, because the link with mesh is made given the entry of \a mm MEDFileField1TS::setFieldProfile method.