From: boulant Date: Fri, 14 Sep 2012 14:57:54 +0000 (+0000) Subject: MEDOP: add the documentation concerning the new GUI of the MED module X-Git-Tag: V6_main_FINAL~515 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=0c76a1384f7a98c114247ab5cba046470f69cd9c;p=tools%2Fmedcoupling.git MEDOP: add the documentation concerning the new GUI of the MED module --- diff --git a/doc/doxygen/figures/medlayers.png b/doc/doxygen/figures/medlayers.png new file mode 100644 index 000000000..179ae0bcf Binary files /dev/null and b/doc/doxygen/figures/medlayers.png differ diff --git a/doc/doxygen/figures/medlayers_70pc.png b/doc/doxygen/figures/medlayers_70pc.png new file mode 100644 index 000000000..f31997693 Binary files /dev/null and b/doc/doxygen/figures/medlayers_70pc.png differ diff --git a/doc/doxygen/main.dox b/doc/doxygen/main.dox index a3d73913c..a8e64c5b0 100644 --- a/doc/doxygen/main.dox +++ b/doc/doxygen/main.dox @@ -1,25 +1,65 @@ /*!\mainpage MEDMEM user's guide -\image html MED_small.png -\image latex MED_small.eps -\anchor fig_MED_small - \section intro Introduction -This document constitutes the user guide of the %MEDMEM library and of its related tools. +This document is the user guide of the %MED SALOME module. The MED +module consists in: + +- \ref S1 to manipulate meshes and fields that conform + to the MED data model. This library can be used in C++ programs as + in python script for data processing on meshes and fields. +- \ref S2 that exhibits some useful functions of the + library for a graphical manipulation of data in standard use cases. +- \ref S3 that can be used to process MED data files + +\section S1 A library of functions for data processing + +The figure below represents the layer structure of the packages of the +library: + +\image html medlayers_70pc.png + +The fondamentals consists in three atomic libraries: + +- \ref medcoupling that describes DataStructures used for cross process exchange of meshes and fields. +- \ref medloader that provides I/O functions to the MED file format +- \ref interptools (INTERP_KERNEL + REMAPPER) that provides + mathematical structures and algorithms for interpolation and + localization. + +You should be warned that the MEDMEM library still exists in the MED +module but is considered as deprecated: + +- \ref medmem covers the %MEDMEM core library, i.e. the implementation + of meshes, supports and fields and the associated drivers (for + MED-file, VTK, GIBI). + +\section S2 A graphical interface for standard use cases + +The MED module in SALOME comes with a graphical interface that helps +you to deal with most standard use case of fields manipulation. The +user guide can be found here: + +- User guide of the MED Graphical Interface + +You could also be interested to read the software specifications and +requirements for this graphical module, and even the technical +considerations for development: + +- Software + specifications and requirements of the MED Graphical Interface +- Developer guide of the MED Graphical Interface + +\section S3 A set of tools for file manipulation -\section install Installation -The install procedure of the %MEDMEM library can handle a variety of configurations -to suit the needs of its user. Instructions for configuring and installing the library can be found in \ref medmem_install. - -\section outline Outline -This user guide contains five different chapters that cover the core %MEDMEM and MEDCoupling libraries, the interpolation library and the associated tools: -- Chapter \ref medcoupling describes DataStructures used for cross -process exchange of meshes and fields. -- Chapter \ref medloader describes API for I/O from or to a MED file -coming from a \ref medcoupling data structure. -- Chapter \ref interptools describes the interpolation and localization library. -- Chapter \ref medmem covers the %MEDMEM core library, i.e. the implementation of meshes, supports and fields and the associated drivers (for MED-file, VTK, GIBI). - Chapter \ref tools describes various tools based on MEDMEM that can be helpful for handling MED files (conversion tools and splitting tools). +\section install Installation +The install procedure of the %MED SALOME module can handle a variety of configurations +to suit the needs of its user. Instructions for configuring and +installing the module an be found in \ref medmem_install. + */ diff --git a/src/MEDOP/doc/models/medop.xmi b/src/MEDOP/doc/models/medop.xmi new file mode 100644 index 000000000..01758265f --- /dev/null +++ b/src/MEDOP/doc/models/medop.xmi @@ -0,0 +1,318 @@ + + + + + umbrello uml modeller http://uml.sf.net + 1.5.8 + UnicodeUTF8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/MEDOP/doc/sphinx/Makefile.am b/src/MEDOP/doc/sphinx/Makefile.am new file mode 100644 index 000000000..415ea5a38 --- /dev/null +++ b/src/MEDOP/doc/sphinx/Makefile.am @@ -0,0 +1,121 @@ +# Copyright (C) 2007-2012 CEA/DEN, EDF R&D, OPEN CASCADE +# +# 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. +# +# 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 +# + +# author: Guillaume Boulant (EDF/R&D, 2012) + +include $(top_srcdir)/adm_local/unix/make_common_starter.am + +tuidocdir = $(docdir)/tui/MED +devdocdir = $(docdir)/dev/MED +medopdocdir=$(devdocdir) + +.PHONY : latex + +if SPHINX_IS_OK + +medopdoc_DATA=html/index.html +html/index.html:$(RSTFILES) + make htm + +endif + +EXTRA_DIST += html + +SPHINXOPTS = +SOURCEDIR = $(srcdir) +SPHINXBUILD = sphinx-build +PAPEROPT_a4 = -D latex_paper_size=a4 +ALLSPHINXOPTS = -d doctrees $(PAPEROPT_a4) $(SPHINXOPTS) $(SOURCEDIR) +SPHINX_PYTHONPATH = $(prefix)/lib/python$(PYTHON_VERSION)/site-packages/salome:$(KERNEL_ROOT_DIR)/lib/python$(PYTHON_VERSION)/site-packages/salome:$(KERNEL_ROOT_DIR)/bin/salome:$(OMNIORB_ROOT)/lib/python$(PYTHON_VERSION)/site-packages + +SPHINX_LD_LIBRARY_PATH = $(OMNIORB_ROOT)/lib + +htm: + mkdir -p html doctrees + PYTHONPATH=$(SPHINX_PYTHONPATH):${PYTHONPATH}; \ + LD_LIBRARY_PATH=$(SPHINX_LD_LIBRARY_PATH):${LD_LIBRARY_PATH}; \ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) html + @echo + @echo "Build finished. The HTML pages are in html." + +latex: + mkdir -p latex doctrees + PYTHONPATH=$(SPHINX_PYTHONPATH):${PYTHONPATH}; \ + LD_LIBRARY_PATH=$(SPHINX_LD_LIBRARY_PATH):${LD_LIBRARY_PATH}; \ + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) latex + @echo + @echo "Build finished; the LaTeX files are in latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +html: + mkdir -p $@ + +RSTFILES= \ + index.rst \ + xmed-specifications.rst \ + xmed-develguide.rst \ + xmed-userguide.rst + +# Files on the development of the prototype (version 2010) +RSTFILES+=\ + xmed-prototype-overview.rst \ + xmed-prototype-develguide.rst \ + xmed-prototype-medmem.rst + +# Files containing definitions and references +RSTFILES+=\ + xmed-definitions.rst \ + xmed-references.rst \ + xmed-workingnotes-2010.rst \ + xmed-workingnotes-2011.rst \ + xmed-workingnotes-2012.rst + +# Files on annexe topics +RSTFILES+=\ + salomedoc.rst + +EXTRA_DIST+= $(RSTFILES) + +EXTRA_DIST+= \ + conf.py + +install-data-local: + $(INSTALL) -d $(DESTDIR)$(medopdocdir) + if test -d "html"; then b=; else b="$(srcdir)/"; fi; \ + cp -rf $$b"html"/* $(DESTDIR)$(medopdocdir) ; \ + if test -f $$b"latex"/medopdoc.pdf; then cp -f $$b"latex"/medopdoc.pdf $(DESTDIR)$(medopdocdir) ; fi; + +uninstall-local: + chmod -R +w $(DESTDIR)$(medopdocdir) + rm -rf $(DESTDIR)$(medopdocdir)/* + +clean-local: + -rm -rf html latex doctrees + if test -d "html"; then rm -rf html ; fi + +pdf: latex + cd latex; make all-pdf + cp latex/*.pdf html/_static/documents/. + +WIKIRELATIVEPATH="pub/userdata/gboulant/data/salome/smodules/xmed/doc" +WIKIREMOTEPATH="nepal@nepal:/nepal/$(WIKIRELATIVEPATH)" +deploy: htm pdf + rsync -avz html/ $(WIKIREMOTEPATH) + @echo "The documentation can be read at URL : http://nepal.der.edf.fr/$(WIKIRELATIVEPATH)/index.html" diff --git a/src/MEDOP/doc/sphinx/_static/documents/20070105_CEA_VBERGEAUD_GuideutilisateurMEDMEMOIRE.pdf b/src/MEDOP/doc/sphinx/_static/documents/20070105_CEA_VBERGEAUD_GuideutilisateurMEDMEMOIRE.pdf new file mode 100755 index 000000000..405a2ccd0 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20070105_CEA_VBERGEAUD_GuideutilisateurMEDMEMOIRE.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20091211_CEA_AGEAY_09-017-RT-A_Normalisation_des_champs_et_des_maillages_pour_le_couplage_de_codes.pdf b/src/MEDOP/doc/sphinx/_static/documents/20091211_CEA_AGEAY_09-017-RT-A_Normalisation_des_champs_et_des_maillages_pour_le_couplage_de_codes.pdf new file mode 100755 index 000000000..2357da079 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20091211_CEA_AGEAY_09-017-RT-A_Normalisation_des_champs_et_des_maillages_pour_le_couplage_de_codes.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20091218_EDF_VCANO_H-I2C-2009-03595-FR.pdf b/src/MEDOP/doc/sphinx/_static/documents/20091218_EDF_VCANO_H-I2C-2009-03595-FR.pdf new file mode 100755 index 000000000..25a151e63 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20091218_EDF_VCANO_H-I2C-2009-03595-FR.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20100129_MAN_seminaireEDF-CEA_all.pdf b/src/MEDOP/doc/sphinx/_static/documents/20100129_MAN_seminaireEDF-CEA_all.pdf new file mode 100755 index 000000000..8048e0bad Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20100129_MAN_seminaireEDF-CEA_all.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20101027_MAN_revueEDF-CEA.pdf b/src/MEDOP/doc/sphinx/_static/documents/20101027_MAN_revueEDF-CEA.pdf new file mode 100755 index 000000000..f5f91231f Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20101027_MAN_revueEDF-CEA.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_notes.pdf b/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_notes.pdf new file mode 100644 index 000000000..aee46bf25 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_notes.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_remarques_ELORENTZ.pdf b/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_remarques_ELORENTZ.pdf new file mode 100644 index 000000000..dce10d93a Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20110309_XMED_scan_remarques_ELORENTZ.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/documents/20110310_seminaireEDF-CEA_maquetteXMED.pdf b/src/MEDOP/doc/sphinx/_static/documents/20110310_seminaireEDF-CEA_maquetteXMED.pdf new file mode 100755 index 000000000..2ea491817 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/documents/20110310_seminaireEDF-CEA_maquetteXMED.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_manipulation_de_champs.pdf b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_manipulation_de_champs.pdf new file mode 100644 index 000000000..9a129300b Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_manipulation_de_champs.pdf differ diff --git a/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_1.ogv b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_1.ogv new file mode 100644 index 000000000..8339d6333 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_1.ogv differ diff --git a/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_3.ogv b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_3.ogv new file mode 100644 index 000000000..ec7c90a92 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_3.ogv differ diff --git a/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_4.ogv b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_4.ogv new file mode 100644 index 000000000..7398d19a9 Binary files /dev/null and b/src/MEDOP/doc/sphinx/_static/presentations/20111115_JUS-2011/20111115_JUS2011_medop_exemple_4.ogv differ diff --git a/src/MEDOP/doc/sphinx/_static/xmed.css b/src/MEDOP/doc/sphinx/_static/xmed.css new file mode 100644 index 000000000..150d01914 --- /dev/null +++ b/src/MEDOP/doc/sphinx/_static/xmed.css @@ -0,0 +1,115 @@ +@import url("default.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; +} diff --git a/src/MEDOP/doc/sphinx/conf.py.in b/src/MEDOP/doc/sphinx/conf.py.in new file mode 100644 index 000000000..7e0e46546 --- /dev/null +++ b/src/MEDOP/doc/sphinx/conf.py.in @@ -0,0 +1,209 @@ +# -*- coding: iso-8859-1 -*- +# +# yacs documentation build configuration file, created by +# sphinx-quickstart on Fri Aug 29 09:57:25 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc'] + +# Uncomment the following line to build the links with Python documentation +# (you might need to set http_proxy environment variable for this to work) +#extensions += ['sphinx.ext.intersphinx'] + +# Intersphinx mapping to add links to modules and objects in the Python +# standard library documentation +intersphinx_mapping = {'http://docs.python.org': None} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'MED, Manipulation de champs dans SALOME' +copyright = '2010 EDF R&D' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '@VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@VERSION@' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'fr' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['.build','ref','images','CVS','.svn'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +#html_theme = 'omadoc' +html_theme_options = { + "stickysidebar": "false", + "rightsidebar": "false", +} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = ['themes'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + + +# 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 = 'xmed.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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_use_modindex = False + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/. +html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'xmeddoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +latex_paper_size = 'a4' + +# The font size ('10pt', '11pt' or '12pt'). +latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'xmed-alldoc.tex', 'Documentation du module XMED', 'G. Boulant', 'manual'), + ('xmed-specifications', 'xmed-specifications.tex', 'Module XMED - Specifications', 'G. Boulant', 'manual'), + ('xmed-develguide', 'xmed-develguide.tex', 'Module XMED - Guide de developpement', 'G. Boulant', 'manual'), + ('xmed-userguide', 'xmed-userguide.tex', 'Module XMED - Guide d\'utilisation', 'G. Boulant', 'manual') +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +latex_use_modindex = False diff --git a/src/MEDOP/doc/sphinx/images/champ_altitude_MAP.png b/src/MEDOP/doc/sphinx/images/champ_altitude_MAP.png new file mode 100644 index 000000000..0fbf2ba0d Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/champ_altitude_MAP.png differ diff --git a/src/MEDOP/doc/sphinx/images/convert.sh b/src/MEDOP/doc/sphinx/images/convert.sh new file mode 100755 index 000000000..289e7c377 --- /dev/null +++ b/src/MEDOP/doc/sphinx/images/convert.sh @@ -0,0 +1,16 @@ +#!/bin/sh +factor="50%" +listfiles="\ + medop-gui-aliasfield.png \ + medop-gui-result.png \ + medop-gui-selectfield.png \ + medop-gui-visufield.png" + +for file in $listfiles; do + echo "Processing file $file ..." + bn=$(basename $file .png) + outfile=$bn"_scale.png" + convert -scale $factor $file $outfile +done + + diff --git a/src/MEDOP/doc/sphinx/images/ico_datasource_add.png b/src/MEDOP/doc/sphinx/images/ico_datasource_add.png new file mode 100644 index 000000000..bcec3d6c7 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_datasource_add.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_datasource_changeUnderlyingMesh.png b/src/MEDOP/doc/sphinx/images/ico_datasource_changeUnderlyingMesh.png new file mode 100644 index 000000000..fe6c8b6d3 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_datasource_changeUnderlyingMesh.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_datasource_expandfield.png b/src/MEDOP/doc/sphinx/images/ico_datasource_expandfield.png new file mode 100644 index 000000000..07c8b0b10 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_datasource_expandfield.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_datasource_use.png b/src/MEDOP/doc/sphinx/images/ico_datasource_use.png new file mode 100644 index 000000000..0d1ab6326 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_datasource_use.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_datasource_view.png b/src/MEDOP/doc/sphinx/images/ico_datasource_view.png new file mode 100644 index 000000000..418914405 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_datasource_view.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_imagesource.png b/src/MEDOP/doc/sphinx/images/ico_imagesource.png new file mode 100644 index 000000000..465b156e4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_imagesource.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_workspace_save.png b/src/MEDOP/doc/sphinx/images/ico_workspace_save.png new file mode 100644 index 000000000..268c8fb7b Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_workspace_save.png differ diff --git a/src/MEDOP/doc/sphinx/images/ico_xmed.png b/src/MEDOP/doc/sphinx/images/ico_xmed.png new file mode 100644 index 000000000..4f09fe03d Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/ico_xmed.png differ diff --git a/src/MEDOP/doc/sphinx/images/med-uml-main.png b/src/MEDOP/doc/sphinx/images/med-uml-main.png new file mode 100755 index 000000000..1e7d458cc Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/med-uml-main.png differ diff --git a/src/MEDOP/doc/sphinx/images/med-uml-main_60pc.png b/src/MEDOP/doc/sphinx/images/med-uml-main_60pc.png new file mode 100644 index 000000000..f8f06cb55 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/med-uml-main_60pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/medlayers.png b/src/MEDOP/doc/sphinx/images/medlayers.png new file mode 100644 index 000000000..179ae0bcf Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medlayers.png differ diff --git a/src/MEDOP/doc/sphinx/images/medmem-corba-layers.png b/src/MEDOP/doc/sphinx/images/medmem-corba-layers.png new file mode 100755 index 000000000..de355e983 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medmem-corba-layers.png differ diff --git a/src/MEDOP/doc/sphinx/images/medmem-layers.png b/src/MEDOP/doc/sphinx/images/medmem-layers.png new file mode 100644 index 000000000..d781003a6 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medmem-layers.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield.png b/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield.png new file mode 100755 index 000000000..ad266f822 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield_scale.png b/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield_scale.png new file mode 100644 index 000000000..33a5caeb9 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-aliasfield_scale.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-result.png b/src/MEDOP/doc/sphinx/images/medop-gui-result.png new file mode 100755 index 000000000..54a41bfed Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-result.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-result_scale.png b/src/MEDOP/doc/sphinx/images/medop-gui-result_scale.png new file mode 100644 index 000000000..a53187bd4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-result_scale.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-selectfield.png b/src/MEDOP/doc/sphinx/images/medop-gui-selectfield.png new file mode 100755 index 000000000..47d5d61a4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-selectfield.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-selectfield_scale.png b/src/MEDOP/doc/sphinx/images/medop-gui-selectfield_scale.png new file mode 100644 index 000000000..e311926f6 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-selectfield_scale.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-visufield.png b/src/MEDOP/doc/sphinx/images/medop-gui-visufield.png new file mode 100755 index 000000000..fc4262722 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-visufield.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop-gui-visufield_scale.png b/src/MEDOP/doc/sphinx/images/medop-gui-visufield_scale.png new file mode 100644 index 000000000..6cbe393c9 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop-gui-visufield_scale.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop_exportparavis.png b/src/MEDOP/doc/sphinx/images/medop_exportparavis.png new file mode 100644 index 000000000..4205c6ba6 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop_exportparavis.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop_exportparavis_result.png b/src/MEDOP/doc/sphinx/images/medop_exportparavis_result.png new file mode 100644 index 000000000..56abc6ee3 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop_exportparavis_result.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop_image2med_dialog.png b/src/MEDOP/doc/sphinx/images/medop_image2med_dialog.png new file mode 100644 index 000000000..35cf57b39 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop_image2med_dialog.png differ diff --git a/src/MEDOP/doc/sphinx/images/medop_image2med_tomographie.png b/src/MEDOP/doc/sphinx/images/medop_image2med_tomographie.png new file mode 100644 index 000000000..9f67fbc0c Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/medop_image2med_tomographie.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-architecture.png b/src/MEDOP/doc/sphinx/images/xmed-architecture.png new file mode 100755 index 000000000..143b674f7 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-architecture.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-exploremed.png b/src/MEDOP/doc/sphinx/images/xmed-exploremed.png new file mode 100644 index 000000000..c9e0283aa Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-exploremed.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-functions.png b/src/MEDOP/doc/sphinx/images/xmed-functions.png new file mode 100644 index 000000000..b0e67b8ef Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-functions.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh.png new file mode 100644 index 000000000..c62da6a19 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png new file mode 100644 index 000000000..bccd8c258 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-changeUnderlyingMesh_wsview.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu.png new file mode 100644 index 000000000..a8df311ca Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_60pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_60pc.png new file mode 100644 index 000000000..5492fa1cc Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_60pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_70pc.png new file mode 100644 index 000000000..5db5a11d8 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_80pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_80pc.png new file mode 100644 index 000000000..48ed01162 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-contextmenu_80pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-expand-zoom.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-expand-zoom.png new file mode 100644 index 000000000..b4891fd84 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-expand-zoom.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore-zoom.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore-zoom.png new file mode 100644 index 000000000..2de39c77f Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore-zoom.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore.png new file mode 100644 index 000000000..8bb9bbd68 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-explore.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-menucontextuel-zoom.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-menucontextuel-zoom.png new file mode 100644 index 000000000..85ea5d5cc Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-menucontextuel-zoom.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-selectfile.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-selectfile.png new file mode 100644 index 000000000..39da53302 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-selectfile.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-alias.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-alias.png new file mode 100644 index 000000000..f6eca45e0 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-alias.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result.png new file mode 100644 index 000000000..505e3d6ad Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result_70pc.png new file mode 100644 index 000000000..f942cd84b Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace-result_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace.png new file mode 100644 index 000000000..1f7109f63 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace_70pc.png new file mode 100644 index 000000000..98e1f324c Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-useinworkspace_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result.png new file mode 100644 index 000000000..b0f4243d4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_50pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_50pc.png new file mode 100644 index 000000000..f86b7b021 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_50pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_70pc.png new file mode 100644 index 000000000..6bf6817a5 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-result_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-zoom.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-zoom.png new file mode 100644 index 000000000..e556b1011 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize-zoom.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize.png new file mode 100644 index 000000000..94fa549d6 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_50pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_50pc.png new file mode 100644 index 000000000..a96aefc10 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_50pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_70pc.png new file mode 100644 index 000000000..1f0599e77 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-datasource-visualize_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-start.png b/src/MEDOP/doc/sphinx/images/xmed-gui-start.png new file mode 100644 index 000000000..8a0a5931f Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-start.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png b/src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png new file mode 100644 index 000000000..532c285e6 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-withframe.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-workspace-view.png b/src/MEDOP/doc/sphinx/images/xmed-gui-workspace-view.png new file mode 100644 index 000000000..f501f6cf1 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-workspace-view.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui-workspace.png b/src/MEDOP/doc/sphinx/images/xmed-gui-workspace.png new file mode 100644 index 000000000..081b8333f Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui-workspace.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui.png b/src/MEDOP/doc/sphinx/images/xmed-gui.png new file mode 100644 index 000000000..0c9168374 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-gui_70pc.png b/src/MEDOP/doc/sphinx/images/xmed-gui_70pc.png new file mode 100644 index 000000000..6d1845c61 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-gui_70pc.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-implantation.png b/src/MEDOP/doc/sphinx/images/xmed-implantation.png new file mode 100644 index 000000000..0f17dcce4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-implantation.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-irm-diff.png b/src/MEDOP/doc/sphinx/images/xmed-irm-diff.png new file mode 100644 index 000000000..44d557884 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-irm-diff.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-irm-field.png b/src/MEDOP/doc/sphinx/images/xmed-irm-field.png new file mode 100644 index 000000000..1012ab1ea Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-irm-field.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-irm.png b/src/MEDOP/doc/sphinx/images/xmed-irm.png new file mode 100644 index 000000000..5d20c7ed1 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-irm.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-datasource.png b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-datasource.png new file mode 100644 index 000000000..4e67ab118 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-datasource.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace-save.png b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace-save.png new file mode 100644 index 000000000..9d10513c9 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace-save.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace.png b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace.png new file mode 100644 index 000000000..3138f7a08 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-userguide-example2-workspace.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-visu-importtimestamps.png b/src/MEDOP/doc/sphinx/images/xmed-visu-importtimestamps.png new file mode 100644 index 000000000..b685eccbd Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-visu-importtimestamps.png differ diff --git a/src/MEDOP/doc/sphinx/images/xmed-visu-scalarmaptimestamps.png b/src/MEDOP/doc/sphinx/images/xmed-visu-scalarmaptimestamps.png new file mode 100644 index 000000000..1cda69ba4 Binary files /dev/null and b/src/MEDOP/doc/sphinx/images/xmed-visu-scalarmaptimestamps.png differ diff --git a/src/MEDOP/doc/sphinx/index.rst b/src/MEDOP/doc/sphinx/index.rst new file mode 100644 index 000000000..90fdc6b46 --- /dev/null +++ b/src/MEDOP/doc/sphinx/index.rst @@ -0,0 +1,44 @@ + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + Documentation du module XMED +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Le module SALOME nommé XMED (pour eXtension MED) est l'espace de +développement des fonctions de manipulation de champs dans SALOME. Le +contenu de ce module est amené à intégrer le module MED pour former la +future version en préparation pour la version SALOME 7 de 2012. + +Documentation principale +======================== + +.. toctree:: + :maxdepth: 1 + + xmed-specifications.rst + xmed-develguide.rst + xmed-userguide.rst + +Documentation du prototype 2010 +=============================== + +Cette section décrit le prototype mis au point en 2010 pour les +analyses de conception (maquette 2010 sur base MEDMEM) + +.. toctree:: + :maxdepth: 1 + + xmed-prototype-overview.rst + xmed-prototype-develguide.rst + xmed-prototype-medmem.rst + +Documentation annexe +==================== + +.. toctree:: + :maxdepth: 1 + + xmed-references.rst + xmed-workingnotes-2010.rst + xmed-workingnotes-2011.rst + xmed-workingnotes-2012.rst + salomedoc.rst diff --git a/src/MEDOP/doc/sphinx/salomedoc.rst b/src/MEDOP/doc/sphinx/salomedoc.rst new file mode 100644 index 000000000..fc2f1fdc8 --- /dev/null +++ b/src/MEDOP/doc/sphinx/salomedoc.rst @@ -0,0 +1,231 @@ +.. meta:: + :keywords: SALOME, development + :author: Guillaume Boulant + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Annexe : Règles de développement SALOME +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Cette annexe est un recueil de techniques de développement spécifiques +à l'environnement SALOME et utilisées pour la mise au point du module +XMED. Elles sont a priori utilisables pour d'autres contexte de +développement dans SALOME. + +.. TODO: récupérer les fonctions génériques de VisuGUI_Tools.cxx +.. TODO: récupérer les fonctions génériques de SMESGGUI_utils.cxx + +.. contents:: Sommaire + :local: + :backlinks: none + +Récupérer la sélection dans l'arbre d'étude +=========================================== + +Dans une classe dérivée de ``SalomeApp_Module``, on peut utiliser un +code de la forme suivante: + +.. code-block:: cpp + + #include + #include + #include + #include + + // ... + + // Get the selected object in the study (SObject) + LightApp_SelectionMgr* aSelectionMgr = this->getApp()->selectionMgr(); + SALOME_ListIO aListIO; + aSelectionMgr->selectedObjects(aListIO); + + // Analyse the selection. There can be more than one item. + SALOME_ListIteratorOfListIO It (aListIO); + for (; It.More(); It.Next()) { + Handle(SALOME_InteractiveObject) anIO = It.Value(); + SALOMEDS::SObject_var aSObject = aStudy->FindObjectID(anIO->getEntry()); + + // Check if the selected object is relevant for the operation + // ... + + // Process the SObject if it's relevant + // ... + + } + +On peut noter qu'une variable ``aStudy`` est requise. Elle représente +l'étude SALOME sur laquelle s'oppère la sélection. L'étude active +(impliquée dans la sélection) peut être obtenue au moyen du +gestionnaire d'étude (voir :ref:`ci-dessous `). + +Réglage du curseur graphique +============================ + +Dans le cas où le traitement est long, il peut être intéressant +d'encadrer l'opération par un vérouillage du curseur de sélection: + +.. code-block:: cpp + + QApplication::setOverrideCursor(Qt::WaitCursor); + + // Do the job + // ... + + QApplication::restoreOverrideCursor(); + + +Les variables pour la gestion de l'étude +======================================== + +Les variables CORBA +------------------- + +Les variables CORBA comme le serveur de noms (naming service) et le +gestionnaire de cycle de vie des objets (LifeCycleCRORBA) sont +fréquement utilisés. Dans le contexte d'une application (classe de +type ``SalomeApp_Module``), il est possible de récupérer simplement +des instances de ces variables par les commandes suivantes: + +.. code-block:: cpp + + #include + #include + + CORBA::ORB_var orb = SalomeApp_Application::orb(); + SALOMEDSClient_StudyManager* studyMgr = SalomeApp_Application::studyMgr(); + SALOME_NamingService* namingService = SalomeApp_Application::namingService(); + SALOME_LifeCycleCORBA* lcc = SalomeApp_Application::lcc(); + +Pour un usage en dehors de l'application graphique (par exemple au +niveau du container), l'orb peut être obtenu par les mécanismes +standard d'omniORB: + +.. code-block:: cpp + + CORBA::ORB_var orb = CORBA::ORB_init(0,0); + +L'orb est par exemple utile à récupérer pour la sérialisation des +objets CORBA et la manipulation des références sous forme de chaîne de +caractères: + +.. code-block:: cpp + + // 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 + QString medIOR = orb->object_to_string(medObj); + + SALOME_MED::MED_ptr anOtherRefToMedObj = orb->string_to_object(medIOR) + +.. note: this serialization can be used to communicate between a GUI + and a component in a container, or between the C++ context and the + python context. + +.. _salomedoc_getActiveStudy: + +Récupérer l'étude active +------------------------ + +Le concept d'étude active est un concept GUI. Il désigne l'étude en +cours d'usage au niveau de l'interface graphique. + +.. note: Pour rappel, l'étude est un objet CORBA de type + ``SALOMEDS::Study`` qui héberge physiquement les ``SObject`` + pointant vers les données. L'arbre d'étude ("Object browser") est + une représentation graphique de cet objet. + +L'étude active peut être obtenue au moyen du gestionnaire +d'étude. Dans le corps d'une classe de type ``SalomeApp_Module``, ceci +peut se faire par un code de la forme suivante: + +.. code-block:: cpp + + #include "SALOMEconfig.h" + #include CORBA_SERVER_HEADER(SALOMEDS) + #include + #include + + // ... + + // Get the study id of the active study + SalomeApp_Study* appStudy = dynamic_cast (this->getApp()->activeStudy()); + _PTR(Study) aCStudy = appStudy->studyDS(); + int aStudyID = aCStudy->StudyId(); + + // Then get the study manager + SALOME_NamingService *aNamingService = SalomeApp_Application::namingService(); + CORBA::Object_var anObject = aNamingService->Resolve("/myStudyManager"); + SALOMEDS::StudyManager_var aStudyManager = SALOMEDS::StudyManager::_narrow(anObject); + + // Finally, request the study manager for the study (SALOMEDS::Study) + SALOMEDS::Study_var aStudy = aStudyManager->GetStudyByID(aStudyID); + + +Communiquer avec la console python +================================== + +La console python désigne l'interpréteur embarqué dans l'interface +graphique de SALOME (GUI). Elle est également désignée comme +l'interface textuelle de SALOME (TUI) car elle permet de piloter +SALOME au moyen de commandes en syntaxe python. + +Le paragraphe montre comment communiquer avec cette interface texte +depuis le contexte C++ de l'interface graphique, en particulier pour +déclencher l'exécution de commandes. + +Le code se situe donc au sein d'une classe de type +``SalomeApp_Module`` (de laquelle hérite la partie graphique d'un +module SALOME, de nom ``GUI``). Cette classe possède une +méthode ``getApp()`` par laquelle on peut récupérer une instance de la +console python embarquée (this->getApp()->pythonConsole()). + +Le code suivant illustre l'envoie d'une commande python par ce +mécanisme. Dans cette exemple, on défini une variable ``id`` dans la +console python comme l'identifiant de l'étude active: + +.. code-block:: cpp + + #include + #include + #include + + PyConsole_Console * pyConsole = getApp()->pythonConsole(); + + QStringList commands; + commands+="import salome"; + commands+="id=salome.myStudyId"; + + QStringListIterator it(commands); + while (it.hasNext()) { + pyConsole->exec(it.next()); + } + +Dans ce deuxième exemple, on cherche à reconstituer dans le contexte +de la console python un pointer vers un objet med instancié dans le +contexte C++ de l'application graphique. Pour cela, on communique la +référence de l'objet sous la forme sérialisé (IOR pour un objet +CORBA): + +.. code-block:: cpp + + #include + #include + #include + #include + + // We suppose here that we have a CORBA object reference (object of + // type *_ptr or *_var), for example a SALOME_MED::MED object. + SALOME_MED::MED_ptr medObj = ... // anything to get this object + + // Get the IOR of this object + QString medIOR = SalomeApp_Application::orb()->object_to_string(medObj); + + PyConsole_Console * pyConsole = getApp()->pythonConsole(); + + QStringList commands; + commands+="import salome"; + commands+=QString("med=salome.orb.string_to_object(\"%1\")").arg(medIOR); + + QStringListIterator it(commands); + while (it.hasNext()) { + pyConsole->exec(it.next()); + } diff --git a/src/MEDOP/doc/sphinx/xmed-definitions.rst b/src/MEDOP/doc/sphinx/xmed-definitions.rst new file mode 100644 index 000000000..cfd0bc148 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-definitions.rst @@ -0,0 +1,88 @@ +.. 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 diff --git a/src/MEDOP/doc/sphinx/xmed-develguide.rst b/src/MEDOP/doc/sphinx/xmed-develguide.rst new file mode 100644 index 000000000..be5d72bab --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-develguide.rst @@ -0,0 +1,239 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med, développement + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Module XMED: Guide de développement +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +(|XMED_DEVELGUIDE_PDF|_) + +Ce document est la documentation technique du module XMED. Il fournit +les instructions à suivre pour installer le module en vue d'un travail +de développement, puis décrit les éléments de conception qui +structurent le module. + +.. contents:: Sommaire + :local: + :backlinks: none + +.. warning:: Ce document 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. + +Mise en place d'un espace de développement +========================================== + +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 + +Exécution des tests unitaires +----------------------------- + +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/lib/python2.6/site-packages/salome/xmed/test_medoperation.py + +L'exécution imprime un rapport détaillant le résultat pour chaque +fonction de test:: + + test_addition (__main__.MyTestSuite) ... ok + test_arithmetics (__main__.MyTestSuite) ... ok + test_composition (__main__.MyTestSuite) ... FAIL + test_litteral_equation (__main__.MyTestSuite) ... ok + test_modification_of_attributes (__main__.MyTestSuite) ... ok + test_unary_operations (__main__.MyTestSuite) ... ok + test_update_metadata (__main__.MyTestSuite) ... ok + +Les scripts de test sont: + +* ``test_medoperation.py``: tests des operations de champs telles + qu'elles sont mises en oeuvre depuis l'interface textuelle. +* ``test_xmed.py``: tests des composants CORBA mis en oeuvre + (``MEDDataManager`` et ``MEDCalculator``) + +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: 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. diff --git a/src/MEDOP/doc/sphinx/xmed-prototype-develguide.rst b/src/MEDOP/doc/sphinx/xmed-prototype-develguide.rst new file mode 100644 index 000000000..de2387b74 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-prototype-develguide.rst @@ -0,0 +1,731 @@ +.. meta:: + :keywords: maillage, champ, manipulation, XMED + :author: Guillaume Boulant + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Démonstrateur XMED, documentation technique +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Cette note fait la synthèse des développements effectués pour le +maquettage des fonctions de manipulation de champs dans SALOME. Elle +présente les principes retenus en matière de conception, c'est-à-dire +concernant les mécanismes techniques sous-jacents, et en matière +d'ergonomie, c'est-à-dire concernant les modalités d'utilisation dans +l'environnement SALOME. + +Ces principes sont illustrés par des développements implantés dans le +module XMED, développé pour les besoins de l'analyse, et dans le +module MED distribué avec la plateforme SALOME. + +.. note:: la lecture de ce chapitre demande une connaissance de la + structure de classes du module MED, en particulier la distinction + entre les classes ``MEDMEM::*`` et les servants CORBA associés + (classe ``SALOME_MED::*``). + +.. contents:: Sommaire + :local: + :backlinks: none + +Principes directeurs +==================== + +Objectif et motivation +---------------------- + +L'objectif de maquettage est de trouver une architecture technique qui +permet d'exécuter le cas d'utilisation suivant: + +* Chargement d'un fichier med dans SALOME (a priori dans le module MED) +* Sélection graphique des champs de l'étude à mettre à disposition + dans la console utilisateur ("calculette" en mode texte qui + concraitement correspond à l'interface python de SALOME). +* Dans la calculette, exécution d'opérations algébriques (+,-,*,/) + entre champs avec possibilité d'utiliser des scalaires dans des + opérations de type transformation linéaire (y=ax+b ou y et x sont + des champs et a et b des scalaires). Opérations pow, sqrt. +* Possibilité de visualiser les champs produits avec VISU pour + contrôle des résultats. +* Possibilité d'exporter des champs produits dans un fichier med. + +Eléments de contexte +-------------------- + +Les opérations de manipulation de champs sont en grande partie +implémentées dans la bibliothèque MEDMEM. Pour illustration, le +fragment de code ci-dessous montre comment une addition de champ peut +être opérée en python: + +.. code-block:: python + + from libMEDMEM_Swig import MedDataManager + from xmed.helper import readMed, writeMed + + # Load the medmem data structure from a med file + med = readMed("/tmp/input.med") + # Then create a med data manager to deal with the fields data + dm = MedDataManager(med) + # Get the timestamps (dt,it)=(-1,-1) of the fields "testfield1" and "testfield2" + f1 = dm.getFieldDouble("testfield1",-1,-1) + f2 = dm.getFieldDouble("testfield2",-1,-1) + + # Create a new field as the sum of f1 and f2 + r = f1 + f2 + # And add this new field to the med data structure + med.addField(r) + + # Finally, write the whole data in an output med file + writeMed(med,"/tmp/output.med") + +Ceci montre que les champs peuvent être manipulés avec une interface +relativement ergonomique (une addition de deux champs f1 et f2 s'écrit +f1+f2) tant que l'on manoeuvre des objets MEDMEM purs (classes C++ du +package MEDMEM et wrapping python du package MEDMEM_SWIG). + +Par ailleurs, le fonctionnement actuel des modules SALOME qui +manoeuvrent des données MED est d'instancier les structures de données +MEDMEM au niveau de la partie serveur, c'est-à-dire au niveau des +servants CORBA hébergés dans le processus ``SALOME_Container``, et de +donner accés à ces données depuis l'étude SALOME au travers de +pointeurs CORBA. Ce choix d'architecture présente l'avantage de +centraliser au niveau serveur la gestion du cycle de vie des données +informatiques et de pouvoir distribuer des "poignées" pour manipuler +ces données depuis chaque point de l'application qui sait accéder au +bus CORBA, l'interface graphique en particulier. + + +Hypothèse de travail +-------------------- + +Compte-tenu de l'objectif de maquettage et des éléments de contexte +existant, on cherche une solution dans le cadre des hypothèses +de travail suivantes: + +* La manipulation des champs se fait dans l'environement graphique de + SALOME. +* Dans cet environnement, on souhaite pouvoir sélectionner + graphiquement les champs à considérer, puis manipuler ces champs + dans l'interface texte au moyen de variables python avec une syntaxe + aussi simple que celle définie dans le wrapping python de MEDMEM, + c'est-à-dire que pour faire l'addition de 2 champs f1 et f2, on veut + pouvoir écrire f1+f2. +* Les données MED sont physiquement dans la partie serveur de SALOME + et accessibles via des pointeurs CORBA (interface spécifiée dans + MED.idl). On exclu la recopie de données au niveau du client + graphique. + +Dans le cadre de ces hypothèses, la difficulté technique réside dans +la mise au point d'une interface de communication entre des variables +manipulées par l'utilisateur dans l'interface graphique (c'est-à-dire +dans le processus ``SALOME_SessionServer``) et des objets MEDMEM +instanciés dans le containeur des servants CORBA (c'est-à-dire dans le +processus ``SALOME_Container``). + + +Eléments de conception +====================== + + +Implantation technique +---------------------- + +Le diagramme ci-dessous représente l'organisation des principaux +paquets logiciels du module MED: + +.. image:: images/medmem-layers.png + :align: center + +Les cadres bleus représentent le lieu d'implantation des +développements effectués dans le module MED pour les besoins du +maquettage. On notera en particulier les interventions aux niveaux +suivants: + +* interfaces idl: ajout de l'interface MEDOP.idl +* package MEDMEM_I: ajout du servant SALOME_MED::MEDOP qui implémente + l'interface MEDOP.idl + +Architecture technique +---------------------- + +Les schéma ci-dessous représente les objets informatiques qui sont à +l'oeuvre pour la réalisation des opérations sur les champs: + +.. image:: /images/xmed-architecture.png + :align: center + :alt: Objets mis en oeuvre dans l'interface de manipulation de champs + +On distingue les objets suivants: + +* Une instance de ``MEDMEM::MED``, correspondant à la structure de donnée + MED chargée en mémoire. +* Des instances de ``MEDMEM::FIELD`` qui représentent les champs med + chargés en mémoire. +* Une instances de ``SALOME_MED::MED`` et des instances de + ``SALOME_MED::FIELD`` qui sont les servants CORBA respectivement de la + structure med et des champs qui lui sont associés et chargés en + mémoire. +* Une instance de ``SALOME_MED::MEDOP`` qui est le servant CORBA qui + centralise la mise en oeuvre des opérations de champs sur le serveur + ``SALOME_Container``. Le servant MEDOP détient en attribut une référence + sur la structure ``MEDMEM::MED``, ce qui lui permet d'accéder + directement aux champs ``MEDMEM::FIELD`` à partir de leur nom et du pas + de temps. +* Des instances de ``FieldProxy`` qui correspondent aux variables + manipulées au niveau de l'interface graphique et qui représentent + les champs. Une instance de FieldProxy possède détient les + références des servants ``SALOME_MED::MEDOP`` et + ``SALOME_MED::FIELD`` sous la forme de pointeurs CORBA de noms + ``medop_ptr`` et ``field_ptr`` respectivement. +* Il existe également une instance de ``MedProxy`` non représentée + dans ce diagramme. Cette instance correspond à une variable qui + permet de manipuler la structure med. + +.. note:: Les éléments apportés par la maquette sont les classes + ``SALOME_MED::MEDOP``, ``MedProxy`` et ``FieldProxy``. Les autres + éléments ont pu être modifiés légèrement pour les besoins de + l'intégration ou pour la correction de quelques bugs. + +Le cycle de vie de ces objets est le suivant. + +Pour ce qui concerne les instances de la structure ``MEDMEM::MED`` et +des champs ``MEDMEM::FIELD``, la création est faite au moment du +chargement du fichier med dans SALOME au moyen du module MED. A cette +occasion, les servants CORBA associés ``SALOME_MED::MED`` et +``SALOME_MED::FIELD`` sont créés et des références vers ces servants +sont publiés dans l'étude. Ils peuvent donc être sélectionnés par +l'utilisateur dans l'interface graphique. L'ensemble de ces données +préexiste à la manipulation de champs. + +Les objets ``SALOME_MED::MEDOP`` sont instanciés au sein du servant +``SALOME_MED::MED`` auquel ils sont associées. Le servant +``SALOME_MED::MED`` possède une référence sur la structure +``MEDMEM::MED`` et il la transmet à l'instance du servant +``SALOME_MED::MEDOP`` qu'il construit. L'opérateur MEDOP est donc +autonome par la suite pour manipuler les données MED, et les champs en +particulier. Le code python ci-dessous montre comment un opérateur med +``SALOME_MED::MEDOP`` peut être créé puis utilisé pour réaliser +l'addition de deux champs: + +.. code-block:: python + + import salome + salome.salome_init() + import SALOME_MED + + medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + medObj = medComp.readStructFile("myfile.med",salome.myStudyName) + medOp = medObj.createMedOperator() + + f1 = medObj.getField("testfield1",-1,-1) + f2 = medObj.getField("testfield2",-1,-1) + + somme = medOp.add(f1,f2) + +Il est à noter qu'une instance de ``SALOME_MED::MEDOP`` est associé à +une instance unique de ``SALOME_MED::MED`` (et donc indirectement de +``MEDMED::MED``) pour toute la durée de son cycle de vie. Par contre, +un servant ``SALOME_MED::MED`` peut être associé à plusieurs servants +``SALOME_MED::MEDOP`` différents. Un servant ``SALOME_MED::MEDOP`` a +une référence directe sur la structure ``MEDMEM::MED`` et peut la +manoeuvrer pour demander des champs, faire des opérations avec ces +champs, ajouter le champs résultat à la structure et enfin retourner +un servant ``SALOME_MED::FIELD`` qui encapsule le champ résultat. + +Enfin, quelques éléments concernant la classe ``FieldProxy``. Une +instance de ``FieldProxy`` est un objet python qui peut être +manoeuvrée dans l'interpréteur SALOME et qui référence un champ MED +localisé sur le serveur ``SALOME_Container`` (par le mécanisme décrit +ci-dessus). C'est à ce niveau qu'on règle les détails d'ergonomie +d'usage (cf. paragraphe ci-après). La création d'un objet +``FieldProxy`` déclenche la création d'un opérateur med (instance de +``SALOME_MED::MEDOP``) qui lui est associé et dont il conserve la +référence CORBA en attribut (noté ``medop_ptr`` sur le diagramme). Cet +opérateur ``medop_ptr`` peut être requêter pour exécuter toutes les +opérations possibles sur ce champ, comme illustrer sur l'exemple +ci-dessus. + + +Rôle des objets proxy +--------------------- + +Dans le modèle d'architecture présenté ci-dessus, on introduit deux +types d'objets proxy: + +* Les objets de classe ``FieldProxy`` qui représentent des poignées de + manipulation des champs ``MEDMEM::FIELD`` physiquement instanciés + dans le container SALOME. +* Les objets de classe ``MedProxy`` qui représentent des poignées de + manipulation des structures ``MEDMEM::MED`` physiquement instanciées + dans le container SALOME. + +Elles sont instanciées dans l'interpréteur python SALOME pour +manipulation dans l'interface textuelle à partir de la donnée du +pointeur vers le servant ``SALOME_MED::MED`` et de l'identifiant du +champ (le nom du champ et le pas de temps défini par le numéro d'ordre +et le numéro d'iteration: + +.. code-block:: python + + import salome + salome.salome_init() + import SALOME_MED + + medComp = salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + medObj = medComp.readStructFile("myfile.med",salome.myStudyName) + + from xmed import fieldproxy + from xmed import medproxy + + f1 = fieldproxy.getFieldFromMed(medObj, "testfield1", -1, -1) + f2 = fieldproxy.getFieldFromMed(medObj, "testfield2", -1, -1) + + field_somme = f1 + f2 + field_offset = f1 + 5.3 + +Dans cet exemple, les variables ``f1``, ``f2``, ``field_somme`` et +``field_offset`` sont des objets de classe ``FieldProxy``. Ils +correspondent aux variables physiquement manipulées par +l'utilisateur pour désigner les champs dans les opérations. + +Ces classes proxy sont conçues pour être le lieu d'implémentation de +l'interprétation des commandes utilisateur et donc de l'ergonomie +de manipulation des champs au niveau l'interface textuelle. Ce point +est développé :ref:`plus bas `. + +Programmation de l'interface textuelle +-------------------------------------- + +Dans le cadre de la maquette, l'interface de manipulation des champs +est l'interface textuelle python intégrée à SALOME. Dans la pratique, +l'utilisateur manipule des variables python qui correspondent à des +objets de classe ``FieldProxy`` équipées des fonctions requises et de +l'ergonomie nécessaire à la mise en oeuvre des opérations (voir +ci-dessus). + +Or, l'hypothèse de travail est que les données MED sont chargées dans +SALOME et publiées dans l'étude pour point d'accés depuis l'interface +graphique. L'utilisateur choisi un champs directement dans l'arbre +d'étude (ou dans une interface graphique dédiée) puis demande qu'il +soit mis à disposition dans l'interface python sous un nom de variable +à choisir. Les captures d'écran ci-dessous montre la séquence +graphique en images: + +.. |IMG_SELECT| image:: images/medop-gui-selectfield_scale.png +.. |IMG_ALIAS| image:: images/medop-gui-aliasfield_scale.png + ++---------------+---------------+ +| |IMG_SELECT| | |IMG_ALIAS| | ++---------------+---------------+ + +L'image de gauche montre la sélection du pas de temps, l'image de +droite la boîte de dialogue qui permet la saisie de l'alias avec +lequel le champs sera manipulé dans l'interface textuelle. La +validation de cette fenêtre doit mettre automatiquement le champ à +disposition dans l'interface python SALOME et sous le nom de variable +spécifié par l'alias saisi. + +Pour cela, il y a un couplage technique à programmer entre l'interface +graphique et l'interface textuelle python, avec en particulier la +transmission des pointeurs vers les servants CORBA mis en jeu dans la +sélection. + +Ce couplage est implanté au niveau de la classe MEDGUI.cxx du module +MED (où de la classe XMEDGUI.cxx du module XMED pour la maquette) qui +implémente l'interface graphique du module. Pour rappel, l'interface +graphique d'un module SALOME se présente sous la forme d'une classe +centrale de nom ``GUI`` et qui spécialise la classe +``SalomeApp_Module``. Cette classe possède une méthode ``getApp()`` +par laquelle on peut récupérer une instance de la console python +embarquée (this->getApp()->pythonConsole()). + +Le code suivant illustre l'envoie d'une commande python par ce +mécanisme. Dans cet example, on cherche à reconstituer dans le +contexte de la console python un pointer vers un objet med instancié +dans le contexte C++ de l'application graphique. Pour cela, on +communique la référence de l'objet sous la forme sérialisé (IOR pour +un objet CORBA): + +.. code-block:: cpp + + #include + #include + #include + #include + + // We suppose here that we have a CORBA object reference (object of + // type *_ptr or *_var), for example a SALOME_MED::MED object. + SALOME_MED::MED_ptr medObj = ... // anything to get this object + + // Get the IOR of this object + QString medIOR = SalomeApp_Application::orb()->object_to_string(medObj); + + PyConsole_Console * pyConsole = getApp()->pythonConsole(); + + QStringList commands; + commands+="import salome"; + commands+=QString("med=salome.orb.string_to_object(\"%1\")").arg(medIOR); + + QStringListIterator it(commands); + while (it.hasNext()) { + pyConsole->exec(it.next()); + } + +Le code réel de la maquette est basé sur ce principe et transmet à la +console python des lignes de commandes qui permettent de reconstruire: + +* un pointeur CORBA vers le servant ``SALOME_MED::MED`` associé au + champ sélectionné; +* une instance de ``FieldProxy`` qui correspond au champ sélectionné + et avec pour nom de variable la valeur de l'alias saisi dans + l'interface graphique. + +Au niveau du code C++ de la classe ``XMEDGUI.cxx``, cela se traduit +par la fabrication de la liste de commandes suivante pour envoie à la +console python par le mécanisme illustré plus haut: + +.. code-block:: cpp + + QStringList commands; + commands+="from xmed.fieldproxy import getFieldFromMed"; + commands+="from xmed.medproxy import getMedProxy"; + commands+=QString("if not dir().__contains__('med'): med = getMedProxy(\"%1\")").arg(medIOR); + commands+=QString("%1=getFieldFromMed(med,\"%3\",%4,%5)").arg(*alias).arg(fieldName).arg(orderIndex).arg(iterationIndex); + +Les variables ``medIOR``, ``fieldName``, ``orderIndex`` et +``iterationIndex`` sont construites à partir du champ sélectionné par +des techniques de programmation standard dans SALOME qu'on peut +examiner en détail dans la classe ``XMEDGUI`` (voir méthode +``XMEDGUI::LoadIntoPythonConsole()``). La variable ``alias`` est la +chaîne saisie par l'utilisateur dans la fenêtre de dialogue. + +Le point important à noter ici est que les données à transmettre +doivent être fournies sous forme de chaînes de caractères ou de types +simples. C'est pourquoi la référence au servant CORBA +``SALOME_MED::MED`` est transmise ici sous la forme de son IOR, +c'est-à-dire une chaîne de caractères qui permet l'identification de +l'objet au niveau du bus CORBA. + +Au niveau de la console python cela correspond à l'exécution des +commandes suivantes: + +.. code-block:: python + + from xmed.fieldproxy import getFieldFromMed + from xmed.medproxy import getMedProxy + + med = getMedProxy("IOR:010000001700000049444c3a53414c4f4d455f4d45442f4d45443a312e300000010000000000000064000000010102000e0000003133302e39382e37372e313733009e0a0e000000feadc4ca4c00003169000000001100000200000000000000080000000100000000545441010000001c00000001000000010001000100000001000105090101000100000009010100") + + f1=getFieldFromMed(med,"testfield1",-1,-1) + +Ce jeu d'instructions reconstitue un pointeur vers le servant CORBA +``SALOME_MED::MED`` à partir de son identifiant IOR (voir la fonction +``getMedProxy(...)``, puis crée une instance de ``FieldProxy`` +associée à ce servant (en fait associée au servant +``SALOME_MED::MEDOP`` créé sur demande par le servant +``SALOME_MED::MED``, voir la fonction ``getFieldFromMed(...)``). + +.. _develguide_execFieldOperation: + +Exécution des opérations sur le champs +-------------------------------------- + +Les variables définies dans l'interface textuelle pour désigner les +champs à manipuler sont des objets de classe ``FieldProxy``. + +Cette classe a une propriété remarquable, elle est construite sur un +design pattern de type "Proxy" qui pointe vers un servant +``SALOME_MED::FIELD``. Cela signifie que l'on ne peut pas accéder +directement au servant vers lequel il pointe, mais que l'on passe +systématiquement par une procédure de l'objet proxy qui fait "boîte +aux lettres": + +.. code-block:: python + + class FieldProxy: + + def __getattr__( self, name ): + """ + This method realizes the proxy pattern toward the servant + SALOME_MED::FIELD. + """ + return getattr( self.__field_ptr, name ) + +Ce pattern permet l'implémentation de pré-traitement et/ou de +post-traitement suivant le type d'accés que l'on cherche à faire. + +Il permet aussi et surtout de fournir un objet python qui présente +l'interface de ``SALOME_MED::FIELD`` dotée d'extentions adhoc pour les +operations de champs. Ici, python est ton ami, car il s'agit pour cela +d'équiper la classe ``FieldProxy`` des automatismes prévus nativement +par python pour les operations entre objets. En particulier, la +re-définition des fonctions internes ``__add__`` (opérateur addition), +``__sub__`` (opérateur soustraction), ``__mul__`` (opérateur +multiplication) et ``__div__`` (opérateur division) au sein de la +classe ``FieldProxy``, permet de prendre la main sur le comportement +des opérations algébriques et de définir une ergonomie sur mesure. Par +exemple, la méthode ``__add__`` peut gérer les variantes "f1+f2" +(ajout de deux variables de type FieldProxy) et "f1+5.3" (ajout d'un +réel à une variable de type FieldProxy): + +.. code-block:: python + + class FieldProxy: + + def __add__(self, operande): + """ + This can process the addition of two fields or the addition of + a scalar to a field. It depends weither the operande is a + FieldProxy or a simple scalar numerical value. + """ + if isinstance(operande, FieldProxy): + # The operande is an other field + otherField_ptr = operande.__field_ptr + rfield_ptr = self.__medOp_ptr.add(self.__field_ptr, otherField_ptr) + else: + # The operande is a scalar numerical value that must be + # considered as an offset in a linear transformation + factor = 1 + offset = operande + rfield_ptr = self.__medOp_ptr.lin(self.__field_ptr, factor, offset) + return FieldProxy(self.__med_ptr, rfield_ptr) + +Il est à noter que dans les deux cas de figure (opérande=champ ou +opérande=scalaire), la fonction délègue la réalisation concrète de +l'opération au servant ``SALOME_MED::MEDOP`` (identifié ici par +l'attribut ``self.__medOp_ptr`` et que l'on appelera l'*opérateur +MEDOP* dans la suite pour simplifier), mais n'appelle pas le même +service de calcul (l'addition entre champs dans le premier cas, +l'application d'une transformation linéaire de type y=factor*x+offset +dans le deuxième cas). + +Pour couvrir le cas des opérations algébriques, l'opérateur MEDOP +présentre l'interface suivante (cf. fichier ``MEDOP.idl`` qui définie +l'interface du servant ``SALOME_MED_MEDOP``): + +.. code-block:: cpp + + /*! Addition of the fields f1 and f2 ( f1+f2) */ + FIELD add(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception); + /*! Substraction of the fields f1 and f2 (f1-f2) */ + FIELD sub(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception); + /*! Multiplication of the fields f1 by f2 (f1*f2) */ + FIELD mul(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception); + /*! Division of the fields f1 by f2 (f1/f2) */ + FIELD div(in FIELD f1, in FIELD f2) raises (SALOME::SALOME_Exception); + /*! Power of the field f (f^power) */ + FIELD pow(in FIELD f, in long power) raises (SALOME::SALOME_Exception); + /*! Linear transformation of the field f (factor*f+offset) */ + FIELD lin(in FIELD f, in double factor, in double offset) raises (SALOME::SALOME_Exception); + /*! Dublication of the field f */ + FIELD dup(in FIELD f) raises (SALOME::SALOME_Exception); + +Cette interface est implémentée dans la classe C++ ``MEDOP_i`` du +module MED (voir fichier ``MEDMEM_MedOp_i.hxx`` du package +``MEDMEM_I``). C'est au sein des instances de cette classe que sont +réalisées les opérations et que sont produites physiquement les +données. Typiquement, les opérations présentées ici produisent un +champ ``MEDMEM::FIELD`` sur la base duquel elle fabrique un servant +``SALOME_MED::FIELD`` pour finalement retourner un pointeur CORBA sur +ce servant. + +Ce mécanisme global peut être étendu sans limitation à tout les types +d'opération qui sont envisagés dans les spécifications de manipulation +des champs dans SALOME. + + +Contrôle visuel des champs +-------------------------- + +Les illustrations ci-dessous montrent qu'une fonction de visalisation +est implémentée dans la maquette pour permettre le contrôle visuel +d'un champ au moyen d'une représentation 3D (une carte spatiale du +module du champ dans l'exemple implémenté par défaut): + +.. |IMG_VISU| image:: images/medop-gui-visufield_scale.png +.. |IMG_RESULT| image:: images/medop-gui-result_scale.png + ++---------------+---------------+ +| |IMG_VISU| | |IMG_RESULT| | ++---------------+---------------+ + +Cette fonction répond au besoin de contrôle interactif des résultats +produits par les opérations de manipulation de champs. + +Il s'agit là d'un usage classique de SALOME, dans lequel on demande au +module VISU de faire une représentation 3D d'un champ spécifié par la +donnée du servant ``SALOME_MED::FIELD`` qui lui est associé +(représenté par la variable ``field_ptr`` dans l'exemple ci-dessous): + +.. code-block:: python + + import salome + import VISU + + visuComp = salome.lcc.FindOrLoadComponent("FactoryServer", "VISU") + visuComp.SetCurrentStudy(salome.myStudy) + + # Then we can import the specified field in the VISU module. This + # creates an study entry in the VISU folder. + result = visuComp.ImportMedField(field_ptr) + + meshName = field_ptr.getSupport().getMesh().getName() + fieldName = field_ptr.getName() + iterNumber = field_ptr.getIterationNumber() + scalarmap = visuComp.ScalarMapOnField(result, + meshName, + visuEntityType, + fieldName, + iterNumber) + +Dans ce jeu d'instructions donné pour exemple (non fonctionnel, en +particulier à cause de la non définition de la variable +``visuEntityType``, voir remarque plus bas), le composant VISU +désigné ici par la variable ``visuComp`` va chercher les données du +champ en interrogeant le servant ``SALOME_MED::FIELD`` transmis en +argument de la fonction ``ImportMedField``, puis produit une +représentation de type "scalarmap". + +.. note:: Compte-tenu des propriétés de la classe FieldProxy décrites + plus haut conférées par le pattern "Proxy", on peut transmettre ici + aussi bien le servant CORBA que l'instance du proxy (la fonction + ``ImportMedField`` n'y verra que du feu). + +Le code complet et fonctionnel de la fonction d'affichage est dans le +corps du module python ``fieldproxy.py`` sous la forme d'une fonction +de nom ``visuField``. Il convient de noter que cette fonction doit +établir une correspondance entre le type des entités tel que défini +dans MED et dans VISU: + +.. code-block:: python + + medEntityType = field_ptr.getSupport().getEntity() + if (medEntityType == SALOME_MED.MED_CELL): + visuEntityType = VISU.CELL + elif (medEntityType == SALOME_MED.MED_NODE): + visuEntityType = VISU.NODE + + +Export des résultats de calcul +------------------------------ + +Tous les champs produits à l'occasion des opérations entre objets +``FieldProxy`` sont automatiquement ajoutés à la structure med à +laquelle is sont associés. Une convention d'attribution des noms est +implémentée de sorte que par défaut aucune précision n'est demandée à +l'utilisateur. + +La structure med peut être manipulée au moyen de la variable ``med`` +créée dans l'interface textuelle comme une instance de la classe +``MedProxy``. La classe ``MedProxy`` fournit un objet qui présente +l'interface du servant ``SALOME_MED::MED`` étendue de quelques +fonctions utilitaires pour la gestion et le contrôle des données. + +En particulier, la sauvegarde de la structure dans un fichier est +automatisée par la méthode ``save(medfilename)``: + +.. code-block:: python + + med = medproxy.MedProxy(medObj) + med.save("/tmp/output.med") + +Cette méthode s'occupe de définir un driver d'écriture et de procéder +à l'enregistrement des données de la structure med (les maillages, les +champs présents au départ et tous les champs produits depuis la +lecture initiale). + +Limitations +=========== + +L'implémentation de la maquette limite l'usage des opérations aux cas +de figure suivants: + +* Seules les operations entre champs qui partagent le même support med + sont possibles. Ceci est une contrainte imposé par la conception + actuelle de MEDMEM. +* Le résultat d'une opérations est calculé sur toutes les composantes + et tout le domaine de définition des champs en opérande. Cette + deuxième contrainte est juste parce que les usages plus fin, + notemment avec la notion de domaine de définition, n'a pas encore + été exéminée à ce jour. +* Le nom d'un champ produit par une opération ne correspond pas au nom + de la variable python par laquelle on le réceptionne et on le + manipule. Le nom est attribué par une convention (ceci n'est pas + vraiment une limitation mais une caractéristique à connaître). + +On note également les restriction techniques suivantes: + +* Les données MEDMEM sont supposées être chargées par le composant MED + puis référencées dans l'étude SALOME (comme c'est fait aujourd'hui + par le module MED). +* Dans certain cas, python n'est pas ton ami. Pour que les opérateur + de la classe ``FieldProxy`` soient pris en considération dans les + opérations sur les champs, il est indispensable que le premier + opérande d'une opération unitaire soit un champ (objet de classe + ``FieldProxy``). Par exemple: "field_offset = field + 5.3" + fonctionne alors que "field_offset = 5.3 + field" ne fonctionne pas + car python tente de traiter la situation au moyen de la fonction + ``__add__`` de la classe ``float`` (qui n'est pas modifiable). + + +Notice informatique +=================== + +Gestion de configuration +------------------------ + +Les développements décrits dans ce chapitre sont répartis entre les +modules MED et XMED (développé pour l'occasion). Cette séparation est +faite par soucis de clarté et d'efficacité de développement, mais les +éléménts du module XMED ont vocation à intégrer le module MED dans la +mesure où les propositions techniques sont retenues pour le +développement à venir. + +Le code source du module XMED peut être récupérés par la commande +suivante:: + + $ svn co svn://nepal.der.edf.fr/FIELD/XMED_SRC/trunk XMED_SRC + +Le pré-requis est la plate-forme SALOME version 5.1.4 (ou plus) +équipée au minimum des modules KERNEL, GUI, MED (branche BR_medop) et +VISU. Pour récupérer la branche BR_medop du module MED, taper la +commande:: + + $ cvs -d :pserver:anonymous@cvs.opencascade.com:2401/home/server/cvs/MED co -r BR_medop MED_SRC + +La configuration de référence est: + +* XMED: révision svn 41 +* MED: tag cvs BR_medop_20101025 + +Moyens de tests +--------------- + +Plusieurs types de tests unitaires sont définis (reste à les +automatiser proprement): + +* Test des servants et utilitaires de manipulation python: + + - Dans XMED, package xmed/tests, utiliser le script + ``test_medoperation.py`` dans un interpréteur python lancé dans + une session shell SALOME. Ce script prépare des variables de test + et fournit des fonctions de test unitaire (à exécuter ou pour s'en + inspirer). Après avoir lancé SALOME via une application virtuelle, + on peut taper:: + + $ /runSession + [NS=venus:2810] $ python -i test_medoperation.py + >>> + + - Ceci permet de tester en particulier l'interface ``MedOp`` et son + utilisation dans le module python ``fieldproxy.py``. + +* Test des classes MEDMEM: + + - Test de MEDMEM::MedDataManager dans ``MEDMEM_MedDataManager_test.cxx`` + +Un fichier de test basique (mais néanmoins suffisant) de nom +``tesfield.med`` est fourni avec les sources dans le répertoire +``/resources/datafiles`` et dans l'installation au niveau du +répertoire ``/share/salome/resources/xmed/datadir``. Il +contient deux champs ``testfield1`` et ``testfield2`` définis sur un +pas de temps unique (dt,it=-1,-1). Ces champs définissent des valeurs +par éléments (MED_CELL). diff --git a/src/MEDOP/doc/sphinx/xmed-prototype-medmem.rst b/src/MEDOP/doc/sphinx/xmed-prototype-medmem.rst new file mode 100644 index 000000000..da331c05e --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-prototype-medmem.rst @@ -0,0 +1,513 @@ +.. meta:: + :keywords: maillage, champ, MED, MEDMEM + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Note de travail concernant l'utilisation de MEDMEM +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Le module MED de SALOME comporte plusieurs composants d'intérêt pour +la manipulation de champs: + +* la bibliothèque MEDMEM qui fournit une interface de programmation + pour manoeuvrer une structure MED +* le module CORBA SALOME_MED qui matérialise le composant SALOME + (serveur corba) du module MED +* l'interopérabilité avec le module VISU qui permet la visualisation + des champs manipulés dans MED + +Les sections ci-après donnent quelques éclairages techniques sur ces +différents aspects. Les sources de démonstration peuvent être +récupérés depuis le dépôt svn:: + + $ svn export svn://nepal.der.edf.fr/OM/manifield/trunk manifield + $ svn export svn://nepal.der.edf.fr/FIELD/demofield/trunk demofield + +.. contents:: Sommaire + :local: + :backlinks: none + +Présentation synthétique de MED +=============================== + +MED désigne un modèle conceptuel pour décrire des données de type +éléments finis (éléments finis, volumes finis et éléments +discrets). Dans l'usage courant, il permet la description et l'échange +des données de calcul de type maillages et champs. La documentation +complète peut être trouvée à l'URL suivantes: + +* |LINK_EDF_MEDDOC|_ (version 2.3). + +On distingue deux implémentations informatiques de ce modèle: + +* MED fichier: qui permet la lecture et l'écriture de données depuis + un fichier au format med. Les opérations de lecture/écriture sont + atomiques (pas de chargement de la structure de données globale). +* MED mémoire (noté MEDMEM): qui permet le chargement en mémoire d'une + image de la structure de données MED contenue dans un fichier au + format med. Les opérations peuvent être atomiques ou + globales. + +On notera simplement ici que MEDMEM utilise MED fichier pour les +opérations de lecture/écriture et que MED fichier est indépendant de +MED mémoire. La documentation complète de MED fichier peut être +trouvée à l'URL suivante: + +* |LINK_EDF_MEDFICHIERDOC|_ + +La bibliothèque MEDMEM +====================== + +Le modèle de classes MEDMEM est structuré autour des notions de MESH +(les maillages), de SUPPORT (le profil des entités) et de FIELD (les +champs). Ces notions reprennent en partie des concepts du modèle +MED. Le diagramme ci-dessous présente les classes principales: + +.. image:: images/med-uml-main_60pc.png + :align: center + +Le conteneur de plus haut niveau dans MEDMEM est la classe MED. La +figure ci-dessous indique qu'une instance MED peut être associée à +plusieurs maillage et plusieurs champs. Par contre un champ donné ne +peut être associé qu'à un seul maillage (par l'intermédiaire du +support). Plusieurs champs peuvent être associés au même maillage. La +forme la plus courante est d'ailleurs une instance composé d'un +maillage unique sur lequel sont définis plusieurs champs. + +On peut avoir également des configurations plus complexes, comme par +exemple un maillage unique, plusieurs champs définis sur ce maillage +mais avec des supports différents, par exemple parce que les valeurs +sont définies sur des entités de maillage différentes (les éléments +pour un champ, les noeuds pour un autre, ...):: + + field1->support1->mesh + field2->support2->mesh + field3->support3->mesh + +On observe: + +* 2 champs U et V doivent avoir le même support (au sens informatique + du terme) pour pouvoir être en argument d'une opération (sinon + exception). Il faudrait accepter qu'il soit informatiquement + différent et vérifier la conformité conceptuelle. +* Cette contrainte peut se comprendre car physiquement les données + sont stockées dans un vecteur qui couvre toutes les mailles. Le + support est le seul masque de lecture pour établir la correspondance + avec les positions dans le maillage et il est donc important qu'une + cohérence soit assurée. + +Les objets champs (FIELD) et maillage (MESH) +-------------------------------------------- + +Un objet MED permet d'accéder aux différentes informations concernant +les objets MESH, SUPPORT et FIELD, mais il ne permet pas d'accéder aux +données physiques associées à ces objets (les valeurs des composantes +pour les champs, les mailles et leur connectivité pour les +maillages). L'accès aux données physiques est du ressort des objets +spécifiques MESH, SUPPORT et FIELD. + +Un objet MED peut être créé intégralement en mémoire. L'usage plus +fréquent est de l'initialiser à partir de la donnée d'un fichier +med. Pour cela, l'objet MED doit être associé à un driver +d'entrée/sortie branché sur le fichier (``testfilename`` dans +l'exemple): + +.. code-block:: cpp + + MED *myMed = new MED; + MED_MED_RDONLY_DRIVER *driverIn = new MED_MED_RDONLY_DRIVER(testfilename, myMed); + driverIn->open(); + driverIn->readFileStruct(); + driverIn->close(); + +A l'occasion de la fonction readFileStruct, la structure interne de +l'objet MED est enrichie des informations concernant les objets MESH, +SUPPORT et FIELD contenu dans le fichier. En particulier un +dictionnaire des champs (variable map interne) est initialisé est +contient l'ensemble des objets ``FIELD_`` préchargés (i.e. avec les +méta-données uniquement). Chaque objet ``FIELD_`` ainsi préchargé est +autonome pour être chargé sur demande. On peut alors requêter l'objet +MED pour obtenir un champ particulier (spécifié par son nom +``fieldname`` dans l'exemple): + +.. code-block:: cpp + + FIELD *field = (FIELD *)myMed->getField(fieldname, dt, it); + +Puis le champ qui lui est associé doit être physiquement chargé pour +permettre la mise à jour du support: + +.. code-block:: cpp + + MESH * mesh = myMed->getMesh(field); + mesh->read(); + myMed->updateSupport(); + +Pour enfin charger les valeurs des composantes du champ: + +.. code-block:: cpp + + field->read(); + +La numérotation des éléments de maillage +---------------------------------------- + +Les éléments qui composent un maillage sont caractérisés par: + +* Le type d'entité de l'élément, à choisir dans la liste + ``MED_EN::medEntityMesh``, qui contient en particulier ``MED_NODE``, + ``MED_FACE``, ``MED_CELL``. +* Le type de géométrie de l'élément, à choisir dans la liste + ``MED_EN::medGeometryElement``, qui contient en particulier + ``MED_NONE``, ``MED_TRIA3``, ..., ``MED_ALL_ELEMENTS``. + +Les éléments sont numérotés par un indice relatif à la catégorie +géométrique à laquelle ils appartiennent. Ainsi, si le modèle est +composé de Na arrêtes et Nf faces de type géométrique MED_QUAD4, alors +ces faces sont numérotées de 1 à Nf dans le modèle MED (et de manière +persistente dans le fichier med). De même, les arrêtes sont numérotées +de 1 à Na. Une numérotion globale implicite existe sur les éléments, +elle consiste à parcourir l'ensemble des types géométriques dans +l'ordre de définition du modèle de données. Ainsi, si le modèle +contient uniquement les Na arrêtes et les Nf faces, alors l'indice +global de la première face est Na+1. + +.. note:: Des exemples de code sont disponibles dans le package ``demofield``, fichier ``python/pybasicfields/MEDMEM_tester.py``. + + +Binding python de MEDMEM +------------------------ + +Les classes du package ``MEDMEM`` (package du module ``MED`` qui +implémentent les structures de données C++ de MED mémoire) produisent +la bibliothèque ``libmedmem.so``. Cette ensemble de classes est en +partie mis à disposition de l'interface python grace à une couche de +liaison (binding Python-C++) générée par le logiciel SWIG à partir +d'un fichier de description d'interface ``libMEDMEM_Swig.i`` (dans le +package source ``MEDMEM_SWIG``). + +Ce fichier d'interface doit être mis à jour dés lors qu'une évolution +des interfaces publiques des classes C++ MEDMEM est faite ou qu'une +nouvelle classe est créée (du moins si l'on souhaite profiter de ces +évolutions dans l'interface python). + +Cette mise à jour nécessite de prendre soin au transfert des +structures de données entre les espaces python et C++. En particulier, +l'utilisation des template de classe pour décrire les champs typés en +C++ appelle une précaution de codage particulière de l'interface +SWIG. + +Pour exemple, le fragment de code ci-dessous, extrait du fichier +``libMEDMEM_Swig.i``, montre comment déclarer la nouvelle classe +``MedDataManager`` dans l'interface: + +.. code-block:: cpp + + #include "MEDMEM_MedDataManager.hxx" + + class MedDataManager + { + public: + ~MedDataManager(); + void printFieldDouble(FIELD * field); + + %extend { + MedDataManager(char * fileName) + { + return new MedDataManager(string(fileName)); + } + MedDataManager(MED * med) + { + return new MedDataManager(med); + } + + %newobject getFieldDouble(const char * fieldName, const int dt, const int it); + FIELD * getFieldDouble(const char * fieldName, const int dt, const int it) + { + return (FIELD *) self->getFieldDouble(string(fieldName), dt, it); + } + } + + }; + + +Utilisation de MEDMEM pour la manipulation de champs +---------------------------------------------------- + +Des opérations de manipulation de champs sont disponibles dans la +bibliothèque MEDMEM standard est peuvent être utilisées dans +l'interface python. Les quelques lignes suivantes illustrent l'usage +qu'on peut en faire pour exécuter l'addition de deux champs sur tout +leur espace de définition et pour un pas de temps donné: + +.. code-block:: python + + from libMEDMEM_Swig import MedDataManager + from xmed.helper import readMed, writeMed + + # Load the medmem data structure from a med file + med = readMed("/tmp/input.med") + # Then create a med data manager to deal with the fields data + dm = MedDataManager(med) + # Get the timestamps (dt,it)=(-1,-1) of the fields "testfield1" and "testfield2" + f1 = dm.getFieldDouble("testfield1",-1,-1) + f2 = dm.getFieldDouble("testfield2",-1,-1) + + # Create a new field as the sum of f1 and f2 + r = f1 + f2 + # And add this new field to the med data structure + med.addField(r) + + # Finally, write the whole data in an output med file + writeMed(med,"/tmp/output.med") + +.. note:: Cet exemple de code requiert les évolutions de MEDMEM + opérées dans la branche BR_medop (pour disposer de la classe + MedDataManager en particulier) et le package python ``xmed`` qui + fournit quelques fonctions utilitaires pour manoeuvrer les données + med (ce package est dans le module XMED et sera probablement à + terme intégré au module MED). + +Des limitations existent aujourd'hui pour ce type de manipulations: + +* les champs doivent partager le même support MED, c'est-à-dire être + décrit sur le même maillage et sur les mêmes entités de ce + maillage. +* ... + + +Remarque sur l'implémentation C++ +--------------------------------- + +A noter l'usage de plusieurs formes d'arguments pour les fonctions: + +* passage des arguments par valeur ``myfunction(A a);`` +* passage des arguments par référence ``myfunction(A& a);`` +* passage des arguments par pointeur ``myfunction(A* a);`` + +Le passage des arguments par référence est une facilité d'écriture +pour éviter de passer un pointeur tout en évitant la récopie des +données de la variable. + +.. _xmed-medmem_corbainterface: + +L'interface CORBA SALOME_MED +============================ + +Implémentation du composant MED et des servants SALOME_MED::\* +-------------------------------------------------------------- + +Le composant MED est un servant CORBA qui permet la manipulation de +données MEDMEM dans l'environnement SALOME. Le composant peut fournir +des pointeurs vers des instances de l'interface SALOME_MED (objets +SALOMEMED::MED, SALOME_MED_FIELD, ...). Ces instances sont des +servants CORBA qui résident dans le container et qui encapsulent les +données MEDMEM. + +Le schéma ci-dessous représente les éléments informatiques qui +composent l'architecture CORBA du module MED: + +.. image:: images/medmem-corba-layers.png + :align: center + +Les structures MEDMEM (données physiques) et SALOME_MED (wrapping +CORBA) fonctionnent différement en ce qui concerne le chargement des +données: + +* Dans MEDMEM, les données sont chargées à la demande (fonctions read + des objets) et aucune gestion n'est assurée. En particulier l'appel + à read alors que la donnée est déjà chargée conduit à une levée + d'exception. C'est à l'utilisateur de MEDMEM de prendre en charge ce + type de gestion. +* Dans SALOME_MED, les données sont chargées à la création de + l'instance SALOME_MED::MED. Les maillages ainsi que les champs et + leurs données sont chargés à ce moment là et gérés dans une table de + type HashMap au niveau de la structure SALOME_MED::MED. Cette + structure remplie dés lors des fonction de gestion. L'appel à + SALOME_MED::MED.getField(...) ne charge pas les données mais renvoie + un pointeur SALOME_MED::FIELD_ptr sur les données chargées à + l'initialisation (ATTENTION, cette fonction est bugguée dans la + branche principale -> Fix dans la branche BR_medop). + +Une gestion intermédiaire peut être envisagée: le chargement à la +demande géré dans une ou plusieurs tables de champs (une pour chaque +type de valeur numérique). Une implémentation de ce type de gestion +est illustré dans la classe ``MedDataManager`` du package MEDMEM qui prend +en charge ce comportement pour les structures de données MED (en +particulier les champs). + +Utilisation du composant MED +---------------------------- +Le module SALOME MED fournit un module CORBA appelé SALOME_MED. Les +interfaces de ce module CORBA sont spécifiées par les fichiers idl +suivants: + +* le fichier + [http://nepal.der.edf.fr/pub/SALOME_userguide/MED5/doc/salome/tui/MED/MED_8idl.html + ``MED.idl``] qui décrit les interfaces des objets manipulés par le + module SALOME_MED. On trouve en particulier les objets MESH, SUPPORT + et FIELD. +* le fichier + [http://nepal.der.edf.fr/pub/SALOME_userguide/MED5/doc/salome/tui/MED/MED__Gen_8idl.html + ``MED_Gen.idl``] qui décrit les interfaces du composant SALOME + (c'est-à-dire le composant chargé par la commande + ``FindOrLoadComponent("FactoryServer", "MED")`` du + lyfeCycleCorba). On trouve: + + - l'interface ``MED_Gen_Driver`` qui hérite de SALOMEDS::Driver + pour l'implémentation des services généraux des composants SALOME + (persistance hdf, dump) + - l'interface ``MED_Gen`` qui hérite des interfaces + ``Engines::Component`` et ``MED_Gen_Driver`` pour + l'implémentation des services spécifiques du composant MED. + +L'implémentation de ces interfaces est faites au niveau de différents +packages des sources du module MED: + +* Le package ``MEDMEM_I`` qui fournit l'implémentation C++ des + interfaces décrites par le fichier ``MED.idl``; +* Le package ``MED`` qui fournit l'implémentation C++ des interfaces + décrites par le fichier ``MED_Gen.idl``, et qui correspond à la + partie composant classique d'un module SALOME. +* Le package ``MedCorba_Swig`` qui fournit une interface swig + générée à partir de l'implémentation C++ de ``MEDMEM_I`` et + ``MED`` + +L'utilisation peut être illustrée au moyen d'exemples python (i.e. qui +utilise l'interface swig fournie par MedCorba_Swig). Après l'import +d'amorce systématique: + +.. code-block:: python + + import salome + salome.salome_init() + + import SALOME_MED + from libSALOME_Swig import * + +On peut charger le composant SALOME MED: + +.. code-block:: python + + medComp=salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + +grâce auquel les services de chargement de la structure MED peuvent +être invoqués. Par exemple, les commandes suivantes chargent toute la +structure MED dans l'étude salome passée en argument: + +.. code-block:: python + + filePathName = "myfile.med" + medComp.readStructFileWithFieldType(filePathName,salome.myStudyName) + +Ce deuxième exemple charge la structure MED mais ne place pas le résultat dans l'étude: + +.. code-block:: python + + filePathName = "myfile.med" + medObj = medComp.readStructFile(filePathName,salome.myStudyName) + +On récupère à la place un objet de classe |LINK_EDF_SALOME_MED__MED|_ +qui permet une utilisation assez semblable (mais différente on le +verra plus bas) à MEDMEM: + +.. code-block:: python + + fieldIdx = 1 # WRN maybe there is no field of idx=1 + iterationIdx = 0 + fieldName = medObj.getFieldNames()[fieldIdx] + dtitfield = medObj.getFieldIteration(fieldName,iterationIdx) + it = dtitfield[0] + dt = dtitfield[1] + fieldObj = medObj.getField(fieldName,it,dt) + nbOfFields = medObj.getNumberOfFields() + fieldNames = medObj.getFieldNames() + + mesh = fieldObj.getSupport().getMesh() + +.. note:: + Observations en vrac: + + * Un FIELD_i possède un champ de type ``MEDMEM::FIELD_`` qui représente + le champ informatique réel (objet MEDMEM). + * FIELD_i::fieldMap variable static de type map qui semble gérer + les différentes instances de FIELD_i (~pattern factory). Cette + map peut être requétée au moyen d'un indice de type long appelé + corbaIndex. + * Quand on crée un FIELD_i par le constructeur d'argument + ``MEDMEM::FIELD_``, le ``MEDMEM::FIELD_`` est ajouté dans la map avec + incrément du corbaIndex + * La fonction FIELD_i::read(i) redirige vers la fonction read(i) du + ``MEDMEM::FIELD_`` associé + * A CONFIRMER: Il semble que les fonctions de chargement + ``readStructFile*()`` charge toutes les données du fichier med, + alors qu'en MEDMEM seules les meta-données sont chargées. + * A CONFIRMER: il semble que le chargement d'une structure MED + CORBA peut se faire sans passer par le composant (cf. l'interface + de MED) + +Interface avec le module VISU +============================= + +Des interactions sont possibles entre MED et VISU à partir du moment +où les données med sont gérées dans l'étude, c'est-à-dire sous la +forme d'objets SALOME_MED (voir ci-dessus) publiés dans l'étude. Les +deux conditions sont aujourd'hui nécessaires (objet corba + publié +dans l'étude) mais il semble que ce ne soit lié qu'à un choix +d'interface VISU (la fonction ``ImportMed`` en particulier) qui peut +a priori être modifié. A CONFIRMER. + +L'exemple de code ci-dessous (en python, mais il peut être transposé à +une implémentation C++) montre par exemple comment envoyer au module +VISU une requête de visualisation d'un champs hébergé par le module +MED (en fait, les données sont gérées au travers d'un objet corba +SALOME_MED "délocalisé" et qui a été référencé dans l'étude dans la +catégorie du composant MED). Les importations standard (salome, +SALOME_MED, ...) sont supposées avoir été faites au préalable (voir +les exemples précédents): + +.. code-block:: python + + # Load the med structure using MED + medComp=salome.lcc.FindOrLoadComponent("FactoryServer", "MED") + filePathName = "myfile.med" + medComp.readStructFileWithFieldType(filePathName,salome.myStudyName) + + # Get the VISU component + import VISU + visuComp = salome.lcc.FindOrLoadComponent("FactoryServer", "VISU") + visuComp.SetCurrentStudy(salome.myStudy) + + # Get the sobject associated to the med object named "Med" + aSObject = salome.myStudy.FindObject("Med") + isPresent, medSObj = aSObject.FindSubObject(1) + + # Finally, import the med sobject in VISU + result = visuComp.ImportMed(medSObj) + +Il est possible de d'aller plus loin et par exemple de déclencher +l'affichage d'une scalarmap d'un champ spécifique pour une itération +particulière (voir la fonction +``TEST_SALOMEMED_requestToVisu_scalarmap`` du fichier +``SALOMEMED_tester.py`` fourni dans les sources d'exemple). + +Liens complémentaires: + +* http://nepal.der.edf.fr/pub/SALOME_userguide/VISU_V5_1_3/doc/salome/gui/VISU La documentation utilisateur en ligne du module VISU + + +Notes en vrac +============= + +Questions: + +* Comment obtenir le nom du fichier med à partir d'une structure med? +* Peut-on imaginer un moyen de fournir l'objet MEDMEM::MED à partir de + la donnée de l'objet CORBA SALOME_MED::MED? + +Remarques: + +* A part, les opérations arithmétiques (+,-,*,/), aucune opération + n'est définie. diff --git a/src/MEDOP/doc/sphinx/xmed-prototype-overview.rst b/src/MEDOP/doc/sphinx/xmed-prototype-overview.rst new file mode 100644 index 000000000..c571c6e6f --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-prototype-overview.rst @@ -0,0 +1,95 @@ +.. meta:: + :keywords: maillage, champ, manipulation, XMED + :author: Guillaume Boulant + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Démonstrateur XMED, vue d'ensemble +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Le module XMED est un espace d'expérimentation pour le développement +des opérations de manipulation de champs. Il complète des +développements intégrés directement dans le module MED et gérés dans +la branche CVS BR_medop. + +Une maquette est au point pour illustrer les propositions en matière +d'ergonomie d'utilisation et en matière d'architecture technique. La +maquette permet de réaliser des cas d'utilisation de la forme: + +* Chargement d'un fichier med dans le module MED (ou publication par + un code de calcul). +* Sélection graphique des champs de l'étude à mettre à disposition + dans la console utilisateur ("calculette" en mode texte qui + concraitement correspond à l'interface python de SALOME). +* Dans la calculette, exécution d'opérations algébriques (+,-,*,/) + entre champs avec possibilité d'utiliser des scalaires dans des + opérations de type transformation linéaire (y=ax+b ou y et x sont + des champs et a et b des scalaires). Egalement quelques fonctions + mathématiques standard applicables sur des champs (pow, sqrt). +* Possibilité de visualiser les champs produits avec VISU +* Possibilité d'exporter des champs produits dans un fichier med + +La figure ci-dessous montre le résultat d'une séquence d'utilisation +dans laquelle les champs "testfield1" et "testfield2" ont été +sélectionnés dans l'arbre d'étude pour être utilisés dans la console +textuelle sous les noms de variables f1 et f2. L'image montre le +contrôle visuel du résultat de l'opération f1+f2-(f1-f2)^2 tapée en +ligne de commande: + +.. image:: images/medop-gui-result.png + :align: center + +La séquence ci-après montre le cas d'utilisation complet en +images: + +1. Sélection d'un champs sur un pas de temps dans l'arbre d'étude +2. Saisie d'un nom de variable (alias) pour manipuler ce champ. Par + défaut, le nom du champ est proposé (``testfield1`` ici). Dans + l'exemple, l'utilisateur remplace par l'alias ``f1``. +3. Contrôle visuel du champ ``testfield1`` manipulé par sa variable + ``f1`` au moyen de la commande ``f1.visu()`` +4. Chargement du champ ``testfield2`` sous le nom ``f2``, exécution de + l'opération ``f1+f2-(f1-f2)^2`` et contrôle visuel du résultat, + récupéré ici dans une variable de nom ``result``. + +.. |IMG_SELECT| image:: images/medop-gui-selectfield_scale.png +.. |IMG_ALIAS| image:: images/medop-gui-aliasfield_scale.png +.. |IMG_VISU| image:: images/medop-gui-visufield_scale.png +.. |IMG_RESULT| image:: images/medop-gui-result_scale.png + ++---------------+---------------+ +| |IMG_SELECT| | |IMG_ALIAS| | ++---------------+---------------+ +| |IMG_VISU| | |IMG_RESULT| | ++---------------+---------------+ + +La solution technique est construite sur les principes suivants: + +* Les données MEDMEM sont physiquement chargées par le composant MED, + c'est-à-dire dans le processus ``Container`` de SALOME, et sont + référencées dans l'étude SALOME. +* Les opérations sont physiquement des opérations entre objets MEDMEM + purs qui ont lieu dans le composant MED. +* Les opérations sont pilotées par des objets proxy python instanciés + dans la console TUI puis manipulés par l'utilisateur. Ces objets + proxy savent accéder aux objets MEDMEM au travers de leur interface + CORBA. + +Ainsi, l'architecture technique est construite pour pouvoir travailler +sur des données MEDMEM pur en partant de pointeurs CORBA manoeuvrés +depuis des objets python dans l'interface textuelle de +SALOME. L'effort principal a donc porté sur la mise au point de +l'interface technique qui permet de lier des variables représentant +les champs au niveau du GUI (techniquement, la calculette est +l'interpréteur python embarqué dans le GUI, étendu de quelques +fonctions pour la manipulation de champs), alors que les données +MEDMEM sont physiquement disponibles uniquement au niveau des +composants CORBA (et les opérations implémentées dans MEDMEM +uniquement). + +Pour le moment, la maquette est limitée à des operations entre champs +qui partagent le même support med (contrainte de MEDMEM) et le +résultat est calculé sur toutes les composantes et tout le domaine de +définition du champs (cette deuxième contrainte est juste parce que +les extentions n'ont pas encore été examinées). Enfin, le support de +gestion des données est supposé être l'étude SALOME et la structure +MED qui y est publiée. diff --git a/src/MEDOP/doc/sphinx/xmed-references.rst b/src/MEDOP/doc/sphinx/xmed-references.rst new file mode 100644 index 000000000..30d66ec7f --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-references.rst @@ -0,0 +1,28 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +ANNEXE: Références documentaires +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. include:: xmed-definitions.rst + +Documents de référence: + +* |REF_EDF_VCA_H-I2C-2009-03595-FR|_ - Valérie Cano - décembre 2009 +* |REF_CEA_VBE_MEDMEM|_ - Vincent Bergeaud - janvier 2007 +* |LINK_EDF_MEDDOC|_ - documentation en ligne (EDF) + +Présentations: + +* |REF_EDF_PRESMANIPCHP01|_ - Valérie Cano, Guillaume Boulant - janvier 2010 +* |REF_EDF_PRESMANIPCHP02|_ - Guillaume Boulant - octobre 2010 +* |REF_EDF_PRESMANIPCHP03|_ - Guillaume Boulant - mars 2011 +* Présentation à la Journée des Utilisateurs de SALOME de 2011 (JUS2011): + + - |REF_EDF_JUS2011_PDF|_ - Anthony Geay (CEA), Guillaume Boulant - novembre 2011 + - |REF_EDF_JUS2011_OGV1|_ + - |REF_EDF_JUS2011_OGV3|_ + - |REF_EDF_JUS2011_OGV4|_ + +Notes de travail: + +* |REF_EDF_GBO_WORKNOTE|_ - Guillaume Boulant - novembre 2010 +* |REF_EDF_ELO_REM|_ - Eric Lorentz - novembre 2010 diff --git a/src/MEDOP/doc/sphinx/xmed-specifications.rst b/src/MEDOP/doc/sphinx/xmed-specifications.rst new file mode 100644 index 000000000..1f8cdabaf --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-specifications.rst @@ -0,0 +1,918 @@ +.. meta:: + :keywords: maillage, champ, manipulation, med + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Module XMED: Spécifications fonctionnelles et techniques +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +(|XMED_SPECIFICATIONS_PDF|_) + +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/src/MEDOP/doc/sphinx/xmed-userguide.rst b/src/MEDOP/doc/sphinx/xmed-userguide.rst new file mode 100644 index 000000000..f35266013 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-userguide.rst @@ -0,0 +1,749 @@ +.. meta:: + :keywords: maillage, champ, manipulation, guide utilisateur + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Module XMED: Guide d'utilisation +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +(|XMED_USERGUIDE_PDF|_) + +Ce document est un guide rapide pour l'utilisation 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 XMED +==================================== + +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 XMED +======================================== + +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 moduel XMED (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/src/MEDOP/doc/sphinx/xmed-workingnotes-2010.rst b/src/MEDOP/doc/sphinx/xmed-workingnotes-2010.rst new file mode 100644 index 000000000..724c9a832 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-workingnotes-2010.rst @@ -0,0 +1,461 @@ +.. meta:: + :keywords: maillage, champ, manipulation + :author: Guillaume Boulant + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +ANNEXE: Note de travail concernant le chantier XMED 2010 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. contents:: Sommaire + :local: + :backlinks: none + +Principes directeurs du développement +===================================== + +En matière de développement: + +* On ne cherche pas d'emblée à s'inscrire dans la fabrication d'un + module SALOME diffusable dans la version d'exploitation 2010 (SALOME + 6). La raison est double: (i) on souhaite au moins pour 2010 ne pas + devoir tenir compte des contraintes de temps SALOME et (ii) le + produit envisagé fin 2010 est une maquette qui cherche à éprouver + l'ergonomie générale d'utilisation et en aucun cas on ne peut + garantir la réalisation d'un module SALOME compatible avec les + exigences de mise en exploitation. +* On ne cherche pas d'emblée à capturer tous les cas d'application, + mais à concevoir un développement qui acceptera les extensions de + périmètres dans des conditions raisonnables. Aussi, les + fonctionnalités développées seront celles qui sont nécessaires à la + réalisation des cas d'application de référence; + +En matière d'ergonomie: + +* L'interface utilisateur de référence (appelé espace de travail dans + le volet de spécifications fonctionnelles) est l'interpréteur + python. Les fonctionnalités doivent être pensées pour un usage + adapté à une interface textuelle (TUI) de ce type. +* La création d'une interface graphique (GUI) peut être envisagée en + complément et comme un moyen de manipuler graphiquement les + fonctionnalités développées pour l'interface textuelle et pour aider + la préparation des variables dans l'interface python. +* Le modèle d'un processus de manipulation de champs est: + + - Préparation du jeu de variables U, V, ... représentant les champs + à manipuler. C'est à ce stade que l'on résoud la question de + sélection des données (dans un champ publié dans l'arbre d'étude, + par un module de calcul ou par chargement d'un fichier med) + - Utilisation des variables avec une sémantique la plus proche + possible du modèle conceptuel et des spécifications + fonctionnelles; + - Création des variables qui représentent les résultats des + fonctions de manipulation; + - Persistence (fichier med), visualisation (SALOME) ou export (vers + une structure qui peut être directement utilisable en numpy) + +Sur le plan technique: + +* On souhaite spécifier clairement le conteneur SALOME des fonctions + de manipulation de champs. Pour discussion: + + - Il apparaît que les modules SALOME MED et VISU contiennent déjà + des fonctions qui peuvent faire partie des fonctions de + manipulations de champs (en particulier pour l'exploration des + structures MED, leur visualisation et la sélection des données à + manipuler). + - Dans la mesure où le module MED n'est pas utilisé à ce jour (en + tout cas pas sous sa forme de module SALOME) et compte-tenu du + caractère obsolescent du module VISU (amené à être remplacé sur le + plan fonctionnel par le module PARAVIS), on pourrait examiner la + création d'un module dédié à la manipulation des maillages et des + champs par l'agrégation technique au sein d'un même module des + fonctions des modules MED et VISU. + +Au moins dans un premier temps, on se donne les limites suivantes: + +* Une opération ne peut pas combiner des pas de temps différents. Dans + l'hypothèse où cette limite venait à être levée, on doit spécifier + le pas de temps de la donnée résultat; +* Le domaine d'application d'une opération pourra être défini + exclusivement par la donnée d'un maillage ou un groupe d'éléments du + maillage; +* On ne traite pas le cas des champs qui prennent leurs valeurs aux + points de gauss ou aux noeuds par élément. Une particularité de ces + types de support est que le repérage de la position implique deux + indices (par exemple l'indice de la maille, puis l'indice du point + de gauss). + +Eléments de conception +====================== + +Plan général +------------ + +On peut par exemple imaginer une maquette du genre: + +* En C++ dans MEDGUI, charger un fichier med et donner une vue de la + structure des maillages et des champs dans l'arbre d'étude. +* Sélectionner un élément (par exemple un pas de temps d'un champ) et + le menu contextuel permet d'exporter ce champ dans la console python + pour manipulation. Pour cela, s'inspirer de la fonction + ``XCADGUI::OnLoadScript()`` du XCADGUI pour manoeuvrer un objet + PythonConsole. +* L'élément est marqué comme ayant été exporté, on peut imaginer une + récupération ultérieure. +* Exporter un deuxième champ cohérent avec le premier (même pas de + temps et défini sur le même maillage avec le même support, on + s'arrange pour). +* Dans la console python, faire les opérations sur les champs +* Publication du champ résultat dans l'arbre d'étude pour sauvegarde + ultérieure. C'est a priori le gros morceau qui consiste à faire un + objet CORBA MED à partir d'un objet MED standard, en plus défini + dans la console python (sous forme d'objet python). + +Quand ce premier cas d'utilisation est au point, on peut envisager de +le compléter par les opérations suivantes + +* exporter le résultat med dans un fichier +* visualiser les champs produits + +Plan de développement: + +* Faire une maquette en MEDMEM pur d'abord, car quelque soit le choix + d'architecture, l'opération physique se déroulera en définitif au + niveau de MEDMEM pur. +* Prévoir une implémentation des opérations sous forme de fonctions + informatiques, même les opérations algébriques (+,-,*,/). Pour ces + dernières et dans certaines conditions (quand on manipule + directement les strutures MEDMEM et non pas les objets CORBA), + l'utilisation des formes A+B, A-B, ... peuvent être rendues + possibles. Dans ce cas, voir la possibilité de combiner plusieurs + opérations algébriques sur une seule ligne: A+B-C*0.3. +* On peut charger la structure MED sous forme d'objet CORBA publiable + dans l'étude, de sorte d'avoir accés aux méta-données et pouvoir par + exemple sélectionner les champs d'intérêt. De cet objet CORBA, on ne + récupère que les informations nécessaires au chargement d'un champs: + le nom du champs, le nom de son maillage associé, les identifiants + du pas de temps, au besoin une structure Field non chargée (par + exemple pour récupérer plus facilement le maillage). +* Un mécanisme (à développer à partir du PyConsole par exemple) + pourrait alors permettre le chargement des champs sélectionnés dans + la console python et sous un nom facile à manoeuvrer. Prendre + inspiration sur XCADGUI::LoadIntoPythonConsole(). +* A priori, les données sont physiquement chargée dans le GUI. Au + besoin, il semble possible (cf. MED_i::init) de fabriquer une objet + CORBA field à partir d'un field standard (à tester). + +Une autre idée est de récupérer le pointeur CORBA MED dans la console +python et de tirer les données à partir de là. Ajouter une couche de +wrapping python pur pour gérer les cas de simplification (surcharge +des opérations arithmétiques par exemple). + +Besoins complémentaires: + +* L'interpréteur doit contenir des éléments d'aide (par exemple un + help qui liste les opérations possibles sur les champs chargés) +* prévoir quelques fonctions de visu et de persistence. Cela commence + probablement par des fonctions de publication dans l'étude des + champs créés par les opérations de manipulation. Les champs sont + physiquement ajouté automatiquement à la structure med par le MedOp + mais il n'est pas obligatoirement publié => fournir un moyen de + publication. + +Limitations actuelles (liées à la conception de MEDMEM): + +* les champs doivent être gérés par la même structure MED car ils + doivent partager le même support. +* les opérations possibles dans MEDMEM sont entre champs pris sur un + pas de temps (Q: les pas de temps peuvent-ils être différents). + + +Développements +-------------- + +Développement de classes proxy: + +* FieldProxy, FieldTimeSeriesProxy +* Attention pour les éries temporelles, le SUPPORT med peut être + différent en chaque pas de temps (par exemple en cas d'extension + spatiale du champ au cours du temps). + +MEDMEM_MedDataManager: + +* FIX: test de l'implémentation C++ au travers de la fonction test() du + MedOperator ==> OK. Quand on fait la même opération depuis python + via l'interface SWIG ==> au deuxième appel de getFieldDouble, le + destructeur du champ semble être appelé. Pb de gestion des pointeurs? + + +Evolutions à prévoir +==================== + +Concernant MEDMEM: + +* FIX: SALOME_MED::MED::getField devrait pouvoir être appelée + plusieurs fois de suite puisqu'on recycle la référence si elle est + déjà chargée. +* IMP: MEDMEM::MED faire une gestion des chargements des champs (par + exemple avec un getField qui renvoie le champ s'il est déjà chargé + ou le charge et le renvoie sinon). +* IMP: Récupérer le nom du fichier med à partir de l'objet MED, en + passant a priori par le driver associé. Plusieurs driver peuvent + être associés à une structure MED car les données peuvent être + chargées en plusieurs fois et de plusieurs fichiers. Il faut donc + étendre la structure MED pour avoir accés à la liste des driver puis + de cette liste déduire les noms des fichiers. +* IMP: Opérations combinant des champs sur des support différents ne + peuvent pas être faites par l'API (une exception est levée en cas de + supports incompatibles), mais on peut imaginer le faire en + manoeuvrant les tableaux de données directement. +* INF: faire le point sur les fonctions utilitaires autour de MEDMEM + et de son interface SWIG (ex: dumpMEDMEM.py, med_opfield_test.py). +* IMP: dans MEDMEM::MED et SALOME_MED::MED, pouvoir enlever un champ + préalablement ajouté: une fonction removeField en complément de + addField. + +Concernant l'interface SALOME_MED: + +* IMP: Fonctions algébriques, qui seront implémentées au niveau de la + structure MED et requêtées au niveau des classes proxy en spécifiant + les identifiants des champs impliqués et les paramétres requis (pas + de temps en particulier). + +Concernant le module MED: + +* IMP: pourvoir exporter la structure med dans un fichier med (la + structure ayant pu être enrichie par la publication de champs créés + par les operations de champs. + + +Historique des travaux +====================== + +20100726 : mise au point du schéma de conception +------------------------------------------------ + +Choix entre MEDMEM et MEDCoupling: on reste sur MEDMEM pour plusieurs +raisons: + +* MED Coupling ne peut pas gérer des mailles de dimensions différentes + dans un même modèle (choix faits dans un soucis de performance dans + l'accès à une structure de donnée compact). On peut contourner le + problème en définissant deux champs pour traiter chacun des type de + mailles. +* Un champ repose sur un maillage complet (pas de notion de profil, + mais cela peut être émulé en créant deux maillages) +* Le concept de point de gauss n'existe pas (pas implémenté) + +TODO: + +* Idéalement, il conviendrait de faire un état des lieux du module + MED, en particulier des éléments MEDMEM (le coeur), les interfaces + CORBA associées (MED.idl implémenté dans le package source + MEDMEM_I), l'engine (composant SALOME d'interface MED_Gen.idl et + implémenté dans le package source MED) et le GUI (MedGUI.cxx + implémenté dans le package source MEDGUI). + +* Ergonomie TUI et modèle CORBA associé: + + 1. Charger un objet medmem (puis les objets métier mesh et field) + sur un domaine d'application donné. + 2. En faire des variables disponibles dans l'interface TUI et que + l'on peut manipuler dans des opérations algébriques. + 3. Pouvoir au besoin en faire des objets CORBA pour l'interface avec + les autres modules SALOME. + +* Compléter le diagramme de la structure informatique de MED (en + particulier l'implémentation des interface IDL). +* Préparer un module de travail XMED (organisation d'une bibliothèque) + +Tests à réaliser: + +* Est-il possible de faire des opérations algébriques à partir des + objets SALOMEMED (objects CORBA MED)? +* Création d'un objet MED_i à partir d'une objet MED pur préalablement + chargé en mémoire. + +A retenir: + +* Des opérations de champs sont possibles sur des champs à des pas de + temps fixés. Si l'opération doit être menée sur plusieurs pas de + temps, alors itérer sur chaque pas de temps. L'idée ici est + d'introduire le concept de série temporelle de champs en temps + qu'objet manipulable. +* Pour deux champs différents de la même structure MED, la données des + identifiants dt et it ne correspond pas forcément au même instant + absolu (en tout cas rien ne le garanti, même si c'est tout de même + une pratique courante). + +20101005 : première maquette de démonstration de l'ergonomie en MEDMEM pur +-------------------------------------------------------------------------- + +XMED: svn révision 16 +Travailler avec le fichier de donnée testfield.med joint. + + +20101007 : Vers une maquette CORBA +---------------------------------- + +Le contexte d'utilisation des opérations de champs est l'environnement +SALOME. Le support de gestion des données est donc l'étude SALOME. Au +plus bas niveau, les champs sont des objets MEDMEM instanciés dans une +session SALOME (soit par un code de calcul intégré, soit par +chargement des données à partir d'un fichier med). Ces objets sont en +général référencés dans l'étude SALOME sous la forme d'objets CORBA de +classe SALOMEMED::FIELD. Plus exactement, l'étude SALOME gère des +SObject (Study Object) dont un attribut est une référence vers un +objet CORBA de classe SALOMEMED::FIELD qui lui-même encapsule un objet +MEDMEM::Field. + +On peut donc envisager une solution dans laquelle on donne à +l'utilisateur des poignées de manipulation des objets +SALOMEMED::FIELD, par exemple au moyen d'un modèle informatique de +type proxy. Cela signifie que l'utilisateur ne manipule pas +directement des objets MEDMEM mais des objets python qui font +l'interface (à concevoir et implémenter, a priori avec un design +pattern de type proxy). + +L'utilisation directe des objets MEDMEM aurait pu être une solution +extremement pratique dans la mesure où ces objets en l'état peuvent +être combinés dans des opérations de champs (c'est déjà +implémenté). Par contre, ce procédé souffre de limitations importantes +dans la gestion et la circulation des données pour les différents cas +d'utilisation envisagés (visualisation, export, transfert à un autre +module SALOME). + +L'avantage de la solution proposée est multiple: + +* Elle permet de travailler sur une structure MED cohérente pour + intégrer les résultats des opérations de calculs et combiner des + champs cohérents entre eux. Tout passe par des classes proxy qui + pourront s'assurer de la cohérence des opérations demandées et + exécuter automatiquement les fonctions de pré-traitement ou + post-traitement requises pour ces opérations. On peut imaginer par + exemple que les requêtes d'opération soient envoyées par les classes + proxy à la structure MED à laquelle les champs sont associés pour + piloter l'opération en MEDMEM pur. +* Elle permet d'automatiser un certain nombre d'opérations + implicites. Par exemple si deux champs ne sont pas définis dans la + même unité, un changement d'unité peut être effectué automatiquement + par la classe proxy avant de commander l'opération au niveau + MEDMEM. +* Elle permet de laisser les données sur le container SALOME et de + réaliser des opérations sans rappatrier les données en local (qui + peuvent être en trés grand nombre). +* Elle permet d'étendre facilement l'ergonomie de manipulation des + champs, par exemple en définissant la notion de *série temporelle de + champs*, ou encore les concepts de *domaine de définition* évoqués + dans les spécifications fonctionnelles. +* Elle rend immédiat la circulation des données entre modules SALOME, + puisque les champs restent accessble par des objets CORBA, en + particulier pour la visualisation ou l'export des champs produits + par les opérations. + +Elle a cependant des inconvénients et/ou limitations: + +* Elle nécessite l'implémentation d'une classe proxy pour encapsuler tous + les appels aux objets SALOME_MED (et donc MEDMEM). Cette interface + se limite a priori aux opérations de champs (les opérations + algébriques dans un premier temps). +* Les champs à manipuler dans une opération donnée doivent être gérés + par la même structure MED. + +Il est à noter également que les interfaces de programmation de +SALOMEMED (interface CORBA pour MEDMEM) devront être étendues pour +permettre des requêtes de manipulations de champs (fonctions addition, +soustraction, multiplication, ...). Pas de contrainte ici sur +l'ergonomie puisque la manipulation par l'utilisateur se fera au +niveau des classes proxy uniquement. + + +Hypothèses: + +* On tente ici une maquette qui exploite dans la mesure du possible le + fonctionnement actuel du module MED, en particulier la gestion des + données dans l'étude. +* Dans une deuxième version, on pourra examiner sérieusement la + révision de la gestion des données dans le module, quitte à la + spécifier et maquetter dans XMED pour intégration ultérieure dans + MED. Exemple: + + - Pouvoir gérer plusieurs structures med dans l'étude. + +* Enfin, on exploite MEDMEM en l'état. Pour les besoins de la gestion + des données (gestion des chargements des champs en particulier, + références croisées pour retrouver le med à partir du champ par + exemple, ...), il pourra être nécessaire de faire évoluer MEDMEM. Il + faut pouvoir par ailleurs gérer indifféremment une structure med (et + les champs qui y sont associés) qu'elle soit créée en mémoire from + scratch ou chargée d'un fichier (donc attention avec les opérations + de lecture read(), sur les maillages comme sur les champs). La + structure med permet d'obtenir les méta données (meta-field par + exemple) mais ne permet pas de savoir si les données sont + physiquement chargées ou pas. + + +Révisions: + +* XMED svn revision 21 + tarball MED_SRC-20101014-15h26m.tgz. + Première version qui permet d'importer un champ dans la console + python sous la forme d'un FieldProxy. Ne permet pas encore de faire + des opérations. Introduction dans le module MED de l'interface MEDOP + pour prendre en charge les opérations sur les champs. + + +20101019 : Maquette de démonstration pour l'addition +---------------------------------------------------- + +Cette maquette implémente une solution technique de bout en bout (de +l'interface python aux objets MEDMEM, en passant par le fieldproxy +puis les servants CORBA pour les operations, ...) mais sur le +périmètre de l'addition de champs sur tout leur domaine de définition +et pour un pas de temps donné. + +Limitations: + +* gére l'addition de champs de type double uniquement (parceque le + reste n'est pas implémenté) + +Révisions: + +* XMED: svn révision 25 +* MED: cvs tag BR_medop_20101019 + + +20101020: Fonctions complémentaires +----------------------------------- + +Cette version test la faisabilité des fonctions complémentaires pour +accompagner la manipulation de champs. Cela comprend en particulier: + +* **la sauvegarde des champs produits** dans un fichier med (un champ ou + toute la structure med). Pour cela, on définit un med proxy comme + l'extention du SALOME_MED::MED (prévir plutôt d'implémenter ce type + de fonction au niveau C++ pour permettre un usage au niveau du GUI + C++?). +* **la visualisation d'un champ** au moyen du module VISU. +* **des fonctions d'aide interactives** pour assister l'utilisateur + dans la console de manipulation des champs. + + +Questions: + +* peut-on sauvegarder un champ unique? +* peut-on faire en sorte que ce soit l'affectation à une variable qui + provoque l'ajout du champ à la structure med (ou plus exactement qui + supprime tous les champs intermédiaires). + + +Révision: + +* XMED: svn revision 31 +* MED: cvs tag BR_medop_20101025 + + +20110606: commit avant transfert dans git +----------------------------------------- + +* XMED: svn revision 53 + +Les parties de MED utiles à MEDOP seront reversées dans XMED +dans une première étape, puis le tout dans MED 6 au final. diff --git a/src/MEDOP/doc/sphinx/xmed-workingnotes-2011.rst b/src/MEDOP/doc/sphinx/xmed-workingnotes-2011.rst new file mode 100644 index 000000000..8ba8b8068 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-workingnotes-2011.rst @@ -0,0 +1,473 @@ +.. meta:: + :keywords: maillage, champ, manipulation + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +ANNEXE: Note de travail concernant le chantier XMED 2011 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. contents:: Sommaire + :local: + :backlinks: none + +Cas d'utilisation métier +======================== + +On illustre par un exemple (Christophe Vallet, R&D/MMC, 1/7/2011):: + + J'ai souvent des fichiers med de résultats de calcul, et j'aimerais y + ajouter de nouveaux champs issus de champs existants. J'aimerais + aussi pouvoir créer de nouveaux meds plus petits par extraction de + certaines composantes de champs, certains groupes ou certains pas de + temps. + +On peut exprimer le besoin sous la forme des cas d'utilisation +suivants (use cases): + +* **UC1: combiner dans un même fichier med des champs issus de + plusieurs sources de données**. On peut par exemple charger un + premier fichier, puis ajouter à cette base des champs issus d'autre + fichiers ou générés par manipulation de champs, ou encore générés + par un module de calcul qui produirait directement du MEDCoupling. +* **UC2: créer un champ contenant certaines composantes d'un autre + champ**. On pense ici aux fonctions de restriction, qui permettraient + de récupérer certaines composantes uniquement. +* **UC3: créer un champ contenant certains pas de temps d'un autre + champ**. C'est un cas particulier des fonctions de restriction + évoquées ci-dessus. +* **UC4: créer un champ comme la limitation d'un autre champ à un + groupe de mailles**. C'est un cas particulier des fonctions de + restriction évoquées ci-dessus. Notion de domaine spatial. A + priori la notion de groupe est définie dans MEDLoader. + +On peut ajouter également les UC identifiés pour la maquette 2010: + +* **UC5: comparer des champs issus de source de données différentes**, + par exemple des champs chargés de deux fichiers med différents et + qui s'appuient sur le même maillage (au moins conceptuellement). Le + problème technique ici est de pouvoir changer le maillage d'un + champ, pour ramener tous les champs sur le même maillage (au sens + informatique). Ceci est une contrainte de MEDCoupling, les + opérations sur des champs A et B imposent que A et B soient définis + sur le même maillage, i.e. le même objet informatique. +* **UC6: créer un champ de toute pièce sur un maillage**, ou un groupe + de mailles. Ce cas d'usage est typiquement prévu pour produire les + conditions de chargement initial d'une structure. Il s'agit ici + d'initialiser un champ à partir de zéro sur une surface prédéfinie + de la géométrie (par exemple spécifiée par un nom de groupe de + mailles). + +Pour UC5: les sources de données sont référencées dans l'object +browser. On importe explicitement les données dans l'espace de +travail. On peut détecter que les maillages sont identiques et on +propose à l'utilisateur de transférer le champ sur le maillage déjà +présent. Sinon, les champs devront être référencés sur des maillages +distincts dans l'arbre de l'espace de travail. + +Analyses préliminaires pour le chantier 2011 +============================================ + +On fait le choix pour le chantier 2011 de travailler à partir de la +bibliothèque MEDCoupling (et non plus MEDMEM comme c'était le cas dans +le démonstrateur 2011). + +Analyse de MEDCoupling et MEDLoader +----------------------------------- + +MEDCoupling est l'implémentation du modèle de données MED (avec +recherche de minimisation des dépendances logicielles) et MEDLoader +fournit une ensemble de fonctions pour le chargement des structures +MEDCoupling depuis un fichier ou inversement leur sauvegarde sous +forme de fichiers. + +Dans l'implémentation MEDCoupling, un champ est l'ensemble des valeurs +d'une grandeur physique sur un maillage pour un pas de temps donné. Un +champ est caractérisé par: + +* un support spatial, le maillage +* un type de discrétisation spatial, défini par l'emplacement des + valeurs sur le maillage (sur les noeuds, sur les cellules, aux + points de gauss, ...) et le mode d'interpolation spatial (P0, P1, + etc) +* un pas de temps, défini par deux entiers (iteration, order) et un + réel (timestamps) + +Dans cette implémentation, il existe une association 1..n entre un +maillage et un champ (alors que dans MEDMEM, la structure +intermédiaire SUPPORT est implémentée). + +MEDCouplingCorba fournit un ensemble de servants CORBA pour manoeuvrer +des structures MEDCoupling au travers du bus CORBA. L'interface à ce +jour est délibérément réduite. Des classes dites "Cliente" sont +fournies pour piloter les servants CORBA depuis un contexte +client. Par exemple ``MEDCouplingFieldDoubleClient`` fournit une +fonction de création d'une structure MEDCoupling à partir d'un +pointeur vers un servant CORBA. La structure est créée localement +(dans le contexte client) avec duplication des données issue de la +structure encapsulée par le servant CORBA (récupération par la +fonction de sérialisation). + +Aucune interface CORBA n'est défini pour MEDLoader. + +Questions: + +* Voir comment sont créés les servants, et surtout comment ils sont + récupérés (via le lcc?) +* Comment peut-on définir un champ sur un groupe de mailles (et non + pas sur le maillage complet)? Comment peut-on extraire le champs + circoncit à une groupe de mailles pour des opérations. + + - R: méthode changeUnderlyingMesh + +* Comment manipuler deux champs chargées de fichiers différents mais + construit sur le même maillage (conceptuellement). On peut forcer la + réassociation d'un champ sur un autre maillage? +* Manipuler des champs de pas de temps différents? Différentes + composantes d'un ou plusieurs champs? +* Comment importer un MedCoupling dans PARAVIS? (dans VISU?)? + +* mapper sur une image + +Improvments: + +* MEDLoader::Write should raise an exception if the filepath is not writable +* MEDDataManager: développer une classe chapeau sur MEDCoupling et + MEDLoader pour aider au chargement et la gestion de données MED + (orienté manipulation de champs). Cette classe serait associée des + structures légères FieldHandler et MeshHandler et des listes + correspondantes pour la navigation dans les méta-données. +* Sur base du MEDDataManager, prévoir des ports med pour yacs par + lesquels pourrait transiter des handler. + +Nouveaux concepts à prendre en compte +------------------------------------- + +Au démarrage du chantier 2011, on observe que les concepts suivants +sont introduits dans le module MED: + +* Le conteneur MED n'existe plus, utiliser MEDFILEBROWSER pour charger + les fichiers med et obtenir les informations générales sur le + contenu. +* MEDFILEBROWSER: remplace le concept de driver et fournit les + fonctions précédemment fournies par la classe MED pour obtenir les + informations de structure. +* Concept d'Extractor pour une lecture sélective des données de champs + (suivant un critère d'extraction) +* Il n'est plus nécessaire d'appeler les méthodes read explicitement + sur les objets (MESH et FIELD) pour charger les données. Par + ailleurs, on peut définir deux fois le même champs (double + chargement a priori) sans lever d'exception). + + +Analyse de conception pour le chantier 2011 +=========================================== + +Composants SALOME (interfaces IDL) +---------------------------------- + +* MEDDataManager: défini une structure FIELD pour identifier un champ + dans les requêtes. Il s'occupe également de la récupération physique + des données, quelqu'en soit la source (fichier avec MEDLoader, autre + module SALOME comme PARAVIS avec une méthode à définir) +* MEDCalculator: s'occupe des requêtes de calcul dont les arguments sont + les structures FIELD du MEDDataManager. Reprendre l'interface de + MEDOP. + +Use case à réaliser depuis un client python: + +* UC01: ajouter un fichier d'entrée et accéder aux informations + concernant les champs. Ex: récupérer une structure champs par la + donnée des paramètres primaires (nom identifiant, dt, it, nom du + maillage). +* UC02: créer des champs et les ajouter au MEDDataManager +* UC03: mener des opérations basique sur les champs en console python + +Interface Utilisateur +--------------------- + +L'interface utilisateur est composée des parties suivantes: + +* une partie GUI (appelée par la suite MEDGUI) qui s'occupe de piloter + le chargement des données dans l'espace de travail, au moyen d'une + interface graphique; +* une partie TUI (appelée par la suite MEDTUI) qui s'occupe de piloter + la création de champs, au moyen de commandes exécutées dans la + console python. + +Le principe est que les champs sont préalablement chargés au niveau du +composant SALOME au moyen de l'interface graphique (MEDGUI), puis +manoeuvrés depuis l'application SALOME au moyen de variables proxy +définies dans la console python (MEDTUI). Au chargement, les champs +sont indéxés par le MEDDataManager, puis les index sont rendus +accessibles au niveau du GUI au moyen d'une représentation +arborescente de la structure MED. Les feuilles de l'arbre +correspondent à des champs qui peuvent être sélectionnés et dont +l'index peut être obtenu de la sélection. + +L'espace de travail est organisé autour du concept de +"workspace". L'étude SALOME liste les datasource (les fichiers source +des données med, mais peut-être aussi les référence vers des objets +MED déjà existants ou chargé dans PARAVIZ). Une vue complémentaire +permet de voir la structure fine d'une source de données. + +Concernant MEDGUI: + +* la représentation des données (les champs et les maillages associés) + doit permettre de récupérer par l'interface graphique les + identifiants des champs à manipuler (a priori les structures FIELD + définies par le composant MEDDataManager). Cela conduit à la mise en + place des composants suivants: + + - MedDataModel hérité de TreeData. Il est peuplé avec les + méta-données décrivant la structure MED explorée. + - MedGuiManager qui permet l'implantation du doc widget de + présentation + +TODO: + +* specifier le concept de workspace (qui a une entrée dans l'étude?) + en bijection avec un datamanager +* identifier des interlocuteur/utilisateur pour l'aspect ergonomie d'usage + +Concernant MEDTUI: + +* Il fournit les classes FieldProxy + +Questions: + +* Comment traiter le cas du travail sur des composantes ciblées, plus + généralement, comment introduire le concept de domaine + d'application? +* Prévoir des fonctions génériques (initialisation d'un champ sur un + maillage avec une fonction analytique de la position, sauvegarder + les champs créés dans un fichier med) + + +Tâches de développement +======================= + +T20110622.1: Gestion des données internes +----------------------------------------- + +**Status: terminé.** +Suite: fonction de sauvegarde au niveau graphique également + +On vise les cas d'utiliation suivants: + +* UC1: intégrer dans le datamodel du gui un champ créé dans la console + python (et donc présent dans le datamanager du composant). Définir + l'utilité? +* UC2: renommer un champ et plus généralement changer ses méta-données + (avec assurance de synchronisation entre toutes les données). +* UC3: sauvegarder une sélection de champs. La sélection peut se faire + dans l'arbre du datamodel gui. + +WARN: robustesse de fieldproxy + + + +T20110622.2: UC Initialisation/Création de champs +------------------------------------------------- + +**Status: à faire** + +Les cas implémentés à ce jour sont la création de champs à partir de +champs existants et chargés d'un fichier med. On souhaite ici réaliser +des cas 'utilisation autour de la création de champs "from scratch", +s'appuyant tout de même sur un maillage chargé. + +UC01: Sélection d'un groupe de maille dans SMESH pour initialiser un +champ (par exemple les conditions limites d'un problème de calcul). + +UC02: créer un champ avec des restrictions qui définissent le domaine +d'application des opération de champs. + +UC03: créer un champ à partir d'une image (codes rgb utilisé comme les +composantes du champs vectoriel ou niveaux de gris pour un champ +scalaire. Attention, pour ça, il faudra a priori fiare une projection +du maillage cartesien de l'image sur le maillage (quelconque) sur +lequel on souhaite définir le champ. + +UC04: créer un champ à partir d'un tableau numpy + +De manière générale, ce type de création sera assisté par le +MEDGUI. Au niveau MEDTUI, les fonctions pourraient être fastidieuses +pour l'utilisateur. + +Par exemple, prévoir un menu contextuel qui propose les opérations +possibles en fonction de la sélection (en plus de la fonction d'import +dans la console python). + +TODO: + +* développer les fonctions d'initialisation, par exemple au moyen + d'applyFunc et du mécanisme de callable? + +T20110622.3: documentation contextuel +------------------------------------- + +**Status: à faire** + +* Remettre toutes les commandes dans le même fichier (fusionner cmdtools + et fieldtools) +* Faire un modèle générique de command (classe de base +* Batir la doc des commandes sur cette base (lister toutes les + instances de type Command par exemple) + +T20110622.4: remontée des exception du composant MEDCalculator +-------------------------------------------------------------- + +**Status: en cours, compléter la couverture** + +Pour des messages contextuel sur les erreurs de calcul (ex: division +par 0) + +* Poursuivre le travail fait sur getMedEventListener +* Protéger tous les appels au composants effectués depuis la console + python (prendre example sur la commande save) + +T20110624.1: gestion des données GUI +------------------------------------ + +**Status: à faire** + + + +Le workspace a une entrée dans l'obrowser. Sur cette entrée on peut: + +* supprimer: supprime tout les champs associés +* sauvegarder. Dans ce cas, on rappelle l'ensemble des champs pour + cocher ceux qu'on veut sauvegarder. + +Le gui data model est réservé aux opérations sur les champs et à +piloter leur import dans la console python. + +TODO: + +* Spécifier les concepts de workspace, database, et datasource, espace + de gestion, ... et les associations. Simplifier avec l'appuie de use + cases. +* Mécanisme de mise à jour du TreeView de XSALOME (aujourd'hui, seul + l'ajout addChild est implémenté +* Clic droit sur objets de l'arbre: dans la notification TreeView -> + WorkspaceController, faire remonter l'évènement clic droit ainsi que la + liste des éléments sélectionné pour faire générer le menu contextuel + au niveau du WorkspaceController qui peut déterminer le contexte métier + (le TreeView ne le connaît pas). +* Définir des DataObject pour les maillages, les séries temporelles et + les champs + + +Spécification des espaces de données: + +* MEDDataManager dépend de l'étude (pour permettre la publication + d'information dans une étude SALOME). +* créer "sourcid = MEDDataManager::addDataSource(filename)", suivie de + requetes getFields(sourceid), getMeshes(sourceid) +* les espaces de données: dataspace, workspace. Un seul workspace par + étude, mais autand de datasources que l'on souhaite dans le + dataspace. Les datasources sont rangés dans l'étude (le dataspace) + et sont non modifiables après chargement (référence des sources de + données). + + +T20110628.1: extention à d'autres objets SALOME +----------------------------------------------- + +**Status: suspendu** + +On doit reposer la question de l'existance de l'arbre indépendant +(DockWidget), d'une part, et l'extention aux autres objets (GEOM et +SMESH en particulier) du principe de sélection graphique pour +utilisation dans la console python, d'autre part. + + +T20110628.2: visualisation d'un champ avec PARAVIS +-------------------------------------------------- + +**Status: terminé (pour une première version)** +Suite: de nombreux défauts subsistent + +Questions/remarques: + +* Pb au démarrage du module: VisTrails fails to start +* Peux-t-on piloter la vue 3D sans charger le module? (voir + myparavis.py) +* Comment donner un nom au MEDReader1 dans l'arbre Pipeline? +* Comment utiliser directement les objets MEDCouplingField? + + +T20110706.1: documentation du module +------------------------------------ + +**Status: en cours (10%)** + +Documenter les commandes TUI puis l'utilisation générale de +l'interafce graphique. Mentionner l'existance de la commande medop.sh +pour travailler exclusivement en mode texte (utile pour les tests +rapides). + +Documenter les modalités d'exécution des tests. + +T20110708.1: helper python pour MEDCoupling +------------------------------------------- + +**Status: en attente (pas urgent)** + +Faire un helper python dans le package xmed qui permet de faire du +medcoupling facilement (essentiellement pour simplifier le chargement, +puis la sélection des données). Cela demanderait de faire un +MedDataManager comme une class C++ pure (non CORBA). Cette classe +travaillerait par exemple uniquement avec des id et des liste d'id, et +fournirait des fonctions d'affichage (comme le ``ls`` et le ``la``) +pour obtenir des meta-information. + +Le servant MedDataManager pourrait être une surcouche de cette classe +c++ pure. + +T20110708.2: analyses et tests +------------------------------ + +TODO: + +* créer un fichier de test avec plusieurs pas de temps +* créer un fichier de test avec des groupes de mailles + + +T20110728.1: refactoring MEDDataManager +--------------------------------------- + +Refactoring pour une meilleur association entre FieldHandler et MeshHandler: + +* dans la mesure du possible utiliser les id plutôt que les handler en + arguments des fonctions d'appel des objets +* A chaque champ (FieldHandler), on doit associer un meshid (et de + manière optionnelle un fieldseriesId, si le champ peut être associé + à une serie temporelle. A priori faisable uniquement au chargement + du datasource). +* Pour cela, revoir les fonctions internes newFieldHandler et addField + ou prévoir de les compléter à chaque fois qu'elles sont appelée avec + les informations concernant le meshid. +* addField est utilisée par le MEDCalculator +* Attention au raffraichissement des données handler au niveau du + Workspace. Peut-être le mieux est que les fieldproxy contiennent + uniquement le fieldid, et qu'ils interroge le datamanager à chaque + fois qu'ils ont besoin d'une donnée. Voir aussi les notifications + via le MEDEventListener? **Le plus simple est de faire la mise à + jour lors de l'appel à la méthode __repr__ du fieldproxy, i.e. quand + on essaye d'afficher les données**. Parceque sinon il n'y a pas de + problème puisque que le calculateur travaille à partir des id. + + +Petites améliorations du DataspaceController: + +* Au OnUseInWorkspace, stocker (dans la mesure du possible) le nom de + l'alias python dans un attribut du sobject. +* Dans DlgChangeUnderLyingMesh, expliquer que le champs sera dupliquer + est posé dans le WS. On peut donc proposer en option de lui associer + un alias pour manipulation dans la console + + + diff --git a/src/MEDOP/doc/sphinx/xmed-workingnotes-2012.rst b/src/MEDOP/doc/sphinx/xmed-workingnotes-2012.rst new file mode 100644 index 000000000..011190ef4 --- /dev/null +++ b/src/MEDOP/doc/sphinx/xmed-workingnotes-2012.rst @@ -0,0 +1,84 @@ +.. meta:: + :keywords: maillage, champ, manipulation + :author: Guillaume Boulant + +.. include:: xmed-definitions.rst + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +ANNEXE: Note de travail concernant le chantier XMED 2012 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. contents:: Sommaire + :local: + :backlinks: none + + +Analyse preliminaire pour le chantier 2012 +========================================== + +La figure imposée pour le chantier 2012 est l'intégration du nouveau +module de manipulation de champs dans SALOME 6.6 (objectif CEA), en +préparation de la mise en exploitation dans SALOME 7 (objectif EDF). + +L'état actuel est: + +* Un module SALOME de nom MED intégrant les bibliothèques MEDCoupling, + MEDLoader, REMAPPER, mais aussi plusieurs packages logiciels + aujourd'hui obsolètes ou amener à disparaître pour l'échéance + SALOME7 +* Un module SALOME de nom XMED qui fournit les fonctions graphiques + pour la manipulation de champs. +* Ce module XMED utilise le module VISU pour les vue de contrôle. + +La cible est: + +* Un module unique (nom à définir, par exemple MEDOP) débarrassé des + packages logiciels obsolètes et intégrant les fonctions graphiques + (GUI et TUI). +* L'utilisation du module PARAVIS (au lieu de VISU) pour les vues de + contrôle. +* L'intégration de MEDCoupling avec YACS (port MED dans YACS par + exemple). + +A examiner: + +* voir les attendus concernant les ports MED dans YACS +* interface PARAVIS: utilisation du viewer (et de l'API python) sans chargement du GUI + +Tâches de développement +======================= + +20120904: Migrer XMED dans MED +------------------------------ + +Plan de travail: + +* Migration des composants + test + + + +20120904: Nettoyage de XSALOME +------------------------------ + +:status: en cours + +* Supprimer les vieilleries de XSALOME: + + - StdHelper -> Basic_Utils (KERNEL) + +20120829: mise en place du chantier 2012 +---------------------------------------- + +:status: terminé + +L'objectif de cette première étape est de reverser le prototype 2011 +(module XMED indépendant) dans la branche V6_main du module MED. On +peut procéder de la manière suivante: + +* update de XMED (et XSALOME utilisé par XMED) pour fonctionnement sur + V6_main +* Eliminer la dépendance à XSALOME +* Supprimer la gestion des multiversion SALOME5/6 au niveau de l'engine + +.. warning:: TODO: refaire le point sur les tâches initiées en 2011 +