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