From: Pascale Noyret Date: Thu, 24 Nov 2011 09:01:57 +0000 (+0000) Subject: Version Initiale X-Git-Tag: mergeto_trunk_2012-08-22~17 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=137793bf8be46e98363add25648a766039926048;p=tools%2Feficas.git Version Initiale --- diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..0b096776 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,70 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " pickle to make pickle files (usable by e.g. sphinx-web)" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf build/* + +html: + mkdir -p build/html build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html + @echo + @echo "Build finished. The HTML pages are in build/html." + +pickle: + mkdir -p build/pickle build/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle + @echo + @echo "Build finished; now you can process the pickle files or run" + @echo " sphinx-web build/pickle" + @echo "to start the sphinx-web server." + +web: pickle + +htmlhelp: + mkdir -p build/htmlhelp build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in build/htmlhelp." + +latex: + mkdir -p build/latex build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex + @echo + @echo "Build finished; the LaTeX files are in build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p build/changes build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes + @echo + @echo "The overview file is in build/changes." + +linkcheck: + mkdir -p build/linkcheck build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in build/linkcheck/output.txt." diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..0fa1e80c --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,179 @@ +# -*- coding: utf-8 -*- +# +# EFICAS documentation build configuration file, created by +# sphinx-quickstart on Wed Sep 14 11:40:32 2011. +# +# 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 value; values that are commented out +# serve to show the default value. + +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('some/directory')) + +# 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'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General substitutions. +project = 'EFICAS' +copyright = '2011, Pascale Noyret' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = '6.4' +# The full version, including alpha/beta/rc tags. +release = '6.4.0' + +# 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 directories, that shouldn't be searched +# for source files. +#exclude_dirs = [] + +# 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 style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# 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 (within the static path) 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_use_modindex = 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, 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 = 'EFICASdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# 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', 'EFICAS.tex', 'EFICAS Documentation', + 'Pascale Noyret', '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 = True diff --git a/doc/eficas_for_Aster.rst b/doc/eficas_for_Aster.rst new file mode 100644 index 00000000..87596f1d --- /dev/null +++ b/doc/eficas_for_Aster.rst @@ -0,0 +1,27 @@ +EFICAS for Aster +================ + +INCLUDE, INCLUDE_MATERIAU and POURSUITE macros have a special behaviour. +the concepts produced by these macros are created by a separated exec (in python sense) of the corresponding (also separated) command file. They are then included in the context of the main command file. +This processing (including in the main JDC the concepts created in INCLUDE, POURSUITE) is almost completely automatic. But, in some particular case, you can have unexpected difficulties. + +Principles are : + +1- Eficas doesn't take account of an invalid file even if some of the commands are completed. + +2- You are able to edit the content of the included file. + +.. image:: images/included.png + :align: center + + +3- Included files are knowned by Eficas according to their UNITE for INCLUDE, according to the materiel(?) 's name. (A file can only have one POURSUITE). so take care not to use the same number UNITE for differents INCLUDE : otherweise, rereading will exec the same file for differents INCLUDE. + + +4- Push the button "Autre Fichier" to command Eficas to change the included file. Using this method, you can force an invalid file to be read and use the valid concepts it includes. + +5- a INCLUDE file can own its INCLUDE file and so weiter... All the concepts can be accessed from the main file and all englobing files. + +5- file's name for INCLUDE_MATERIAU command is build according to the parameter values of the command. Eficas neither asks the user to give its name. + +6- The user is also able to edit simultaneously a JDC and all its POURSUITE or INCLUDE files. Most of the time, modifications will be propaged to the main JDC. However, it could be possible that some errors occurs. In case of doubts, the user should ask about the error reporting ('Rapport de Validation' in JdC Menu) to know more and correct the problem. Reopening files should also be an issue. diff --git a/doc/eficas_for_OpenTurns.rst b/doc/eficas_for_OpenTurns.rst new file mode 100644 index 00000000..aa5d5151 --- /dev/null +++ b/doc/eficas_for_OpenTurns.rst @@ -0,0 +1,3 @@ +EFICAS for OpenTurns +==================== + diff --git a/doc/eficas_in_salome.rst b/doc/eficas_in_salome.rst new file mode 100644 index 00000000..6e57de49 --- /dev/null +++ b/doc/eficas_in_salome.rst @@ -0,0 +1,13 @@ +EFICAS in Salome +================= + +Launching EFICAS in Salome +--------------------------- +first you must activate EFICAS module + +.. image:: images/LctDsSalome.png + :align: center + + + + diff --git a/doc/eficas_personnalisation.rst b/doc/eficas_personnalisation.rst new file mode 100644 index 00000000..e5ab336f --- /dev/null +++ b/doc/eficas_personnalisation.rst @@ -0,0 +1,3 @@ +your own custom EFICAS +======================= + diff --git a/doc/eficas_presentation.rst b/doc/eficas_presentation.rst new file mode 100644 index 00000000..4d223b03 --- /dev/null +++ b/doc/eficas_presentation.rst @@ -0,0 +1,26 @@ +What's EFICAS +============== + +Name's origin +------------- +EFICAS is the acronym of ' Editeur de FIchier de Commandes et Analyseur Sémantique'. +That means that EFICAS allows users to write a parameter file for a code. +It handles whith syntax and semantics. +It avoids misuse of commands which are not allowed in a given context. +It insures integrity of the file. + +General Behaviour +------------------ +* catalogs + +EFICAS can be used by multiple codes and handles with multiple versions of each code. it is customized with files named "Catalogue" : It contains all commands for a code. Each command has a name and parametres which are defined by developpers. + + +* outputs + +Eficas's Output is a commands file named ".comm". It may be able to produce various file formats such as .xml for OpenTurns. However, you always must have a '.comm" output: this is the only format Eficas is able to reread. + +Both Command Files and Catalogs are python file. so you have to remind some +:ref:`python-label` + + diff --git a/doc/eficas_principles.rst b/doc/eficas_principles.rst new file mode 100644 index 00000000..9c046456 --- /dev/null +++ b/doc/eficas_principles.rst @@ -0,0 +1,227 @@ +a new JDC step by step +====================== + +In Eficas, many common commands can be invoked via menus, toolbar buttons as well as keyboard shortcuts. +As in many GUI, a menu widget can be either a pull-down menu or a standalone context menu. Pull-down menus are shown by the menu bar when the user clicks on the respective item or presses the specified shortcut key. Context menus are usually invoked by some special keyboard key or by right-clicking. +Eficas allows you to write (and reread) an unvalid file. At any time, user can save its works. + +Choose a Code +--------------------- + +So try to build a new JDC. + +Eficas will ask you to choose the code you want to work with, each time you click on "Nouveau" or "Open" in the "fichier" Menu, unless you have started Eficas for a specific code ( see how to launch Eficas in Salome) + +.. image:: images/choix_code.png + :align: center + +Choose a version of the Code +---------------------------- + +.. image:: images/choix_cata.png + :align: center + +Enter commands +------------------------- + +Eficas main widget provided two distinct views: The left size always contains the JDC explorer as a tree view. The right widget contains all informations used by the user to constructs the JDC. It shows which commands are available and which rules (faire une reference) have to be followed. Commands are append after this selected in the JDC tree. + +.. image:: images/command.png + :align: center + + +The user can use "Filtre", which is a filter widget to find a command position. The PushButton "suivant" shows the next matching command. + + + + + +The user also can choose the way the commands are sorted, either by alphabetical order, either by fonctionnalities. + +.. image:: images/groupes.png + :align: center + +Choosing command's keywords +--------------------------------- + +For each command, EFICAS shows which keywords are available. + +.. image:: images/motClef.png + :align: center + + +These keywords depend from the context, ie the value of one other +keyword. + +.. image:: images/motClef2.png + :align: center + +or + + +.. image:: images/motClef3.png + :align: center + +types of item in the JDC (Jeu De Commande) +------------------------------------------- + +In JDC, you can have : + +* PROC : this is a command with all its keywords. + + - example: + - DEBUT() is a proc. + - for ASTER, it initializes memory and files. + +* OPER : creates an object which has a type and a name + + - example : + - MONMAIL=LIRE_MAILLAGE(UNITE=20); + - This line creates a new concept MONMAIL of type "maillage", which can be re-used + +When an oper is valid, the user have to named it. + +.. image:: images/nommerConcept.png + :align: center + + + +* mot-clef facteur + + This is a list of keywords which jointly have a meaning for the code. + Some are mandatory, repeatable . + This list can depend on conditionnal rules. + + +* mot-clef simple . + + this is a simple keyword. it also can be mandatory or not... + + +These items are associated according to rules or conditions. These items are +described in the catalog. + + +Attributes of a keyword +--------------------------- + +a parameter ("mot-clef simple") should have : + +- a type : Real, string, complex, integer or a python class which is defined in the catalog. As we have already seen, LIRE_MAILLAGE produced a "maillage" concept and MODELE in AFFE_MODELE oper waits for a concept of type "maillage". Eficas will propose all the valid concepts of type "maillage". + +.. image:: images/Affe.png + :align: center + +- a default value (or not) + +- a cardinality. + +- a short documentation + +- an interval of values or a set of discrete values + + +Input data panel depends on both these attributes. It forces the user to enter a list if needed, it verifies the input type... + +- Example of input Data Pannel for complex valuesNew + +.. image:: images/complex.png + :align: center + + +Color chart +------------- + +a very simple colors chart helps the user to know if a item is valid or not : + +* In the JDC tree view + + - green square : valid objects (JDC, Oper ...) + - red square : unvalid objects + - yellow square : valids OPER the user must name + - green circle : valid keywords + - red circle : unvalid keywords + - green rhomb : condition. all the depending keywords are valid + - yellow rhomb : condition. one of the depending keywords is unvalid + +* In the rules part + + - red is for unobserved rules + - black is for observed rules + + +Context Menus +-------------- +In the JDC tree, Context menus (invoked by right-clicking) allow user to : + +- create comments in the tree +- comment the command itself +- create parameter +- delete the node + +.. image:: images/menus.png + :align: center + + +Parameters +------------ + +The Users can define parameters. As parameters, Eficas accepts : + +- Real +- String +- Integer +- List + +A parameter's definition can use existing parameters such as : +eps=sqrt((((W / NX) ** 2) + ((H / NY) ** 2))) + +Pushing on "Parametres" Pushbutton opens a dialog containing all correct parameters (depending of the attended value's type) + +.. image:: images/parametres.png + :align: center + + +To select the value in the modal dialog widget, highligh the corresponding line and Push on "Valider". + + + +Import data from file +----------------------- + +The user also can import data from a ASCII text file by pushing button "Importer". He chooses to import part of or the complete file. + +.. image:: images/import.png + :align: center + + +Reports +--------------------- +You have acces to + +- Rapport de Validation (Jdc Menu) : It resumes JDC errors +- Fichier Source (JdC Menu) : It shows the text of the initial JDC (in the .comm file). +- Fichier Resultat (JdC Menu) : It shows the text which will be stored at next + +.. image:: images/rapport.png + :align: center + + +Multiples files +--------------------- + +EFICAS allows you to open +simultaneously files with differents catalogs : for example a file with Openturns Study catalog and a file for Openturns wrapper. The user also can easely swap from one file to another by clicking on its tab. + + + +.. image:: images/multiples.png + :align: center + + +If the user want to open the same file in two tabs, Eficas allows it, but corrections in one tabs are not reported in the other. + +.. image:: images/duplication.png + :align: center + + diff --git a/doc/eficas_rules.rst b/doc/eficas_rules.rst new file mode 100644 index 00000000..6ce265f9 --- /dev/null +++ b/doc/eficas_rules.rst @@ -0,0 +1,118 @@ + +=============================== +Eficas rules +=============================== + +All the rules can be combinated, creating more complicated rules. + +AU_MOINS_UN +----------- + + AU_MOINS_UN rule obliges the user to create at least one concept of the list. More than one can be created. + +- Example + + Keyword POUTRE in OPER AFFE_CARA_ELEM contains the rule : + + regles=(AU_MOINS_UN( + 'POUTRE','COQUE','DISCRET','CABLE','BARRE','MASSIF','ASSE_GRIL','GRILLE'),) + +- That means if AFFE_CARA_ELEM is used in the JDC, the user must select one at least of the Keyword between POUTRE, COQUE, DISCRET, CABLE, BARRE, MASSIF, ASSE_GRIL, GRILLE : + + * If the user doesn't select any of these keywords, AFFE_CARA_ELEM is unvalid. + * If he selects POUTRE, AFFE_CARA_ELEM is valid. + * If he selects both POUTRE and DISCRET, AFFE_CARA_ELEM is valid. + + +UN_PARMI +-------- + + AU_MOINS_UN rule obliges the user to create one and only one concept of the list. + +- Example + + Oper AFFE_CHAR_MECA contains the rules : + + regles=(UN_PARMI('VECT_Y','ANGL_VRIL'), + +- That means if AFFE_CHAR_MECA is used in the JDC, the user must select VECT_Y or ANGL_VRIL. + + * If the user doesn't select any of these keywords, DEFI_GROUP is unvalid. + * If he selects only VECT_Y, DEFI_GROUP is valid. + * Eficas will not proposed the keyword ANGL_VRIL if VECT_Y already exists. + + +EXCLUS +-------- + + EXCLUS means that, if one of the keyword is created, the other won't be allowed. + + - Example : + DEFI_SQUELETTE contains the rules : + + EXCLUS('SOUS_STRUC','SECTEUR') + +- That means if DEFI_SQUELETTE is used in the JDC + + * If the user doesn't select any of these keywords, DEFI_SQUELETTE is valid. + * If he selects only SOUS_STRUC, DEFI_SQUELETTE is valid. + * Eficas will not proposed the keyword SECTEUR if SOUS_STRUC already exists. + +ENSEMBLE +-------- + + the rule means that if one keyword is selected, the others have to be also. + the keywords order is not meaningful. + +- Example + + GRILLE in AFFE_CARA_ELEM, contains : + + ENSEMBLE('ORIG_AXE','AXE') + +- That means if GRILLE is used in the JDC + + * If the user doesn't 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 keyword is selected, the others have to be also. + +- Example + + MACRO_MISS_3D contains the rule + + PRESENT_PRESENT('FREQ_MIN','FREQ_MAX','FREQ_PAS') + +- That means if MACRO_MISS_3D is used in the JDC + + * If the user doesn't select any of these keywords, GRILLE is valid. + * If he selects only FREQ_MAX, GRILLE is unvalid. + * If he selects only FREQ_PAS, GRILLE is valid. + * If he selects only FREQ_MIN, GRILLE is invalid. + * If he selects both FREQ_MIN, FREQ_MAX and FREQ_PAS, GRILLE is valid. + + +PRESENT_ABSENT +--------------- + + the rule means that if the FIRST keyword is selected, the others aren't allowed. + +- Example + FORCE_COQUE in AFFE_CHAR_MECA contains + + regles=( PRESENT_ABSENT('FX','PRES','F1','F2','F3','MF1','MF2'), + +- That means if FORCE_COQUE is used in the JDC + + * If the user doesn't select any of these keywords, FORCE_COQUE is valid. + * If he selects only FX, FORCE_COQUE is valid. + * If he selects both PRES and F1, FORCE_COQUE is valid. + + + + + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..5f26c583 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,34 @@ +.. EFICAS 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 EFICAS's documentation! +================================== + +This documentation covers the usage of Eficas as data setting tool in Salome. +This is intended for end users who want to use Eficas and not for developpers who want to write a catalog. +Refer to OpenTurns documentation to know more about Eficas specifications for this code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + eficas_presentation + eficas_principles + eficas_for_Aster + eficas_in_salome + eficas_personnalisation + eficas_rules + python_rules + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/python_rules.rst b/doc/python_rules.rst new file mode 100644 index 00000000..519bdefc --- /dev/null +++ b/doc/python_rules.rst @@ -0,0 +1,34 @@ +.. _python-label: + +=============================== +rules for python syntax +=============================== + +Variable names and identifier are similar to those in many other languages : +---------------------------------------------------------------------------- + +* They start with a letter (A_Z or a-z) or underscore "_"". +* They are followed by letters, numbers or underscores. +* They are case-sensitive. +* A string is a sequence of caracters enclosed by a matching pair of single or double quotes. + +Unlike python, the name's length for concept are limited by Eficas to 8 characters. + +Some identifiers are reserved words : +------------------------------------- + +* You can't use words of the python language as identifiers. +* Eficas itself uses identifiers which become reserved words. for example you can't use the following word, even if it would make some interesting names: + - BLOC, EXCLUS, OPER, ASSD, + - EVAL, FACT, FORM, JDC, + - REGLE, VALIDATOR, EXCLUS, + - ETAPE, ENTITITE + +Python's way for assigning values to variables: +------------------------------------------------- + +* Keep in mind that .comm are python files. The simplest form of assignement is : variable = value +* The hash character (#) starts a comment +* Tuples are enclosed in parentheses. +* Lists are enclosed in bracked. +* In tuples or lists, a ',' follows each item especially the last one.