]> SALOME platform Git repositories - modules/med.git/commitdiff
Salome HOME
Translate GUI user guide to english
authoraguerre <aguerre>
Tue, 19 Nov 2013 12:35:22 +0000 (12:35 +0000)
committeraguerre <aguerre>
Tue, 19 Nov 2013 12:35:22 +0000 (12:35 +0000)
22 files changed:
src/MEDOP/doc/sphinx/_static/documents/xmed-develguide.pdf [new file with mode: 0644]
src/MEDOP/doc/sphinx/_static/documents/xmed-specifications.pdf [new file with mode: 0644]
src/MEDOP/doc/sphinx/_static/documents/xmed-userguide.pdf [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/images/xmed-gui-withframe.png [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/images/xmed-gui.png [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/index.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-definitions.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-develguide.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-prototype-develguide.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-prototype-medmem.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-prototype-overview.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-references.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-specifications.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-userguide-gui.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-workingnotes-2010.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-workingnotes-2011.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/fr/medop-workingnotes-2012.rst [new file with mode: 0644]
src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png
src/MEDOP/doc/sphinx/index.rst
src/MEDOP/doc/sphinx/medop-definitions.rst
src/MEDOP/doc/sphinx/medop-references.rst
src/MEDOP/doc/sphinx/medop-userguide-gui.rst

diff --git a/src/MEDOP/doc/sphinx/_static/documents/xmed-develguide.pdf b/src/MEDOP/doc/sphinx/_static/documents/xmed-develguide.pdf
new file mode 100644 (file)
index 0000000..fad08c8
Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/xmed-develguide.pdf differ
diff --git a/src/MEDOP/doc/sphinx/_static/documents/xmed-specifications.pdf b/src/MEDOP/doc/sphinx/_static/documents/xmed-specifications.pdf
new file mode 100644 (file)
index 0000000..7696873
Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/xmed-specifications.pdf differ
diff --git a/src/MEDOP/doc/sphinx/_static/documents/xmed-userguide.pdf b/src/MEDOP/doc/sphinx/_static/documents/xmed-userguide.pdf
new file mode 100644 (file)
index 0000000..7fd7eab
Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/xmed-userguide.pdf differ
diff --git a/src/MEDOP/doc/sphinx/fr/images/xmed-gui-withframe.png b/src/MEDOP/doc/sphinx/fr/images/xmed-gui-withframe.png
new file mode 100644 (file)
index 0000000..532c285
Binary files /dev/null and b/src/MEDOP/doc/sphinx/fr/images/xmed-gui-withframe.png differ
diff --git a/src/MEDOP/doc/sphinx/fr/images/xmed-gui.png b/src/MEDOP/doc/sphinx/fr/images/xmed-gui.png
new file mode 100644 (file)
index 0000000..0c91683
Binary files /dev/null and b/src/MEDOP/doc/sphinx/fr/images/xmed-gui.png differ
diff --git a/src/MEDOP/doc/sphinx/fr/index.rst b/src/MEDOP/doc/sphinx/fr/index.rst
new file mode 100644 (file)
index 0000000..cf3fa4b
--- /dev/null
@@ -0,0 +1,60 @@
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ Documentation du module MED
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Le module SALOME MED (pour Modèle d'Echange de Données) fournit la
+bibliothèque MEDCoupling (bibliothèque C++ dédiée à la manipulation de
+maillages et de champs conformes au modèle MED), ainsi qu'une
+interface graphique pour la réalisation des opérations de manipulation
+les plus usuelles.
+
+Documentation de référence
+==========================
+
+**Documentation d'utilisation**
+
+.. toctree::
+   :maxdepth: 1
+
+   medop-userguide-gui.rst
+   medop-userguide-api.rst
+
+**Documentation technique**
+
+.. toctree::
+   :maxdepth: 1
+
+   medop-specifications.rst
+   medop-develguide.rst
+
+**Documentation annexe**
+
+.. toctree::
+   :maxdepth: 1
+
+   medop-references.rst
+
+Archives documentaires
+======================
+
+**Documentation du prototype 2010**
+
+Cette section décrit le prototype mis au point en 2010 pour les
+analyses de conception (maquette 2010 sur base MEDMEM)
+
+.. toctree::
+   :maxdepth: 1
+
+   medop-prototype-overview.rst
+   medop-prototype-develguide.rst
+   medop-prototype-medmem.rst
+
+**Journal de travail**
+
+.. toctree::
+   :maxdepth: 1
+
+   medop-workingnotes-2010.rst
+   medop-workingnotes-2011.rst
+   medop-workingnotes-2012.rst
diff --git a/src/MEDOP/doc/sphinx/fr/medop-definitions.rst b/src/MEDOP/doc/sphinx/fr/medop-definitions.rst
new file mode 100644 (file)
index 0000000..0cb67b4
--- /dev/null
@@ -0,0 +1,123 @@
+.. AVERTISSEMENT:
+.. Ce fichier contient les définitions globales à la documentation. Il
+.. peut être inclu au moyen de la directive rst "include" pour
+.. disposer des définitions dans le fichier qui fait l'inclusion.
+.. Pour éviter de polluer les textes dans lequel ce fichier est inclu,
+.. il est interdit de faire afficher du texte par ce document de
+.. définition.
+
+.. REFERENCES DOCUMENTAIRES:
+.. (les documents sont fournis dans le répertoire _static/documents)
+
+.. You can refer to this reference using the keyword: |REF_EDF_VCA_H-I2C-2009-03595-FR|_
+.. |REF_EDF_VCA_H-I2C-2009-03595-FR| replace:: H-I2C-2009-03595-FR: Manipulation de champs dans SALOME - Orientations générales
+.. _REF_EDF_VCA_H-I2C-2009-03595-FR: _static/documents/20091218_EDF_VCANO_H-I2C-2009-03595-FR.pdf
+
+.. You can refer to this reference using the keyword: |REF_CEA_VBE_MEDMEM|_
+.. |REF_CEA_VBE_MEDMEM| replace:: Guide utilisateur de MED mémoire
+.. _REF_CEA_VBE_MEDMEM: _static/documents/20070105_CEA_VBERGEAUD_GuideutilisateurMEDMEMOIRE.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_GBO_WORKNOTE|_
+.. |REF_EDF_GBO_WORKNOTE| replace:: XMED: Notes de travail
+.. _REF_EDF_GBO_WORKNOTE: _static/documents/20110309_XMED_scan_notes.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_ELO_REM|_
+.. |REF_EDF_ELO_REM| replace:: XMED: Remarques E. Lorentz
+.. _REF_EDF_ELO_REM: _static/documents/20110309_XMED_scan_remarques_ELORENTZ.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_PRESMANIPCHP01|_
+.. |REF_EDF_PRESMANIPCHP01| replace:: Séminaire EDF-CEA de janvier 2010: manipulation de champs
+.. _REF_EDF_PRESMANIPCHP01: _static/documents/20100129_MAN_seminaireEDF-CEA_all.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_PRESMANIPCHP02|_
+.. |REF_EDF_PRESMANIPCHP02| replace:: Révue EDF-CEA: maquette de manipulation de champs
+.. _REF_EDF_PRESMANIPCHP02: _static/documents/20101027_MAN_revueEDF-CEA.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_PRESMANIPCHP03|_
+.. |REF_EDF_PRESMANIPCHP03| replace:: Séminaire EDF-CEA de mars 2011: manipulation de champs, maquette 2010
+.. _REF_EDF_PRESMANIPCHP03: _static/documents/20110310_seminaireEDF-CEA_maquetteXMED.pdf
+
+.. PRESENTATIONS:
+
+.. You can refer to this reference using the keyword: |REF_EDF_JUS2011_PDF|_
+.. |REF_EDF_JUS2011_PDF| replace:: JUS2011: outils de manipulation de champs
+.. _REF_EDF_JUS2011_PDF: _static/presentations/20111115_JUS-2011/20111115_JUS2011_manipulation_de_champs.pdf
+
+.. You can refer to this reference using the keyword: |REF_EDF_JUS2011_OGV1|_
+.. |REF_EDF_JUS2011_OGV1| replace:: JUS2011: outils de manipulation de champs - Exemple 1
+.. _REF_EDF_JUS2011_OGV1: _static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_1.ogv
+.. You can refer to this reference using the keyword: |REF_EDF_JUS2011_OGV3|_
+.. |REF_EDF_JUS2011_OGV3| replace:: JUS2011: outils de manipulation de champs - Exemple 3
+.. _REF_EDF_JUS2011_OGV3: _static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_3.ogv
+.. You can refer to this reference using the keyword: |REF_EDF_JUS2011_OGV4|_
+.. |REF_EDF_JUS2011_OGV4| replace:: JUS2011: outils de manipulation de champs - Exemple 4
+.. _REF_EDF_JUS2011_OGV4: _static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_4.ogv
+
+
+
+.. LIENS EXTERNES:
+.. (l'accès nécessite le réseau intranet EDF et internet)
+
+.. You can refer to this reference using the keyword: |LINK_EDF_MEDDOC|_
+.. |LINK_EDF_MEDDOC| replace:: Modèle MED
+.. _LINK_EDF_MEDDOC: http://med.der.edf.fr/logiciels/med-2.3.6/doc/html/modele_de_donnees.html
+
+.. You can refer to this reference using the keyword: |LINK_EDF_MEDFICHIERDOC|_
+.. |LINK_EDF_MEDFICHIERDOC| replace:: Documentation de MED fichier
+.. _LINK_EDF_MEDFICHIERDOC: http://med.der.edf.fr/logiciels/med-2.3.6/doc
+
+.. You can refer to this reference using the keyword: |LINK_EDF_SALOME_MED__MED|_
+.. |LINK_EDF_SALOME_MED__MED| replace:: SALOME_MED::MED
+.. _LINK_EDF_SALOME_MED__MED: http://nepal.der.edf.fr/pub/SALOME_userguide/MED5/doc/salome/tui/MED/interfaceSALOME__MED_1_1MED.html
+
+.. RENVOIES:
+
+.. You can refer to this reference using the keyword: |SEE_MEDMEM_CORBA|
+.. |SEE_MEDMEM_CORBA| replace:: :ref:`L'interface CORBA SALOME_MED<xmed-medmem_corbainterface>`
+
+
+.. SNAPSHOTS:
+
+.. |XMED_SPECIFICATIONS_PDF| replace:: version pdf
+.. _XMED_SPECIFICATIONS_PDF: _static/documents/xmed-specifications.pdf
+
+.. |XMED_DEVELGUIDE_PDF| replace:: version pdf
+.. _XMED_DEVELGUIDE_PDF: _static/documents/xmed-develguide.pdf
+
+.. |XMED_USERGUIDE_PDF| replace:: version pdf
+.. _XMED_USERGUIDE_PDF: _static/documents/xmed-userguide.pdf
+
+
+.. =========================================================
+.. Rendering roles
+.. =========================================================
+.. This role can be used to display monospace text (code)
+.. role:: tt
+   :class: tt
+
+.. role:: strike
+   :class: strike
+
+.. role:: bolditalic
+   :class: bolditalic
+
+.. role:: underline
+   :class: underline
+
+.. role:: tag
+   :class: tag
+
+.. role:: tagb
+   :class: tagb
+
+.. role:: todo
+   :class: todo
+
+.. role:: date
+   :class: date
+
+.. role:: warn
+   :class: warn
+
+.. role:: info
+   :class: info
diff --git a/src/MEDOP/doc/sphinx/fr/medop-develguide.rst b/src/MEDOP/doc/sphinx/fr/medop-develguide.rst
new file mode 100644 (file)
index 0000000..57f826e
--- /dev/null
@@ -0,0 +1,285 @@
+.. meta::
+   :keywords: maillage, champ, manipulation, med, développement
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Module MED: Guide de développement du composant MEDOP
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Le composant logiciel MEDOP est un élément du module MED. Il fournit
+une interface utilisateur pour la manipulation de maillages et de
+champs, composée d'une interface texte (TUI) et d'une interface
+graphique (GUI). L'interface graphique constitue l'interface graphique
+du module MED.
+
+Ce document est la documentation technique du composant MEDOP. Il
+fournit les instructions à suivre pour installer le composant en vue
+d'un travail de développement, puis décrit les éléments de conception.
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Mise en place de l'espace de développement
+==========================================
+
+Gestion de configuration du composant MEDOP
+-------------------------------------------
+
+Le composant logiciel MEDOP est un package du module SALOME MED,
+hébergé dans l'espace source au niveau du sous-répertoire
+`src/MEDOP`. La gestion des fichiers sources est donc intégrée dans le
+module SALOME MED.
+
+Organisation des sources du composant MEDOP
+-------------------------------------------
+
+Le répertoire source `src/MEDOP` distingue les sous-répertoires
+suivants:
+
+* cmp: package containing the SALOME components
+* tui: package containing the python user interface
+* gui: package containing the graphical user interface (the GUI part
+  of the MED module)
+* res: resources files associated to the MEDOP package (icons, config
+  files, data files, ...)
+* exe: additional executable programs that can be launched from the
+  MEDOP framework
+
+Construction du composant MEDOP
+-------------------------------
+
+Intégré à la construction du module MED. Le composant MEDOP dépend de
+MEDCoupling et MEDLoader uniquement.
+
+Exécution des tests unitaires du composant MEDOP
+------------------------------------------------
+
+Les tests unitaires peuvent être exécutés au moyen de scripts python
+lancés depuis une session shell SALOME. Dans un nouveau shell, taper::
+
+ $ ./appli/runSession
+ [NS=mars:2810]$ python appli/bin/salome/med/test_medop_components.py
+
+L'exécution imprime un rapport détaillant le résultat pour chaque
+fonction de test::
+ test_Calculator_applyFunc (__main__.MyTestSuite) ... ok
+ test_Calculator_basics (__main__.MyTestSuite) ... ok
+ test_MEDDataManager_getFieldListInFieldseries (__main__.MyTestSuite) ... ok
+ test_MEDDataManager_getFieldseriesListOnMesh (__main__.MyTestSuite) ... ok
+ test_MEDDataManager_getMesh (__main__.MyTestSuite) ... ok
+ test_MEDDataManager_getMeshList (__main__.MyTestSuite) ... ok
+ test_addDatasource (__main__.MyTestSuite) ... ok
+ test_getDataManager (__main__.MyTestSuite) ... ok
+ test_getFieldHandlerList (__main__.MyTestSuite) ... ok
+ test_getFieldRepresentation (__main__.MyTestSuite) ... ok
+ test_markAsPersistent (__main__.MyTestSuite) ... ok
+ test_saveFields (__main__.MyTestSuite) ... ok
+ test_updateFieldMetadata (__main__.MyTestSuite) ... ok
+
+Les scripts de test sont installés dans le répertoire ``bin/med``. On trouve:
+
+* ``test_medop_components.py``: test les composants SALOME développés pour
+  la manipulation de champs (``MEDDataManager`` et ``MEDCalculator``).
+* ``test_xmed_fieldOperations.py``: test des operations de champs telles
+  qu'elles sont mises en oeuvre depuis l'interface textuelle.
+* ``test_xmed_uiEventListener.py``: test du système de notification
+  d'évènements des composants vers la partie gui du module MED.
+* ``test_xmed_visualisation.py``: test du système de visualisation
+  des champs tel que piloté depuis le module MED.
+
+Architecture du module XMED
+===========================
+
+Le module MED pour la manipulation de champs est composé de:
+
+* une bibliothèque de fonctions pour le traitement de données sur des
+  maillages et des champs conformes au modèle MED (package
+  MEDCoupling, MEDLoader et REMAPPER);
+* une interface graphique pour la mise en oeuvre des cas standard de
+  manipulation de champs;
+* une ensemble d'outils pour intervenir sur des fichiers au format
+  MED.
+
+Une bibliothèque de fonctions pour le traitement de données
+-----------------------------------------------------------
+
+La figure ci-dessous montre la structure des paquets logiciels qui
+constituent la bibliothèque:
+
+.. image:: images/medlayers.png
+   :align: center
+
+Elle comprend en particulier les paquets suivants:
+
+* MEDCoupling: qui décrit les structures de données pour porter les
+  maillages et les champs
+* MEDLoader: qui fournit les fonctions de persistence sous forme de
+  fichiers au format MED (lecture et écriture).
+* REMAPPER:
+
+Il est important de noter que MEDCoupling n'a aucune dépendance
+logicielle autre que la bibliothèque C++ standard. Ceci permet
+d'envisager son implantation dans un code de calcul ou un outil de
+traitement sans tirer l'ensemble pré-requis de SALOME.
+
+Une interface graphique pour l'exécution des cas standard
+---------------------------------------------------------
+
+
+Un ensemble d'outils pour le traitement de fichiers
+---------------------------------------------------
+
+
+Description des composants
+==========================
+
+MEDDataManager - Le gestionnaire des données de session
+-------------------------------------------------------
+
+Le composant MEDDataManager s'occupe de fournir les données MED sur
+demande des interfaces clientes, en particulier pour module de
+pilotage fieldproxy.py. Ces données peuvent avoir plusieurs sources,
+en général elle proviennent d'un fichier au format med contenant des
+champs définis sur des maillages. Les données sont identifiées à la
+lecture des métadonnées de description dans le fichiers med, puis les
+valeurs des champs et les maillages support sont chargés au besoin.
+
+Le chargement des métadonnées de description se fait par la méthode::
+
+  addDatasource(const char \*filepath)
+
+
+
+Eléments d'implémentation
+=========================
+
+Ecrire un service CORBA qui retourne une sequence de FieldHandler:
+
+.. code-block:: cpp
+
+  MEDOP::FieldHandlerList * MyFunction(...) {
+    vector<MEDOP::FieldHandler*> fieldHandlerList;
+    ...
+  
+    fieldHandlerList.push_back(fieldHandler);
+  
+    // Map the resulting list to a CORBA sequence for return:
+    MEDOP::FieldHandlerList_var fieldHandlerSeq = new MEDOP::FieldHandlerList();
+    int nbFieldHandler = fieldHandlerList.size();
+    fieldHandlerSeq->length(nbFieldHandler);
+    for (int i=0; i<nbFieldHandler; i++) {
+      fieldHandlerSeq[i] = *fieldHandlerList[i];
+    } 
+    return fieldHandlerSeq._retn();
+  }
+
+Ecrire un service CORBA qui retourne une structure CORBA:
+
+.. code-block:: cpp
+
+    MEDOP::FieldHandler * fieldHandler = new ...
+    _fieldHandlerMap[fieldHandler->id] = fieldHandler;
+
+    // >>> WARNING: CORBA struct specification indicates that the
+    // assignement acts as a desctructor for the structure that is
+    // pointed to. The values of the fields are copy first in the new
+    // structure that receives the assignement and finally the initial
+    // structure is destroyed. In the present case, WE WANT to keep
+    // the initial fieldHandler in the map. We must then make a deep
+    // copy of the structure found in the map and return the copy. The
+    // CORBA struct specification indicates that a deep copy can be
+    // done using the copy constructor.  <<<
+    return new MEDOP::FieldHandler(*fieldHandler);
+
+
+
+ANNEXE A: Bug en cours
+======================
+
+TO FIX:
+
+* la composition d'opérations n'est pas possible (ex: 2*f1+f2) car
+  2*f1 est indiqué comme non compatible (il semble qu'il n'ai pas la
+  reference correcte vers le maillage).
+* le script de test test_medoperation.py plante si le module xmed n'a
+  pas été chargé avec des données chargées.
+
+ANNEXE B: Traçabilité avec le module XMED
+=========================================
+
+Le module SALOME de nom XMED est l'espace de développement initial du
+composant logiciel MEDOP, intégré aujourd'hui au module MED. Cette
+annexe est la notice technique de ce module, qui reste disponible mais
+qui n'est plus maintenu.
+
+Gestion de configuration du module XMED
+---------------------------------------
+
+Les sources du module (répertoire ``xmed``) sont archivés en dépôt de
+configuration dans une base git du projet NEPAL. Ils peuvent être
+récupérés au moyen de la commande::
+
+ $ git clone git@cli70rw.der.edf.fr:xom/xmed.git
+
+Cette commande installe un répertoire ``xmed`` contenant l'ensemble
+des sources du module XMED.
+
+Le module XMED a pour pré-requis logiciel la plateforme SALOME:
+
+* SALOME version 6.1.3 (au moins) à télécharger à l'URL
+  http://pal.der.edf.fr/pal/projets/pal/releases/V6_1_3
+* On peut également utiliser une version dérivée comme SALOME-MECA 2010.1
+* Installer la plate-forme choisie selon les instructions fournies.
+
+Le module XMED utilise également une bibliothèque interne au projet
+NEPAL, appelée XSALOME, et qui fournit une extension aux fonctions de
+SALOME pour un usage de développement (XSALOME signifie eXtension
+SALOME). Les sources de cette bibliothèque doivent être récupérés au
+moyen de la commande::
+
+ $ git clone git@cli70rw.der.edf.fr:xom/xsalome.git
+
+Cette commande installe un répertoire ``xsalome`` contenant l'ensemble
+des sources de la bibliothèque XSALOME.
+.. note:: La bibliothèque XSALOME n'est pas un module SALOME mais une
+   simple bibliothèque de fonctions qui complète ou rend plus facile
+   d'utilisation les fonctions de SALOME. Elle NE DOIT EN AUCUN CAS
+   être intégrée à d'autres projets que les projets internes NEPAL ou
+   MAILLAGE. Il s'agit en effet d'une bibliothèque de transition qui
+   héberge des développements destinés à être reversés dans la
+   plate-forme SALOME. Le contenu et les interfaces de XSALOME ne peut
+   donc être garanti sur le long terme.
+
+Installation et lancement de l'application
+------------------------------------------
+
+L'installation suppose qu'une version 6.1.3 de SALOME (ou plus) est
+disponible et que le shell de travail est étendu avec l'environnement
+de SALOME. En général, par des commandes de la forme::
+
+ $ . /where/is/salome/prerequis.sh
+ $ . /where/is/salome/envSalome.sh
+
+La compilation des modules xsalome et xmed suit le standard SALOME. La
+bibliothèque xsalome est un prérequis à la compilation de xmed. Pour
+cela, la variable d'environnement XSALOME_DIR doit être spécifiée pour
+la configuration de la procédure de reconstruction de xmed::
+
+ $ export XSALOME_DIR=<xsalome_installdir>
+
+Aprés l'installation de xmed, il est possible de générer
+automatiquement une application SALOME prête à l'emploi pour la
+manipulation de champs::
+
+ $ <xmed_installdir>/bin/salome/xmed/appligen/appligen.sh
+
+Cette commande génére un répertoire ``appli`` à l'emplacement où elle
+est exécutée. Il reste à lancer l'application SALOME au moyen de la
+commande::
+ $ ./appli/runAppli -k
diff --git a/src/MEDOP/doc/sphinx/fr/medop-prototype-develguide.rst b/src/MEDOP/doc/sphinx/fr/medop-prototype-develguide.rst
new file mode 100644 (file)
index 0000000..de2387b
--- /dev/null
@@ -0,0 +1,731 @@
+.. meta::
+   :keywords: maillage, champ, manipulation, XMED
+   :author: Guillaume Boulant
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Démonstrateur XMED, documentation technique
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Cette note fait la synthèse des développements effectués pour le
+maquettage des fonctions de manipulation de champs dans SALOME. Elle
+présente les principes retenus en matière de conception, c'est-à-dire
+concernant les mécanismes techniques sous-jacents, et en matière
+d'ergonomie, c'est-à-dire concernant les modalités d'utilisation dans
+l'environnement SALOME.
+
+Ces principes sont illustrés par des développements implantés dans le
+module XMED, développé pour les besoins de l'analyse, et dans le
+module MED distribué avec la plateforme SALOME.
+
+.. note:: la lecture de ce chapitre demande une connaissance de la
+   structure de classes du module MED, en particulier la distinction
+   entre les classes ``MEDMEM::*`` et les servants CORBA associés
+   (classe ``SALOME_MED::*``).
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Principes directeurs
+====================
+
+Objectif et motivation
+----------------------
+
+L'objectif de maquettage est de trouver une architecture technique qui
+permet d'exécuter le cas d'utilisation suivant:
+
+* Chargement d'un fichier med dans SALOME (a priori dans le module MED)
+* Sélection graphique des champs de l'étude à mettre à disposition
+  dans la console utilisateur ("calculette" en mode texte qui
+  concraitement correspond à l'interface python de SALOME).
+* Dans la calculette, exécution d'opérations algébriques (+,-,*,/)
+  entre champs avec possibilité d'utiliser des scalaires dans des
+  opérations de type transformation linéaire (y=ax+b ou y et x sont
+  des champs et a et b des scalaires). Opérations pow, sqrt.
+* Possibilité de visualiser les champs produits avec VISU pour
+  contrôle des résultats.
+* Possibilité d'exporter des champs produits dans un fichier med.
+
+Eléments de contexte
+--------------------
+
+Les opérations de manipulation de champs sont en grande partie
+implémentées dans la bibliothèque MEDMEM. Pour illustration, le
+fragment de code ci-dessous montre comment une addition de champ peut
+être opérée en python:
+
+.. code-block:: python
+
+    from libMEDMEM_Swig import MedDataManager
+    from xmed.helper import readMed, writeMed
+
+    # Load the medmem data structure from a med file
+    med = readMed("/tmp/input.med")
+    # Then create a med data manager to deal with the fields data
+    dm  = MedDataManager(med)
+    # Get the timestamps (dt,it)=(-1,-1) of the fields "testfield1" and "testfield2"
+    f1 = dm.getFieldDouble("testfield1",-1,-1)
+    f2 = dm.getFieldDouble("testfield2",-1,-1)
+
+    # Create a new field as the sum of f1 and f2
+    r  = f1 + f2
+    # And add this new field to the med data structure
+    med.addField(r)
+
+    # Finally, write the whole data in an output med file
+    writeMed(med,"/tmp/output.med")
+
+Ceci montre que les champs peuvent être manipulés avec une interface
+relativement ergonomique (une addition de deux champs f1 et f2 s'écrit
+f1+f2) tant que l'on manoeuvre des objets MEDMEM purs (classes C++ du
+package MEDMEM et wrapping python du package MEDMEM_SWIG).
+
+Par ailleurs, le fonctionnement actuel des modules SALOME qui
+manoeuvrent des données MED est d'instancier les structures de données
+MEDMEM au niveau de la partie serveur, c'est-à-dire au niveau des
+servants CORBA hébergés dans le processus ``SALOME_Container``, et de
+donner accés à ces données depuis l'étude SALOME au travers de
+pointeurs CORBA. Ce choix d'architecture présente l'avantage de
+centraliser au niveau serveur la gestion du cycle de vie des données
+informatiques et de pouvoir distribuer des "poignées" pour manipuler
+ces données depuis chaque point de l'application qui sait accéder au
+bus CORBA, l'interface graphique en particulier.
+
+
+Hypothèse de travail
+--------------------
+
+Compte-tenu de l'objectif de maquettage et des éléments de contexte
+existant, on cherche une solution dans le cadre des hypothèses
+de travail suivantes:
+
+* La manipulation des champs se fait dans l'environement graphique de
+  SALOME.
+* Dans cet environnement, on souhaite pouvoir sélectionner
+  graphiquement les champs à considérer, puis manipuler ces champs
+  dans l'interface texte au moyen de variables python avec une syntaxe
+  aussi simple que celle définie dans le wrapping python de MEDMEM,
+  c'est-à-dire que pour faire l'addition de 2 champs f1 et f2, on veut
+  pouvoir écrire f1+f2.
+* Les données MED sont physiquement dans la partie serveur de SALOME
+  et accessibles via des pointeurs CORBA (interface spécifiée dans
+  MED.idl). On exclu la recopie de données au niveau du client
+  graphique.
+
+Dans le cadre de ces hypothèses, la difficulté technique réside dans
+la mise au point d'une interface de communication entre des variables
+manipulées par l'utilisateur dans l'interface graphique (c'est-à-dire
+dans le processus ``SALOME_SessionServer``) et des objets MEDMEM
+instanciés dans le containeur des servants CORBA (c'est-à-dire dans le
+processus ``SALOME_Container``).
+
+
+Eléments de conception
+======================
+
+
+Implantation technique
+----------------------
+
+Le diagramme ci-dessous représente l'organisation des principaux
+paquets logiciels du module MED:
+
+.. image:: images/medmem-layers.png
+   :align: center
+
+Les cadres bleus représentent le lieu d'implantation des
+développements effectués dans le module MED pour les besoins du
+maquettage. On notera en particulier les interventions aux niveaux
+suivants:
+
+* interfaces idl: ajout de l'interface MEDOP.idl
+* package MEDMEM_I: ajout du servant SALOME_MED::MEDOP qui implémente
+  l'interface MEDOP.idl
+
+Architecture technique
+----------------------
+
+Les schéma ci-dessous représente les objets informatiques qui sont à
+l'oeuvre pour la réalisation des opérations sur les champs:
+
+.. image:: /images/xmed-architecture.png
+   :align: center
+   :alt: Objets mis en oeuvre dans l'interface de manipulation de champs
+
+On distingue les objets suivants:
+
+* Une instance de ``MEDMEM::MED``, correspondant à la structure de donnée
+  MED chargée en mémoire.
+* Des instances de ``MEDMEM::FIELD`` qui représentent les champs med
+  chargés en mémoire.
+* Une instances de ``SALOME_MED::MED`` et des instances de
+  ``SALOME_MED::FIELD`` qui sont les servants CORBA respectivement de la
+  structure med et des champs qui lui sont associés et chargés en
+  mémoire.
+* Une instance de ``SALOME_MED::MEDOP`` qui est le servant CORBA qui
+  centralise la mise en oeuvre des opérations de champs sur le serveur
+  ``SALOME_Container``. Le servant MEDOP détient en attribut une référence
+  sur la structure ``MEDMEM::MED``, ce qui lui permet d'accéder
+  directement aux champs ``MEDMEM::FIELD`` à partir de leur nom et du pas
+  de temps.
+* Des instances de ``FieldProxy`` qui correspondent aux variables
+  manipulées au niveau de l'interface graphique et qui représentent
+  les champs. Une instance de FieldProxy possède détient les
+  références des servants ``SALOME_MED::MEDOP`` et
+  ``SALOME_MED::FIELD`` sous la forme de pointeurs CORBA de noms
+  ``medop_ptr`` et ``field_ptr`` respectivement.
+* Il existe également une instance de ``MedProxy`` non représentée
+  dans ce diagramme. Cette instance correspond à une variable qui
+  permet de manipuler la structure med.
+
+.. note:: Les éléments apportés par la maquette sont les classes
+   ``SALOME_MED::MEDOP``, ``MedProxy`` et ``FieldProxy``. Les autres
+   éléments ont pu être modifiés légèrement pour les besoins de
+   l'intégration ou pour la correction de quelques bugs.
+
+Le cycle de vie de ces objets est le suivant.
+
+Pour ce qui concerne les instances de la structure ``MEDMEM::MED`` et
+des champs ``MEDMEM::FIELD``, la création est faite au moment du
+chargement du fichier med dans SALOME au moyen du module MED. A cette
+occasion, les servants CORBA associés ``SALOME_MED::MED`` et
+``SALOME_MED::FIELD`` sont créés et des références vers ces servants
+sont publiés dans l'étude. Ils peuvent donc être sélectionnés par
+l'utilisateur dans l'interface graphique. L'ensemble de ces données
+préexiste à la manipulation de champs.
+
+Les objets ``SALOME_MED::MEDOP`` sont instanciés au sein du servant
+``SALOME_MED::MED`` auquel ils sont associées. Le servant
+``SALOME_MED::MED`` possède une référence sur la structure
+``MEDMEM::MED`` et il la transmet à l'instance du servant
+``SALOME_MED::MEDOP`` qu'il construit. L'opérateur MEDOP est donc
+autonome par la suite pour manipuler les données MED, et les champs en
+particulier. Le code python ci-dessous montre comment un opérateur med
+``SALOME_MED::MEDOP`` peut être créé puis utilisé pour réaliser
+l'addition de deux champs:
+
+.. code-block:: python
+
+   import salome
+   salome.salome_init()
+   import SALOME_MED
+   
+   medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED")
+   medObj  = medComp.readStructFile("myfile.med",salome.myStudyName)
+   medOp   = medObj.createMedOperator()
+   
+   f1 = medObj.getField("testfield1",-1,-1)
+   f2 = medObj.getField("testfield2",-1,-1)
+   
+   somme = medOp.add(f1,f2)
+
+Il est à noter qu'une instance de ``SALOME_MED::MEDOP`` est associé à
+une instance unique de ``SALOME_MED::MED`` (et donc indirectement de
+``MEDMED::MED``) pour toute la durée de son cycle de vie. Par contre,
+un servant ``SALOME_MED::MED`` peut être associé à plusieurs servants
+``SALOME_MED::MEDOP`` différents. Un servant ``SALOME_MED::MEDOP`` a
+une référence directe sur la structure ``MEDMEM::MED`` et peut la
+manoeuvrer pour demander des champs, faire des opérations avec ces
+champs, ajouter le champs résultat à la structure et enfin retourner
+un servant ``SALOME_MED::FIELD`` qui encapsule le champ résultat.
+
+Enfin, quelques éléments concernant la classe ``FieldProxy``. Une
+instance de ``FieldProxy`` est un objet python qui peut être
+manoeuvrée dans l'interpréteur SALOME et qui référence un champ MED
+localisé sur le serveur ``SALOME_Container`` (par le mécanisme décrit
+ci-dessus). C'est à ce niveau qu'on règle les détails d'ergonomie
+d'usage (cf. paragraphe ci-après). La création d'un objet
+``FieldProxy`` déclenche la création d'un opérateur med (instance de
+``SALOME_MED::MEDOP``) qui lui est associé et dont il conserve la
+référence CORBA en attribut (noté ``medop_ptr`` sur le diagramme). Cet
+opérateur ``medop_ptr`` peut être requêter pour exécuter toutes les
+opérations possibles sur ce champ, comme illustrer sur l'exemple
+ci-dessus.
+
+
+Rôle des objets proxy
+---------------------
+
+Dans le modèle d'architecture présenté ci-dessus, on introduit deux
+types d'objets proxy:
+
+* Les objets de classe ``FieldProxy`` qui représentent des poignées de
+  manipulation des champs ``MEDMEM::FIELD`` physiquement instanciés
+  dans le container SALOME.
+* Les objets de classe ``MedProxy`` qui représentent des poignées de
+  manipulation des structures ``MEDMEM::MED`` physiquement instanciées
+  dans le container SALOME.
+
+Elles sont instanciées dans l'interpréteur python SALOME pour
+manipulation dans l'interface textuelle à partir de la donnée du
+pointeur vers le servant ``SALOME_MED::MED`` et de l'identifiant du
+champ (le nom du champ et le pas de temps défini par le numéro d'ordre
+et le numéro d'iteration:
+
+.. code-block:: python
+
+   import salome
+   salome.salome_init()
+   import SALOME_MED
+
+   medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED")   
+   medObj  = medComp.readStructFile("myfile.med",salome.myStudyName)
+
+   from xmed import fieldproxy
+   from xmed import medproxy
+
+   f1 = fieldproxy.getFieldFromMed(medObj, "testfield1", -1, -1)
+   f2 = fieldproxy.getFieldFromMed(medObj, "testfield2", -1, -1)
+
+   field_somme  = f1 + f2
+   field_offset = f1 + 5.3
+
+Dans cet exemple, les variables ``f1``, ``f2``, ``field_somme`` et
+``field_offset`` sont des objets de classe ``FieldProxy``. Ils
+correspondent aux variables physiquement manipulées par
+l'utilisateur pour désigner les champs dans les opérations.
+
+Ces classes proxy sont conçues pour être le lieu d'implémentation de
+l'interprétation des commandes utilisateur et donc de l'ergonomie
+de manipulation des champs au niveau l'interface textuelle. Ce point
+est développé :ref:`plus bas <develguide_execFieldOperation>`.
+
+Programmation de l'interface textuelle
+--------------------------------------
+
+Dans le cadre de la maquette, l'interface de manipulation des champs
+est l'interface textuelle python intégrée à SALOME. Dans la pratique,
+l'utilisateur manipule des variables python qui correspondent à des
+objets de classe ``FieldProxy`` équipées des fonctions requises et de
+l'ergonomie nécessaire à la mise en oeuvre des opérations (voir
+ci-dessus).
+
+Or, l'hypothèse de travail est que les données MED sont chargées dans
+SALOME et publiées dans l'étude pour point d'accés depuis l'interface
+graphique. L'utilisateur choisi un champs directement dans l'arbre
+d'étude (ou dans une interface graphique dédiée) puis demande qu'il
+soit mis à disposition dans l'interface python sous un nom de variable
+à choisir. Les captures d'écran ci-dessous montre la séquence
+graphique en images:
+
+.. |IMG_SELECT| image:: images/medop-gui-selectfield_scale.png
+.. |IMG_ALIAS| image:: images/medop-gui-aliasfield_scale.png
+
++---------------+---------------+ 
+| |IMG_SELECT|  | |IMG_ALIAS|   |
++---------------+---------------+ 
+
+L'image de gauche montre la sélection du pas de temps, l'image de
+droite la boîte de dialogue qui permet la saisie de l'alias avec
+lequel le champs sera manipulé dans l'interface textuelle. La
+validation de cette fenêtre doit mettre automatiquement le champ à
+disposition dans l'interface python SALOME et sous le nom de variable
+spécifié par l'alias saisi.
+
+Pour cela, il y a un couplage technique à programmer entre l'interface
+graphique et l'interface textuelle python, avec en particulier la
+transmission des pointeurs vers les servants CORBA mis en jeu dans la
+sélection.
+
+Ce couplage est implanté au niveau de la classe MEDGUI.cxx du module
+MED (où de la classe XMEDGUI.cxx du module XMED pour la maquette) qui
+implémente l'interface graphique du module. Pour rappel, l'interface
+graphique d'un module SALOME se présente sous la forme d'une classe
+centrale de nom ``<MODULE_NAME>GUI`` et qui spécialise la classe
+``SalomeApp_Module``. Cette classe possède une méthode ``getApp()``
+par laquelle on peut récupérer une instance de la console python
+embarquée (this->getApp()->pythonConsole()).
+
+Le code suivant illustre l'envoie d'une commande python par ce
+mécanisme. Dans cet example, on cherche à reconstituer dans le
+contexte de la console python un pointer vers un objet med instancié
+dans le contexte C++ de l'application graphique. Pour cela, on
+communique la référence de l'objet sous la forme sérialisé (IOR pour
+un objet CORBA):
+
+.. code-block:: cpp
+
+   #include <PyConsole_Console.h>
+   #include <QString>
+   #include <QStringList>
+   #include <SalomeApp_Application.h>
+
+   // We suppose here that we have a CORBA object reference (object of
+   // type *_ptr or *_var), for example a SALOME_MED::MED object.
+   SALOME_MED::MED_ptr medObj = ... // anything to get this object  
+
+   // Get the IOR of this object
+   QString medIOR = SalomeApp_Application::orb()->object_to_string(medObj);
+
+   PyConsole_Console * pyConsole = getApp()->pythonConsole();
+
+   QStringList commands;
+   commands+="import salome";
+   commands+=QString("med=salome.orb.string_to_object(\"%1\")").arg(medIOR);
+      
+   QStringListIterator it(commands);
+   while (it.hasNext()) {
+       pyConsole->exec(it.next());
+   }
+
+Le code réel de la maquette est basé sur ce principe et transmet à la
+console python des lignes de commandes qui permettent de reconstruire:
+
+* un pointeur CORBA vers le servant ``SALOME_MED::MED`` associé au
+  champ sélectionné;
+* une instance de ``FieldProxy`` qui correspond au champ sélectionné
+  et avec pour nom de variable la valeur de l'alias saisi dans
+  l'interface graphique.
+
+Au niveau du code C++ de la classe ``XMEDGUI.cxx``, cela se traduit
+par la fabrication de la liste de commandes suivante pour envoie à la
+console python par le mécanisme illustré plus haut:
+
+.. code-block:: cpp
+
+   QStringList commands;
+   commands+="from xmed.fieldproxy import getFieldFromMed";
+   commands+="from xmed.medproxy import getMedProxy";
+   commands+=QString("if not dir().__contains__('med'): med = getMedProxy(\"%1\")").arg(medIOR);
+   commands+=QString("%1=getFieldFromMed(med,\"%3\",%4,%5)").arg(*alias).arg(fieldName).arg(orderIndex).arg(iterationIndex);
+
+Les variables ``medIOR``, ``fieldName``, ``orderIndex`` et
+``iterationIndex`` sont construites à partir du champ sélectionné par
+des techniques de programmation standard dans SALOME qu'on peut
+examiner en détail dans la classe ``XMEDGUI`` (voir méthode
+``XMEDGUI::LoadIntoPythonConsole()``). La variable ``alias`` est la
+chaîne saisie par l'utilisateur dans la fenêtre de dialogue.
+
+Le point important à noter ici est que les données à transmettre
+doivent être fournies sous forme de chaînes de caractères ou de types
+simples. C'est pourquoi la référence au servant CORBA
+``SALOME_MED::MED`` est transmise ici sous la forme de son IOR,
+c'est-à-dire une chaîne de caractères qui permet l'identification de
+l'objet au niveau du bus CORBA.
+
+Au niveau de la console python cela correspond à l'exécution des
+commandes suivantes:
+
+.. code-block:: python
+
+   from xmed.fieldproxy import getFieldFromMed
+   from xmed.medproxy import getMedProxy
+   
+   med = getMedProxy("IOR:010000001700000049444c3a53414c4f4d455f4d45442f4d45443a312e300000010000000000000064000000010102000e0000003133302e39382e37372e313733009e0a0e000000feadc4ca4c00003169000000001100000200000000000000080000000100000000545441010000001c00000001000000010001000100000001000105090101000100000009010100")
+   
+   f1=getFieldFromMed(med,"testfield1",-1,-1)
+
+Ce jeu d'instructions reconstitue un pointeur vers le servant CORBA
+``SALOME_MED::MED`` à partir de son identifiant IOR (voir la fonction
+``getMedProxy(...)``, puis crée une instance de ``FieldProxy``
+associée à ce servant (en fait associée au servant
+``SALOME_MED::MEDOP`` créé sur demande par le servant
+``SALOME_MED::MED``, voir la fonction ``getFieldFromMed(...)``).
+
+.. _develguide_execFieldOperation:
+
+Exécution des opérations sur le champs
+--------------------------------------
+
+Les variables définies dans l'interface textuelle pour désigner les
+champs à manipuler sont des objets de classe ``FieldProxy``.
+
+Cette classe a une propriété remarquable, elle est construite sur un
+design pattern de type "Proxy" qui pointe vers un servant
+``SALOME_MED::FIELD``. Cela signifie que l'on ne peut pas accéder
+directement au servant vers lequel il pointe, mais que l'on passe
+systématiquement par une procédure de l'objet proxy qui fait "boîte
+aux lettres":
+
+.. code-block:: python
+
+   class FieldProxy:
+
+     def __getattr__( self, name ):
+        """
+        This method realizes the proxy pattern toward the servant
+        SALOME_MED::FIELD.
+        """
+        return getattr( self.__field_ptr, name )
+
+Ce pattern permet l'implémentation de pré-traitement et/ou de
+post-traitement suivant le type d'accés que l'on cherche à faire.
+
+Il permet aussi et surtout de fournir un objet python qui présente
+l'interface de ``SALOME_MED::FIELD`` dotée d'extentions adhoc pour les
+operations de champs. Ici, python est ton ami, car il s'agit pour cela
+d'équiper la classe ``FieldProxy`` des automatismes prévus nativement
+par python pour les operations entre objets. En particulier, la
+re-définition des fonctions internes ``__add__`` (opérateur addition),
+``__sub__`` (opérateur soustraction), ``__mul__`` (opérateur
+multiplication) et ``__div__`` (opérateur division) au sein de la
+classe ``FieldProxy``, permet de prendre la main sur le comportement
+des opérations algébriques et de définir une ergonomie sur mesure. Par
+exemple, la méthode ``__add__`` peut gérer les variantes "f1+f2"
+(ajout de deux variables de type FieldProxy) et "f1+5.3" (ajout d'un
+réel à une variable de type FieldProxy):
+
+.. code-block:: python
+
+   class FieldProxy:
+
+     def __add__(self, operande):
+        """
+        This can process the addition of two fields or the addition of
+        a scalar to a field. It depends weither the operande is a
+        FieldProxy or a simple scalar numerical value.
+        """
+        if isinstance(operande, FieldProxy):
+            # The operande is an other field
+            otherField_ptr = operande.__field_ptr
+            rfield_ptr = self.__medOp_ptr.add(self.__field_ptr, otherField_ptr)
+        else:
+            # The operande is a scalar numerical value that must be
+            # considered as an offset in a linear transformation
+            factor = 1
+            offset = operande
+            rfield_ptr = self.__medOp_ptr.lin(self.__field_ptr, factor, offset)
+        return FieldProxy(self.__med_ptr, rfield_ptr)
+
+Il est à noter que dans les deux cas de figure (opérande=champ ou
+opérande=scalaire), la fonction délègue la réalisation concrète de
+l'opération au servant ``SALOME_MED::MEDOP`` (identifié ici par
+l'attribut ``self.__medOp_ptr`` et que l'on appelera l'*opérateur
+MEDOP* dans la suite pour simplifier), mais n'appelle pas le même
+service de calcul (l'addition entre champs dans le premier cas,
+l'application d'une transformation linéaire de type y=factor*x+offset
+dans le deuxième cas).
+
+Pour couvrir le cas des opérations algébriques, l'opérateur MEDOP
+présentre l'interface suivante (cf. fichier ``MEDOP.idl`` qui définie
+l'interface du servant ``SALOME_MED_MEDOP``):
+
+.. code-block:: cpp
+
+    /*! Addition of the fields f1 and f2 ( f1+f2) */
+    FIELD add(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception);
+    /*! Substraction of the fields f1 and f2 (f1-f2) */
+    FIELD sub(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception);
+    /*! Multiplication of the fields f1 by f2 (f1*f2) */
+    FIELD mul(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception);
+    /*! Division of the fields f1 by f2 (f1/f2) */
+    FIELD div(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception);
+    /*! Power of the field f (f^power) */
+    FIELD pow(in FIELD f, in long power) raises (SALOME::SALOME_Exception);
+    /*! Linear transformation of the field f (factor*f+offset) */
+    FIELD lin(in FIELD f, in double factor, in double offset) raises (SALOME::SALOME_Exception);
+    /*! Dublication of the field f */
+    FIELD dup(in FIELD f) raises (SALOME::SALOME_Exception);
+
+Cette interface est implémentée dans la classe C++ ``MEDOP_i`` du
+module MED (voir fichier ``MEDMEM_MedOp_i.hxx`` du package
+``MEDMEM_I``). C'est au sein des instances de cette classe que sont
+réalisées les opérations et que sont produites physiquement les
+données. Typiquement, les opérations présentées ici produisent un
+champ ``MEDMEM::FIELD`` sur la base duquel elle fabrique un servant
+``SALOME_MED::FIELD`` pour finalement retourner un pointeur CORBA sur
+ce servant.
+
+Ce mécanisme global peut être étendu sans limitation à tout les types
+d'opération qui sont envisagés dans les spécifications de manipulation
+des champs dans SALOME.
+
+
+Contrôle visuel des champs
+--------------------------
+
+Les illustrations ci-dessous montrent qu'une fonction de visalisation
+est implémentée dans la maquette pour permettre le contrôle visuel
+d'un champ au moyen d'une représentation 3D (une carte spatiale du
+module du champ dans l'exemple implémenté par défaut):
+
+.. |IMG_VISU| image:: images/medop-gui-visufield_scale.png
+.. |IMG_RESULT| image:: images/medop-gui-result_scale.png
+
++---------------+---------------+ 
+| |IMG_VISU|    | |IMG_RESULT|  |
++---------------+---------------+ 
+
+Cette fonction répond au besoin de contrôle interactif des résultats
+produits par les opérations de manipulation de champs.
+
+Il s'agit là d'un usage classique de SALOME, dans lequel on demande au
+module VISU de faire une représentation 3D d'un champ spécifié par la
+donnée du servant ``SALOME_MED::FIELD`` qui lui est associé
+(représenté par la variable ``field_ptr`` dans l'exemple ci-dessous):
+
+.. code-block:: python
+   
+   import salome
+   import VISU
+
+   visuComp = salome.lcc.FindOrLoadComponent("FactoryServer", "VISU")
+   visuComp.SetCurrentStudy(salome.myStudy)
+
+   # Then we can import the specified field in the VISU module. This
+   # creates an study entry in the VISU folder.
+   result = visuComp.ImportMedField(field_ptr)
+
+   meshName   = field_ptr.getSupport().getMesh().getName()
+   fieldName  = field_ptr.getName()
+   iterNumber = field_ptr.getIterationNumber()
+   scalarmap = visuComp.ScalarMapOnField(result,
+                                         meshName,
+                                         visuEntityType,
+                                         fieldName,
+                                         iterNumber)
+
+Dans ce jeu d'instructions donné pour exemple (non fonctionnel, en
+particulier à cause de la non définition de la variable
+``visuEntityType``, voir remarque plus bas), le composant VISU
+désigné ici par la variable ``visuComp`` va chercher les données du
+champ en interrogeant le servant ``SALOME_MED::FIELD`` transmis en
+argument de la fonction ``ImportMedField``, puis produit une
+représentation de type "scalarmap".
+
+.. note:: Compte-tenu des propriétés de la classe FieldProxy décrites
+   plus haut conférées par le pattern "Proxy", on peut transmettre ici
+   aussi bien le servant CORBA que l'instance du proxy (la fonction
+   ``ImportMedField`` n'y verra que du feu).
+
+Le code complet et fonctionnel de la fonction d'affichage est dans le
+corps du module python ``fieldproxy.py`` sous la forme d'une fonction
+de nom ``visuField``. Il convient de noter que cette fonction doit
+établir une correspondance entre le type des entités tel que défini
+dans MED et dans VISU:
+
+.. code-block:: python
+
+    medEntityType = field_ptr.getSupport().getEntity()
+    if (medEntityType == SALOME_MED.MED_CELL):
+        visuEntityType = VISU.CELL
+    elif (medEntityType == SALOME_MED.MED_NODE):
+        visuEntityType = VISU.NODE
+
+
+Export des résultats de calcul
+------------------------------
+
+Tous les champs produits à l'occasion des opérations entre objets
+``FieldProxy`` sont automatiquement ajoutés à la structure med à
+laquelle is sont associés. Une convention d'attribution des noms est
+implémentée de sorte que par défaut aucune précision n'est demandée à
+l'utilisateur.
+
+La structure med peut être manipulée au moyen de la variable ``med``
+créée dans l'interface textuelle comme une instance de la classe
+``MedProxy``. La classe ``MedProxy`` fournit un objet qui présente
+l'interface du servant ``SALOME_MED::MED`` étendue de quelques
+fonctions utilitaires pour la gestion et le contrôle des données.
+
+En particulier, la sauvegarde de la structure dans un fichier est
+automatisée par la méthode ``save(medfilename)``:
+
+.. code-block:: python
+
+   med = medproxy.MedProxy(medObj)
+   med.save("/tmp/output.med")
+
+Cette méthode s'occupe de définir un driver d'écriture et de procéder
+à l'enregistrement des données de la structure med (les maillages, les
+champs présents au départ et tous les champs produits depuis la
+lecture initiale).
+
+Limitations
+===========
+
+L'implémentation de la maquette limite l'usage des opérations aux cas
+de figure suivants:
+
+* Seules les operations entre champs qui partagent le même support med
+  sont possibles. Ceci est une contrainte imposé par la conception
+  actuelle de MEDMEM.
+* Le résultat d'une opérations est calculé sur toutes les composantes
+  et tout le domaine de définition des champs en opérande. Cette
+  deuxième contrainte est juste parce que les usages plus fin,
+  notemment avec la notion de domaine de définition, n'a pas encore
+  été exéminée à ce jour.
+* Le nom d'un champ produit par une opération ne correspond pas au nom
+  de la variable python par laquelle on le réceptionne et on le
+  manipule. Le nom est attribué par une convention (ceci n'est pas
+  vraiment une limitation mais une caractéristique à connaître).
+
+On note également les restriction techniques suivantes:
+
+* Les données MEDMEM sont supposées être chargées par le composant MED
+  puis référencées dans l'étude SALOME (comme c'est fait aujourd'hui
+  par le module MED).
+* Dans certain cas, python n'est pas ton ami. Pour que les opérateur
+  de la classe ``FieldProxy`` soient pris en considération dans les
+  opérations sur les champs, il est indispensable que le premier
+  opérande d'une opération unitaire soit un champ (objet de classe
+  ``FieldProxy``). Par exemple: "field_offset = field + 5.3"
+  fonctionne alors que "field_offset = 5.3 + field" ne fonctionne pas
+  car python tente de traiter la situation au moyen de la fonction
+  ``__add__`` de la classe ``float`` (qui n'est pas modifiable).
+
+
+Notice informatique
+===================
+
+Gestion de configuration
+------------------------
+
+Les développements décrits dans ce chapitre sont répartis entre les
+modules MED et XMED (développé pour l'occasion). Cette séparation est
+faite par soucis de clarté et d'efficacité de développement, mais les
+éléménts du module XMED ont vocation à intégrer le module MED dans la
+mesure où les propositions techniques sont retenues pour le
+développement à venir.
+
+Le code source du module XMED peut être récupérés par la commande
+suivante::
+
+ $ svn co svn://nepal.der.edf.fr/FIELD/XMED_SRC/trunk XMED_SRC
+
+Le pré-requis est la plate-forme SALOME version 5.1.4 (ou plus)
+équipée au minimum des modules KERNEL, GUI, MED (branche BR_medop) et
+VISU. Pour récupérer la branche BR_medop du module MED, taper la
+commande::
+
+ $ cvs -d :pserver:anonymous@cvs.opencascade.com:2401/home/server/cvs/MED co -r BR_medop MED_SRC
+
+La configuration de référence est:
+
+* XMED: révision svn 41
+* MED: tag cvs BR_medop_20101025
+
+Moyens de tests
+---------------
+
+Plusieurs types de tests unitaires sont définis (reste à les
+automatiser proprement):
+
+* Test des servants et utilitaires de manipulation python:
+
+  - Dans XMED, package xmed/tests, utiliser le script
+    ``test_medoperation.py`` dans un interpréteur python lancé dans
+    une session shell SALOME. Ce script prépare des variables de test
+    et fournit des fonctions de test unitaire (à exécuter ou pour s'en
+    inspirer). Après avoir lancé SALOME via une application virtuelle,
+    on peut taper::
+      $ <APPLI_ROOT>/runSession
+      [NS=venus:2810] $ python -i test_medoperation.py
+      >>> 
+   
+  - Ceci permet de tester en particulier l'interface ``MedOp`` et son
+    utilisation dans le module python ``fieldproxy.py``.
+
+* Test des classes MEDMEM:
+
+  - Test de MEDMEM::MedDataManager dans ``MEDMEM_MedDataManager_test.cxx``
+
+Un fichier de test basique (mais néanmoins suffisant) de nom
+``tesfield.med`` est fourni avec les sources dans le répertoire
+``<XMED_SRC>/resources/datafiles`` et dans l'installation au niveau du
+répertoire ``<INSTALLDIR>/share/salome/resources/xmed/datadir``. Il
+contient deux champs ``testfield1`` et ``testfield2`` définis sur un
+pas de temps unique (dt,it=-1,-1). Ces champs définissent des valeurs
+par éléments (MED_CELL).
diff --git a/src/MEDOP/doc/sphinx/fr/medop-prototype-medmem.rst b/src/MEDOP/doc/sphinx/fr/medop-prototype-medmem.rst
new file mode 100644 (file)
index 0000000..2302f7b
--- /dev/null
@@ -0,0 +1,513 @@
+.. meta::
+   :keywords: maillage, champ, MED, MEDMEM
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Note de travail concernant l'utilisation de MEDMEM
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Le module MED de SALOME comporte plusieurs composants d'intérêt pour
+la manipulation de champs:
+
+* la bibliothèque MEDMEM qui fournit une interface de programmation
+  pour manoeuvrer une structure MED
+* le module CORBA SALOME_MED qui matérialise le composant SALOME
+  (serveur corba) du module MED
+* l'interopérabilité avec le module VISU qui permet la visualisation
+  des champs manipulés dans MED
+
+Les sections ci-après donnent quelques éclairages techniques sur ces
+différents aspects. Les sources de démonstration peuvent être
+récupérés depuis le dépôt svn::
+
+ $ svn export svn://nepal.der.edf.fr/OM/manifield/trunk manifield
+ $ svn export svn://nepal.der.edf.fr/FIELD/demofield/trunk demofield
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Présentation synthétique de MED
+===============================
+
+MED désigne un modèle conceptuel pour décrire des données de type
+éléments finis (éléments finis, volumes finis et éléments
+discrets). Dans l'usage courant, il permet la description et l'échange
+des données de calcul de type maillages et champs. La documentation
+complète peut être trouvée à l'URL suivantes:
+
+* |LINK_EDF_MEDDOC|_ (version 2.3).
+
+On distingue deux implémentations informatiques de ce modèle:
+
+* MED fichier: qui permet la lecture et l'écriture de données depuis
+  un fichier au format med. Les opérations de lecture/écriture sont
+  atomiques (pas de chargement de la structure de données globale).
+* MED mémoire (noté MEDMEM): qui permet le chargement en mémoire d'une
+  image de la structure de données MED contenue dans un fichier au
+  format med. Les opérations peuvent être atomiques ou
+  globales.
+
+On notera simplement ici que MEDMEM utilise MED fichier pour les
+opérations de lecture/écriture et que MED fichier est indépendant de
+MED mémoire. La documentation complète de MED fichier peut être
+trouvée à l'URL suivante:
+
+* |LINK_EDF_MEDFICHIERDOC|_
+
+La bibliothèque MEDMEM
+======================
+
+Le modèle de classes MEDMEM est structuré autour des notions de MESH
+(les maillages), de SUPPORT (le profil des entités) et de FIELD (les
+champs). Ces notions reprennent en partie des concepts du modèle
+MED. Le diagramme ci-dessous présente les classes principales:
+
+.. image:: images/med-uml-main_60pc.png
+   :align: center
+
+Le conteneur de plus haut niveau dans MEDMEM est la classe MED. La
+figure ci-dessous indique qu'une instance MED peut être associée à
+plusieurs maillage et plusieurs champs. Par contre un champ donné ne
+peut être associé qu'à un seul maillage (par l'intermédiaire du
+support). Plusieurs champs peuvent être associés au même maillage. La
+forme la plus courante est d'ailleurs une instance composé d'un
+maillage unique sur lequel sont définis plusieurs champs.
+
+On peut avoir également des configurations plus complexes, comme par
+exemple un maillage unique, plusieurs champs définis sur ce maillage
+mais avec des supports différents, par exemple parce que les valeurs
+sont définies sur des entités de maillage différentes (les éléments
+pour un champ, les noeuds pour un autre, ...)::
+
+  field1->support1->mesh
+  field2->support2->mesh
+  field3->support3->mesh
+
+On observe:
+
+* 2 champs U et V doivent avoir le même support (au sens informatique
+  du terme) pour pouvoir être en argument d'une opération (sinon
+  exception). Il faudrait accepter qu'il soit informatiquement
+  différent et vérifier la conformité conceptuelle.
+* Cette contrainte peut se comprendre car physiquement les données
+  sont stockées dans un vecteur qui couvre toutes les mailles. Le
+  support est le seul masque de lecture pour établir la correspondance
+  avec les positions dans le maillage et il est donc important qu'une
+  cohérence soit assurée.
+
+Les objets champs (FIELD) et maillage (MESH)
+--------------------------------------------
+
+Un objet MED permet d'accéder aux différentes informations concernant
+les objets MESH, SUPPORT et FIELD, mais il ne permet pas d'accéder aux
+données physiques associées à ces objets (les valeurs des composantes
+pour les champs, les mailles et leur connectivité pour les
+maillages). L'accès aux données physiques est du ressort des objets
+spécifiques MESH, SUPPORT et FIELD.
+
+Un objet MED peut être créé intégralement en mémoire. L'usage plus
+fréquent est de l'initialiser à partir de la donnée d'un fichier
+med. Pour cela, l'objet MED doit être associé à un driver
+d'entrée/sortie branché sur le fichier (``testfilename`` dans
+l'exemple):
+
+.. code-block:: cpp
+   
+   MED *myMed = new MED;
+   MED_MED_RDONLY_DRIVER *driverIn = new MED_MED_RDONLY_DRIVER(testfilename, myMed);
+   driverIn->open();
+   driverIn->readFileStruct();
+   driverIn->close();
+
+A l'occasion de la fonction readFileStruct, la structure interne de
+l'objet MED est enrichie des informations concernant les objets MESH,
+SUPPORT et FIELD contenu dans le fichier. En particulier un
+dictionnaire des champs (variable map interne) est initialisé est
+contient l'ensemble des objets ``FIELD_`` préchargés (i.e. avec les
+méta-données uniquement). Chaque objet ``FIELD_`` ainsi préchargé est
+autonome pour être chargé sur demande. On peut alors requêter l'objet
+MED pour obtenir un champ particulier (spécifié par son nom
+``fieldname`` dans l'exemple):
+
+.. code-block:: cpp
+
+   FIELD<double> *field = (FIELD<double> *)myMed->getField(fieldname, dt, it);
+
+Puis le champ qui lui est associé doit être physiquement chargé pour
+permettre la mise à jour du support:
+
+.. code-block:: cpp
+   
+   MESH * mesh = myMed->getMesh(field);
+   mesh->read();
+   myMed->updateSupport();
+
+Pour enfin charger les valeurs des composantes du champ:
+
+.. code-block:: cpp
+   
+   field->read();
+
+La numérotation des éléments de maillage
+----------------------------------------
+
+Les éléments qui composent un maillage sont caractérisés par:
+
+* Le type d'entité de l'élément, à choisir dans la liste
+  ``MED_EN::medEntityMesh``, qui contient en particulier ``MED_NODE``,
+  ``MED_FACE``, ``MED_CELL``.
+* Le type de géométrie de l'élément, à choisir dans la liste
+  ``MED_EN::medGeometryElement``, qui contient en particulier
+  ``MED_NONE``, ``MED_TRIA3``, ..., ``MED_ALL_ELEMENTS``.
+
+Les éléments sont numérotés par un indice relatif à la catégorie
+géométrique à laquelle ils appartiennent. Ainsi, si le modèle est
+composé de Na arrêtes et Nf faces de type géométrique MED_QUAD4, alors
+ces faces sont numérotées de 1 à Nf dans le modèle MED (et de manière
+persistente dans le fichier med). De même, les arrêtes sont numérotées
+de 1 à Na. Une numérotion globale implicite existe sur les éléments,
+elle consiste à parcourir l'ensemble des types géométriques dans
+l'ordre de définition du modèle de données. Ainsi, si le modèle
+contient uniquement les Na arrêtes et les Nf faces, alors l'indice
+global de la première face est Na+1.
+
+.. note:: Des exemples de code sont disponibles dans le package ``demofield``, fichier ``python/pybasicfields/MEDMEM_tester.py``.
+
+
+Binding python de MEDMEM
+------------------------
+
+Les classes du package ``MEDMEM`` (package du module ``MED`` qui
+implémentent les structures de données C++ de MED mémoire) produisent
+la bibliothèque ``libmedmem.so``. Cette ensemble de classes est en
+partie mis à disposition de l'interface python grace à une couche de
+liaison (binding Python-C++) générée par le logiciel SWIG à partir
+d'un fichier de description d'interface ``libMEDMEM_Swig.i`` (dans le
+package source ``MEDMEM_SWIG``).
+
+Ce fichier d'interface doit être mis à jour dés lors qu'une évolution
+des interfaces publiques des classes C++ MEDMEM est faite ou qu'une
+nouvelle classe est créée (du moins si l'on souhaite profiter de ces
+évolutions dans l'interface python).
+
+Cette mise à jour nécessite de prendre soin au transfert des
+structures de données entre les espaces python et C++. En particulier,
+l'utilisation des template de classe pour décrire les champs typés en
+C++ appelle une précaution de codage particulière de l'interface
+SWIG.
+
+Pour exemple, le fragment de code ci-dessous, extrait du fichier
+``libMEDMEM_Swig.i``, montre comment déclarer la nouvelle classe
+``MedDataManager`` dans l'interface:
+
+.. code-block:: cpp
+   
+   #include "MEDMEM_MedDataManager.hxx"
+
+   class MedDataManager
+   {
+     public:
+      ~MedDataManager();
+      void printFieldDouble(FIELD<double,FullInterlace> * field);
+   
+      %extend {
+        MedDataManager(char * fileName)
+        {
+         return new MedDataManager(string(fileName));
+        }
+        MedDataManager(MED * med)
+        {
+          return new MedDataManager(med);
+        }
+    
+        %newobject getFieldDouble(const char * fieldName, const int dt, const int it);
+        FIELD<double, FullInterlace> * getFieldDouble(const char * fieldName, const int dt, const int it)
+        {
+         return (FIELD<double, FullInterlace> *) self->getFieldDouble(string(fieldName), dt, it);
+        }
+      }
+  
+   };
+
+
+Utilisation de MEDMEM pour la manipulation de champs
+----------------------------------------------------
+
+Des opérations de manipulation de champs sont disponibles dans la
+bibliothèque MEDMEM standard est peuvent être utilisées dans
+l'interface python. Les quelques lignes suivantes illustrent l'usage
+qu'on peut en faire pour exécuter l'addition de deux champs sur tout
+leur espace de définition et pour un pas de temps donné:
+
+.. code-block:: python
+
+    from libMEDMEM_Swig import MedDataManager
+    from xmed.helper import readMed, writeMed
+
+    # Load the medmem data structure from a med file
+    med = readMed("/tmp/input.med")
+    # Then create a med data manager to deal with the fields data
+    dm  = MedDataManager(med)
+    # Get the timestamps (dt,it)=(-1,-1) of the fields "testfield1" and "testfield2"
+    f1 = dm.getFieldDouble("testfield1",-1,-1)
+    f2 = dm.getFieldDouble("testfield2",-1,-1)
+
+    # Create a new field as the sum of f1 and f2
+    r  = f1 + f2
+    # And add this new field to the med data structure
+    med.addField(r)
+
+    # Finally, write the whole data in an output med file
+    writeMed(med,"/tmp/output.med")
+
+.. note:: Cet exemple de code requiert les évolutions de MEDMEM
+   opérées dans la branche BR_medop (pour disposer de la classe
+   MedDataManager en particulier) et le package python ``xmed`` qui
+   fournit quelques fonctions utilitaires pour manoeuvrer les données
+   med (ce package est dans le module XMED et sera probablement à
+   terme intégré au module MED).
+
+Des limitations existent aujourd'hui pour ce type de manipulations:
+
+* les champs doivent partager le même support MED, c'est-à-dire être
+  décrit sur le même maillage et sur les mêmes entités de ce
+  maillage.
+* ...
+
+
+Remarque sur l'implémentation C++
+---------------------------------
+
+A noter l'usage de plusieurs formes d'arguments pour les fonctions:
+
+* passage des arguments par valeur ``myfunction(A a);``
+* passage des arguments par référence ``myfunction(A& a);``
+* passage des arguments par pointeur ``myfunction(A* a);``
+
+Le passage des arguments par référence est une facilité d'écriture
+pour éviter de passer un pointeur tout en évitant la récopie des
+données de la variable.
+
+.. _xmed-medmem_corbainterface:
+
+L'interface CORBA SALOME_MED
+============================
+
+Implémentation du composant MED et des servants SALOME_MED::\*
+--------------------------------------------------------------
+
+Le composant MED est un servant CORBA qui permet la manipulation de
+données MEDMEM dans l'environnement SALOME. Le composant peut fournir
+des pointeurs vers des instances de l'interface SALOME_MED (objets
+SALOMEMED::MED, SALOME_MED_FIELD, ...). Ces instances sont des
+servants CORBA qui résident dans le container et qui encapsulent les
+données MEDMEM.
+
+Le schéma ci-dessous représente les éléments informatiques qui
+composent l'architecture CORBA du module MED:
+
+.. image:: images/medmem-corba-layers.png
+   :align: center
+
+Les structures MEDMEM (données physiques) et SALOME_MED (wrapping
+CORBA) fonctionnent différement en ce qui concerne le chargement des
+données:
+
+* Dans MEDMEM, les données sont chargées à la demande (fonctions read
+  des objets) et aucune gestion n'est assurée. En particulier l'appel
+  à read alors que la donnée est déjà chargée conduit à une levée
+  d'exception. C'est à l'utilisateur de MEDMEM de prendre en charge ce
+  type de gestion.
+* Dans SALOME_MED, les données sont chargées à la création de
+  l'instance SALOME_MED::MED. Les maillages ainsi que les champs et
+  leurs données sont chargés à ce moment là et gérés dans une table de
+  type HashMap au niveau de la structure SALOME_MED::MED. Cette
+  structure remplie dés lors des fonction de gestion. L'appel à
+  SALOME_MED::MED.getField(...) ne charge pas les données mais renvoie
+  un pointeur SALOME_MED::FIELD_ptr sur les données chargées à
+  l'initialisation (ATTENTION, cette fonction est bugguée dans la
+  branche principale -> Fix dans la branche BR_medop).
+
+Une gestion intermédiaire peut être envisagée: le chargement à la
+demande géré dans une ou plusieurs tables de champs (une pour chaque
+type de valeur numérique). Une implémentation de ce type de gestion
+est illustré dans la classe ``MedDataManager`` du package MEDMEM qui prend
+en charge ce comportement pour les structures de données MED (en
+particulier les champs).
+
+Utilisation du composant MED
+----------------------------
+Le module SALOME MED fournit un module CORBA appelé SALOME_MED. Les
+interfaces de ce module CORBA sont spécifiées par les fichiers idl
+suivants:
+
+* le fichier
+  [http://nepal.der.edf.fr/pub/SALOME_userguide/MED5/doc/salome/tui/MED/MED_8idl.html
+  ``MED.idl``] qui décrit les interfaces des objets manipulés par le
+  module SALOME_MED. On trouve en particulier les objets MESH, SUPPORT
+  et FIELD.
+* le fichier
+  [http://nepal.der.edf.fr/pub/SALOME_userguide/MED5/doc/salome/tui/MED/MED__Gen_8idl.html
+  ``MED_Gen.idl``] qui décrit les interfaces du composant SALOME
+  (c'est-à-dire le composant chargé par la commande
+  ``FindOrLoadComponent("FactoryServer", "MED")`` du
+  lyfeCycleCorba). On trouve:
+
+  - l'interface ``MED_Gen_Driver`` qui hérite de SALOMEDS::Driver
+    pour l'implémentation des services généraux des composants SALOME
+    (persistance hdf, dump)
+  - l'interface ``MED_Gen`` qui hérite des interfaces
+    ``Engines::Component`` et ``MED_Gen_Driver`` pour
+    l'implémentation des services spécifiques du composant MED.
+
+L'implémentation de ces interfaces est faites au niveau de différents
+packages des sources du module MED:
+
+* Le package ``MEDMEM_I`` qui fournit l'implémentation C++ des
+  interfaces décrites par le fichier ``MED.idl``;
+* Le package ``MED`` qui fournit l'implémentation C++ des interfaces
+  décrites par le fichier ``MED_Gen.idl``, et qui correspond à la
+  partie composant classique d'un module SALOME.
+* Le package ``MedCorba_Swig`` qui fournit une interface swig
+  générée à partir de l'implémentation C++ de ``MEDMEM_I`` et
+  ``MED``
+
+L'utilisation peut être illustrée au moyen d'exemples python (i.e. qui
+utilise l'interface swig fournie par MedCorba_Swig). Après l'import
+d'amorce systématique:
+
+.. code-block:: python
+   
+   import salome
+   salome.salome_init()
+   
+   import SALOME_MED
+   from libSALOME_Swig import *
+
+On peut charger le composant SALOME MED:
+
+.. code-block:: python
+   
+   medComp=salome.lcc.FindOrLoadComponent("FactoryServer", "MED")
+
+grâce auquel les services de chargement de la structure MED peuvent
+être invoqués. Par exemple, les commandes suivantes chargent toute la
+structure MED dans l'étude salome passée en argument:
+
+.. code-block:: python
+   
+   filePathName = "myfile.med"
+   medComp.readStructFileWithFieldType(filePathName,salome.myStudyName)
+
+Ce deuxième exemple charge la structure MED mais ne place pas le résultat dans l'étude:
+
+.. code-block:: python
+   
+   filePathName = "myfile.med"
+   medObj = medComp.readStructFile(filePathName,salome.myStudyName)
+
+On récupère à la place un objet de classe |LINK_EDF_SALOME_MED__MED|_
+qui permet une utilisation assez semblable (mais différente on le
+verra plus bas) à MEDMEM:
+
+.. code-block:: python
+
+   fieldIdx     = 1 # WRN maybe there is no field of idx=1
+   iterationIdx = 0
+   fieldName = medObj.getFieldNames()[fieldIdx]
+   dtitfield = medObj.getFieldIteration(fieldName,iterationIdx)        
+   it = dtitfield[0]
+   dt = dtitfield[1]
+   fieldObj = medObj.getField(fieldName,it,dt)
+   nbOfFields = medObj.getNumberOfFields()
+   fieldNames = medObj.getFieldNames()
+    
+   mesh = fieldObj.getSupport().getMesh()
+
+.. note::
+   Observations en vrac:
+
+   * Un FIELD_i possède un champ de type ``MEDMEM::FIELD_`` qui représente
+     le champ informatique réel (objet MEDMEM).
+   * FIELD_i::fieldMap variable static de type map qui semble gérer
+     les différentes instances de FIELD_i (~pattern factory). Cette
+     map peut être requétée au moyen d'un indice de type long  appelé
+     corbaIndex.
+   * Quand on crée un FIELD_i par le constructeur d'argument
+     ``MEDMEM::FIELD_``, le ``MEDMEM::FIELD_`` est ajouté dans la map avec
+     incrément du corbaIndex
+   * La fonction FIELD_i::read(i) redirige vers la fonction read(i) du
+     ``MEDMEM::FIELD_`` associé
+   * A CONFIRMER: Il semble que les fonctions de chargement
+     ``readStructFile*()`` charge toutes les données du fichier med,
+     alors qu'en MEDMEM seules les meta-données sont chargées.
+   * A CONFIRMER: il semble que le chargement d'une structure MED
+     CORBA peut se faire sans passer par le composant (cf. l'interface
+     de MED)
+
+Interface avec le module VISU
+=============================
+
+Des interactions sont possibles entre MED et VISU à partir du moment
+où les données med sont gérées dans l'étude, c'est-à-dire sous la
+forme d'objets SALOME_MED (voir ci-dessus) publiés dans l'étude. Les
+deux conditions sont aujourd'hui nécessaires (objet corba + publié
+dans l'étude) mais il semble que ce ne soit lié qu'à un choix
+d'interface VISU (la fonction ``ImportMed`` en particulier) qui peut
+a priori être modifié. A CONFIRMER.
+
+L'exemple de code ci-dessous (en python, mais il peut être transposé à
+une implémentation C++) montre par exemple comment envoyer au module
+VISU  une requête de visualisation d'un champs hébergé par le module
+MED (en fait, les données sont gérées au travers d'un objet corba
+SALOME_MED "délocalisé" et qui a été référencé dans l'étude dans la
+catégorie du composant MED). Les importations standard (salome,
+SALOME_MED, ...) sont supposées avoir été faites au préalable (voir
+les exemples précédents):
+
+.. code-block:: python
+   
+   # Load the med structure using MED
+   medComp=salome.lcc.FindOrLoadComponent("FactoryServer", "MED")
+   filePathName = "myfile.med"
+   medComp.readStructFileWithFieldType(filePathName,salome.myStudyName)
+    
+   # Get the VISU component
+   import VISU
+   visuComp = salome.lcc.FindOrLoadComponent("FactoryServer", "VISU")
+   visuComp.SetCurrentStudy(salome.myStudy)
+    
+   # Get the sobject associated to the med object named "Med"
+   aSObject = salome.myStudy.FindObject("Med")
+   isPresent, medSObj = aSObject.FindSubObject(1)
+    
+   # Finally, import the med sobject in VISU 
+   result = visuComp.ImportMed(medSObj)
+
+Il est possible de d'aller plus loin et par exemple de déclencher
+l'affichage d'une scalarmap d'un champ spécifique pour une itération
+particulière (voir la fonction
+``TEST_SALOMEMED_requestToVisu_scalarmap`` du fichier
+``SALOMEMED_tester.py`` fourni dans les sources d'exemple).
+
+Liens complémentaires:
+
+* http://nepal.der.edf.fr/pub/SALOME_userguide/VISU_V5_1_3/doc/salome/gui/VISU La documentation utilisateur en ligne du module VISU
+
+
+Notes en vrac
+=============
+
+Questions:
+
+* Comment obtenir le nom du fichier med à partir d'une structure med? 
+* Peut-on imaginer un moyen de fournir l'objet MEDMEM::MED à partir de
+  la donnée de l'objet CORBA SALOME_MED::MED?
+
+Remarques:
+
+* A part, les opérations arithmétiques (+,-,*,/), aucune opération
+  n'est définie.
diff --git a/src/MEDOP/doc/sphinx/fr/medop-prototype-overview.rst b/src/MEDOP/doc/sphinx/fr/medop-prototype-overview.rst
new file mode 100644 (file)
index 0000000..c571c6e
--- /dev/null
@@ -0,0 +1,95 @@
+.. meta::
+   :keywords: maillage, champ, manipulation, XMED
+   :author: Guillaume Boulant
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Démonstrateur XMED, vue d'ensemble
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Le module XMED est un espace d'expérimentation pour le développement
+des opérations de manipulation de champs. Il complète des
+développements intégrés directement dans le module MED et gérés dans
+la branche CVS BR_medop.
+
+Une maquette est au point pour illustrer les propositions en matière
+d'ergonomie d'utilisation et en matière d'architecture technique. La
+maquette permet de réaliser des cas d'utilisation de la forme:
+
+* Chargement d'un fichier med dans le module MED (ou publication par
+  un code de calcul).
+* Sélection graphique des champs de l'étude à mettre à disposition
+  dans la console utilisateur ("calculette" en mode texte qui
+  concraitement correspond à l'interface python de SALOME).
+* Dans la calculette, exécution d'opérations algébriques (+,-,*,/)
+  entre champs avec possibilité d'utiliser des scalaires dans des
+  opérations de type transformation linéaire (y=ax+b ou y et x sont
+  des champs et a et b des scalaires). Egalement quelques fonctions
+  mathématiques standard applicables sur des champs (pow, sqrt).
+* Possibilité de visualiser les champs produits avec VISU
+* Possibilité d'exporter des champs produits dans un fichier med
+
+La figure ci-dessous montre le résultat d'une séquence d'utilisation
+dans laquelle les champs "testfield1" et "testfield2" ont été
+sélectionnés dans l'arbre d'étude pour être utilisés dans la console
+textuelle sous les noms de variables f1 et f2. L'image montre le
+contrôle visuel du résultat de l'opération f1+f2-(f1-f2)^2 tapée en
+ligne de commande:
+
+.. image:: images/medop-gui-result.png
+   :align: center
+
+La séquence ci-après montre le cas d'utilisation complet en
+images:
+
+1. Sélection d'un champs sur un pas de temps dans l'arbre d'étude
+2. Saisie d'un nom de variable (alias) pour manipuler ce champ. Par
+   défaut, le nom du champ est proposé (``testfield1`` ici). Dans
+   l'exemple, l'utilisateur remplace par l'alias ``f1``.
+3. Contrôle visuel du champ ``testfield1`` manipulé par sa variable
+   ``f1`` au moyen de la commande ``f1.visu()``
+4. Chargement du champ ``testfield2`` sous le nom ``f2``, exécution de
+   l'opération ``f1+f2-(f1-f2)^2`` et contrôle visuel du résultat,
+   récupéré ici dans une variable de nom ``result``.
+
+.. |IMG_SELECT| image:: images/medop-gui-selectfield_scale.png
+.. |IMG_ALIAS| image:: images/medop-gui-aliasfield_scale.png
+.. |IMG_VISU| image:: images/medop-gui-visufield_scale.png
+.. |IMG_RESULT| image:: images/medop-gui-result_scale.png
+
++---------------+---------------+ 
+| |IMG_SELECT|  | |IMG_ALIAS|   |
++---------------+---------------+ 
+| |IMG_VISU|    | |IMG_RESULT|  |
++---------------+---------------+ 
+
+La solution technique est construite sur les principes suivants:
+
+* Les données MEDMEM sont physiquement chargées par le composant MED,
+  c'est-à-dire dans le processus ``Container`` de SALOME, et sont
+  référencées dans l'étude SALOME.
+* Les opérations sont physiquement des opérations entre objets MEDMEM
+  purs qui ont lieu dans le composant MED.
+* Les opérations sont pilotées par des objets proxy python instanciés
+  dans la console TUI puis manipulés par l'utilisateur. Ces objets
+  proxy savent accéder aux objets MEDMEM au travers de leur interface
+  CORBA.
+
+Ainsi, l'architecture technique est construite pour pouvoir travailler
+sur des données MEDMEM pur en partant de pointeurs CORBA manoeuvrés
+depuis des objets python dans l'interface textuelle de
+SALOME. L'effort principal a donc porté sur la mise au point de
+l'interface technique qui permet de lier des variables représentant
+les champs au niveau du GUI (techniquement, la calculette est
+l'interpréteur python embarqué dans le GUI, étendu de quelques
+fonctions pour la manipulation de champs), alors que les données
+MEDMEM sont physiquement disponibles uniquement au niveau des
+composants CORBA (et les opérations implémentées dans MEDMEM
+uniquement).
+
+Pour le moment, la maquette est limitée à des operations entre champs
+qui partagent le même support med (contrainte de MEDMEM) et le
+résultat est calculé sur toutes les composantes et tout le domaine de
+définition du champs (cette deuxième contrainte est juste parce que
+les extentions n'ont pas encore été examinées). Enfin, le support de
+gestion des données est supposé être l'étude SALOME et la structure
+MED qui y est publiée.
diff --git a/src/MEDOP/doc/sphinx/fr/medop-references.rst b/src/MEDOP/doc/sphinx/fr/medop-references.rst
new file mode 100644 (file)
index 0000000..9be8cdc
--- /dev/null
@@ -0,0 +1,28 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ANNEXE: Références documentaires
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. include:: medop-definitions.rst
+
+Documents de référence:
+
+* |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009
+* |REF_CEA_VBE_MEDMEM|_ - Vincent Bergeaud - janvier 2007
+* |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF)
+
+Présentations:
+
+* |REF_EDF_PRESMANIPCHP01|_ - Valérie Cano, Guillaume Boulant - janvier 2010
+* |REF_EDF_PRESMANIPCHP02|_ - Guillaume Boulant - octobre 2010
+* |REF_EDF_PRESMANIPCHP03|_ - Guillaume Boulant - mars 2011
+* Présentation à la Journée des Utilisateurs de SALOME de 2011 (JUS2011):
+
+  - |REF_EDF_JUS2011_PDF|_ - Anthony Geay (CEA), Guillaume Boulant - novembre 2011
+  - |REF_EDF_JUS2011_OGV1|_
+  - |REF_EDF_JUS2011_OGV3|_
+  - |REF_EDF_JUS2011_OGV4|_
+
+Notes de travail:
+
+* |REF_EDF_GBO_WORKNOTE|_ - Guillaume Boulant - novembre 2010
+* |REF_EDF_ELO_REM|_ - Eric Lorentz - novembre 2010
diff --git a/src/MEDOP/doc/sphinx/fr/medop-specifications.rst b/src/MEDOP/doc/sphinx/fr/medop-specifications.rst
new file mode 100644 (file)
index 0000000..09ca88c
--- /dev/null
@@ -0,0 +1,916 @@
+.. meta::
+   :keywords: maillage, champ, manipulation, med
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Module MED: Spécifications fonctionnelles et techniques
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Ce texte présente les spécifications informatiques pour le
+développement d'un module de manipulation de champs qui répond à
+l'expression de besoins formulée dans le cahier des charges
+|REF_EDF_VCA_H-I2C-2009-03595-FR|_.
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Description des cas d'application de référence
+==============================================
+
+Plusieurs cas d'applications métier sont identifiés pour piloter le
+développement du module de manipulation de champs:
+
+* **Analyser et post-traiter le résultat d'un calcul**. C'est l'usage
+  principal qui consiste typiquement à créer des champs comme le
+  résultat d'*opérations mathématiques* dont les opérandes sont des
+  champs et des scalaires. On compte également dans cette catégorie
+  les *opérations de restriction* qui permettent d'extraire puis
+  utiliser une partie d'un champs, c'est-à-dire de créer un champ
+  comme la restriction d'un autre champ à une partie de son domaine de
+  définition (certaines composantes, certains pas de temps, limitation
+  à un groupe de mailles).
+* **Comparer des champs issus d'un calcul paramétrique**. Il s'agit
+  d'une variante du cas précédent qui consiste à mesurer et visualiser
+  les variations entre des champs issues de sources de données
+  différentes (différents fichiers med).
+* **Préparer les conditions aux limites d'une calcul**. Il s'agit de
+  pouvoir initialiser un champ sur un maillage ou un groupe de
+  mailles, c'est-à-dire créer un champ de toute pièce sur un
+  support spatial donné, par exemple par la donnée d'une fonction
+  mathématique qui donne les valeurs des composantes en fonction des
+  coordonnées spatiales.
+* **Gérer des données de calcul**. Il s'agit typiquement de pouvoir
+  rassembler au sein d'un même fichier med des champs et des maillages
+  issues de différentes sources de données, et/ou créés au travers des
+  cas d'application présentés ci-dessus.
+
+Modèle conceptuel des données
+=============================
+
+On rappelle ici les concepts utilisés dans le module et les modalités
+d'utilisation de ces concepts. Le point de vue est celui de
+l'utilisateur du module de manipulation de champs. Il s'agit
+essentiellement pour le moment d'éclaircir l'ergonomie d'usage sur le
+plan conceptuel, avant d'aborder la déclinaison en spécifications
+techniques pour lesquelles les particularités du modèle MED devront
+être intégrées à la réflexion.
+
+Concept de champ
+----------------
+
+Le concept central est celui de *champ*, c'est-à-dire une grandeur
+physique exprimée sur un domaine spatial D. La grandeur peut être de
+type scalaire (une température), de type vectorielle (une vitesse) ou
+de type tensorielle (les contraintes). En un point de l'espace, elle
+se définie donc par la donnée d'une ou plusieurs valeurs numériques
+appelées les *composantes* (1 pour un champ scalaire, 3 pour un champ
+vectoriel 3D, 6 pour un champ tensoriel symétrique 3D).
+
+.. note:: Une pratique courante au niveau des codes est de stocker
+   plusieurs grandeurs physiques différentes dans un même champs med
+   (au sens informatique du terme). Par exemple, le champ
+   électromagnétique à 6 composantes, plus le champ de température
+   scalaire peuvent techniquement être stockés dans un même champs med
+   à 7 composantes. C'est pourquoi, le module de manipulation de
+   champs doit fournir des fonctions de restrictions qui permettent
+   d'extraire certaines composantes pour former la grandeur physique à
+   étudier. Dans la suite du document, on part du principe que l'on
+   peut se ramener dans tous les cas au cas d'un champ homogène tel
+   que défini plus haut.
+
+Dans le cadre d'un modèle numérique discret, les valeurs du champ sont
+exprimées pour un nombre fini de positions, qui correspondent à des
+lieux particuliers du maillage. Suivant la nature des modèles de
+calcul, les valeurs peuvent être données par cellule, par face, par
+noeud, aux points de gauss, ...
+
+Ainsi, un champ discret est un objet dont les valeurs peuvent être
+lues selon les dimensions suivantes:
+
+* *La position p dans l'espace*, caractérisée par le type de l'élément
+  de maillage support et son numéro identifiant
+* *La composante c*, caractérisée par son indice (jusqu'à 6
+  composantes dans les modèles physiques envisagés)
+
+L'évolution d'un champ dans le temps peut être exprimée sous la forme
+d'une série temporelle, c'est-à-dire une séquence de champs donnés
+pour des instants discrets. Aussi, si l'on manipule un champ qui varie
+dans le temps, l'accès aux valeurs introduit une dimension
+supplémentaire:
+
+* *Le temps t*, caractérisé par un numéro de pas de temps
+  (correspondant en général à une étape du calcul qui a produit le champ).
+
+.. note:: Il s'agit là d'une représentation conceptuelle standard dont
+   le |LINK_EDF_MEDDOC|_ fait une expression détaillée. En
+   particulier, la position p est déterminée par la donnée du type
+   d'élément support (valeurs aux noeuds, aux mailles, aux noeuds par
+   éléments, aux points de gauss) et de l'indice de cet élément. En
+   général, le type d'éléments support est résolu à l'initialisation
+   et l'indice peut suffire au repérage dans les algorithmes. Le temps
+   t est déterminé par un numéro d'itération, qui peut éventuellement
+   être complété par un numéro d'ordre. Le cas des points de gauss
+   ajoute un cran de complexité dans la mesure où il faut repérer
+   l'entité géométrique (maille, face, arrête) puis le point de gauss
+   de cette entité. A noter que dans le modèle MED, le concept de
+   série temporelle de champ n'est pas explicitement définie et
+   l'accès à des valeurs à différents instants t1 et t2 nécessite le
+   chargement des champs ``F1=F(t1)`` et ``F2=F(t2)``.
+
+Par convention, on utilisera par la suite les notations:
+
+* **U(t,p,c)** pour désigner la valeur de la composante c d'un champ U
+  à la position p et prise à l'instant t; 
+* **U(t,p,:)** pour signifier que l'on manipule l'ensemble de toutes
+  les composantes;
+* **U(t,:,c)** pour signifier que l'on manipule le domaine de
+  définition spatial complet. 
+
+Dans une grande majorité des cas d'usage on travaille à temps t fixé
+et sur un domaine spatiale prédéfini. Aussi on utilisera également la
+notation à deux arguments ``U(:,:)`` ou tout simplement ``U`` (dès
+lors qu'il n'y a pas ambiguïté) pour désigner un champ complet et Uc
+pour désigner la composante c du champ avec c=1..6.
+
+Concept d'opération
+-------------------
+Le deuxième concept à préciser est la notion d'*opération*. Une
+opération dans le présent contexte est l'application d'un opérateur
+sur un ou plusieurs champs pour produire une grandeur de type champ ou
+de type valeur numérique.
+
+Par exemple, la formule ``W=OP(U,V)`` indique que le champ W est formé
+à partir des champs U et V en arguments d'une fonction OP. Dans le cas
+d'une opération algébrique comme l'addition (cf. :ref:`Spécification
+des opérations<xmed-specifications>`, le résultat attendu par défaut
+est que pour chaque instant t, chaque position p et chaque composante
+c, on a ``W(t,p,c)=U(t,p,c)+V(t,p,c)`` (que l'on peut noter également
+``W(:,:,:)=U(:,:,:)+V(:,:,:)`` compte-tenu de la convention présentée
+plus haut). Ce n'est cependant pas une règle et l'utilisateur peut
+très bien manoeuvrer les champs en détaillant et mixant les
+composantes (par exemple ``W(:,:,3)=5+U(:,:,1)*V(:,:,2)``), ou encore
+ne travailler que sur un domaine spatial et/ou temporel particulier
+(cf. |REF_EDF_VCA_H-I2C-2009-03595-FR|_ §5.4.1).
+
+On formalise donc le concept d'opération par les propriétés suivantes:
+
+* L'opérateur peut produire un champ (par exemple la somme de deux
+  champs W=sum(U,V)=U+V), une valeur numérique (par exemple la moyenne
+  spatiale d'un champ m=smoy(U)) ou une valeur logique (par exemple le
+  test d'égalité de deux champs b=isequal(U,V));
+* L'opérateur peut être paramétré par la donnée de valeurs numériques
+  (par exemple, le changement d'unité peut être défini comme une
+  multiplication par un scalaire V=multiply(U,1000)=1000*U);
+* L'opérateur est caractérisé par un domaine d'application qui
+  spécifie la portée de l'opération. Ce domaine comporte plusieurs
+  dimensions:
+  - Un domaine temporel T qui spécifie les pas de temps sur lesquels
+    l'opération est appliquée;
+  - Un domaine spatial D qui spécifie la limite de portée de
+    l'opérateur et donc le domaine de définition du champ produit (qui
+    correspond dans ce cas à une restriction du domaine de définition
+    des champs en argument);
+  - Un domaine de composantes C qui spécifie les composantes sur
+    lesquelles l'opération est appliquée;
+
+.. note::
+   Sur le plan informatique, l'opérateur aura également un paramètre
+   appelé *option* qui pourra indiquer par exemple dans une
+   opération unaire V=F(U) si le résultat V est une nouvelle instance
+   de champ ou la valeur modifiée du champ de départ U. Il pourra
+   également être amené à manoeuvrer des paramètres de type chaîne de
+   caractères, par exemple pour les opérations de changement de nom
+   des champs.
+
+De manière générale, on utilisera la notation
+**(W|y)=OP[D,C,T](P,U,V,...)** pour désigner une opération OP:
+
+* **(V|y)**: V ou y désignent respectivement un résultat de type
+  champ ou de type valeur numérique ou logique;
+* **[T,D,C]**: le domaine d'application de l'opérateur avec T le
+  domaine temporel, D le domaine spatial et C le domaine des
+  composantes;
+* **P,U,V,...**: les paramètres numériques P (liste de valeurs
+  numériques) et les champs U,V,... en arguments de l'opérateur;
+
+On note également les particularités suivantes pour certaines
+opérations:
+
+* Le domaine de définition du champ produit par une opération peut
+  être différent du domaine de définition des champs en argument. Par
+  exemple, dans le cas d'une opération de projection de champ, le
+  domaine spatial résultat peut être modifié par rapport au domaine de
+  définition initial, soit par la modification de la zone géométrique,
+  soit par modification des entités de maillage support.
+* En dehors des opérations de type dérivée et intégrale, les valeurs
+  résultats sont déterminées de manière locale en chaque point du
+  domaine d'application. Par exemple, l'addition W=U+V consiste à
+  produire un champ W dont les valeurs en chaque point p sont la somme
+  des valeurs des composantes de U et V en ce point p: ``W=U+V <=>
+  W(:,p,:)=U(:,p,:)+V(:,p,:)`` pour tout point p du domaine
+  d'application D.
+
+Concept de domaine d'application
+--------------------------------
+
+Un domaine d'application est associé à une opération (et non pas à un
+champ). Il a pour objectif de restreindre la portée de l'opération en
+terme spatial, temporel, jeu des composantes.
+
+Pour ce qui concerne le domaine spatial D, plusieurs modalités de
+définition sont envisagées:
+
+* la donnée d'un maillage ou d'un groupe d'éléments du maillage;
+* un système de filtres qui peut combiner:
+
+  - une zone géométrique définie indépendamment du maillage (boîte
+    limite par exemple),
+  - des critères conditionnant le calcul (par exemple U(t,p,c)=1 si
+    V(t,p,c)<seuil).
+
+.. warning:: Version 2010: D pourra correspondre au maillage complet
+   et dans la mesure du possible à un groupe d'éléments du maillage
+
+Ce domaine d'application peut être différent du domaine de définition
+des champs mais il doit être compatible (recouvrement spatial partiel
+au moins et même support d'entité de maillage). Ainsi, sans précision
+particulière, une opération s'applique à l'ensemble du domaine de
+définition des champs en argument (qui dans la pratique MED est
+spécifié par le support et correspond en général au maillage
+complet).
+
+Limites d'utilisation
+---------------------
+
+Plusieurs situations doivent être examinées pour poser les limites
+d'utilisation:
+
+* Les champs en argument n'ont pas tous le même domaine de définition,
+  par exemple parcequ'il ne sont pas définis sur les mêmes zones
+  géométriques ou parcequ'ils ne sont pas donnés sur le même type
+  d'entité de maillage. On peut imaginer dans ce cas produire le
+  résultat sur les zones de recouvrement uniquement.
+* Le domaine de définition des champs et le domaine d'application de
+  l'opérateur ne sont pas compatibles, par exemple parcequ'on demande
+  une restriction sur une zone géométrique qui ne fait pas partie de
+  la zone de définition du champ d'entrée. A priori, ce type
+  d'opération est déclaré en échec.
+* Les champs en argument ne sont pas définis sur les mêmes pas de
+  temps. Si l'opération est tolérée (techniquement MEDCoupling permet
+  de le faire), le pas de temps résultat est indéfini.
+
+.. warning:: **A faire**: spécifier les modalités de prise en compte de
+   ces différentes situations (au moins sur le plan conceptuel).
+
+Au delà de ces limites conceptuelles, il faut avoir en tête les
+limites techniques liées à l'usage de MED mémoire (paquet
+MEDCoupling). Par exemple, MEDCoupling impose que les champs opérandes
+soient définis sur le même maillage support (on parle ici de l'objet
+informatique correspondant au maillage). Deux champs construits sur le
+même maillage (du point de vue conceptuel) mais issus de deux fichiers
+med différents sont considérés comme des champs définis sur des
+maillages support différents, c'est-à-dire que les objects
+informatiques correspondant aux maillages sont différents (chargés de
+deux fichiers différents). En l'état, il est donc impossible par
+exemple de faire la comparaison de champs résultats d'une étude
+paramétriques. MEDCoupling fournit une solution qu'il faudra mettre en
+oeuvre de manière ergonomique au niveau du module MED. Il est possible
+de changer le maillage support M1 d'un champs par un maillage M2 à
+partir du moment où les maillages M1 et M2 sont identiques
+géométriquement à une erreur près qu'il est possible de spécifier.
+
+.. note:: 
+   D'autres situations limites peuvent être évoquées sous l'angle
+   informatique. Ce sont des situations qui a priori n'ont pas de
+   raison d'exister sur le plan conceptuel mais qui peuvent très bien
+   survenir au niveau du module informatique compte-tenu des
+   particularités du modèle MED. Par exemple:
+   
+   * Le nombre et la nature des composantes ne sont pas identiques
+     pour tous les champs d'entrée. Par exemple, U défini ses
+     composantes comme U(:,:,1)=Ux, U(:,:,2)=Uy, U(:,:,3)=Uz et V les
+     défini comme U(:,:,1)=Uz, U(:,:,2)=Ux, U(:,:,3)=Uy. Cette
+     situation peut être gérée techniquement par exemple au moyen
+     d'une carte de correspondance qui accompagnerai chacun des champs
+     pour exprimer le sens physique de chaque composants (histoire de
+     ne pas ajouter des choux et des carottes).
+
+Spécifications générales
+========================
+
+Le diagramme ci-dessous représente un découpage fonctionnel qui rend
+compte de l'expression des besoins:
+
+.. image:: images/xmed-functions.png
+   :align: center
+
+On peut identifier les fonctionnalités suivantes:
+
+* **Opérations**: fonctions de manipulation de champs proprement
+  dites;
+* **Persistance**: fonctions d'enregistrement persistant et de
+  chargement des données (au format med fichier)
+* **Visualisation**: fonctions de contrôle visuel des champs
+  manipulés
+* **Export des données**: fonction de transposition des données de
+  champs dans un format textuel directement exploitable et de manière
+  autoportante dans une autre application, par exemple en python au
+  moyen des structures de données Numpy.
+
+Ces fonctions s'articulent autour d'un conteneur qui héberge les
+champs manipulés et les supports de ces champs (représenté par le
+cylindre central).
+
+Un scénario d'utilisation type est:
+
+* Préparation des champs à manipuler, par deux moyens complémentaires:
+
+  - Utilisation des fonctions de persistance: chargement depuis un
+    fichier med d'un ensemble de champs qui partagent le même espace
+    de définition;
+  - Utilisation des opérations de champs: chargement d'un maillage
+    depuis un fichier med, puis création ab initio de champs au moyen
+    des opérations de champs;
+
+* Manipulation des champs par application des opérations à
+  disposition, puis contrôle visuel des résultats produits au moyen
+  des fonctions de visualisation mises à disposition par SALOME;
+* Restitution des résultats produits, par deux moyens complémentaires:
+
+  - Restitution des champs produits et/ou modifiés sous une forme
+    persistante (fichier med);
+  - Restitution d'une partie seulement des résultats sous forme de
+    tableaux de valeurs sauvegardés dans un fichier texte ou exporté
+    sous forme de tableau numpy
+
+.. _xmed-specifications:
+
+Spécification des opérations
+============================
+
+Le cahier des charges définit trois catégories d'opérations
+mathématiques:
+
+* **Les opérations arithmétiques**, dans lesquelles le résultat à la
+  position p et à l'instant t ne dépend que des données à la position
+  p et à l'instant t;
+* **Les opérations d'interpolations**, dans lesquelles le résultat
+  est exprimé sur des entités de maillages différentes ou est projeté
+  sur une zone géométrique différente du domaine de définition
+  initial;
+* **Les opérations globales**, dans lesquelles le résultat peut
+  demander l'agrégation des valeurs sur plusieurs position p ou
+  plusieurs pas de temps t (calcul d'extremum, d'intégrale);
+
+Auxquelles, on peut ajouter à des fins de gestion des données:
+
+* **Les opérations de génération**, qui permettent de créer un champ
+  sur un maillage vierge ou d'étendre le domaine spatial de définition
+  d'un champ;
+* **Les opérations d'ordre sémantique**, qui permettent de modifier
+  les méta-données associées aux champs (nom, unité, ...)
+* **Les opérations de diagnostic**, qui permettent d'effectuer une
+  analyse particulière d'un champ et/ou des éléments de maillage
+  associés et de fournir un compte-rendu, sous la forme d'une
+  structure de données ou d'un texte formaté affichable dans
+  l'interface utilisateur.
+
+La suite de la section décrit les spécifications prévues pour chaque
+type d'opération unitaire. Un dernier paragraphe concerne les
+modalités de combinaison des opérations et spécifie la définition d'un
+domaine d'application sur une opération, qui permet de restreindre la
+portée de l'opération en terme spatial, temporelle ou nature des
+composantes impliquées.
+
+Les opérations arithmétiques
+----------------------------
+
+Les opérations arithmétiques regroupent:
+
+* les **opérations algébriques** (+, -, x, /);
+* les **opérations vectorielles** (produit scalaire, produit
+  vectoriel, produit tensoriel);
+* l'**application d'une fonction mathématique** à variable scalaire
+  (exponentielle, logarithme, fonctions trigonométriques, valeur
+  absolue, partie entière) ou à variable de type champ (les fonctions
+  de norme par exemple).
+
+Pour les besoins des spécifications informatiques, il est plus commode
+de classer ces opérations en deux catégories:
+
+* les **opérations unaires**, qui prennent un opérande unique en
+  argument. C'est le cas de la plupart des fonctions mathématiques
+  envisagées;
+* les **opérations binaires**, qui prennent deux opérandes en
+  argument. C'est le cas des opérations algébriques et des opérations
+  vectorielles.
+A partir de cette classification, il convient de distinguer trois
+formes d'usage selon la nature des opérandes:
+
+* les opérandes sont exclusivement des scalaires (typiquement des
+  valeurs de composantes des champs et des paramètres numériques). Par
+  exemple::
+    W(:,:4) = 1+2xU(:,:,2)+V(:,:,3)
+
+* les opérandes sont exclusivement des champs. Par exemple::
+
+    W = U + V       (addition)
+    W = U ^ V       (produit vectoriel)
+
+* les opérandes sont des champs et des paramètres numériques. Par exemple::
+
+    W = 3xU - 2xV
+    W = U + 2
+
+Le premier cas de figure (opérandes scalaires) est trivial car les
+règles mathématiques conventionnelles s'appliquent et sont
+implémentées dans tous les langages (Python et C++ en
+particulier). Les cas 2 et 3 par contre doivent être précisés car (i)
+les règles de comportement ne peuvent pas être simplement déduites des
+règles mathématiques (quel est le résultat de ``W = U + 2`` ?) et
+(ii) certaines écritures ne peuvent avoir aucun sens (par exemple
+``W = 2 / U``). Il convient donc de  préciser les conventions et
+les limites sur ces deux cas de figure.
+
+Dans le cas des opérations unaires où l'opérande est un champ, on doit
+distinguer deux cas d'usage:
+
+* l'application d'une fonction mathématique à valeur de type champ. Ce
+  cas est trivial également et on applique la règle d'usage de la
+  fonction. C'est typiquement le cas des fonctions de calcul de
+  norme.
+* l'application d'une fonction mathématique à valeur scalaire. Dans ce
+  cas, on convient d'appliquer la fonction de manière unitaire sur
+  chacune des composantes c du champ: ``W(:,:,c) = OP( U(:,:,c)
+  )``
+
+Dans le cas des opérations binaires, on recense les combinaisons
+d'opérandes suivantes (les lettres capitales représentent des champs,
+et les lettres minuscules une valeur scalaire qui peut être un
+paramètre numérique ou la composante d'un champ):
+
+* U+V ajoute les composantes en regard: W(:,:,c)=U(:,:,c)+V(:,:,c)
+* U-V soustrait les composantes en regard: W(:,:,c)=U(:,:,c)-V(:,:,c)
+* U*V multiplie les composantes en regard: W(:,:,c)=U(:,:,c)*V(:,:,c)
+* U/V divise les composantes en regard: W(:,:,c)=U(:,:,c)/V(:,:,c)
+* U+x ajoute x à toute les composantes: W(:,:,c)=U(:,:,c)+x
+* U*x multiplie toutes les composantes par x: W(:,:,c)=U(:,:,c)*x
+* U.V produit scalaire des champs U et V: W(:,:c)=U(:,:,c)*V(:,:,c)
+* U^V produit vectoriel des champs U et V: W(:,:1)=U(:,:,2)*V(:,:,3)-U(:,:,3)*V(:,:,2), ...
+
+.. note::
+   Pour ce qui concerne les opérations vectorielles, un convention
+   implicite est appliquée par laquelle on suppose que les composantes
+   sont rangées dans l'ordre des dimensions spatiales U1=Ux, U2=Uy,
+   U3=Uz. Sur le plan informatique au niveau du modèle MEDMEM, ceci
+   n'est pas garanti et aucun élément du modèle ne permet de
+   contraindre l'application de cette convention. Il convient donc de
+   prévoir des fonctions techniques qui permettront de mettre en
+   correspondance les indices de composantes et les dimensions
+   spatiales (par exemple par la données d'une carte de correspondance
+   applicable à un ensemble de champs).
+
+.. warning::
+   A développer:
+   
+   * Analyse dimensionnelle du champ résultats pour adapter
+     l'unité. Par exemple, si on fait UxV où U et V sont exprimés en
+     [m] alors le résultat est en [m2].
+
+Les opérations d'interpolation
+------------------------------
+.. warning:: Non prévues au programme 2010.
+
+Les opérations mathématiques globales
+-------------------------------------
+.. warning:: Non prévues au programme 2010.
+
+Les opérations de génération
+----------------------------
+.. warning:: EN TRAVAUX
+
+Les opérations de génération sont des fonctions qui permettent de
+créer un champ sur un domaine du maillage où il n'est pas défini
+initialement. Deux cas de figure peuvent se présenter:
+
+* Le champ n'existe pas et il doit être créé sur un domaine à définir;
+* Le champ existe mais les valeurs ne sont pas définies sur l'ensemble
+  du maillage.
+
+On peut envisager plusieurs modalités de mise en oeuvre:
+
+* le prolongement par une valeur constante (ou plus généralement par
+  une fonction de l'espace?);
+* les valeurs du champs sont données par une fonction f(p,t) qui prend
+  la position p et le pas de temps t en argument;
+* on peut prédéfinir le champ position **r** qui porte les
+  coordonnées spatiales de l'élément de maillage support, puis faire
+  une opération arithmétique standard.
+
+Les opérations d'ordre sémantique
+---------------------------------
+.. warning:: EN TRAVAUX
+
+Concerne:
+
+* le changement de nom du champ
+* le changement d'unité du champ (il s'agit ici de conserver la
+  cohérence entre la valeur numérique et l'attribut "unité" d'un
+  champ.
+
+Les opérations de diagnostic
+----------------------------
+.. warning:: EN TRAVAUX. A faire en fonction des besoins des cas d'application
+
+On peut identifier plusieurs types d'opérations:
+
+* les opérations à diagnostic booléen, par exemple
+  b=isequal(U,V)=[U=V] (où [.] signifie évaluation de la condition
+  entre crochers)
+* les opérations à diagnostic textuel, par exemple afficher les
+  méta-données associées à un champs (unité, nom, maillage support,
+  type d'entité, pas de temps, ...)
+* les opérations à diagnostic structuré, qui donneraient une structure
+  de données exploitable au niveau d'un code logiciel.
+
+Combinaison des opérations
+--------------------------
+.. warning:: EN TRAVAUX. Indiquer les règles de combinaison (associativité, commutativité, ...)
+
+Définition d'un domaine d'application
+-------------------------------------
+Pour rappel, un domaine d'application peut être associé à une
+opération pour restreindre la portée de l'opération en terme spatial,
+temporelle ou nature des composantes impliquées.
+
+.. warning:: Todo: spécifier comment on le définit et les modalités d'applications.
+
+Spécification de l'ergonomie
+============================
+
+L'ergonomie générale d'utilisation du module de manipulation de champs
+est inspirée des logiciels comme octave ou scilab. Elle associe une
+interface graphique, pour sélectionner et préparer les données, avec
+une interface texte (la console python) pour le travail effectif sur
+les données:
+
+* L'**interface graphique** a pour fonction essentielle de sélectionner et
+  préparer les champs à manipuler dans l'interface texte, puis
+  fournit des fonctions pour la gestion générale des données
+  (chargement, sauvegarde, contrôle visuel, export).
+* L'**interface texte** offre un jeu de commandes pour manipuler les
+  champs (afficher les données, effectuer des opérations), piloter les
+  fonctions d'affichage (contrôle visuel au moyen des modules VISU
+  et/ou PARAVIS) et communiquer avec l'interface graphique (ajouter
+  des nouveaux champs dans l'espace de gestion, mettre à jour les
+  méta-données d'un champ).
+
+Sur le plan de l'ergonomie, cela se traduit par un processus de
+travail dans lequel on peut distinguer différentes phases:
+
+* Une phase de préparation des champs à manoeuvrer sous la forme de
+  variables nommées et simples à manipuler dans l'interface
+  textuelle. Lors de cette phase, l'utilisateur spécifie de manière
+  graphique tout ce qui peut être définis à l'avance et pour toute la
+  durée du processus de travail. Par exemple, en spécifiant le nom des
+  fichiers med source des données et les noms des champs à utiliser
+  dans ces fichiers, le pas de temps de travail, le jeu des
+  composantes à considérer, le domaine d'application des opérations;
+* Une phase de manipulation des champs proprement dite, qui a lieu
+  principalement dans l'interface textuelle, et qui peut s'accompagner
+  de contrôle visuel des résultats et/ou d'export à destination
+  d'outils complémentaires indépendants (gnuplot, python, ...);
+* Une phase de restitution des champs produits pour assurer la
+  persistance des données de travail. Tout les champs créés par les
+  manipulations au niveau de l'interface textuelle ne sont pas à
+  sauvegarder, et on on propose donc à l'utilisateur les moyens de
+  choisir les champs à conserver. Cette phase peut amener
+  l'utilisateur à préciser les informations manquantes, comme les noms
+  de fichiers, les noms de champs produits, les unités, ...
+
+Dans ce cadre, l'utilisation type des fonctions de manipulation de
+champs est un processus de la forme suivante:
+
+1. Chargement d'un fichier med dans SALOME et exploration du contenu,
+   composé de maillages, sur lesquels sont définis des champs, pouvant
+   contenir un ou plusieurs pas de temps.
+2. Sélection (graphique) des champs à manipuler, avec la possibilité
+   de préciser des restrictions d'utilisation (pas de temps,
+   composantes, groupe de maille).
+3. Création de nouveaux champs par l'exécution d'opérations
+   algébriques (+,-,*,/) entre champs, l'application de fonctions
+   mathématiques standard (pow, sqrt, abs), ou encore l'initialisation
+   "from scratch" à partir d'un maillage support.
+4. Contrôle visuel rapide des champs produits (avec les modules VISU
+   et/ou PARAVIS de SALOME, pilotés automatiquement depuis l'interface
+   utilisateur)
+5. Enregistrement d'une partie des champs produits dans un fichier med
+
+
+Les espaces de données utilisateur
+----------------------------------
+
+Sur le plan conceptuel, on est amené à définir deux espaces de données
+utilisateur:
+
+* **l'espace des données source** (*dataspace*), dans lequel
+  l'utilisateur définit les sources de données med (*datasource*),
+  c'est-à-dire les fichiers med dans lesquels sont lus les champs
+  et maillages. Cet espace est en lecture seule et permet
+  l'exploration des sources de données (aperçu des maillages et des
+  champs).
+* **l'espace des données de travail** (*workspace*), dans lequel
+  l'utilisateur dépose les champs et maillages à utiliser, puis range
+  les champs produits au travers des fonctions de manipulation de
+  champs.
+
+La figure ci-dessous en donne une représentation imagée avec le
+support de l'interface graphique du module (interface non définitive
+affichée ici pour illustration des spécifications):
+
+.. image:: images/xmed-gui-withframe.png
+   :align: center
+
+.. note:: Techniquement, les données sources sont rangées dans l'étude
+   SALOME et peuvent être explorées au moyen de l'object browser. Les
+   données de travail sont rangées dans un arbre complémentaire et
+   manipulable dans la console python.
+
+Le principe général est que **les données sources ne sont jamais
+modifiées**. Le dataspace est un espace de chargement qui permet
+d'explorer puis de sélectionner les données à manipuler. L'utilisateur
+travaille à partir de maillages et de champs chargés préalablement
+dans cet espace, mais ne peut en aucun cas les modifier
+directement. Pour cela, il doit d'abord les sélectionner pour
+utilisation dans l'espace de travail. Ce choix garantie l'intégrité
+des sources de données et permet de rejouer la séquence de travail à
+partir de zéro en cas de besoin (on efface le tableau noir et on
+recommence). Par ailleurs, il permet d'assister graphiquement la
+définition du champs à manipuler effectivement, en particulier pour
+affecter un nom de variable de manipulation.
+
+Les captures d'écrans suivantes montrent le principe d'utilisation sur
+le cas de la sélection d'un pas de temps à utiliser dans l'espace de
+travail. Les données à manoeuvrer (maillage et/ou champs) sont
+sélectionnées pour utilisation dans l'espace de travail, où elles
+peuvent être modifiées et/ou utilisées dans les opérations de
+champs. Ici, le champ est désigné par la varibale ``f4`` dans
+l'interface textuelle:
+
+* Sur cette première capture, on sélectionne le pas de temps n°4 du
+  champs ``Pulse`` définit sur le maillage ``Grid_80x80`` de la source
+  de données ``timeseries.med`` (concrètement le fichier
+  ``timeseries.med``) pour faire apparaître ensuite le menu contextuel
+  et choisir l'option "Use in workspace":
+
+.. image:: images/xmed-gui-datasource-contextmenu_70pc.png
+   :align: center
+
+* Cette capture montre une fenêtre de dialogue qui invite
+  l'utilisateur à spécifier un alias pour la variable python qui
+  va permettre la manipulation du champ dans l'interface textuelle de
+  l'espace de travail (par défaut, le nom complet du champ est
+  proposé). Ici, l'utilisateur spécifie ``f4``: 
+
+.. image:: images/xmed-gui-datasource-useinworkspace_70pc.png
+   :align: center
+
+* La validation de la fenêtre provoque l'ajout du champs dans l'espace
+  de travail (le champ est désormais disponible à la manipulation) et
+  définit une variable python de nom ``f4`` qui permet la manipulation
+  du champ:
+
+.. image:: images/xmed-gui-datasource-useinworkspace-result_70pc.png
+   :align: center
+
+Modalités d'utilisation
+-----------------------
+
+.. warning:: cette section est à nettoyer car elle contient des
+   informations redondantes avec d'autres sections précédentes ou pire
+   qui contredisent des sections précédentes.
+
+Dans le cadre défini ci-dessus, une session d'utilisation type est:
+
+* Sélectionner les sources de données puis définir le domaine
+  d'application (espace, temps, composantes), avec éventuellement
+  l'assistance d'une interface graphique;
+* Charger les champs en conséquence dans l'espace de travail. Cette
+  opération propose de définir une variable python pour manipulation
+  dans l'interface textuelle.
+* Effectuer les opérations dans l'espace de travail, c'est-à-dire en
+  ligne de commandes python (ce qui demandera sans doute un travail
+  conséquent de simplification et d'assistance en ligne). Par exemple,
+  si ``fa`` et ``fb`` désignent deux champs définis dans l'espace de
+  travail, alors on peut en faire la somme par la commande::
+  
+  >>> r=fa+fb
+
+* Effectuer les contrôles visuel et les diagnostics en ligne de
+  commandes python (cf. :ref:`Spécification des fonctions de
+  visualisation<specification_visualisation>`)::
+
+  >>> view(r)
+
+* Enregistrer les champs produits dans l'espace de travail sous forme
+  de fichier med.
+
+Sur cette base, on peut envisager une grande variété de cas d'utilisation:
+
+* La structure MED (champs, maillage et groupes de mailles) est
+  chargée dans le dataspace (l'étude SALOME techniquement) et peut
+  être explorée au niveau de l'arbre d'étude. L'arbre peut faire
+  apparaître:
+  - les maillages et les groupes (qui peuvent être utilisés
+    éventuellement pour restreindre le domaine d'application)
+  - les champs dont on peut explorer les composantes et les itérations
+
+* On sélectionne plusieurs champs, éventuellement en sélectionnant les
+  pas de temps, les composantes et les domaines d'application spatiaux
+* Menu contextuel --> Modifier un champ, Créer un champ, Prolonger un
+  champ, ....
+* On choisi pour la suite "Créer un champ", une fenêtre de dialogue
+  s'affiche avec les saisies préremplies avec les données
+  sélectionnées. Il est possible de rajouter des éléments ou préciser
+  le domaine d'application
+* Une partie de la boîte de dialogue est réservée à la saisie de la
+  ligne de commande python qui permet la création du nouveau champ. Le
+  nom dans l'étude pour le nouveau champ, ainsi que son nom python,
+  sont spécifié par l'utilisateur ({{H|un peu à la mode du module
+  system}}).
+* L'opération est exécutée dans l'espace utilisateur (l'interface
+  python), de sorte que les variables soient projetées dans cet espace
+  et manipulables après l'opération au besoin. Par ailleurs,
+  l'utilisateur peut visualiser les ligne de commandes nécessaires à
+  taper pour exécuter sa requête.
+
+.. _specification_visualisation:
+
+Spécification des fonctions de visualisation
+============================================
+
+Dans le cadre du module MED, on appelle *fonction de visualisation*
+une fonction qui permet d'avoir un aperçu graphique d'un champ, par
+exemple au moyen d'une carte de champ construite sur une de ses
+composante. Il s'agit là de vue de contrôle pour avoir une idée rapide
+de la forme du champs. Pour créer des représentations spécifiques, on
+préférera passer par les fonctions d'export vers le module PARAVIS.
+
+Les modules VISU et PARAVIS offre des interface de programmation C++
+et python qui permettent le pilotage depuis un module tiers comme le
+module MED. On peut donc envisager une fonction de visualisation
+intégrée au module de manipulation de champs, c'est-à-dire que l'on
+déclenche sans sortir du module MED, et qui exploite les fonctions de
+visualisation des modules VISU et/ou PARAVIS.
+
+Les captures d'écran ci-dessous illustrent la mise en oeuvre de la
+fonction de visualisation:
+
+* Sélection d'un champ pour faire apparaitre le menu contextuel et
+  choisir l'option "Visualize":
+
+.. image:: images/xmed-gui-datasource-visualize_70pc.png
+   :align: center   
+
+* Cette option déclenche l'affichage d'une carte de champ sur le cadre
+  d'affichage des viewers SALOME:
+
+.. image:: images/xmed-gui-datasource-visualize-result_70pc.png
+   :align: center
+
+Cette fonction est également disponible en ligne de commandes de
+l'interface textuelle. Par exemple si ``f4`` désigne un champ de
+l'espace de travail (importé des données source ou construit par les
+opérations de champs), alors, on obtient une carte de champ par la
+commande::
+
+ >>> view(f4)
+
+On peut remarquer d'ailleurs sur la capture d'écran de droite
+ci-dessus que la demande de visualisation déclenche l'exécution de la
+commande ``view`` dans la console de travail sur un champ identifié
+par son numéro (3 dans l'exemple).
+
+.. note:: Tous les champs, qu'ils soient des champs chargés d'une
+   source de données ou construits par des opérations de champs sont
+   identifiés par un numéro unique et invariant tout au long de la
+   session de travail.
+
+Spécification des fonctions de persistance
+==========================================
+
+On adopte le principe de fonctionnement suivant:
+
+* Le module n’assure pas la persistence au sens SALOME du terme,
+  c’est-à-dire qu’il ne permet pas la sauvegarde du travail dans une
+  étude au format hdf, ni le dump sous la forme de script python
+  SALOME. Le besoin n'est pas avéré et on peut même dire que ça n'a
+  pas de sens compte-tenu de l'usage envisagé pour le module MED.
+* Par contre, le module fournit des fonctions de sauvegarde du travail
+  sous forme de fichiers med, l’export vers les modules VISU et
+  PARAVIZ, ou même la sauvegarde de l’historique de l’interface de
+  commandes.
+
+Ainsi donc, l'utilisateur aura une fonction (probablement graphique)
+pour définir la sélection des champs de l'espace de travail à
+sauvegarder.
+
+Spécification des fonctions d'export
+====================================
+
+.. warning:: EN TRAVAUX.
+
+Plusieurs export peuvent être proposés:
+
+* Export des champs vers le module PARAVIZ, dans l'objectif par
+  exemple d'en faire une analyse visuelle plus poussée qu'avec les
+  cartes de champs disponibles par défaut dans le module MED
+* Export des données sous forme de tableau numpy, par exemple pour
+  permettre un travail algorithmique sur les valeurs des champs.
+
+Spécifications techniques
+=========================
+
+Il s'agit d'exprimer ici les contraintes techniques applicables à la
+conception et au développement du nouveau module MED.
+
+Implantation technique du module
+--------------------------------
+
+Il est convenu que le module MED existant dans la plate-forme SALOME
+incarne le module de manipulation de champ. Dans la pratique, il
+s'agit d'identifier clairement les parties à conserver, d'une part,
+puis les parties à re-écrire, d'autre part. On peut partir sur les
+hypothèses techniques suivantes:
+
+* Le noyau du module en charge des opérations de manipulation de
+  champs proprement dites est construit sur la base des paquets
+  logiciels MEDCoupling (lui-même basé sur le INTERP_KERNEL) et
+  MEDLoader.
+* L'interface graphique du module MED est complétement re-écrite et
+  remplacée par une interface adaptée spécialement à la manipulation
+  des champs et la gestion des données associées
+* Le contrôle visuel pourra être déclenché dans les visualisateurs
+  SALOME (servis par les modules VISU et/ou PARAVIZ);
+* Le module n'assure pas la persistence au sens SALOME du terme,
+  c'est-à-dire qu'il ne permet pas la sauvegarde du travail dans une
+  étude au format hdf, ni le dump sous la forme de script python
+  SALOME.
+* Par contre, il fournit des fonctions de sauvegarde du travail sous
+  forme de fichiers med, l'export vers les modules VISU et PARAVIZ, ou
+  même la sauvegarde de l'historique de l'interface de commandes.
+
+L'implantation technique des développements est représentée sur la
+figure ci-dessous:
+
+.. image:: images/xmed-implantation.png
+   :align: center
+
+Le schéma représente les packages logiciels qui composent le module
+MED (cf. |REF_CEA_VBE_MEDMEM|_):
+
+* La partie MEDMEM, représentées en blanc. Cette partie est conservée
+  pour compatibilité ascendante au niveau des applications métier qui
+  ont fait le choix historique de s'appuyer sur MEDMEM. Cette partie
+  du module MED aura tendance à disparaitre dans le futur au bénéfice
+  de MEDCoupling et MEDLoader.
+* La partie MEDCoupling, représentée en orange et qui founrnit le
+  modèle MED mémoire de référence (composé de maillage et de champs)
+  et l'interface de programmation pour manipuler le modèle. Le paquet
+  MEDLoader est une extention dédiée à la persistence au format med
+  fichier (lecture et écriture de champs et de maillage dans des
+  fichiers med).
+* La partie à développer pour la manipulation de champ, représentée en
+  bleu.
+
+.. note:: MEDCoupling peut être vu comme une structure de donnée
+   particulièrement adaptée à la manipulation des gros volumes de
+   données, en particulier par l'exploitation des possibilités de
+   parallélisation et la réduction de la tailles des structures de
+   données. En contrepartie, elle peut présenter un périmètre
+   fonctionnel moins large que MEDMEM. Pour cette raison, MEDMEM avait
+   été choisi comme socle de développement du prototype en 2010:
+
+   * MEDCoupling ne permet pas de gérer des maillages composés de
+     plusieurs type de mailles et il est exclus de le faire évoluer
+     dans ce sens (c'est un choix fait pour les objectifs de
+     performances évoqués plus haut);
+   * MEDCoupling ne permet pas de gérer les supports qui expriment les
+     champs aux noeuds par élément ni aux points de gauss. Cette
+     seconde limitation a disparu en 2011.
+
+   Aujourd'hui, on fait clairement le choix de MEDCoupling pour sa
+   qualité et sa robustesse, dans l'objectif d'une meilleure
+   maintenance à long terme. Par ailleurs, les différences
+   fonctionnelles avec MEDMEM, si elles existaient encore en 2012 pour
+   les besoins de la manipulation de champs, pourront être résorbées
+   dans un futur proche.
+
+
diff --git a/src/MEDOP/doc/sphinx/fr/medop-userguide-gui.rst b/src/MEDOP/doc/sphinx/fr/medop-userguide-gui.rst
new file mode 100644 (file)
index 0000000..f09404a
--- /dev/null
@@ -0,0 +1,748 @@
+.. meta::
+   :keywords: maillage, champ, manipulation, guide utilisateur
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Module MED: Guide d'utilisation de l'interface graphique
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Ce document est un guide rapide pour l'utilisation de l'interface
+graphique du module MED. Il montre comment utiliser le module sur la
+base de quelques exemples de référence, inspirés des cas d'utilisation
+identifiés lors de l'analyse des besoins en matière de manipulation de
+champs.
+
+.. warning:: Le document est autonome, mais il est vivement conseillé
+   de parcourir au préalable (ou en parallèle) :doc:`le document de
+   spécifications<medop-specifications>`, au moins pour fixer les
+   concepts et la terminologie.
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Présentation générale du module MED
+===================================
+
+L'ergonomie générale d'utilisation du module de manipulation de champs
+est inspirée des logiciels comme octave ou scilab. Elle associe une
+interface graphique, pour sélectionner et préparer les données, avec
+une interface texte (la console python) pour le travail effectif sur
+les données.
+
+Pour cela, le module propose deux espaces utilisateurs qui sont
+symbolisés par les rectangles rouges et vert sur la capture d'écran
+ci-dessous:
+
+* **l'espace des données** (*dataspace*), dans lequel l'utilisateur
+  définit les sources de données med (*datasource*), c'est-à-dire les
+  fichiers med dans lesquels sont lus les champs et maillages. Cet
+  espace permet l'exploration des maillages et des champs fournis par
+  les différentes sources de données.
+* **l'espace de travail** (*workspace*), dans lequel l'utilisateur
+  peut déposer des champs sélectionnées dans l'espace source, pour
+  ensuite les travailler par exemple pour produire des nouveaux champs
+  au moyen des fonctions de manipulation fournies par l'interface
+  textuelle (console python TUI).
+
+.. image:: images/xmed-gui-withframe.png
+   :align: center
+
+L'utilisation type des fonctions de manipulation de champs suit un
+processus de la forme suivante:
+
+1. Chargement d'un fichier med dans l'espace de données (dataspace) et
+   exploration du contenu, composé de maillages et de champs définis
+   sur ces maillages et pouvant contenir un ou plusieurs pas de temps.
+2. Sélection (graphique) des champs à manipuler dans l'espace de
+   travail (workspace), avec la possibilité de préciser des
+   restrictions d'utilisation (pas de temps, composantes, groupe de
+   maille).
+3. Création de nouveaux champs par l'exécution d'opérations
+   algébriques (+,-,*,/) entre champs, l'application de fonctions
+   mathématiques standard (pow, sqrt, abs), ou encore l'initialisation
+   "from scratch" sur un maillage support.
+4. Contrôle visuel rapide des champs produits (avec les modules VISU
+   et/ou PARAVIS de SALOME, pilotés automatiquement depuis l'interface
+   utilisateur)
+5. Enregistrement d'une partie des champs produits dans un fichier med
+
+
+Tour rapide des fonctions du module MED
+=======================================
+
+Cette section présente des exemples d'utilisation du module XMED sous
+la forme de "storyboard", et illustre au passage les fonctions mises à
+disposition par le module.
+
+.. warning:: Cette section est en travaux. Tant que cet avis n'aura
+   pas disparu, veuillez en considérer le plan et le contenu encore
+   incomplets, temporaires et sujets à caution.
+
+Exemple 1: Explorer des sources de données
+------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * ajouter une source de données
+   * fonctions "Extends field series", "Visualize"
+
+.. |ICO_DATASOURCE_ADD| image:: images/ico_datasource_add.png
+                        :height: 16px
+
+.. |ICO_XMED| image:: images/ico_xmed.png
+              :height: 16px
+
+.. |ICO_DATASOURCE_EXPAND| image:: images/ico_datasource_expandfield.png
+                           :height: 16px
+
+.. |ICO_DATASOURCE_VIEW| image:: images/ico_datasource_view.png
+                         :height: 16px
+
+Au démarrage, le module de manipulation de champs, identifié par
+l'icône |ICO_XMED|, présente une interface vierge:
+
+.. image:: images/xmed-gui-start.png
+   :align: center
+   :width: 800px
+
+La première étape consiste à ajouter une ou plusieurs source de
+données med dans le "dataspace". Pour cela, on clique sur l'icône "Add
+datasource" |ICO_DATASOURCE_ADD| qui propose de sélectionner un
+fichier med:
+
+.. image:: images/xmed-gui-datasource-selectfile.png
+   :align: center
+   :width: 800px
+
+L'opération ajoute une nouvelle entrée (datasource) dans l'espace de
+données (dataspace). Le contenu peut être exploré en parcourant
+l'arborescence. La figure ci-dessous (image de gauche) montre le
+résultat du chargement du fichier ``timeseries.med`` contenant un
+maillage de nom ``Grid_80x80`` sur lequel est défini un champ au noeud
+de nom ``Pulse``. Par défaut, la composition du champs (en terme de
+pas de temps et de composantes) n'est pas affichée pour éviter
+l'encombrement visuel de l'arbre. On doit faire la demande explicite
+au moyen de la commande "Expand field timeseries"
+|ICO_DATASOURCE_EXPAND| disponible dans le menu contextuel associé aux
+champs. Le résultat est affiché sur l'image centrale. La liste des
+itérations du champ ``Pulse`` peut être consultée.
+
+.. |IMG_DATASOURCE_EXPLORE| image:: images/xmed-gui-datasource-explore-zoom.png
+                            :height: 340px
+.. |IMG_DATASOURCE_MENUCON| image:: images/xmed-gui-datasource-menucontextuel-zoom.png
+                            :height: 340px
+.. |IMG_DATASOURCE_EXPANDF| image:: images/xmed-gui-datasource-expand-zoom.png
+                            :height: 340px
+
++--------------------------+--------------------------+--------------------------+
+| |IMG_DATASOURCE_EXPLORE| | |IMG_DATASOURCE_MENUCON| | |IMG_DATASOURCE_EXPANDF| |
++--------------------------+--------------------------+--------------------------+
+
+.. note:: En toute rigueur, le concept de *champ* dans le modèle MED
+   désigne une itération donnée. Un ensemble d'itérations est désigné
+   par le terme *série temporelle de champs*. Par abus de langage, et
+   s'il n'y a pas ambiguité, on utilisera le nom du champ pour
+   désigner à la fois le champs proprement dit ou la série temporelle
+   à laquelle il appartient.
+
+Enfin, il est possible au niveau du dataspace de visualiser la forme
+générale du champ au moyen d'une carte scalaire affichée dans le
+viewer de SALOME. Pour cela, on sélectionne le pas de temps à
+visualiser et on utilise la commande "Visualize" |ICO_DATASOURCE_VIEW|
+disponible dans le menu contextuel associé:
+
+.. image:: images/xmed-gui-datasource-visualize-zoom.png
+   :align: center
+   :width: 800px
+
+.. note:: Cette représentation graphique a pour objectif le contrôle
+   visuel rapide. Aussi, les fonctions du module VISU sont employées
+   par défaut, mais il est possible de faire l'affichage des cartes
+   scalaires au moyen du module PARAVIS (choix de préférence non
+   implémenté pour le moment, mais techniquement réalisable).
+
+Exemple 2: Rassembler des champs issus de différentes sources
+-------------------------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * fonction "Use in workspace"
+   * fonction "Save"
+
+.. |ICO_DATASOURCE_USE| image:: images/ico_datasource_use.png
+                        :height: 16px
+.. |ICO_WORKSPACE_SAVE| image:: images/ico_workspace_save.png
+                        :height: 16px
+
+L'objectif est de récupérer des données issues de différents fichiers
+med, puis de les rassembler dans un même fichier en sortie.
+
+On commence par ajouter les sources de données med dans l'espace de
+données (dataspace). Dans l'exemple ci-dessous, l'espace de données
+contient deux sources de nom ``parametric_01.med`` et
+``smallmesh_varfiled.med``. La première source contient le maillage
+``Grid_80x80_01`` sur lequel est défini le champ ``StiffExp_01``. La
+deuxième source contient le maillage ``My2DMesh`` sur lequel sont
+définis deux champs de noms respectifs ``testfield1`` et
+``testfield2``:
+
+.. image:: images/xmed-userguide-example2-datasource.png
+   :align: center
+   :width: 800px
+
+Pour l'exemple, on souhaite rassembler les champs ``StiffExp_01`` et
+``testfield2`` dans un fichier de nom ``result.med``. La procédure
+consiste à importer les deux champs dans l'espace de travail
+(workspace), puis à sauvegarder l'espace de travail. Pour cela, on
+sélectionne les champs et on utilise la commande "Use in workspace"
+|ICO_DATASOURCE_USE| disponible dans le menu contextuel. Les deux
+champs sélectionnés apparaissent dans l'arborescence de l'espace de
+travail:
+
+.. image:: images/xmed-userguide-example2-workspace.png
+   :align: center
+   :width: 800px
+
+La sauvegarde de l'espace de travail est faite au moyen de la commande
+"Save workspace" |ICO_WORKSPACE_SAVE| disponible dans la barre
+d'outils du module. Une fenêtre de dialogue invite l'utilisateur à
+spécifier le nom du fichier de sauvegarde:
+
+.. image:: images/xmed-userguide-example2-workspace-save.png
+   :align: center
+   :width: 800px
+
+Ce fichier ``result.med`` peut ensuite être rechargé dans le module
+XMED (ou les modules VISU ou PARAVIS) pour vérifier la présence des
+champs sauvegardés.
+
+.. BUG: plantage à l'utilsation dans XMED d'un fichier rechargé
+.. (invalid mesh on field)
+
+.. _xmed.userguide.exemple3:
+
+Exemple 3: Appliquer une opération mathématique sur des champs
+--------------------------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * exécution d'opérations mathématiques dans la console TUI
+   * fonction "put" pour référencer un champ de travail dans la liste
+     des champs persistant.
+   * fonction "Visualize" depuis le TUI.
+
+L'usage le plus courant du module de manipulation de champs est
+d'exécuter des opérations mathématiques dont les opérandes sont des
+champs ou des composantes de ces champs.
+
+On se place dans une situation où les sources de données sont définies
+dans le "dataspace" (dans l'exemple ci-après, une série temporelle de
+nom ``Pulse``, contenant 10 pas de temps, définis sur un maillage de
+nom ``Grid_80x80``, le tout issu du datasource ``timeseries.med``).
+
+Comme vu précedemment, pour manoeuvrer un champ dans l'espace de
+travail, on sélectionne ce champ, puis on exécute la commande "Use in
+workspace" |ICO_DATASOURCE_USE| du menu contextuel. Dans le cas
+présent, un seul champ est sélectionné (contre deux dans l'exemple
+précédent) et la commande ouvre alors une fenêtre de dialogue qui
+permet de préciser les données sur lesquelles on souhaite
+effectivement travailler et comment on veut les manoeuvrer:
+
+.. image:: images/xmed-gui-datasource-useinworkspace-alias.png
+   :align: center
+   :width: 800px
+
+.. note:: En l'état actuel du développement, l'interface propose
+   uniquement de définir le nom de la variable sous laquelle doit être
+   manoeuvré le champ dans la console de travail (TUI). Dans une
+   version ultérieure, il est prévue de pouvoir préciser la ou les
+   composante du champs à utiliser et un groupe de maille pour définir
+   une restriction géométrique. Inversement, il sera également
+   possible de choisir une série temporelle complète pour faire des
+   opérations globales sur l'ensemble des pas de temps.
+
+Aprés validation, le champ est placé dans l'arborescence du
+"workspace" et une variable de nom ``<alias>`` est créée
+automatiquement dans la console de travail pour désigner le
+champ. Dans cet exemple, ``<alias>`` vaut ``f3``, positionné ainsi par
+l'utilisateur pour rappeler que la variable correspond au pas de temps
+n°3:
+
+.. image:: images/xmed-gui-workspace.png
+   :align: center
+   :width: 800px
+
+La manipulation peut commencer. Dans l'exemple ci-dessous, on crée le
+champ ``r`` comme le résultat d'une transformation afine du champ
+``f3`` (multiplication du champ par le facteur 2.7 auquel on ajoute
+l'offset 5.2)::
+
+ >>> r=2.7*f3+5.2
+
+On peut poursuivre la manipulation du champs avec une variété
+d'opérations qui sont détaillées dans les spécifications du module
+(cf. :ref:`Spécification des opérations<xmed-specifications>`):
+
+ >>> r=f3/1000     # les valeurs de r sont celles du champ f3 réduites d'un facteur 1000
+ >>> r=1/f3        # les valeurs de r sont les inverses des valeurs de f3
+ >>> r=f3*f3       # les valeurs de r sont celles du champ f3 élevées au carré
+ >>> r=pow(f3,2)   # même résultat
+ >>> r=abs(f3)     # valeur absolue du champ f3
+ >>> ...
+
+Les opérations peuvent utiliser plusieurs opérandes de type champs. Si
+``f4`` désigne le pas de temps n°4 du champ ``Pulse``, alors on peut
+calculer toute combinaison algébrique des deux champs::
+
+ >>> r=f3+f4
+ >>> r=f3-f4
+ >>> r=f3/f4
+ >>> r=f3*f4
+
+Avec au besoin l'utilisation de variables scalaires::
+
+ >>> r=4*f3-f4/1000
+ >>> ...
+
+Dans ces exemples, la variable ``r`` désigne un champ de travail qui
+contient le résultat de l'opération. Par défaut, ce champ de travail
+n'est pas référencé dans l'arborescence du workspace. Si on souhaite
+tout de même le référencer, par exemple pour qu'il soit pris en compte
+dans la sauvegarde, alors on tape la commande::
+
+ >>> put(r)
+
+La fonction ``put`` a pour but de marquer le champ en argument comme
+persistent, puis de le ranger dans l'arborescence du "workspace" afin
+qu'il soit visible et sélectionnable. En effet, parmi tous les champs
+qui pourront être créés dans la console pendant la session de travail,
+tous n'ont pas besoin d'être sauvegardés. Certains sont même des
+variables temporaires qui servent à la construction des champs
+résultats finaux. C'est pourquoi, seuls les champs rangés dans
+l'arborescence du workspace sont enregistrés lors de la demande de
+sauvegarde du workspace.
+
+Les variables définies dans la console ont d'autres utilités. Tout
+d'abord, elles permettent d'imprimer les informations concernant le
+champ manoeuvré. Pour cela, on tape simplement le nom de la variable
+puis retour::
+
+ >>> f3
+ field name (id)        = Pulse (3)
+ mesh name (id)         = Grid_80x80 (0)
+ discretization         = ON_NODES
+ (iter, order)          = (3,-1)
+ data source            = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
+
+Elle peut également être utilisée comme argument des commandes de
+gestion disponibles dans l'interface textuelle (dont la liste
+détaillée est décrite à la section :ref:`Documentation de l'interface
+textuelle<xmed.userguide.tui>`). Par exemple, la fonction ``view``
+permet d'afficher la carte scalaire du champ dans le viewer::
+
+ >>> view(f3)
+
+Donne:
+
+.. image:: images/xmed-gui-workspace-view.png
+   :align: center
+   :width: 800px
+
+.. note:: On remarquera ici qu'il est facile de comparer deux pas de
+   temps d'un champ, par exemple en calculant la différence ``f3-f4``,
+   puis en affichant un aperçu de la carte scalaire résultat au moyen
+   de la fonction ``view``::
+
+    >>> view(f3-f4)
+
+On peut enfin tout simplement afficher les données du champs par la
+commande ``print``::
+
+ >>> print f3
+ Data content :
+ Tuple #0 : -0.6 
+ Tuple #1 : -0.1 
+ Tuple #2 : 0.4 
+ Tuple #3 : -0.1 
+ Tuple #4 : 0.4 
+ ...
+ Tuple #6556 : 3.5 
+ Tuple #6557 : 3.3 
+ Tuple #6558 : 1.5 
+ Tuple #6559 : 0.3 
+ Tuple #6560 : 0.2
+
+Il est important de noter que les opérations entre champs ne peuvent
+être faites qu'entre champs définis sur le même maillage. Il s'agit là
+d'une spécification du modèle MED qui interdit d'envisager les
+opérations entre champs définis sur des maillages géométriquement
+différents. Techniquement, cela se traduit par l'obligation pour les
+objets informatique *champs* de partager le même objet informatique
+*maillage*.
+
+Dans l'hypothèse où on souhaite utiliser des champs définis sur des
+maillages différents, par exemple pour manoeuvrer les valeurs des
+champs à l'interface de deux maillages partageant une zone géométrique
+2D, il faut d'abord ramener tous les champs sur le même maillage de
+surface par une opération de projection.
+
+.. note:: Même si ceci est techniquement possible avec la bibliothèque
+   MEDCoupling, cet type d'opération de projection n'est pas encore
+   disponible dans le module de manipulation de champs (prévu en
+   2012).
+
+Un autre besoin plus classique est l'utilisation de champs définis sur
+des maillages géométriquement identiques, mais techniquement
+différents, par exemple lorsqu'ils sont chargés de fichiers med
+différents. Pour traiter ce cas de figure, la bibliothèque MEDCoupling
+prévoit une fonction de "Changement du maillage support", dont
+l'utilisation au niveau du module de manipulation de champs est
+illustrée dans :ref:`l'exemple 4<xmed.userguide.exemple4>` ci-après.
+
+.. _xmed.userguide.exemple4:
+
+Exemple 4: Comparer des champs issues de différentes sources
+------------------------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * Changement du maillage support "change underlying mesh"
+
+On se place ici dans le cas de figure où des champs ont été produits
+sur le même maillage, au sens géométrique, mais enregistrés dans des
+fichiers med différents. C'est le cas par exemple d'une étude
+paramétrique où plusieurs calculs sont effectués avec des variantes
+sur certains paramètres du modèle simulé, chaque calcul produisant un
+fichier med.
+
+Soit ``parametric_01.med`` et ``parametric_02.med`` deux fichiers med
+contenant les champs que l'on souhaite comparer, par exemple en
+calculant la différence des valeurs et en visualisant le résultat.
+
+Aprés le chargement des sources de données dans le module XMED,
+l'utilisateur se trouve en présence de deux maillages, au sens
+technique du terme cette fois-ci, c'est-à-dire que les champs sont
+associées à des objets informatiques maillage différents, bien que
+géométriquement identiques.
+
+Or, les fonctions de manipulation de champs ne permettent pas les
+opérations sur des champs dont les maillages supports sont différents
+(voir la remarque à la fin de :ref:`l'exemple
+3<xmed.userguide.exemple3>`).
+
+Pour résoudre ce cas de figure, le module de manipulation de champs
+met à disposition la fonction "Change underlying mesh" qui permet de
+remplacer le maillage support d'un champ par un autre à partir du
+moment où les deux maillages sont géométriquement identiques,
+c'est-à-dire que les noeuds ont les mêmes coordonnées spatiales.
+
+.. |ICO_DATASOURCE_CHG| image:: images/ico_datasource_changeUnderlyingMesh.png
+                        :height: 16px
+
+Dans l'exemple proposé, l'utilisateur sélectionne le premier pas de
+temps du champ ``StiffExp_01`` du "datasource" ``parametric_01.med``,
+puis l'importe dans l'espace de travail au moyen de la commande "Use
+in workspace" |ICO_DATASOURCE_USE|. Il sélectionne ensuite le premier
+pas de temps du champs ``StiffExp_02`` du "datasource"
+``parametric_02.med``, mais l'importe dans l'espace de travail au
+moyen de la commande "Change underlying mesh" |ICO_DATASOURCE_CHG|. La
+fenêtre de dialogue ci-dessous s'affiche et invite l'utilisateur à
+choisir le nouveau maillage support par sélection dans l'arborescence
+du "dataspace":
+
+.. image:: images/xmed-gui-datasource-changeUnderlyingMesh.png
+   :align: center
+
+Dans cet exemple, on sélectionne le maillage ``Grid_80x80_01`` support
+du champ ``StiffExp_01``, avec lequel on souhaite faire la
+comparaison. Après validation, l'arborescence du workspace contient le
+champ ``StiffExp_02`` défini sur le maillage ``Grid_80x80_01``:
+
+.. image:: images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png
+   :align: center
+
+.. note:: La fonction "Change underlying mesh" ne modifie pas le champ
+  sélectionné dans le "dataspace" (principe de base de fonctionnement
+  du dataspace), mais crée une copie du champ dans l'espace de travail
+  pour ensuite remplacer le maillage support. D'où le nom par défaut
+  pour le champ ``dup(<nom du champ sélectionné>)`` (dup pour
+  "duplicate").
+
+Il reste à associer une variable à ce champ pour le manipuler dans la
+console. Ceci peut être fait au moyen de la commande "Use in console",
+disponible dans le menu contextuel du workspace.
+
+En définitif, si ``f1`` désigne le champ issu du datasource
+``parametric_01.med`` et ``f2`` le champ issu du datasource
+``parametric_02.med`` par la procédure décrite ci-dessus, alors la
+comparaison des deux grandeurs peut être faite comme pour le cas de
+:ref:`l'exemple 3<xmed.userguide.exemple3>`::
+
+ >>> r=f1-f2
+ >>> view(r)
+
+.. note:: En remarque générale sur cet exemple, il convient de noter
+   les points suivants:
+
+   * l'égalité géométrique de deux maillages est établie à une marge
+     d'erreur prés qu'il est possible de définir techniquement, mais
+     qui n'est pas ajustable au niveau de l'interface du module de
+     manipulation de champs. Elle est fixée à une valeur standard qui
+     permet de traiter la plupart des cas utilisateur. On verra à
+     l'usage s'il est nécessaire de remonter ce paramètre au niveau de
+     l'interface.
+   * L'utilisateur doit faire la démande explicite de changer le
+     maillage support d'un champ, en prévision de la comparaison de
+     champs issus de datasource différentes. Il s'agit là d'un choix
+     fonctionnel délibéré pour que l'utilisateur garde trace des
+     modifications faites sur les données (pas de modification
+     automatiques à l'insu de l'utilisateur, même sous prétexte
+     d'amélioration de l'ergonomie).
+
+
+Exemple 5: Créer un champ sur un domaine spatial
+------------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * initialisation par une fonction de la position spatiale
+   * initialisation sur un groupe de maille
+
+Le domaine géométrique de définition du champs à créer est spécifié
+ici par la donnée d'un groupe de mailles. Ce cas d'usage est
+typiquement prévu pour produire les conditions de chargement initial
+d'une structure, par exemple en définissant un champ sur une surface
+de la géométrie, identifiée par un nom de groupe de mailles.
+
+.. warning:: DEVELOPPEMENT EN COURS
+
+Exemple 6: Extraire une partie d'un champ
+-----------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * extraire une composante (ou un sous-ensemble des composantes)
+   * extraire un domaine géométrique (valeurs sur un groupe de maille)
+   * extraire un ou plusieurs pas de temps.
+
+.. warning:: DEVELOPPEMENT EN COURS
+
+   On doit illustrer ici les fonctions de restriction, qui
+   permettraient de récupérer certaines composantes uniquement. Le
+   principe est qu'on crée un nouveau champ qui est une restriction du
+   champ argument à une liste de composantes à spécifier (utiliser la
+   fonction __call__ des fieldproxy).
+
+Pour l'extraction des pas de temps, on peut se ramener au cas de
+l'exemple 2 avec une seule source de donnée.
+
+Exemple 7: Créer un champ à partir d'une image to[mp]ographique
+---------------------------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * Création d'un champ sans datasource (ni maillage, ni champs), à
+     partir d'un fichier image
+
+En tomographie ou en topographie, les appareils de mesure produisent
+des images qui représentent une grandeur physique en niveaux de gris
+sur un plan de coupe donné. L'image ci-dessous représente par exemple
+une vue interne du corps humain faite par IRM:
+
+.. image:: images/xmed-irm.png
+   :align: center
+   :width: 600px
+
+Cette image est un ensemble de pixels organisés sur une grille
+cartesienne. Elle peut donc être modélisée sous la forme d'un champ
+scalaire dont les valeurs sont définies aux cellules d'un maillage
+réglés de même taille que l'image (en nombre de pixels):
+
+.. image:: images/xmed-irm-field.png
+   :align: center
+   :width: 600px
+
+Le module de manipulation de champ fournit un utilitaire appelé
+``image2med.py`` qui permet d'appliquer ce principe à la conversion
+d'un fichier image en fichier med contenant la représentation de
+l'image sous forme d'un champ scalaire (seul le niveau de gris est
+conservé)::
+
+  $ <xmed_root_dir>/bin/salome/xmed/image2med.py -i myimage.png -m myfield.med
+
+.. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png
+                        :height: 16px
+
+Cette opération de conversion peut être faite automatiquement dans
+l'interface graphique du module au moyen de la commande "Add Image
+Source" |ICO_IMAGESOURCE| disponible dans la barre d'outils. Cette
+commande ouvre la fenêtre suivante pour inviter l'utilisateur à
+choisir un fichier image:
+
+.. image:: images/medop_image2med_dialog.png
+   :align: center
+
+Le nom du fichier med résultat est proposé par défaut (changement de
+l'extention en ``*.med``) mais il peut être modifié. Enfin, on peut
+demander le chargement automatique du fichier med produit pour ajout
+dans l'espace de donnée. Les champs peuvent alors être manipulés comme
+dans les cas d'utilisation standard.
+
+Par exemple, l'image ci-dessous affiche le résultat de la différence
+entre deux images, ajoutée à l'image de référence: si i1 et i2
+désignent les champs créés à partir des deux images, on représente ``r
+= i1 + 5*(i2-i1)`` où le facteur 5 est arbitraire et sert à amplifier
+la zone d'intérêt (en haut de l'oeil gauche):
+
+.. image:: images/xmed-irm-diff.png
+   :align: center
+   :width: 600px
+
+L'exemple ci-dessous est le résultat du chargement d'une image
+tomographique issue du projet MAP (Charles Toulemonde,
+EDF/R&D/MMC). L'image tomographique:
+
+.. image:: images/champ_altitude_MAP.png
+   :align: center
+   :width: 600px
+
+Le résultat du chargement:
+
+.. image:: images/medop_image2med_tomographie.png
+   :align: center
+   :width: 800px
+
+Exemple 8: Continuer l'analyse dans PARAVIS
+-------------------------------------------
+
+.. note:: Cet exemple présente les fonctions:
+
+   * Export de champs vers le module PARAVIS.
+
+Les possibilités de représentation graphique des champs fournies par
+le module MED ont pour seul objectif le contrôle visuel rapide. Par
+défaut, le viewer de VISU est employé.
+
+Pour une analyse plus détaillées des champs, il est nécessaire de
+poursuivre le travail dans PARAVIS. Le module de manipulation de
+champs offre une fonction qui simplifie ce passage, en faisant le
+chargement automatique dans PARAVIS et en proposant une visualisation
+par défaut (carte de champs scalaire).
+
+Pour cela, il faut sélectionner dans l'espace de travail les champs à
+exporter, puis déclencher la fonction d'export depuis le menu
+contextuel associé:
+
+.. image:: images/medop_exportparavis.png
+   :align: center
+
+Les champs sélectionnés sont regroupés dans une entrée MED du
+navigateur PARAVIS, et le premier champ est affiché sous forme de
+carte de champ:
+
+.. image:: images/medop_exportparavis_result.png
+   :align: center
+   :width: 800px
+
+.. note:: La fonction d'export est une fonction de confort. La même
+   opération peut être faite manuellement en procédant d'abord à
+   l'enregistrement des champs sous forme de fichier MED, puis en
+   chargeant le fichier généré dans le module PARAVIS pour
+   visualisation.
+
+.. _xmed.userguide.tui:
+
+Utilisation de l'interface textuelle du module MED (TUI)
+========================================================
+
+Toutes les opérations menées au moyen de l'interface graphique peuvent
+être réalisées (avec plus ou moins de facilité) avec l'interface
+textuelle. Le module de manipulation de champs peut même être utilisé
+exclusivement en mode texte. Pour cela, on lance la commande::
+
+ $ <path/to/appli>/medop.sh
+
+Cette commande ouvre une console de commandes ``medop>``. Un fichier
+med peut être chargé et travaillé, par exemple pour créer des champs à
+partir des données du fichier.
+
+Que l'on soit en mode texte pur ou en mode graphique, un séquence de
+travail type dans la console peut ressembler au jeu d'instructions
+suivantes::
+
+ >>> load("/path/to/mydata.med")
+ >>> la
+ id=0    name    = testfield1
+ id=1    name    = testfield2
+ >>> f1=get(0)
+ >>> f2=get(1)
+ >>>   ls
+ f1      (id=0, name=testfield1)
+ f2      (id=1, name=testfield2)
+ >>> r=f1+f2
+ >>> ls
+ f1      (id=0, name=testfield1)
+ f2      (id=1, name=testfield2)
+ r       (id=2, name=testfield1+testfield2)
+ >>> r.update(name="toto")
+ >>> ls
+ f1      (id=0, name=testfield1)
+ f2      (id=1, name=testfield2)
+ r       (id=2, name=toto)
+ >>> put(r)
+ >>> save("result.med")
+
+Les commandes principales sont:
+
+* ``load``: charge un fichier med dans la base de données (utile
+  uniquement en mode texte pur)::
+
+  >>> load("/path/to/datafile.med")
+
+* ``la``: affiche la liste de tous les champs chargés en base de données ("list all")
+* ``get``: définit un champ dans l'espace de travail à partir de son
+  identifiant (utile plutôt en mode texte pur car l'interface
+  graphique permet de faire cette opération par sélection d'un champ
+  dans le dataspace)::
+
+  >>> f=get(fieldId)
+
+* ``ls``: affiche la liste des champs présent dans l'espace de travail ("list")
+* ``put``: met un champ en référence dans l'*espace de gestion*::
+
+  >>> put(f)
+
+* ``save``: sauvegarde tous les champs référencés dans l'espace de
+  gestion dans un fichier med::
+
+  >>> save("/path/to/resultfile.med")
+
+.. note:: On peut faire à ce stade plusieurs remarques:
+
+   * la commande ``load`` charge uniquement les méta-informations
+     décrivant les maillage et les champs (noms, type de
+     discrétisation, liste des pas de temps). Les maillages et les
+     valeurs physiques des champs sont chargées ultérieurement (et
+     automatiquement) dés lors qu'elles sont requises par une
+     opération. Dans tous les cas, les données med (méta-informations
+     et valeurs) sont physiquement stockées au niveau de l'espace
+     *base de données*.
+   * la commande ``get`` définit en réalité un *manipulateur de champ*
+     dans l'espace de travail, c'est-à-dire une variable qui fait la
+     liaison avec le champ physique hébergé dans la base de
+     données. Les données physiques ne circulent jamais entre les
+     espaces, mais restent centralisées au niveau de la base de
+     données.
+
+Les commandes TUI suivantes nécessitent de travailler dans
+l'environnement graphique:
+
+* ``visu``: afficher une carte de champ pour contrôle visuel rapide
+  (pas de paramettrage possible)
+
+  >>> view(f)
+
+
diff --git a/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2010.rst b/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2010.rst
new file mode 100644 (file)
index 0000000..724c9a8
--- /dev/null
@@ -0,0 +1,461 @@
+.. meta::
+   :keywords: maillage, champ, manipulation
+   :author: Guillaume Boulant
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ANNEXE: Note de travail concernant le chantier XMED 2010
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Principes directeurs du développement
+=====================================
+
+En matière de développement:
+
+* On ne cherche pas d'emblée à s'inscrire dans la fabrication d'un
+  module SALOME diffusable dans la version d'exploitation 2010 (SALOME
+  6). La raison est double: (i) on souhaite au moins pour 2010 ne pas
+  devoir tenir compte des contraintes de temps SALOME et (ii) le
+  produit envisagé fin 2010 est une maquette qui cherche à éprouver
+  l'ergonomie générale d'utilisation et en aucun cas on ne peut
+  garantir la réalisation d'un module SALOME compatible avec les
+  exigences de mise en exploitation.
+* On ne cherche pas d'emblée à capturer tous les cas d'application,
+  mais à concevoir un développement qui acceptera les extensions de
+  périmètres dans des conditions raisonnables. Aussi, les
+  fonctionnalités développées seront celles qui sont nécessaires à la
+  réalisation des cas d'application de référence;
+
+En matière d'ergonomie:
+
+* L'interface utilisateur de référence (appelé espace de travail dans
+  le volet de spécifications fonctionnelles) est l'interpréteur
+  python. Les fonctionnalités doivent être pensées pour un usage
+  adapté à une interface textuelle (TUI) de ce type.
+* La création d'une interface graphique (GUI) peut être envisagée en
+  complément et comme un moyen de manipuler graphiquement les
+  fonctionnalités développées pour l'interface textuelle et pour aider
+  la préparation des variables dans l'interface python.
+* Le modèle d'un processus de manipulation de champs est:
+
+  - Préparation du jeu de variables U, V, ... représentant les champs
+    à manipuler. C'est à ce stade que l'on résoud la question de
+    sélection des données (dans un champ publié dans l'arbre d'étude,
+    par un module de calcul ou par chargement d'un fichier med)
+  - Utilisation des variables avec une sémantique la plus proche
+    possible du modèle conceptuel et des spécifications
+    fonctionnelles;
+  - Création des variables qui représentent les résultats des
+    fonctions de manipulation;
+  - Persistence (fichier med), visualisation (SALOME) ou export (vers
+    une structure qui peut être directement utilisable en numpy)
+
+Sur le plan technique:
+
+* On souhaite spécifier clairement le conteneur SALOME des fonctions
+  de manipulation de champs. Pour discussion:
+
+  - Il apparaît que les modules SALOME MED et VISU contiennent déjà
+    des fonctions qui peuvent faire partie des fonctions de
+    manipulations de champs (en particulier pour l'exploration des
+    structures MED, leur visualisation et la sélection des données à
+    manipuler).
+  - Dans la mesure où le module MED n'est pas utilisé à ce jour (en
+    tout cas pas sous sa forme de module SALOME) et compte-tenu du
+    caractère obsolescent du module VISU (amené à être remplacé sur le
+    plan fonctionnel  par le module PARAVIS), on pourrait examiner la
+    création d'un module dédié à la manipulation des maillages et des
+    champs par l'agrégation technique au sein d'un même module des
+    fonctions des modules MED et VISU.
+
+Au moins dans un premier temps, on se donne les limites suivantes:
+
+* Une opération ne peut pas combiner des pas de temps différents. Dans
+  l'hypothèse où cette limite venait à être levée, on doit spécifier
+  le pas de temps de la donnée résultat;
+* Le domaine d'application d'une opération pourra être défini
+  exclusivement par la donnée d'un maillage ou un groupe d'éléments du
+  maillage;
+* On ne traite pas le cas des champs qui prennent leurs valeurs aux
+  points de gauss ou aux noeuds par élément. Une particularité de ces
+  types de support est que le repérage de la position implique deux
+  indices (par exemple l'indice de la maille, puis l'indice du point
+  de gauss).
+
+Eléments de conception
+======================
+
+Plan général
+------------
+
+On peut par exemple imaginer une maquette du genre:
+
+* En C++ dans MEDGUI, charger un fichier med et donner une vue de la
+  structure des maillages et des champs dans l'arbre d'étude.
+* Sélectionner un élément (par exemple un pas de temps d'un champ) et
+  le menu contextuel permet d'exporter ce champ dans la console python
+  pour manipulation. Pour cela, s'inspirer de la fonction
+  ``XCADGUI::OnLoadScript()`` du XCADGUI pour manoeuvrer un objet
+  PythonConsole.
+* L'élément est marqué comme ayant été exporté, on peut imaginer une
+  récupération ultérieure.
+* Exporter un deuxième champ cohérent avec le premier (même pas de
+  temps et défini sur le même maillage avec le même support, on
+  s'arrange pour).
+* Dans la console python, faire les opérations sur les champs
+* Publication du champ résultat dans l'arbre d'étude pour sauvegarde
+  ultérieure. C'est a priori le gros morceau qui consiste à faire un
+  objet CORBA MED à partir d'un objet MED standard, en plus défini
+  dans la console python (sous forme d'objet python).
+
+Quand ce premier cas d'utilisation est au point, on peut envisager de
+le compléter par les opérations suivantes
+
+* exporter le résultat med dans un fichier
+* visualiser les champs produits
+
+Plan de développement:
+
+* Faire une maquette en MEDMEM pur d'abord, car quelque soit le choix
+  d'architecture, l'opération physique se déroulera en définitif au
+  niveau de MEDMEM pur.
+* Prévoir une implémentation des opérations sous forme de fonctions
+  informatiques, même les opérations algébriques (+,-,*,/). Pour ces
+  dernières et dans certaines conditions (quand on manipule
+  directement les strutures MEDMEM et non pas les objets CORBA),
+  l'utilisation des formes A+B, A-B, ... peuvent être rendues
+  possibles. Dans ce cas, voir la possibilité de combiner plusieurs
+  opérations algébriques sur une seule ligne: A+B-C*0.3.
+* On peut charger la structure MED sous forme d'objet CORBA publiable
+  dans l'étude, de sorte d'avoir accés aux méta-données et pouvoir par
+  exemple sélectionner les champs d'intérêt. De cet objet CORBA, on ne
+  récupère que les informations nécessaires au chargement d'un champs:
+  le nom du champs, le nom de son maillage associé, les identifiants
+  du pas de temps, au besoin une structure Field non chargée (par
+  exemple pour récupérer plus facilement le maillage).
+* Un mécanisme (à développer à partir du PyConsole par exemple)
+  pourrait alors permettre le chargement des champs sélectionnés dans
+  la console python et sous un nom facile à manoeuvrer. Prendre
+  inspiration sur XCADGUI::LoadIntoPythonConsole().
+* A priori, les données sont physiquement chargée dans le GUI. Au
+  besoin, il semble possible (cf. MED_i::init) de fabriquer une objet
+  CORBA field à partir d'un field standard (à tester).
+
+Une autre idée est de récupérer le pointeur CORBA MED dans la console
+python et de tirer les données à partir de là. Ajouter une couche de
+wrapping python pur pour gérer les cas de simplification (surcharge
+des opérations arithmétiques par exemple).
+
+Besoins complémentaires:
+
+* L'interpréteur doit contenir des éléments d'aide (par exemple un
+  help qui liste les opérations possibles sur les champs chargés)
+* prévoir quelques fonctions de visu et de persistence. Cela commence
+  probablement par des fonctions de publication dans l'étude des
+  champs créés par les opérations de manipulation. Les champs sont
+  physiquement ajouté automatiquement à la structure med par le MedOp
+  mais il n'est pas obligatoirement publié => fournir un moyen de
+  publication.
+
+Limitations actuelles (liées à la conception de MEDMEM):
+
+* les champs doivent être gérés par la même structure MED car ils
+  doivent partager le même support.
+* les opérations possibles dans MEDMEM sont entre champs pris sur un
+  pas de temps (Q: les pas de temps peuvent-ils être différents).
+
+
+Développements
+--------------
+
+Développement de classes proxy:
+
+* FieldProxy, FieldTimeSeriesProxy
+* Attention pour les éries temporelles, le SUPPORT med peut être
+  différent en chaque pas de temps (par exemple en cas d'extension
+  spatiale du champ au cours du temps).
+
+MEDMEM_MedDataManager:
+
+* FIX: test de l'implémentation C++ au travers de la fonction test() du
+  MedOperator ==> OK. Quand on fait la même opération depuis python
+  via l'interface SWIG ==> au deuxième appel de getFieldDouble, le
+  destructeur du champ semble être appelé. Pb de gestion des pointeurs?
+
+
+Evolutions à prévoir
+====================
+
+Concernant MEDMEM:
+
+* FIX: SALOME_MED::MED::getField devrait pouvoir être appelée
+  plusieurs fois de suite puisqu'on recycle la référence si elle est
+  déjà chargée.
+* IMP: MEDMEM::MED faire une gestion des chargements des champs (par
+  exemple avec un getField qui renvoie le champ s'il est déjà chargé
+  ou le charge et le renvoie sinon).
+* IMP: Récupérer le nom du fichier med à partir de l'objet MED, en
+  passant a priori par le driver associé. Plusieurs driver peuvent
+  être associés à une structure MED car les données peuvent être
+  chargées en plusieurs fois et de plusieurs fichiers. Il faut donc
+  étendre la structure MED pour avoir accés à la liste des driver puis
+  de cette liste déduire les noms des fichiers.
+* IMP: Opérations combinant des champs sur des support différents ne
+  peuvent pas être faites par l'API (une exception est levée en cas de
+  supports incompatibles), mais on peut imaginer le faire en
+  manoeuvrant les tableaux de données directement.
+* INF: faire le point sur les fonctions utilitaires autour de MEDMEM
+  et de son interface SWIG (ex: dumpMEDMEM.py, med_opfield_test.py).
+* IMP: dans MEDMEM::MED et SALOME_MED::MED, pouvoir enlever un champ
+  préalablement ajouté: une fonction removeField en complément de
+  addField.
+
+Concernant l'interface SALOME_MED:
+
+* IMP: Fonctions algébriques, qui seront implémentées au niveau de la
+  structure MED et requêtées au niveau des classes proxy en spécifiant
+  les identifiants des champs impliqués et les paramétres requis (pas
+  de temps en particulier).
+
+Concernant le module MED:
+
+* IMP: pourvoir exporter la structure med dans un fichier med (la
+  structure ayant pu être enrichie par la publication de champs créés
+  par les operations de champs.
+
+
+Historique des travaux
+======================
+
+20100726 : mise au point du schéma de conception
+------------------------------------------------
+
+Choix entre MEDMEM et MEDCoupling: on reste sur MEDMEM pour plusieurs
+raisons:
+
+* MED Coupling ne peut pas gérer des mailles de dimensions différentes
+  dans un même modèle (choix faits dans un soucis de performance dans
+  l'accès à une structure de donnée compact). On peut contourner le
+  problème en définissant deux champs pour traiter chacun des type de
+  mailles.
+* Un champ repose sur un maillage complet (pas de notion de profil,
+  mais cela peut être émulé en créant deux maillages)
+* Le concept de point de gauss n'existe pas (pas implémenté)
+
+TODO:
+
+* Idéalement, il conviendrait de faire un état des lieux du module
+  MED, en particulier des éléments MEDMEM (le coeur), les interfaces
+  CORBA associées (MED.idl implémenté dans le package source
+  MEDMEM_I), l'engine (composant SALOME d'interface MED_Gen.idl et
+  implémenté dans le package source MED) et le GUI (MedGUI.cxx
+  implémenté dans le package source MEDGUI).
+
+* Ergonomie TUI et modèle CORBA associé:
+
+  1. Charger un objet medmem (puis les objets métier mesh et field)
+     sur un domaine d'application donné.
+  2. En faire des variables disponibles dans l'interface TUI et que
+     l'on peut manipuler dans des opérations algébriques.
+  3. Pouvoir au besoin en faire des objets CORBA pour l'interface avec
+     les autres modules SALOME.
+
+* Compléter le diagramme de la structure informatique de MED (en
+  particulier l'implémentation des interface IDL).
+* Préparer un module de travail XMED (organisation d'une bibliothèque)
+
+Tests à réaliser:
+
+* Est-il possible de faire des opérations algébriques à partir des
+  objets SALOMEMED (objects CORBA MED)?
+* Création d'un objet MED_i à partir d'une objet MED pur préalablement
+  chargé en mémoire.
+
+A retenir:
+
+* Des opérations de champs sont possibles sur des champs à des pas de
+  temps fixés. Si l'opération doit être menée sur plusieurs pas de
+  temps, alors itérer sur chaque pas de temps. L'idée ici est
+  d'introduire le concept de série temporelle de champs en temps
+  qu'objet manipulable.
+* Pour deux champs différents de la même structure MED, la données des
+  identifiants dt et it ne correspond pas forcément au même instant
+  absolu (en tout cas rien ne le garanti, même si c'est tout de même
+  une pratique courante).
+
+20101005 : première maquette de démonstration de l'ergonomie en MEDMEM pur
+--------------------------------------------------------------------------
+
+XMED: svn révision 16
+Travailler avec le fichier de donnée testfield.med joint.
+
+
+20101007 : Vers une maquette CORBA
+----------------------------------
+
+Le contexte d'utilisation des opérations de champs est l'environnement
+SALOME. Le support de gestion des données est donc l'étude SALOME. Au
+plus bas niveau, les champs sont des objets MEDMEM instanciés dans une
+session SALOME (soit par un code de calcul intégré, soit par
+chargement des données à partir d'un fichier med). Ces objets sont en
+général référencés dans l'étude SALOME sous la forme d'objets CORBA de
+classe SALOMEMED::FIELD. Plus exactement, l'étude SALOME gère des
+SObject (Study Object) dont un attribut est une référence vers un
+objet CORBA de classe SALOMEMED::FIELD qui lui-même encapsule un objet
+MEDMEM::Field.
+
+On peut donc envisager une solution dans laquelle on donne à
+l'utilisateur des poignées de manipulation des objets
+SALOMEMED::FIELD, par exemple au moyen d'un modèle informatique de
+type proxy. Cela signifie que l'utilisateur ne manipule pas
+directement des objets MEDMEM mais des objets python qui font
+l'interface (à concevoir et implémenter, a priori avec un design
+pattern de type proxy).
+
+L'utilisation directe des objets MEDMEM aurait pu être une solution
+extremement pratique dans la mesure où ces objets en l'état peuvent
+être combinés dans des opérations de champs (c'est déjà
+implémenté). Par contre, ce procédé souffre de limitations importantes
+dans la gestion et la circulation des données pour les différents cas
+d'utilisation envisagés (visualisation, export, transfert à un autre
+module SALOME).
+
+L'avantage de la solution proposée est multiple:
+
+* Elle permet de travailler sur une structure MED cohérente pour
+  intégrer les résultats des opérations de calculs et combiner des
+  champs cohérents entre eux. Tout passe par des classes proxy qui
+  pourront s'assurer de la cohérence des opérations demandées et
+  exécuter automatiquement les fonctions de pré-traitement ou
+  post-traitement requises pour ces opérations. On peut imaginer par
+  exemple que les requêtes d'opération soient envoyées par les classes
+  proxy à la structure MED à laquelle les champs sont associés pour
+  piloter l'opération en MEDMEM pur.
+* Elle permet d'automatiser un certain nombre d'opérations
+  implicites. Par exemple si deux champs ne sont pas définis dans la
+  même unité, un changement d'unité peut être effectué automatiquement
+  par la classe proxy avant de commander l'opération au niveau
+  MEDMEM.
+* Elle permet de laisser les données sur le container SALOME et de
+  réaliser des opérations sans rappatrier les données en local (qui
+  peuvent être en trés grand nombre).
+* Elle permet d'étendre facilement l'ergonomie de manipulation des
+  champs, par exemple en définissant la notion de *série temporelle de
+  champs*, ou encore les concepts de *domaine de définition* évoqués
+  dans les spécifications fonctionnelles.
+* Elle rend immédiat la circulation des données entre modules SALOME,
+  puisque les champs restent accessble par des objets CORBA, en
+  particulier pour la visualisation ou l'export des champs produits
+  par les opérations.
+
+Elle a cependant des inconvénients et/ou limitations:
+
+* Elle nécessite l'implémentation d'une classe proxy pour encapsuler tous
+  les appels aux objets SALOME_MED (et donc MEDMEM). Cette interface
+  se limite a priori aux opérations de champs (les opérations
+  algébriques dans un premier temps).
+* Les champs à manipuler dans une opération donnée doivent être gérés
+  par la même structure MED.
+
+Il est à noter également que les interfaces de programmation de
+SALOMEMED (interface CORBA pour MEDMEM) devront être étendues pour
+permettre des requêtes de manipulations de champs (fonctions addition,
+soustraction, multiplication, ...). Pas de contrainte ici sur
+l'ergonomie puisque la manipulation par l'utilisateur se fera au
+niveau des classes proxy uniquement.
+
+
+Hypothèses:
+
+* On tente ici une maquette qui exploite dans la mesure du possible le
+  fonctionnement actuel du module MED, en particulier la gestion des
+  données dans l'étude.
+* Dans une deuxième version, on pourra examiner sérieusement la
+  révision de la gestion des données dans le module, quitte à la
+  spécifier et maquetter dans XMED pour intégration ultérieure dans
+  MED. Exemple:
+
+  - Pouvoir gérer plusieurs structures med dans l'étude.
+
+* Enfin, on exploite MEDMEM en l'état. Pour les besoins de la gestion
+  des données (gestion des chargements des champs en particulier,
+  références croisées pour retrouver le med à partir du champ par
+  exemple, ...), il pourra être nécessaire de faire évoluer MEDMEM. Il
+  faut pouvoir par ailleurs gérer indifféremment une structure med (et
+  les champs qui y sont associés) qu'elle soit créée en mémoire from
+  scratch ou chargée d'un fichier (donc attention avec les opérations
+  de lecture read(), sur les maillages comme sur les champs). La
+  structure med permet d'obtenir les méta données (meta-field par
+  exemple) mais ne permet pas de savoir si les données sont
+  physiquement chargées ou pas.
+
+
+Révisions:
+
+* XMED svn revision 21 + tarball MED_SRC-20101014-15h26m.tgz.
+  Première version qui permet d'importer un champ dans la console
+  python sous la forme d'un FieldProxy. Ne permet pas encore de faire
+  des opérations. Introduction dans le module MED de l'interface MEDOP
+  pour prendre en charge les opérations sur les champs.
+
+
+20101019 : Maquette de démonstration pour l'addition
+----------------------------------------------------
+
+Cette maquette implémente une solution technique de bout en bout (de
+l'interface python aux objets MEDMEM, en passant par le fieldproxy
+puis les servants CORBA pour les operations, ...) mais sur le
+périmètre de l'addition de champs sur tout leur domaine de définition
+et pour un pas de temps donné.
+
+Limitations:
+
+* gére l'addition de champs de type double uniquement (parceque le
+  reste n'est pas implémenté)
+
+Révisions:
+
+* XMED: svn révision 25
+* MED: cvs tag BR_medop_20101019
+
+
+20101020: Fonctions complémentaires
+-----------------------------------
+
+Cette version test la faisabilité des fonctions complémentaires pour
+accompagner la manipulation de champs. Cela comprend en particulier:
+
+* **la sauvegarde des champs produits** dans un fichier med (un champ ou
+  toute la structure med). Pour cela, on définit un med proxy comme
+  l'extention du SALOME_MED::MED (prévir plutôt d'implémenter ce type
+  de fonction au niveau C++ pour permettre un usage au niveau du GUI
+  C++?).
+* **la visualisation d'un champ** au moyen du module VISU.
+* **des fonctions d'aide interactives** pour assister l'utilisateur
+  dans la console de manipulation des champs.
+
+
+Questions:
+
+* peut-on sauvegarder un champ unique?
+* peut-on faire en sorte que ce soit l'affectation à une variable qui
+  provoque l'ajout du champ à la structure med (ou plus exactement qui
+  supprime tous les champs intermédiaires).
+
+
+Révision:
+
+* XMED: svn revision 31
+* MED: cvs tag BR_medop_20101025
+
+
+20110606: commit avant transfert dans git
+-----------------------------------------
+
+* XMED: svn revision 53
+
+Les parties de MED utiles à MEDOP seront reversées dans XMED
+dans une première étape, puis le tout dans MED 6 au final. 
diff --git a/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2011.rst b/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2011.rst
new file mode 100644 (file)
index 0000000..2c38e64
--- /dev/null
@@ -0,0 +1,473 @@
+.. meta::
+   :keywords: maillage, champ, manipulation
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ANNEXE: Note de travail concernant le chantier XMED 2011
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+Cas d'utilisation métier
+========================
+
+On illustre par un exemple (Christophe Vallet, R&D/MMC, 1/7/2011)::
+
+ J'ai souvent des fichiers med de résultats de calcul, et j'aimerais y
+ ajouter de nouveaux champs issus de champs existants. J'aimerais
+ aussi pouvoir créer de nouveaux meds plus petits par extraction de
+ certaines composantes de champs, certains groupes ou certains pas de
+ temps.
+
+On peut exprimer le besoin sous la forme des cas d'utilisation
+suivants (use cases):
+
+* **UC1: combiner dans un même fichier med des champs issus de
+  plusieurs sources de données**. On peut par exemple charger un
+  premier fichier, puis ajouter à cette base des champs issus d'autre
+  fichiers ou générés par manipulation de champs, ou encore générés
+  par un module de calcul qui produirait directement du MEDCoupling.
+* **UC2: créer un champ contenant certaines composantes d'un autre
+  champ**. On pense ici aux fonctions de restriction, qui permettraient
+  de récupérer certaines composantes uniquement.
+* **UC3: créer un champ contenant certains pas de temps d'un autre
+  champ**. C'est un cas particulier des fonctions de restriction
+  évoquées ci-dessus.
+* **UC4: créer un champ comme la limitation d'un autre champ à un
+  groupe de mailles**. C'est un cas particulier des fonctions de
+  restriction évoquées ci-dessus. Notion de domaine spatial. A
+  priori la notion de groupe est définie dans MEDLoader.
+
+On peut ajouter également les UC identifiés pour la maquette 2010:
+
+* **UC5: comparer des champs issus de source de données différentes**,
+  par exemple des champs chargés de deux fichiers med différents et
+  qui s'appuient sur le même maillage (au moins conceptuellement).  Le
+  problème technique ici est de pouvoir changer le maillage d'un
+  champ, pour ramener tous les champs sur le même maillage (au sens
+  informatique). Ceci est une contrainte de MEDCoupling, les
+  opérations sur des champs A et B imposent que A et B soient définis
+  sur le même maillage, i.e. le même objet informatique.
+* **UC6: créer un champ de toute pièce sur un maillage**, ou un groupe
+  de mailles. Ce cas d'usage est typiquement prévu pour produire les
+  conditions de chargement initial d'une structure. Il s'agit ici
+  d'initialiser un champ à partir de zéro sur une surface prédéfinie
+  de la géométrie (par exemple spécifiée par un nom de groupe de
+  mailles).
+
+Pour UC5: les sources de données sont référencées dans l'object
+browser. On importe explicitement les données dans l'espace de
+travail. On peut détecter que les maillages sont identiques et on
+propose à l'utilisateur de transférer le champ sur le maillage déjà
+présent. Sinon, les champs devront être référencés sur des maillages
+distincts dans l'arbre de l'espace de travail.
+
+Analyses préliminaires pour le chantier 2011
+============================================
+
+On fait le choix pour le chantier 2011 de travailler à partir de la
+bibliothèque MEDCoupling (et non plus MEDMEM comme c'était le cas dans
+le démonstrateur 2011).
+
+Analyse de MEDCoupling et MEDLoader
+-----------------------------------
+
+MEDCoupling est l'implémentation du modèle de données MED (avec
+recherche de minimisation des dépendances logicielles) et MEDLoader
+fournit une ensemble de fonctions pour le chargement des structures
+MEDCoupling depuis un fichier ou inversement leur sauvegarde sous
+forme de fichiers.
+
+Dans l'implémentation MEDCoupling, un champ est l'ensemble des valeurs
+d'une grandeur physique sur un maillage pour un pas de temps donné. Un
+champ est caractérisé par:
+
+* un support spatial, le maillage
+* un type de discrétisation spatial, défini par l'emplacement des
+  valeurs sur le maillage (sur les noeuds, sur les cellules, aux
+  points de gauss, ...) et le mode d'interpolation spatial (P0, P1,
+  etc)
+* un pas de temps, défini par deux entiers (iteration, order) et un
+  réel (timestamps)
+
+Dans cette implémentation, il existe une association 1..n entre un
+maillage et un champ (alors que dans MEDMEM, la structure
+intermédiaire SUPPORT est implémentée).
+
+MEDCouplingCorba fournit un ensemble de servants CORBA pour manoeuvrer
+des structures MEDCoupling au travers du bus CORBA. L'interface à ce
+jour est délibérément réduite. Des classes dites "Cliente" sont
+fournies pour piloter les servants CORBA depuis un contexte
+client. Par exemple ``MEDCouplingFieldDoubleClient`` fournit une
+fonction de création d'une structure MEDCoupling à partir d'un
+pointeur vers un servant CORBA. La structure est créée localement
+(dans le contexte client) avec duplication des données issue de la
+structure encapsulée par le servant CORBA (récupération par la
+fonction de sérialisation).
+
+Aucune interface CORBA n'est défini pour MEDLoader.
+
+Questions:
+
+* Voir comment sont créés les servants, et surtout comment ils sont
+  récupérés (via le lcc?)
+* Comment peut-on définir un champ sur un groupe de mailles (et non
+  pas sur le maillage complet)? Comment peut-on extraire le champs
+  circoncit à une groupe de mailles pour des opérations.
+
+  - R: méthode changeUnderlyingMesh
+
+* Comment manipuler deux champs chargées de fichiers différents mais
+  construit sur le même maillage (conceptuellement). On peut forcer la
+  réassociation d'un champ sur un autre maillage?
+* Manipuler des champs de pas de temps différents? Différentes
+  composantes d'un ou plusieurs champs?
+* Comment importer un MedCoupling dans PARAVIS? (dans VISU?)?
+
+* mapper sur une image
+
+Improvments:
+
+* MEDLoader::Write should raise an exception if the filepath is not writable
+* MEDDataManager: développer une classe chapeau sur MEDCoupling et
+  MEDLoader pour  aider au chargement et la gestion de données MED
+  (orienté manipulation de champs). Cette classe serait associée des
+  structures légères FieldHandler et MeshHandler et des listes
+  correspondantes pour la navigation dans les méta-données.
+* Sur base du MEDDataManager, prévoir des ports med pour yacs par
+  lesquels pourrait transiter des handler.
+
+Nouveaux concepts à prendre en compte
+-------------------------------------
+
+Au démarrage du chantier 2011, on observe que les concepts suivants
+sont introduits dans le module MED: 
+
+* Le conteneur MED n'existe plus, utiliser MEDFILEBROWSER pour charger
+  les fichiers med et obtenir les informations générales sur le
+  contenu.
+* MEDFILEBROWSER: remplace le concept de driver et fournit les
+  fonctions précédemment fournies par la classe MED pour obtenir les
+  informations de structure.
+* Concept d'Extractor pour une lecture sélective des données de champs
+  (suivant un critère d'extraction)
+* Il n'est plus nécessaire d'appeler les méthodes read explicitement
+  sur les objets (MESH et FIELD) pour charger les données. Par
+  ailleurs, on peut définir deux fois le même champs (double
+  chargement a priori) sans lever d'exception).
+
+
+Analyse de conception pour le chantier 2011
+===========================================
+
+Composants SALOME (interfaces IDL)
+----------------------------------
+
+* MEDDataManager: défini une structure FIELD pour identifier un champ
+  dans les requêtes. Il s'occupe également de la récupération physique
+  des données, quelqu'en soit la source (fichier avec MEDLoader, autre
+  module SALOME comme PARAVIS avec une méthode à définir)
+* MEDCalculator: s'occupe des requêtes de calcul dont les arguments sont
+  les structures FIELD du MEDDataManager. Reprendre l'interface de
+  MEDOP.
+
+Use case à réaliser depuis un client python:
+
+* UC01: ajouter un fichier d'entrée et accéder aux informations
+  concernant les champs. Ex: récupérer une structure champs par la
+  donnée des paramètres primaires (nom identifiant, dt, it, nom du
+  maillage).
+* UC02: créer des champs et les ajouter au MEDDataManager
+* UC03: mener des opérations basique sur les champs en console python
+
+Interface Utilisateur
+---------------------
+
+L'interface utilisateur est composée des parties suivantes:
+
+* une partie GUI (appelée par la suite MEDGUI) qui s'occupe de piloter
+  le chargement des données dans l'espace de travail, au moyen d'une
+  interface graphique;
+* une partie TUI (appelée par la suite MEDTUI) qui s'occupe de piloter
+  la création de champs, au moyen de commandes exécutées dans la
+  console python.
+
+Le principe est que les champs sont préalablement chargés au niveau du
+composant SALOME au moyen de l'interface graphique (MEDGUI), puis
+manoeuvrés depuis l'application SALOME au moyen de variables proxy
+définies dans la console python (MEDTUI). Au chargement, les champs
+sont indéxés par le MEDDataManager, puis les index sont rendus
+accessibles au niveau du GUI au moyen d'une représentation
+arborescente de la structure MED. Les feuilles de l'arbre
+correspondent à des champs qui peuvent être sélectionnés et dont
+l'index peut être obtenu de la sélection.
+
+L'espace de travail est organisé autour du concept de
+"workspace". L'étude SALOME liste les datasource (les fichiers source
+des données med, mais peut-être aussi les référence vers des objets
+MED déjà existants ou chargé dans PARAVIZ). Une vue complémentaire
+permet de voir la structure fine d'une source de données.
+
+Concernant MEDGUI:
+
+* la représentation des données (les champs et les maillages associés)
+  doit permettre de récupérer par l'interface graphique les
+  identifiants des champs à manipuler (a priori les structures FIELD
+  définies par le composant MEDDataManager). Cela conduit à la mise en
+  place des composants suivants:
+
+  - MedDataModel hérité de TreeData. Il est peuplé avec les
+    méta-données décrivant la structure MED explorée.
+  - MedGuiManager qui permet l'implantation du doc widget de
+    présentation
+
+TODO:
+
+* specifier le concept de workspace (qui a une entrée dans l'étude?)
+  en bijection avec un datamanager
+* identifier des interlocuteur/utilisateur pour l'aspect ergonomie d'usage
+
+Concernant MEDTUI:
+
+* Il fournit les classes FieldProxy
+
+Questions:
+
+* Comment traiter le cas du travail sur des composantes ciblées, plus
+  généralement, comment introduire le concept de domaine
+  d'application?
+* Prévoir des fonctions génériques (initialisation d'un champ sur un
+  maillage avec une fonction analytique de la position, sauvegarder
+  les champs créés dans un fichier med)
+
+
+Tâches de développement
+=======================
+
+T20110622.1: Gestion des données internes
+-----------------------------------------
+
+**Status: terminé.**
+Suite: fonction de sauvegarde au niveau graphique également
+
+On vise les cas d'utiliation suivants:
+
+* UC1: intégrer dans le datamodel du gui un champ créé dans la console
+  python (et donc présent dans le datamanager du composant). Définir
+  l'utilité?
+* UC2: renommer un champ et plus généralement changer ses méta-données
+  (avec assurance de synchronisation entre toutes les données).
+* UC3: sauvegarder une sélection de champs. La sélection peut se faire
+  dans l'arbre du datamodel gui.
+
+WARN: robustesse de fieldproxy
+
+
+
+T20110622.2: UC Initialisation/Création de champs
+-------------------------------------------------
+
+**Status: à faire**
+
+Les cas implémentés à ce jour sont la création de champs à partir de
+champs existants et chargés d'un fichier med. On souhaite ici réaliser
+des cas 'utilisation autour de la création de champs "from scratch",
+s'appuyant tout de même sur un maillage chargé.
+
+UC01: Sélection d'un groupe de maille dans SMESH pour initialiser un
+champ (par exemple les conditions limites d'un problème de calcul).
+
+UC02: créer un champ avec des restrictions qui définissent le domaine
+d'application des opération de champs.
+
+UC03: créer un champ à partir d'une image (codes rgb utilisé comme les
+composantes du champs vectoriel ou niveaux de gris pour un champ
+scalaire. Attention, pour ça, il faudra a priori fiare une projection
+du maillage cartesien de l'image sur le maillage (quelconque) sur
+lequel on souhaite définir le champ.
+
+UC04: créer un champ à partir d'un tableau numpy
+
+De manière générale, ce type de création sera assisté par le
+MEDGUI. Au niveau MEDTUI, les fonctions pourraient être fastidieuses
+pour l'utilisateur.
+
+Par exemple, prévoir un menu contextuel qui propose les opérations
+possibles en fonction de la sélection (en plus de la fonction d'import
+dans la console python).
+
+TODO:
+
+* développer les fonctions d'initialisation, par exemple au moyen
+  d'applyFunc et du mécanisme de callable?
+
+T20110622.3: documentation contextuel
+-------------------------------------
+
+**Status: à faire**
+
+* Remettre toutes les commandes dans le même fichier (fusionner cmdtools
+  et fieldtools)
+* Faire un modèle générique de command (classe de base
+* Batir la doc des commandes sur cette base (lister toutes les
+  instances de type Command par exemple)
+
+T20110622.4: remontée des exception du composant MEDCalculator
+--------------------------------------------------------------
+
+**Status: en cours, compléter la couverture**
+
+Pour des messages contextuel sur les erreurs de calcul (ex: division
+par 0)
+
+* Poursuivre le travail fait sur getMedEventListener
+* Protéger tous les appels au composants effectués depuis la console
+  python (prendre example sur la commande save)
+
+T20110624.1: gestion des données GUI
+------------------------------------
+
+**Status: à faire**
+
+
+
+Le workspace a une entrée dans l'obrowser. Sur cette entrée on peut:
+
+* supprimer: supprime tout les champs associés
+* sauvegarder. Dans ce cas, on rappelle l'ensemble des champs pour
+  cocher ceux qu'on veut sauvegarder.
+
+Le gui data model est réservé aux opérations sur les champs et à
+piloter leur import dans la console python.
+
+TODO:
+
+* Spécifier les concepts de workspace, database, et datasource, espace
+  de gestion, ... et les associations. Simplifier avec l'appuie de use
+  cases.
+* Mécanisme de mise à jour du TreeView de XSALOME (aujourd'hui, seul
+  l'ajout addChild est implémenté
+* Clic droit sur objets de l'arbre: dans la notification TreeView ->
+  WorkspaceController, faire remonter l'évènement clic droit ainsi que la
+  liste des éléments sélectionné pour faire générer le menu contextuel
+  au niveau du WorkspaceController qui peut déterminer le contexte métier
+  (le TreeView ne le connaît pas).
+* Définir des DataObject pour les maillages, les séries temporelles et
+  les champs
+
+
+Spécification des espaces de données:
+
+* MEDDataManager dépend de l'étude (pour permettre la publication
+  d'information dans une étude SALOME).
+* créer "sourcid = MEDDataManager::addDataSource(filename)", suivie de
+  requetes getFields(sourceid), getMeshes(sourceid)
+* les espaces de données: dataspace, workspace. Un seul workspace par
+  étude, mais autand de datasources que l'on souhaite dans le
+  dataspace. Les datasources sont rangés dans l'étude (le dataspace)
+  et sont non modifiables après chargement (référence des sources de
+  données).
+
+
+T20110628.1: extention à d'autres objets SALOME
+-----------------------------------------------
+
+**Status: suspendu**
+
+On doit reposer la question de l'existance de l'arbre indépendant
+(DockWidget), d'une part, et l'extention aux autres objets (GEOM et
+SMESH en particulier) du principe de sélection graphique pour
+utilisation dans la console python, d'autre part.
+
+
+T20110628.2: visualisation d'un champ avec PARAVIS
+--------------------------------------------------
+
+**Status: terminé (pour une première version)**
+Suite: de nombreux défauts subsistent
+
+Questions/remarques:
+
+* Pb au démarrage du module: VisTrails fails to start
+* Peux-t-on piloter la vue 3D sans charger le module? (voir
+  myparavis.py)
+* Comment donner un nom au MEDReader1 dans l'arbre Pipeline?
+* Comment utiliser directement les objets MEDCouplingField?
+
+
+T20110706.1: documentation du module
+------------------------------------
+
+**Status: en cours (10%)**
+
+Documenter les commandes TUI puis l'utilisation générale de
+l'interafce graphique. Mentionner l'existance de la commande medop.sh
+pour travailler exclusivement en mode texte (utile pour les tests
+rapides).
+
+Documenter les modalités d'exécution des tests.
+
+T20110708.1: helper python pour MEDCoupling
+-------------------------------------------
+
+**Status: en attente (pas urgent)**
+
+Faire un helper python dans le package xmed qui permet de faire du
+medcoupling facilement (essentiellement pour simplifier le chargement,
+puis la sélection des données). Cela demanderait de faire un
+MedDataManager comme une class C++ pure (non CORBA). Cette classe
+travaillerait par exemple uniquement avec des id et des liste d'id, et
+fournirait des fonctions d'affichage (comme le ``ls`` et le ``la``)
+pour obtenir des meta-information.
+
+Le servant MedDataManager pourrait être une surcouche de cette classe
+c++ pure.
+
+T20110708.2: analyses et tests
+------------------------------
+
+TODO:
+
+* créer un fichier de test avec plusieurs pas de temps
+* créer un fichier de test avec des groupes de mailles
+
+
+T20110728.1: refactoring MEDDataManager
+---------------------------------------
+
+Refactoring pour une meilleur association entre FieldHandler et MeshHandler:
+
+* dans la mesure du possible utiliser les id plutôt que les handler en
+  arguments des fonctions d'appel des objets
+* A chaque champ (FieldHandler), on doit associer un meshid (et de
+  manière optionnelle un fieldseriesId, si le champ peut être associé
+  à une serie temporelle. A priori faisable uniquement au chargement
+  du datasource).
+* Pour cela, revoir les fonctions internes newFieldHandler et addField
+  ou prévoir de les compléter à chaque fois qu'elles sont appelée avec
+  les informations concernant le meshid.
+* addField est utilisée par le MEDCalculator
+* Attention au raffraichissement des données handler au niveau du
+  Workspace. Peut-être le mieux est que les fieldproxy contiennent
+  uniquement le fieldid, et qu'ils interroge le datamanager à chaque
+  fois qu'ils ont besoin d'une donnée. Voir aussi les notifications
+  via le MEDEventListener?  **Le plus simple est de faire la mise à
+  jour lors de l'appel à la méthode __repr__ du fieldproxy, i.e. quand
+  on essaye d'afficher les données**. Parceque sinon il n'y a pas de
+  problème puisque que le calculateur travaille à partir des id.
+
+
+Petites améliorations du DataspaceController:
+
+* Au OnUseInWorkspace, stocker (dans la mesure du possible) le nom de
+  l'alias python dans un attribut du sobject.
+* Dans DlgChangeUnderLyingMesh, expliquer que le champs sera dupliquer
+  est posé dans le WS. On peut donc proposer en option de lui associer
+  un alias pour manipulation dans la console
+
diff --git a/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2012.rst b/src/MEDOP/doc/sphinx/fr/medop-workingnotes-2012.rst
new file mode 100644 (file)
index 0000000..b6ecb6d
--- /dev/null
@@ -0,0 +1,84 @@
+.. meta::
+   :keywords: maillage, champ, manipulation
+   :author: Guillaume Boulant
+
+.. include:: medop-definitions.rst
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ANNEXE: Note de travail concernant le chantier XMED 2012
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. contents:: Sommaire
+   :local:
+   :backlinks: none
+
+
+Analyse preliminaire pour le chantier 2012
+==========================================
+
+La figure imposée pour le chantier 2012 est l'intégration du nouveau
+module de manipulation de champs dans SALOME 6.6 (objectif CEA), en
+préparation de la mise en exploitation dans SALOME 7 (objectif EDF).
+
+L'état actuel est:
+
+* Un module SALOME de nom MED intégrant les bibliothèques MEDCoupling,
+  MEDLoader, REMAPPER, mais aussi plusieurs packages logiciels
+  aujourd'hui obsolètes ou amener à disparaître pour l'échéance
+  SALOME7
+* Un module SALOME de nom XMED qui fournit les fonctions graphiques
+  pour la manipulation de champs.
+* Ce module XMED utilise le module VISU pour les vue de contrôle.
+
+La cible est:
+
+* Un module unique (nom à définir, par exemple MEDOP) débarrassé des
+  packages logiciels obsolètes et intégrant les fonctions graphiques
+  (GUI et TUI).
+* L'utilisation du module PARAVIS (au lieu de VISU) pour les vues de
+  contrôle.
+* L'intégration de MEDCoupling avec YACS (port MED dans YACS par
+  exemple).
+
+A examiner:
+
+* voir les attendus concernant les ports MED dans YACS
+* interface PARAVIS: utilisation du viewer (et de l'API python) sans chargement du GUI
+
+Tâches de développement
+=======================
+
+20120904: Migrer XMED dans MED
+------------------------------
+
+Plan de travail:
+
+* Migration des composants + test
+
+
+
+20120904: Nettoyage de XSALOME
+------------------------------
+
+:status: en cours
+
+* Supprimer les vieilleries de XSALOME:
+
+  - StdHelper -> Basic_Utils (KERNEL)
+
+20120829: mise en place du chantier 2012
+----------------------------------------
+
+:status: terminé
+
+L'objectif de cette première étape est de reverser le prototype 2011
+(module XMED indépendant) dans la branche V6_main du module MED. On
+peut procéder de la manière suivante:
+
+* update de XMED (et XSALOME utilisé par XMED) pour fonctionnement sur
+  V6_main
+* Eliminer la dépendance à XSALOME
+* Supprimer la gestion des multiversion SALOME5/6 au niveau de l'engine
+
+.. warning:: TODO: refaire le point sur les tâches initiées en 2011 
+
index 532c285e6c7c3d6e0730053a0bb219dfc4d83b42..4ec113636526dbf72100152c3bcb549ee1ddd319 100644 (file)
Binary files a/src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png and b/src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png differ
index cf3fa4b1ef0b33c6cbeb811a1388e1aac9bd4507..e291c971ce52733d1c9192730b018b08a0f072be 100644 (file)
@@ -1,18 +1,16 @@
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%
- Documentation du module MED
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Documentation of MED module
+%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Le module SALOME MED (pour Modèle d'Echange de Données) fournit la
-bibliothèque MEDCoupling (bibliothèque C++ dédiée à la manipulation de
-maillages et de champs conformes au modèle MED), ainsi qu'une
-interface graphique pour la réalisation des opérations de manipulation
-les plus usuelles.
+The SALOME MED module provides MEDCoupling library (a C++ library dedicated of
+mesh and field manipulation consistent with MED model), as well as a Graphical
+User Interface to access some usual operations.
 
-Documentation de référence
-==========================
+References
+==========
 
-**Documentation d'utilisation**
+**User documentation**
 
 .. toctree::
    :maxdepth: 1
@@ -20,7 +18,7 @@ Documentation de référence
    medop-userguide-gui.rst
    medop-userguide-api.rst
 
-**Documentation technique**
+**Technical documentation** (**in french**):
 
 .. toctree::
    :maxdepth: 1
@@ -28,15 +26,15 @@ Documentation de référence
    medop-specifications.rst
    medop-develguide.rst
 
-**Documentation annexe**
+**Additional documentation**
 
 .. toctree::
    :maxdepth: 1
 
    medop-references.rst
 
-Archives documentaires
-======================
+Document archive (in french)
+============================
 
 **Documentation du prototype 2010**
 
index 0cb67b4e562729049faad89c4507568b4095c405..3b4e371648f3abd2d3c2b776e07b16d590c39603 100644 (file)
@@ -14,7 +14,7 @@
 .. _REF_EDF_VCA_H-I2C-2009-03595-FR: _static/documents/20091218_EDF_VCANO_H-I2C-2009-03595-FR.pdf
 
 .. You can refer to this reference using the keyword: |REF_CEA_VBE_MEDMEM|_
-.. |REF_CEA_VBE_MEDMEM| replace:: Guide utilisateur de MED mémoire
+.. |REF_CEA_VBE_MEDMEM| replace:: MEDMEM user's guide
 .. _REF_CEA_VBE_MEDMEM: _static/documents/20070105_CEA_VBERGEAUD_GuideutilisateurMEDMEMOIRE.pdf
 
 .. You can refer to this reference using the keyword: |REF_EDF_GBO_WORKNOTE|_
index 9be8cdc5f70e4dcb4751e0c496bb640b117c23d0..0cc327834072d200b4008b0345e45534436572c9 100644 (file)
@@ -1,16 +1,16 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-ANNEXE: Références documentaires
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Appendix: Documentation references
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 .. include:: medop-definitions.rst
 
-Documents de référence:
+References:
 
-* |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009
+* (**in french**) |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009
 * |REF_CEA_VBE_MEDMEM|_ - Vincent Bergeaud - janvier 2007
-* |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF)
+* (**in french**) |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF)
 
-Présentations:
+Slides (**in french**):
 
 * |REF_EDF_PRESMANIPCHP01|_ - Valérie Cano, Guillaume Boulant - janvier 2010
 * |REF_EDF_PRESMANIPCHP02|_ - Guillaume Boulant - octobre 2010
@@ -18,11 +18,11 @@ Présentations:
 * Présentation à la Journée des Utilisateurs de SALOME de 2011 (JUS2011):
 
   - |REF_EDF_JUS2011_PDF|_ - Anthony Geay (CEA), Guillaume Boulant - novembre 2011
-  - |REF_EDF_JUS2011_OGV1|_
-  - |REF_EDF_JUS2011_OGV3|_
-  - |REF_EDF_JUS2011_OGV4|_
+  - |REF_EDF_JUS2011_OGV1|_ (**video**)
+  - |REF_EDF_JUS2011_OGV3|_ (**video**)
+  - |REF_EDF_JUS2011_OGV4|_ (**video**)
 
-Notes de travail:
+Working notes (**in french**):
 
 * |REF_EDF_GBO_WORKNOTE|_ - Guillaume Boulant - novembre 2010
 * |REF_EDF_ELO_REM|_ - Eric Lorentz - novembre 2010
index f09404a6498c5620a95106d4bc478d64c5ace580..3494402c5b2b0b7fc574487613a72039e2dd57f0 100644 (file)
@@ -1,93 +1,83 @@
 .. meta::
-   :keywords: maillage, champ, manipulation, guide utilisateur
+   :keywords: mesh, field, manipulation, user guide
    :author: Guillaume Boulant
 
 .. include:: medop-definitions.rst
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Module MED: Guide d'utilisation de l'interface graphique
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+MED module: User guide for graphical interface
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Ce document est un guide rapide pour l'utilisation de l'interface
-graphique du module MED. Il montre comment utiliser le module sur la
-base de quelques exemples de référence, inspirés des cas d'utilisation
-identifiés lors de l'analyse des besoins en matière de manipulation de
-champs.
+This document is a quick guide for Graphical User Interface of MED module. It
+shows how to use this module on the basis of a few reference examples, built
+from use cases identified during requirement analysis stage.
 
-.. warning:: Le document est autonome, mais il est vivement conseillé
-   de parcourir au préalable (ou en parallèle) :doc:`le document de
-   spécifications<medop-specifications>`, au moins pour fixer les
-   concepts et la terminologie.
+.. warning:: This document is self-contained, but it is strongly advised to
+             read :doc:`the specification document<medop-specifications>` (in
+             french), at least to clarify concepts and terminology.
 
-.. contents:: Sommaire
+.. contents:: Contents
    :local:
    :backlinks: none
 
-Présentation générale du module MED
-===================================
-
-L'ergonomie générale d'utilisation du module de manipulation de champs
-est inspirée des logiciels comme octave ou scilab. Elle associe une
-interface graphique, pour sélectionner et préparer les données, avec
-une interface texte (la console python) pour le travail effectif sur
-les données.
-
-Pour cela, le module propose deux espaces utilisateurs qui sont
-symbolisés par les rectangles rouges et vert sur la capture d'écran
-ci-dessous:
-
-* **l'espace des données** (*dataspace*), dans lequel l'utilisateur
-  définit les sources de données med (*datasource*), c'est-à-dire les
-  fichiers med dans lesquels sont lus les champs et maillages. Cet
-  espace permet l'exploration des maillages et des champs fournis par
-  les différentes sources de données.
-* **l'espace de travail** (*workspace*), dans lequel l'utilisateur
-  peut déposer des champs sélectionnées dans l'espace source, pour
-  ensuite les travailler par exemple pour produire des nouveaux champs
-  au moyen des fonctions de manipulation fournies par l'interface
-  textuelle (console python TUI).
+.. warning:: Screenshots are not up-to-date. They were extracted from SALOME
+             6 with data visualization achieved using VISU module. In SALOME
+             7, VISU module has been replaced by PARAVIS module. The
+             look-and-feel may thus be slightly different.
+
+General presentation of MED module
+==================================
+
+The overall ergonomics of MED module for field manipulation is inspired by
+softwares such as octave or scilab. It combines a graphical interface (GUI) to
+select and prepare data, with a textual interface (the python console, TUI)
+for actual work on data.
+
+This module provides two user environments that are marked by the red and
+green rectangles on the screenshot below:
+
+* **The data space** (*dataspace*), in which user defines the MED data sources
+  (*datasource*), that is to say the med files from which meshes and fields
+  are read. This data space allows for the exploration of meshes and fields
+  provided by the different data sources.
+* **The workspace** (*workspace*), in which user may drop fields selected in
+  the source space, and then use them for example to produce new fields using
+  the operations on fields provided by the TUI.
 
 .. image:: images/xmed-gui-withframe.png
    :align: center
 
-L'utilisation type des fonctions de manipulation de champs suit un
-processus de la forme suivante:
+A typical use of field manipulation functions is:
 
-1. Chargement d'un fichier med dans l'espace de données (dataspace) et
-   exploration du contenu, composé de maillages et de champs définis
-   sur ces maillages et pouvant contenir un ou plusieurs pas de temps.
-2. Sélection (graphique) des champs à manipuler dans l'espace de
-   travail (workspace), avec la possibilité de préciser des
-   restrictions d'utilisation (pas de temps, composantes, groupe de
-   maille).
-3. Création de nouveaux champs par l'exécution d'opérations
-   algébriques (+,-,*,/) entre champs, l'application de fonctions
-   mathématiques standard (pow, sqrt, abs), ou encore l'initialisation
-   "from scratch" sur un maillage support.
-4. Contrôle visuel rapide des champs produits (avec les modules VISU
-   et/ou PARAVIS de SALOME, pilotés automatiquement depuis l'interface
-   utilisateur)
-5. Enregistrement d'une partie des champs produits dans un fichier med
+1. Load a med file in the data space and explore its contents: meshes and
+   fields defined on these meshes, defined for one or several time steps.
+2. Select (using GUI) fields to be manipulated in workspace ; it is possible
+   to introduce restrictions on time steps, components or groups of cells.
+3. Create new fields executing algebraic operations (+,-,*,/) on fields,
+   applying simple mathematical functions (pow, sqrt, abs), or initializing
+   them "from scratch" on a support mesh.
+4. Visually control produced fields, using PARAVIS module in SALOME,
+   automatically controlled from user interface.
+5. Save (parts of) produced fields to a med file.
 
 
-Tour rapide des fonctions du module MED
-=======================================
+Quick tour on functions available in MED module
+===============================================
 
-Cette section présente des exemples d'utilisation du module XMED sous
-la forme de "storyboard", et illustre au passage les fonctions mises à
-disposition par le module.
+This section presents some use examples of MED module like a "storyboard",
+illustrating the functions proposed by the module.
 
-.. warning:: Cette section est en travaux. Tant que cet avis n'aura
-   pas disparu, veuillez en considérer le plan et le contenu encore
-   incomplets, temporaires et sujets à caution.
+.. warning:: This section is under construction. Please consider that its
+             contents and organization are still incomplete and may change
+             until this warning is removed.
 
-Exemple 1: Explorer des sources de données
-------------------------------------------
+Example 1: Explore data sources
+-------------------------------
 
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
 
-   * ajouter une source de données
-   * fonctions "Extends field series", "Visualize"
+   * add a data source
+   * "Extends field series" and "Visualize" functions
 
 .. |ICO_DATASOURCE_ADD| image:: images/ico_datasource_add.png
                         :height: 16px
@@ -101,34 +91,30 @@ Exemple 1: Explorer des sources de données
 .. |ICO_DATASOURCE_VIEW| image:: images/ico_datasource_view.png
                          :height: 16px
 
-Au démarrage, le module de manipulation de champs, identifié par
-l'icône |ICO_XMED|, présente une interface vierge:
+At startup the field manipulation module, identified by icon |ICO_XMED|, shows
+an empty interface:
 
 .. image:: images/xmed-gui-start.png
    :align: center
    :width: 800px
 
-La première étape consiste à ajouter une ou plusieurs source de
-données med dans le "dataspace". Pour cela, on clique sur l'icône "Add
-datasource" |ICO_DATASOURCE_ADD| qui propose de sélectionner un
-fichier med:
+The first step consists in adding one or several med data sources in
+"dataspace". For this, user clicks on icon "Add datasource"
+|ICO_DATASOURCE_ADD| to select a med file:
 
 .. image:: images/xmed-gui-datasource-selectfile.png
    :align: center
    :width: 800px
 
-L'opération ajoute une nouvelle entrée (datasource) dans l'espace de
-données (dataspace). Le contenu peut être exploré en parcourant
-l'arborescence. La figure ci-dessous (image de gauche) montre le
-résultat du chargement du fichier ``timeseries.med`` contenant un
-maillage de nom ``Grid_80x80`` sur lequel est défini un champ au noeud
-de nom ``Pulse``. Par défaut, la composition du champs (en terme de
-pas de temps et de composantes) n'est pas affichée pour éviter
-l'encombrement visuel de l'arbre. On doit faire la demande explicite
-au moyen de la commande "Expand field timeseries"
-|ICO_DATASOURCE_EXPAND| disponible dans le menu contextuel associé aux
-champs. Le résultat est affiché sur l'image centrale. La liste des
-itérations du champ ``Pulse`` peut être consultée.
+This operation adds a new entry (datasource) in data space. The contents can
+be explored using the data tree. The figure below (left image) shows the
+result of loading the file ``timeseries.med`` containing a mesh named
+``Grid_80x80`` on which a field on nodes named ``Pulse`` is defined. By
+default, the field composition (in terms of time steps and components) is not
+displayed to avoid visual congestion of data tree. User must explicitly ask
+for visualization using the command "Expand field timeseries"
+|ICO_DATASOURCE_EXPAND| available in the field contextual menu. The result is
+displayed on center image. The list of field ``Pulse`` iterations can be advised.
 
 .. |IMG_DATASOURCE_EXPLORE| image:: images/xmed-gui-datasource-explore-zoom.png
                             :height: 340px
@@ -141,537 +127,459 @@ itérations du champ ``Pulse`` peut être consultée.
 | |IMG_DATASOURCE_EXPLORE| | |IMG_DATASOURCE_MENUCON| | |IMG_DATASOURCE_EXPANDF| |
 +--------------------------+--------------------------+--------------------------+
 
-.. note:: En toute rigueur, le concept de *champ* dans le modèle MED
-   désigne une itération donnée. Un ensemble d'itérations est désigné
-   par le terme *série temporelle de champs*. Par abus de langage, et
-   s'il n'y a pas ambiguité, on utilisera le nom du champ pour
-   désigner à la fois le champs proprement dit ou la série temporelle
-   à laquelle il appartient.
+.. note:: Strictly speaking,  the *field* concept in MED model corresponds to
+          a given iteration. A set of iterations is identified by the term
+          *field time series*. If there is no ambiguity, the field name will
+          refer to both the field itself or the time series it belongs to.
 
-Enfin, il est possible au niveau du dataspace de visualiser la forme
-générale du champ au moyen d'une carte scalaire affichée dans le
-viewer de SALOME. Pour cela, on sélectionne le pas de temps à
-visualiser et on utilise la commande "Visualize" |ICO_DATASOURCE_VIEW|
-disponible dans le menu contextuel associé:
+Finally, it is possible from dataspace to visualize the field general shape
+using a scalar map displayed in SALOME viewer. For this, user selects the time step to
+display then uses the command "Visualize" |ICO_DATASOURCE_VIEW| available in
+the associated contextual menu:
 
 .. image:: images/xmed-gui-datasource-visualize-zoom.png
    :align: center
    :width: 800px
 
-.. note:: Cette représentation graphique a pour objectif le contrôle
-   visuel rapide. Aussi, les fonctions du module VISU sont employées
-   par défaut, mais il est possible de faire l'affichage des cartes
-   scalaires au moyen du module PARAVIS (choix de préférence non
-   implémenté pour le moment, mais techniquement réalisable).
+.. note:: This graphical representation aims at providing a quick visual
+          control. Scalar maps are displayed using the PARAVIS module.
 
-Exemple 2: Rassembler des champs issus de différentes sources
--------------------------------------------------------------
+Example 2: Combine fields from different sources
+------------------------------------------------
 
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
 
-   * fonction "Use in workspace"
-   * fonction "Save"
+   * function "Use in workspace"
+   * function "Save"
 
 .. |ICO_DATASOURCE_USE| image:: images/ico_datasource_use.png
                         :height: 16px
 .. |ICO_WORKSPACE_SAVE| image:: images/ico_workspace_save.png
                         :height: 16px
 
-L'objectif est de récupérer des données issues de différents fichiers
-med, puis de les rassembler dans un même fichier en sortie.
+The objective is to access data contained in several med files, then to
+combine them in the same output file.
 
-On commence par ajouter les sources de données med dans l'espace de
-données (dataspace). Dans l'exemple ci-dessous, l'espace de données
-contient deux sources de nom ``parametric_01.med`` et
-``smallmesh_varfiled.med``. La première source contient le maillage
-``Grid_80x80_01`` sur lequel est défini le champ ``StiffExp_01``. La
-deuxième source contient le maillage ``My2DMesh`` sur lequel sont
-définis deux champs de noms respectifs ``testfield1`` et
-``testfield2``:
+User starts by adding med data sources in dataspace. In the example below,
+dataspace contains two sources names ``parametric_01.med`` and
+``smallmesh_varfiled.med``. The first one contains the mesh ``Grid_80x80_01``
+on which the field ``StiffExp_01`` is defined. The second source contains the
+mesh ``My2DMesh`` on which the two fields ``testfield1`` are ``testfield2``
+are defined:
 
 .. image:: images/xmed-userguide-example2-datasource.png
    :align: center
    :width: 800px
 
-Pour l'exemple, on souhaite rassembler les champs ``StiffExp_01`` et
-``testfield2`` dans un fichier de nom ``result.med``. La procédure
-consiste à importer les deux champs dans l'espace de travail
-(workspace), puis à sauvegarder l'espace de travail. Pour cela, on
-sélectionne les champs et on utilise la commande "Use in workspace"
-|ICO_DATASOURCE_USE| disponible dans le menu contextuel. Les deux
-champs sélectionnés apparaissent dans l'arborescence de l'espace de
-travail:
+In this example, ``StiffExp_01`` and ``testfield2`` are combined then saved to
+``result.med`` file. The procedure consists in importing the two fields in
+workspace, then to save the workspace. For this user selects the fields and
+uses the command "Use in workspace" |ICO_DATASOURCE_USE| available in the
+contextual menu. Both selected fields appear in the workspace tree:
 
 .. image:: images/xmed-userguide-example2-workspace.png
    :align: center
    :width: 800px
 
-La sauvegarde de l'espace de travail est faite au moyen de la commande
-"Save workspace" |ICO_WORKSPACE_SAVE| disponible dans la barre
-d'outils du module. Une fenêtre de dialogue invite l'utilisateur à
-spécifier le nom du fichier de sauvegarde:
+Workspace is saved using the command "Save workspace" |ICO_WORKSPACE_SAVE|
+available in the module toolbar. A dialog window lets user set the save
+file name:
 
 .. image:: images/xmed-userguide-example2-workspace-save.png
    :align: center
    :width: 800px
 
-Ce fichier ``result.med`` peut ensuite être rechargé dans le module
-XMED (ou les modules VISU ou PARAVIS) pour vérifier la présence des
-champs sauvegardés.
+The file ``result.med`` can then be reloaded in MED module (or PARAVIS module)
+to check the presence of saved fields.
 
 .. BUG: plantage à l'utilsation dans XMED d'un fichier rechargé
 .. (invalid mesh on field)
 
 .. _xmed.userguide.exemple3:
 
-Exemple 3: Appliquer une opération mathématique sur des champs
---------------------------------------------------------------
+Example 3: Apply a formula on fields
+------------------------------------
 
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functions:
 
-   * exécution d'opérations mathématiques dans la console TUI
-   * fonction "put" pour référencer un champ de travail dans la liste
-     des champs persistant.
-   * fonction "Visualize" depuis le TUI.
+   * execute mathematical operations in TUI console
+   * function "put" to refer to a work field in the list of persisting fields.
+   * function "Visualize" from TUI.
 
-L'usage le plus courant du module de manipulation de champs est
-d'exécuter des opérations mathématiques dont les opérandes sont des
-champs ou des composantes de ces champs.
+The most common usage of field manipulation module is to execute mathematical
+operations on fields or on their components.
 
-On se place dans une situation où les sources de données sont définies
-dans le "dataspace" (dans l'exemple ci-après, une série temporelle de
-nom ``Pulse``, contenant 10 pas de temps, définis sur un maillage de
-nom ``Grid_80x80``, le tout issu du datasource ``timeseries.med``).
+Assume data sources are already defined in dataspace (in the following example
+a temporal series named ``Pulse`` contains 10 time steps defined on a mesh
+named ``Grid_80x80``, all read from ``timeseries.med`` data source).
 
-Comme vu précedemment, pour manoeuvrer un champ dans l'espace de
-travail, on sélectionne ce champ, puis on exécute la commande "Use in
-workspace" |ICO_DATASOURCE_USE| du menu contextuel. Dans le cas
-présent, un seul champ est sélectionné (contre deux dans l'exemple
-précédent) et la commande ouvre alors une fenêtre de dialogue qui
-permet de préciser les données sur lesquelles on souhaite
-effectivement travailler et comment on veut les manoeuvrer:
+As previously seen, a field can be manipulated in workspace after selecting
+the field and applying the command "Use in
+workspace" |ICO_DATASOURCE_USE| from contextual menu. Here only one file is
+selected (two in the previous example) and the command then opens a dialog
+window to select data to work on and the way they will be manipulated:
 
 .. image:: images/xmed-gui-datasource-useinworkspace-alias.png
    :align: center
    :width: 800px
 
-.. note:: En l'état actuel du développement, l'interface propose
-   uniquement de définir le nom de la variable sous laquelle doit être
-   manoeuvré le champ dans la console de travail (TUI). Dans une
-   version ultérieure, il est prévue de pouvoir préciser la ou les
-   composante du champs à utiliser et un groupe de maille pour définir
-   une restriction géométrique. Inversement, il sera également
-   possible de choisir une série temporelle complète pour faire des
-   opérations globales sur l'ensemble des pas de temps.
-
-Aprés validation, le champ est placé dans l'arborescence du
-"workspace" et une variable de nom ``<alias>`` est créée
-automatiquement dans la console de travail pour désigner le
-champ. Dans cet exemple, ``<alias>`` vaut ``f3``, positionné ainsi par
-l'utilisateur pour rappeler que la variable correspond au pas de temps
-n°3:
+.. note:: In the current state of development, the interface only propose to
+          define the name of a variable representing the field in TUI. In
+          a next version, user will have the possibility to specify the field
+          component(s) to be used and a group of cells to introduce
+          a geometrical restriction. Conversely it will be possible to select
+          a complete time series to apply global operations on all time steps.
+
+After validation, the field if put in workspace tree and a variable
+``<alias>`` is automatically created in the TUI to designate the field. In
+this example, ``<alias>`` is ``f3``, as set by user to recall that variable
+corresponds to the third time step:
 
 .. image:: images/xmed-gui-workspace.png
    :align: center
    :width: 800px
 
-La manipulation peut commencer. Dans l'exemple ci-dessous, on crée le
-champ ``r`` comme le résultat d'une transformation afine du champ
-``f3`` (multiplication du champ par le facteur 2.7 auquel on ajoute
-l'offset 5.2)::
+Field manipulation can start. In the example below, use creates the field``r``
+as the result of an affine transformation of field ``f3`` (multiplication of
+field by a scale factor 2.7 then addition of offset 5.2)::
 
  >>> r=2.7*f3+5.2
 
-On peut poursuivre la manipulation du champs avec une variété
-d'opérations qui sont détaillées dans les spécifications du module
+Other operations can be applied, as detailed in module specifications
 (cf. :ref:`Spécification des opérations<xmed-specifications>`):
 
- >>> r=f3/1000     # les valeurs de r sont celles du champ f3 réduites d'un facteur 1000
- >>> r=1/f3        # les valeurs de r sont les inverses des valeurs de f3
- >>> r=f3*f3       # les valeurs de r sont celles du champ f3 élevées au carré
- >>> r=pow(f3,2)   # même résultat
- >>> r=abs(f3)     # valeur absolue du champ f3
+ >>> r=f3/1000     # the values of r are the ones of f3 reduced by a factor 1000
+ >>> r=1/f3        # the values of r are the inverted values of f3
+ >>> r=f3*f3       # the values of r are the squared values of f3
+ >>> r=pow(f3,2)   # same result
+ >>> r=abs(f3)     # absolute value of field f3
  >>> ...
 
-Les opérations peuvent utiliser plusieurs opérandes de type champs. Si
-``f4`` désigne le pas de temps n°4 du champ ``Pulse``, alors on peut
-calculer toute combinaison algébrique des deux champs::
+The two operands can be fields. If ``f4`` is the fourth time step of field
+``Pulse``, then algebraic combinations of fields can be computed::
 
  >>> r=f3+f4
  >>> r=f3-f4
  >>> r=f3/f4
  >>> r=f3*f4
 
-Avec au besoin l'utilisation de variables scalaires::
+Scalar variables can be used if needed::
 
  >>> r=4*f3-f4/1000
  >>> ...
 
-Dans ces exemples, la variable ``r`` désigne un champ de travail qui
-contient le résultat de l'opération. Par défaut, ce champ de travail
-n'est pas référencé dans l'arborescence du workspace. Si on souhaite
-tout de même le référencer, par exemple pour qu'il soit pris en compte
-dans la sauvegarde, alors on tape la commande::
+In theses examples, the variable ``r`` corresponds to a work field containing
+the operation result. By default the field is nor referenced in workspace
+tree. If user wants to add it, for example to make it considered when saving,
+then the following command is used::
 
  >>> put(r)
 
-La fonction ``put`` a pour but de marquer le champ en argument comme
-persistent, puis de le ranger dans l'arborescence du "workspace" afin
-qu'il soit visible et sélectionnable. En effet, parmi tous les champs
-qui pourront être créés dans la console pendant la session de travail,
-tous n'ont pas besoin d'être sauvegardés. Certains sont même des
-variables temporaires qui servent à la construction des champs
-résultats finaux. C'est pourquoi, seuls les champs rangés dans
-l'arborescence du workspace sont enregistrés lors de la demande de
-sauvegarde du workspace.
-
-Les variables définies dans la console ont d'autres utilités. Tout
-d'abord, elles permettent d'imprimer les informations concernant le
-champ manoeuvré. Pour cela, on tape simplement le nom de la variable
-puis retour::
+The function ``put`` aims at tagging the field as persisting, the to store it
+in the workspace tree to make it visible and selectable. Among all fields that
+could be created in console during the work session, all do not need to be
+saved. Some may only be temporary variables used in the construction of final
+fields. That is why only fields in workspace tree are saved when saving the
+workspace.
+
+Variables defined in console have other uses. First they allow for printing
+information relative to the manipulated field. For this one enters the
+variable name then validates::
 
  >>> f3
- field name (id)        = Pulse (3)
- mesh name (id)         = Grid_80x80 (0)
- discretization         = ON_NODES
- (iter, order)          = (3,-1)
- data source            = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
-
-Elle peut également être utilisée comme argument des commandes de
-gestion disponibles dans l'interface textuelle (dont la liste
-détaillée est décrite à la section :ref:`Documentation de l'interface
-textuelle<xmed.userguide.tui>`). Par exemple, la fonction ``view``
-permet d'afficher la carte scalaire du champ dans le viewer::
+ field name (id)         = Pulse (3)
+ mesh name (id)          = Grid_80x80 (0)
+ discretization          = ON_NODES
+ (iter, order)           = (3,-1)
+ data source             = file:///home/gboulant/development/projets/salome/MEDOP/XMED/xmed/resources/datafiles/timeseries.med
+
+Second, variables can be used as command arguments (the list of commands
+available in TUI is described in section :ref:`Documentation of textual
+interface<xmed.userguide.tui>`). For example the function ``view`` displays
+the field scalar map in the viewer::
 
  >>> view(f3)
 
-Donne:
+Results in:
 
 .. image:: images/xmed-gui-workspace-view.png
    :align: center
    :width: 800px
 
-.. note:: On remarquera ici qu'il est facile de comparer deux pas de
-   temps d'un champ, par exemple en calculant la différence ``f3-f4``,
-   puis en affichant un aperçu de la carte scalaire résultat au moyen
-   de la fonction ``view``::
+.. note:: It is easy to compare two time steps of a field, computing the
+          difference ``f3-f4``, then producing a scalar map preview using the
+          function ``view``::
 
     >>> view(f3-f4)
 
-On peut enfin tout simplement afficher les données du champs par la
-commande ``print``::
+Finally the field data can be displayed using the command``print``::
 
  >>> print f3
  Data content :
- Tuple #0 : -0.6 
- Tuple #1 : -0.1 
- Tuple #2 : 0.4 
- Tuple #3 : -0.1 
- Tuple #4 : 0.4 
+ Tuple #0 : -0.6
+ Tuple #1 : -0.1
+ Tuple #2 : 0.4
+ Tuple #3 : -0.1
+ Tuple #4 : 0.4
  ...
- Tuple #6556 : 3.5 
- Tuple #6557 : 3.3 
- Tuple #6558 : 1.5 
- Tuple #6559 : 0.3 
+ Tuple #6556 : 3.5
+ Tuple #6557 : 3.3
+ Tuple #6558 : 1.5
+ Tuple #6559 : 0.3
  Tuple #6560 : 0.2
 
-Il est important de noter que les opérations entre champs ne peuvent
-être faites qu'entre champs définis sur le même maillage. Il s'agit là
-d'une spécification du modèle MED qui interdit d'envisager les
-opérations entre champs définis sur des maillages géométriquement
-différents. Techniquement, cela se traduit par l'obligation pour les
-objets informatique *champs* de partager le même objet informatique
-*maillage*.
-
-Dans l'hypothèse où on souhaite utiliser des champs définis sur des
-maillages différents, par exemple pour manoeuvrer les valeurs des
-champs à l'interface de deux maillages partageant une zone géométrique
-2D, il faut d'abord ramener tous les champs sur le même maillage de
-surface par une opération de projection.
-
-.. note:: Même si ceci est techniquement possible avec la bibliothèque
-   MEDCoupling, cet type d'opération de projection n'est pas encore
-   disponible dans le module de manipulation de champs (prévu en
-   2012).
-
-Un autre besoin plus classique est l'utilisation de champs définis sur
-des maillages géométriquement identiques, mais techniquement
-différents, par exemple lorsqu'ils sont chargés de fichiers med
-différents. Pour traiter ce cas de figure, la bibliothèque MEDCoupling
-prévoit une fonction de "Changement du maillage support", dont
-l'utilisation au niveau du module de manipulation de champs est
-illustrée dans :ref:`l'exemple 4<xmed.userguide.exemple4>` ci-après.
+It is important to note that operations between fields can only be applied if
+fields are defined on the same mesh. It corresponds to a specification of MED
+model that forbids operations between fields defined on meshes geometrically
+different. Technically it means that the conceptual objects *fields* must share
+the same conceptual object *mesh*.
+
+If user do want to use fields defined on different meshes, for example to
+manipulate the field values at the interface of two meshes sharing a 2D
+geometrical area, it is necessary first to make all fields be defined on the
+same surface mesh using a projection operation.
+
+.. note:: Such projection operations are available in the MEDCoupling library.
+
+Another classical need is using fields defined on meshes geometrically
+identical, but technically different for example when they are loaded from
+different med files. For such a case, the MEDCoupling library proposes
+a function "Change support mesh" ; its use in field manipulation module is
+illustrated in :ref:`example 4<xmed.userguide.exemple4>` described hereafter.
 
 .. _xmed.userguide.exemple4:
 
-Exemple 4: Comparer des champs issues de différentes sources
-------------------------------------------------------------
+Example 4: Compare fields derived from different sources
+--------------------------------------------------------
 
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following function:
 
-   * Changement du maillage support "change underlying mesh"
+   * Change the underlying (support) mesh
 
-On se place ici dans le cas de figure où des champs ont été produits
-sur le même maillage, au sens géométrique, mais enregistrés dans des
-fichiers med différents. C'est le cas par exemple d'une étude
-paramétrique où plusieurs calculs sont effectués avec des variantes
-sur certains paramètres du modèle simulé, chaque calcul produisant un
-fichier med.
+Assume here that fields have been defined on same mesh, geometrically
+speaking, but saved in different med files. This occurs for example for
+a parametric study in which several computations are achieved with variants on
+some parameters of the simulated model, each computation producing a med file.
 
-Soit ``parametric_01.med`` et ``parametric_02.med`` deux fichiers med
-contenant les champs que l'on souhaite comparer, par exemple en
-calculant la différence des valeurs et en visualisant le résultat.
+Let ``parametric_01.med`` and ``parametric_02.med`` be two med files
+containing the fields to compare, for example computing the difference of
+their values and visualizing the result.
 
-Aprés le chargement des sources de données dans le module XMED,
-l'utilisateur se trouve en présence de deux maillages, au sens
-technique du terme cette fois-ci, c'est-à-dire que les champs sont
-associées à des objets informatiques maillage différents, bien que
-géométriquement identiques.
+After loading data sources user sees two meshes, this time from the technical
+point of view, that is to say fields are associated to different conceptual
+mesh objects, while geometrically identical.
 
-Or, les fonctions de manipulation de champs ne permettent pas les
-opérations sur des champs dont les maillages supports sont différents
-(voir la remarque à la fin de :ref:`l'exemple
+However field manipulation functions do not allow operations on fields lying
+on different support meshes (see remark at the end of  :ref:`example
 3<xmed.userguide.exemple3>`).
 
-Pour résoudre ce cas de figure, le module de manipulation de champs
-met à disposition la fonction "Change underlying mesh" qui permet de
-remplacer le maillage support d'un champ par un autre à partir du
-moment où les deux maillages sont géométriquement identiques,
-c'est-à-dire que les noeuds ont les mêmes coordonnées spatiales.
+To circumvent this issue, the module offers the function "Change underlying
+mesh" to replace a field mesh support by another, provided that the two meshes
+are geometrically identical, that is to say nodes have the same spatial
+coordinates.
 
 .. |ICO_DATASOURCE_CHG| image:: images/ico_datasource_changeUnderlyingMesh.png
                         :height: 16px
 
-Dans l'exemple proposé, l'utilisateur sélectionne le premier pas de
-temps du champ ``StiffExp_01`` du "datasource" ``parametric_01.med``,
-puis l'importe dans l'espace de travail au moyen de la commande "Use
-in workspace" |ICO_DATASOURCE_USE|. Il sélectionne ensuite le premier
-pas de temps du champs ``StiffExp_02`` du "datasource"
-``parametric_02.med``, mais l'importe dans l'espace de travail au
-moyen de la commande "Change underlying mesh" |ICO_DATASOURCE_CHG|. La
-fenêtre de dialogue ci-dessous s'affiche et invite l'utilisateur à
-choisir le nouveau maillage support par sélection dans l'arborescence
-du "dataspace":
+In the proposed example, user selects the first time step of field
+``StiffExp_01`` in data source ``parametric_01.med``, and imports it in
+workspace using the command "Use in workspace" |ICO_DATASOURCE_USE|. User then
+selects the first time step of field ``StiffExp_02`` in data source
+``parametric_02.med``, but imports it in workspace using the command "Change
+underlying mesh" |ICO_DATASOURCE_CHG|. The following dialog window appears to
+let user select the new support mesh in dataspace tree:
 
 .. image:: images/xmed-gui-datasource-changeUnderlyingMesh.png
    :align: center
 
-Dans cet exemple, on sélectionne le maillage ``Grid_80x80_01`` support
-du champ ``StiffExp_01``, avec lequel on souhaite faire la
-comparaison. Après validation, l'arborescence du workspace contient le
-champ ``StiffExp_02`` défini sur le maillage ``Grid_80x80_01``:
+In this example, the support mesh ``Grid_80x80_01`` of field ``StiffExp_01``
+to compare with is selected. After validation the workspace tree contains the
+field ``StiffExp_02`` defined on mesh ``Grid_80x80_01``:
 
 .. image:: images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png
    :align: center
 
-.. note:: La fonction "Change underlying mesh" ne modifie pas le champ
-  sélectionné dans le "dataspace" (principe de base de fonctionnement
-  du dataspace), mais crée une copie du champ dans l'espace de travail
-  pour ensuite remplacer le maillage support. D'où le nom par défaut
-  pour le champ ``dup(<nom du champ sélectionné>)`` (dup pour
-  "duplicate").
+.. note:: The function "Change underlying mesh" does not modify the field
+          selected in dataspace (basic running principle of dataspace), but
+          creates a field copy in workspace to then change support mesh. This
+          explains the default name for field ``dup(<name of selected
+          field>)`` (dup stands for "duplicate").
 
-Il reste à associer une variable à ce champ pour le manipuler dans la
-console. Ceci peut être fait au moyen de la commande "Use in console",
-disponible dans le menu contextuel du workspace.
+All we have to do now is to associate a variable to this field, in order to
+manipulate it in TUI. This can be done using the command "Use in console"
+available in workspace contextual menu.
 
-En définitif, si ``f1`` désigne le champ issu du datasource
-``parametric_01.med`` et ``f2`` le champ issu du datasource
-``parametric_02.med`` par la procédure décrite ci-dessus, alors la
-comparaison des deux grandeurs peut être faite comme pour le cas de
-:ref:`l'exemple 3<xmed.userguide.exemple3>`::
+Finally, if ``f1`` is a field from datasource ``parametric_01.med`` and ``f2``
+is a field from datasource
+``parametric_02.med`` according to the above procedure, then comparison values
+can be achieved as explained in :ref:`example 3<xmed.userguide.exemple3>`::
 
  >>> r=f1-f2
  >>> view(r)
 
-.. note:: En remarque générale sur cet exemple, il convient de noter
-   les points suivants:
-
-   * l'égalité géométrique de deux maillages est établie à une marge
-     d'erreur prés qu'il est possible de définir techniquement, mais
-     qui n'est pas ajustable au niveau de l'interface du module de
-     manipulation de champs. Elle est fixée à une valeur standard qui
-     permet de traiter la plupart des cas utilisateur. On verra à
-     l'usage s'il est nécessaire de remonter ce paramètre au niveau de
-     l'interface.
-   * L'utilisateur doit faire la démande explicite de changer le
-     maillage support d'un champ, en prévision de la comparaison de
-     champs issus de datasource différentes. Il s'agit là d'un choix
-     fonctionnel délibéré pour que l'utilisateur garde trace des
-     modifications faites sur les données (pas de modification
-     automatiques à l'insu de l'utilisateur, même sous prétexte
-     d'amélioration de l'ergonomie).
-
-
-Exemple 5: Créer un champ sur un domaine spatial
-------------------------------------------------
+.. note:: As a general remark concerning this example, one may note:
+
+   * the geometrical equality of two meshes is constrained to a numerical
+     error that can be technically set, but not through the module interface.
+     This tolerance is empirically set to a standard value regarding to
+     success of most of the use cases. The usefulness of setting this value in
+     the interface could be later investigated.
+
+   * User must explicitly ask for changing a field support mesh, in order to
+     compare fields coming from different data sources. This choice has been
+     made to keep trace of modifications made on data (no modification is made
+     without user knowing, even to improve ergonomics).
+
 
-.. note:: Cet exemple présente les fonctions:
+Example 5: Create a field on a spatial domain
+---------------------------------------------
 
-   * initialisation par une fonction de la position spatiale
-   * initialisation sur un groupe de maille
+.. note:: This example illustrates the following functions:
 
-Le domaine géométrique de définition du champs à créer est spécifié
-ici par la donnée d'un groupe de mailles. Ce cas d'usage est
-typiquement prévu pour produire les conditions de chargement initial
-d'une structure, par exemple en définissant un champ sur une surface
-de la géométrie, identifiée par un nom de groupe de mailles.
+   * initialize with function of spatial position
+   * initialize on a group of cells
 
-.. warning:: DEVELOPPEMENT EN COURS
+The geometrical domain on which the field to create is defined is here given
+by cell group data. This use case is provided for producing initial load
+conditions of a structure, for example defining a field on a geometry surface
+identified by a group of cells.
 
-Exemple 6: Extraire une partie d'un champ
------------------------------------------
+.. warning:: DEVELOPMENT IN PROGRESS
 
-.. note:: Cet exemple présente les fonctions:
+Example 6: Extract a field part
+-------------------------------
 
-   * extraire une composante (ou un sous-ensemble des composantes)
-   * extraire un domaine géométrique (valeurs sur un groupe de maille)
-   * extraire un ou plusieurs pas de temps.
+.. note:: This example illustrates the following functions:
 
-.. warning:: DEVELOPPEMENT EN COURS
+   * extract a component (or a subset of components)
+   * extract a geometrical domain (values on a group of cells)
+   * extract one or several time steps
 
-   On doit illustrer ici les fonctions de restriction, qui
-   permettraient de récupérer certaines composantes uniquement. Le
-   principe est qu'on crée un nouveau champ qui est une restriction du
-   champ argument à une liste de composantes à spécifier (utiliser la
-   fonction __call__ des fieldproxy).
+.. warning:: DEVELOPMENT IN PROGRESS
 
-Pour l'extraction des pas de temps, on peut se ramener au cas de
-l'exemple 2 avec une seule source de donnée.
+   Here the restriction functions that allow to get some components only, have
+   to be illustrated. The principle is creating a new field that is
+   a restriction of input field to a list of given components (use the
+   function __call__ of fieldproxy).
 
-Exemple 7: Créer un champ à partir d'une image to[mp]ographique
----------------------------------------------------------------
+For time step extraction, we can reduce to the case of example 2 with a single
+data source.
 
-.. note:: Cet exemple présente les fonctions:
+Example 7: Create a field from a to[mp]ographic image
+-----------------------------------------------------
 
-   * Création d'un champ sans datasource (ni maillage, ni champs), à
-     partir d'un fichier image
+.. note:: This example illustrates the following function:
 
-En tomographie ou en topographie, les appareils de mesure produisent
-des images qui représentent une grandeur physique en niveaux de gris
-sur un plan de coupe donné. L'image ci-dessous représente par exemple
-une vue interne du corps humain faite par IRM:
+   * Create a field without data source (neither mesh nor field), from an
+     image file
+
+In tomography or topography studies, measurement devices produce images that
+represent a physical quantity using gray levels on a given cutting plane. The
+following image represents for example a internal view of human body obtained
+by MRI:
 
 .. image:: images/xmed-irm.png
    :align: center
    :width: 600px
 
-Cette image est un ensemble de pixels organisés sur une grille
-cartesienne. Elle peut donc être modélisée sous la forme d'un champ
-scalaire dont les valeurs sont définies aux cellules d'un maillage
-réglés de même taille que l'image (en nombre de pixels):
+This image is a subset of pixels organized on a Cartesian grid. It can thus be
+represented as a scalar field whose values are defined on cells of a mesh
+having the same dimension as the image (number of pixels):
 
 .. image:: images/xmed-irm-field.png
    :align: center
    :width: 600px
 
-Le module de manipulation de champ fournit un utilitaire appelé
-``image2med.py`` qui permet d'appliquer ce principe à la conversion
-d'un fichier image en fichier med contenant la représentation de
-l'image sous forme d'un champ scalaire (seul le niveau de gris est
-conservé)::
+The field manipulation module provides a tool named ``image2med.py`` to
+convert a file image to a med file containing the image representation as
+a scalar field (only the gray level is kept)::
 
   $ <xmed_root_dir>/bin/salome/xmed/image2med.py -i myimage.png -m myfield.med
 
 .. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png
                         :height: 16px
 
-Cette opération de conversion peut être faite automatiquement dans
-l'interface graphique du module au moyen de la commande "Add Image
-Source" |ICO_IMAGESOURCE| disponible dans la barre d'outils. Cette
-commande ouvre la fenêtre suivante pour inviter l'utilisateur à
-choisir un fichier image:
+This conversion operation can be automatically achieved using the command "Add
+Image Source" |ICO_IMAGESOURCE| available in GUI toolbar. This command opens
+the following window to let user select a file image:
 
 .. image:: images/medop_image2med_dialog.png
    :align: center
 
-Le nom du fichier med résultat est proposé par défaut (changement de
-l'extention en ``*.med``) mais il peut être modifié. Enfin, on peut
-demander le chargement automatique du fichier med produit pour ajout
-dans l'espace de donnée. Les champs peuvent alors être manipulés comme
-dans les cas d'utilisation standard.
+The name of result med file is set by default (changing file extension to
+``*.med``) but can be modified. Finally user can ask for automatic load of
+this med file in data space. Fields can then be manipulated like presented in
+the standard use cases.
 
-Par exemple, l'image ci-dessous affiche le résultat de la différence
-entre deux images, ajoutée à l'image de référence: si i1 et i2
-désignent les champs créés à partir des deux images, on représente ``r
-= i1 + 5*(i2-i1)`` où le facteur 5 est arbitraire et sert à amplifier
-la zone d'intérêt (en haut de l'oeil gauche):
+For example, the image below depicts the result of the difference between two
+images, added to the reference image: if i1 and i2 are the fields created from
+these two images, then ``r = i1 + 5*(i2-i1)`` with 5 an arbitrary factor to
+amplify the region of interest (above the left eye):
 
 .. image:: images/xmed-irm-diff.png
    :align: center
    :width: 600px
 
-L'exemple ci-dessous est le résultat du chargement d'une image
-tomographique issue du projet MAP (Charles Toulemonde,
-EDF/R&D/MMC). L'image tomographique:
+The example below is the result of loading a tomographic image courtesy of MAP
+project (Charles Toulemonde, EDF/R&D/MMC). The tomographic image:
 
 .. image:: images/champ_altitude_MAP.png
    :align: center
    :width: 600px
 
-Le résultat du chargement:
+The result of loading:
 
 .. image:: images/medop_image2med_tomographie.png
    :align: center
    :width: 800px
 
-Exemple 8: Continuer l'analyse dans PARAVIS
--------------------------------------------
+Example 8: Continue analysis in PARAVIS
+---------------------------------------
 
-.. note:: Cet exemple présente les fonctions:
+.. note:: This example illustrates the following functio:
 
-   * Export de champs vers le module PARAVIS.
+   * Export fields to PARAVIS module
 
-Les possibilités de représentation graphique des champs fournies par
-le module MED ont pour seul objectif le contrôle visuel rapide. Par
-défaut, le viewer de VISU est employé.
+The solutions for field representation in MED module aims at proposing a quick
+visual control.
 
-Pour une analyse plus détaillées des champs, il est nécessaire de
-poursuivre le travail dans PARAVIS. Le module de manipulation de
-champs offre une fonction qui simplifie ce passage, en faisant le
-chargement automatique dans PARAVIS et en proposant une visualisation
-par défaut (carte de champs scalaire).
+For a detailed analysis of fields, user shall switch to PARAVIS. The field
+manipulation module has a function to facilitate this transition, with
+automatic load in PARAVIS and proposing a default visualization (scalar map).
 
-Pour cela, il faut sélectionner dans l'espace de travail les champs à
-exporter, puis déclencher la fonction d'export depuis le menu
-contextuel associé:
+For this user selects in workspace the fields to export, then call the export
+function from contextual menu:
 
 .. image:: images/medop_exportparavis.png
    :align: center
 
-Les champs sélectionnés sont regroupés dans une entrée MED du
-navigateur PARAVIS, et le premier champ est affiché sous forme de
-carte de champ:
+Selected fields are grouped in a single MED entry in PARAVIS, and the first
+field is depicted as a scalar map:
 
 .. image:: images/medop_exportparavis_result.png
    :align: center
    :width: 800px
 
-.. note:: La fonction d'export est une fonction de confort. La même
-   opération peut être faite manuellement en procédant d'abord à
-   l'enregistrement des champs sous forme de fichier MED, puis en
-   chargeant le fichier généré dans le module PARAVIS pour
-   visualisation.
+.. note:: The export function is a convenience function. The same operation
+          can be manually achieved, first saving fields to a med file then
+          loading the created file in PARAVIS module for visualization.
 
 .. _xmed.userguide.tui:
 
-Utilisation de l'interface textuelle du module MED (TUI)
-========================================================
+Using the textual interface (TUI)
+=================================
 
-Toutes les opérations menées au moyen de l'interface graphique peuvent
-être réalisées (avec plus ou moins de facilité) avec l'interface
-textuelle. Le module de manipulation de champs peut même être utilisé
-exclusivement en mode texte. Pour cela, on lance la commande::
+All operations driven through GUI can be done (more or less easily) using TUI.
+The field manipulation module can even be used exclusively in textual mode.
+For this run the command::
 
  $ <path/to/appli>/medop.sh
 
-Cette commande ouvre une console de commandes ``medop>``. Un fichier
-med peut être chargé et travaillé, par exemple pour créer des champs à
-partir des données du fichier.
+This command opens a command console ``medop>``. A med file can be loaded and
+manipulated, for example to create fields from file data.
 
-Que l'on soit en mode texte pur ou en mode graphique, un séquence de
-travail type dans la console peut ressembler au jeu d'instructions
-suivantes::
+Whatever textual or graphical mode is used, a typical workflow in console
+looks like the following instructions::
 
  >>> load("/path/to/mydata.med")
  >>> la
@@ -679,7 +587,7 @@ suivantes::
  id=1    name    = testfield2
  >>> f1=get(0)
  >>> f2=get(1)
- >>>   ls
+ >>>    ls
  f1      (id=0, name=testfield1)
  f2      (id=1, name=testfield2)
  >>> r=f1+f2
@@ -695,54 +603,47 @@ suivantes::
  >>> put(r)
  >>> save("result.med")
 
-Les commandes principales sont:
+The main commands are:
 
-* ``load``: charge un fichier med dans la base de données (utile
-  uniquement en mode texte pur)::
+* ``load``: load a med file in data base (useful in pure textual mode)::
 
   >>> load("/path/to/datafile.med")
 
-* ``la``: affiche la liste de tous les champs chargés en base de données ("list all")
-* ``get``: définit un champ dans l'espace de travail à partir de son
-  identifiant (utile plutôt en mode texte pur car l'interface
-  graphique permet de faire cette opération par sélection d'un champ
-  dans le dataspace)::
+* ``la``: show the list of all fields loaded in data base ("list all")
+* ``get``: set a field in workspace from its identifier (useful in pure
+  textual mode ; this operation can be done in GUI selecting a field from data
+  space).::
 
   >>> f=get(fieldId)
 
-* ``ls``: affiche la liste des champs présent dans l'espace de travail ("list")
-* ``put``: met un champ en référence dans l'*espace de gestion*::
+* ``ls``: show the list of fields available in workspace ("list")
+* ``put``: put a reference to a field in *management space*::
 
   >>> put(f)
 
-* ``save``: sauvegarde tous les champs référencés dans l'espace de
-  gestion dans un fichier med::
+* ``save``: save to a med a file all fields referenced in management space::
 
   >>> save("/path/to/resultfile.med")
 
-.. note:: On peut faire à ce stade plusieurs remarques:
-
-   * la commande ``load`` charge uniquement les méta-informations
-     décrivant les maillage et les champs (noms, type de
-     discrétisation, liste des pas de temps). Les maillages et les
-     valeurs physiques des champs sont chargées ultérieurement (et
-     automatiquement) dés lors qu'elles sont requises par une
-     opération. Dans tous les cas, les données med (méta-informations
-     et valeurs) sont physiquement stockées au niveau de l'espace
-     *base de données*.
-   * la commande ``get`` définit en réalité un *manipulateur de champ*
-     dans l'espace de travail, c'est-à-dire une variable qui fait la
-     liaison avec le champ physique hébergé dans la base de
-     données. Les données physiques ne circulent jamais entre les
-     espaces, mais restent centralisées au niveau de la base de
-     données.
-
-Les commandes TUI suivantes nécessitent de travailler dans
-l'environnement graphique:
-
-* ``visu``: afficher une carte de champ pour contrôle visuel rapide
-  (pas de paramettrage possible)
+.. note::
+
+   * the ``load`` command only loads metadata describing meshes and fields
+     (names, discretization types, list of time steps). Meshes and physical
+     quantities on fields are loaded later (and automatically) as soon as an
+     operation needs them. In all cases med data (mete-information and values)
+     are physically stored in *data base* environment.
+   * the ``get`` command defines a *field handler* in workspace, i.e.
+     a variable that links to the physical field hosted in data base. Physical
+     data never transit between environments but remain centralized in data
+     base.
+
+The following TUI commands need to work in graphical environment:
+
+* ``visu``: display a field map for quick visual control (no parametrization
+  is possible)
 
   >>> view(f)
 
 
+
+..  LocalWords:  softwares