3 \page MEDLoaderBasicAPIPage Basic MEDLoader API.
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 methods whose names have the first
10 character in capital. You are intended to use these methods. The following
11 chapters will try to describe in details some of important ones.
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 ParaMEDMEM::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 ParaMEDMEM::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
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.
25 \section BasicMEDLoaderBasicAPIGlobalInfo Retrieving tiny global information from MED files using basic API
27 The MEDLoader::CheckFileForRead method will perform such a check before any attempt of read.
28 A field is also discriminated by its name. The methods MEDLoader::GetCellFieldNamesOnMesh and MEDLoader::GetNodeFieldNamesOnMesh are available to know all fields
29 respectively on cells and on nodes lying on a specified mesh.
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 methods MEDLoader::GetCellFieldIterations and
36 MEDLoader::GetNodeFieldIterations return a vector of pairs (iteration, order).
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.
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.
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 MEDLoader::GetMeshNames method to
48 discover all the mesh names contained in your file.
50 \section BasicMEDLoaderBasicAPIMesh Reading and writing meshes in MED files using basic API
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 method MEDLoader::ReadUMeshFromFile corresponds to the mesh dimension you are
58 interested in, expressed relatively to the maximal dimension of cells contained
61 Let's take 2 examples :
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 :
68 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_9
70 If you are interested in MED_SEG2 and MED_SEG3 you should use :
72 \snippet MEDLoaderExamplesTest.py PySnippetMeshAdvAPI1_10
74 The method MEDLoader::ReadUMeshDimFromFile could
75 help you to have this mesh dimension.
77 Here is a \ref MEDLoaderExample2 "Python example".<br>
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.
85 \subsection BasicMEDLoaderAPIPoMesh Part of meshes in MED files
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 method MEDLoader::GetMeshFamiliesNames.
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 method to retrieve the groups of a specified mesh is MEDLoader::GetMeshGroupsNames.
100 MEDLoader allows you to retrieve the
101 corresponding "part of meshes" thanks to static methods
102 MEDLoader::ReadUMeshFromFamilies and MEDLoader::ReadUMeshFromGroups.
103 These methods allow you to combine several families and groups in the
106 \subsection BasicMEDLoaderAPIField Reading a field at one time step in MED files
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.
116 Here is a \ref py_mcfield_loadfile_onetimestep_basic "Python example".
119 \subsection MEDLoaderMEDFieldsRead Reading several field time steps at a time in MED files
121 It is possible with MEDLoader to read several time steps of a field at once.
122 The advantage with this approach is to avoid reading and loading the same mesh several
125 Here is a \ref py_mcfield_loadfile_alltimesteps_basic "Python example".
128 \section MEDLoaderWriteMain Writing a MED file with MEDLoader
130 As MED file does, MEDLoader write process clearly separates
131 meshes from fields. The reason is that a common use case in write mode
132 is to write in a first time a mesh and then to write several time steps
133 of a same field in appended mode.
135 The fact that the write process is rarely in a one shot puts a
136 constraint on API to precise to MEDLoader if you intend
137 to append data to an existing file, or if you want to create a new
138 file from scratch. This explains the presence of boolean parameter \b
139 writeFromScratch in API of MEDLoader starting with \b
142 If \b writeFromScratch parameter is set to \b true and if the file
143 already exists the file will be crashed and replaced by the new
144 corresponding data. If \b writeFromScratch parameter is set to \b false and if the
145 file does \b not \b exist the new file is created, but if the file
146 exists MEDLoader will enter in appended mode.
148 Two classes of MEDLoader write methods exist when \b writeFromScratch
151 - Methods \b MEDLoader::Write*Dep : The write operation is performed without any question in file. The
152 responsibility is let to the user because the MED file could be
153 corrupted. The advantage of this method is that it is faster
154 because no check is done.
155 - Methods \b MEDLoader::Write* : MEDLoader will not corrupt your file
156 by always trying to append data. The consequence is that a
157 read of part (and data processing) of MED file could be needed before any attempt of
158 writing. So these methods could be in some cases much time and memory consuming.
160 The behaviour of MEDLoader when \b writeFromScratch is set to false will be precised
161 for each \b MEDLoader::Write* methods is the next subsections.
163 \subsection MEDLoaderWriteMesh Writing one mesh in a MED file with MEDLoader
165 The first think to know is that MEDLoader is using the \b meshName in
166 ParaMEDMEM::MEDCouplingMesh instance to put it in MED file.
168 As explained in previous section \ref MEDLoaderMeshNameConstraint "here",
169 a mesh in MED file is discriminated by a name, so the \b meshName
170 \b should \b be \b non \b empty. If it is the case an
171 INTERP_KERNEL::Exception will be thrown.
173 Here is a \ref py_mcumesh_writefile_onemesh_basic "Python example".
176 \subsection MEDLoaderWriteMeshes Writing several meshes in a MED file with MEDLoader
178 It could be interesting to write several meshes in one shot. Two
181 - Write several instances of ParaMEDMEM::MEDCouplingUMesh
182 lying \b on \b same \b coords \b with \b different \b mesh \b dimensions. In this case MEDLoader::WriteUMeshes is the method you should
183 use. Typically this method should be used to write files such as
184 defined \ref MEDLoaderExample2 "here".
185 This method first checks that all instances share the same
186 ParaMEDMEM::DataArrayDouble instance as coords. If not an
187 INTERP_KERNEL::Exception will be thrown and an invocation on
188 ParaMEDMEM::MEDCouplingPointSet::tryToShareSameCoords will be necessary.
190 - Write a partition of meshes having \b same \b mesh \b dimension, that is to say a set of
191 groups and families from given meshes. As in the previous case the
192 check of same coords will be done (if not an INTERP_KERNEL::Exception is
193 thrown). After this step this method will
194 merge input (preserving order) and will simplify the
195 merged mesh. After this operation, the groups will be constituted by
196 assigning the group names with the corresponding names of
197 instance. That's why all meshes must have a not empty name which is different from one mesh to the other. The method to use in this case is
198 MEDLoader::WriteUMeshesPartition.
200 For these 2 described methods the semantic of \b writeFromScratch when
201 \b false is the same, that is to say : no writing
202 (INTERP_KERNEL::Exception thrown) will be done if the
203 file already exists and contains a mesh with name 'meshName'
204 for MEDLoader::WriteUMeshesPartition method and the name of first element
205 of unstructured mesh vector passed as first parameter of
206 MEDLoader::WriteUMeshes.
208 \subsection MEDLoaderWriteField Writing one time step of a field in a MED file with MEDLoader
210 To write \b one \b time \b step of a field from scratch with MEDLoader
211 use MEDLoader::WriteField method. The behaviour of this method depends
212 on the value of the \b writeFromScratch parameter :
214 - When \b writeFromScratch equals to \b true, this method performs two things, it
215 writes the underlying mesh and writes the specified time step on it.
217 - When \b writeFromScatch equals to \b false, this method checks that
218 the underlying mesh exists (by looking to the contents of \c field->getMesh()->getName()) in file. If not, the behaviour is the
219 same that previous case with \b writeFromScratch parameter set to
220 \b true. If the mesh already exists, MEDLoader reads the field and
221 tries to apply field on it. This operation could be rather time
222 consuming because a read operation is performed and a reorder
223 operation too. If the file already contains the same field at the
224 same time step (iteration and order ids) the corresponding time step
225 will be replaced by the field passed in parameter.
227 \subsection MEDLoaderWriteFields Writing several time steps of a field in a MED file with MEDLoader
229 Here is a \ref py_mcfield_writefile_severaltimesteps_basic "Python example".
