doc/user/doxygen/doxfiles/reference/medloader/MEDLoaderAdvancedAPI.dox

   1
   2 /*!
   3 \page MEDLoaderAdvancedAPIPage Advanced MEDLoader API
   4
   5 [TOC]
   6
   7 This method is much closer to MED file organization than the \ref
   8 MEDLoaderBasicAPIPage "basic MEDLoader API". All MED file
   9 concepts are exposed to the user. As a consequence, this advanced
  10 API is meant to evolve with MED file data model enhancement.
  11
  12 In reading mode, the user can scan entirely and directly the contents of
  13 its MED file directly as it is organized on the disk.
  14 Inversely, in writing mode, the user can describe its data in the same
  15 way that MED file does on the disk.
  16
  17 When looking for a specific point in the API, the diagram provided at the
  18 end of this section might help:
  19
  20 \section AdvMEDLoaderBasics Some of basics of advanced API
  21
  22 - Like basic %MEDLoader API there is a notion of \c meshDimRelToMax.
  23 Each time this parameter appears in API, it will have the semantic
  24 explained here.
  25 The value of the parameter \c meshDimRelToMax is at most in {0,-1,-2,-3}. This relative value specifies a level
  26 relative to the value returned by ParaMEDMEM::MEDFileMesh::getMeshDimension().
  27
  28 A mesh containing MED_TETRA4, MED_TRI3, MED_QUAD4 and MED_POINT1 has a meshDimension
  29 equal to 3. For \c meshDimRelToMax equal to 0 the user will
  30 deal with cells whose type has a dimension equal to 3+0, that is to
  31 say here MED_TETRA4. For \c meshDimRelToMax equal to -1 the user will
  32 deal with cells which dimension equals 3-1 that is to say MED_TRI3
  33 and MED_QUAD4.
  34
  35 An important method is ParaMEDMEM::MEDFileUMesh::getNonEmptyLevels(). It returns all
  36 non empty levels available. In the previous example, this method will
  37 return {0,-1,-3}. -2 does not appear because no cells with dimension
  38 equal to 1 (3-2) appear in MED file mesh (no MED_SEG2, no MED_SEG3).
  39
  40 - Besides notion of \c meshDimRelToMax there is notion of \c meshDimRelToMaxExt.
  41 \c meshDimRelToMaxExt is simply an extension of \c meshDimRelToMax for
  42 nodes.
  43
  44 The parameter of \c meshDimRelToMaxExt appears in
  45 \ref ParaMEDMEM::MEDFileUMesh "umesh advanced API" of %MEDLoader with the following semantics.
  46
  47 Some of MED file concepts are available both for cells and
  48 nodes (for example families, groups, numbering) ; that's why for a simpler API this
  49 concept has been introduced. \c meshDimRelToMaxExt parameter can take a value in at
  50 most {1,0,-1,-2,-3}.
  51 1 stands for node and 0,-1,-2,-3 has exactly the
  52 same semantic than those described in \c meshDimRelToMax
  53 before.
  54
  55 - A parameter that also often appears in advanced %MEDLoader API is \c renum.
  56 This parameter is set to \c
  57 true by default.
  58 This parameter indicates if the user intends to take into account
  59 the renumbering array of cells of the current MED file mesh.
  60 If no renumbering array is defined, this parameter is ignored by
  61 %MEDLoader.
  62
  63 If such renumbering exists and the \c renum parameter is
  64 set to \c true, then the renumbering is taken into account. This is
  65 exactly the behaviour of \ref MEDLoader::ReadUMeshFromFile "basic MEDLoader API".
  66 If the user expects to ignore this renumbering even in case of
  67 presence of renumbering array, false should be passed to \c renum
  68 parameter. \b The \b parameter \b renum \b should \b be \b set \b with
  69 \b caution \b for \b users \b concerned \b by \b cells \b orders.
  70
  71 - A last important parameter is the \c mode during writing. The
  72   available values for the parameter \c mode are :
  73   - 2 : for a write from scratch. If file already exists, file will be
  74   erased and replace by the content of the instance on which \c write
  75   method has been called.
  76   - 1 : If the file does not exists equivalent to 2. If file already
  77   exists, the write is done on APPEND mode. That is to say that no
  78   data loss will occur. But in case that an element with same ids than
  79   current instance already exists, the content is not written and an
  80   exception is thrown.
  81   - 0 : If the file does not exists equivalent to 2. If file already
  82   exists write without any question. If an element with same ids
  83   existed previously the content is overwritten by the content of the
  84   current instance, that can lead to a file corruption.
  85
  86 \section AdvMEDLoaderAPIMeshesRW Dealing with Meshes with advanced API.
  87
  88 Contrary to the basic %MEDLoader API, here after reading process, the user
  89 has to deal with a new instance of class that fits the MED file model.
  90 To access a MEDCoupling mesh user should request this class
  91 instance.
  92
  93 \subsection AdvMEDLoaderAPIMeshReading Reading a mesh.
  94
  95 The class that incarnates Read/Write mesh in MED file is ParaMEDMEM::MEDFileUMesh.
  96
  97 First of all, like basic %MEDLoader API, only MEDfile files whose version >= 2.2 are able
  98 to be read with advanced API.
  99
 100 To read a mesh having the name \c meshName in file \c fileName the
 101 following simple code has to be written :
 102
 103 \code
 104
 105 MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName,meshName);
 106
 107 \endcode
 108
 109 If the user do not know the name of the mesh inside MED file
 110 'fileName' the following code should be written :
 111
 112 \code
 113
 114 MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName);
 115
 116 \endcode
 117
 118 In this case the first mesh (in MED file sense) found in \c fileName
 119 file will be loaded.
 120
 121 Now the user can ask for mesh dimension of of \c myMedMesh instance by
 122 calling \c myMedMesh->getMeshDimension(). This method returns the
 123 highest level of present cell in MED file mesh \c myMedMesh.
 124 This returned integer is computed and \b not those contained in MED file
 125 that can be invalid.
 126
 127 \n
 128
 129 - Retrieving a mesh at a specified relative level \c meshDimRelToMax=mdrm : simply call
 130   - \c myMedMesh->getMeshAtLevel(mdrm)
 131   - or \c myMedMesh->getLevel0Mesh() or \c
 132   myMedMesh->getLevelM1Mesh(), or \c myMedMesh->getLevelM2Mesh()
 133   depending on the value of mdrm
 134
 135
 136 - Retrieving a family at a specified level :
 137   - Either an array of node/cell id
 138     - \c getFamilyArr method or \c getFamiliesArr
 139   - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
 140     - \c getFamily method or \c getFamilies
 141
 142 - Retrieving a group at a specified level :
 143   - Either an array of node/cell id
 144     - \c getGroupArr method or \c getGroupsArr
 145   - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
 146     - \c getGroup method or \c getGroups
 147
 148 - Retrieving family field array :
 149 Method \c getFamilyFieldAtLevel retrieves for a specified extended level the
 150 family id of each cell or node.
 151
 152 - Retrieving renumbering array :
 153 Method \c getNumberFieldAtLevel returns, if it exists for a specified extended level, the
 154 family id of each cell or node. If it does not exist an exception will
 155 be thrown.
 156
 157 An important point is that families and groups are \b not sorted in
 158 MED file. No sort is stored in MED file explicitly for Groups and
 159 Families. Advanced %MEDLoader API, uses the same order than underlying
 160 mesh at specified level.
 161
 162 \anchor AdvMEDLoaderAPIMeshReadingSampl
 163
 164 \if ENABLE_EXAMPLES
 165 Here is a \ref cpp_mcumesh_loadfile "C++ example" illustrating a typical use of \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" instance.
 166 \endif
 167
 168 \subsection AdvMEDLoaderAPIMeshWriting Writing a mesh.
 169
 170 The use is very symmetric to reading part. It is possible to either
 171 build a \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh" instance from
 172 scratch, or to work with an existing instance coming from a loading
 173 from a file.
 174
 175 One important point is that coordinates of a mesh are shared by all
 176 cells whatever their level. That's why the
 177 \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" instance
 178 should be shared by all \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" used in input parameter of
 179 set* methods. If the user intends to build a \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh" instance from
 180 scratch, a call to \c setCoords should be done first.
 181
 182
 183 Generally speaking traduce get* methods with set* methods have corresponding write semantic.
 184
 185 Some differences still exist :
 186
 187 - \c setMeshAtLevel, \c setMeshAtLevelOld simply call \c setMeshAtLevelGen with repectively \c newOrOld parameter
 188 set to true and false. These methods specify if a renumbering computation is needed or not. \c setMeshAtLevelOld is faster
 189 than \c setMeshAtLevel because no renumbering computation is done. If the user is not warranty about the order of its meshes to enter
 190 it is better to use \c setMeshAtLevel method.
 191
 192 - Groups definition : Groups constitution is time consuming because of the store mode chosen by MED file. Groups definition
 193 leads to a partition computation which is time/memory consuming ; that is why groups should be defined at once and not with addGroup one by one that will lead to
 194 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
 195 set to the desired group name. If not an exception will be thrown, because MED file does not support groups with no name.
 196
 197 \anchor AdvMEDLoaderAPIMeshWritingSampl
 198
 199 \if ENABLE_EXAMPLES
 200 Here is a \ref cpp_mcumesh_writefile "C++ example".
 201 \endif
 202
 203 \section AdvMEDLoaderAPIFieldRW Dealing with Fields with advanced API.
 204
 205 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".
 206
 207 Here the list of classes in %MEDLoader advanced API top down sorted :
 208
 209 - Level 0 : ParaMEDMEM::MEDFileFields
 210 - Level -1 : ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA
 211 - Level -2 : ParaMEDMEM::MEDFileField1TSWithoutSDA
 212 - Level -3 : ParaMEDMEM::MEDFileFieldPerMesh (present only for backward compatibility MED file 2.2)
 213 - Level -4 : ParaMEDMEM::MEDFileFieldPerMeshPerType
 214 - Level -5 : ParaMEDMEM::MEDFileFieldPerMeshPerTypePerDisc
 215
 216
 217 Each level in the tree representing a field (cyan box) is represented by a class. The only difference is that values are grouped in a single big array located
 218 in level -2 (ParaMEDMEM::MEDFileField1TSWithoutSDA)  in which each leaf (level -5) of MED file field
 219 points to range [\a start, \a end).
 220
 221 As different time steps of a same field and different fields inside a MED file can share or not profiles (yellow box) and localization (red box) a manipulable field classes instance
 222 (ParaMEDMEM::MEDFileField1TS and ParaMEDMEM::MEDFileFieldMultiTS) in advanced API is the result of a subclass of a data class
 223 (respectively ParaMEDMEM::MEDFileField1TSWithoutSDA, ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA) and an instance of ParaMEDMEM::MEDFileFieldGlobsReal representing the shared data arrays (SDA)
 224 at a specified scope inside the MED file.
 225
 226 \subsection AdvMEDLoaderAPIFieldR Reading a field
 227
 228 \subsubsection AdvMEDLoaderAPIFieldRC Reading a field defined on all entities
 229
 230 Fields defined on all entities are the most used and common fields in MED file world.
 231
 232 In this mode the user does **not** want to retrieve the entity ids of the constituting subsupport of the whole mesh because it has no sense.
 233
 234 \if ENABLE_EXAMPLES
 235 Here is a \ref py_mcfield_loadfile_allentities "Python example".
 236 \endif
 237
 238 \subsubsection AdvMEDLoaderAPIFieldRP Reading a partial field
 239
 240 \if ENABLE_EXAMPLES
 241 Here is a \ref py_mcfield_loadfile_partial "Python example".
 242 \endif
 243
 244 \subsection AdvMEDLoaderAPIFieldW Writing a field
 245
 246 \subsubsection AdvMEDLoaderAPIFieldWC Writing a field defined on all entities
 247
 248 Fields defined on all entities are the most used and common fields in MED file world.
 249
 250 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.
 251
 252 \if ENABLE_EXAMPLES
 253 Here is a \ref py_mcfield_writefile_allentities "Python example".
 254 \endif
 255
 256 \subsubsection AdvMEDLoaderAPIFieldWP Writing a partial field
 257
 258 \if ENABLE_EXAMPLES
 259 Here is a \ref py_mcfield_writefile_partial "Python example".
 260 \endif
 261
 262 \section AdvMEDLoaderDiagram Simplified class diagram of the advanced API
 263
 264 \image html med-loader-adv-classes.png "Class diagram of the advanced MEDLoader API"
 265
 266 The blue rectangles show the links to the MEDCoupling objects. Note that in MEDCoupling there is no
 267 representation of a field of integer. Those are extracted directly as \ref ParaMEDMEM::DataArrayInt "DataArrayInt".
 268
 269 The classes shown on this diagram (all part of the \ref cpp "unfortunately named ParaMEDMEM namespace"):
 270 - \ref ParaMEDMEM::MEDFileData "MEDFileData", the encapsulation of a complete MED file
 271
 272 and also:
 273 - \ref ParaMEDMEM::MEDFileMeshes "MEDFileMeshes", the set of meshes in the file
 274 - \ref ParaMEDMEM::MEDFileMeshMultiTS "MEDFileMeshMultiTS", a single mesh with muliple time steps
 275 - \ref ParaMEDMEM::MEDFileMesh "MEDFileMesh", a single mesh on a single timestep
 276 - \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh", a single unstructured mesh
 277
 278 and also:
 279 - \ref ParaMEDMEM::MEDFileFields "MEDFileFields", the set of fields in a MED file
 280 - \ref ParaMEDMEM::MEDFileAnyTypeFieldMultiTS "MEDFileAnyTypeFieldMultiTS", a single field with multiple
 281 time steps (can be an integer field or a double field)
 282 - \ref ParaMEDMEM::MEDFileFieldMultiTS "MEDFileFieldMultiTS", a single field of doubles with multiple time steps
 283 - \ref ParaMEDMEM::MEDFileIntFieldMultiTS "MEDFileIntFieldMultiTS", a single field of int with multiple time steps
 284 - \ref ParaMEDMEM::MEDFileFieldMultiTS "MEDFileAnyTypeField1TS", a single field with a single time step
 285 (integer or double)
 286 - \ref ParaMEDMEM::MEDFileField1TS "MEDFileField1TS", a single field of doubles with a single time step
 287 - \ref ParaMEDMEM::MEDFileIntField1TS "MEDFileIntField1TS", a single field of ints with a single time step
 288
 289 and finally:
 290 - \ref ParaMEDMEM::MEDFileParameters "MEDFileParameters", numerical parameters stored in a MED file
 291
 292
 293
 294 */