From: Cédric Aguerre Date: Wed, 28 Oct 2015 17:34:45 +0000 (+0100) Subject: MERGE stage 2: update doc/dev then remove src/MEDCalc/doc X-Git-Tag: simple_cmake~2^2~17 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=4fca417beab3604d1b54295d67a7bb8312a9f454;p=tools%2Fmedcoupling.git MERGE stage 2: update doc/dev then remove src/MEDCalc/doc --- diff --git a/doc/dev/CMakeLists.txt.BACKUP.5306.txt b/doc/dev/CMakeLists.txt.BACKUP.5306.txt deleted file mode 100644 index d91183151..000000000 --- a/doc/dev/CMakeLists.txt.BACKUP.5306.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Copyright (C) 2012-2015 CEA/DEN, EDF R&D -# -# This library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. -# -# This library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -# -# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com -# - -ADD_SUBDIRECTORY(sphinx) diff --git a/doc/dev/CMakeLists.txt.REMOTE.5306.txt b/doc/dev/CMakeLists.txt.REMOTE.5306.txt deleted file mode 100644 index d91183151..000000000 --- a/doc/dev/CMakeLists.txt.REMOTE.5306.txt +++ /dev/null @@ -1,20 +0,0 @@ -# Copyright (C) 2012-2015 CEA/DEN, EDF R&D -# -# This library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. -# -# This library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -# -# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com -# - -ADD_SUBDIRECTORY(sphinx) diff --git a/doc/dev/models/medcalc.xmi b/doc/dev/models/medcalc.xmi new file mode 100644 index 000000000..00fbdb5a4 --- /dev/null +++ b/doc/dev/models/medcalc.xmi @@ -0,0 +1,318 @@ + + + + + umbrello uml modeller http://uml.sf.net + 1.5.8 + UnicodeUTF8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/dev/models/medop.xmi b/doc/dev/models/medop.xmi deleted file mode 100644 index 9422c56f0..000000000 --- a/doc/dev/models/medop.xmi +++ /dev/null @@ -1,318 +0,0 @@ - - - - - umbrello uml modeller http://uml.sf.net - 1.5.8 - UnicodeUTF8 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/dev/sphinx/CMakeLists.txt b/doc/dev/sphinx/CMakeLists.txt index 7ebd6c6f6..e38aa7beb 100644 --- a/doc/dev/sphinx/CMakeLists.txt +++ b/doc/dev/sphinx/CMakeLists.txt @@ -20,7 +20,7 @@ SALOME_CONFIGURE_FILE(conf.py.in conf.py) SET(_cmd_options -c ${CMAKE_CURRENT_BINARY_DIR} -b html -d doctrees -D latex_paper_size=a4 ${CMAKE_CURRENT_SOURCE_DIR} html) -SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${SPHINX_EXECUTABLE}" "${_cmd_options}") +SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${SPHINX_EXECUTABLE}" "${_cmd_options}") ADD_CUSTOM_TARGET(dev_docs ALL COMMAND ${_cmd}) diff --git a/doc/dev/sphinx/_static/medcalc.css b/doc/dev/sphinx/_static/medcalc.css new file mode 100644 index 000000000..1d0a878f4 --- /dev/null +++ b/doc/dev/sphinx/_static/medcalc.css @@ -0,0 +1,159 @@ +@import url("classic.css"); + +body { + font-family: {{ 'Liberation', sans-serif }}; + font-size: 82%; + color: #000; + background-color: #fff; + margin-left: 28px; +} + +ul { + margin: 0 0 0 0; +} + +div.related { + background-color: #444; +} + +a, +div.sphinxsidebar h3 a, +div.sphinxsidebar a, +div.footer a { + color: #444; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + color: #000; +} + +div.sphinxsidebar ul { + font-size: 94%; + color: #000; +} + +div.sphinxsidebar input { + border-color: #444; +} + +div.document { + background-color: #f5f8e4; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + color: #000; + background-color: transparent; + border-bottom: 1px solid #444; +} + +div.footer { + color: #000; +} + +li.toctree-l2 { + font-size: 100%; +} + +li.toctree-l3 { + font-size: 100%; +} + +div.sphinxsidebarwrapper ul { + list-style-type: disc; + margin-top: 1px; + padding-left: 6px; +} + +div.sphinxsidebarwrapper h3 { + font-size: 100%; + font-weight: bold; +} + +div.body h1 { + font-size: 200%; +} +div.body h2 { + font-size: 160%; +} +div.body h3, div.body h4 { + font-size: 125%; +} + +div.body p.topic-title { + margin-bottom: 2px; + font-size: 100%; +} + +div.sphinxsidebar p { + color: #444; +} + +#introduction p > em { + text-align: right; + float: right; +} + +#introduction p { + font-size: 90%; + margin-bottom: 3px; +} + +#introduction #id2.docutils.footnote { + font-size: 70%; + margin-top: 25px; +} + +#introduction table.docutils.footnote { + font-size: 70%; + margin-top: 5px; +} + + +.tt { + font-family:"Courier New",Courier,monospace; +} +.strike { + text-decoration: line-through; +} + +.bolditalic { + font-style:italic; + font-weight:bold +} + +.underline { + text-decoration:underline; +} + +.tag { + font-family:"Courier New",Courier,monospace; +} + +.tagb { + font-family:"Courier New",Courier,monospace; + font-weight:bold +} + +.todo { + background-color:yellow; +} + +.warn { + background-color:#FFE4E4; +} + +.info { + background-color:#EEEEEE; +} + +.date { + font-family:"Courier New",Courier,monospace; + font-style:italic; +} + diff --git a/doc/dev/sphinx/_static/medop.css b/doc/dev/sphinx/_static/medop.css deleted file mode 100644 index 1d0a878f4..000000000 --- a/doc/dev/sphinx/_static/medop.css +++ /dev/null @@ -1,159 +0,0 @@ -@import url("classic.css"); - -body { - font-family: {{ 'Liberation', sans-serif }}; - font-size: 82%; - color: #000; - background-color: #fff; - margin-left: 28px; -} - -ul { - margin: 0 0 0 0; -} - -div.related { - background-color: #444; -} - -a, -div.sphinxsidebar h3 a, -div.sphinxsidebar a, -div.footer a { - color: #444; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - color: #000; -} - -div.sphinxsidebar ul { - font-size: 94%; - color: #000; -} - -div.sphinxsidebar input { - border-color: #444; -} - -div.document { - background-color: #f5f8e4; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - color: #000; - background-color: transparent; - border-bottom: 1px solid #444; -} - -div.footer { - color: #000; -} - -li.toctree-l2 { - font-size: 100%; -} - -li.toctree-l3 { - font-size: 100%; -} - -div.sphinxsidebarwrapper ul { - list-style-type: disc; - margin-top: 1px; - padding-left: 6px; -} - -div.sphinxsidebarwrapper h3 { - font-size: 100%; - font-weight: bold; -} - -div.body h1 { - font-size: 200%; -} -div.body h2 { - font-size: 160%; -} -div.body h3, div.body h4 { - font-size: 125%; -} - -div.body p.topic-title { - margin-bottom: 2px; - font-size: 100%; -} - -div.sphinxsidebar p { - color: #444; -} - -#introduction p > em { - text-align: right; - float: right; -} - -#introduction p { - font-size: 90%; - margin-bottom: 3px; -} - -#introduction #id2.docutils.footnote { - font-size: 70%; - margin-top: 25px; -} - -#introduction table.docutils.footnote { - font-size: 70%; - margin-top: 5px; -} - - -.tt { - font-family:"Courier New",Courier,monospace; -} -.strike { - text-decoration: line-through; -} - -.bolditalic { - font-style:italic; - font-weight:bold -} - -.underline { - text-decoration:underline; -} - -.tag { - font-family:"Courier New",Courier,monospace; -} - -.tagb { - font-family:"Courier New",Courier,monospace; - font-weight:bold -} - -.todo { - background-color:yellow; -} - -.warn { - background-color:#FFE4E4; -} - -.info { - background-color:#EEEEEE; -} - -.date { - font-family:"Courier New",Courier,monospace; - font-style:italic; -} - diff --git a/doc/dev/sphinx/conf.py.in b/doc/dev/sphinx/conf.py.in index bc94c6f51..de917ad04 100644 --- a/doc/dev/sphinx/conf.py.in +++ b/doc/dev/sphinx/conf.py.in @@ -132,7 +132,7 @@ html_theme_options = { # The stylecheet file will be searched within the static path, while # the layout.html file will be searched within the template path # (Note that this parameter can't be used together with html_theme. Exclusive) -html_style = 'medop.css' +html_style = 'medcalc.css' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -175,7 +175,7 @@ html_copy_source = True #html_file_suffix = '' # Output file base name for HTML help builder. -htmlhelp_basename = 'medopdoc' +htmlhelp_basename = 'medcalcdoc' # Options for LaTeX output @@ -196,11 +196,11 @@ latex_elements = { # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ - ('index', 'medop-alldoc.tex', 'Documentation du module MED', 'G. Boulant', 'manual'), - ('medop-specifications', 'medop-specifications.tex', 'Module MED - Specifications', 'G. Boulant', 'manual'), - ('medop-develguide', 'medop-develguide.tex', 'Module MED - Guide de developpement', 'G. Boulant', 'manual'), - ('medop-userguide-gui', 'medop-userguide-gui.tex', 'Module MED - Guide d\'utilisation de l\'interface graphique', 'G. Boulant', 'howto'), - ('medop-userguide-api', 'medop-userguide-api.tex', 'MEDMEM library - Starter guide for users', 'G. Boulant', 'howto') + ('index', 'medcalc-alldoc.tex', 'Documentation du module MED', 'G. Boulant', 'manual'), + ('medcalc-specifications', 'medcalc-specifications.tex', 'Module MED - Specifications', 'G. Boulant', 'manual'), + ('medcalc-develguide', 'medcalc-develguide.tex', 'Module MED - Guide de developpement', 'G. Boulant', 'manual'), + ('medcalc-userguide-gui', 'medcalc-userguide-gui.tex', 'Module MED - Guide d\'utilisation de l\'interface graphique', 'G. Boulant', 'howto'), + ('medcalc-userguide-api', 'medcalc-userguide-api.tex', 'MEDMEM library - Starter guide for users', 'G. Boulant', 'howto') ] # The name of an image file (relative to this directory) to place at the top of diff --git a/doc/dev/sphinx/fr/index.rst b/doc/dev/sphinx/fr/index.rst index cf3fa4b1e..8d2939d2e 100644 --- a/doc/dev/sphinx/fr/index.rst +++ b/doc/dev/sphinx/fr/index.rst @@ -17,23 +17,23 @@ Documentation de référence .. toctree:: :maxdepth: 1 - medop-userguide-gui.rst - medop-userguide-api.rst + medcalc-userguide-gui.rst + medcalc-userguide-api.rst **Documentation technique** .. toctree:: :maxdepth: 1 - medop-specifications.rst - medop-develguide.rst + medcalc-specifications.rst + medcalc-develguide.rst **Documentation annexe** .. toctree:: :maxdepth: 1 - medop-references.rst + medcalc-references.rst Archives documentaires ====================== diff --git a/doc/dev/sphinx/fr/medcalc-definitions.rst b/doc/dev/sphinx/fr/medcalc-definitions.rst new file mode 100644 index 000000000..0cb67b4e5 --- /dev/null +++ b/doc/dev/sphinx/fr/medcalc-definitions.rst @@ -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` + + +.. 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/doc/dev/sphinx/fr/medcalc-develguide.rst b/doc/dev/sphinx/fr/medcalc-develguide.rst new file mode 100644 index 000000000..1984584f8 --- /dev/null +++ b/doc/dev/sphinx/fr/medcalc-develguide.rst @@ -0,0 +1,285 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med, développement + :author: Guillaume Boulant + +.. include:: medcalc-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Module MED: Guide de développement du composant MEDCalc +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Le composant logiciel MEDCalc 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 MEDCalc. 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 MEDCalc +------------------------------------------- + +Le composant logiciel MEDCalc est un package du module SALOME MED, +hébergé dans l'espace source au niveau du sous-répertoire +`src/MEDCalc`. La gestion des fichiers sources est donc intégrée dans le +module SALOME MED. + +Organisation des sources du composant MEDCalc +------------------------------------------- + +Le répertoire source `src/MEDCalc` 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 MEDCalc package (icons, config + files, data files, ...) +* exe: additional executable programs that can be launched from the + MEDCalc framework + +Construction du composant MEDCalc +------------------------------- + +Intégré à la construction du module MED. Le composant MEDCalc dépend de +MEDCoupling et MEDLoader uniquement. + +Exécution des tests unitaires du composant MEDCalc +------------------------------------------------ + +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_medcalc_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_loadDatasource (__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_medcalc_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:: + + loadDatasource(const char \*filepath) + + + +Eléments d'implémentation +========================= + +Ecrire un service CORBA qui retourne une sequence de FieldHandler: + +.. code-block:: cpp + + MEDCALC::FieldHandlerList * MyFunction(...) { + vector fieldHandlerList; + ... + + fieldHandlerList.push_back(fieldHandler); + + // Map the resulting list to a CORBA sequence for return: + MEDCALC::FieldHandlerList_var fieldHandlerSeq = new MEDCALC::FieldHandlerList(); + int nbFieldHandler = fieldHandlerList.size(); + fieldHandlerSeq->length(nbFieldHandler); + for (int i=0; iid] = 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 MEDCALC::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 MEDCalc, 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= + +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:: + + $ /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/doc/dev/sphinx/fr/medcalc-references.rst b/doc/dev/sphinx/fr/medcalc-references.rst new file mode 100644 index 000000000..2153884c1 --- /dev/null +++ b/doc/dev/sphinx/fr/medcalc-references.rst @@ -0,0 +1,28 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +ANNEXE: Références documentaires +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. include:: medcalc-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/doc/dev/sphinx/fr/medcalc-specifications.rst b/doc/dev/sphinx/fr/medcalc-specifications.rst new file mode 100644 index 000000000..ae152232e --- /dev/null +++ b/doc/dev/sphinx/fr/medcalc-specifications.rst @@ -0,0 +1,916 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med + :author: Guillaume Boulant + +.. include:: medcalc-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`, 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)>> r=fa+fb + +* Effectuer les contrôles visuel et les diagnostics en ligne de + commandes python (cf. :ref:`Spécification des fonctions de + 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/doc/dev/sphinx/fr/medcalc-userguide-gui.rst b/doc/dev/sphinx/fr/medcalc-userguide-gui.rst new file mode 100644 index 000000000..a90efde32 --- /dev/null +++ b/doc/dev/sphinx/fr/medcalc-userguide-gui.rst @@ -0,0 +1,752 @@ +.. meta:: + :keywords: maillage, champ, manipulation, guide utilisateur + :author: Guillaume Boulant + +.. include:: medcalc-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`, 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 ```` est créée +automatiquement dans la console de travail pour désigner le +champ. Dans cet exemple, ```` 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`): + + >>> 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`). 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` 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`). + +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()`` (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`:: + + >>> 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é):: + + $ /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:: + + $ /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:: + + >>> medcalc.LoadDataSource("/path/to/mydata.med") + >>> la + id=0 name = testfield1 + id=1 name = testfield2 + >>> f1=accessField(0) + >>> f2=accessField(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) + >>> putInWorkspace(r) + >>> saveWorkspace("result.med") + +Les commandes principales sont: + +* ``LoadDataSource``: charge un fichier med dans la base de données (utile + uniquement en mode texte pur):: + + >>> LoadDataSource("/path/to/datafile.med") + +* ``LoadImageAsDataSource``: load an image as a med file + +* ``la``: affiche la liste de tous les champs chargés en base de données ("list all") +* ``accessField``: 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=accessField(fieldId) + +* ``ls``: affiche la liste des champs présent dans l'espace de travail ("list") +* ``putInWorkspace``: met un champ en référence dans l'*espace de gestion*:: + + >>> putInWorkspace(f) + +* ``saveWorkspace``: sauvegarde tous les champs référencés dans l'espace de + gestion dans un fichier med:: + + >>> saveWorkspace("/path/to/resultfile.med") + +.. note:: On peut faire à ce stade plusieurs remarques: + + * la commande ``LoadDataSource`` 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 ``accessField`` 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: + +* ``medcalc.MakeDeflectionShape`` +* ``medcalc.MakeIsoSurface`` +* ``medcalc.MakePointSprite`` +* ``medcalc.MakeScalarMap`` +* ``medcalc.MakeSlices`` +* ``medcalc.MakeVectorField`` diff --git a/doc/dev/sphinx/fr/medop-definitions.rst b/doc/dev/sphinx/fr/medop-definitions.rst deleted file mode 100644 index 0cb67b4e5..000000000 --- a/doc/dev/sphinx/fr/medop-definitions.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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` - - -.. 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/doc/dev/sphinx/fr/medop-develguide.rst b/doc/dev/sphinx/fr/medop-develguide.rst deleted file mode 100644 index 57f826e1c..000000000 --- a/doc/dev/sphinx/fr/medop-develguide.rst +++ /dev/null @@ -1,285 +0,0 @@ -.. 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 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; iid] = 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= - -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:: - - $ /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/doc/dev/sphinx/fr/medop-prototype-develguide.rst b/doc/dev/sphinx/fr/medop-prototype-develguide.rst index de2387b74..0bc2eae90 100644 --- a/doc/dev/sphinx/fr/medop-prototype-develguide.rst +++ b/doc/dev/sphinx/fr/medop-prototype-develguide.rst @@ -210,14 +210,14 @@ l'addition de deux champs: 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é à @@ -269,7 +269,7 @@ et le numéro d'iteration: salome.salome_init() import SALOME_MED - medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") medObj = medComp.readStructFile("myfile.med",salome.myStudyName) from xmed import fieldproxy @@ -312,9 +312,9 @@ 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 @@ -353,7 +353,7 @@ un objet CORBA): // 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 + 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); @@ -363,7 +363,7 @@ un objet CORBA): 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()); @@ -411,9 +411,9 @@ commandes suivantes: 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 @@ -543,9 +543,9 @@ 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. @@ -556,7 +556,7 @@ 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 @@ -710,11 +710,11 @@ automatiser proprement): 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:: - + $ /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``. diff --git a/doc/dev/sphinx/fr/medop-prototype-medmem.rst b/doc/dev/sphinx/fr/medop-prototype-medmem.rst index 2302f7b70..9c29fee19 100644 --- a/doc/dev/sphinx/fr/medop-prototype-medmem.rst +++ b/doc/dev/sphinx/fr/medop-prototype-medmem.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, MED, MEDMEM :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Note de travail concernant l'utilisation de MEDMEM @@ -115,7 +115,7 @@ 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(); @@ -140,7 +140,7 @@ 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(); @@ -148,7 +148,7 @@ permettre la mise à jour du support: Pour enfin charger les valeurs des composantes du champ: .. code-block:: cpp - + field->read(); La numérotation des éléments de maillage @@ -204,7 +204,7 @@ Pour exemple, le fragment de code ci-dessous, extrait du fichier ``MedDataManager`` dans l'interface: .. code-block:: cpp - + #include "MEDMEM_MedDataManager.hxx" class MedDataManager @@ -212,24 +212,24 @@ Pour exemple, le fragment de code ci-dessous, extrait du fichier public: ~MedDataManager(); void printFieldDouble(FIELD * field); - + %extend { MedDataManager(char * fileName) { - return new MedDataManager(string(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 * getFieldDouble(const char * fieldName, const int dt, const int it) { - return (FIELD *) self->getFieldDouble(string(fieldName), dt, it); + return (FIELD *) self->getFieldDouble(string(fieldName), dt, it); } } - + }; @@ -380,17 +380,17 @@ 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 @@ -398,14 +398,14 @@ grâce auquel les services de chargement de la structure MED peuvent 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) @@ -418,13 +418,13 @@ verra plus bas) à MEDMEM: fieldIdx = 1 # WRN maybe there is no field of idx=1 iterationIdx = 0 fieldName = medObj.getFieldNames()[fieldIdx] - dtitfield = medObj.getFieldIteration(fieldName,iterationIdx) + 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:: @@ -469,22 +469,22 @@ 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 + + # 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 @@ -503,7 +503,7 @@ Notes en vrac Questions: -* Comment obtenir le nom du fichier med à partir d'une structure med? +* 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? diff --git a/doc/dev/sphinx/fr/medop-prototype-overview.rst b/doc/dev/sphinx/fr/medop-prototype-overview.rst index c571c6e6f..5eaa00e08 100644 --- a/doc/dev/sphinx/fr/medop-prototype-overview.rst +++ b/doc/dev/sphinx/fr/medop-prototype-overview.rst @@ -56,11 +56,11 @@ images: .. |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: diff --git a/doc/dev/sphinx/fr/medop-references.rst b/doc/dev/sphinx/fr/medop-references.rst deleted file mode 100644 index 9be8cdc5f..000000000 --- a/doc/dev/sphinx/fr/medop-references.rst +++ /dev/null @@ -1,28 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -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/doc/dev/sphinx/fr/medop-specifications.rst b/doc/dev/sphinx/fr/medop-specifications.rst deleted file mode 100644 index 09ca88cd2..000000000 --- a/doc/dev/sphinx/fr/medop-specifications.rst +++ /dev/null @@ -1,916 +0,0 @@ -.. 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`, 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)>> r=fa+fb - -* Effectuer les contrôles visuel et les diagnostics en ligne de - commandes python (cf. :ref:`Spécification des fonctions de - 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/doc/dev/sphinx/fr/medop-userguide-gui.rst b/doc/dev/sphinx/fr/medop-userguide-gui.rst deleted file mode 100644 index f09404a64..000000000 --- a/doc/dev/sphinx/fr/medop-userguide-gui.rst +++ /dev/null @@ -1,748 +0,0 @@ -.. 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`, 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 ```` est créée -automatiquement dans la console de travail pour désigner le -champ. Dans cet exemple, ```` 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`): - - >>> 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`). 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` 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`). - -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()`` (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`:: - - >>> 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é):: - - $ /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:: - - $ /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/doc/dev/sphinx/fr/medop-workingnotes-2011.rst b/doc/dev/sphinx/fr/medop-workingnotes-2011.rst index 2c38e64bb..269b63b5a 100644 --- a/doc/dev/sphinx/fr/medop-workingnotes-2011.rst +++ b/doc/dev/sphinx/fr/medop-workingnotes-2011.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, manipulation :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ANNEXE: Note de travail concernant le chantier XMED 2011 @@ -145,7 +145,7 @@ Nouveaux concepts à prendre en compte ------------------------------------- Au démarrage du chantier 2011, on observe que les concepts suivants -sont introduits dans le module MED: +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 @@ -469,5 +469,5 @@ Petites améliorations du DataspaceController: est posé dans le WS. On peut donc proposer en option de lui associer un alias pour manipulation dans la console - - + + diff --git a/doc/dev/sphinx/fr/medop-workingnotes-2012.rst b/doc/dev/sphinx/fr/medop-workingnotes-2012.rst index b6ecb6d37..4a3e10af4 100644 --- a/doc/dev/sphinx/fr/medop-workingnotes-2012.rst +++ b/doc/dev/sphinx/fr/medop-workingnotes-2012.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, manipulation :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ANNEXE: Note de travail concernant le chantier XMED 2012 @@ -80,5 +80,5 @@ peut procéder de la manière suivante: * 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 +.. warning:: TODO: refaire le point sur les tâches initiées en 2011 diff --git a/doc/dev/sphinx/index.rst b/doc/dev/sphinx/index.rst index e291c971c..6560ec984 100644 --- a/doc/dev/sphinx/index.rst +++ b/doc/dev/sphinx/index.rst @@ -15,23 +15,23 @@ References .. toctree:: :maxdepth: 1 - medop-userguide-gui.rst - medop-userguide-api.rst + medcalc-userguide-gui.rst + medcalc-userguide-api.rst **Technical documentation** (**in french**): .. toctree:: :maxdepth: 1 - medop-specifications.rst - medop-develguide.rst + medcalc-specifications.rst + medcalc-develguide.rst **Additional documentation** .. toctree:: :maxdepth: 1 - medop-references.rst + medcalc-references.rst Document archive (in french) ============================ diff --git a/doc/dev/sphinx/medcalc-definitions.rst b/doc/dev/sphinx/medcalc-definitions.rst new file mode 100644 index 000000000..3b4e37164 --- /dev/null +++ b/doc/dev/sphinx/medcalc-definitions.rst @@ -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:: 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|_ +.. |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` + + +.. 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/doc/dev/sphinx/medcalc-develguide.rst b/doc/dev/sphinx/medcalc-develguide.rst new file mode 100644 index 000000000..1984584f8 --- /dev/null +++ b/doc/dev/sphinx/medcalc-develguide.rst @@ -0,0 +1,285 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med, développement + :author: Guillaume Boulant + +.. include:: medcalc-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Module MED: Guide de développement du composant MEDCalc +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Le composant logiciel MEDCalc 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 MEDCalc. 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 MEDCalc +------------------------------------------- + +Le composant logiciel MEDCalc est un package du module SALOME MED, +hébergé dans l'espace source au niveau du sous-répertoire +`src/MEDCalc`. La gestion des fichiers sources est donc intégrée dans le +module SALOME MED. + +Organisation des sources du composant MEDCalc +------------------------------------------- + +Le répertoire source `src/MEDCalc` 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 MEDCalc package (icons, config + files, data files, ...) +* exe: additional executable programs that can be launched from the + MEDCalc framework + +Construction du composant MEDCalc +------------------------------- + +Intégré à la construction du module MED. Le composant MEDCalc dépend de +MEDCoupling et MEDLoader uniquement. + +Exécution des tests unitaires du composant MEDCalc +------------------------------------------------ + +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_medcalc_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_loadDatasource (__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_medcalc_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:: + + loadDatasource(const char \*filepath) + + + +Eléments d'implémentation +========================= + +Ecrire un service CORBA qui retourne une sequence de FieldHandler: + +.. code-block:: cpp + + MEDCALC::FieldHandlerList * MyFunction(...) { + vector fieldHandlerList; + ... + + fieldHandlerList.push_back(fieldHandler); + + // Map the resulting list to a CORBA sequence for return: + MEDCALC::FieldHandlerList_var fieldHandlerSeq = new MEDCALC::FieldHandlerList(); + int nbFieldHandler = fieldHandlerList.size(); + fieldHandlerSeq->length(nbFieldHandler); + for (int i=0; iid] = 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 MEDCALC::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 MEDCalc, 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= + +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:: + + $ /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/doc/dev/sphinx/medcalc-references.rst b/doc/dev/sphinx/medcalc-references.rst new file mode 100644 index 000000000..43cb54564 --- /dev/null +++ b/doc/dev/sphinx/medcalc-references.rst @@ -0,0 +1,28 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Appendix: Documentation references +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. include:: medcalc-definitions.rst + +References: + +* (**in french**) |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009 +* |REF_CEA_VBE_MEDMEM|_ - Vincent Bergeaud - janvier 2007 +* (**in french**) |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF) + +Slides (**in french**): + +* |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|_ (**video**) + - |REF_EDF_JUS2011_OGV3|_ (**video**) + - |REF_EDF_JUS2011_OGV4|_ (**video**) + +Working notes (**in french**): + +* |REF_EDF_GBO_WORKNOTE|_ - Guillaume Boulant - novembre 2010 +* |REF_EDF_ELO_REM|_ - Eric Lorentz - novembre 2010 diff --git a/doc/dev/sphinx/medcalc-specifications.rst b/doc/dev/sphinx/medcalc-specifications.rst new file mode 100644 index 000000000..ae152232e --- /dev/null +++ b/doc/dev/sphinx/medcalc-specifications.rst @@ -0,0 +1,916 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med + :author: Guillaume Boulant + +.. include:: medcalc-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`, 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)>> r=fa+fb + +* Effectuer les contrôles visuel et les diagnostics en ligne de + commandes python (cf. :ref:`Spécification des fonctions de + 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/doc/dev/sphinx/medcalc-userguide-api.rst b/doc/dev/sphinx/medcalc-userguide-api.rst new file mode 100644 index 000000000..161e0551f --- /dev/null +++ b/doc/dev/sphinx/medcalc-userguide-api.rst @@ -0,0 +1,528 @@ +.. meta:: + :description: introduction guide for users of the MEDMEM library + :keywords: mesh, field, med, MEDCoupling, MEDLoader + :author: Guillaume Boulant + +.. include:: medcalc-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +MEDMEM library: Starter guide for users +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +This document illustrates how to start with the programming interface +of the MEDMEM library. The users is someone who intends to create a +data processing script involving meshes and fields. + +.. contents:: Sommaire + :local: + :backlinks: none + :depth: 2 + +General overview +================ + +Definition of the MEDMEM library +-------------------------------- + +The MEDMEM library is designed to manipulate meshes and fields that +conform to the MED data model. This library can be used in C++ +programs as in python scripts for data processing on meshes and +fields. The library contains the data structure to describe meshes and +fields as C++ objects (MEDCoupling package). It provides a set of +functions to manage the persistency toward the med file format +(MEDLoader package), and to process the data througt interpolation and +localization algorithms (INTERP_KERNEL and REMAPPER packages), for +example to perform field projections from a mesh to another. + +Installation of the MEDMEM library +---------------------------------- + +The MEDMEM library is part of the SALOME MED module and then is +installed together with this module by the installation process of +SALOME. Nevertheless, it is possible for low-weight deployment to +install only the MEDMEM library from the source files embedded in the +SALOME MED module. Keep in mind that the MEDMEM library is designed to +be a self-consistent library with very few third party softwares (only +med-file, glibc and mpi typically). In particular, it is strictly +independant from the SALOME framework even if it distributed with +SALOME for convenience reasons. + +Components of the MEDMEM library +-------------------------------- + +The MEDMEM library consists in a small set of atomic libraries files, +in particular: + +* :tt:`medcoupling`: this library provides the data structures (C++ + classes) to describe meshes and fields. +* :tt:`medloader`: this library provides I/O functions to the MED file + format +* :tt:`interpkernel`: this library provides the mathematical + structures and algorithms required med data processing, in + particular interpolation and localization. +* :tt:`medcouplingremapper`: this library provides the functions for + fields projections and interpolation. + +The figure below represents the layer structure of the packages of the +library: + +.. image:: images/medlayers_70pc.png + :align: center + +What we call MEDMEM library in this document is represented by the +orange packages on this diagram. The white packages reprensent the old +deprecated MEDMEM library. The blue packages represent the aditionnal +components for field manipulation througth the user interface (TUI and +GUI). + +The MEDMEM library comes also with this set of atomic libraries for +advanced users/programmers: + +* :tt:`medcouplingcorba`: this library is designed for cross process + exchange of medcoupling objects. +* :tt:`medpartitioner`: this library provides functions to split a MED + domain in several part in the perspective of parallel computing + +All these atomic C++ libraries are wrapped into a set of python +modules (using the swig binding technology) so that all the data +processing can be realized by scripting. + +.. warning:: It could happen that some parts of the C++ libraries are + not wrapped into python modules. This coverture will be + extend on demand and if the integrity of the concepts is + preserved. + +Main concepts of the MEDMEM library +=================================== + +.. warning:: TODO avec Antony. Présenter les structure de données de + MEDCoupling principalement. Describe the MEDMEM data + model, the typical content of a med file, the types of + cell that compose the meshes, the types of spatial + discretization of fields, ... + +Basic usages of the MEDMEM library +================================== + +This section illustrates the usage of main features of the MEDMEM +library using python examples. The usage of python is just to have a +light syntax that makes more easy the first understanding. + +.. note:: All code examples here after are parts of the tutorial use + cases located in the folder :tt:`src/MEDCalc/tut` in the MED + source directory. These use cases are all working executable + programs and they can be used to initiate your own script. + +Preparing the shell environment +------------------------------- + +We make the hypothesis here that the MEDMEM library is installed using +the SALOME procedure and then is located in the MED module +installation directory. In addition to the MED library, the third +party softwares required for executing the examples are: python, hdf5 +and med-fichier. Then, you should prepare your shell environment +with a set of instructions that looks like:: + + #------ python ------ + export PYTHONHOME= + export PYTHONSTARTUP=${PYTHONHOME}/pythonrc.py + export PYTHON_INCLUDE=${PYTHONHOME}/include/python2.6 + export PATH=${PYTHONHOME}/bin:${PATH} + export LD_LIBRARY_PATH=${PYTHONHOME}/lib:${LD_LIBRARY_PATH} + + #------ hdf5 ------ + HDF5HOME= + export PATH=${HDF5HOME}/bin:$PATH + export LD_LIBRARY_PATH=${HDF5HOME}/lib:${LD_LIBRARY_PATH} + export HDF5_DISABLE_VERSION_CHECK=1 + + #------ med ------ + MED2HOME= + export PATH=${MED2HOME}/bin:${PATH} + export LD_LIBRARY_PATH=${MED2HOME}/lib:${LD_LIBRARY_PATH} + + #------ medmem --- + MED_ROOT_DIR= + export LD_LIBRARY_PATH=${MED_ROOT_DIR}/lib/salome:${LD_LIBRARY_PATH} + PYTHONPATH=${MED_ROOT_DIR}/lib/python2.6/site-packages/salome:${PYTHONPATH} + PYTHONPATH=${MED_ROOT_DIR}/bin/salome:${PYTHONPATH} + PYTHONPATH=${MED_ROOT_DIR}/lib/salome:${PYTHONPATH} + export PYTHONPATH + +Example 01: Explore a med file to get information concerning meshes and fields +------------------------------------------------------------------------------ + +:objectives: This example illustrates how to get information + concerning meshes and fields from a med file, using the + MEDLoader library. + +The loading of meshes and fields from a med file to a MEDCoupling data +structure requires first the knowledge of metadata associated to these +meshes and fields. You have to know the names of the meshes, so that +you can specify the one you want to load, and then the names of the +fields associated to one given mesh, the space discretizations used +for each field, and the iterations available. + +The MEDLoader library can read these metadata without loading the +physical data that compose the meshes and fields. This feature ensures +the performance of the exploration process, in particular in the case +of big meshes. + +This first instruction looks for meshes embedded in the med file +(located by :tt:`filepath`) and returns the list of mesh names: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +.. WARNING: Note that the file path for the include directive must be + relative to this rst source file (i.e. as organized in the MED + source directory, and nevertheless the build procedure is realized + elsewhere. + +Then, you may select one of these names (or iterate on all names of +the list) and read the list of fields defined on this mesh: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T2A + :end-before: # _T2B + +A field name could identify several MEDCoupling fields, that differ by +their spatial discretization on the mesh (values on cells, values on +nodes, ...). This spatial discretization is specified by the +TypeOfField that is an integer value in this list: + +* :tt:`0 = ON_CELLS` (physical values defined by cell) +* :tt:`1 = ON_NODES` (physical values defined on nodes) +* :tt:`2 = ON_GAUSS_PT` (physical values defined on Gauss points) +* :tt:`3 = ON_GAUSS_NE` + +.. note:: This constant variables are defined by the MEDLoader module + (:tt:`from MEDLoader import ON_NODES`). + +As a consequence, before loading the physical values of a field, we +have to determine the types of spatial discretization that come with +this field name and to choose one of this types. The instruction below +read all the spatial discretization types available for the field of +name :tt:`fieldName` defined on the mesh of name :tt:`meshName`: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T3A + :end-before: # _T3B + +Once you have selected the spatial discretization of interest (called +:tt:`typeOfDiscretization` in the code below, that corresponds to an +item of the list :tt:`listOfTypes`), you can extract the list of time +iterations available for the identified field: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T4A + :end-before: # _T4B + +The iterations can be weither a list of time steps for which the field +is defined (a timeseries) or a list of frequency steps (spectral +analysis). In any case, an iteration item consists in a couple of +integers, the first defining the main iteration step and the second an +iteration order in this step, that can be consider as a sub-iteration +of the step. In most of cases, the iteration order is set to :tt:`-1` +(no sub-iterations). + +The field values can now be read for one particular time step (or +spectrum tic), defined by the pair (iteration number, iteration +order). This is illustrated by the example here after. + +Example 02: Load a mesh and a field from a med file +--------------------------------------------------- + +:objectives: This illustrates how to load the physical data of a + specified mesh and a specified field. + +The metadata read from a med file are required to identify the list of +meshes and fields in the med file. We assume in this example that the +mesh and field to load are identified, i.e. we know the name of the +mesh to load (:tt:`meshName`) and the characteristic properties of the +field to load (:tt:`fieldName`, :tt:`typeOfDiscretization` and +:tt:`iteration`). For example, the instruction below load the mesh of +name :tt:`meshName`: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T5A + :end-before: # _T5B + +and the instruction below load the field with name :tt:`fieldName` +defined on this mesh at a particular iteration step characterized by +the couple :tt:`(iterationNumber,iterationOrder)`: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T6A + :end-before: # _T6B + +The variables :tt:`mesh` and :tt:`field` in this code example are instances of +the MEDCoupling classes describing the meshes and fields. + +Note that the read functions required the parameter +:tt:`dimrestriction`. This parameter discreminates the mesh dimensions you +are interested to relatively to the maximal dimension of cells +contained in the mesh (then its value could be 0, -1, -2 or -3 +depending on the max dimension of the mesh). A value of +:tt:`dimrestriction=0` means "no restriction". + +Example 03: Manage the MEDCoupling data load from a med file +------------------------------------------------------------ + +:objectives: Some suggestions for the MEDCoupling objects management, + in a programming context. + +In a real programming case, it could be relevant to explore first the +med file to load all metadata concerning the whole set of meshes and +associated fields, and then to load the physical data only once when +required by the program. + +Such a programming scenario required that you keep all metadata in +data structures created in memory, so that you can manage the +collection of meshes and fields. Nevertheless, the MEDMEM library +does not provide such data structures. + +We suggest to work with a simple list concept to store the metadata +for each mesh entry and each field entry. Note that a mesh entry is +characterized by the mesh name only, while a field entry is +charaterized by the following attributes: + +* :tt:`fieldName`: the name of the field +* :tt:`meshName`: the name of the mesh that supports the field +* :tt:`typeOfDiscretization`: the type of spatial discretization +* :tt:`iteration`: a couple of integers :tt:`(iter,order)` that + characterizes the step in a serie (timeseries or spectrum). + +By default, we suggest to work with a simple map concept (dictionnary in a +python context, map in a C++ context) to register the meshes and +fields loaded from the med file for each metadata entry. + +Then, depending on the processing algorithm you intend to implement, +you may dispatch the data in a tree structure that fit your specific +case, for performance reasons. For example, the following code +illustrates how to dispatch the metadata in a tree data structure +where leaves are the physical data (field objects). We first have to +define a tree structure (basic definition in htis simple case, but it +works fine): + +.. include:: ../../tut/medloader/manage.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +Then, we can scan the med structure and dispatch the metadata in the +tree structure: + +.. include:: ../../tut/medloader/manage.py + :literal: + :start-after: # _T2A + :end-before: # _T2B + +Finally (and afterwards), we can display on standard output the +metadata registered in the tree structure: + +.. include:: ../../tut/medloader/manage.py + :literal: + :start-after: # _T3A + :end-before: # _T3B + +Example 04: Simple arithmetic operations with fields +---------------------------------------------------- + +:objectives: This example illustrates how to load field iterations + from a med file containing a field timeseries and shows + how to use these iterations in simple arithmetic + operations. + +We consider a med file :tt:`timeseries.med`, containing one single +mesh named :tt:`Grid_80x80` that supports a field with values defined +on nodes (:tt:`typeOfDiscretization=ON_NODES`) given for ten +iterations. + +This first code block identifies the mesh and the field to consider in +this example: + +.. include:: ../../tut/addfields/operations.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +The following instructions load the field, make a scaling on the +physical values (multiply by 3) and then save the result in an output +med file named :tt:`scaling.med`: + +.. include:: ../../tut/addfields/operations.py + :literal: + :start-after: # _T2A + :end-before: # _T2B + +Note the usage of the method :tt:`applyFunc` that takes in argument a +string expression that defined the mathematical function to apply on +the values of the fields. In this expression, the field is symbolized +by the letter :tt:`f`. + +The following set of instructions makes the addition of iteration +number 3 with iteration number 4 of the field. Note that this +operation required first to load the mesh: + +.. include:: ../../tut/addfields/operations.py + :literal: + :start-after: # _T3A + :end-before: # _T3B + +Exemple 05: Compare fields load from different files +---------------------------------------------------- + +:objectives: Illustrates the usage of the function + changeUnderlyingMesh + +Exemple 06: Create a field from scratch on a spatial domain +----------------------------------------------------------- + +:objectives: Illustrates the applyFunc method of fields + +Exemple 07: Manipulate structured mesh +-------------------------------------- + +:objectives: Illustrates the basic usage of the advanced interface of + MEDLoader. + +The MEDLoader frontal interface let you load unstructured meshes: + +.. include:: ../../tut/medloader/tutorial.py + :literal: + :start-after: # _T5A + :end-before: # _T5B + +That is to say that even if the mesh is a structured mesh (a grid mesh +for example), then you will get a MEDCoupling unstructured mesh +object. + +To manipulate structured mesh objects, you have to use the MEDLoader +backend interface named :tt:`MEDFileMesh`, or its derivative +:tt:`MEDFileUMesh` for unstructured meshes, and :tt:`MEDFileCMesh` for +structured meshes (CMesh for Cartesian Mesh). The code below +illustrates how to load a mesh using the :tt:`MEDFileMesh` interface, +and to know if it is a structured mesh: + +.. include:: ../../tut/medloader/cmesh.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +This second example can be used in the case where you know in advance +that it is a structured mesh: + +.. include:: ../../tut/medloader/cmesh.py + :literal: + :start-after: # _T2A + :end-before: # _T2B + +In any cases, you can also save the mesh in another file with the +methode :tt:`write` of the :tt:`MEDFileMesh` object: + +.. include:: ../../tut/medloader/cmesh.py + :literal: + :start-after: # _T3A + :end-before: # _T3B + +Exemple 08: Make a projection of a field +---------------------------------------- + +:objectives: Make the projection of a field from a source mesh to a + target meshe. The source mesh and the target mesh are + two different mesh of the same geometry. + +The input data of this use case are: + +* a source mesh, and a field defined on this source mesh (left side of + the figure below) +* a target mesh, on which we want to project the field (right side of + the figure below) + +.. note:: The two meshes are displayed side by side on the figure for + convenience reason, but in the real use case they stand at + the same location in 3D space (they describe the same + geometry). + +.. image:: images/medop_projection_inputs.png + :align: center + +The expected result is a field defined on the target mesh and which +corresponds to a physical data equivalent to the source field, +i.e. with conservation of some physical properties. This operation +requires the usage of interpolation algorithms provided by the +:tt:`medcouplingremapper` library: + +.. include:: ../../tut/projection/demomed/demo_loadsource.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +Some comments on this code: + +* The physical property to be preserved by this interpolation is + specified using the keyword :tt:`ConservativeVolumic` +* The parameter :tt:`P0P0` given at the preparation step of the + remapper specifies that the interpolation is done from CELLS (P0) to + CELLS (P0). +* The interpolation, strictly speaking, is performed by the + instruction :tt:`ftarget = + remap.transferField(fsource,defaultValue)` +* In this instruction, the :tt:`defaultValue` is used to set the target value + in the case where there is no cell in the source mesh that overlap + the target mesh (for example when the source mesh correspond to a + geometrical sub-part of the target mesh). + +When executing the :tt:`remapper`, the result is a new field defined on +the target mesh, as illustrated on the figure below: + +.. image:: images/medop_projection_result.png + :align: center + +Exemple 09: Make a partition of a mesh using a field +---------------------------------------------------- + +:objective: This illustrates how to make a mesh partition using the + value of a field defined on this mesh. + +The input data is a MEDCoupling scalar field (:tt:`field`) defined on +a 3D mesh, and we want to use this field as a criterium to make a +partition of the mesh, for example by creating the mesh surface that +delimits the volumes where the field value is greater that a limit L +(and conversely the volumes where the field value is lower). + +.. image:: images/partition_mesh.png + :align: center + +The code below shows the simplest way to extract the cells where +:tt:`field>L` and to create the skin mesh: + +.. include:: ../../tut/medcoupling/partition.py + :literal: + :start-after: # _T1A + :end-before: # _T1B + +At the end, the variable :tt:`skin` is a 2D mesh that can be saved in +a med file using the MEDLoader: + +.. image:: images/partition_skin.png + :align: center + +Advanced usages of the MEDMEM library +===================================== + +This section could explain how to process the physical data +(dataArray) and to manipulate the advanced concepts of the MEDMEM +library. + +.. Exemple 01: Create a field from an image +.. ---------------------------------------- + diff --git a/doc/dev/sphinx/medcalc-userguide-gui.rst b/doc/dev/sphinx/medcalc-userguide-gui.rst new file mode 100644 index 000000000..7a5de95c8 --- /dev/null +++ b/doc/dev/sphinx/medcalc-userguide-gui.rst @@ -0,0 +1,653 @@ +.. meta:: + :keywords: mesh, field, manipulation, user guide + :author: Guillaume Boulant + +.. include:: medcalc-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +MED module: User guide for graphical interface +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +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:: This document is self-contained, but it is strongly advised to + read :doc:`the specification document` (in + french), at least to clarify concepts and terminology. + +.. contents:: Contents + :local: + :backlinks: none + +.. 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 + +A typical use of field manipulation functions is: + +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. + + +Quick tour on functions available in MED module +=============================================== + +This section presents some use examples of MED module like a "storyboard", +illustrating the functions proposed by the module. + +.. warning:: This section is under construction. Please consider that its + contents and organization are still incomplete and may change + until this warning is removed. + +Example 1: Explore data sources +------------------------------- + +.. note:: This example illustrates the following functions: + + * add a data source + * "Extends field series" and "Visualize" functions + +.. |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 + +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 + +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 + +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 +.. |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:: 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. + +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:: This graphical representation aims at providing a quick visual + control. Scalar maps are displayed using the PARAVIS module. + +Example 2: Combine fields from different sources +------------------------------------------------ + +.. note:: This example illustrates the following functions: + + * 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 + +The objective is to access data contained in several med files, then to +combine them in the same output file. + +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 + +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 + +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 + +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: + +Example 3: Apply a formula on fields +------------------------------------ + +.. note:: This example illustrates the following functions: + + * execute mathematical operations in TUI console + * function "put" to refer to a work field in the list of persisting fields. + * function "Visualize" from TUI. + +The most common usage of field manipulation module is to execute mathematical +operations on fields or on their components. + +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). + +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:: 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 +```` is automatically created in the TUI to designate the field. In +this example, ```` 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 + +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 + +Other operations can be applied, as detailed in module specifications +(cf. :ref:`Spécification des opérations`): + + >>> 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 + >>> ... + +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 + +Scalar variables can be used if needed:: + + >>> r=4*f3-f4/1000 + >>> ... + +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) + +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 + +Second, variables can be used as command arguments (the list of commands +available in TUI is described in section :ref:`Documentation of textual +interface`). For example the function ``view`` displays +the field scalar map in the viewer:: + + >>> view(f3) + +Results in: + +.. image:: images/xmed-gui-workspace-view.png + :align: center + :width: 800px + +.. 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) + +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 #6556 : 3.5 + Tuple #6557 : 3.3 + Tuple #6558 : 1.5 + Tuple #6559 : 0.3 + Tuple #6560 : 0.2 + +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` described hereafter. + +.. _xmed.userguide.exemple4: + +Example 4: Compare fields derived from different sources +-------------------------------------------------------- + +.. note:: This example illustrates the following function: + + * Change the underlying (support) mesh + +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. + +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. + +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. + +However field manipulation functions do not allow operations on fields lying +on different support meshes (see remark at the end of :ref:`example +3`). + +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 + +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 + +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:: 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()`` (dup stands for "duplicate"). + +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. + +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`:: + + >>> r=f1-f2 + >>> view(r) + +.. 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). + + +Example 5: Create a field on a spatial domain +--------------------------------------------- + +.. note:: This example illustrates the following functions: + + * initialize with function of spatial position + * initialize on a group of cells + +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. + +.. warning:: DEVELOPMENT IN PROGRESS + +Example 6: Extract a field part +------------------------------- + +.. note:: This example illustrates the following functions: + + * extract a component (or a subset of components) + * extract a geometrical domain (values on a group of cells) + * extract one or several time steps + +.. warning:: DEVELOPMENT IN PROGRESS + + 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). + +For time step extraction, we can reduce to the case of example 2 with a single +data source. + +Example 7: Create a field from a to[mp]ographic image +----------------------------------------------------- + +.. note:: This example illustrates the following function: + + * 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 + +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 + +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):: + + $ /bin/salome/xmed/image2med.py -i myimage.png -m myfield.med + +.. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png + :height: 16px + +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 + +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. + +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 + +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 + +The result of loading: + +.. image:: images/medop_image2med_tomographie.png + :align: center + :width: 800px + +Example 8: Continue analysis in PARAVIS +--------------------------------------- + +.. note:: This example illustrates the following functio: + + * Export fields to PARAVIS module + +The solutions for field representation in MED module aims at proposing a quick +visual control. + +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). + +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 + +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:: 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: + +Using the textual interface (TUI) +================================= + +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:: + + $ /medop.sh +.. + This command opens a command console ``medop>``. A med file can be loaded and + manipulated, for example to create fields from file data. + +Whatever textual or graphical mode is used, a typical workflow in console +looks like the following instructions:: + + >>> medcalc.LoadDataSource("/path/to/mydata.med") + >>> la + id=0 name = testfield1 + id=1 name = testfield2 + >>> f1=accessField(0) + >>> f2=accessField(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) + >>> putInWorkspace(r) + >>> saveWorkspace("result.med") + +The main commands are: + +* ``LoadDataSource``: load a med file in data base (useful in pure textual mode):: + + >>> LoadDataSource("/path/to/datafile.med") + +* ``LoadImageAsDataSource``: load an image as a med file + +* ``la``: show the list of all fields loaded in data base ("list all") +* ``accessField``: 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=accessField(fieldId) + +* ``ls``: show the list of fields available in workspace ("list") +* ``putInWorkspace``: put a reference to a field in *management space*:: + + >>> putInWorkspace(f) + +* ``saveWorkspace``: save to a med a file all fields referenced in management space:: + + >>> saveWorkspace("/path/to/resultfile.med") + +.. note:: + + * the ``LoadDataSource`` 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 ``accessField`` 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: + +* ``medcalc.MakeDeflectionShape`` +* ``medcalc.MakeIsoSurface`` +* ``medcalc.MakePointSprite`` +* ``medcalc.MakeScalarMap`` +* ``medcalc.MakeSlices`` +* ``medcalc.MakeVectorField`` + + +.. LocalWords: softwares diff --git a/doc/dev/sphinx/medop-definitions.rst b/doc/dev/sphinx/medop-definitions.rst deleted file mode 100644 index 3b4e37164..000000000 --- a/doc/dev/sphinx/medop-definitions.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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:: 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|_ -.. |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` - - -.. 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/doc/dev/sphinx/medop-develguide.rst b/doc/dev/sphinx/medop-develguide.rst deleted file mode 100644 index 57f826e1c..000000000 --- a/doc/dev/sphinx/medop-develguide.rst +++ /dev/null @@ -1,285 +0,0 @@ -.. 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 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; iid] = 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= - -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:: - - $ /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/doc/dev/sphinx/medop-prototype-develguide.rst b/doc/dev/sphinx/medop-prototype-develguide.rst index de2387b74..0bc2eae90 100644 --- a/doc/dev/sphinx/medop-prototype-develguide.rst +++ b/doc/dev/sphinx/medop-prototype-develguide.rst @@ -210,14 +210,14 @@ l'addition de deux champs: 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é à @@ -269,7 +269,7 @@ et le numéro d'iteration: salome.salome_init() import SALOME_MED - medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") medObj = medComp.readStructFile("myfile.med",salome.myStudyName) from xmed import fieldproxy @@ -312,9 +312,9 @@ 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 @@ -353,7 +353,7 @@ un objet CORBA): // 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 + 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); @@ -363,7 +363,7 @@ un objet CORBA): 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()); @@ -411,9 +411,9 @@ commandes suivantes: 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 @@ -543,9 +543,9 @@ 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. @@ -556,7 +556,7 @@ 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 @@ -710,11 +710,11 @@ automatiser proprement): 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:: - + $ /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``. diff --git a/doc/dev/sphinx/medop-prototype-medmem.rst b/doc/dev/sphinx/medop-prototype-medmem.rst index 2302f7b70..9c29fee19 100644 --- a/doc/dev/sphinx/medop-prototype-medmem.rst +++ b/doc/dev/sphinx/medop-prototype-medmem.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, MED, MEDMEM :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Note de travail concernant l'utilisation de MEDMEM @@ -115,7 +115,7 @@ 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(); @@ -140,7 +140,7 @@ 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(); @@ -148,7 +148,7 @@ permettre la mise à jour du support: Pour enfin charger les valeurs des composantes du champ: .. code-block:: cpp - + field->read(); La numérotation des éléments de maillage @@ -204,7 +204,7 @@ Pour exemple, le fragment de code ci-dessous, extrait du fichier ``MedDataManager`` dans l'interface: .. code-block:: cpp - + #include "MEDMEM_MedDataManager.hxx" class MedDataManager @@ -212,24 +212,24 @@ Pour exemple, le fragment de code ci-dessous, extrait du fichier public: ~MedDataManager(); void printFieldDouble(FIELD * field); - + %extend { MedDataManager(char * fileName) { - return new MedDataManager(string(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 * getFieldDouble(const char * fieldName, const int dt, const int it) { - return (FIELD *) self->getFieldDouble(string(fieldName), dt, it); + return (FIELD *) self->getFieldDouble(string(fieldName), dt, it); } } - + }; @@ -380,17 +380,17 @@ 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 @@ -398,14 +398,14 @@ grâce auquel les services de chargement de la structure MED peuvent 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) @@ -418,13 +418,13 @@ verra plus bas) à MEDMEM: fieldIdx = 1 # WRN maybe there is no field of idx=1 iterationIdx = 0 fieldName = medObj.getFieldNames()[fieldIdx] - dtitfield = medObj.getFieldIteration(fieldName,iterationIdx) + 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:: @@ -469,22 +469,22 @@ 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 + + # 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 @@ -503,7 +503,7 @@ Notes en vrac Questions: -* Comment obtenir le nom du fichier med à partir d'une structure med? +* 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? diff --git a/doc/dev/sphinx/medop-prototype-overview.rst b/doc/dev/sphinx/medop-prototype-overview.rst index c571c6e6f..5eaa00e08 100644 --- a/doc/dev/sphinx/medop-prototype-overview.rst +++ b/doc/dev/sphinx/medop-prototype-overview.rst @@ -56,11 +56,11 @@ images: .. |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: diff --git a/doc/dev/sphinx/medop-references.rst b/doc/dev/sphinx/medop-references.rst deleted file mode 100644 index 0cc327834..000000000 --- a/doc/dev/sphinx/medop-references.rst +++ /dev/null @@ -1,28 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -Appendix: Documentation references -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -.. include:: medop-definitions.rst - -References: - -* (**in french**) |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009 -* |REF_CEA_VBE_MEDMEM|_ - Vincent Bergeaud - janvier 2007 -* (**in french**) |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF) - -Slides (**in french**): - -* |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|_ (**video**) - - |REF_EDF_JUS2011_OGV3|_ (**video**) - - |REF_EDF_JUS2011_OGV4|_ (**video**) - -Working notes (**in french**): - -* |REF_EDF_GBO_WORKNOTE|_ - Guillaume Boulant - novembre 2010 -* |REF_EDF_ELO_REM|_ - Eric Lorentz - novembre 2010 diff --git a/doc/dev/sphinx/medop-specifications.rst b/doc/dev/sphinx/medop-specifications.rst deleted file mode 100644 index 09ca88cd2..000000000 --- a/doc/dev/sphinx/medop-specifications.rst +++ /dev/null @@ -1,916 +0,0 @@ -.. 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`, 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)>> r=fa+fb - -* Effectuer les contrôles visuel et les diagnostics en ligne de - commandes python (cf. :ref:`Spécification des fonctions de - 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/doc/dev/sphinx/medop-userguide-api.rst b/doc/dev/sphinx/medop-userguide-api.rst deleted file mode 100644 index 6f230abc8..000000000 --- a/doc/dev/sphinx/medop-userguide-api.rst +++ /dev/null @@ -1,528 +0,0 @@ -.. meta:: - :description: introduction guide for users of the MEDMEM library - :keywords: mesh, field, med, MEDCoupling, MEDLoader - :author: Guillaume Boulant - -.. include:: medop-definitions.rst - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -MEDMEM library: Starter guide for users -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -This document illustrates how to start with the programming interface -of the MEDMEM library. The users is someone who intends to create a -data processing script involving meshes and fields. - -.. contents:: Sommaire - :local: - :backlinks: none - :depth: 2 - -General overview -================ - -Definition of the MEDMEM library --------------------------------- - -The MEDMEM library is designed to manipulate meshes and fields that -conform to the MED data model. This library can be used in C++ -programs as in python scripts for data processing on meshes and -fields. The library contains the data structure to describe meshes and -fields as C++ objects (MEDCoupling package). It provides a set of -functions to manage the persistency toward the med file format -(MEDLoader package), and to process the data througt interpolation and -localization algorithms (INTERP_KERNEL and REMAPPER packages), for -example to perform field projections from a mesh to another. - -Installation of the MEDMEM library ----------------------------------- - -The MEDMEM library is part of the SALOME MED module and then is -installed together with this module by the installation process of -SALOME. Nevertheless, it is possible for low-weight deployment to -install only the MEDMEM library from the source files embedded in the -SALOME MED module. Keep in mind that the MEDMEM library is designed to -be a self-consistent library with very few third party softwares (only -med-file, glibc and mpi typically). In particular, it is strictly -independant from the SALOME framework even if it distributed with -SALOME for convenience reasons. - -Components of the MEDMEM library --------------------------------- - -The MEDMEM library consists in a small set of atomic libraries files, -in particular: - -* :tt:`medcoupling`: this library provides the data structures (C++ - classes) to describe meshes and fields. -* :tt:`medloader`: this library provides I/O functions to the MED file - format -* :tt:`interpkernel`: this library provides the mathematical - structures and algorithms required med data processing, in - particular interpolation and localization. -* :tt:`medcouplingremapper`: this library provides the functions for - fields projections and interpolation. - -The figure below represents the layer structure of the packages of the -library: - -.. image:: images/medlayers_70pc.png - :align: center - -What we call MEDMEM library in this document is represented by the -orange packages on this diagram. The white packages reprensent the old -deprecated MEDMEM library. The blue packages represent the aditionnal -components for field manipulation througth the user interface (TUI and -GUI). - -The MEDMEM library comes also with this set of atomic libraries for -advanced users/programmers: - -* :tt:`medcouplingcorba`: this library is designed for cross process - exchange of medcoupling objects. -* :tt:`medpartitioner`: this library provides functions to split a MED - domain in several part in the perspective of parallel computing - -All these atomic C++ libraries are wrapped into a set of python -modules (using the swig binding technology) so that all the data -processing can be realized by scripting. - -.. warning:: It could happen that some parts of the C++ libraries are - not wrapped into python modules. This coverture will be - extend on demand and if the integrity of the concepts is - preserved. - -Main concepts of the MEDMEM library -=================================== - -.. warning:: TODO avec Antony. Présenter les structure de données de - MEDCoupling principalement. Describe the MEDMEM data - model, the typical content of a med file, the types of - cell that compose the meshes, the types of spatial - discretization of fields, ... - -Basic usages of the MEDMEM library -================================== - -This section illustrates the usage of main features of the MEDMEM -library using python examples. The usage of python is just to have a -light syntax that makes more easy the first understanding. - -.. note:: All code examples here after are parts of the tutorial use - cases located in the folder :tt:`src/MEDOP/tut` in the MED - source directory. These use cases are all working executable - programs and they can be used to initiate your own script. - -Preparing the shell environment -------------------------------- - -We make the hypothesis here that the MEDMEM library is installed using -the SALOME procedure and then is located in the MED module -installation directory. In addition to the MED library, the third -party softwares required for executing the examples are: python, hdf5 -and med-fichier. Then, you should prepare your shell environment -with a set of instructions that looks like:: - - #------ python ------ - export PYTHONHOME= - export PYTHONSTARTUP=${PYTHONHOME}/pythonrc.py - export PYTHON_INCLUDE=${PYTHONHOME}/include/python2.6 - export PATH=${PYTHONHOME}/bin:${PATH} - export LD_LIBRARY_PATH=${PYTHONHOME}/lib:${LD_LIBRARY_PATH} - - #------ hdf5 ------ - HDF5HOME= - export PATH=${HDF5HOME}/bin:$PATH - export LD_LIBRARY_PATH=${HDF5HOME}/lib:${LD_LIBRARY_PATH} - export HDF5_DISABLE_VERSION_CHECK=1 - - #------ med ------ - MED2HOME= - export PATH=${MED2HOME}/bin:${PATH} - export LD_LIBRARY_PATH=${MED2HOME}/lib:${LD_LIBRARY_PATH} - - #------ medmem --- - MED_ROOT_DIR= - export LD_LIBRARY_PATH=${MED_ROOT_DIR}/lib/salome:${LD_LIBRARY_PATH} - PYTHONPATH=${MED_ROOT_DIR}/lib/python2.6/site-packages/salome:${PYTHONPATH} - PYTHONPATH=${MED_ROOT_DIR}/bin/salome:${PYTHONPATH} - PYTHONPATH=${MED_ROOT_DIR}/lib/salome:${PYTHONPATH} - export PYTHONPATH - -Example 01: Explore a med file to get information concerning meshes and fields ------------------------------------------------------------------------------- - -:objectives: This example illustrates how to get information - concerning meshes and fields from a med file, using the - MEDLoader library. - -The loading of meshes and fields from a med file to a MEDCoupling data -structure requires first the knowledge of metadata associated to these -meshes and fields. You have to know the names of the meshes, so that -you can specify the one you want to load, and then the names of the -fields associated to one given mesh, the space discretizations used -for each field, and the iterations available. - -The MEDLoader library can read these metadata without loading the -physical data that compose the meshes and fields. This feature ensures -the performance of the exploration process, in particular in the case -of big meshes. - -This first instruction looks for meshes embedded in the med file -(located by :tt:`filepath`) and returns the list of mesh names: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -.. WARNING: Note that the file path for the include directive must be - relative to this rst source file (i.e. as organized in the MED - source directory, and nevertheless the build procedure is realized - elsewhere. - -Then, you may select one of these names (or iterate on all names of -the list) and read the list of fields defined on this mesh: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T2A - :end-before: # _T2B - -A field name could identify several MEDCoupling fields, that differ by -their spatial discretization on the mesh (values on cells, values on -nodes, ...). This spatial discretization is specified by the -TypeOfField that is an integer value in this list: - -* :tt:`0 = ON_CELLS` (physical values defined by cell) -* :tt:`1 = ON_NODES` (physical values defined on nodes) -* :tt:`2 = ON_GAUSS_PT` (physical values defined on Gauss points) -* :tt:`3 = ON_GAUSS_NE` - -.. note:: This constant variables are defined by the MEDLoader module - (:tt:`from MEDLoader import ON_NODES`). - -As a consequence, before loading the physical values of a field, we -have to determine the types of spatial discretization that come with -this field name and to choose one of this types. The instruction below -read all the spatial discretization types available for the field of -name :tt:`fieldName` defined on the mesh of name :tt:`meshName`: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T3A - :end-before: # _T3B - -Once you have selected the spatial discretization of interest (called -:tt:`typeOfDiscretization` in the code below, that corresponds to an -item of the list :tt:`listOfTypes`), you can extract the list of time -iterations available for the identified field: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T4A - :end-before: # _T4B - -The iterations can be weither a list of time steps for which the field -is defined (a timeseries) or a list of frequency steps (spectral -analysis). In any case, an iteration item consists in a couple of -integers, the first defining the main iteration step and the second an -iteration order in this step, that can be consider as a sub-iteration -of the step. In most of cases, the iteration order is set to :tt:`-1` -(no sub-iterations). - -The field values can now be read for one particular time step (or -spectrum tic), defined by the pair (iteration number, iteration -order). This is illustrated by the example here after. - -Example 02: Load a mesh and a field from a med file ---------------------------------------------------- - -:objectives: This illustrates how to load the physical data of a - specified mesh and a specified field. - -The metadata read from a med file are required to identify the list of -meshes and fields in the med file. We assume in this example that the -mesh and field to load are identified, i.e. we know the name of the -mesh to load (:tt:`meshName`) and the characteristic properties of the -field to load (:tt:`fieldName`, :tt:`typeOfDiscretization` and -:tt:`iteration`). For example, the instruction below load the mesh of -name :tt:`meshName`: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T5A - :end-before: # _T5B - -and the instruction below load the field with name :tt:`fieldName` -defined on this mesh at a particular iteration step characterized by -the couple :tt:`(iterationNumber,iterationOrder)`: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T6A - :end-before: # _T6B - -The variables :tt:`mesh` and :tt:`field` in this code example are instances of -the MEDCoupling classes describing the meshes and fields. - -Note that the read functions required the parameter -:tt:`dimrestriction`. This parameter discreminates the mesh dimensions you -are interested to relatively to the maximal dimension of cells -contained in the mesh (then its value could be 0, -1, -2 or -3 -depending on the max dimension of the mesh). A value of -:tt:`dimrestriction=0` means "no restriction". - -Example 03: Manage the MEDCoupling data load from a med file ------------------------------------------------------------- - -:objectives: Some suggestions for the MEDCoupling objects management, - in a programming context. - -In a real programming case, it could be relevant to explore first the -med file to load all metadata concerning the whole set of meshes and -associated fields, and then to load the physical data only once when -required by the program. - -Such a programming scenario required that you keep all metadata in -data structures created in memory, so that you can manage the -collection of meshes and fields. Nevertheless, the MEDMEM library -does not provide such data structures. - -We suggest to work with a simple list concept to store the metadata -for each mesh entry and each field entry. Note that a mesh entry is -characterized by the mesh name only, while a field entry is -charaterized by the following attributes: - -* :tt:`fieldName`: the name of the field -* :tt:`meshName`: the name of the mesh that supports the field -* :tt:`typeOfDiscretization`: the type of spatial discretization -* :tt:`iteration`: a couple of integers :tt:`(iter,order)` that - characterizes the step in a serie (timeseries or spectrum). - -By default, we suggest to work with a simple map concept (dictionnary in a -python context, map in a C++ context) to register the meshes and -fields loaded from the med file for each metadata entry. - -Then, depending on the processing algorithm you intend to implement, -you may dispatch the data in a tree structure that fit your specific -case, for performance reasons. For example, the following code -illustrates how to dispatch the metadata in a tree data structure -where leaves are the physical data (field objects). We first have to -define a tree structure (basic definition in htis simple case, but it -works fine): - -.. include:: ../../tut/medloader/manage.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -Then, we can scan the med structure and dispatch the metadata in the -tree structure: - -.. include:: ../../tut/medloader/manage.py - :literal: - :start-after: # _T2A - :end-before: # _T2B - -Finally (and afterwards), we can display on standard output the -metadata registered in the tree structure: - -.. include:: ../../tut/medloader/manage.py - :literal: - :start-after: # _T3A - :end-before: # _T3B - -Example 04: Simple arithmetic operations with fields ----------------------------------------------------- - -:objectives: This example illustrates how to load field iterations - from a med file containing a field timeseries and shows - how to use these iterations in simple arithmetic - operations. - -We consider a med file :tt:`timeseries.med`, containing one single -mesh named :tt:`Grid_80x80` that supports a field with values defined -on nodes (:tt:`typeOfDiscretization=ON_NODES`) given for ten -iterations. - -This first code block identifies the mesh and the field to consider in -this example: - -.. include:: ../../tut/addfields/operations.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -The following instructions load the field, make a scaling on the -physical values (multiply by 3) and then save the result in an output -med file named :tt:`scaling.med`: - -.. include:: ../../tut/addfields/operations.py - :literal: - :start-after: # _T2A - :end-before: # _T2B - -Note the usage of the method :tt:`applyFunc` that takes in argument a -string expression that defined the mathematical function to apply on -the values of the fields. In this expression, the field is symbolized -by the letter :tt:`f`. - -The following set of instructions makes the addition of iteration -number 3 with iteration number 4 of the field. Note that this -operation required first to load the mesh: - -.. include:: ../../tut/addfields/operations.py - :literal: - :start-after: # _T3A - :end-before: # _T3B - -Exemple 05: Compare fields load from different files ----------------------------------------------------- - -:objectives: Illustrates the usage of the function - changeUnderlyingMesh - -Exemple 06: Create a field from scratch on a spatial domain ------------------------------------------------------------ - -:objectives: Illustrates the applyFunc method of fields - -Exemple 07: Manipulate structured mesh --------------------------------------- - -:objectives: Illustrates the basic usage of the advanced interface of - MEDLoader. - -The MEDLoader frontal interface let you load unstructured meshes: - -.. include:: ../../tut/medloader/tutorial.py - :literal: - :start-after: # _T5A - :end-before: # _T5B - -That is to say that even if the mesh is a structured mesh (a grid mesh -for example), then you will get a MEDCoupling unstructured mesh -object. - -To manipulate structured mesh objects, you have to use the MEDLoader -backend interface named :tt:`MEDFileMesh`, or its derivative -:tt:`MEDFileUMesh` for unstructured meshes, and :tt:`MEDFileCMesh` for -structured meshes (CMesh for Cartesian Mesh). The code below -illustrates how to load a mesh using the :tt:`MEDFileMesh` interface, -and to know if it is a structured mesh: - -.. include:: ../../tut/medloader/cmesh.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -This second example can be used in the case where you know in advance -that it is a structured mesh: - -.. include:: ../../tut/medloader/cmesh.py - :literal: - :start-after: # _T2A - :end-before: # _T2B - -In any cases, you can also save the mesh in another file with the -methode :tt:`write` of the :tt:`MEDFileMesh` object: - -.. include:: ../../tut/medloader/cmesh.py - :literal: - :start-after: # _T3A - :end-before: # _T3B - -Exemple 08: Make a projection of a field ----------------------------------------- - -:objectives: Make the projection of a field from a source mesh to a - target meshe. The source mesh and the target mesh are - two different mesh of the same geometry. - -The input data of this use case are: - -* a source mesh, and a field defined on this source mesh (left side of - the figure below) -* a target mesh, on which we want to project the field (right side of - the figure below) - -.. note:: The two meshes are displayed side by side on the figure for - convenience reason, but in the real use case they stand at - the same location in 3D space (they describe the same - geometry). - -.. image:: images/medop_projection_inputs.png - :align: center - -The expected result is a field defined on the target mesh and which -corresponds to a physical data equivalent to the source field, -i.e. with conservation of some physical properties. This operation -requires the usage of interpolation algorithms provided by the -:tt:`medcouplingremapper` library: - -.. include:: ../../tut/projection/demomed/demo_loadsource.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -Some comments on this code: - -* The physical property to be preserved by this interpolation is - specified using the keyword :tt:`ConservativeVolumic` -* The parameter :tt:`P0P0` given at the preparation step of the - remapper specifies that the interpolation is done from CELLS (P0) to - CELLS (P0). -* The interpolation, strictly speaking, is performed by the - instruction :tt:`ftarget = - remap.transferField(fsource,defaultValue)` -* In this instruction, the :tt:`defaultValue` is used to set the target value - in the case where there is no cell in the source mesh that overlap - the target mesh (for example when the source mesh correspond to a - geometrical sub-part of the target mesh). - -When executing the :tt:`remapper`, the result is a new field defined on -the target mesh, as illustrated on the figure below: - -.. image:: images/medop_projection_result.png - :align: center - -Exemple 09: Make a partition of a mesh using a field ----------------------------------------------------- - -:objective: This illustrates how to make a mesh partition using the - value of a field defined on this mesh. - -The input data is a MEDCoupling scalar field (:tt:`field`) defined on -a 3D mesh, and we want to use this field as a criterium to make a -partition of the mesh, for example by creating the mesh surface that -delimits the volumes where the field value is greater that a limit L -(and conversely the volumes where the field value is lower). - -.. image:: images/partition_mesh.png - :align: center - -The code below shows the simplest way to extract the cells where -:tt:`field>L` and to create the skin mesh: - -.. include:: ../../tut/medcoupling/partition.py - :literal: - :start-after: # _T1A - :end-before: # _T1B - -At the end, the variable :tt:`skin` is a 2D mesh that can be saved in -a med file using the MEDLoader: - -.. image:: images/partition_skin.png - :align: center - -Advanced usages of the MEDMEM library -===================================== - -This section could explain how to process the physical data -(dataArray) and to manipulate the advanced concepts of the MEDMEM -library. - -.. Exemple 01: Create a field from an image -.. ---------------------------------------- - diff --git a/doc/dev/sphinx/medop-userguide-gui.rst b/doc/dev/sphinx/medop-userguide-gui.rst deleted file mode 100644 index 3494402c5..000000000 --- a/doc/dev/sphinx/medop-userguide-gui.rst +++ /dev/null @@ -1,649 +0,0 @@ -.. meta:: - :keywords: mesh, field, manipulation, user guide - :author: Guillaume Boulant - -.. include:: medop-definitions.rst - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -MED module: User guide for graphical interface -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -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:: This document is self-contained, but it is strongly advised to - read :doc:`the specification document` (in - french), at least to clarify concepts and terminology. - -.. contents:: Contents - :local: - :backlinks: none - -.. 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 - -A typical use of field manipulation functions is: - -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. - - -Quick tour on functions available in MED module -=============================================== - -This section presents some use examples of MED module like a "storyboard", -illustrating the functions proposed by the module. - -.. warning:: This section is under construction. Please consider that its - contents and organization are still incomplete and may change - until this warning is removed. - -Example 1: Explore data sources -------------------------------- - -.. note:: This example illustrates the following functions: - - * add a data source - * "Extends field series" and "Visualize" functions - -.. |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 - -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 - -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 - -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 -.. |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:: 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. - -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:: This graphical representation aims at providing a quick visual - control. Scalar maps are displayed using the PARAVIS module. - -Example 2: Combine fields from different sources ------------------------------------------------- - -.. note:: This example illustrates the following functions: - - * 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 - -The objective is to access data contained in several med files, then to -combine them in the same output file. - -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 - -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 - -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 - -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: - -Example 3: Apply a formula on fields ------------------------------------- - -.. note:: This example illustrates the following functions: - - * execute mathematical operations in TUI console - * function "put" to refer to a work field in the list of persisting fields. - * function "Visualize" from TUI. - -The most common usage of field manipulation module is to execute mathematical -operations on fields or on their components. - -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). - -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:: 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 -```` is automatically created in the TUI to designate the field. In -this example, ```` 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 - -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 - -Other operations can be applied, as detailed in module specifications -(cf. :ref:`Spécification des opérations`): - - >>> 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 - >>> ... - -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 - -Scalar variables can be used if needed:: - - >>> r=4*f3-f4/1000 - >>> ... - -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) - -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 - -Second, variables can be used as command arguments (the list of commands -available in TUI is described in section :ref:`Documentation of textual -interface`). For example the function ``view`` displays -the field scalar map in the viewer:: - - >>> view(f3) - -Results in: - -.. image:: images/xmed-gui-workspace-view.png - :align: center - :width: 800px - -.. 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) - -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 #6556 : 3.5 - Tuple #6557 : 3.3 - Tuple #6558 : 1.5 - Tuple #6559 : 0.3 - Tuple #6560 : 0.2 - -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` described hereafter. - -.. _xmed.userguide.exemple4: - -Example 4: Compare fields derived from different sources --------------------------------------------------------- - -.. note:: This example illustrates the following function: - - * Change the underlying (support) mesh - -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. - -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. - -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. - -However field manipulation functions do not allow operations on fields lying -on different support meshes (see remark at the end of :ref:`example -3`). - -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 - -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 - -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:: 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()`` (dup stands for "duplicate"). - -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. - -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`:: - - >>> r=f1-f2 - >>> view(r) - -.. 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). - - -Example 5: Create a field on a spatial domain ---------------------------------------------- - -.. note:: This example illustrates the following functions: - - * initialize with function of spatial position - * initialize on a group of cells - -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. - -.. warning:: DEVELOPMENT IN PROGRESS - -Example 6: Extract a field part -------------------------------- - -.. note:: This example illustrates the following functions: - - * extract a component (or a subset of components) - * extract a geometrical domain (values on a group of cells) - * extract one or several time steps - -.. warning:: DEVELOPMENT IN PROGRESS - - 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). - -For time step extraction, we can reduce to the case of example 2 with a single -data source. - -Example 7: Create a field from a to[mp]ographic image ------------------------------------------------------ - -.. note:: This example illustrates the following function: - - * 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 - -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 - -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):: - - $ /bin/salome/xmed/image2med.py -i myimage.png -m myfield.med - -.. |ICO_IMAGESOURCE| image:: images/ico_imagesource.png - :height: 16px - -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 - -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. - -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 - -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 - -The result of loading: - -.. image:: images/medop_image2med_tomographie.png - :align: center - :width: 800px - -Example 8: Continue analysis in PARAVIS ---------------------------------------- - -.. note:: This example illustrates the following functio: - - * Export fields to PARAVIS module - -The solutions for field representation in MED module aims at proposing a quick -visual control. - -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). - -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 - -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:: 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: - -Using the textual interface (TUI) -================================= - -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:: - - $ /medop.sh - -This command opens a command console ``medop>``. A med file can be loaded and -manipulated, for example to create fields from file data. - -Whatever textual or graphical mode is used, a typical workflow in console -looks like the following instructions:: - - >>> 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") - -The main commands are: - -* ``load``: load a med file in data base (useful in pure textual mode):: - - >>> load("/path/to/datafile.med") - -* ``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``: show the list of fields available in workspace ("list") -* ``put``: put a reference to a field in *management space*:: - - >>> put(f) - -* ``save``: save to a med a file all fields referenced in management space:: - - >>> save("/path/to/resultfile.med") - -.. 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 diff --git a/doc/dev/sphinx/medop-workingnotes-2011.rst b/doc/dev/sphinx/medop-workingnotes-2011.rst index 2c38e64bb..269b63b5a 100644 --- a/doc/dev/sphinx/medop-workingnotes-2011.rst +++ b/doc/dev/sphinx/medop-workingnotes-2011.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, manipulation :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ANNEXE: Note de travail concernant le chantier XMED 2011 @@ -145,7 +145,7 @@ Nouveaux concepts à prendre en compte ------------------------------------- Au démarrage du chantier 2011, on observe que les concepts suivants -sont introduits dans le module MED: +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 @@ -469,5 +469,5 @@ Petites améliorations du DataspaceController: est posé dans le WS. On peut donc proposer en option de lui associer un alias pour manipulation dans la console - - + + diff --git a/doc/dev/sphinx/medop-workingnotes-2012.rst b/doc/dev/sphinx/medop-workingnotes-2012.rst index b6ecb6d37..4a3e10af4 100644 --- a/doc/dev/sphinx/medop-workingnotes-2012.rst +++ b/doc/dev/sphinx/medop-workingnotes-2012.rst @@ -2,7 +2,7 @@ :keywords: maillage, champ, manipulation :author: Guillaume Boulant -.. include:: medop-definitions.rst +.. include:: medcalc-definitions.rst %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ANNEXE: Note de travail concernant le chantier XMED 2012 @@ -80,5 +80,5 @@ peut procéder de la manière suivante: * 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 +.. warning:: TODO: refaire le point sur les tâches initiées en 2011