Back to index

salome-med  6.5.0
Basic MEDLoader API.

The aim of this page is to present basic API of MEDLoader.

The goal of this basic API is to perform a read or a write in one shot without any internal state. That's why the basic API of MEDLoader offers only static methods whose method names have the first character in capital. You are intended to use these methods. The following chapters will try to describe in details some of important ones.

The basic idea of MEDLoader is to exploite as much as possible MED file capabilities to store MEDCoupling data file in a MED file and reversely to load from a MED file into a MEDCoupling data structure. Basically, the info on components of ParaMEDMEM::DataArrayDouble instances are stores into components and units into MED files. The name of meshes and fields are used by MEDLoader to use it as this into MED file. A field f with time discretization set to ONE_TIME, the value of f->getTime(time,iteration,order) are used by MEDLoader to store to identify the field into MED file. All strings used by MEDLoader to use it into MED file should fulfill the rules of MED file where length are limited. That's why the user should be aware of these constaints when trying to read/write a MED file using MEDLoader. MEDLoader tries to manage that by protecting the user by throwing exceptions when the rules are not followed.

Main concepts of MED files

Here we will describes some of basic concepts of MED files in order to use the best methods proposed by MEDLoader API.

Basics in MED files

First of all MEDLoader will not read MED files whose version is lower than 2.2. The MEDLoader::CheckFileForRead will perform the check of that before any attempt of read.

For new comers in MED file world some of basics principles are recalled here. Let's recall basic principles that explains some of the aspect of MEDLoade API. MED file can contain several meshes. These meshes are discriminated by their names (two meshes could not have the same names). By the same way a MED file can contain several fields in MED. So MEDLoader propose to you the MEDLoader::GetMeshNames method to discover all the mesh names contained in your file.

A field is also discriminated by its name. The method MEDLoader::GetCellFieldNamesOnMesh and MEDLoader::GetNodeFieldNamesOnMesh are available to know all fields respectively on cells and on nodes lying on a specified mesh.

A field is defined by several time steps discriminated by a pair of int (iteration,order). It is not possible to store 2 time steps of a same field having the same iteration and order number. The floatting point value attached on this couple of ids (iteration,order) is only present for information. Static methods MEDLoader::GetCellFieldIterations and MEDLoader::GetNodeFieldIterations return a vector of pair containing each respectively iteration and order.

A time step of a field lyies on one or more mesh(es) specified by its or their name. A time step of a field in MED file could be defined on point and on cell and, or on gauss points and, or on point per element.

This recalled specificities of MED file explains 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.

Meshes in MED files

In MED file meshes could combine in one unstructured mesh cells that have different dimension. For example it is possible to mix MED_TETRA4, MED_TRIA6, MED_SEG2, MED_POINT1, MED_POLYGON, MED_POLYHEDRA in a same mesh. In MEDCouplingUMesh such a mix is not allowed as described here. So to read such mesh it is important to know which meshdimension you are interested to. In API the parameter meshDimRelToMax discreminates the meshdim you are interested to relatively to the maximal dimension of cells contained in the mesh in file.

Let's take 2 examples :

MEDCouplingUMesh *m2D=MEDLoader::ReadUMeshFromFile("","MyMesh",0);

If you are interested in MED_SEG2 and MED_SEG3 you should use :

MEDCouplingUMesh *m1D=MEDLoader::ReadUMeshFromFile("","MyMesh",-1);

The method MEDLoader::ReadUMeshDimFromFile could help you to have this mesh dimension.


To get 3D cells (MED_POLYHEDRA and MED_TETRA4) you should type :

MEDCouplingUMesh *m3D=MEDLoader::ReadUMeshFromFile("","Example2",0);

To get 2D cells (MED_TRI6 and MED_QUAD8) you should type :

MEDCouplingUMesh *m2D=MEDLoader::ReadUMeshFromFile("","Example2",-1);

To get 1D cells (MED_SEG2) you should type :

MEDCouplingUMesh *m1D=MEDLoader::ReadUMeshFromFile("","Example2",-2);

And finally for 0D cells (MED_POINT1) you will write :

MEDCouplingUMesh *m0D=MEDLoader::ReadUMeshFromFile("","Example2",-3);

To finish this subsection, it is important to know that MEDLoader takes into account of the cell numbers stored in a mesh of a med file. This renumbering allows MEDLoader to conserve the order of MEDCoupling cells into the file. So if the renumbering of cells in MED file is not correct an exception will be thrown.

Part of meshes in MED files

A mesh contains one or more families on nodes and/or on cells. A family is a partition (mathematical sense) of the mesh it lies to. A family can be described by an integer field on all nodes and on all cells of a same mesh. All cells and nodes having the same ids defines this family. This id is called the familyId. A family is discriminated by its id. MED file attach a name to its id to be more userfriendly. So by construction, 2 different families could not share anything. The user can retrieve all the families names available on a mesh with the static method MEDLoader::GetMeshFamiliesNames.

A group is a set of families. So groups can overlap each other, contrary to families. Groups are also discriminated by a name. As for families the static method to retrieves the groups of a specified mesh is MEDLoader::GetMeshGroupsNames.

MEDLoader allows you to retrieve the corresponding "part of meshes" thanks to static methods MEDLoader::ReadUMeshFromFamilies and MEDLoader::ReadUMeshFromGroups. This method allows you to combine several families and groups in the same returned mesh.

Reading a field at one time step in MED files

A field at one time step on one mesh, with one entity (cell, node) lies on all mesh on on a part of it. In this last case a definition of a profile is needed. Even if the notions of profile on mesh and group on mesh could appear close, these two concepts are totally disconnected in MED file. The aspect of profile is managed by MEDLoader, thats why this aspect does not appear in the MEDLoader API. So to retrieve a field on 3D cell called "F1Cell" in example file (seen in meshes section) on a mesh "Example2" on time step defined by iteration number 2 and iteration 3 the request will be :

MEDCouplingFieldDouble *f1Cell_3D=MEDLoader::ReadFieldCell("","Example2",0,"F1Cell",2,3);

To retrive the same field (same iteration) on 2D cells only the call will be :

MEDCouplingFieldDouble *f1Cell_2D=MEDLoader::ReadFieldCell("","Example2",-1,"F1Cell",2,3);

Reading several field time steps at a time in MED files

It is possible with MEDLoader to read several time steps of a field at a time. The advantage with this approach is to avoid to read and load several time a same mesh. This is typically recommanded to use the following code when you desire to load all time steps of a field on cell "myField" lying on same mesh "mesh1" in one shot :

std::vector<std::pair<int,int> > timeStepsIds=MEDLoader::GetCellFieldIterations("");
std::vector<MEDCouplingFieldDouble *> fs=MEDLoader::ReadFieldsCellOnSameMesh("","mesh1",0,"myField",timeStepsIds);

Writing a MED file with MEDLoader

As MEDMEM and MED file do, MEDLoader write process separates clearly meshes from fields. The reason is that a common use case in write mode is to write in a first time a mesh and then writes several time steps of a same field in appended mode.

The fact that the write process is rarely in a one shot put a constraint on API (as MEDMEM does) to precise to MEDLoader if you intend to append data to an existing file, or if you want to create a new file from scratch. This explains the presence of boolean parameter writeFromScratch in API of MEDLoader starting with MEDLoader::Write* .

If writeFromScratch parameter is set to true and if the file already exists the file will be crashed and replaced by the new corresponding data. If writeFromScratch parameter is set to false and if the file does not exist the new file is created, but if the file exists MEDLoader will enter in appended mode.

Two classes of MEDLoader write methods exists when writeFromScratch is set to false :

The behaviour of MEDLoader when writeFromScratch is set to false will be precised for each MEDLoader::Write* methods is the next subsections.

Writing one mesh in a MED file with MEDLoader

The first think to know is that MEDLoader is using the meshName in ParaMEDMEM::MEDCouplingMesh instance to put it in MED file.

As explained in previous section here, a mesh in MED file is discriminated by a name, so the meshName should be non empty. If it is the case an INTERP_KERNEL::Exception will be thrown.

To write one mesh myMesh with name "myMeshName" in a MED file "" the following code should be typed :

MEDCouplingUMesh *myMesh=...;

With the previous code, if "" file existed the file is crashed and will contain after the call only the content of myMesh instance.

If you desire to append a mesh in "" you should type :

MEDCouplingUMesh *myMesh=...;

With the previous code, if the "" had already a mesh called "myMeshName" an INTERP_KERNEL::Exception will be thrown.

Writing several meshes in a MED file with MEDLoader

It could be interesting to write several meshes in one shot. Two possiblities are possible :

For these 2 described methods the semantic of writeFromScratch when false is the same, that is to say : no writing (INTERP_KERNEL::Exception thrown) will be done if the file already exists and contains already a mesh with name 'meshName' for MEDLoader::WriteUMeshesPartition method and the name of the first of the vector of unstructured meshes passed as first parameter of MEDLoader::WriteUMeshes.

Writing one time step of a field in a MED file with MEDLoader

To write one time step of a field from scratch with MEDLoader is to use MEDLoader::WriteField method. The behviour of this method depends on the value of the writeFromScratch paramter :

Writing several time steps of a field in a MED file with MEDLoader

To write a serie of time steps in a "" file lying on the same unstructured mesh the typical code to write is the following :

MEDCouplingFieldDouble *f=...;
//Writing first time step with iteration==1 and order==0
//Writing second time step with iteration==2 and order==0

In the previous code, it is important to note that the values of pair (iteration,order) should be different between two calls to avoid that a call to MEDLoader::WriteFieldUsingAlreadyWrittenMesh overwrites a previous call. An another important thing is the fact that f->getMesh() does not be modified. This method of writing presents the big advantage to be fast, because no check neither read is performed by this method. That's why contrary to other MEDLoader::Write* method the parameter of writeFromScratch is not needed here.