From 6dfa1718db04ba334e80c5d6e2cfd3f24734138a Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Tue, 19 May 2015 15:54:39 +0200 Subject: [PATCH] Documentation and source minor corrections and improvements --- doc/en/advanced.rst | 6 +- doc/en/examples.rst | 10 +-- doc/en/ref_algorithm_GradientTest.rst | 36 +++++++++-- ...ef_algorithm_ParticleSwarmOptimization.rst | 2 +- doc/en/ref_algorithm_SamplingTest.rst | 4 +- doc/en/ref_output_variables.rst | 14 ++-- doc/en/reference.rst | 4 +- doc/en/using.rst | 64 ++++++++++--------- doc/fr/advanced.rst | 5 +- doc/fr/examples.rst | 8 +-- doc/fr/index.rst | 4 +- doc/fr/ref_algorithm_GradientTest.rst | 31 +++++++-- ...ef_algorithm_ParticleSwarmOptimization.rst | 2 +- doc/fr/ref_algorithm_SamplingTest.rst | 6 +- doc/fr/ref_output_variables.rst | 19 +++--- doc/fr/reference.rst | 2 +- doc/fr/using.rst | 58 +++++++++-------- src/daComposant/daAlgorithms/GradientTest.py | 43 ++++++++++--- 18 files changed, 201 insertions(+), 117 deletions(-) diff --git a/doc/en/advanced.rst b/doc/en/advanced.rst index 84a5fc5..46ff898 100644 --- a/doc/en/advanced.rst +++ b/doc/en/advanced.rst @@ -199,9 +199,9 @@ variables ``var`` and ``info``. The variable ``var`` is to be used in the same way as for the final ADD object, that is as a list/tuple object. Some templates are available when editing the ADAO case in graphical editor. -These simple scripts can be customized by the user, either at the EFICAS edition -stage, or at the YACS edition stage, to improve the tuning of the ADAO -calculation in YACS. +These simple scripts can be customized by the user, either at the embedded +edition stage, or at the edition stage before execution, to improve the tuning +of the ADAO calculation. As an example, here is one very simple script (similar to the "*ValuePrinter*" template) used to print the value of one monitored variable:: diff --git a/doc/en/examples.rst b/doc/en/examples.rst index a02f4ca..cc13355 100644 --- a/doc/en/examples.rst +++ b/doc/en/examples.rst @@ -117,17 +117,17 @@ button or menu of SALOME, and you will see: .. centered:: **Activating the module ADAO in SALOME** -Choose the "*New*" button in this window. You will directly get the EFICAS -interface for variables definition, along with the SALOME "*Object browser*". -You can then click on the "*New*" button |eficas_new| to create a new ADAO case, -and you will see: +Choose the "*New*" button in this window. You will directly get the embedded +case editor interface for variables definition, along with the SALOME "*Object +browser*". You can then click on the "*New*" button |eficas_new| to create a new +ADAO case, and you will see: .. _adao_viewer: .. image:: images/adao_viewer.png :align: center :width: 100% .. centered:: - **The EFICAS editor for cases definition in module ADAO** + **The embedded editor for cases definition in module ADAO** Then, fill in the variables to build the ADAO case by using the experimental set up described above. All the technical information given above will be directly diff --git a/doc/en/ref_algorithm_GradientTest.rst b/doc/en/ref_algorithm_GradientTest.rst index de57cbe..c325802 100644 --- a/doc/en/ref_algorithm_GradientTest.rst +++ b/doc/en/ref_algorithm_GradientTest.rst @@ -46,11 +46,37 @@ function, normalized by the value at the nominal point: .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} If the residue is decreasing and the decrease change in :math:`\alpha^2` with +respect to :math:`\alpha`, it signifies that the gradient is well calculated +until the stopping precision of the quadratic decrease, and that :math:`F` is +not linear. + +If the residue is decreasing and the decrease change in :math:`\alpha` with respect to :math:`\alpha`, until a certain level after which the residue remains small and constant, it signifies that the :math:`F` is linear and that the residue is decreasing due to the error coming from :math:`\nabla_xF` term calculation. +"TaylorOnNorm" residue +********************** + +One observe the residue coming from the Taylor development of the :math:`F` +function, with respect to the :math:`\alpha` parameter to the square: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{\alpha^2} + +This is a residue essentialy similar to the classical Taylor criterion +previously described, but its behaviour can differ depending on the numerical +properties of the calculation. + +If the residue is constant until a certain level after which the residue will +growth, it signifies that the gradient is well calculated until this stopping +precision, and that :math:`F` is not linear. + +If the residue is systematicaly growing from a very smal value with respect to +:math:`||F(\mathbf{x})||`, it signifies that :math:`F` is (quasi-)linear and +that the gradient calculation is correct until the precision for which the +residue reachs the numerical order of :math:`||F(\mathbf{x})||`. + "Norm" residue ************** @@ -126,10 +152,12 @@ The options of the algorithm are the following: ResiduFormula This key indicates the residue formula that has to be used for the test. The - default choice is "Taylor", and the possible ones are "Taylor" (residue of - the Taylor development of the operator, which has to decrease with the - square power of the perturbation) and "Norm" (residue obtained by taking the - norm of the Taylor development at zero order approximation, which + default choice is "Taylor", and the possible ones are "Taylor" (normalized + residue of the Taylor development of the operator, which has to decrease + with the square power of the perturbation), "TaylorOnNorm" (residue of the + Taylor development of the operator with respect to the pertibation to the + square, which has to remain constant) and "Norm" (residue obtained by taking + the norm of the Taylor development at zero order approximation, which approximate the gradient, and which has to remain constant). Example : ``{"ResiduFormula":"Taylor"}`` diff --git a/doc/en/ref_algorithm_ParticleSwarmOptimization.rst b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst index ff117b4..4954d8c 100644 --- a/doc/en/ref_algorithm_ParticleSwarmOptimization.rst +++ b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst @@ -145,7 +145,7 @@ The options of the algorithm are the following: (``None`` is not allowed when there is no bound). This key is required and there is no default values. - Example : ``{"BoxBounds":[[-0.5,0.5],[0.01,2.],[0.,1.e99],[-1.e99,1.e99]]}`` + Example : ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` SetSeed This key allow to give an integer in order to fix the seed of the random diff --git a/doc/en/ref_algorithm_SamplingTest.rst b/doc/en/ref_algorithm_SamplingTest.rst index 7996b55..10dd6b0 100644 --- a/doc/en/ref_algorithm_SamplingTest.rst +++ b/doc/en/ref_algorithm_SamplingTest.rst @@ -126,7 +126,7 @@ The options of the algorithm are the following: list of explicit sampling of each variable as a list. That is then a list of lists, each of them being potentially of different size. - Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` for a state space of dimension 2 + Example : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` for a state space of dimension 2 SampleAsMinMaxStepHyperCube This key describes the calculations points as an hyper-cube, from a given @@ -146,7 +146,7 @@ The options of the algorithm are the following: 'uniform' of parameters (low,high), or 'weibull' of parameter (shape). That is then a list of the same size than the one of the state. - Example : ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3],['uniform',[-2,2],4]]`` for a state space of dimension 2 + Example : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` for a state space of dimension 2 QualityCriterion This key indicates the quality criterion, used to find the state estimate. diff --git a/doc/en/ref_output_variables.rst b/doc/en/ref_output_variables.rst index f7f0079..28ac19a 100644 --- a/doc/en/ref_output_variables.rst +++ b/doc/en/ref_output_variables.rst @@ -76,13 +76,13 @@ Examples of Python scripts to obtain or treat the outputs These examples present Python commands or scripts which allow to obtain or to treat the ouput of an algorithm run. To help the user, they are directly -available in the user interface, when building the ADAO case in EFICAS, in the -"*Template*" type fields. In an equivalent way, these commands can be integrated -in an external user script (and inserted in the ADAO case by a "*Script*" type -input) or can exist as a string, including line feeds (and inserted in the ADAO -case by a "*String*" type input). Lot of variants can be build from these -simple examples, the main objective beeing to help the user to elaborate the -exact procedure he needs in output. +available in the user interface, when building the ADAO case in the embedded +case editor, in the "*Template*" type fields. In an equivalent way, these +commands can be integrated in an external user script (and inserted in the ADAO +case by a "*Script*" type input) or can exist as a string, including line feeds +(and inserted in the ADAO case by a "*String*" type input). Lot of variants can +be build from these simple examples, the main objective beeing to help the user +to elaborate the exact procedure he needs in output. The first example (named "*AnalysisPrinter*" in the inputs of type "*Template*") consists in printing, in the standard log output, the value of the diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 9955521..c0d6226 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -37,9 +37,9 @@ Each command or keyword to be defined through the ADAO GUI has some properties. The first property is to be *required*, *optional* or only factual, describing a type of input. The second property is to be an "open" variable with a fixed type but with any value allowed by the type, or a "restricted" variable, limited to -some specified values. The EFICAS editor GUI having build-in validating +some specified values. The embedded case editor GUI having build-in validating capacities, the properties of the commands or keywords given through this GUI -are automatically correct. +are automatically correct. .. _section_reference_entry: diff --git a/doc/en/using.rst b/doc/en/using.rst index ce822c6..dab727e 100644 --- a/doc/en/using.rst +++ b/doc/en/using.rst @@ -43,18 +43,20 @@ :align: middle :scale: 50% -This section presents the usage of the ADAO module in SALOME platform. It is -complemented by the detailed description of all the commands and keywords in the -section :ref:`section_reference`, by advanced usage procedures in the section -:ref:`section_advanced`, and by examples in the section :ref:`section_examples`. +This section presents the usage of the ADAO module in SALOME platform. Here we +describe the general progression to establish an ADAO case, the details being +given in the following chapters. It is completed by the detailed description of +all the commands and keywords in the section :ref:`section_reference`, by +advanced usage procedures in the section :ref:`section_advanced`, and by +examples in the section :ref:`section_examples`. Logical procedure to build an ADAO case --------------------------------------- The construction of an ADAO case follows a simple approach to define the set of -input data, and then generates a complete executable block diagram used in YACS. -Many variations exist for the definition of input data, but the logical sequence -remains unchanged. +input data, and then generates a complete executable block diagram used in YACS +[#]_. Many variations exist for the definition of input data, but the logical +sequence remains unchanged. First of all, the user is considered to know its personal input data needed to set up the data assimilation study. These data can already be available in @@ -86,28 +88,28 @@ or opening an already existing one: .. centered:: **Activating the module ADAO in SALOME** -Choosing the "*New*" button, an embedded case editor EFICAS [#]_ will be opened, -along with the standard "*Object browser*". You can then click on the "*New*" -button |eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to -create a new ADAO case, and you will see: +Choosing the "*New*" button, an embedded case editor [#]_ will be opened, along +with the standard "*Object browser*". You can then click on the "*New*" button +|eficas_new| (or choose the "*New*" entry in the "*ADAO*" main menu) to create a +new ADAO case, and you will see: .. _adao_viewer: .. image:: images/adao_viewer.png :align: center :width: 100% .. centered:: - **The EFICAS editor for cases definition in module ADAO** + **The embedded editor for cases definition in module ADAO** .. _section_u_step2: STEP 2: Build and modify the ADAO case, and save it --------------------------------------------------- -To build a case using EFICAS, you have to go through a series of sub-steps, by -selecting, at each sub-step, a keyword and then filling in its value. It is -noted that it is in this step that is needed, among other things, to define the -call to the simulation code used in observation or evolution operators -describing the problem [#]_. +To build a case using the embedded editor, you have to go through a series of +sub-steps, by selecting, at each sub-step, a keyword and then filling in its +value. It is noted that it is in this step that is needed, among other things, +to define the call to the simulation code used in observation or evolution +operators describing the problem [#]_. The structured editor indicates hierarchical types, values or keywords allowed. Incomplete or incorrect keywords are identified by a visual error red flag. @@ -137,20 +139,20 @@ Finally, you have to save your ADAO case by pushing the "*Save*" button |eficas_save|, or the "*Save as*" button |eficas_saveas|, or by choosing the "*Save/Save as*" entry in the "*ADAO*" menu. You will be prompted for a location in your file tree and a name, that will be completed by a "*.comm*" extension -used for JDC EFICAS files. This will generate a pair of files describing the -ADAO case, with the same base name, the first one being completed by a "*.comm*" -extension and the second one by a "*.py*" extension [#]_. +used for the embedded case editor. This will generate a pair of files describing +the ADAO case, with the same base name, the first one being completed by a +"*.comm*" extension and the second one by a "*.py*" extension [#]_. .. _section_u_step3: STEP 3: Export the ADAO case as a YACS scheme --------------------------------------------- -When the ADAO case is completed, you have to export it as a YACS scheme [#]_ in -order to execute the data assimilation calculation. This can be easily done by -using the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the -"*Export to YACS*" entry in the "*ADAO*" main menu, or in the contextual case -menu in the SALOME object browser. +When the ADAO case is completed, you have to export it as a YACS scheme in order +to execute the data assimilation calculation. This can be easily done by using +the "*Export to YACS*" button |eficas_yacs|, or equivalently choose the "*Export +to YACS*" entry in the "*ADAO*" main menu, or in the contextual case menu in the +SALOME object browser. .. _adao_exporttoyacs01: .. image:: images/adao_exporttoyacs.png @@ -190,9 +192,9 @@ post-processing can use all the SALOME possibilities. See the part describing full description of these elements. In practice, the YACS scheme has an "*algoResults*" output port of the -computation bloc, which gives access to an object of type "*pyobj*" named -hereafter "*ADD*", containing all the calculation results. These results can be -obtained by retrieving the named variables stored along the calculation. The +computation bloc, which gives access to a structured object named hereafter +"*ADD*" for example, containing all the calculation results. These results can +be obtained by retrieving the named variables stored along the calculation. The main information is the "*Analysis*" one, that can be obtained by the python command (for example in an in-line script node or a script provided through the "*UserPostAnalysis*" keyword):: @@ -249,10 +251,10 @@ shown in the "*YACS Container Log*". The execution can also be done using a Shell script, as described in the section :ref:`section_advanced`. -.. [#] For more information on EFICAS, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform. +.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform. -.. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts. +.. [#] For more information on the embedded case editor, see the *EFICAS module* and its integrated help available from the main menu *Help* of the SALOME platform. -.. [#] For more information on YACS, see the *YACS module* and its integrated help available from the main menu *Help* of the SALOME platform. +.. [#] The use of physical simulation code in the data assimilation elementary operators is illustrated or described in the following main parts. .. [#] This intermediary python file can also be used as described in the section :ref:`section_advanced`. diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst index d798074..82e7b63 100644 --- a/doc/fr/advanced.rst +++ b/doc/fr/advanced.rst @@ -211,8 +211,9 @@ liste/tuple. Des modèles ("templates") sont disponibles lors de l'édition le cas ADAO dans l'éditeur graphique. Ces scripts simples peuvent être adaptés par l'utilisateur, -soit dans l'étape d'édition EFICAS, ou dans l'étape d'édition YACS, pour -améliorer l'adaptation du calcul ADAO dans YACS. +soit dans l'étape d'édition intégrée, ou dans l'étape d'édition avant +l'exécution, pour améliorer l'adaptation du calcul ADAO dans le superviseur +d'exécution de SALOME. A titre d'exemple, voici un script très simple (similaire au modèle "*ValuePrinter*") utilisable pour afficher la valeur d'une variable surveillée:: diff --git a/doc/fr/examples.rst b/doc/fr/examples.rst index 91ed950..307b176 100644 --- a/doc/fr/examples.rst +++ b/doc/fr/examples.rst @@ -125,16 +125,16 @@ menu appropri **Activation du module ADAO dans SALOME** Choisir le bouton "*Nouveau*" dans cette fenêtre. On obtient directement -l'interface EFICAS pour la définition de variables, en même temps que l'"*Arbre -d'étude*" de SALOME. On peut alors choisir le bouton "*Nouveau*" |eficas_new| -pour créer un nouveau cas ADAO, et on voit : +l'interface de l'éditeur intégré de cas pour la définition de variables, en même +temps que l'"*Arbre d'étude*" de SALOME. On peut alors choisir le bouton +"*Nouveau*" |eficas_new| pour créer un nouveau cas ADAO, et on voit : .. _adao_viewer: .. image:: images/adao_viewer.png :align: center :width: 100% .. centered:: - **L'éditeur EFICAS pour la définition de cas dans le module ADAO** + **L'éditeur intégré pour la définition de cas dans le module ADAO** Ensuite, il faut remplir les variables pour construire le cas ADAO en utilisant les conditions d'expérience décrites ci-dessus. L'ensemble des informations diff --git a/doc/fr/index.rst b/doc/fr/index.rst index c69adf5..52952b9 100644 --- a/doc/fr/index.rst +++ b/doc/fr/index.rst @@ -33,8 +33,8 @@ Documentation ADAO Le module ADAO fournit des fonctionnalités d'**assimilation de données et d'optimisation** dans un contexte SALOME. Il est basé sur l'utilisation d'autres -modules, à savoir YACS et EFICAS, et sur l'utilisation d'une bibliothèque -générique sous-jacente d'assimilation de données. +modules, à savoir YACS et EFICAS, et sur l'utilisation d'une bibliothèque et des +outils génériques sous-jacents d'assimilation de données. En bref, l'assimilation de données est un cadre méthodologique pour calculer l'estimation optimale de la valeur réelle (inaccessible) de l'état d'un système diff --git a/doc/fr/ref_algorithm_GradientTest.rst b/doc/fr/ref_algorithm_GradientTest.rst index 61bd4fe..ee8bbb0 100644 --- a/doc/fr/ref_algorithm_GradientTest.rst +++ b/doc/fr/ref_algorithm_GradientTest.rst @@ -41,13 +41,13 @@ R *************** On observe le résidu issu du développement de Taylor de la fonction :math:`F`, -normalisée par la valeur au point nominal : +normalisé par la valeur au point nominal : .. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} Si le résidu décroit et que la décroissance se fait en :math:`\alpha^2` selon :math:`\alpha`, cela signifie que le gradient est bien calculé jusqu'à la -précision d'arrêt de la décroissance quadratique et que :math:`F` n'est pas +précision d'arrêt de la décroissance quadratique, et que :math:`F` n'est pas linéaire. Si le résidu décroit et que la décroissance se fait en :math:`\alpha` selon @@ -55,6 +55,27 @@ Si le r constant, cela signifie que :math:`F` est linéaire et que le résidu décroit à partir de l'erreur faite dans le calcul du terme :math:`\nabla_xF`. +Résidu "TaylorOnNorm" +********************* + +On observe le résidu issu du développement de Taylor de la fonction :math:`F`, +rapporté au paramètre :math:`\alpha` au carré : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{\alpha^2} + +C'est un résidu essentiellement similaire au critère classique de Taylor décrit +précédemment, mais son comportement peut différer selon les propriétés +numériques des calculs de ses différents termes. + +Si le résidu est constant jusqu'à un certain seuil et croissant ensuite, cela +signifie que le gradient est bien calculé jusqu'à cette précision d'arrêt, et +que :math:`F` n'est pas linéaire. + +Si le résidu est systématiquement croissant en partant d'une valeur faible par +rapport à :math:`||F(\mathbf{x})||`, cela signifie que :math:`F` est +(quasi-)linéaire et que le calcul du gradient est correct jusqu'au moment où le +résidu est de l'ordre de grandeur de :math:`||F(\mathbf{x})||`. + Résidu "Norm" ************* @@ -134,8 +155,10 @@ Les options de l'algorithme sont les suivantes: ResiduFormula Cette clé indique la formule de résidu qui doit être utilisée pour le test. Le choix par défaut est "Taylor", et les choix possibles sont "Taylor" - (résidu du développement de Taylor de l'opérateur, qui doit décroître comme - le carré de la perturbation) et "Norm" (résidu obtenu en prenant la norme du + (résidu du développement de Taylor normalisé de l'opérateur, qui doit + décroître comme le carré de la perturbation), "TaylorOnNorm" (résidu du + développement de Taylor rapporté à la perturbation de l'opérateur, qui doit + rester constant) et "Norm" (résidu obtenu en prenant la norme du développement de Taylor à l'ordre 0, qui approxime le gradient, et qui doit rester constant). diff --git a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst index 98a67eb..4a841d6 100644 --- a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst +++ b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst @@ -149,7 +149,7 @@ Les options de l'algorithme sont les suivantes: valeur autorisée lorsqu'il n'y a pas de borne). Cette clé est requise et il n'y a pas de valeurs par défaut. - Exemple : ``{"BoxBounds":[[-0.5,0.5],[0.01,2.],[0.,1.e99],[-1.e99,1.e99]]}`` + Exemple : ``{"BoxBounds":[[-0.5,0.5], [0.01,2.], [0.,1.e99], [-1.e99,1.e99]]}`` SetSeed Cette clé permet de donner un nombre entier pour fixer la graine du diff --git a/doc/fr/ref_algorithm_SamplingTest.rst b/doc/fr/ref_algorithm_SamplingTest.rst index ec3d412..04c1dec 100644 --- a/doc/fr/ref_algorithm_SamplingTest.rst +++ b/doc/fr/ref_algorithm_SamplingTest.rst @@ -131,7 +131,7 @@ Les options de l'algorithme sont les suivantes: liste. C'est donc une liste de listes, chacune étant de taille potentiellement différente. - Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.],[-2,2,1]]}`` pour un espace d'état de dimension 2 + Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2 SampleAsMinMaxStepHyperCube Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on @@ -151,8 +151,8 @@ Les options de l'algorithme sont les suivantes: (mean,std), 'lognormal' de paramètres (mean,sigma), 'uniform' de paramètres (low,high), ou 'weibull' de paramètre (shape). C'est donc une liste de la même taille que celle de l'état. - - Exemple : ``{"SampleAsIndependantRandomVariables":[['normal',[0.,1.],3],['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2 + + Exemple : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2 QualityCriterion Cette clé indique le critère de qualité, qui est utilisé pour trouver diff --git a/doc/fr/ref_output_variables.rst b/doc/fr/ref_output_variables.rst index 47bb2b4..e64ebb2 100644 --- a/doc/fr/ref_output_variables.rst +++ b/doc/fr/ref_output_variables.rst @@ -77,15 +77,16 @@ Exemples de scripts Python pour obtenir ou traiter les sorties .. index:: single: AnalysisPrinterAndSaver Ces exemples présentent des commandes ou scripts Python qui permettent d'obtenir -ou de traiter les sorties d'une exécution d'algorithme. Pour aider l'utilisateur, -ils sont directement disponibles dans l'interface, à la construction du cas ADAO -dans EFICAS, dans les champs de type "*Template*". De manière équivalente, ces -commandes peuvent être contenues dans un script utilisateur externe (et insérées -dans le cas ADAO par l'entrée de type "*Script*") ou contenues dans une chaîne -de caractères, y compris les retour à la ligne (et insérées dans le cas ADAO par -l'entrée de type "*String*"). De nombreuses variantes peuvent être imaginées à -partir de ces exemples simples, l'objectif étant surtout d'aider l'utilisateur à -effectuer le traitement exact dont il a besoin en sortie. +ou de traiter les sorties d'une exécution d'algorithme. Pour aider +l'utilisateur, ils sont directement disponibles dans l'interface, à la +construction du cas ADAO dans l'éditeur intégré de cas, dans les champs de type +"*Template*". De manière équivalente, ces commandes peuvent être contenues dans +un script utilisateur externe (et insérées dans le cas ADAO par l'entrée de type +"*Script*") ou contenues dans une chaîne de caractères, y compris les retour à +la ligne (et insérées dans le cas ADAO par l'entrée de type "*String*"). De +nombreuses variantes peuvent être imaginées à partir de ces exemples simples, +l'objectif étant surtout d'aider l'utilisateur à effectuer le traitement exact +dont il a besoin en sortie. Le premier exemple (appelé "*AnalysisPrinter*" dans les entrées de type "*Template*") consiste à afficher, dans la sortie standard d'exécution, la diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index d74f1dd..3bb2a5d 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -38,7 +38,7 @@ propri *optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde propriété est d'être une variable "ouverte" avec un type fixé mais avec n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée -à des valeurs spécifiées. L'éditeur graphique EFICAS disposant de capacités +à des valeurs spécifiées. L'éditeur graphique intégré disposant de capacités intrinsèques de validation, les propriétés des commandes ou mots-clés données à l'aide de l'interface graphique sont automatiquement correctes. diff --git a/doc/fr/using.rst b/doc/fr/using.rst index c82cb5d..bf08916 100644 --- a/doc/fr/using.rst +++ b/doc/fr/using.rst @@ -43,10 +43,12 @@ :align: middle :scale: 50% -Cette section présente l'usage du module ADAO dans la plateforme SALOME. Il est -complété par la description détaillée de l'ensemble des commandes et mots-clés -dans la section :ref:`section_reference`, par des procédures avancées d'usage -dans la section :ref:`section_advanced`, et par des exemples dans la section +Cette section présente l'usage du module ADAO dans la plateforme SALOME. On +décrit ici le cheminement général pour établir un cas ADAO, les détails étant +fournis dans les chapitres suivants. Il est complété par la description +détaillée de l'ensemble des commandes et mots-clés dans la section +:ref:`section_reference`, par des procédures avancées d'usage dans la section +:ref:`section_advanced`, et par des exemples dans la section :ref:`section_examples`. Procédure logique pour construire un cas ADAO @@ -54,8 +56,8 @@ Proc La construction d'un cas ADAO suit une démarche simple pour définir l'ensemble des données d'entrée, et ensuite générer un diagramme complet d'exécution -utilisé dans YACS. De nombreuses variations existent pour la définition des -données d'entrée, mais la séquence logique reste inchangée. +utilisé dans YACS [#]_. De nombreuses variations existent pour la définition +des données d'entrée, mais la séquence logique reste inchangée. De manière générale, l'utilisateur doit connaître ses données d'entrées, requises pour mettre au point une étude d'assimilation de données. Ces données @@ -89,7 +91,7 @@ l'ouverture d'une .. centered:: **Activation du module ADAO dans SALOME** -En choisissant le bouton "*Nouveau*", un éditeur intégré de cas EFICAS [#]_ sera +En choisissant le bouton "*Nouveau*", un éditeur intégré de cas [#]_ sera ouvert, en même temps que le "*navigateur d'objets*" standard. On peut alors cliquer sur le bouton "*Nouveau*"(ou choisir l'entrée "*Nouveau*" dans le dans le menu principal "*ADAO*") pour créer un nouveau cas ADAO, et on obtient : @@ -99,18 +101,18 @@ le menu principal "*ADAO*") pour cr :align: center :width: 100% .. centered:: - **L'éditeur EFICAS pour la définition des cas dans le module ADAO** + **L'éditeur intégré pour la définition des cas dans le module ADAO** .. _section_u_step2: ÉTAPE 2 : Créer et modifier le cas ADAO, et l'enregistrer --------------------------------------------------------- -Pour construire un cas en utilisant EFICAS, on doit passer par une série de -sous-étapes, en choisissant, à chaque étape, un mot-clé puis en remplissant ses -valeurs. On note que c'est dans cette étape qu'il faut, entre autres, définir -l'**appel au code de simulation** utilisé dans les opérateurs d'observation ou -d'évolution décrivant le problème [#]_. +Pour construire un cas en utilisant l'éditeur intégré, on doit passer par une +série de sous-étapes, en choisissant, à chaque étape, un mot-clé puis en +remplissant ses valeurs. On note que c'est dans cette étape qu'il faut, entre +autres, définir l'**appel au code de simulation** utilisé dans les opérateurs +d'observation ou d'évolution décrivant le problème [#]_. L'éditeur structuré indique des types hiérarchiques, des valeurs ou des mots-clés autorisés. Les mots-clés incomplets ou incorrects sont identifiés par @@ -144,9 +146,9 @@ Au final, il faut enregistrer le cas ADAO en utilisant le bouton "*Enregistrer*" choisissant l'entrée "*Enregistrer/ Enregistrer sous*" dans le menu "*ADAO*". Il est alors demandé un emplacement, à choisir dans l'arborescence des fichiers, et un nom, qui sera complété par l'extension "*.comm*" utilisée pour les fichiers -JDC d'EFICAS. Cette action va générer une paire de fichiers décrivant le cas -ADAO, avec le même nom de base, le premier présentant une extension "*.comm*" et -le second une extension "*.py*" [#]_. +de l'éditeur intégre de cas. Cette action va générer une paire de fichiers +décrivant le cas ADAO, avec le même nom de base, le premier présentant une +extension "*.comm*" et le second une extension "*.py*" [#]_. .. _section_u_step3: @@ -154,11 +156,11 @@ le second une extension "*.py*" [#]_. --------------------------------------------------- Lorsque le cas ADAO est complété, il doit être converti ou exporté sous la forme -d'un schéma YACS [#]_ pour pouvoir exécuter le calcul d'assimilation de -données. Cela peut être réalisé facilement en utilisant le bouton "*Exporter -vers YACS*" |eficas_yacs|, ou de manière équivalente en choisissant l'entrée -"*Exporter vers YACS*" dans le menu principal "*ADAO*", ou dans le menu -contextuel du cas dans le navigateur d'objets SALOME. +d'un schéma YACS pour pouvoir exécuter le calcul d'assimilation de données. Cela +peut être réalisé facilement en utilisant le bouton "*Exporter vers YACS*" +|eficas_yacs|, ou de manière équivalente en choisissant l'entrée "*Exporter vers +YACS*" dans le menu principal "*ADAO*", ou dans le menu contextuel du cas dans +le navigateur d'objets SALOME. .. _adao_exporttoyacs01: .. image:: images/adao_exporttoyacs.png @@ -181,7 +183,7 @@ fichier XML*. .. index:: single: Analysis -Lorsque le schéma YACS est généré et ouvert dans SALOME à travers le l'interface +Lorsque le schéma YACS est généré et ouvert dans SALOME à travers l'interface graphique du module YACS, on peut modifier ou compléter le schéma comme tout schéma YACS standard. Des noeuds ou des blocs peuvent être ajoutés, copiés ou modifiés pour élaborer une analyse complexe, ou pour insérer des capacités @@ -189,7 +191,7 @@ d'assimilation de donn plus complexes. Le principal complément nécessaire dans un schéma YACS est une étape de -post-processing. L'évaluation du résultat doit être réalisé dans le contexte +post-processing. L'évaluation du résultat doit être réalisée dans le contexte physique de simulation utilisé par la procédure d'assimilation de données. Le post-processing peut être fournit à travers le mot-clé "*UserPostAnalysis*" d'ADAO sous la forme d'un fichier de script ou d'une chaîne de caractères, par @@ -200,8 +202,8 @@ capacit description complète de ces éléments. En pratique, le schéma YACS dispose d'un port de sortie "*algoResults*" dans le -bloc de calcul, qui donne accès à un objet de type "*pyobj*" nommé ci-aprés -"*ADD*", qui contient tous les résultats de calcul. Ces résultats peuvent être +bloc de calcul, qui donne accès à un objet structuré nommé ci-aprés "*ADD*" par +exemple, qui contient tous les résultats de calcul. Ces résultats peuvent être obtenus en récupérant les variables nommées stockées au cours des calculs. L'information principale est la variable "*Analysis*", qui peut être obtenue par une commande python (par exemple dans un noeud script intégré ("in-line script @@ -262,10 +264,10 @@ pr L'exécution peut aussi être conduite en utilisant un script de commandes Shell, comme décrit dans la section :ref:`section_advanced`. -.. [#] Pour de plus amples informations sur EFICAS, voir le *module EFICAS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME. +.. [#] Pour de plus amples informations sur YACS, voir le *module YACS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME. -.. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent. +.. [#] Pour de plus amples informations sur l'éditeur intégré de cas, voir le *module EFICAS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME. -.. [#] Pour de plus amples informations sur YACS, voir le *module YACS* et son aide intégrée disponible dans le menu principal *Aide* de l'environnement SALOME. +.. [#] L'utilisation du code de simulation physique dans les opérateurs de base de l'assimilation de données est illustrée ou décrite dans les parties principales qui suivent. .. [#] Ce fichier python intermédiaire peut aussi être utilisé comme décrit dans la section :ref:`section_advanced`. diff --git a/src/daComposant/daAlgorithms/GradientTest.py b/src/daComposant/daAlgorithms/GradientTest.py index b7b0dff..b87370e 100644 --- a/src/daComposant/daAlgorithms/GradientTest.py +++ b/src/daComposant/daAlgorithms/GradientTest.py @@ -33,7 +33,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): default = "Taylor", typecast = str, message = "Formule de résidu utilisée", - listval = ["Norm", "Taylor"], + listval = ["Norm", "TaylorOnNorm", "Taylor"], ) self.defineRequiredParameter( name = "EpsilonMinimumExponent", @@ -91,7 +91,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): self.setParameters(Parameters) # Hm = HO["Direct"].appliedTo - if self._parameters["ResiduFormula"] == "Taylor": + if self._parameters["ResiduFormula"] in ["Taylor", "TaylorOnNorm"]: Ht = HO["Tangent"].appliedInXTo # # ---------- @@ -115,7 +115,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): # dX0 = float(self._parameters["AmplitudeOfInitialDirection"]) * numpy.matrix( dX0 ).T # - if self._parameters["ResiduFormula"] == "Taylor": + if self._parameters["ResiduFormula"] in ["Taylor", "TaylorOnNorm"]: GradFxdX = Ht( (X, dX0) ) GradFxdX = numpy.asmatrix(numpy.ravel( GradFxdX )).T # @@ -126,7 +126,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): __entete = " i Alpha ||X|| ||F(X)|| ||F(X+dX)|| ||dX|| ||F(X+dX)-F(X)|| ||F(X+dX)-F(X)||/||dX|| R(Alpha) log( R ) " __msgdoc = """ On observe le résidu issu du développement de Taylor de la fonction F, - normalisée par la valeur au point nominal : + normalisé par la valeur au point nominal : || F(X+Alpha*dX) - F(X) - Alpha * GradientF_X(dX) || R(Alpha) = ---------------------------------------------------- @@ -134,13 +134,38 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): Si le résidu décroit et que la décroissance se fait en Alpha**2 selon Alpha, cela signifie que le gradient est bien calculé jusqu'à la précision d'arrêt - de la décroissance quadratique et que F n'est pas linéaire. + de la décroissance quadratique, et que F n'est pas linéaire. Si le résidu décroit et que la décroissance se fait en Alpha selon Alpha, jusqu'à un certain seuil aprés lequel le résidu est faible et constant, cela signifie que F est linéaire et que le résidu décroit à partir de l'erreur faite dans le calcul du terme GradientF_X. + On prend dX0 = Normal(0,X) et dX = Alpha*dX0. F est le code de calcul. + """ + if self._parameters["ResiduFormula"] == "TaylorOnNorm": + __entete = " i Alpha ||X|| ||F(X)|| ||F(X+dX)|| ||dX|| ||F(X+dX)-F(X)|| ||F(X+dX)-F(X)||/||dX|| R(Alpha) log( R ) " + __msgdoc = """ + On observe le résidu issu du développement de Taylor de la fonction F, + rapporté au paramètre Alpha au carré : + + || F(X+Alpha*dX) - F(X) - Alpha * GradientF_X(dX) || + R(Alpha) = ---------------------------------------------------- + Alpha**2 + + C'est un résidu essentiellement similaire au critère classique de Taylor, + mais son comportement peut différer selon les propriétés numériques des + calculs de ses différents termes. + + Si le résidu est constant jusqu'à un certain seuil et croissant ensuite, + cela signifie que le gradient est bien calculé jusqu'à cette précision + d'arrêt, et que F n'est pas linéaire. + + Si le résidu est systématiquement croissant en partant d'une valeur faible + par rapport à ||F(X)||, cela signifie que F est (quasi-)linéaire et que le + calcul du gradient est correct jusqu'au moment où le résidu est de l'ordre de + grandeur de ||F(X)||. + On prend dX0 = Normal(0,X) et dX = Alpha*dX0. F est le code de calcul. """ if self._parameters["ResiduFormula"] == "Norm": @@ -192,7 +217,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): NormedFX = numpy.linalg.norm( FX_plus_dX - FX ) NormedFXsdX = NormedFX/NormedX # Residu Taylor - if self._parameters["ResiduFormula"] == "Taylor": + if self._parameters["ResiduFormula"] in ["Taylor", "TaylorOnNorm"]: NormedFXGdX = numpy.linalg.norm( FX_plus_dX - FX - amplitude * GradFxdX ) # Residu Norm NormedFXsAm = NormedFX/amplitude @@ -203,13 +228,15 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): NormesdX.append( NormedX ) NormesFXdX.append( NormeFXdX ) NormesdFX.append( NormedFX ) - if self._parameters["ResiduFormula"] == "Taylor": + if self._parameters["ResiduFormula"] in ["Taylor", "TaylorOnNorm"]: NormesdFXGdX.append( NormedFXGdX ) NormesdFXsdX.append( NormedFXsdX ) NormesdFXsAm.append( NormedFXsAm ) # if self._parameters["ResiduFormula"] == "Taylor": Residu = NormedFXGdX / NormeFX + elif self._parameters["ResiduFormula"] == "TaylorOnNorm": + Residu = NormedFXGdX / (amplitude*amplitude) elif self._parameters["ResiduFormula"] == "Norm": Residu = NormedFXsAm if Normalisation < 0 : Normalisation = Residu @@ -233,7 +260,7 @@ class ElementaryAlgorithm(BasicObjects.Algorithm): f.close() # Residus = self.StoredVariables["CostFunctionJ"][-len(Perturbations):] - if self._parameters["ResiduFormula"] == "Taylor": + if self._parameters["ResiduFormula"] in ["Taylor", "TaylorOnNorm"]: PerturbationsCarre = [ 10**(2*i) for i in xrange(-len(NormesdFXGdX)+1,1) ] PerturbationsCarre.reverse() dessiner( -- 2.39.2