--- /dev/null
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MDMdoc.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MDMdoc.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/MDMdoc"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MDMdoc"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
--- /dev/null
+.. _accasConnecteur-label:
+
+
+API for accas
+=============
+
+Usage
+______
+
+
+Syntax
+______
+
+General syntax
+~~~~~~~~~~~~~~
+
+
--- /dev/null
+.. _bloc-label:
+
+
+Defining a conditional Group
+=============================
+
+Definition and Usage
+____________________
+
+| In a user dataset, a conditional group will exist (or not) depending on the evaluation of a python condition which often takes the form parameter == value). This python condition is dynamically evaluated.
+| Apart from its cardinality, a conditional group has the same syntax as non-conditional group.
+
+Syntax
+______
+
+General syntax
+~~~~~~~~~~~~~~
+
+Syntax is :
+::
+
+ myConditionalGroup = BLOC( condition= " python statement",
+ ... #included SIMP or others FACT/BLOC
+ )
+
+BLOC can be seen as an 'if' statement.
+Python statement contains often <, >, == but it can be any expression returning True or False.
+
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-after: Test_proc_5
+ :end-before: #Test_proc_5
+
+This means :
+ * if frequency_every == 'every', particule_printed (only one) is requested
+ * else step_to_be_printed (list) is required.
+
+
+Don't forget that catalogs are python code. All "keywords" are arguments and in python, arguments are separated by comma "," and must be enclosed in parenthesis. Note that conditions are statements but also python strings. Use single quotes within double quotes if needed.
+
+
+
+Cardinality
+~~~~~~~~~~~
+- A BLOC appears based on the evaluation of the conditional statement. it has no mandatory or optional status
+- Also, a BLOC has no cardinality. It cannot be repeated. On the other hand, the FACT or SIMPs that make it up may have multiple cardinality and may appear several times.
+- if keywords within a BLOC have a status,it is applied within the BLOC.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-after: Test_proc_6
+ :end-before: #Test_proc_6
+
+This means :
+ * if wind_speed > 0.5, wind_direction is needed and rain_speed can be added
+
+
+
+
+Other useful attributes
+~~~~~~~~~~~~~~~~~~~~~~~
+ +-------------+-------------------------------------------------+-----------+
+ |*attribute* |*Description* |*default* |
+ +=============+=================================================+===========+
+ |ang |short documentation | |
+ +-------------+-------------------------------------------------+-----------+
+
+
--- /dev/null
+EFICAS terms
+============
+
+Apart of a root node (named JDC_CATA), catalogs contain different types of entities :
+
+ - terminal_symbol : SIMP (SIMPle type) or SIMP_keyword
+ - group_of_eficas_keyword : FACT (shorcut for FACTOR) or BLOC (conditionnal FACT):
+ - Content elements are terminal_symbol or group_of_eficas_keyword
+ - The grouping of these keywords is important from a data modelling perpective.
+ - The group_of_eficas_keyword can be conditional and only becomes necessary if another parameter meets a condition (ie wind_direction is only necssary if wind_speed is not nul)
+ - eficas_keyword : terminal_symbol or group_of_eficas_keyword
+ - commands : PROC (shortcut for procedure) or OPER (shortcut for operator).
+ - they constitute the second level of the hierachical tree (after root node).
+ - PROC and OPER both contain other keywords (group or terminal_symbol).
+ - an OPER returns a user class, unlike PROC which returns nothing.
+ - this objet has a type and a name.
+ - rules : defines the structure of the dataset (if element A is present, element B has to be present also) or order of the commands (ie : element START is defined before END)
+
+ - concept : is a user defined class declaration. It can be used as a type for a parameter. Nothing is pre-judged about this class implementation. The actual definition/implementation can be found in the context of code project.
+
+Catalogs have a python syntax :ref:`python-label`
--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# MDM documentation build configuration file, created by
+# sphinx-quickstart on Thu Oct 1 10:55:47 2018.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# 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.todo']
+#extensions = []
+
+# 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-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'MDM'
+copyright = u'2019, Pascale Noyret - Eric Fayolle'
+
+# 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 = '0.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.alpha'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# 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 patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# 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'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> 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
+
+# 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_domain_indices = True
+
+# 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, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MDMDoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+ # get rid off blank pages
+ 'classoptions': ',openany,oneside',
+ 'babel' : '\\usepackage[english]{babel}',
+
+
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'MDM.tex', u'MDM Documentation',
+ u'Pascale Noyret - Eric Fayolle', '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
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'MDMdoc', u'MDM Documentation',
+ [u'Pascale Noyret - Eric Fayolle'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'MDM', u'MDM Documentation',
+ u'Pascale Noyret - Eric Fayolle', 'MDM', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+#TODO extension option :
+todo_include_todos=True
--- /dev/null
+.. _fact-label:
+
+Defining a Group of Keywords
+=============================
+
+Definition and Usage
+____________________
+
+| A group is a set of elements. Grouping these elements is meaningfull from a business data modeling perspective. These elements are either keywords or groups themselves.
+| A group has a parent : It is located in a command (in a PROC or OPER at the second level of the tree) or inside a group (BLOC or FACT).
+
+Syntax
+______
+
+General syntax
+~~~~~~~~~~~~~~
+
+Syntax is :
+::
+
+ myGroup = FACT (
+ ... #included SIMP or others FACT/BLOC
+ )
+
+"myGroup" is a python label. A group can not have the same name as its brothers.
+It contains simple elements or groups. There is no recursivity depth limit.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: job_properties
+ :end-at: #job_properties
+
+Definition of FACT including an other FACT :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: ThresholdExceedence
+ :end-at: #ThresholdExceedence
+
+
+Cardinality
+~~~~~~~~~~~
+It is possible to constrain the number of instances (cardinality) of a FACT. The cardinality is specified using the min and max attributes which specifies the minimum/maximum number of repetitions :
+ - If min=max=1 (default), the FACT appears only once in a valid dataset.
+ - If min=max=n the FACT appears n times in a valid dataset.
+ - If max > 1, the group of parameters can appear more than once.
+ - "**" means there is no upper limit for the maximal cardinality.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: species_parameters
+ :end-at: #species_parameters
+
+Note that a group status can be mandatory or optional. Regardless of its status, The group contains optional and mandatory elements. In the previous example, species_parameters has to be defined at least one time (in a valid dataset). Within this group, species_is_frozen is not mandatory. For each instance of species_parameters, species_is_frozen can appear or not.
+
+Other useful attributes
+~~~~~~~~~~~~~~~~~~~~~~~
+ +-------------+-------------------------------------------------+-----------+
+ |*attribute* |*Description* |*default* |
+ +=============+=================================================+===========+
+ | statut |status 'o' if mandatory and 'f' if not | f |
+ +-------------+-------------------------------------------------+-----------+
+ |ang |short documentation | |
+ +-------------+-------------------------------------------------+-----------+
+
--- /dev/null
+First notions of Catalogs
+==========================
+
+Catalog
+-------
+
+Catalogs are a simple way to express a data model.
+They organize the elements and specify the relationships between them.
+
+A Catalog defines the rules of parameters validity but also, and above all, the rules of consistency of a dataset, of its structure.
+For example, this means :
+
+ - the type and cardinality of elements,
+ - how to order the elements in their relationship to each other,
+ - the simultaneous (or exclusive) existence of certain parameters/groups of parameters.
+
+These rules ensure that a dataset is a consistent entity.
+
+Once the catalog is well-defined, EFICAS generates automatically an XSD file.
+These are two views of the same data model.
+
+The python user dataset and/or xml file(s) is/are validated and compliant(s) with the catalog and/or XSD file.
+The generated python/xml parameter files can be seen :
+
+ 1. as hierarchical data ordered in a tree.
+
+ 2. as an organized way of calling data object contructors with their parameters.
+
+ 3. as a set of computational steps (commands) with their arguments (very close to python code)
+
+| The data/commands roots are called steps.
+| A VIMMP user data/commands set is a collection of 'steps'.
+| Each step is a consistent process/part of the complete workflow/dataflow. This makes it possible to understand the complete workflow/dataflow schema.
+
--- /dev/null
+.. MDM documentation master file, created by sphinx-quickstart on Wed Sep 14 11:40:32 2011.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to MDM's documentation!
+==================================
+
+This documentation explains how you can create a data model with MDM and how you can use it to set or validate data.
+It is intended for developers to help them write data models, not an end-user documentation.
+
+
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ mdm_presentation
+ first_notions
+ simp.rst
+ fact.rst
+ bloc.rst
+ oper_and_proc.rst
+ structure_rules.rst
+ python_rules
+ xsd_mapping.rst
+ accasConnecteur.rst
--- /dev/null
+MDM Tool
+===========
+
+MDM DataModels Usage
+____________________
+
+MDM is designed to help code developpers. It allows to:
+
+ * simplify the writing of data models thanks to MDM definition specific langage (DSL) in python.
+ * automatically generate a corresponding unambiguous XSD description.
+ * offer dynamic validation which allows to take into account the value of certain parameters to activate specific parts of the model.
+ * maintain consistency between the version of the model expressed in the MDM grammar and the corresponding XSD version.
+ * validate datasets against these data models (one of them or both)
+ * use directly the produced XSDs (thanks to their unambiguity) in automatic driver generation tools (such as pyxb) and thus easely generate XML drivers (in C++ and Python) for input/output parameters.
+ * automatically generate an GUI which allows end users to write a specific code parameter file / dataset in xml or python format. This GUI frees the user from syntax and semantic issues and guarantees data integrity
+ * provide help to define the calculation scheme / calculation workflows in Salome environment.
+
+The dataset format is either python or XML, or both.
+A valid dataset conforms to the structure and the rules of the data model against both XSD and DSL python format.
+MDM is developped in python. For Gui Part, QT5 is needed.
+
+General Behaviour
+_________________
+
+ * Models
+ Most automatic driver generation tools require an XSD definition of the data model. However, writing a data model directly into XSD is often painful and time consuming.
+ the MDM grammar is used to express a data model faster in a python-like format (called catalog). MDM provides an .xsd mapping able to transcribe level of validation made in MDM. Translation from this grammar to XSD is done automatically. Resulting XSD are unambiguous and can also be used easely with automatic drivers generating tools. MDM allows to manages dynamic validation rules (a simple way to activate part of the XSD description according to the values of certain parameters,). It also provides a graphical (model-compliant) interface to create valid sets of documents / user data. In addition, this generated graphical representation allows a virtuous cycle between the design of the model and the visual representation.
+
+ An MDM catalog can contain other MDM catalogs. This means that others catalogs can be used to supplement the structure of another catalog through inclusion/import mechanisms.
+
+ * Data Sets
+ The available commands are defined in the data model.
+ In order to create a new valid data set, the end user can use the GUI and choose parameters/commands (parts of the XSD schema) from those available. He defines valid values for mandatory parameters (cardinality, type...) and adds optional parameters if necessary.
+
+ Data sets can be built/modified/validated by command line (TUI).
+
+refaire la phrase
+ The python/XML duality of the dataset expression allows on the one hand to execute the dataset in a proper python context, and/or, on the other hand to use it as a set of input parameters for code.
+
+ * Workflows
+ Workflows managed by an orchestrator such as the YACS module of the SALOME project manipulate the parameters to launch codes.
+ Some parameters are common to several workflows. With MDM, it is possible to define a common data model for launching workflows and to enrich it with specific data models for each code in each workflow node.
+
--- /dev/null
+.. _Defining-steps-in-a-catalog:
+
+Defining steps in a catalog
+===========================
+
+
+Step nodes
+__________
+
+
+General syntax
+~~~~~~~~~~~~~~
+A step can be :
+ * PROC : a simple procedure
+ * OPER : a command returning a concept/user type
+
+A PROC definition aggregates hierarchical data to express a consistent part of your modeling.
+
+::
+
+ MonPROC = PROC (nom = 'MonPROC', ..
+ );
+ MonOPER = OPER (nom = 'MonOPER', sd_prod= myUserClass,
+ );
+
+To describe a PROC, the attribute "name" is mandatory and must be the stringfield lvalue. Note that the variable name must begin with an **upper character**. Once a PROC or an OPER is defined you can add elements FACT, BLOC or SIMP inside .
+
+::
+
+ Solver_Input = PROC(nom = 'Solver_Input',
+ simulation_title = SIMP(statut='o', typ='TXM', defaut='Simple test'),
+ time_step = SIMP(statut='o', typ='R' , defaut=0.01 , val_min=0),
+ number_of_steps = SIMP(statut='o', typ='I' , defaut=10000, val_min=1),
+ number_of_equilibration_steps = SIMP(statut='o', typ='I' , defaut=1000 , val_min=1),
+ job_properties= FACT(statut='o',
+ job_duration = SIMP(statut='o', typ='R' , defaut=1000, val_min=0),
+ stack_size = SIMP(statut='f', typ='R' , defaut=1000, val_min=0),
+ print_frequency = SIMP(statut='f', typ='TXM', defaut='every', into=['every','never','sometimes']),
+ close_time = SIMP(statut='f', typ='R' , defaut=1000, val_min=0),
+ ),
+ );
+
+.. _Defining-a-concept-type-user:
+
+Defining a concept type / user type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An OPER definition agregates hierarchical data in order to express a coherent part of your modelisation.
+Despite a PROC, an OPER produces a new data(object) that you can reuse in further defintion.
+An oper can be considered as a function call with many parameters more or less complex and which returns a new one.
+
+To describe an OPER , you have first to describe a user-defined concept type.
+Declarations appear at the beginning of the catalogs. User classes inherits from ASSD. Most of the time the pass statement is all you need to write.
+
+::
+
+ from Accas import *
+ class myInteger(ASSD) : pass
+ class mesh(ASSD) : pass
+ class meshEntity(ASSD) : pass
+ class meshNode(meshEntity) : pass
+ class meshEdges(meshEntity): pass
+ class field(ASSD) : pass
+
+OPERs return value. The return_type is a user-defined data type.
+
+::
+
+ class mesh(ASSD) : pass
+ ReadMesh = OPER (nom = 'ReadMesh', sd_prod = mesh,
+ MyFile= (typ=’Fichier’, statut ='o'),
+ );
+ CalculateField = OPER( nom = 'CalculateField', sd_prod=field,
+ is_on_mesh=SIMP(typ=mesh, statut='o'),
+ calculFunction = FACT(...),
+ );
+
+
+::
+
+ mymesh = ReadMesh(MyFile="/tmp/vimmp.mesh");
+ myField = CalculateField(is_on_mesh=mymesh, calculFunction=...);
+
+The end user can define a mesh with ReadMesh OPER (This mesh will be named) and then use this mesh in order to defined a Field....
+
+Other useful attributes
+~~~~~~~~~~~~~~~~~~~~~~~
+ +-------------+-------------------------------------------------+-----------+
+ |*attribute* |*Description* |*default* |
+ +=============+=================================================+===========+
+ | statut |status 'o' if mandatory and 'f' if not | f |
+ +-------------+-------------------------------------------------+-----------+
+ |ang |short documentation | |
+ +-------------+-------------------------------------------------+-----------+
+
--- /dev/null
+.. _python-label:
+
+===============================
+Rules for python syntax
+===============================
+
+Variable names and identifiers are similar to those in many other languages :
+-----------------------------------------------------------------------------
+
+* They start with a letter (A_Z or a-z) or an underscore "_"".
+* They are followed by letters, numbers or underscores.
+* They are case-sensitive.
+* A string is a sequence of caracters enclosed by a pair of matching single or double quotation marks.
+
+
+
+Some identifiers are reserved words :
+-------------------------------------
+
+* You cannot use words of the python language as identifiers.
+* Some identifiers are reserved words. For example, you cannot use the following words, even if they sound like interesting names:
+ - ASSD, BLOC, EXCLUS,
+ - ENTITE, ETAPE, EVAL, , JDC
+ - OPER, PROC,
+ - REGLE, VALIDATOR
+
+
+Catalogs are executable python files:
+-------------------------------------
+Keep in mind that :
+
+* The simplest form of assignement is : variable = value
+* The hash character (#) starts a comment
+* Tuples are enclosed in square brackets.
+* Lists are enclosed in parentheses.
+* Brackets have to be closed.
+* To create a list, elements must be separated by ','. Do not forget this ',' even if the list contains only one element.
+* If necessary, classes or functions must be defined.
+* Arguments are separated with ','
+
+::
+
+ #code python :
+ time_step = SIMP(statut='o', typ='R',)
+
+This is a instantiation operation. It creates an object of type SIMP. the SIMP __init__() is called with two arguments statut and typ.
+
+You must respect the python syntax and remember that the commands (OPER and PROC) must begin with a capital letter.
+
+
--- /dev/null
+Defining a Keyword
+===================
+
+Definition and Usage
+____________________
+
+A model keyword defines an input parameter. It specifies the information (ie name, type) and some of the constraints on the parameter value.
+A model keyword has a parent : it is located in a command (in a PROC or OPER at the second level of the tree) or within a group (BLOC or FACT).
+
+Syntax
+______
+
+
+General syntax
+~~~~~~~~~~~~~~
+
+Source line code is :
+::
+
+ myKeyword = SIMP (typ = 'R')
+
+| The *typ* attribute precises the type of keyword (in this case, float)
+| "myKeyword" is the name of the keyword. It is a python label. A keyword can not have the same name as its brothers.
+| The *typ* attribute is mandatory. The other SIMP attributes (see below) have a default value and are optional.
+
+
+Typ
+~~~
+
+The *typ* attribute can take the following values :
+
+ - A simple type :
+ * boolean (bool)
+ * integer (I)
+ * float (R)
+ * complex (C)
+ * text (TXM)
+
+ Examples :
+
+ ::
+
+ number_of_species = SIMP( typ='I' ),
+ YoungModulus = SIMP( typ='R' ),
+ electrostatics_is_on = SIMP( typ=bool, ),
+
+
+ * Valid values for number_of_species : 1, -6, 128
+ * Valid values for YoungModulus : 1, 110.3, -6., 14.5×10−3
+ * Valid values for electrostatics_is_on : True, False , 0, 1
+ |
+
+ - A tuple of N elements (Tuple(3)).
+
+ * Within each tuple, each model element has a specified type.
+
+ ::
+
+ pair_identification = SIMP(statut ='o', typ=Tuple(2), validators=VerifTypeTuple(('TXM','TXM' )),),
+ simulation_box_sizes = SIMP(statut ='o', typ=Tuple(3), validators=VerifTypeTuple(('R' ,'R', 'R')),),
+ length = SIMP(statut ='o', typ=Tuple(2), validators=VerifTypeTuple(('R' ,'TXM' )),),
+
+
+ means that pair_identification is a tuple of two strings, simulation_box_sizes a tuple of three floats and length a tuple whose first parameter is a float and second one a string.
+
+ * Valid values for pair_identification : ('A', 'A'), ('A','B')
+ * Valid values for simulation_box_sizes : (1,1.,0), (2.,-2.5, 10+3)
+ * Valid values for length : (1,'m'), (2., 'cm') but also (and badly) (-500, 'Fahr') or (32, 'fareneit')
+
+ .. note:: A tuple element is not seen as a list but as ONE element. (it is possible to define list of tuple -see the paragraph 'cardinality' )
+
+
+ - A directory or a file (existing or not)
+
+ +-------------------------------------+-----------------------------------------------------+
+ | parameter is : | catalog's description is : |
+ +=====================================+=====================================================+
+ |an existing file | typ='Fichier' |
+ +-------------------------------------+-----------------------------------------------------+
+ |a directory | typ='Repertoire' |
+ +-------------------------------------+-----------------------------------------------------+
+ |an existing file with specific suffix| typ=('Fichier','JDC Files (*.comm);;All Files (*)') |
+ +-------------------------------------+-----------------------------------------------------+
+ |a non-existing file | typ=('Fichier',"",'Sauvegarde'), |
+ +-------------------------------------+-----------------------------------------------------+
+ |a file (existing or not) | typ='FichierNoAbs' |
+ +-------------------------------------+-----------------------------------------------------+
+ |a file or a directory | typ='FichierOuRepertoire' |
+ +-------------------------------------+-----------------------------------------------------+
+
+ .. note:: To filter filenames, you have to set the *typ* attribute with a python tuple :
+
+ * The first element is a fixed string value : *'Fichier'* , *'Repertoire'* , *'FichierNoAbs'* , *'FichierOuRepertoire'*
+ * The second element is a Qt filter string as defined by QT. This string is only used by the graphical interface. The filter is inactive for *typ* *'Repertoire'* .
+ * The third element is only used with the value *'Sauvegarde'* in the triple *('Fichier',"",'Sauvegarde')* to activate the non-existing file usecase.
+
+ - Or previously user defined type in the catalog (a mesh for example)
+
+ A user-defined class inherits from the class ASSD
+
+ ::
+
+ class mesh (ASSD) : pass
+ myMesh=SIMP(typ = 'mesh')
+
+ In this case, myMesh is a keyword waiting for a mesh instance. This instance has to be created with an OPER command.
+ (todo label)
+
+
+Cardinality
+~~~~~~~~~~~
+It is possible to constrain the number of occurences (cardinality) of a keyword. The cardinality is set using the min and max attributes.
+If min=max=1 (default), the keyword is only one (unique) value. if max > 1, parameter is a list. min/max specify the minimum/maximum number of occurences in the list. 'max= "**"' does not set an upper limit for the maximum cardinality, but allows you to enter as many values as needed.
+
+.. code-block:: python
+
+ scalar = SIMP(typ = 'R')
+ list_of_scalars = SIMP(typ = 'R',max="**")
+ list_of_3_to_5_scalars= SIMP(typ = 'R',max=5, min=3)
+
+
+* Valid values for scalar : 1., 2.,
+* Valid values for list_of_scalars : (1.,1.,0), (2.,5., 7.,8,.,... 999.), (1.,)
+* Valid values for list_of_3_to_5_scalars : (1.,1.,1), (1.,1.,1.,1.),(1.,1.,1.)
+
+Note that a list may be mandatory or optional.
+
+
+Other useful attributes
+~~~~~~~~~~~~~~~~~~~~~~~
+ +-------------+-------------------------------------------------+-----------+
+ |*attribute* |*Description* |*default* |
+ +=============+=================================================+===========+
+ | statut |status 'o' if mandatory and 'f' if not | f |
+ +-------------+-------------------------------------------------+-----------+
+ |into |finite set of value | None |
+ +-------------+-------------------------------------------------+-----------+
+ |val_min |minimal value |float(-inf)|
+ +-------------+-------------------------------------------------+-----------+
+ |val_max |maximal value |float(inf) |
+ +-------------+-------------------------------------------------+-----------+
+ |ang |short documentation | None |
+ +-------------+-------------------------------------------------+-----------+
+ |defaut |default value | None |
+ +-------------+-------------------------------------------------+-----------+
+
+ And some examples :
+
+.. code-block:: python
+
+ print_frequency = SIMP(statut='f', typ='TXM', defaut='every', into=['every','never','10 steps'])
+ close_time = SIMP(statut='f', typ='R' , defaut=1000, val_min=0)
+ number_of_steps = SIMP(statut='f', typ='I' , defaut=100 , val_min=0, val_max=1000)
+
+
+* Valid values for print_frequency : 'every','never','10 steps' and nothing else
+* Valid values for close_time : positive float (not nul)
+* Valid values for number_of_steps : integer between 1 and 999
+
+
--- /dev/null
+.. _rules-label:
+
+Defining rules
+==============
+
+Definition and Usage
+____________________
+
+Sometimes the user wants his data to comply with certain construction rules.
+These rules affect the structure of the user's data set (not the value).
+They can be applied to any entity (OPER, PROC, JDC, BLOC or MYCONCEPT).
+
+Syntax
+______
+
+General syntax
+~~~~~~~~~~~~~~
+
+Syntax is :
+::
+
+ regles = (..list of rules),
+
+
+AU_MOINS_UN
+-----------
+AU_MOINS_UN rule requires to create at least one eficas_keyword from the list. More than one can be created.
+::
+
+ Structure = FACT ( statut ='f',
+ regles = (AU_MOINS_UN( 'Beam', 'Bar', 'Grid'),)
+ Beam = FACT (...),
+ Bar = FACT (...),
+ Grid = FACT (...),
+ );
+
+If 'Structure' is defined, one of the keyword 'Beam', 'Bar', 'Grid' is also defined.
+ * If none of these keywords is present, the structure is invalid.
+ * If only the word "Beam" is present, the structure is valid.
+ * If both keywords "Beam" and "Bar" are present, the structure is valid.
+
+UN_PARMI
+--------
+UN_PARMI rule forces the end user to create one and only one eficas_keyword from the list.
+::
+
+ FOR_DPD = BLOC(condition = "code=='DPD'",
+ regles=(UN_PARMI('Initialisation', 'Solver_Input'),
+ ),
+ ...),
+
+The end user must select 'Initialisation' or (exclusive or) 'Solver_Input'.
+
+ * If the user does not select any of these keywords, the dataset is invalid.
+ * If he selects only 'Solver_Input', the dataset is valid.
+ * If he selects only 'Initialisation', the dataset is valid.
+ * If he selects both, the dataset is invalid. (Ihm will not proposed the keyword 'Initialisation' if 'Solver_Input' already exists.)
+
+
+EXCLUS
+------
+EXCLUS means that, if one of the eficas_keyword is created, the others will not be allowed.
+::
+
+ JOB_DURATION = FACT(statut='o',
+ regles=( EXCLUS('duration','number_of_time_step','end_at'),
+ ),
+ ...),
+
+
+Only one or none of the keyword are allowed.
+ * If the user does not select any of these keywords, JOB_DURATION is valid.
+ * If he only selects 'duration', JOB_DURATION is valid.
+ * If he only selects 'number_of_time_step', JOB_DURATION is valid.
+ * If he only selects 'end_at', JOB_DURATION is valid.
+ * Otherwise, JOB_DURATION is invalid
+
+ENSEMBLE
+--------
+The rule means that if one eficas_keyword is selected, the others must be selected as well.
+::
+
+ GRILLE = FACT(statut='f',
+ regles=( ENSEMBLE('ORIG_AXE','AXE'),
+ ),
+ ...),
+
+if GRILLE is used in the dataset
+ * If the user does not select any of these keywords, GRILLE is valid.
+ * If he selects only 'ORIG_AXE', GRILLE is invalid.
+ * If he selects both 'ORIG_AXE' and 'AXE', GRILLE is valid.
+
+
+PRESENT_PRESENT
+---------------
+The rule means that if the FIRST eficas_keyword is selected, the others must be selected as well.
+::
+
+ FREQUENCE = FACT(statut='f',
+ regles=( PRESENT_PRESENT('FREQ_MIN','FREQ_MAX','FREQ_PAS')
+ ),
+ ...),
+
+That means :
+
+ * If the user does not select any of these keywords, 'FREQUENCE' is valid.
+ * If he selects only 'FREQ_MAX', 'FREQUENCE' is valid.
+ * If he selects only 'FREQ_MIN', 'FREQUENCE' is invalid.
+ * If he selects both 'FREQ_MIN', 'FREQ_MAX' and 'FREQ_PAS', 'FREQUENCE' is valid.
+
+
+PRESENT_ABSENT
+--------------
+The rule means that if the FIRST eficas_keyword is selected, the others are not allowed.
+::
+
+ GRID = FACT(statut='f',
+ regles=( PRESENT_ABSENT('GroupOfNodes','GroupOfFaces','GroupOfEdges'),
+ ),
+ ...),
+
+This means :
+
+ * If the user does not select any of these keywords, 'GRID' is valid.
+ * If he selects only 'GroupOfNodes', 'GRID' is valid.
+ * If he selects both 'GroupOfFaces' and 'GroupOfNodes', 'GRID' is invalid.
+
+
+All rules can be combinated, which creates more complicated rules.
+
+::
+
+ GRID = FACT(statut='f',
+ regles=( PRESENT_ABSENT('GroupOfNodes','GroupOfFaces','GroupOfEdges'),
+ ENSEMBLE('GroupOfFaces','GroupOfEdges'),
+ ),
+ ...),
+
+
+That means :
+
+ * If the user select 'GroupOfNodes', GRID is valid.
+ * If the user select 'GroupOfFaces' and 'GroupOfEdges', GRID is valid.
+ * If he selects none of these keywords GRID is valid.
+ * Otherwise 'GRID' is invalid
--- /dev/null
+VIMMP DataModel
+===============
+
+Definition and Usage
+____________________
+
+The VIMMP data model is designed to help code developers:
+ * Automatically generate XML drivers for input / output parameters
+ * Allow users to write a specific code parameter file in xml or python format. It deals with syntax and semantics issues ensuring the integrity of the file.
+ * Provide help to define the calculation scheme
+
+The generated python input parameter files can also be seen as a way to supervise a set of computational steps (commands) with their arguments.
+The available commands are defined by the data model (also called catalog).
+Building a new user data set that conforms to a data model consists of choosing the desired commands from the available commands.
+Each selected command has its specific parameters that the user must define. Some are required, some require multiple occurrences, others require the user to name the returned concept.
+
+
+General Behaviour
+_________________
+
+Xml driver generation requires an XML schema definition describing the data model.
+You may be writing your data model in XSD, but it will be painful and time consuming.
+In addition, there are several ways to describe the same model in XSD.
+Eficas tool is useful to describe quickly your data model in a catalog and will provides you an .xsd mapping involving easy to use generated drivers.
+Eficas manages dynamic validation rules and also provides a graphical (model-compliant) interface for creating valid sets of documents / user data.
+
+
+Common Data Model
+_________________
+
+The set of VIMMP usecases are converted into executable workflows managed by an orchestrator as YACS module of the SALOME project.
+These workflows manipulate parameters to launch the different codes.
+Some parameters are common to multiple workflows and define the VIMMP common data model for launching the workflows.
+
+Specific Data Model
+___________________
+
+Some parameters are specific to a workflow/a code and is useless to the others.
+However they are needed to launch the workflow then you will have to define the VIMMP specific data model for being able to launch the workflows.
+
+
+
--- /dev/null
+.. _mapping-label:
+
+..
+ Le TEST_ROOT n'est pas évalué dans le literalinclude
+.. |TEST_ROOT| replace:: ../Tests/MappingAccasXsd/
+.. |cata_1.py| replace:: :download:`cata_1.py <../Tests/MappingAccasXsd/cata_1.py>`
+.. |cata_1.xsd| replace:: :download:`cata_1.xsd <../Tests/MappingAccasXsd/cata_1.xsd>`
+.. |cata_1_test1.xml| replace:: :download:`cata_1_test_1.xml <../Tests/MappingAccasXsd/cata_1_test_1.xml>`
+
+Generating the XSD file from the catalog file
+=============================================
+
+generateXSD command
+____________________
+
+To obtain the |cata_1.xsd| file corresponding to the |cata_1.py| file just enter ::
+
+ python ./generateXSD.py -c ./cata_1.py
+
+
+Here is the interesting part of |cata_1.py| content.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-after: beginJdC
+ :end-before: endJdC
+
+
+The generateXSD command has created the |cata_1.xsd| file.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+
+You may check it with xmllint command.
+You may visualize it with xsddiagram command.
+
+Using PyXB to generate drivers
+______________________________
+
+Using the XSD model file to get an XML generated driver is as simple as typing ::
+
+ pyxbgen -m cata_1_genere -u cata_1.xsd --write-for-customization
+
+It will create an raw/ directory containing various classes imported from the ./cata_1_genere.py file.
+
+
+Using PyXB generated drivers
+_____________________________
+
+You can use the driver to load an xml file like |cata_1_test1.xml| conforming to the |cata_1.xsd| file.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_test_1.py
+ :end-before: CONFIGURATION
+
+Once the .xml file is loaded you can display it in a pretty xml format.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_test_1.py
+ :start-after: _setOrphanElementInContent
+
+Understanding the XSD mapping for SIMP
+______________________________________
+
+SIMP for type simple type {'I','R', bool, 'TXM'}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Declaring an SIMP with a *type* attribute
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *SIMP* is mapped to an xsd global type and an xsd element.
+The xsd element is defined locally and may appear multiple times depending on the use the catalog does of it.
+
+If we look at the test_simp_2 in |cata_1.py| content, we get an example of an *SIMP* of *type* 'I' (int type).
+
+.. todo::
+ Give the possibility of customizing the xsd type used by an eficas type
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2
+ :end-at: test_simp_2
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2"
+ :end-at: /xs:simpleType
+
+An XSD element local declaration using this type is obviously defined since we declare it in the catalog :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2"
+ :end-at: name="test_simp_2"
+
+You may notice that the XSD elements attributes **minOccurs** and **maxOccurs** are defined by default to 1 since the *statut* attribute is obligatory *'o'*.
+The XSD attribute **default** value is set to 2 conforming to the catalog *defaut* attribute.
+
+.. note::
+ * The xsd **minOccurs** attribute value of an element declaration that comes from an *SIMP* is either 0 or 1.
+ * The xsd **maxOccurs** attribute value of an element declaration that comes from an *SIMP* will alway be 1.
+
+If we look at the test_simp_4 in |cata_1.py| content, we get an example of an *SIMP* of *type* bool (boolean type).
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_4
+ :end-at: test_simp_4
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_4"
+ :end-at: /xs:simpleType
+
+And the XSD element local declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_4"
+ :end-at: name="test_simp_4"
+
+.. note:: Notice that the eficas *defaut* attribute is set to the python value True and the **default** xsd attribute is set to the xsd value true
+
+.. note:: If two *SIMP* have the same name (so, not sibling *SIMP* ) and different *type* attributes, there will be two local element declarations with the same name and two global xsd **type** with two different typenames
+
+
+Defining how many times a *SIMP* may appear
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If we look at the test_simp_2_3 in |cata_1.py| content, we get an example of an *SIMP* of type 'I' using *min* and *max* attributes.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_3
+ :end-at: test_simp_2_3
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_3"
+ :end-before: T_test_simp_2_4
+
+..
+ ATTENTION, JE N'AI PAS TROUVE UNE MEILLEURE BALISE DE FIN que le nom du test suivant : T_test_simp_2_4.
+
+You may notice that the XSD type is very different from the **T_test_simp_2** one.
+This is because the XSD list type is used for multiple occurrences of a *SIMP* and the XSD list must be derived by restriction to get our own list type.
+
+An XSD element declaration using this type is also defined as for test_simp2 :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2_3"
+ :end-at: name="test_simp_2_3"
+
+You may notice that the minimum and maximum sizes of an XSD list are defined in the type definition thanks to a facet :
+
+.. code-block:: xml
+
+ <xs:minLength value = "3"/>
+
+
+Remind that in XSD, if there is no **maxLength** facet definition, the size of the list is considered unlimited.
+If a *max* eficas attribute is set to a number instead of '**' you get a additional **maxLength** xsd attribute as for type *test_simp_2_4* :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_4
+ :end-at: test_simp_2_4
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_4"
+ :end-before: T_test_simp_2_5
+
+The XSD elements attributes **minOccurs** and **maxOccurs** are also defined to 1 conforming to the *statut* value *'o'*.
+
+Defining an *SIMP* default value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *defaut* eficas attribute provide a way to give a default value to an *SIMP* if it isn't defined by the user :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_5
+ :end-at: test_simp_2_5
+
+The *defaut* eficas attribute take into account the *min* and *max* eficas attribute. The number of values given in the *defaut* must be in the inclusive [ *min*, *max* ] range.
+
+If we look at the XSD element declaration, you can see the **default** xsd attribute which is set to a list of 4 numbers.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2_5"
+ :end-at: name="test_simp_2_5"
+
+..
+ ATTENTION, si un type T_test_simp_2_6 est défini, il faut modifier la balise de fin à cette valeur
+
+We observe that :
+ * the value of the XSD attribute **default** is set to a list conforming to the catalog *defaut* attribute
+ * the XSD elements attributes **minOccurs** is set to 0 conforming to the *statut* value *'f'*.
+
+.. note:: As you may have already noticed, some eficas *attribute* may be mapped to the **xsd type** and others to the **element declaration**.
+
+Constraining the range of possible values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Thanks to *val_min*, *val_max*, and *into* eficas attributes you may constraint the range of values allowed for the elements.
+Here is an example of produced **xsd type** for *val_min*, *val_max* usage :
+
+When we define the fololwing eficas keyword with *val_min*, *val_max* attributes
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_1
+ :end-at: test_simp_2_1
+
+The corresponding generated XSD type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_1"
+ :end-before: T_test_simp_2_2
+
+When we define the following eficas keyword with *into* attribute :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_2
+ :end-at: test_simp_2_2
+
+The corresponding mapped XSD type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_2"
+ :end-before: T_test_simp_2_3
+
+The use of the *into* attribute implies a xsd type definition using **xsd enumeration**.
+
+.. note:: Hence it's possible to define an *into* attribute with an *SIMP* of *type* 'R', it is generaly not very useful
+
+Declaring an SIMP with a *type* 'TXM' with an occurence of 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of 'TXM' type is quite the same as 'I' or 'R' types.
+Here is an example for a SIMP with type 'TXM' :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_1_1
+ :end-at: test_simp_1_1
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_1_1"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_1_1"
+ :end-at: name="test_simp_1_1"
+
+
+Declaring an SIMP with a *type* 'TXM' with an occurence > 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Here is an example for a SIMP with type 'TXM' with multiple ocurrences :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_1_3
+ :end-before: test_simp_2
+..
+ ATTENTION, si un type T_test_simp_1_4 est défini, il faut modifier la balise de fin à cette valeur
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_1_3"
+ :end-before: T_test_simp_2
+..
+ ATTENTION, si un type T_test_simp_1_4 est défini, il faut modifier la balise de fin à cette valeur
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_1_3"
+ :end-at: name="test_simp_1_3"
+
+.. note::
+ * The use of eficas *attributes* *val_min* and *val_max* for *type* == 'TXM' may be used to enforce values to be between the *val_min* , *val_max* strings in alphabetical order. The use of eficas *validator* keyword is a better way to check regexp for string values
+ * The use of eficas *attributes* *into* is often very convenient to enforce the only predefined possible strings
+
+.. note::
+ * Since the xsd type used to map the eficas attribute *max* when it is >1 is a **list** and since the xsd **list** separator is a space character then you can't use a space character in your strings
+ * The xsd type **list** used to map eficas attribute *max* when it is >1 is a choice of mapping which avoid the use of an xml element for each value in the .xml dataset file. Even if you can't express the direct access to an element of the list in the xpath language, it's not an issue in the PyxB generated driver because you get a Python list with its classic acessors
+
+SIMP with type { 'Fichier', 'Repertoire', 'FichierOuRepertoire', 'FichierNoAbs' }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whatever the *typ* is for managing file or directory, by now the xsd mapping is a simple string.
+There are possible improvements such as managing xsd regexp expression.
+
+Here is an example for a SIMP with type 'Fichier' with a filename filter :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_7_4
+ :end-at: test_simp_7_4
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_7_4"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_7_4"
+ :end-at: name="test_simp_7_4"
+
+.. note:: It could be useful to define a specic xsd type for using a well-known type for managing files and directories.
+
+
+SIMP of UserASSD type
+~~~~~~~~~~~~~~~~~~~~~~
+An SIMP may have a user defined type.
+Depending on the way you declare the SIMP, you can either create a new data or refer to a previoulsy created one.
+
+Declaration of an UserASSD type SIMP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Here is a declaration example for a SIMP with user type *User_Data* :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: class User_Data
+ :end-at: class User_Data
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_8_1
+ :end-at: test_simp_8_1
+
+The *UserASSD* class declared this way is quite the same notion as using an *ASSD* class in an *OPER* command (:ref:`Defining a concept type <Defining-a-concept-type-user>`). The *UserASSD* differs from an ASSD by :
+ * the *UserASSD* *SIMP* can be declared where ever you like in the catalog (not just at first level like for an *OPER*)
+ * the generated python code (.comm) will call the object constructor of the *UserASSD* type with no parameter
+
+.. todo:: Expliciter le mécanisme en oeuvre au niveau python.
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_8_1"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_8_1"
+ :end-at: name="test_simp_8_1"
+
+Referencing a UserASSD type SIMP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *SIMP* reference is done this way:
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_8_2
+ :end-at: test_simp_8_2
+
+Note the User_Data type given to the *typ* attribute.
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_test_simp_8_2"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_8_2"
+ :end-at: name="test_simp_8_2"
+
+SIMP for complex type {'C'}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not yet implemented !
+
+SIMP for type {Tuple}
+~~~~~~~~~~~~~~~~~~~~~
+
+Not yet implemented !
+
+
+Understanding the XSD mapping for JdC, OPER and PROC
+____________________________________________________
+
+The JdC root level
+~~~~~~~~~~~~~~~~~~
+
+As explained in section :ref:`Defining steps in a catalog<Defining-steps-in-a-catalog>` OPER and PROC commands are the very first keywords that appears under the root node. They both provide a way to agregate data.
+
+
+The *OPER* command returns a user type while a *PROC* doesn't and just agregate a first level coherent set of data.
+
+If we have a look to a JdC definition :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: JDC_CATA
+ :end-at: JDC_CATA
+
+We notice that the *code* parameter declares the name of the code for which the catalog is written.
+The xsd mapping is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_Test1"
+ :end-at: /xs:complexType
+
+The **xsd:choice** with a **maxOccurs=unbounded** is used because the user may choose how many *PROC* / *OPER* he/she wants and in the order he/she decided.
+
+The root element declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="Test1"
+ :end-at: name="Test1"
+
+The name of the element comes from the *code* parameter previously defined.
+You find all the element declarations that come from all the *PROC* / *OPER* declared in the catalog.
+
+.. note:: For generate drivers with PyXB, it's a really bad idea to define xsd **element** with **maxOccurs** > 1 in a **xs:choice** with a **maxOccurs** == 'unbounded'. Despite the generate code is correct, it produce a python class unusable since the PyXB Finite Automate with Counter can't decide from which schema component two elements of the same type comes from. This ambighuity interrupt the xml production from your python object.
+
+.. note:: TODO : We have to explain the way we use the schema namespaces.
+
+The OPER command
+~~~~~~~~~~~~~~~~
+
+
+The *OPER* command returns an *ASSD* type (not a *UserASSD*).
+An *ASSD* type provides the ability to declare and use a user class in a eficas catalog.
+
+Producing an *ASSD* :
+^^^^^^^^^^^^^^^^^^^^^
+
+After having declared the new typename *ASSD* :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: class Mesh
+ :end-at: class Mesh
+
+The *OPER* command describes a way to create user type instances :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: ReadMesh
+ :end-at: ,)
+
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_ReadMesh"
+ :end-at: /xs:complexType
+
+.. note::
+ * The **attribute** 'name' is used in the xml dataset to hold the name of the user data *Mesh*.
+ * The two xsd **attribute** 'accasType' and 'typeUtilisateur' are for eficas internal use
+
+The element declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="ReadMesh"
+ :end-at: name="ReadMesh"
+
+Using an already produced *ASSD* object :
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to declare in a catalog that a specific data of the dataset is a reuse of an already produced data by an *OPER*, you have to declare it within an SIMP. This SIMP must have the *typ* attribute equals to the *sd_prod* attribute value of the corresponding *OPER* :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: MyField
+ :end-at: ,)
+
+You get the xsd types :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_MyField"
+ :end-at: /xs:complexType
+
+.. todo:: Revisit the statut attribute use, here if you don't set statut='o' you have **minOccurs** == 0
+
+and
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_onMesh"
+ :end-at: /xs:simpleType
+
+
+Concerning the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="MyField"
+ :end-at: name="MyField"
+
+The way we choose to map the *OPER* to xsd allows users to create a cross reference system using name of produced structure in their dataset.
+
+.. todo:: Generate a schema validation rule to check that a name used as a reference is unique and exists in the corresponding object, we have to add in the root element declaration the following code :
+
+.. code-block:: xml
+
+ <xs:key name="Key_Name_In_CreateMesh">
+ <xs:selector xpath="./Test1:CreateMesh"/>
+ <xs:field xpath="./@nom"/>
+ </xs:key>
+
+ <xs:keyref name="MyField_Ref_A_CreateMesh" refer="Test1:Key_Name_In_CreateMesh">
+ <xs:selector xpath="./Test1:MyField/Test1:onMesh"/>
+ <xs:field xpath="."/>
+ </xs:keyref>
+
+.. note:: PyXB doesn't care about these rules, it relies on the sax/dom parsers capabilities. By default, using the libxml library, these checks are not performed. Anyway it's always possible to fully validate xml datasets by using a parser which have this kind of capability.
+
+.. todo:: PyXB doesn't automaticaly create links between the objects using the ref name contract. Either the user have to recrate the links or we have to provide a PyXB extension to do so.
+
+The PROC command
+~~~~~~~~~~~~~~~~
+
+The *PROC* command agregates a first level coherent set of data.
+
+The *PROC* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: Test_proc_2
+ :end-at: Test_proc_2
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_Test_proc_2"
+ :end-at: /xs:complexType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="Test_proc_2"
+ :end-at: name="Test_proc_2"
+
+Declaring an SIMP of type UserASSD in a PROC or a FACT :
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is a *PROC* declaration using an SIMP UserASSD :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: class MeshU
+ :end-at: class MeshU
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: Meshes
+ :end-at: #Meshes
+
+You get the *PROC* xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_Meshes"
+ :end-at: /xs:complexType
+
+And the associated element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="Meshes"
+ :end-at: name="Meshes"
+
+.. todo:: We will have an eficas *xsdattribute* attribute to get the *SIMP* as an xsd attribute instead of an xsd element
+
+Concerning the *FACT* xsd type, you get :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_mesh"
+ :end-at: /xs:complexType
+
+The *SIMP* of UserASSD type becomes :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_name"
+ :end-at: /xs:simpleType
+
+Using an already defined SIMP of type UserASSD :
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to declare somewhere in a catalog that a specific data is a reuse of an already defined *UserASSD* *SIMP* data, you have to declare it within an SIMP of type *UserASSD* thanks to the *typ* attribute :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: MyFieldBis
+ :end-at: ,)
+
+.. note:: Note that this is exactly the same as using an *ASSD* provided by an *OPER*.
+
+You get the xsd types :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_MyFieldBis"
+ :end-at: /xs:complexType
+
+and
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_onMesh_1"
+ :end-at: /xs:simpleType
+
+
+Concerning the element declaration, you get :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="MyFieldBis"
+ :end-at: name="MyFieldBis"
+
+.. note:: The string **onMesh** element value must be a valid name of a **name** element value from a **mesh** element.
+
+.. todo:: We have to write a rule to check this.
+
+
+Understanding the XSD mapping for FACT
+______________________________________
+
+As explain in :ref:`fact-label` section, the *FACT* keyword provide a way of grouping elements. It may appear *PROC*, *OPER*, *BLOC* or *FACT*. If we review the following catalog from the :ref:`fact-label` section :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: ThresholdExceedence
+ :end-at: #ThresholdExceedence
+
+You get the two xsd complex types using the **<xs:sequence>** xsd element :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_ThresholdExceedence"
+ :end-at: /xs:complexType
+
+and
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_Event"
+ :end-at: /xs:complexType
+
+
+The element declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="ThresholdExceedence"
+ :end-at: name="ThresholdExceedence"
+
+In order to illustrate the management of the cardinality, we can review the second example from the :ref:`fact-label` section :
+
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: species_parameters
+ :end-at: #species_parameters
+
+You get the xsd complex types using the **<xs:sequence>** xsd element :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_species_parameters"
+ :end-at: /xs:complexType
+
+
+The element declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="species_parameters"
+ :end-at: name="species_parameters"
+
+.. note:: The *FACT* cardinality is carry out by the **maxOccurs** attribute of the element declaration. The **minOccurs** attribute deserve the *statut* eficas attribute.
+
+Understanding the XSD mapping for BLOC
+______________________________________
+
+As explain in :ref:`bloc-label` section, the *BLOC* keyword provides a conditional way to activate a group of elements. Apart from the *condition* eficas attribute, it's quite the same as the *FACT* keyword.
+
+If we review the following catalog from the :ref:`fact-label` section :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-after: Test_proc_5
+ :end-before: #Test_proc_5
+
+The xsd mapping provides two **<xs:group>** elements :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_frequency_every"
+ :end-at: /xs:group
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :start-at: name="T_frequ_not_every"
+ :end-at: /xs:group
+
+The parent xsd type uses **group ref** declarations :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.xsd
+ :language: xml
+ :dedent: 2
+ :start-after: name="T_Test_proc_5"
+ :end-before: /xs:complexType
+
+The content of these groups may appear or not in the parent structure.
+Using **group ref** allows the apparition of group content without any additionnal element level.
+Considering the *BLOC* semantic, the **minOccurs** attribute is always 0 and **maxOccurs** is always 1.
+
+.. note:: An ambiguity problem may appear if an element with the same name is present in different group's contents.
+
+.. todo:: The *BLOC* xsd mapping must be refine. We may use **key**, **keyref** xsd element to restrict the possibility of activating only one branch of the conditional. However, the semantic of the *BLOC* keyword is wide.
+
+We may have that kind of usescases :
+ * A conditional E1 python expression for a B1 bloc with content C1 following a not(E1) expression for a B2 bloc with content C2
+ * A conditional E1 python expression for a B1 bloc with content C1 following a not(E1) expression for a B2 bloc with content almost C1, the difference being the type of an SIMP with the same name
+ * A conditional E1 python expression for a B1 bloc with content C1 following a E2 expression for a B2 bloc with content C2 including partially or totally C1
+ * ....
+
+
+
+Understanding the XSD mapping for included catalogs
+___________________________________________________
+
+Eficas offers the possibility to include one catalog from an other. There will be a main catalog from which the *JdC* keyword is defined and non-main catalogs from which there is no *JdC* keyword. A catalog may be included mutiple times in different catalogs. Whatever the catalog is (main/non-main), it is mandatory to declare :
+ * from which the current catalog may be included using the *importedBy* keyword
+ * the code name for which the data model is implemented by the current catalog. This is done thanks to the *code* keyword in the *JdC* of the main catalog and thanks to the *implement* keyword non-main catalog.
+
+Here is an exemple with three levels of catalogs.
+
+First, the main common catalog :
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.py
+ :language: python
+
+The *JdC* definition declares the main property of this catalog.
+
+
+The given values in the *importedBy* keyword declare middle level/domain specific catalogs that may import this catalog.
+
+For each catalog declared in the *importedBy* keyword **one global xsd type and one global element declaration** are produced :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="T_MDCommun_Abstract"
+ :end-at: name="T_MDCommun_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="MDCommun_Abstract"
+ :end-at: name="MDCommun_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="T_CFDCommun_Abstract"
+ :end-at: name="T_CFDCommun_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="CFDCommun_Abstract"
+ :end-at: name="CFDCommun_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="T_DomainSpecific_Abstract"
+ :end-at: name="T_DomainSpecific_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="DomainSpecific_Abstract"
+ :end-at: name="DomainSpecific_Abstract"
+
+The **abstract="true"** attribute implies that the xsd type have be be derivated in subsequent catalogs to be concretly defined.
+
+The abstract complex type says nothing about what will be the concrete type.
+
+.. note:: If *importedBy* keyword is not defined, there will be no generation of xsd abstract types.
+
+The root xsd is element type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_modeleCommun.xsd
+ :language: xml
+ :start-at: name="T_modeleCommun"
+ :end-at: /xs:complexType
+
+.. note:: The three *importedBy* catalogs appear as optional **element ref**. This give the possibility to complete the main root catalog with elements coming from subsequent catalogs knowing nothing about them.
+
+Second, the intermediate/domain specific catalog :
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This catalog finality is to gather common informations from a class of code. For example, it could be a "domain specific catalog".
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.py
+ :language: python
+
+* Since a catalog is a python script, it is possible to define an *autonome* variable to easily switch between a main/non-main catalog.
+* A main catalog must declare a *JdC = JDC_CATA* definition as explained in :ref:`Defining-steps-in-a-catalog` (in our example, if *autonome* is True).
+* In this example, the *importedBy* values declare the specific/final catalogs 'MD1', 'MD2' and 'MDSpecific' that may use this catalog.
+* The *implement* keyword declares the abstract typename it implements and from which catalog. In this example, it implements the **T_MDCommun_Abstract** type from the *modeleCommun* catalog.
+
+For each catalog declared in the *importedBy* keyword we get global xsd types and global element declaration production (as for the upper level before) :
+
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="T_MD1_Abstract"
+ :end-at: name="T_MD1_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="MD1_Abstract"
+ :end-at: name="MD1_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="T_MD2_Abstract"
+ :end-at: name="T_MD2_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="MD2_Abstract"
+ :end-at: name="MD2_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="T_MDSpecific_Abstract"
+ :end-at: name="T_MDSpecific_Abstract"
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="MDSpecific_Abstract"
+ :end-at: name="MDSpecific_Abstract"
+
+As in the main catalog, the **abstract="true"** attribute implies that the xsd type must be derivated in subsequent catalogs to be concretly defined.
+The abstract complex type still says nothing about what will be the concrete type.
+
+The root xsd element type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MDCommun.xsd
+ :language: xml
+ :start-at: name="T_MDCommun"
+ :end-at: /xs:complexType
+
+.. note:: Notice the presence of our three *importedBy* catalogs that appear as optional **element ref**. This give the possibility to complete the intermediate root catalog with elements coming from subsequent catalogs. Since the root main common catalog hosts itself intermediate elements, we have a sort of transitivity which allows to produce a unique xsd file combining different levels of description.
+
+Third, the final/specific catalog :
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In our three level exemple, this level is the final/fully specialized catalog.
+
+
+Nobody includes it since *importedBy* is empty.
+
+This catalog finality is to describe all the informations that are not in the scope of the common model or domain specific codes but are specfic to a code.
+Many code specific catalogs may use the same intermediate catalog or even directly the common catalog.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MD1.py
+ :language: python
+
+* The *importedBy* keyword is empty. It could be absent only in standalone catalogs. In this example, if the *importedBy* keyword is omitted, since the catalog imports (in the python way) the intermediate one, *importedBy* keyword would have the value defined in the intermediate catalog.
+* The *implement* keyword still declares the abstract typename it implements and from which catalog. In this example, it implements the **T_MD1_Abstract** type from the *MDCommun* catalog.
+
+Since the *importedBy* keyword is empty, there is no abstract type production.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/MultipleCata/cata_MD1.xsd
+ :language: xml
+ :start-at: name="T_MD1"
+ :end-at: /xs:complexType
+
+Understanding the XSD mapping for RULES
+_______________________________________
+
+.. todo:: Not implemented yet.
