--- /dev/null
+#FIG 3.2 Produced by xfig version 3.2.5b
+Landscape
+Center
+Inches
+Letter
+110.00
+Single
+-2
+1200 2
+6 675 675 3075 4650
+2 2 0 1 0 2 50 -1 30 0.000 0 0 -1 0 0 5
+ 675 675 3075 675 3075 4650 675 4650 675 675
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+ 675 1275 3075 1275
+4 0 0 50 -1 0 16 0.0000 4 225 975 900 1650 (1) name\001
+4 0 0 50 -1 0 16 0.0000 4 225 1635 900 1950 (1) coordinates\001
+4 0 0 50 -1 0 16 0.0000 4 225 1185 1275 2250 (?) fam ids\001
+4 0 0 50 -1 0 16 0.0000 4 225 1305 1275 2550 (?) numbers\001
+4 0 0 50 -1 0 16 0.0000 4 240 2010 900 2850 (*) geometric type\001
+4 0 0 50 -1 0 16 0.0000 4 240 1725 1275 3150 (1) connectivity\001
+4 0 0 50 -1 0 16 0.0000 4 225 1200 1275 3450 (1) fam ids\001
+4 0 0 50 -1 0 16 0.0000 4 225 1320 1275 3750 (1) numbers\001
+4 0 0 50 -1 0 16 0.0000 4 225 1275 900 4050 (+) families\001
+4 0 0 50 -1 0 16 0.0000 4 240 1125 900 4350 (*) groups\001
+4 0 0 50 -1 14 24 0.0000 4 240 960 1425 1125 MESH\001
+-6
+6 9450 675 11625 2100
+2 2 0 1 0 6 50 -1 30 0.000 0 0 -1 0 0 5
+ 9450 675 11625 675 11625 2100 9450 2100 9450 675
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+ 9450 1200 11625 1200
+4 0 0 50 -1 0 16 0.0000 4 225 975 9825 1650 (1) name\001
+4 0 0 50 -1 0 16 0.0000 4 225 705 9825 1950 (1) ids\001
+4 0 0 50 -1 14 24 0.0000 4 240 1680 9750 1050 PROFILE\001
+-6
+6 9450 2550 12525 4875
+2 2 0 1 0 29 50 -1 28 0.000 0 0 -1 0 0 5
+ 9450 2550 12525 2550 12525 4875 9450 4875 9450 2550
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+ 9450 3150 12525 3150
+4 0 0 50 -1 0 16 0.0000 4 225 975 9825 3525 (1) name\001
+4 0 0 50 -1 0 16 0.0000 4 225 1515 9825 3825 (1) dimension\001
+4 0 0 50 -1 0 16 0.0000 4 240 2250 9825 4125 (1) number of points\001
+4 0 0 50 -1 0 16 0.0000 4 225 1860 9825 4425 (1) reference cell\001
+4 0 0 50 -1 0 16 0.0000 4 240 1230 9825 4725 (1) weights\001
+4 0 0 50 -1 14 24 0.0000 4 240 2880 9525 2925 LOCALIZATION\001
+-6
+6 4425 675 8025 6000
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+ 4425 1200 8025 1200
+2 2 0 1 0 3 50 -1 30 0.000 0 0 -1 0 0 5
+ 4425 675 8025 675 8025 6000 4425 6000 4425 675
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+ 4425 1275 8025 1275
+4 0 0 50 -1 0 16 0.0000 4 225 975 4650 1650 (1) name\001
+4 0 0 50 -1 0 16 0.0000 4 240 2250 5025 2550 (1) component name\001
+4 0 0 50 -1 0 16 0.0000 4 225 1470 5025 2850 (1) unit name\001
+4 0 0 50 -1 0 16 0.0000 4 240 1485 4650 3150 (*) time steps\001
+4 0 0 50 -1 0 16 0.0000 4 225 1290 5025 3450 (1) iteration\001
+4 0 0 50 -1 0 16 0.0000 4 225 960 5025 3750 (1) order\001
+4 0 0 50 -1 0 16 0.0000 4 225 870 5025 4050 (1) time\001
+4 0 0 50 -1 0 16 0.0000 4 240 2430 5025 4350 (*) per geometric type\001
+4 0 0 50 -1 0 16 0.0000 4 240 2010 5325 4650 (1) geometric type\001
+4 0 0 50 -1 0 16 0.0000 4 240 2280 5325 4950 (+) per discretization\001
+4 0 0 50 -1 0 16 0.0000 4 225 1080 5700 5250 (1) values\001
+4 0 0 50 -1 14 24 0.0000 4 240 1200 5550 1125 FIELD\001
+4 0 0 50 -1 0 16 0.0000 4 240 2565 4650 2250 (+) info on components\001
+4 0 2 10 -1 0 16 0.0000 4 225 1620 4650 1950 (1) mesh name\001
+4 0 6 10 -1 0 16 0.0000 4 240 1755 5700 5550 (?) profile name\001
+4 0 29 10 -1 0 16 0.0000 4 225 2295 5700 5850 (?) localization name\001
+-6
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 1
+ 8850 4200
+2 1 0 4 4 7 50 -1 -1 0.000 0 0 -1 1 1 4
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 4500 1875 3825 1875 3825 1575 2025 1575
+2 1 0 4 4 7 50 -1 -1 0.000 0 0 -1 1 1 4
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 9675 1575 8550 1575 8550 5475 7575 5475
+2 1 0 4 4 7 50 -1 -1 0.000 0 0 -1 1 1 4
+ 1 1 2.00 120.00 120.00
+ 1 1 2.00 120.00 120.00
+ 9825 3450 9000 3450 9000 5775 8025 5775
/*!
\page medloader MEDLoader
+[TOC]
+
\section MEDLoaderIntro Introduction
-%MEDLoader is a package in charge of loading from a file or write to a file
+\ref medloader "MEDLoader" is a package in charge of loading from a file or write to a file
in MED format a \ref medcoupling data structure. The fact that these
functionalities are not merged in \ref medcoupling is explained by a
willingness of reducing as much as possible the dependancies of \ref medcoupling libraries.
As a MED file can combine several \ref medcoupling aspects in one (for exemple meshes in
MED file on different mesh dimension with families and groups) the API
-of %MEDLoader is much more rich than simply read and write.
+of \ref medloader "MEDLoader" is much more rich than simply read and write.
+
+\ref MEDCouplingMeshesPage "MEDCoupling mesh" is \b not as rich as a MED file mesh, and a \ref MEDCouplingFieldsPage "MEDCoupling field" is \b not as rich as a MED file field.
+But it is possible to emulate with a very good fidelity a MED file mesh and a MED file field with a collection of MEDCoupling instances for each.
+
+\section MEDLoader2Approaches Two approaches are available in MEDLoader : Advanced API, Basic API
+
+\ref medloader "MEDLoader" module offers two different approaches to perform Read/Write from/to MED file.
+
+- \ref MEDLoaderAdvApproach "advanced API approach"
+- \ref MEDLoaderBasicApproach "basic API apprach"
+
+Whatever the approach(es) you choose, it is advisable to know main concepts of MED files \ref MEDLoaderMainC "that are quickly reminded here."
+
+\subsection MEDLoaderAdvApproach Advanced API approach
+
+\subpage MEDLoaderAdvancedAPIPage "A specific page dedicated to the advanced API is available here".
+
+This approach is the most close to MED file. By using this advanced API approach the user will manipulates classes that represents MED file concepts.
+
+It implies that the user should be informed about the \ref MEDLoaderMainC "MED file concepts", that do not exist in \ref medcoupling "MEDCoupling". For example :
+
+- group/family in meshes
+- profiles in fields
+
+This is typically the case for a user that wants to precisely set/get mesh/group/family groups set on different level.
+
+*That's why a set of classes representing a memory representation of MED file concepts are proposed by advanced API approach.*
+
+*So All information contained in file is represented in advanced API class instances.*
+
+The level of coherency check is variable across methods, to let to the user the maximal capacity of modification of its MED file data in memory.
+
+This API is particulary recommended :
+
+1. For users that want to repare a MED file (invalid family ids, invalid mesh dimension, mismatch of family ids, numbering cells/nodes array modification)
+2. For users that want to operate directly on complex MED file objects (split of MED files for example, duplication of nodes).
+
+\subsection MEDLoaderBasicApproach Basic API approach
+
+\subpage MEDLoaderBasicAPIPage "A specific page dedicated to the basic API is available here".
+
+This approach is less close to MED file concepts, but closer to \ref MEDCouplingMainConc "MEDCoupling concepts".
+
+So, basic API, is simpler as show method MEDLoader::WriteUMesh that needs no special knowledge needed of MED file concepts to interact with MED files.
+
+This API is in the form of a list of public static methods a class ParaMEDMEM::MEDLoader.
+
+This simplicity has a cost, the I/O are not (cannot be) optimized.
+
+As MED file concepts are more complex than MEDCoupling concepts, this approach is not the most relevant for specific MED file objects read/write.
+
+- Manipulation of multi level MED file mesh is not easy to manipulate with basic approach
+
+- Manipulation of partial fields in not easy to manipulate too with basic approach
+
+
+\subsection MEDLoaderCohabitationApproach Cohabitation of the two approaches
+
+The two approaches are \b NOT opposed, they are compatible each other so it is possible to mix them.
+
+Typically it it is possible to read rich information of a complex MED file using advanced API in read mode, and write a simpler MED file model
+coming from a post treatement of the complex input MED file data to a simple output MED file using basic API for writing.
+
+\section MEDLoaderMainC 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 \ref medloader "MEDLoader API".
+
+\subsection BasicMEDLoaderAPIGen Basics in MED files
+
+First of all **MEDLoader will not read MED files whose version is strictly lower than 2.2.**
+
+For new comers in MED file world some of basics principles are recalled in the following graphic :
+
+\image html MEDFileConcepts.png "Resumed MED file concepts"
-MEDCoupling mesh does \b not fit a MED file mesh, and a MEDCoupling
-field does \b not fit a MED file field. But it is possible to emulate
-with a very good fidelity a MED file mesh and a MED file field with
-a collection of MEDCoupling instances for each.
+Inside the parenthesis, there is multiplicity :
-That's why %MEDLoader module offers two different approaches to perform Read/Write from/to MED
-file.
+- + stands for [1,inf)
+- * stands for [0,inf)
+- ? stands for 0 or 1
-- Either the user is close too MEDCoupling concepts. This is the case
-if pieces of information to access or to write are \b directly
-mapped to a MEDCouplingMesh/MEDCouplingFieldDouble in MEDCoupling package. \nIn this case, the \ref MEDLoaderBasicAPI "basic API" is recommended in this case because simpler and faster.
+Each box are **independant in MED file format during read write session.**
-- Or the user knows the MED file concept well and if nature of
-information to deal with do not fit exactly the class offered by
-MEDCoupling, the \ref MEDLoaderAdvancedAPI "advanced API" is
-recommended. This is typically the case for a user that wants to precisely set/get
-mesh/group/family groups set on different level lying on a same field defined
-partially... This API is faster, all information contained in file is represented, but
-less check is performed.\n This API is recommended for users that want to operate directly on MED files (split of MED files for example)
+**Boxes instances are linked each other only by red arrows using string as discriminating key.** It implies that empty names in basic concepts objects of MED file are forbidden.
-The two methods are \b not opposed, they are compatible each other so
-it is possible to mix them. But the user should keep in mind that
-behaviour of these two methods can vary.
+There can be as many instance of boxes as wanted in a MED file.
+
+**As it can be seen in MED file world, fields and meshes are sorted by geometric type**.
+
+This specificity leads to a constraint during writing phase because some mesh operations may modify significantly the organization of geometric types during mesh/field operations.
+\n Here some of operation that can alter the geometric type order of cells :
+
+- aggregation of meshes
+- aggregation of fields
+- extraction of a part of meshes
+- extraction of a part of fields
+- partial polyhedrization of meshes
+- unpolyhedronization of meshes
+
+\section MEDLoaderCommonVoc Vocabulary used in MEDLoader
+
+\subsection Relative mesh dimension
+
+As it has been seen \ref BasicMEDLoaderAPIGen "above", all big arrays in fields and meshes (execpted coordinates) are sorted by geometric type, without any awareness of the dimension.
+
+For example an unstructured mesh in MED file world can lie simultaneously on MED_TRI3, MED_POINT1, MED_POLYHED, MED_TETRA4..., \ref MEDCouplingMeshes "which is impossible in MEDCoupling" for manipulation reasons.
+
+To connect the MED file world to the MEDLoader/MEDCoupling world the notion of **relative mesh dimension** has been introduced in \ref medloader "MEDLoader".
+
+This concept of **relative mesh dimension** is used frequently in the \ref medloader "MEDLoader both APIs" ( \ref MEDLoaderBasicAPIPage "basic" and \ref MEDLoaderAdvancedAPIPage "advanced").
+
+To explain the semantic of **relative mesh dimension** let's take the example of a mesh called \a myMesh in a MED file, containing MED_TRI3, MED_POINT1, MED_POLYHED, MED_TETRA4.
+
+For each geometric type on which \a myMesh is defined the mesh dimension are :
+
+- MED_TRI3 -> mesh dimension=2
+- MED_POINT1 -> mesh dimension=0
+- MED_POLYHED -> mesh dimension=3
+- MED_TETRA4 -> mesh dimension=3
+
+The mesh dimension of \a myMesh is equal to 3 ( \f max(2,0,3,3) ). The **relative mesh dimension** is equal to the difference between mesh dimension of geometic type and the mesh dimension
+of the whole MED file dimension. It leads to the following **relative mesh dimension** :
+
+- MED_TRI3 -> **relative mesh dimension** = -1
+- MED_POINT1 -> **relative mesh dimension** = -3
+- MED_POLYHED -> **relative mesh dimension** = 0
+- MED_TETRA4 -> **relative mesh dimension** = 0
+
+In \ref medloader **MEDLoader** all geometric information are then grouped relative dimension per relative dimension. It leads to the following geometric sorting of
+MED file data structure of \a myMesh :
+
+- Level 0
+ - MED_TETRA4
+ - MED_POLYHED
+- Level -1
+ - MED_TRI3
+- Level -2
+ - nothing -> level **not** available for \a myMesh
+- Level -3
+ - MED_POINT1
+
+The mesh dimension of \a myMesh is 3. The relative mesh dimension available are [0,-1,-3].
*/
/*!
-\page MEDLoaderBasicAPI Basic MEDLoader API.
+\page MEDLoaderBasicAPIPage Basic MEDLoader API.
+
+[TOC]
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
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
+ 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 \ref ParaMEDMEM::MEDCouplingTimeDiscretization
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.
-\section MEDLoaderMainC 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.
-
-\subsection BasicMEDLoaderAPIGen Basics in MED files
-
-First of all MEDLoader \b will \b not read MED files whose version is
-\b lower \b than \b 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.
-\anchor MEDLoaderMeshNameConstraint 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.
+\section BasicMEDLoaderBasicAPIGlobalInfo Retrieving tiny global information from MED files using basic API
+The MEDLoader::CheckFileForRead method will perform the check of that before any attempt of read.
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 time step of a field lyies on one \b or \b more mesh(es) specified by its \b or \b their name. A time step of a field in
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.
-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.
+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.
-\subsection BasicMEDLoaderAPIMesh Meshes in MED files
+Let's recall basic principles that explains some of the aspect of MEDLoade API.
+\anchor MEDLoaderMeshNameConstraint 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.
+
+\section BasicMEDLoaderBasicAPIMesh 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
*/
/*!
-\page MEDLoaderAdvancedAPI Advanced %MEDLoader API.
+\page MEDLoaderAdvancedAPIPage Advanced %MEDLoader API.
+
+[TOC]
This method is much closer to MED file organization than \ref
MEDLoaderBasicAPI "basic MEDLoader API". All MED file
