/*!
\page MEDLoaderAdvancedAPIPage Advanced MEDLoader API.

[TOC]

This method is much closer to MED file organization than \ref
MEDLoaderBasicAPI "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 contents 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.

\section AdvMEDLoaderBasics Some of basics of advanced API

- Like basic %MEDLoader API there is a notion of \c meshDimRelToMax.
Each time this parameter appears in API, it will have the semantic
explained here.
The value of the parameter \c meshDimRelToMax is at most in {0,-1,-2,-3}. This relative value specifies a level
relative to the value returned by ParaMEDMEM::MEDFileMesh::getMeshDimension().

A mesh containing MED_TETRA4, MED_TRI3, MED_QUAD4 and MED_POINT1 has a meshDimension
equal to 3. For \c 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 \c meshDimRelToMax equal to -1 the user will
deal with cells which dimension equals 3-1 that is to say MED_TRI3
and MED_QUAD4.

An important method is ParaMEDMEM::MEDFileUMesh::getNonEmptyLevels(). 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, no MED_SEG3).

- Besides notion of \c meshDimRelToMax there is notion of \c meshDimRelToMaxExt.
\c meshDimRelToMaxExt is simply an extension of \c meshDimRelToMax for
nodes.

The parameter of \c meshDimRelToMaxExt appears in
\ref ParaMEDMEM::MEDFileUMesh "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. \c 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 \c meshDimRelToMax
before.

- A parameter that also often appears in advanced %MEDLoader API is \c renum.
This parameter is set to \c
true by default.
This parameter indicates if the user intends to take into account
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 \c renum parameter is
set to \c true, then the renumbering is taken into account. This is
exactly the behaviour of \ref MEDLoader::ReadUMeshFromFile "basic MEDLoader API".
If the user expects to ignore this renumbering even in case of
presence of renumbering array, false should be passed to \c renum
parameter. \b The \b parameter \b renum \b should \b be \b set \b with
\b caution \b for \b users \b concerned \b by \b cells \b orders.

- A last important parameter is the \c mode during writing. The
  available values for the parameter \c 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 \c write
  method has been called.
  - 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.

\section AdvMEDLoaderAPIMeshesRW Dealing with Meshes 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 a MEDCoupling mesh user should request this class
instance.

\subsection AdvMEDLoaderAPIMeshReading 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 \c meshName in file \c fileName the
following simple code has to be written :

\code

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

\endcode

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

\code

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

\endcode

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

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

\n

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


- Retrieving a family at a specified level :
  - Either an array of node/cell id
    - \c getFamilyArr method or \c getFamiliesArr
  - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
    - \c getFamily method or \c getFamilies

- Retrieving a group at a specified level :
  - Either an array of node/cell id
    - \c getGroupArr method or \c getGroupsArr
  - Or on \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" form by calling
    - \c getGroup method or \c getGroups

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

- Retrieving renumbering array :
Method \c 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 \b not sorted in
MED file. No sort is stored in MED file explicitly for Groups and
Families. Advanced %MEDLoader API, uses the same order than underlying
mesh at specified level.

\anchor AdvMEDLoaderAPIMeshReadingSampl

\if ENABLE_EXAMPLES
Here is a \ref cpp_mcumesh_loadfile "C++ example" illustrating a typical use of \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" instance.
\endif

\subsection AdvMEDLoaderAPIMeshWriting Writing a mesh.

The use is very symmetric to reading part. It is possible to either
build a \ref ParaMEDMEM::MEDFileUMesh "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
\ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" instance
should be shared by all \ref ParaMEDMEM::MEDCouplingUMesh "MEDCouplingUMesh" used in input parameter of
set* methods. If the user intends to build a \ref ParaMEDMEM::MEDFileUMesh "MEDFileUMesh" instance from
scratch, a call to \c setCoords should be done first.


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

Some differences still exist :

- \c setMeshAtLevel, \c setMeshAtLevelOld simply call \c setMeshAtLevelGen with repectively \c newOrOld parameter
set to true and false. These methods specify if a renumbering computation is needed or not. \c setMeshAtLevelOld is faster
than \c 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 \c setMeshAtLevel method.

- Groups definition : Groups constitution is time consuming because of the store mode chosen by MED file. Groups definition
leads to a partition computation which is time/memory consuming ; that is 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.

\anchor AdvMEDLoaderAPIMeshWritingSampl

\if ENABLE_EXAMPLES
Here is a \ref cpp_mcumesh_writefile "C++ example".
\endif

\section AdvMEDLoaderAPIFieldRW Dealing with Fields with advanced API.

In advanced API fields have been developed using divide and conquer pattern to reproduce with the maximal fidelity the MED file field concept \ref BasicMEDLoaderAPIGen "seen here".

Here the list of classes in %MEDLoader advanced API top down sorted :

- Level 0 : ParaMEDMEM::MEDFileFields
- Level -1 : ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA
- Level -2 : ParaMEDMEM::MEDFileField1TSWithoutSDA
- Level -3 : ParaMEDMEM::MEDFileFieldPerMesh (present only for backward compatibility MED file 2.2)
- Level -4 : ParaMEDMEM::MEDFileFieldPerMeshPerType
- Level -5 : ParaMEDMEM::MEDFileFieldPerMeshPerTypePerDisc


Each level in the tree representing a field (cyan box) is represented by a class. The only difference is that values are grouped in a single big array located
in level -2 (ParaMEDMEM::MEDFileField1TSWithoutSDA)  in which each leaf (level -5) of MED file field
points to range [\a start, \a end).

As different time steps of a same field and different fields inside a MED file can share or not profiles (yellow box) and localization (red box) a manipulable field classes instance
(ParaMEDMEM::MEDFileField1TS and ParaMEDMEM::MEDFileFieldMultiTS) in advanced API is the result of a subclass of a data class
(respectively ParaMEDMEM::MEDFileField1TSWithoutSDA, ParaMEDMEM::MEDFileFieldMultiTSWithoutSDA) and an instance of ParaMEDMEM::MEDFileFieldGlobsReal representing the shared data arrays (SDA)
at a specified scope inside the MED file.

\subsection AdvMEDLoaderAPIFieldR Reading a field

\subsubsection AdvMEDLoaderAPIFieldRC Reading a field defined on all entities

Fields defined on all entities are the most used and common fields in MED file world.

In this mode the user does **not** want to retrieve the entity ids of the constituting subsupport of the whole mesh because it has no sense.

\if ENABLE_EXAMPLES
Here is a \ref py_mcfield_loadfile_allentities "Python example".
\endif

\subsubsection AdvMEDLoaderAPIFieldRP Reading a partial field

\if ENABLE_EXAMPLES
Here is a \ref py_mcfield_loadfile_partial "Python example".
\endif

\subsection AdvMEDLoaderAPIFieldW Writing a field

\subsubsection AdvMEDLoaderAPIFieldWC Writing a field defined on all entities

Fields defined on all entities are the most used and common fields in MED file world.

In this mode the user do **not** want to retrieve the entity ids of the constituting subsupport of the whole mesh because it has no sense.

\if ENABLE_EXAMPLES
Here is a \ref py_mcfield_writefile_allentities "Python example".
\endif

\subsubsection AdvMEDLoaderAPIFieldWP Writing a partial field

\if ENABLE_EXAMPLES
Here is a \ref py_mcfield_writefile_partial "Python example".
\endif

*/