From 5c4f00206f27a56fac57b3f2b3c537b9b7cd63a3 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Mon, 26 Dec 2022 17:43:03 +0100 Subject: [PATCH] Documentation review corrections and improvements --- doc/en/ref_algorithm_FunctionTest.rst | 18 +++++- .../scripts/simple_FunctionTest1.py} | 4 +- ...ctionTest.res => simple_FunctionTest1.res} | 0 ...ctionTest.rst => simple_FunctionTest1.rst} | 9 ++- doc/en/scripts/simple_FunctionTest2.py | 30 ++++++++++ doc/en/scripts/simple_FunctionTest2.res | 60 +++++++++++++++++++ doc/en/scripts/simple_FunctionTest2.rst | 16 +++++ doc/fr/ref_algorithm_FunctionTest.rst | 17 +++++- .../scripts/simple_FunctionTest1.py} | 6 +- ...ctionTest.res => simple_FunctionTest1.res} | 0 ...ctionTest.rst => simple_FunctionTest1.rst} | 9 ++- doc/fr/scripts/simple_FunctionTest2.py | 30 ++++++++++ doc/fr/scripts/simple_FunctionTest2.res | 60 +++++++++++++++++++ doc/fr/scripts/simple_FunctionTest2.rst | 16 +++++ 14 files changed, 258 insertions(+), 17 deletions(-) rename doc/{fr/scripts/simple_FunctionTest.py => en/scripts/simple_FunctionTest1.py} (83%) rename doc/en/scripts/{simple_FunctionTest.res => simple_FunctionTest1.res} (100%) rename doc/en/scripts/{simple_FunctionTest.rst => simple_FunctionTest1.rst} (78%) create mode 100644 doc/en/scripts/simple_FunctionTest2.py create mode 100644 doc/en/scripts/simple_FunctionTest2.res create mode 100644 doc/en/scripts/simple_FunctionTest2.rst rename doc/{en/scripts/simple_FunctionTest.py => fr/scripts/simple_FunctionTest1.py} (74%) rename doc/fr/scripts/{simple_FunctionTest.res => simple_FunctionTest1.res} (100%) rename doc/fr/scripts/{simple_FunctionTest.rst => simple_FunctionTest1.rst} (77%) create mode 100644 doc/fr/scripts/simple_FunctionTest2.py create mode 100644 doc/fr/scripts/simple_FunctionTest2.res create mode 100644 doc/fr/scripts/simple_FunctionTest2.rst diff --git a/doc/en/ref_algorithm_FunctionTest.rst b/doc/en/ref_algorithm_FunctionTest.rst index 7261d48..cb6e896 100644 --- a/doc/en/ref_algorithm_FunctionTest.rst +++ b/doc/en/ref_algorithm_FunctionTest.rst @@ -96,13 +96,25 @@ StoreSupplementaryCalculations .. _section_ref_algorithm_FunctionTest_examples: .. include:: snippets/Header2Algo09.rst -.. include:: scripts/simple_FunctionTest.rst +.. --------- .. +.. include:: scripts/simple_FunctionTest1.rst -.. literalinclude:: scripts/simple_FunctionTest.py +.. literalinclude:: scripts/simple_FunctionTest1.py .. include:: snippets/Header2Algo10.rst -.. literalinclude:: scripts/simple_FunctionTest.res +.. literalinclude:: scripts/simple_FunctionTest1.res + :language: none + +.. --------- .. +.. include:: scripts/simple_FunctionTest2.rst + +.. literalinclude:: scripts/simple_FunctionTest2.py + +.. include:: snippets/Header2Algo10.rst + +.. literalinclude:: scripts/simple_FunctionTest2.res + :language: none .. ------------------------------------ .. .. include:: snippets/Header2Algo06.rst diff --git a/doc/fr/scripts/simple_FunctionTest.py b/doc/en/scripts/simple_FunctionTest1.py similarity index 83% rename from doc/fr/scripts/simple_FunctionTest.py rename to doc/en/scripts/simple_FunctionTest1.py index d99ec9f..2c78348 100644 --- a/doc/fr/scripts/simple_FunctionTest.py +++ b/doc/en/scripts/simple_FunctionTest1.py @@ -2,9 +2,9 @@ # from numpy import array, eye from adao import adaoBuilder -case = adaoBuilder.New('') +case = adaoBuilder.New() case.setCheckingPoint( Vector = array([0., 1., 2.]), Stored=True ) -case.setObservationOperator( Matrix = eye(3), ) +case.setObservationOperator( Matrix = eye(3) ) case.setAlgorithmParameters( Algorithm='FunctionTest', Parameters={ diff --git a/doc/en/scripts/simple_FunctionTest.res b/doc/en/scripts/simple_FunctionTest1.res similarity index 100% rename from doc/en/scripts/simple_FunctionTest.res rename to doc/en/scripts/simple_FunctionTest1.res diff --git a/doc/en/scripts/simple_FunctionTest.rst b/doc/en/scripts/simple_FunctionTest1.rst similarity index 78% rename from doc/en/scripts/simple_FunctionTest.rst rename to doc/en/scripts/simple_FunctionTest1.rst index e147d6f..ad2aeb2 100644 --- a/doc/en/scripts/simple_FunctionTest.rst +++ b/doc/en/scripts/simple_FunctionTest1.rst @@ -1,11 +1,14 @@ .. index:: single: FunctionTest (example) +First example +............. + This example describes the test of the correct operation of a given operator, and that its call proceeds in a way compatible with its common use in the ADAO algorithms. The required information are minimal, namely here an operator -:math:`F` (described for the test by the observation command -"*ObservationOperator*"), and a state :math:`\mathbf{x}^b` to test it on -(described for the test by the command "*CheckingPoint*"). +:math:`F` (described for the test by the command "*ObservationOperator*"), and +a particular state :math:`\mathbf{x}` to test it on (described for the test by +the command "*CheckingPoint*"). The test is repeated a configurable number of times, and a final statistic makes it possible to quickly verify the operator's good behavior. The simplest diff --git a/doc/en/scripts/simple_FunctionTest2.py b/doc/en/scripts/simple_FunctionTest2.py new file mode 100644 index 0000000..ed5bf9c --- /dev/null +++ b/doc/en/scripts/simple_FunctionTest2.py @@ -0,0 +1,30 @@ +# -*- coding: utf-8 -*- +# +from numpy import array, ravel +def QuadFunction( coefficients ): + """ + Quadratic simulation in x: y = a x^2 + b x + c + """ + a, b, c = list(ravel(coefficients)) + x_points = (-5, 0, 1, 3, 10) + y_points = [] + for x in x_points: + y_points.append( a*x*x + b*x + c ) + return array(y_points) +# +# (Re)naming statement for the simulation function +DirectOperator = QuadFunction +# +from adao import adaoBuilder +case = adaoBuilder.New() +case.setCheckingPoint( Vector = array([1., 1., 1.]), Stored=True ) +case.setObservationOperator( OneFunction = DirectOperator ) +case.setAlgorithmParameters( + Algorithm='FunctionTest', + Parameters={ + 'NumberOfRepetition' : 15, + 'NumberOfPrintedDigits' : 3, + 'ShowElementarySummary':False, + }, + ) +case.execute() diff --git a/doc/en/scripts/simple_FunctionTest2.res b/doc/en/scripts/simple_FunctionTest2.res new file mode 100644 index 0000000..6176669 --- /dev/null +++ b/doc/en/scripts/simple_FunctionTest2.res @@ -0,0 +1,60 @@ + + FUNCTIONTEST + ============ + + This test allows to analyze the (repetition of) launch of some given + operator. It shows simple statistics related to its successful execution, + or related to the similarities of repetition of its execution. + +===> Information before launching: + ----------------------------- + Characteristics of input vector X, internally converted: + Type...............: + Length of vector...: 3 + Minimum value......: 1.000e+00 + Maximum value......: 1.000e+00 + Mean of vector.....: 1.000e+00 + Standard error.....: 0.000e+00 + L2 norm of vector..: 1.732e+00 + + --------------------------------------------------------------------------- + +===> Beginning of repeated evaluation, without activating debug + + --------------------------------------------------------------------------- + +===> End of repeated evaluation, without deactivating debug + + --------------------------------------------------------------------------- + +===> Launching statistical summary calculation for 15 states + + --------------------------------------------------------------------------- + +===> Statistical analysis of the outputs obtained through sequential repeated evaluations + + (Remark: numbers that are (about) under 2e-16 represent 0 to machine precision) + + Characteristics of the whole set of outputs Y: + Number of evaluations.........................: 15 + Minimum value of the whole set of outputs.....: 1.000e+00 + Maximum value of the whole set of outputs.....: 1.110e+02 + Mean of vector of the whole set of outputs....: 2.980e+01 + Standard error of the whole set of outputs....: 4.123e+01 + + Characteristics of the vector Ym, mean of the outputs Y: + Size of the mean of the outputs...............: 5 + Minimum value of the mean of the outputs......: 1.000e+00 + Maximum value of the mean of the outputs......: 1.110e+02 + Mean of the mean of the outputs...............: 2.980e+01 + Standard error of the mean of the outputs.....: 4.123e+01 + + Characteristics of the mean of the differences between the outputs Y and their mean Ym: + Size of the mean of the differences...........: 5 + Minimum value of the mean of the differences..: 0.000e+00 + Maximum value of the mean of the differences..: 0.000e+00 + Mean of the mean of the differences...........: 0.000e+00 + Standard error of the mean of the differences.: 0.000e+00 + + --------------------------------------------------------------------------- + diff --git a/doc/en/scripts/simple_FunctionTest2.rst b/doc/en/scripts/simple_FunctionTest2.rst new file mode 100644 index 0000000..2e001dd --- /dev/null +++ b/doc/en/scripts/simple_FunctionTest2.rst @@ -0,0 +1,16 @@ +Second example +.............. + +This new example describes the test of the correct operation of a given +operator named ``QuadFunction``, available under its functional form. It is +defined by the command "*ObservationOperator*" as +:ref:`section_ref_operator_one`. Using the command "*CheckingPoint*", one add +also a particular state :math:`\mathbf{x}` to test the operator on. + +The test is repeated here 15 times, and a final statistic makes it possible to +quickly verify the operator's good behavior. The simplest diagnostic consists +in checking, at the very end of the display, the order of magnitude of the +values indicated as the mean of the differences between the repeated outputs +and their mean, under the part entitled "*Characteristics of the mean of the +differences between the outputs Y and their mean Ym*". For a satisfactory +operator, these values should be close to the numerical zero. diff --git a/doc/fr/ref_algorithm_FunctionTest.rst b/doc/fr/ref_algorithm_FunctionTest.rst index 7336b16..e55b0ad 100644 --- a/doc/fr/ref_algorithm_FunctionTest.rst +++ b/doc/fr/ref_algorithm_FunctionTest.rst @@ -97,13 +97,24 @@ StoreSupplementaryCalculations .. _section_ref_algorithm_FunctionTest_examples: .. include:: snippets/Header2Algo09.rst -.. include:: scripts/simple_FunctionTest.rst +.. --------- .. +.. include:: scripts/simple_FunctionTest1.rst -.. literalinclude:: scripts/simple_FunctionTest.py +.. literalinclude:: scripts/simple_FunctionTest1.py .. include:: snippets/Header2Algo10.rst -.. literalinclude:: scripts/simple_FunctionTest.res +.. literalinclude:: scripts/simple_FunctionTest1.res + :language: none + +.. --------- .. +.. include:: scripts/simple_FunctionTest2.rst + +.. literalinclude:: scripts/simple_FunctionTest2.py + +.. include:: snippets/Header2Algo10.rst + +.. literalinclude:: scripts/simple_FunctionTest2.res :language: none .. ------------------------------------ .. diff --git a/doc/en/scripts/simple_FunctionTest.py b/doc/fr/scripts/simple_FunctionTest1.py similarity index 74% rename from doc/en/scripts/simple_FunctionTest.py rename to doc/fr/scripts/simple_FunctionTest1.py index 638d6dd..2c78348 100644 --- a/doc/en/scripts/simple_FunctionTest.py +++ b/doc/fr/scripts/simple_FunctionTest1.py @@ -2,15 +2,15 @@ # from numpy import array, eye from adao import adaoBuilder -case = adaoBuilder.New('') +case = adaoBuilder.New() case.setCheckingPoint( Vector = array([0., 1., 2.]), Stored=True ) -case.setObservationOperator( Matrix = eye(3), ) +case.setObservationOperator( Matrix = eye(3) ) case.setAlgorithmParameters( Algorithm='FunctionTest', Parameters={ 'NumberOfRepetition' : 5, 'NumberOfPrintedDigits' : 2, - "ShowElementarySummary":False, + 'ShowElementarySummary':False, }, ) case.execute() diff --git a/doc/fr/scripts/simple_FunctionTest.res b/doc/fr/scripts/simple_FunctionTest1.res similarity index 100% rename from doc/fr/scripts/simple_FunctionTest.res rename to doc/fr/scripts/simple_FunctionTest1.res diff --git a/doc/fr/scripts/simple_FunctionTest.rst b/doc/fr/scripts/simple_FunctionTest1.rst similarity index 77% rename from doc/fr/scripts/simple_FunctionTest.rst rename to doc/fr/scripts/simple_FunctionTest1.rst index f988d3d..5c8fad2 100644 --- a/doc/fr/scripts/simple_FunctionTest.rst +++ b/doc/fr/scripts/simple_FunctionTest1.rst @@ -1,11 +1,14 @@ .. index:: single: FunctionTest (exemple) +Premier exemple +............... + Cet exemple décrit le test du bon fonctionnement d'un opérateur quelconque, et que son appel se déroule de manière compatible avec son usage courant dans les algorithmes d'ADAO. Les informations nécessaires sont minimales, à savoir ici -un opérateur :math:`F` (décrit pour le test par la commande d'observation -"*ObservationOperator*"), et un état :math:`\mathbf{x}^b` sur lequel le tester -(décrit pour le test par la commande "*CheckingPoint*"). +un opérateur (décrit pour le test par la commande d'observation +"*ObservationOperator*"), et un état particulier :math:`\mathbf{x}` sur lequel +le tester (décrit pour le test par la commande "*CheckingPoint*"). Le test est répété un nombre paramétrable de fois, et une statistique finale permet de vérifier rapidement le bon comportement de l'opérateur. Le diagnostic diff --git a/doc/fr/scripts/simple_FunctionTest2.py b/doc/fr/scripts/simple_FunctionTest2.py new file mode 100644 index 0000000..441ffbb --- /dev/null +++ b/doc/fr/scripts/simple_FunctionTest2.py @@ -0,0 +1,30 @@ +# -*- coding: utf-8 -*- +# +from numpy import array, ravel +def QuadFunction( coefficients ): + """ + Simulation quadratique aux points x : y = a x^2 + b x + c + """ + a, b, c = list(ravel(coefficients)) + x_points = (-5, 0, 1, 3, 10) + y_points = [] + for x in x_points: + y_points.append( a*x*x + b*x + c ) + return array(y_points) +# +# Déclaration de (re)nommage de la fonction de simulation +DirectOperator = QuadFunction +# +from adao import adaoBuilder +case = adaoBuilder.New() +case.setCheckingPoint( Vector = array([1., 1., 1.]), Stored=True ) +case.setObservationOperator( OneFunction = DirectOperator ) +case.setAlgorithmParameters( + Algorithm='FunctionTest', + Parameters={ + 'NumberOfRepetition' : 15, + 'NumberOfPrintedDigits' : 3, + 'ShowElementarySummary':False, + }, + ) +case.execute() diff --git a/doc/fr/scripts/simple_FunctionTest2.res b/doc/fr/scripts/simple_FunctionTest2.res new file mode 100644 index 0000000..6176669 --- /dev/null +++ b/doc/fr/scripts/simple_FunctionTest2.res @@ -0,0 +1,60 @@ + + FUNCTIONTEST + ============ + + This test allows to analyze the (repetition of) launch of some given + operator. It shows simple statistics related to its successful execution, + or related to the similarities of repetition of its execution. + +===> Information before launching: + ----------------------------- + Characteristics of input vector X, internally converted: + Type...............: + Length of vector...: 3 + Minimum value......: 1.000e+00 + Maximum value......: 1.000e+00 + Mean of vector.....: 1.000e+00 + Standard error.....: 0.000e+00 + L2 norm of vector..: 1.732e+00 + + --------------------------------------------------------------------------- + +===> Beginning of repeated evaluation, without activating debug + + --------------------------------------------------------------------------- + +===> End of repeated evaluation, without deactivating debug + + --------------------------------------------------------------------------- + +===> Launching statistical summary calculation for 15 states + + --------------------------------------------------------------------------- + +===> Statistical analysis of the outputs obtained through sequential repeated evaluations + + (Remark: numbers that are (about) under 2e-16 represent 0 to machine precision) + + Characteristics of the whole set of outputs Y: + Number of evaluations.........................: 15 + Minimum value of the whole set of outputs.....: 1.000e+00 + Maximum value of the whole set of outputs.....: 1.110e+02 + Mean of vector of the whole set of outputs....: 2.980e+01 + Standard error of the whole set of outputs....: 4.123e+01 + + Characteristics of the vector Ym, mean of the outputs Y: + Size of the mean of the outputs...............: 5 + Minimum value of the mean of the outputs......: 1.000e+00 + Maximum value of the mean of the outputs......: 1.110e+02 + Mean of the mean of the outputs...............: 2.980e+01 + Standard error of the mean of the outputs.....: 4.123e+01 + + Characteristics of the mean of the differences between the outputs Y and their mean Ym: + Size of the mean of the differences...........: 5 + Minimum value of the mean of the differences..: 0.000e+00 + Maximum value of the mean of the differences..: 0.000e+00 + Mean of the mean of the differences...........: 0.000e+00 + Standard error of the mean of the differences.: 0.000e+00 + + --------------------------------------------------------------------------- + diff --git a/doc/fr/scripts/simple_FunctionTest2.rst b/doc/fr/scripts/simple_FunctionTest2.rst new file mode 100644 index 0000000..ca702e1 --- /dev/null +++ b/doc/fr/scripts/simple_FunctionTest2.rst @@ -0,0 +1,16 @@ +Deuxième exemple +................ + +Ce nouvel exemple décrit le test du bon fonctionnement d'un opérateur +quelconque nommé ``QuadFunction``, disponible sous forme fonctionnelle. Il est +définit par la commande "*ObservationOperator*" selon la +:ref:`section_ref_operator_one`. Par la commande "*CheckingPoint*", on ajoute +aussi un état particulier :math:`\mathbf{x}` sur lequel tester l'opérateur. + +Ce test est répété ici 15 fois, et une statistique finale permet de vérifier +rapidement le bon comportement de l'opérateur. Le diagnostic le plus simple +consiste à vérifier, à la toute fin de l'affichage, l'ordre de grandeur des +valeurs indiquées comme la moyenne des différences entre les sorties répétées +et leur moyenne, sous la partie titrée "*Characteristics of the mean of the +differences between the outputs Y and their mean Ym*". Pour qu'un opérateur +soit satisfaisant, ces valeurs doivent être proches du zéro numérique. -- 2.39.2