Basic MEDLoader API

Table of Contents

• Retrieving tiny global information from MED files using basic API
• Reading and writing meshes in MED files using basic API
  • Part of meshes in MED files
  • Reading a field at one time step in MED files
  • Reading several field time steps at a time in MED files
• Writing a MED file with MEDLoader
  • Writing one mesh in a MED file with MEDLoader
  • Writing several meshes in a MED file with MEDLoader
  • Writing one time step of a field in a MED file with MEDLoader
  • Writing several time steps of a field in a MED file with MEDLoader

The aim of this page is to present MEDLoader basic API. 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 functions whose names have the first character in capital. You are intended to use these functions. The following chapters will try to describe in details some of important ones.

The basic idea of MEDLoader is to exploit 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 MEDCoupling::DataArrayDouble instances are stored into components and units into MED files. The name of meshes and fields are used by MEDLoader as is into MED file. From a field f with time discretization set to ONE_TIME, calls to 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 is limited. That's why the user should be aware of these constraints 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.

Retrieving tiny global information from MED files using basic API

The MEDCoupling::CheckFileForRead function will perform such a check before any attempt of read. A field is also discriminated by its name. The functions MEDCoupling::GetCellFieldNamesOnMesh and MEDCoupling::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 ints (iteration,order). It is not possible to store 2 time steps of a same field having the same iteration and order numbers. The floating point value attached to this couple of ids (iteration,order) is only present for information. Static functions MEDCoupling::GetCellFieldIterations and MEDCoupling::GetNodeFieldIterations return a vector of pairs (iteration, order).

A field time step lies on one or more mesh(es) specified by its or their name(s). A field time step 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 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.

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 name). In the same way a MED file can contain several fields. So MEDLoader offers the MEDCoupling::GetMeshNames function to discover all the mesh names contained in your file.

Reading and writing meshes in MED files using basic API

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 mesh dimension you are interested in. The parameter meshDimRelToMax of function MEDCoupling::ReadUMeshFromFile corresponds to the mesh dimension you are interested in, expressed relatively to the maximal dimension of cells contained in the mesh in file.

Let's take 2 examples :

• If you have a mesh called "MyMesh" in file "file1.med" with MED_POLYGON, MED_TRI3, MED_SEG2 and MED_SEG3 : The max dimension of cells is 2 (for MED_POLYGON and MED_TRI3). So if you want exclusively cells with type MED_POLYGON and MED_TRI3 you should use :

        m2D=ReadUMeshFromFile("file1.med","MyMesh",0)

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

        m1D=ReadUMeshFromFile("file1.med","MyMesh",-1)

The function MEDCoupling::ReadUMeshDimFromFile could help you to have this mesh dimension.

Here is a Python example.

To finish this subsection, it is important to know that MEDLoader takes into account 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 on. A family can be described by an integer value on all nodes and on all cells of a same mesh. All cells and nodes having the same id define this family. This id is called the familyId. A family is discriminated by its id. MED file attaches a name to its id to be more user friendly. 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 function MEDCoupling::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 function to retrieve the groups of a specified mesh is MEDCoupling::GetMeshGroupsNames.

MEDLoader allows you to retrieve the corresponding "part of meshes" thanks to static functions MEDCoupling::ReadUMeshFromFamilies and MEDCoupling::ReadUMeshFromGroups. These functions allow 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 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, that is why this aspect does not appear in the MEDLoader API.

Here is a Python example.

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 once. The advantage with this approach is to avoid reading and loading the same mesh several times.

Here is a Python example.

Writing a MED file with MEDLoader

As MED file does, MEDLoader write process clearly separates 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 to write several time steps of a same field in appended mode.

The fact that the write process is rarely in a one shot puts a constraint on API 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 MEDCoupling::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 functions exist when writeFromScratch is set to false :

• Functions MEDCoupling::Write*Dep : The write operation is performed without any question in file. The responsibility is let to the user because the MED file could be corrupted. The advantage of this function is that it is faster because no check is done.
• Functions MEDCoupling::Write* : MEDLoader will not corrupt your file by always trying to append data. The consequence is that a read of part (and data processing) of MED file could be needed before any attempt of writing. So these functions could be in some cases much time and memory consuming.

The behaviour of MEDLoader when writeFromScratch is set to false will be precised for each MEDCoupling::Write* functions 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 MEDCoupling::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.

Here is a Python example.

Writing several meshes in a MED file with MEDLoader

It could be interesting to write several meshes in one shot. Two possibilities:

• Write several instances of MEDCoupling::MEDCouplingUMesh lying on same coords with different mesh dimensions. In this case MEDCoupling::WriteUMeshes is the function you should use. Typically this function should be used to write files such as defined here. This function first checks that all instances share the same MEDCoupling::DataArrayDouble instance as coords. If not an INTERP_KERNEL::Exception will be thrown and an invocation on MEDCoupling::MEDCouplingPointSet::tryToShareSameCoords will be necessary.

• Write a partition of meshes having same mesh dimension, that is to say a set of groups and families from given meshes. As in the previous case the check of same coords will be done (if not an INTERP_KERNEL::Exception is thrown). After this step this function will merge input (preserving order) and will simplify the merged mesh. After this operation, the groups will be constituted by assigning the group names with the corresponding names of 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 MEDCoupling::WriteUMeshesPartition.

For these 2 described functions 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 a mesh with name 'meshName' for MEDCoupling::WriteUMeshesPartition function and the name of first element of unstructured mesh vector passed as first parameter of MEDCoupling::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 use MEDCoupling::WriteField function. The behaviour of this function depends on the value of the writeFromScratch parameter :

• When writeFromScratch equals to true, this function performs two things, it writes the underlying mesh and writes the specified time step on it.

• When writeFromScatch equals to false, this function checks that the underlying mesh exists (by looking to the contents of field->getMesh()->getName()) in file. If not, the behaviour is the same that previous case with writeFromScratch parameter set to true. If the mesh already exists, MEDLoader reads the field and tries to apply field on it. This operation could be rather time consuming because a read operation is performed and a reorder operation too. If the file already contains the same field at the same time step (iteration and order ids) the corresponding time step will be replaced by the field passed in parameter.

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

Here is a Python example.