2 :description: introduction guide for users of the MEDMEM library
3 :keywords: mesh, field, med, MEDCoupling, MEDLoader
4 :author: Guillaume Boulant
6 .. include:: medcalc-definitions.rst
8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 MEDMEM library: Starter guide for users
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 This document illustrates how to start with the programming interface
13 of the MEDMEM library. The users is someone who intends to create a
14 data processing script involving meshes and fields.
16 .. contents:: Sommaire
24 Definition of the MEDMEM library
25 --------------------------------
27 The MEDMEM library is designed to manipulate meshes and fields that
28 conform to the MED data model. This library can be used in C++
29 programs as in python scripts for data processing on meshes and
30 fields. The library contains the data structure to describe meshes and
31 fields as C++ objects (MEDCoupling package). It provides a set of
32 functions to manage the persistency toward the med file format
33 (MEDLoader package), and to process the data througt interpolation and
34 localization algorithms (INTERP_KERNEL and REMAPPER packages), for
35 example to perform field projections from a mesh to another.
37 Installation of the MEDMEM library
38 ----------------------------------
40 The MEDMEM library is part of the SALOME MED module and then is
41 installed together with this module by the installation process of
42 SALOME. Nevertheless, it is possible for low-weight deployment to
43 install only the MEDMEM library from the source files embedded in the
44 SALOME MED module. Keep in mind that the MEDMEM library is designed to
45 be a self-consistent library with very few third party softwares (only
46 med-file, glibc and mpi typically). In particular, it is strictly
47 independant from the SALOME framework even if it distributed with
48 SALOME for convenience reasons.
50 Components of the MEDMEM library
51 --------------------------------
53 The MEDMEM library consists in a small set of atomic libraries files,
56 * :tt:`medcoupling`: this library provides the data structures (C++
57 classes) to describe meshes and fields.
58 * :tt:`medloader`: this library provides I/O functions to the MED file
60 * :tt:`interpkernel`: this library provides the mathematical
61 structures and algorithms required med data processing, in
62 particular interpolation and localization.
63 * :tt:`medcouplingremapper`: this library provides the functions for
64 fields projections and interpolation.
66 The figure below represents the layer structure of the packages of the
69 .. image:: images/medlayers_70pc.png
72 What we call MEDMEM library in this document is represented by the
73 orange packages on this diagram. The white packages reprensent the old
74 deprecated MEDMEM library. The blue packages represent the aditionnal
75 components for field manipulation througth the user interface (TUI and
78 The MEDMEM library comes also with this set of atomic libraries for
79 advanced users/programmers:
81 * :tt:`medcouplingcorba`: this library is designed for cross process
82 exchange of medcoupling objects.
83 * :tt:`medpartitioner`: this library provides functions to split a MED
84 domain in several part in the perspective of parallel computing
86 All these atomic C++ libraries are wrapped into a set of python
87 modules (using the swig binding technology) so that all the data
88 processing can be realized by scripting.
90 .. warning:: It could happen that some parts of the C++ libraries are
91 not wrapped into python modules. This coverture will be
92 extend on demand and if the integrity of the concepts is
95 Main concepts of the MEDMEM library
96 ===================================
98 .. warning:: TODO avec Antony. Présenter les structure de données de
99 MEDCoupling principalement. Describe the MEDMEM data
100 model, the typical content of a med file, the types of
101 cell that compose the meshes, the types of spatial
102 discretization of fields, ...
104 Basic usages of the MEDMEM library
105 ==================================
107 This section illustrates the usage of main features of the MEDMEM
108 library using python examples. The usage of python is just to have a
109 light syntax that makes more easy the first understanding.
111 .. note:: All code examples here after are parts of the tutorial use
112 cases located in the folder :tt:`src/MEDCalc/tut` in the MED
113 source directory. These use cases are all working executable
114 programs and they can be used to initiate your own script.
116 Preparing the shell environment
117 -------------------------------
119 We make the hypothesis here that the MEDMEM library is installed using
120 the SALOME procedure and then is located in the MED module
121 installation directory. In addition to the MED library, the third
122 party softwares required for executing the examples are: python, hdf5
123 and med-fichier. Then, you should prepare your shell environment
124 with a set of instructions that looks like::
126 #------ python ------
127 export PYTHONHOME=</path/to/python>
128 export PYTHONSTARTUP=${PYTHONHOME}/pythonrc.py
129 export PYTHON_INCLUDE=${PYTHONHOME}/include/python2.6
130 export PATH=${PYTHONHOME}/bin:${PATH}
131 export LD_LIBRARY_PATH=${PYTHONHOME}/lib:${LD_LIBRARY_PATH}
134 HDF5HOME=</path/to/hdf5>
135 export PATH=${HDF5HOME}/bin:$PATH
136 export LD_LIBRARY_PATH=${HDF5HOME}/lib:${LD_LIBRARY_PATH}
137 export HDF5_DISABLE_VERSION_CHECK=1
140 MED2HOME=</path/to/med>
141 export PATH=${MED2HOME}/bin:${PATH}
142 export LD_LIBRARY_PATH=${MED2HOME}/lib:${LD_LIBRARY_PATH}
145 MED_ROOT_DIR=<path/to/salome_med_module>
146 export LD_LIBRARY_PATH=${MED_ROOT_DIR}/lib/salome:${LD_LIBRARY_PATH}
147 PYTHONPATH=${MED_ROOT_DIR}/lib/python2.6/site-packages/salome:${PYTHONPATH}
148 PYTHONPATH=${MED_ROOT_DIR}/bin/salome:${PYTHONPATH}
149 PYTHONPATH=${MED_ROOT_DIR}/lib/salome:${PYTHONPATH}
152 Example 01: Explore a med file to get information concerning meshes and fields
153 ------------------------------------------------------------------------------
155 :objectives: This example illustrates how to get information
156 concerning meshes and fields from a med file, using the
159 The loading of meshes and fields from a med file to a MEDCoupling data
160 structure requires first the knowledge of metadata associated to these
161 meshes and fields. You have to know the names of the meshes, so that
162 you can specify the one you want to load, and then the names of the
163 fields associated to one given mesh, the space discretizations used
164 for each field, and the iterations available.
166 The MEDLoader library can read these metadata without loading the
167 physical data that compose the meshes and fields. This feature ensures
168 the performance of the exploration process, in particular in the case
171 This first instruction looks for meshes embedded in the med file
172 (located by :tt:`filepath`) and returns the list of mesh names:
174 .. include:: ../../tut/medloader/tutorial.py
179 .. WARNING: Note that the file path for the include directive must be
180 relative to this rst source file (i.e. as organized in the MED
181 source directory, and nevertheless the build procedure is realized
184 Then, you may select one of these names (or iterate on all names of
185 the list) and read the list of fields defined on this mesh:
187 .. include:: ../../tut/medloader/tutorial.py
192 A field name could identify several MEDCoupling fields, that differ by
193 their spatial discretization on the mesh (values on cells, values on
194 nodes, ...). This spatial discretization is specified by the
195 TypeOfField that is an integer value in this list:
197 * :tt:`0 = ON_CELLS` (physical values defined by cell)
198 * :tt:`1 = ON_NODES` (physical values defined on nodes)
199 * :tt:`2 = ON_GAUSS_PT` (physical values defined on Gauss points)
200 * :tt:`3 = ON_GAUSS_NE`
202 .. note:: This constant variables are defined by the MEDLoader module
203 (:tt:`from MEDLoader import ON_NODES`).
205 As a consequence, before loading the physical values of a field, we
206 have to determine the types of spatial discretization that come with
207 this field name and to choose one of this types. The instruction below
208 read all the spatial discretization types available for the field of
209 name :tt:`fieldName` defined on the mesh of name :tt:`meshName`:
211 .. include:: ../../tut/medloader/tutorial.py
216 Once you have selected the spatial discretization of interest (called
217 :tt:`typeOfDiscretization` in the code below, that corresponds to an
218 item of the list :tt:`listOfTypes`), you can extract the list of time
219 iterations available for the identified field:
221 .. include:: ../../tut/medloader/tutorial.py
226 The iterations can be weither a list of time steps for which the field
227 is defined (a timeseries) or a list of frequency steps (spectral
228 analysis). In any case, an iteration item consists in a couple of
229 integers, the first defining the main iteration step and the second an
230 iteration order in this step, that can be consider as a sub-iteration
231 of the step. In most of cases, the iteration order is set to :tt:`-1`
234 The field values can now be read for one particular time step (or
235 spectrum tic), defined by the pair (iteration number, iteration
236 order). This is illustrated by the example here after.
238 Example 02: Load a mesh and a field from a med file
239 ---------------------------------------------------
241 :objectives: This illustrates how to load the physical data of a
242 specified mesh and a specified field.
244 The metadata read from a med file are required to identify the list of
245 meshes and fields in the med file. We assume in this example that the
246 mesh and field to load are identified, i.e. we know the name of the
247 mesh to load (:tt:`meshName`) and the characteristic properties of the
248 field to load (:tt:`fieldName`, :tt:`typeOfDiscretization` and
249 :tt:`iteration`). For example, the instruction below load the mesh of
252 .. include:: ../../tut/medloader/tutorial.py
257 and the instruction below load the field with name :tt:`fieldName`
258 defined on this mesh at a particular iteration step characterized by
259 the couple :tt:`(iterationNumber,iterationOrder)`:
261 .. include:: ../../tut/medloader/tutorial.py
266 The variables :tt:`mesh` and :tt:`field` in this code example are instances of
267 the MEDCoupling classes describing the meshes and fields.
269 Note that the read functions required the parameter
270 :tt:`dimrestriction`. This parameter discreminates the mesh dimensions you
271 are interested to relatively to the maximal dimension of cells
272 contained in the mesh (then its value could be 0, -1, -2 or -3
273 depending on the max dimension of the mesh). A value of
274 :tt:`dimrestriction=0` means "no restriction".
276 Example 03: Manage the MEDCoupling data load from a med file
277 ------------------------------------------------------------
279 :objectives: Some suggestions for the MEDCoupling objects management,
280 in a programming context.
282 In a real programming case, it could be relevant to explore first the
283 med file to load all metadata concerning the whole set of meshes and
284 associated fields, and then to load the physical data only once when
285 required by the program.
287 Such a programming scenario required that you keep all metadata in
288 data structures created in memory, so that you can manage the
289 collection of meshes and fields. Nevertheless, the MEDMEM library
290 does not provide such data structures.
292 We suggest to work with a simple list concept to store the metadata
293 for each mesh entry and each field entry. Note that a mesh entry is
294 characterized by the mesh name only, while a field entry is
295 charaterized by the following attributes:
297 * :tt:`fieldName`: the name of the field
298 * :tt:`meshName`: the name of the mesh that supports the field
299 * :tt:`typeOfDiscretization`: the type of spatial discretization
300 * :tt:`iteration`: a couple of integers :tt:`(iter,order)` that
301 characterizes the step in a serie (timeseries or spectrum).
303 By default, we suggest to work with a simple map concept (dictionnary in a
304 python context, map in a C++ context) to register the meshes and
305 fields loaded from the med file for each metadata entry.
307 Then, depending on the processing algorithm you intend to implement,
308 you may dispatch the data in a tree structure that fit your specific
309 case, for performance reasons. For example, the following code
310 illustrates how to dispatch the metadata in a tree data structure
311 where leaves are the physical data (field objects). We first have to
312 define a tree structure (basic definition in htis simple case, but it
315 .. include:: ../../tut/medloader/manage.py
320 Then, we can scan the med structure and dispatch the metadata in the
323 .. include:: ../../tut/medloader/manage.py
328 Finally (and afterwards), we can display on standard output the
329 metadata registered in the tree structure:
331 .. include:: ../../tut/medloader/manage.py
336 Example 04: Simple arithmetic operations with fields
337 ----------------------------------------------------
339 :objectives: This example illustrates how to load field iterations
340 from a med file containing a field timeseries and shows
341 how to use these iterations in simple arithmetic
344 We consider a med file :tt:`timeseries.med`, containing one single
345 mesh named :tt:`Grid_80x80` that supports a field with values defined
346 on nodes (:tt:`typeOfDiscretization=ON_NODES`) given for ten
349 This first code block identifies the mesh and the field to consider in
352 .. include:: ../../tut/addfields/operations.py
357 The following instructions load the field, make a scaling on the
358 physical values (multiply by 3) and then save the result in an output
359 med file named :tt:`scaling.med`:
361 .. include:: ../../tut/addfields/operations.py
366 Note the usage of the method :tt:`applyFunc` that takes in argument a
367 string expression that defined the mathematical function to apply on
368 the values of the fields. In this expression, the field is symbolized
369 by the letter :tt:`f`.
371 The following set of instructions makes the addition of iteration
372 number 3 with iteration number 4 of the field. Note that this
373 operation required first to load the mesh:
375 .. include:: ../../tut/addfields/operations.py
380 Exemple 05: Compare fields load from different files
381 ----------------------------------------------------
383 :objectives: Illustrates the usage of the function
386 Exemple 06: Create a field from scratch on a spatial domain
387 -----------------------------------------------------------
389 :objectives: Illustrates the applyFunc method of fields
391 Exemple 07: Manipulate structured mesh
392 --------------------------------------
394 :objectives: Illustrates the basic usage of the advanced interface of
397 The MEDLoader frontal interface let you load unstructured meshes:
399 .. include:: ../../tut/medloader/tutorial.py
404 That is to say that even if the mesh is a structured mesh (a grid mesh
405 for example), then you will get a MEDCoupling unstructured mesh
408 To manipulate structured mesh objects, you have to use the MEDLoader
409 backend interface named :tt:`MEDFileMesh`, or its derivative
410 :tt:`MEDFileUMesh` for unstructured meshes, and :tt:`MEDFileCMesh` for
411 structured meshes (CMesh for Cartesian Mesh). The code below
412 illustrates how to load a mesh using the :tt:`MEDFileMesh` interface,
413 and to know if it is a structured mesh:
415 .. include:: ../../tut/medloader/cmesh.py
420 This second example can be used in the case where you know in advance
421 that it is a structured mesh:
423 .. include:: ../../tut/medloader/cmesh.py
428 In any cases, you can also save the mesh in another file with the
429 methode :tt:`write` of the :tt:`MEDFileMesh` object:
431 .. include:: ../../tut/medloader/cmesh.py
436 Exemple 08: Make a projection of a field
437 ----------------------------------------
439 :objectives: Make the projection of a field from a source mesh to a
440 target meshe. The source mesh and the target mesh are
441 two different mesh of the same geometry.
443 The input data of this use case are:
445 * a source mesh, and a field defined on this source mesh (left side of
447 * a target mesh, on which we want to project the field (right side of
450 .. note:: The two meshes are displayed side by side on the figure for
451 convenience reason, but in the real use case they stand at
452 the same location in 3D space (they describe the same
455 .. image:: images/medop_projection_inputs.png
458 The expected result is a field defined on the target mesh and which
459 corresponds to a physical data equivalent to the source field,
460 i.e. with conservation of some physical properties. This operation
461 requires the usage of interpolation algorithms provided by the
462 :tt:`medcouplingremapper` library:
464 .. include:: ../../tut/projection/demomed/demo_loadsource.py
469 Some comments on this code:
471 * The physical property to be preserved by this interpolation is
472 specified using the keyword :tt:`IntensiveMaximum`
473 * The parameter :tt:`P0P0` given at the preparation step of the
474 remapper specifies that the interpolation is done from CELLS (P0) to
476 * The interpolation, strictly speaking, is performed by the
477 instruction :tt:`ftarget =
478 remap.transferField(fsource,defaultValue)`
479 * In this instruction, the :tt:`defaultValue` is used to set the target value
480 in the case where there is no cell in the source mesh that overlap
481 the target mesh (for example when the source mesh correspond to a
482 geometrical sub-part of the target mesh).
484 When executing the :tt:`remapper`, the result is a new field defined on
485 the target mesh, as illustrated on the figure below:
487 .. image:: images/medop_projection_result.png
490 Exemple 09: Make a partition of a mesh using a field
491 ----------------------------------------------------
493 :objective: This illustrates how to make a mesh partition using the
494 value of a field defined on this mesh.
496 The input data is a MEDCoupling scalar field (:tt:`field`) defined on
497 a 3D mesh, and we want to use this field as a criterium to make a
498 partition of the mesh, for example by creating the mesh surface that
499 delimits the volumes where the field value is greater that a limit L
500 (and conversely the volumes where the field value is lower).
502 .. image:: images/partition_mesh.png
505 The code below shows the simplest way to extract the cells where
506 :tt:`field>L` and to create the skin mesh:
508 .. include:: ../../tut/medcoupling/partition.py
513 At the end, the variable :tt:`skin` is a 2D mesh that can be saved in
514 a med file using the MEDLoader:
516 .. image:: images/partition_skin.png
519 Advanced usages of the MEDMEM library
520 =====================================
522 This section could explain how to process the physical data
523 (dataArray) and to manipulate the advanced concepts of the MEDMEM
526 .. Exemple 01: Create a field from an image
527 .. ----------------------------------------