Salome HOME
medcoupling documentation modification
[tools/medcoupling.git] / doc / developer / doxygen / doxfiles / reference / medloader / MEDLoaderBasicAPI.dox
1
2 /*!
3 \page MEDLoaderBasicAPIPage Basic MEDLoader API
4
5 [TOC]
6
7 The aim of this page is to present MEDLoader basic API. The goal of
8 this basic API is to perform a read or a write in one shot without any
9 internal state. That's why the basic API of MEDLoader offers \b only \b static functions whose names have the first
10 character in capital. You are intended to use these functions. The following
11 chapters will try to describe in details some of important ones.
12
13 The basic idea of MEDLoader is to exploit as much as possible MED
14  file capabilities to store MEDCoupling data file in a MED file and
15 reversely to load from a MED file into a MEDCoupling data structure.
16 Basically, the info on components of MEDCoupling::DataArrayDouble instances are stored into components and units into MED files. The
17 name of meshes and fields are used by MEDLoader as is into
18 MED file. From a field f with \ref MEDCoupling::MEDCouplingTimeDiscretization
19 "time discretization" set to ONE_TIME, calls to
20 \c f->getTime(time,iteration,order) are used by MEDLoader to store the field into MED file. All strings used by MEDLoader should fulfill the rules of MED file where string length
21 is limited.
22 That's why the user should be aware of these constraints when trying to read/write a MED file using MEDLoader.
23 MEDLoader tries to manage that by protecting the user by throwing exceptions when the rules are not followed.
24
25 \section BasicMEDLoaderBasicAPIGlobalInfo Retrieving tiny global information from MED files using basic API
26
27 The MEDCoupling::CheckFileForRead function will perform such a check before any attempt of read.
28 A field is also discriminated by its name. The functions MEDCoupling::GetCellFieldNamesOnMesh and MEDCoupling::GetNodeFieldNamesOnMesh are available to know all fields
29 respectively on cells and on nodes lying on a specified mesh.
30
31  A field is defined by several time steps discriminated by a pair of ints
32 (iteration,order). It is \b not possible to store 2 time steps of a same
33 field having the same iteration and order
34 numbers. The floating point value attached to this couple of ids (iteration,order) is only present for information.
35 Static functions MEDCoupling::GetCellFieldIterations and
36 MEDCoupling::GetNodeFieldIterations return a vector of pairs (iteration, order).
37
38 A field time step lies on one \b or \b more mesh(es) specified by its \b or \b their name(s). A field time step in
39 MED file could be defined on point \b and on cell \b and, \b or on Gauss points \b and, \b or on point per element.
40
41 This recalled specificities of MED file explain that it is necessary to specify each time, at field-read time, the type of field, the iteration and order number the mesh you are interested in.
42
43 Let's recall basic principles that explains some of the aspect of MEDLoade API.
44 \anchor MEDLoaderMeshNameConstraint MED file can contain several meshes. These meshes are
45 discriminated by their names (two meshes could not have the same
46 name). In the same way a MED file can contain several fields.
47 So MEDLoader offers the MEDCoupling::GetMeshNames function to
48 discover all the mesh names contained in your file.
49
50 \section BasicMEDLoaderBasicAPIMesh Reading and writing meshes in MED files using basic API
51
52 In MED file meshes could combine in one unstructured mesh cells that
53 have different dimension. For example it is possible to mix
54 MED_TETRA4, MED_TRIA6, MED_SEG2, MED_POINT1, MED_POLYGON,
55 MED_POLYHEDRA in a same mesh. In MEDCouplingUMesh such a mix is not
56 allowed as described \ref MEDCouplingMeshes "here". So to \b read such mesh it
57 is important to know which mesh dimension you are interested in. The parameter \b meshDimRelToMax of function MEDCoupling::ReadUMeshFromFile corresponds to the mesh dimension you are
58 interested in, expressed relatively to the maximal dimension of cells contained
59 in the mesh in file.
60
61 Let's take 2 examples :
62
63 - If you have a mesh called "MyMesh" in file "file1.med" with
64 MED_POLYGON, MED_TRI3, MED_SEG2 and MED_SEG3 : The max dimension of
65 cells is 2 (for MED_POLYGON and MED_TRI3). So if you want exclusively
66 cells with type MED_POLYGON and MED_TRI3 you should use :
67
68 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_9
69
70 If you are interested in MED_SEG2 and MED_SEG3 you should use :
71
72 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_10
73
74 The function MEDCoupling::ReadUMeshDimFromFile could
75 help you to have this mesh dimension.
76
77 Here is a \ref MEDLoaderExample2 "Python example".<br>
78
79 To finish this subsection, it is important to know that MEDLoader
80 takes into account the cell numbers stored in a mesh of a med
81 file. This renumbering allows MEDLoader to conserve the order of
82 MEDCoupling cells into the file. So if the renumbering of cells in MED
83 file is not correct an exception will be thrown.
84
85 \subsection BasicMEDLoaderAPIPoMesh Part of meshes in MED files
86
87 A mesh contains one or more families on nodes and/or on cells. A family is a partition
88 (mathematical sense) of the mesh it lies on. A family can be described
89 by an integer value on \b all nodes and on \b all cells of a same mesh.
90 All cells and nodes having the same id define this family. This id
91 is called the familyId. A family is discriminated by its id. MED file
92 attaches a name to its id to be more user friendly. So by construction, 2 different
93 families could not share anything. The user can retrieve all the
94 families names available on a mesh with the static function MEDCoupling::GetMeshFamiliesNames.
95
96 A group is a set of families. So groups can overlap each other,
97 contrary to families. Groups are also discriminated by a name. As for
98 families the static function to retrieve the groups of a specified mesh is MEDCoupling::GetMeshGroupsNames.
99
100 MEDLoader allows you to retrieve the
101 corresponding "part of meshes" thanks to static functions
102 MEDCoupling::ReadUMeshFromFamilies and MEDCoupling::ReadUMeshFromGroups.
103 These functions allow you to combine several families and groups in the
104 same returned mesh.
105
106 \subsection BasicMEDLoaderAPIField Reading a field at one time step in MED files
107
108 A field at one time step on one mesh, with one entity (cell, node)
109 lies on all mesh on a part of it. In this last case a definition of
110 a profile is needed. Even if the notions of profile on mesh and group
111 on mesh could appear close, these two concepts are totally
112 disconnected in MED file.
113 The aspect of profile is managed by MEDLoader, that is why this
114 aspect does not appear in the MEDLoader API.
115
116 \if ENABLE_EXAMPLES
117 Here is a \ref py_mcfield_loadfile_onetimestep_basic "Python example".
118 \endif
119
120 \subsection MEDLoaderMEDFieldsRead Reading several field time steps at a time in MED files
121
122 It is possible with MEDLoader to read several time steps of a field at once.
123 The advantage with this approach is to avoid reading and loading the same mesh several
124 times.
125
126 \if ENABLE_EXAMPLES
127 Here is a \ref py_mcfield_loadfile_alltimesteps_basic "Python example".
128 \endif
129
130 \section MEDLoaderWriteMain Writing a MED file with MEDLoader
131
132 As MED file does, MEDLoader write process clearly separates
133 meshes from fields. The reason is that a common use case in write mode
134 is to write in a first time a mesh and then to write several time steps
135 of a same field in appended mode.
136
137 The fact that the write process is rarely in a one shot puts a
138 constraint on API to precise to MEDLoader if you intend
139 to append data to an existing file, or if you want to create a new
140 file from scratch. This explains the presence of boolean parameter \b
141 writeFromScratch in API of MEDLoader starting with \b
142 MEDCoupling::Write* .
143
144 If \b writeFromScratch parameter is set to \b true and if the file
145 already exists the file will be crashed and replaced by the new
146 corresponding data. If \b writeFromScratch parameter is set to \b false and if the
147 file does \b not \b exist the new file is created, but if the file
148 exists MEDLoader will enter in appended mode.
149
150 Two classes of MEDLoader write functions exist when \b writeFromScratch
151 is set to \b false :
152
153 -  Functions \b MEDCoupling::Write*Dep : The write operation is performed without any question in file. The
154    responsibility is let to the user because the MED file could be
155    corrupted. The advantage of this function is that it is faster
156    because no check is done.
157 - Functions \b MEDCoupling::Write* : MEDLoader will not corrupt your file
158    by always trying to append data. The consequence is that a
159    read of part (and data processing) of MED file could be needed before any attempt of
160    writing. So these functions could be in some cases much time and memory consuming.
161
162 The behaviour of MEDLoader when \b writeFromScratch is set to false will be precised
163 for each \b MEDCoupling::Write* functions is the next subsections.
164
165 \subsection MEDLoaderWriteMesh Writing one mesh in a MED file with MEDLoader
166
167 The first think to know is that MEDLoader is using the \b meshName in
168 MEDCoupling::MEDCouplingMesh instance to put it in MED file.
169
170 As explained in previous section \ref MEDLoaderMeshNameConstraint "here",
171 a mesh in MED file is discriminated by a name, so the \b meshName
172 \b should \b be \b non \b empty. If it is the case an
173 INTERP_KERNEL::Exception will be thrown.
174
175 \if ENABLE_EXAMPLES
176 Here is a \ref py_mcumesh_writefile_onemesh_basic "Python example".
177 \endif
178
179 \subsection MEDLoaderWriteMeshes Writing several meshes in a MED file with MEDLoader
180
181 It could be interesting to write several meshes in one shot. Two
182 possibilities:
183
184 - Write several instances of MEDCoupling::MEDCouplingUMesh
185   lying \b on \b same \b coords \b with \b different \b mesh \b dimensions. In this case MEDCoupling::WriteUMeshes is the function you should
186   use. Typically this function should be used to write files such as
187   defined \ref MEDLoaderExample2 "here".
188   This function first checks that all instances share the same
189   MEDCoupling::DataArrayDouble instance as coords. If not an
190   INTERP_KERNEL::Exception will be thrown and an invocation on
191   MEDCoupling::MEDCouplingPointSet::tryToShareSameCoords will be necessary.
192
193 - Write a partition of meshes having \b same \b mesh \b dimension, that is to say a set of
194   groups and families from given meshes. As in the previous case the
195   check of same coords will be done (if not an INTERP_KERNEL::Exception is
196   thrown). After this step this function will
197   merge input (preserving order) and will simplify the
198   merged mesh. After this operation, the groups will be constituted by
199   assigning the group names with the corresponding names of
200   instance. That's why all meshes must have a not empty name which is different from one mesh to the other. The function to use in this case is
201   MEDCoupling::WriteUMeshesPartition.
202
203 For these 2 described functions the semantic of \b writeFromScratch when
204 \b false is the same, that is to say : no writing
205 (INTERP_KERNEL::Exception thrown) will be done if the
206 file already exists and contains a mesh with name 'meshName'
207 for MEDCoupling::WriteUMeshesPartition function and the name of first element
208 of unstructured mesh vector passed as first parameter of
209 MEDCoupling::WriteUMeshes.
210
211 \subsection MEDLoaderWriteField Writing one time step of a field in a MED file with MEDLoader
212
213 To write \b one \b time \b step of a field from scratch with MEDLoader
214 use MEDCoupling::WriteField function. The behaviour of this function depends
215 on the value of the \b writeFromScratch parameter :
216
217 - When \b writeFromScratch equals to \b true, this function performs two things, it
218 writes the underlying mesh and writes the specified time step on it.
219
220 - When \b writeFromScatch equals to \b false, this function checks that
221   the underlying mesh exists (by looking to the contents of \c field->getMesh()->getName()) in file. If not, the behaviour is the
222   same that previous case with \b writeFromScratch parameter set to
223   \b true. If the mesh already exists, MEDLoader reads the field and
224   tries to apply field on it. This operation could be rather time
225   consuming because a read operation is performed and a reorder
226   operation too. If the file already contains the same field at the
227   same time step (iteration and order ids) the corresponding time step
228   will be replaced by the field passed in parameter.
229
230 \subsection MEDLoaderWriteFields Writing several time steps of a field in a MED file with MEDLoader
231
232 \if ENABLE_EXAMPLES
233 Here is a \ref py_mcfield_writefile_severaltimesteps_basic "Python example".
234 \endif
235
236 */