1 Data movement (mesh/field construction)
2 =======================================
7 To read a mesh from a MED file simply invoke
9 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
10 :start-after: UG_ReadMeshFromFile_1
11 :end-before: UG_ReadMeshFromFile_1
13 If the file contains more than one mesh, the previous call will
16 You can access to a precise mesh by doing
18 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
19 :start-after: UG_ReadMeshFromFile_2
20 :end-before: UG_ReadMeshFromFile_2
25 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
26 :start-after: UG_ReadField_1
27 :end-before: UG_ReadField_1
29 This command will succeed if there is exactly one field in
30 "file.med" and only one time step attached to it.
32 If there are more than one field in "file.med" you are expected to
33 specify the field name.
35 To know all fields in "file.med" either you read exception thrown or you can invoke
37 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
38 :start-after: UG_ReadField_2
39 :end-before: UG_ReadField_2
41 When you have the fieldName you can safely invoke.
43 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
44 :start-after: UG_ReadField_3
45 :end-before: UG_ReadField_3
47 This command will succeed if there are exactly one time step
48 attached on it. If no you are expected to specify the time step
51 A time step is identified by two piece of information :
53 - pair of integers specifying without ambiguity a key for access
54 - floating point (physical time step)
56 To retrieve list of time step of a field invoke
58 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
59 :start-after: UG_ReadField_4
60 :end-before: UG_ReadField_4
62 This method returns a list of triplet. The first 2 elements of
63 triplets is pair of integers of time step and the last element in
64 the triplet is the physical time step.
66 To read a field "Field1" at time step defined by pair "(ts0,ts1)"
69 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
70 :start-after: UG_ReadField_5
71 :end-before: UG_ReadField_5
73 If you do not succeed reading field in "file.med" using this method
74 it means that your MED file is complex and requires more information
75 to be extracted. :ref:`Go to advanced reading<medcoupling_AdvancedReading>`.
77 .. admonition:: Remark
79 the method is concise but by calling this method several
80 times it leads to a several mesh loads.
83 .. _medcoupling_Write_mesh:
88 MED file format expects a mesh sorted by geometric type. You are
89 responsible to reorder, if needed, cells to match MED file format
92 This responsability is let to the end user to avoid misrenumbering effect.
94 You can check this by invoking:
96 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
97 :start-after: UG_ReadMeshFromFile_3
98 :end-before: UG_ReadMeshFromFile_3
100 To reorder cells you are encouraged to read :ref:`this <renumber_for_MED>`.
102 If *m* is well numbered, you can dump it into a file by doing :
104 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
105 :start-after: UG_ReadMeshFromFile_0
106 :end-before: UG_ReadMeshFromFile_0
108 The last element specifies the behavior in case if "file2.med" would
109 already exist. True means, scratch it and write it from scratch.
110 False means do not scratch try to append it.
113 Write field into file
114 ---------------------
116 You are expected to have a field *f* with a mesh :ref:`correctly numbered.<medcoupling_Write_mesh>`
118 If *f* is a valid MEDCouplingFieldDouble you can dump it into a MED file by simply :
120 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
121 :start-after: UG_ReadField_0
122 :end-before: UG_ReadField_0
124 The last element specifies the behavior in case if "file.med" would
125 already exist. The same meaning than for :ref:`writing mesh.<medcoupling_Write_mesh>`
127 The typical usecase is to store a multi time step field.
129 To do that, let's consider that *fs* store a list of
130 MEDCouplingFieldDouble with at least one element in it.
132 .. WARNING:: All meshes of elements in *fs* are expected to be the same
134 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
135 :start-after: UG_ReadField_6
136 :end-before: UG_ReadField_6
138 .. admonition:: Remark
140 f.getTime()[1:3] returns the pair of integer that specifies the time step.
142 f.getTime()[1:3] should be different each other. If two
143 elements in *fs* have the same pair of integer time step key, the
144 second one will take the place of the first !
146 Create an array from scratch
147 ----------------------------
149 There are several simple ways to create a medcoupling array from a Python list.
151 The following call creates an array of double values consisting of 3 tuples with 2 components:
153 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
154 :start-after: UG_DataArrayDouble_0
155 :end-before: UG_DataArrayDouble_0
157 The next call creates an array equivalent to one create above:
159 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
160 :start-after: UG_DataArrayDouble_1
161 :end-before: UG_DataArrayDouble_1
163 The call below creates an array holding the same but differently arranged values: 2 tuples with 3 components:
165 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
166 :start-after: UG_DataArrayDouble_2
167 :end-before: UG_DataArrayDouble_2
169 You can change number of components in *d* so that it holds 3 tuples with 2 components again:
171 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
172 :start-after: UG_DataArrayDouble_3
173 :end-before: UG_DataArrayDouble_3
175 Arrays of different types (DataArrayInt, DataArrayFloat) can be created in the same way as DataArrayDouble:
177 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
178 :start-after: UG_DataArrayDouble_4
179 :end-before: UG_DataArrayDouble_4
181 A medcoupling array can be created from a numpy array and can be transformed to a numpy array:
183 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest_numpy.py
184 :start-after: UG_DataArrayNumpy_0
185 :end-before: UG_DataArrayNumpy_0
189 Create an unstructured mesh from scratch
190 ----------------------------------------
195 MEDCouplingUMesh class represents a general case unstructured mesh. Data of MEDCouplingUMesh is defined in several steps.
197 Firstly define basic mesh data in full interlace mode for coordinates and nodal connectivity cell per cell.
199 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
200 :start-after: PySnippetUMeshStdBuild1_1
201 :end-before: PySnippetUMeshStdBuild1_1
203 Then create MEDCouplingUMesh instance giving its mesh dimension (2 here) and a name.
205 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
206 :start-after: PySnippetUMeshStdBuild1_2
207 :end-before: PySnippetUMeshStdBuild1_2
209 Then add cells to the mesh. This step includes
211 - giving an upper bound of the number of cells to be inserted into the unstructured mesh.
212 - entering nodal connectivity of all cells, cell per cell using MEDCouplingUMesh.insertNextCell method.
213 - compacting connectivity arrays by calling MEDCouplingUMesh.finishInsertingCells method.
215 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
216 :start-after: PySnippetUMeshStdBuild1_3
217 :end-before: PySnippetUMeshStdBuild1_3
219 As the connectivity of the mesh has been defined, let's set the coordinates using array *coords* defined above.
221 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
222 :start-after: PySnippetUMeshStdBuild1_4
223 :end-before: PySnippetUMeshStdBuild1_4
225 Now the mesh is usable. To assure this, call
227 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
228 :start-after: PySnippetUMeshStdBuild1_5
229 :end-before: PySnippetUMeshStdBuild1_5
234 MEDCoupling1SGTUMesh class represents an unstructured mesh composed of cells of same geometric type. It is more optimal due to this simplicity.
236 Basically a MEDCoupling1SGTUMesh is defined in the same way as MEDCouplingUMesh. A difference is that the geometric type of cells is specified at construction, and not specified later e.g. in insertNextCell method:
238 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
239 :start-after: GU_MEDCoupling1SGTUMesh_0
240 :end-before: GU_MEDCoupling1SGTUMesh_0
245 MEDCoupling1DGTUMesh also represents an unstructured mesh composed of cells of same geometric type but it is specialized for cell of "dynamic" geometric type only: NORM_POLYHED and NORM_POLYG.
247 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
248 :start-after: GU_MEDCoupling1SGTUMesh_1
249 :end-before: GU_MEDCoupling1SGTUMesh_1
251 When connectivity of a polyhedron is defined, facets are separated one from another by -1.
253 Create a cartesian mesh from scratch
254 ------------------------------------
256 We are going to build a 2D cartesian mesh, constituted from 9 nodes along X axis, and 7 nodes along Y axis.
258 Firstly define for each direction the discretization and build a DataArrayDouble on the corresponding direction.
260 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
261 :start-after: PySnippetCMeshStdBuild1_1
262 :end-before: PySnippetCMeshStdBuild1_1
264 Then create MEDCoupling.MEDCouplingCMesh instance giving the 2 instances of DataArrayDouble defined above.
266 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
267 :start-after: PySnippetCMeshStdBuild1_2
268 :end-before: PySnippetCMeshStdBuild1_2
270 The mesh is now usable.
272 .. figure:: ../images/cartesian.png
275 A cartesian mesh created by the code above
277 Create a curvelinear mesh from scratch
278 --------------------------------------
280 First we create a curvelinear mesh and define its structure, for instance a 2-dimensional mesh with 2 nodes in one direction and 3 nodes in the other direction:
282 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
283 :start-after: UG_MEDCouplingCurveLinearMesh_0
284 :end-before: UG_MEDCouplingCurveLinearMesh_0
286 Then define coordinates of 6 nodes in 2D space:
288 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
289 :start-after: UG_MEDCouplingCurveLinearMesh_1
290 :end-before: UG_MEDCouplingCurveLinearMesh_1
292 The mesh is now usable. It's a good habit to assure this:
294 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
295 :start-after: UG_MEDCouplingCurveLinearMesh_2
296 :end-before: UG_MEDCouplingCurveLinearMesh_2
298 .. figure:: ../images/curvelinear.png
301 A curvelinear mesh created by the code above
303 .. _MEDCouplingFieldDoubleOnCells:
305 Create a field on cell from scratch
306 -----------------------------------
308 Assume we already have a mesh. We create a field on all cells of the mesh.
310 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
311 :start-after: UG_MEDCouplingFieldDouble_0
312 :end-before: UG_MEDCouplingFieldDouble_0
314 ONE_TIME indicates that the field data relates to a single time step. Now define this time moment.
316 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
317 :start-after: UG_MEDCouplingFieldDouble_1
318 :end-before: UG_MEDCouplingFieldDouble_1
320 Then define field values:
322 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
323 :start-after: UG_MEDCouplingFieldDouble_2
324 :end-before: UG_MEDCouplingFieldDouble_2
327 Create a field on node from scratch
328 -----------------------------------
330 Assume we already have a mesh. We create a field on all nodes of the mesh. The procedure is same as for a :ref:`field on cells <MEDCouplingFieldDoubleOnCells>` except two points:
332 - Spatial discretization in the field constructor is ON_NODES
333 - Number of tuples in an array of values is equal to mesh.getNumberOfNodes()
335 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
336 :start-after: UG_MEDCouplingFieldDouble_3
337 :end-before: UG_MEDCouplingFieldDouble_3
340 Create a field on Gauss points from scratch
341 -------------------------------------------
343 Assume we already have a 2D mesh consisting of triangle and quadrangle cells. We create a field on Gauss points. First, a field is constructed with use of ON_GAUSS_PT and its basic attributes are set:
345 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
346 :start-after: UG_MEDCouplingGaussPointField_0
347 :end-before: UG_MEDCouplingGaussPointField_0
349 Now define localization of Gauss points on cells. In this example, we define two Gauss points on triangle cells and four Gauss points on quadrangle cells. Localization of Gauss points is defined by three lists of float values:
351 #. Coordinates of nodes of the reference cell.
352 #. Coordinates of Gauss points on the reference cell.
353 #. Weights of Gauss points.
355 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
356 :start-after: UG_MEDCouplingGaussPointField_1
357 :end-before: UG_MEDCouplingGaussPointField_1
359 Finally set field values:
361 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
362 :start-after: UG_MEDCouplingGaussPointField_2
363 :end-before: UG_MEDCouplingGaussPointField_2
368 applyFunc method modifies all tuples of a field at once. It changes both values and number of components, only number of tuples remains the same.
370 To set value *val* to all tuples of the field *f* and to make it have *nbComp* components, call:
372 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
373 :start-after: UG_MEDCouplingFieldDouble_5
374 :end-before: UG_MEDCouplingFieldDouble_5
376 It is also possible to compute new values basing on current values. To do so you can specify a function by which a new value will be computed. For more info on supported expressions that can be used in the function, see `expressions supported`_.
378 .. _`expressions supported`: ../../developer/arrays.html#MEDCouplingArrayApplyFuncExpr
380 You can use some letters, for example "x", "y", "z" etc., to refer to current component values. For example, to transform a 3D vector field to its magnitude, call:
382 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
383 :start-after: UG_MEDCouplingFieldDouble_6
384 :end-before: UG_MEDCouplingFieldDouble_6
386 This way a value resulting from the function evaluation is assigned to all components.
388 But you can have its own expression for each component within one function. For this purpose, there are predefined variable names (IVec, JVec, KVec, LVec etc) each dedicated to a certain component (IVec, to the component #0 etc). A factor of such a variable is added to the corresponding component only.
390 Using this feature, you can set a magnitude of a 3D vector as the fourth component and swap X and Y components by calling:
392 .. literalinclude:: ../../../src/MEDCoupling_Swig/UsersGuideExamplesTest.py
393 :start-after: UG_MEDCouplingFieldDouble_7
394 :end-before: UG_MEDCouplingFieldDouble_7
396 Define groups and write mesh using advanced API
397 -----------------------------------------------
399 To get access to full power of MED file, for example to define groups of cells, it is
400 necessary to use the advanced medcoupling API, namely class MEDFileUMesh_.
402 .. _MEDFileUMesh: ../../developer/classMEDCoupling_1_1MEDFileUMesh.html
404 First of all we populate a MEDFileUMesh with meshes (MEDCouplingUMesh) of different dimensions, if present:
406 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
407 :start-after: UG_ReadMeshFromFile_4
408 :end-before: UG_ReadMeshFromFile_4
410 Level must be 0 for a mesh of highest dimension, -1 for a mesh of dimension a unit less than highest dimension etc.
412 If cells are not yet sorted by geometric type, we can pass True as the third argument of setMeshAtLevel to make them sorted:
414 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
415 :start-after: UG_ReadMeshFromFile_9
416 :end-before: UG_ReadMeshFromFile_9
418 .. WARNING:: meshes of different dimension must share the same point coordinate array and have the same name
420 We can change point coordinates as soon as all meshes are added:
422 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
423 :start-after: UG_ReadMeshFromFile_5
424 :end-before: UG_ReadMeshFromFile_5
426 To define groups we call, for example:
428 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
429 :start-after: UG_ReadMeshFromFile_6
430 :end-before: UG_ReadMeshFromFile_6
432 The first argument of addGroup defines a type of group. 1 stands for nodes. 0,-1,-2 and -3 have the same meaning as the level in setMeshAtLevel method. Note that a name of DataArrayInt defines a group name.
434 It is possible to change name of a group or a family by calling:
436 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
437 :start-after: UG_ReadMeshFromFile_7
438 :end-before: UG_ReadMeshFromFile_7
440 Finally we write all data added to *mm* to a file:
442 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
443 :start-after: UG_ReadMeshFromFile_8
444 :end-before: UG_ReadMeshFromFile_8
446 The last argument defines behavior if a file exists. 2 means remove. 1 means append; if data with same ID present, an exception is thrown. 0 means overwrite data with same ID; that can lead to a file corruption.
448 .. _medcoupling_AdvancedReading:
450 Read/write fields using advanced API
451 ------------------------------------
453 Having *field* on *mesh* we can write it using MEDFileField1TS_ class, which is a part of advanced medcoupling API, as following:
455 .. _MEDFileField1TS: ../../developer/classMEDCoupling_1_1MEDFileField1TS.html
457 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
458 :start-after: UG_RWFieldAdv_0
459 :end-before: UG_RWFieldAdv_0
461 The last argument of write method defines behavior if a file exists. 2 means remove. 1 means append; if data with same ID present, an exception is thrown. 0 means overwrite data with same ID; that can lead to a file corruption.
463 If there is a need to write a field lying only on a part of a mesh, the following code gives an example of this:
465 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
466 :start-after: UG_RWFieldAdv_1
467 :end-before: UG_RWFieldAdv_1
469 *profile* defines entities on which *fieldPartial* lies. *level* defines entities the field lies on: 1 stands for nodes, 0 is for entities of dimension equal to the mesh dimension, -1 is for entities of dimension a unit less than the mesh dimension etc.
471 MEDFileField1TS also can be used to read a field:
473 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
474 :start-after: UG_RWFieldAdv_2
475 :end-before: UG_RWFieldAdv_2
477 * field method can be used if field support is simple: one spatial discretization and one *level*.
478 * getFieldAtLevel method allows to choose spatial discretization and *level*.
479 * getFieldOnMeshAtLevel method allows to specify spatial discretization, *level* and mesh.
481 *level* of a field, if unknown, can be defined by calling:
483 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
484 :start-after: UG_RWFieldAdv_3
485 :end-before: UG_RWFieldAdv_3
487 *maxDim* is the maximal absolute dimension of entities the field lies on. *maxRelDims* is a sequence returning the dimensions relative to the maximal absolute one.
489 To read/write fields including several time steps medcoupling provides MEDFileFieldMultiTS_ class. To write all time steps it is necessary just to append them to MEDFileFieldMultiTS:
491 .. _MEDFileFieldMultiTS: ../../developer/classMEDCoupling_1_1MEDFileFieldMultiTS.html
493 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
494 :start-after: UG_RWFieldAdv_4
495 :end-before: UG_RWFieldAdv_4
497 To read a time step with a known *iteration* and *order* MEDFileField1TS can be used as shown above. To iterate through all time steps, use MEDFileFieldMultiTS as following:
499 .. literalinclude:: ../../../src/MEDLoader/Swig/UsersGuideExamplesTest.py
500 :start-after: UG_RWFieldAdv_5
501 :end-before: UG_RWFieldAdv_5