doc/user/doxygen/doxfiles/reference/medloader/intro-medloader.dox

   1 /*!
   2 \page intro-medloader Overview
   3
   4 [TOC]
   5
   6 \section MEDLoaderIntro Introduction
   7
   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 "MEDCoupling data structure". The fact that these
  10 functionalities are not merged in the \ref library "MEDCoupling library" is explained by a
  11 willingness of reducing as much as possible the dependencies of this library.
  12
  13 As a MED file can combine several \ref medcoupling "MEDCoupling" aspects in one (for example meshes in
  14 MED file on more than one dimensions with families and groups) the API
  15 of \ref medloader "MEDLoader" is much more rich than simply read and write.
  16
  17 \ref meshes "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.
  19
  20 \section MEDLoader2Approaches Two approaches
  21
  22 \ref medloader "MEDLoader" module offers two different approaches to perform Read/Write from/to MED file.
  23
  24 - \ref MEDLoaderBasicApproach "basic API approach"
  25 - \ref MEDLoaderAdvApproach "advanced API approach"
  26
  27 Whatever the approach(es) you choose, it is advisable to know main concepts of MED files \ref MEDLoaderMainC "that are quickly reminded here."
  28
  29 \subsection MEDLoaderBasicApproach Basic API approach
  30
  31 \ref MEDLoaderBasicAPIPage "A specific page dedicated to the basic API is available here".
  32
  33 This approach is less close to MED file concepts, but closer to \ref medcoupling "MEDCoupling concepts".
  34
  35 So, basic API is simpler, as shown by method MEDLoader::WriteUMesh that needs no special knowledge about MED file concepts to interact with MED files.
  36
  37 This API is in the form of a list of public static methods in a class MEDCoupling::MEDLoader.
  38
  39 This simplicity has a cost, the I/O are not (cannot be) optimized.
  40
  41 As MED file concepts are more complex than MEDCoupling concepts, this approach is not the most relevant for specific MED file objects read/write.
  42
  43 - Manipulation of multi level MED file mesh is not easy with basic approach
  44
  45 - Manipulation of partial fields is not easy with basic approach
  46
  47 \subsection MEDLoaderAdvApproach Advanced API approach
  48
  49 \ref MEDLoaderAdvancedAPIPage "A specific page dedicated to the advanced API is available here".
  50
  51 This approach is the closest to MED file. By using this advanced API approach the user will manipulate classes that represent MED file concepts.
  52
  53 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 :
  54
  55 - group/family in meshes
  56 - profiles in fields
  57
  58 This is typically the case for a user that wants to precisely set/get mesh/group/family groups set on different level.
  59
  60 *This is why a set of classes corresponding to memory representation of MED file concepts is proposed by advanced API approach.*
  61
  62 *So All information contained in file is represented by advanced API class instances.*
  63
  64 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.
  65
  66 This API is particularly recommended :
  67
  68 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)
  69 2. For users that want to operate directly on complex MED file objects (split of MED files for example, duplication of nodes).
  70
  71
  72 \subsection MEDLoaderCohabitationApproach Cohabitation of the two approaches
  73
  74 The two approaches are \b NOT opposed, they are compatible each other so it is possible to mix them.
  75
  76 Typically it is possible to read rich information of a complex MED file using advanced API in read mode, postprocess this input then get a simpler MED file model, and write it to a simple output MED file using basic API.
  77
  78 \section MEDLoaderMainC Main concepts of MED files
  79
  80 Here we will describe some of the basic concepts of MED files in order to
  81 use the best methods proposed by \ref medloader "MEDLoader API".
  82
  83 \subsection BasicMEDLoaderAPIGen Basics in MED files
  84
  85 First of all **MEDLoader will not read MED files whose version is strictly lower than 2.2.**
  86
  87 For new comers in MED file world some of basics principles are recalled in the following graphic :
  88
  89 \image html MEDFileConcepts.png "Resumed MED file concepts"
  90
  91 Inside the parenthesis, there is multiplicity :
  92
  93 - + stands for [1,inf)
  94 - * stands for [0,inf)
  95 - ? stands for 0 or 1
  96
  97 Each box is **independent in MED file format during read/write session.**
  98
  99 **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.
 100
 101 There can be as many instance of boxes as wanted in a MED file.
 102
 103 **As it can be seen in MED file world, fields and meshes are sorted by geometric type**.
 104
 105 This specificity leads to a constraint during writing phase because some mesh operations may significantly modify the organization of geometric types during mesh/field operations.
 106 \n Here are some of operations that can alter the geometric type order of cells:
 107
 108 - aggregation of meshes
 109 - aggregation of fields
 110 - extraction of a part of meshes
 111 - extraction of a part of fields
 112 - partial polyhedrization of meshes
 113 - unpolyhedronization of meshes
 114
 115 \section MEDLoaderCommonVoc Vocabulary used in MEDLoader
 116
 117 \subsection MEDLoaderCommonVocRelMeshDimMesh Relative mesh dimension in meshes
 118
 119 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.
 120
 121 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.
 122
 123 To connect the MED file world to the MEDLoader/MEDCoupling world the notion of **relative mesh dimension** has been introduced in \ref medloader "MEDLoader".
 124
 125 This concept of **relative mesh dimension** is used frequently in the \ref medloader "MEDLoader APIs" (\ref MEDLoaderBasicAPIPage "basic" and \ref MEDLoaderAdvancedAPIPage "advanced").
 126
 127 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.
 128
 129 For each geometric type on which \a myMesh is defined the mesh dimensions are :
 130
 131 - MED_TRI3 -> mesh dimension=2
 132 - MED_POINT1 -> mesh dimension=0
 133 - MED_POLYHED -> mesh dimension=3
 134 - MED_TETRA4 -> mesh dimension=3
 135
 136 The mesh dimension of \a myMesh is equal to 3 ( \c max(2,0,3,3) ). The **relative mesh dimension** is equal to the difference between mesh dimension of geometric type and the mesh dimension
 137 of the whole MED file dimension. It leads to the following **relative mesh dimension** :
 138
 139 - MED_TRI3 -> **relative mesh dimension** = -1
 140 - MED_POINT1 -> **relative mesh dimension** = -3
 141 - MED_POLYHED -> **relative mesh dimension** = 0
 142 - MED_TETRA4 -> **relative mesh dimension** = 0
 143
 144 In \ref medloader "MEDLoader" all geometric information are then grouped relative dimension per relative dimension. It leads to the following geometric sorting of
 145 MED file data structure of \a myMesh :
 146
 147 - Level 0
 148   - MED_TETRA4
 149   - MED_POLYHED
 150 - Level -1
 151   - MED_TRI3
 152 - Level -2
 153   - nothing -> level **not** available for \a myMesh
 154 - Level -3
 155   - MED_POINT1
 156
 157 The mesh dimension of \a myMesh is 3. The relative mesh dimensions available are 0, -1 and -3.
 158
 159 \subsection MEDLoaderCommonVocRelMeshDimField Relative mesh dimension in fields
 160
 161 As it has been seen previously in \ref MEDLoaderCommonVocRelMeshDimMesh "for meshes", the values of fields are sorted by levels too.
 162
 163 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.
 164
 165 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.
 166
 167 \subsection MEDLoaderCommonVocIterationOrder Iteration and order in MED file
 168
 169 As seen \ref BasicMEDLoaderAPIGen "above", fields in MED file can be defined on different time steps.
 170
 171 But there is a **major difference** with \ref medcoupling "MEDCoupling" concept in time steps. \ref medcoupling "MEDCoupling" focuses on the float value of time for interpolation reason.
 172
 173 \ref medloader MEDLoader and MED file focus on pair of integers to precise a specific time steps.
 174
 175 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.
 176
 177 In MED file and so in \ref medloader "MEDLoader" the time steps are identified by a pair of integers called :
 178
 179 - iteration
 180 - order
 181
 182 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.
 183
 184 */