Advanced MEDLoader API.

This method is much closer to MED file organization than basic MEDLoader API. All MED file concepts are exposed to the user. As a consequence, this advanced API is lead to change with MED file data model enhancement.

In reading mode, the user can scan entirely and directly the content of its MED file as it is organized in its MED file. Inversely, in writing mode, the user can describe its data in the same way that MED file does.

Some of basic parameters appearing in advanced API

• Like basic MEDLoader API there is a notion of meshDimRelToMax. Each time This parameter appears in API, it will have the semantic explain here. The value of the parameter meshDimRelToMax is at most in {0,-1,-2,-3}. This relative value specifies a level relative to value returned by myMedMesh->getMeshDimension().

A mesh containing MED_TETRA4, MED_TRI3, MED_QUAD4 and MED_POINT1 has a meshDimension equal to 3. For meshDimRelToMax equal to 0 the user will deal with cells whose type has a dimension equal to 3+0, that is to say here MED_TETRA4. For meshDimRelToMax equal to -1 the user will deal with cells witch dimension equal to 3-1 that is to say MED_TRI3 and MED_QUAD4.

An important method is getNonEmptyLevels() method. It returns all non empty levels available. In the previous example, this method will return {0,-1,-3}. -2 does not appear because no cells with dimension equal to 1 (3-2) appear in MED file mesh (no MED_SEG2 not MED_SEG3).

• Besides notion of meshDimRelToMax there is notion of meshDimRelToMaxExt. meshDimRelToMaxExt is simply an extension of meshDimRelToMax for nodes.

The parameter of meshDimRelToMaxExt appears in umesh advanced API of MEDLoader with the following semantics.

Some of MED file concepts are available both for cells and nodes, (for example families, groups, numbering ) that's why for a simpler API this concept has been introduced. meshDimRelToMaxExt parameter can take a value in at most {1,0,-1,-2,-3}. 1 stands for node and 0,-1,-2,-3 has exactly the same semantic than those described in meshDimRelToMax decribed before.

• A parameter that also often appears in advanced MEDLoader API is renum. This parameter by default in advanced MEDLoader API is set to true. This parameter indicates if the user intend to take into account of the renumbering array of cells of the current MED file mesh. If no renumbering array is defined, this parameter is ignored by MEDLoader.

If such renumbering exists and the renum parameter is set to true, then the renumbering is taken into account. This is exactly the behaviour of basic MEDLoader API. If the user expects to ignore this renumbering even in case of presence of renumbering array, false should be passed to renum parameter. The parameter renum should be set with cauton for users concerned by cells orders.

• A laster important parameter is the mode during writing. The available values for the parameter mode are :
  • 2 : for a write from scratch. If file already exists, file will be erased and replace by the content of the instance on which write method has been calles.
  • 1 : If the file does not exists equivalent to 2. If file already exists, the write is done on APPEND mode. That is to say that no data loss will occur. But in case that an element with same ids than current instance already exists, the content is not written and an exception is thrown.
  • 0 : If the file does not exists equivalent to 2. If file already exists write without any question. If an element with same ids existed previously the content is overwritten by the content of the current instance, that can lead to a file corruption.

Reading from a file with advanced API.

Contrary to the basic MEDLoader API, here after reading process, the user has to deal with a new instance of class that fits the MED file model. To access to a MEDCoupling mesh the user should request this class instance.

Reading a mesh.

The class that incarnates Read/Write mesh in MED file is ParaMEDMEM::MEDFileUMesh.

First of all, like basic MEDLoader API, only MEDfile files whose version >= 2.2 are able to be read with advanced API.

To read a mesh having the name meshName in file fileName the following simple code has to be written :

MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName,meshName);

If the user do not know the name of the mesh inside MED file 'fileName' the following code should be written :

MEDFileUMesh *myMedMesh=MEDFileUMesh::New(fileName);

In this case the first mesh (in MED file sense) found in fileName file will be loaded.

Now the user can ask for mesh dimension of of myMedMesh instance by calling myMedMesh->getMeshDimension(). This method returns the highest level of present cell in MED file mesh myMedMesh. This returned integer is computed and not those contained in MED file that can be invalid.

• Retrieving a mesh at a specified relative level meshDimRelToMax=mdrm : simply call
  • myMedMesh->getMeshAtLevel(mdrm)
  • or myMedMesh->getLevel0Mesh() or myMedMesh->getLevelM1Mesh(), or myMedMesh->getLevelM2Mesh() depending on the value of mdrm

• Retrieving a family at a specified level :
  • Either an array of node/cell id
    • getFamilyArr method or getFamiliesArr
  • Or on MEDCouplingUMesh form by calling
    • getFamily method or getFamilies

• Retrieving a group at a specified level :
  • Either an array of node/cell id
    • getGroupArr method or getGroupsArr
  • Or on MEDCouplingUMesh form by calling
    • getGroup method or getGroups

• Retrieving family field array : Method getFamilyFieldAtLevel retrieves for a specified extended level the family id of each cell or node.

• Retrieving renumbering array : Method getNumberFieldAtLevel returns, if it exists for a specified extended level, the family id of each cell or node. If it does not exist an exception will be thrown.

An important point is that families and groups are not sorted in MED file. No sort is stored in MED file explicitely for Groups and Families. Advanced MEDLoader API, uses the same order than underlying mesh at specified level.

Sample of reading a mesh.

Here a typical use of MEDCouplingUMesh instance.

const char fileName[]=...;
const char meshName[]=...;
MEDFileUMesh *medmesh=MEDFileUMesh::New(fileName,meshName);
std::vector<int> nel=medmesh->getNonEmptyLevels();
if(nel.size()<1)
  throw INTERP_KERNEL::Exception("The test is not good for my file ! Expecting a multi level mesh to play with !");
MEDCouplingUMesh *m0=medmesh->getMeshAtLevel(nel[1],false);
MEDCouplingUMesh *g1=medmesh->getGroup(nel[1],"mesh2",false);
DataArrayInt *dag1=medmesh->getGroupArr(nel[1],"mesh2",false);
MEDCouplingUMesh *g1bis=m0->buildPartOfMySelf(dag1->getConstPointer(),dag1->getConstPointer()+dag1->getNbOfElems());
g1bis->setName(dag1->getName());
if(!g1->isEqual(g1bis,1e-12))
  throw INTERP_KERNEL::Exception("hmmmm :g1 and g1bis should be equal...");
//
dag1->decrRef();
g1->decrRef();
m0->decrRef();
medmesh->decrRef();

Writing a mesh.

The use is very symetric to reading part. It is possible to either build a MEDFileUMesh instance from scratch, or to work with an existing instance coming from a loading from a file.

One important point is that coordinates of a mesh are shared by all cells whatever their level. That's why the DataArrayDouble instance should be shared by all MEDCouplingUMesh used in input parameter of set* methods. If the user intend to build a MEDFileUMesh instance from scratch, a call to setCoords should be done first.

Generally speaking traduce get* methods with set* methods have corresponding write semantic.

Some differences still exist :

• setMeshAtLevel, setMeshAtLevelOld simply call setMeshAtLevelGen with repectively newOrOld parameter set to true and false. These method specifies if a renumbering computation is needed or not. setMeshAtLevelOld is faster than setMeshAtLevel because no renumbering computation is done. If the user is not warranty about the order of its meshes to enter it is better to use setMeshAtLevel method.

• Groups definition : Groups constitution is time consuming because of the stored mode chosen by MED file to store them. Groups definition lead to a partition computation which is time/mem consuming that's why groups should be defined at once and not with addGroup one by one that will lead to compute a partition for each appended group. One important point to note is that DataArrayInt instance given in input to define groups should have its name set to the desired group name. If not an exception will be thrown, because MED file does not support groups with no name.

Sample of writing a mesh.

MEDCouplingUMesh *m=...; //m is a mesh with meshDim=2 spaceDim=2
MEDCouplingUMesh *m1=...; //m1 is a mesh with meshDim=1 spaceDim=2 same coords than m
MEDCouplingUMesh *m2=...; //m2 is a mesh with meshDim=0 spaceDim=2 same coords than m
MEDFileUMesh *mm=MEDFileUMesh::New();
mm->setName("mm");//name needed to be non empty
mm->setDescription("Description mm");
mm->setCoords(m1->getCoords());
mm->setMeshAtLevel(-1,m1,false);
mm->setMeshAtLevel(0,m,false);
mm->setMeshAtLevel(-2,m2,false);
DataArrayInt *g1=DataArrayInt::New();
g1->alloc(2,1);
g1->setName("G1");
const int val1[2]={1,3};
std::copy(val1,val1+2,g1->getPointer());
DataArrayInt *g2=DataArrayInt::New();
g2->alloc(3,1);
g2->setName("G2");
const int val2[3]={1,2,3};
std::copy(val2,val2+3,g2->getPointer());
//
std::vector<const DataArrayInt *> grps(2);
grps[0]=g1; grps[1]=g2;
mm->setGroupsAtLevel(0,grps,false);
//
g2->decrRef();
g1->decrRef();
//
mm->write(2);