From 6da595f45d1a2749eef75c8b0250875fa9e00c86 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Thu, 27 Jan 2022 18:51:41 +0100 Subject: [PATCH] Documentation review and update for *Tests --- doc/en/ref_algorithm_GradientTest.rst | 20 ++++------------- doc/en/ref_algorithm_LinearityTest.rst | 21 ++++-------------- doc/en/ref_algorithm_TangentTest.rst | 2 ++ .../AmplitudeOfTangentPerturbation.rst | 11 ++++++++++ .../snippets/ResiduFormula_GradientTest.rst | 15 +++++++++++++ .../snippets/ResiduFormula_LinearityTest.rst | 16 ++++++++++++++ doc/fr/ref_algorithm_GradientTest.rst | 19 ++++------------ doc/fr/ref_algorithm_LinearityTest.rst | 22 ++++--------------- doc/fr/ref_algorithm_TangentTest.rst | 2 ++ .../AmplitudeOfTangentPerturbation.rst | 11 ++++++++++ .../snippets/ResiduFormula_GradientTest.rst | 14 ++++++++++++ .../snippets/ResiduFormula_LinearityTest.rst | 17 ++++++++++++++ 12 files changed, 104 insertions(+), 66 deletions(-) create mode 100644 doc/en/snippets/AmplitudeOfTangentPerturbation.rst create mode 100644 doc/en/snippets/ResiduFormula_GradientTest.rst create mode 100644 doc/en/snippets/ResiduFormula_LinearityTest.rst create mode 100644 doc/fr/snippets/AmplitudeOfTangentPerturbation.rst create mode 100644 doc/fr/snippets/ResiduFormula_GradientTest.rst create mode 100644 doc/fr/snippets/ResiduFormula_LinearityTest.rst diff --git a/doc/en/ref_algorithm_GradientTest.rst b/doc/en/ref_algorithm_GradientTest.rst index a86fd21..01e66e9 100644 --- a/doc/en/ref_algorithm_GradientTest.rst +++ b/doc/en/ref_algorithm_GradientTest.rst @@ -100,27 +100,15 @@ which has to remain stable until the calculation precision is reached. .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst -.. include:: snippets/SetSeed.rst - -ResiduFormula - .. index:: single: ResiduFormula +.. include:: snippets/ResiduFormula_GradientTest.rst - *Predefined name*. 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" (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 - perturbation 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"}`` +.. include:: snippets/SetSeed.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/en/ref_algorithm_LinearityTest.rst b/doc/en/ref_algorithm_LinearityTest.rst index 05ad52a..e3fd85c 100644 --- a/doc/en/ref_algorithm_LinearityTest.rst +++ b/doc/en/ref_algorithm_LinearityTest.rst @@ -121,28 +121,15 @@ If it is equal to 0 only on part of the variation domain of increment .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst -.. include:: snippets/SetSeed.rst - -ResiduFormula - .. index:: single: ResiduFormula +.. include:: snippets/ResiduFormula_LinearityTest.rst - *Predefined name*. This key indicates the residue formula that has to be - used for the test. The default choice is "CenteredDL", and the possible ones - are "CenteredDL" (residue of the difference between the function at nominal - point and the values with positive and negative increments, which has to stay - very small), "Taylor" (residue of the Taylor development of the operator - normalized by the nominal value, which has to stay very small), - "NominalTaylor" (residue of the order 1 approximations of the operator, - normalized to the nominal point, which has to stay close to 1), and - "NominalTaylorRMS" (residue of the order 1 approximations of the operator, - normalized by RMS to the nominal point, which has to stay close to 0). - - Example : - ``{"ResiduFormula":"CenteredDL"}`` +.. include:: snippets/SetSeed.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/en/ref_algorithm_TangentTest.rst b/doc/en/ref_algorithm_TangentTest.rst index 9607599..49abb58 100644 --- a/doc/en/ref_algorithm_TangentTest.rst +++ b/doc/en/ref_algorithm_TangentTest.rst @@ -64,6 +64,8 @@ One take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst diff --git a/doc/en/snippets/AmplitudeOfTangentPerturbation.rst b/doc/en/snippets/AmplitudeOfTangentPerturbation.rst new file mode 100644 index 0000000..75d1be0 --- /dev/null +++ b/doc/en/snippets/AmplitudeOfTangentPerturbation.rst @@ -0,0 +1,11 @@ +.. index:: single: AmplitudeOfTangentPerturbation + +AmplitudeOfTangentPerturbation + *Real value*. This key indicates the relative numerical magnitude of the + perturbation used to estimate the tangent value of the operator at the + evaluation point, i.e. its directional derivative. The conservative default + is 1.e-2, and it is strongly recommended to adapt it to the needs of real + problems, by decreasing its value by several orders of magnitude. + + Example : + ``{"AmplitudeOfTangentPerturbation":1.e-2}`` diff --git a/doc/en/snippets/ResiduFormula_GradientTest.rst b/doc/en/snippets/ResiduFormula_GradientTest.rst new file mode 100644 index 0000000..450e4c7 --- /dev/null +++ b/doc/en/snippets/ResiduFormula_GradientTest.rst @@ -0,0 +1,15 @@ +.. index:: single: ResiduFormula + +ResiduFormula + *Predefined name*. 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" (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 + perturbation 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/snippets/ResiduFormula_LinearityTest.rst b/doc/en/snippets/ResiduFormula_LinearityTest.rst new file mode 100644 index 0000000..0da3f39 --- /dev/null +++ b/doc/en/snippets/ResiduFormula_LinearityTest.rst @@ -0,0 +1,16 @@ +.. index:: single: ResiduFormula + +ResiduFormula + *Predefined name*. This key indicates the residue formula that has to be + used for the test. The default choice is "CenteredDL", and the possible ones + are "CenteredDL" (residue of the difference between the function at nominal + point and the values with positive and negative increments, which has to stay + very small), "Taylor" (residue of the Taylor development of the operator + normalized by the nominal value, which has to stay very small), + "NominalTaylor" (residue of the order 1 approximations of the operator, + normalized to the nominal point, which has to stay close to 1), and + "NominalTaylorRMS" (residue of the order 1 approximations of the operator, + normalized by RMS to the nominal point, which has to stay close to 0). + + Example : + ``{"ResiduFormula":"CenteredDL"}`` diff --git a/doc/fr/ref_algorithm_GradientTest.rst b/doc/fr/ref_algorithm_GradientTest.rst index 3ee6397..41249fb 100644 --- a/doc/fr/ref_algorithm_GradientTest.rst +++ b/doc/fr/ref_algorithm_GradientTest.rst @@ -99,26 +99,15 @@ qui doit rester constant jusqu'à ce que l'on atteigne la précision du calcul. .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst -.. include:: snippets/SetSeed.rst - -ResiduFormula - .. index:: single: ResiduFormula +.. include:: snippets/ResiduFormula_GradientTest.rst - *Nom prédéfini*. 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 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). - - Exemple : - ``{"ResiduFormula":"Taylor"}`` +.. include:: snippets/SetSeed.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/fr/ref_algorithm_LinearityTest.rst b/doc/fr/ref_algorithm_LinearityTest.rst index ee44bb0..715813b 100644 --- a/doc/fr/ref_algorithm_LinearityTest.rst +++ b/doc/fr/ref_algorithm_LinearityTest.rst @@ -120,29 +120,15 @@ de F est vérifiée. .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst -.. include:: snippets/SetSeed.rst - -ResiduFormula - .. index:: single: ResiduFormula - - *Nom prédéfini*. Cette clé indique la formule de résidu qui doit être - utilisée pour le test. Le choix par défaut est "CenteredDL", et les choix - possibles sont "CenteredDL" (résidu de la différence entre la fonction au - point nominal et ses valeurs avec des incréments positif et négatif, qui doit - rester très faible), "Taylor" (résidu du développement de Taylor de - l'opérateur normalisé par sa valeur nominal, qui doit rester très faible), - "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur, - normalisé au point nominal, qui doit rester proche de 1), et - "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur, - normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit - rester proche de 0). +.. include:: snippets/ResiduFormula_LinearityTest.rst - Exemple : - ``{"ResiduFormula":"CenteredDL"}`` +.. include:: snippets/SetSeed.rst StoreSupplementaryCalculations .. index:: single: StoreSupplementaryCalculations diff --git a/doc/fr/ref_algorithm_TangentTest.rst b/doc/fr/ref_algorithm_TangentTest.rst index 20a3b4e..485ee55 100644 --- a/doc/fr/ref_algorithm_TangentTest.rst +++ b/doc/fr/ref_algorithm_TangentTest.rst @@ -65,6 +65,8 @@ On prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et .. include:: snippets/AmplitudeOfInitialDirection.rst +.. include:: snippets/AmplitudeOfTangentPerturbation.rst + .. include:: snippets/EpsilonMinimumExponent.rst .. include:: snippets/InitialDirection.rst diff --git a/doc/fr/snippets/AmplitudeOfTangentPerturbation.rst b/doc/fr/snippets/AmplitudeOfTangentPerturbation.rst new file mode 100644 index 0000000..af42bf7 --- /dev/null +++ b/doc/fr/snippets/AmplitudeOfTangentPerturbation.rst @@ -0,0 +1,11 @@ +.. index:: single: AmplitudeOfTangentPerturbation + +AmplitudeOfTangentPerturbation + *Valeur réelle*. Cette clé indique l'amplitude numérique relative de la + perturbation utilisée pour estimer la valeur tangente de l'opérateur au point + d'évaluation, i.e. sa dérivée directionnelle. Le défaut conservatif est de + 1.e-2, et il est fortement recommandé de l'adapter aux besoins pour des + problèmes réels, en diminuant sa valeur de plusieurs ordres de grandeur. + + Exemple : + ``{"AmplitudeOfTangentPerturbation":1.e-2}`` diff --git a/doc/fr/snippets/ResiduFormula_GradientTest.rst b/doc/fr/snippets/ResiduFormula_GradientTest.rst new file mode 100644 index 0000000..76d3830 --- /dev/null +++ b/doc/fr/snippets/ResiduFormula_GradientTest.rst @@ -0,0 +1,14 @@ +.. index:: single: ResiduFormula + +ResiduFormula + *Nom prédéfini*. 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 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). + + Exemple : + ``{"ResiduFormula":"Taylor"}`` diff --git a/doc/fr/snippets/ResiduFormula_LinearityTest.rst b/doc/fr/snippets/ResiduFormula_LinearityTest.rst new file mode 100644 index 0000000..a81aeaf --- /dev/null +++ b/doc/fr/snippets/ResiduFormula_LinearityTest.rst @@ -0,0 +1,17 @@ +.. index:: single: ResiduFormula + +ResiduFormula + *Nom prédéfini*. Cette clé indique la formule de résidu qui doit être + utilisée pour le test. Le choix par défaut est "CenteredDL", et les choix + possibles sont "CenteredDL" (résidu de la différence entre la fonction au + point nominal et ses valeurs avec des incréments positif et négatif, qui doit + rester très faible), "Taylor" (résidu du développement de Taylor de + l'opérateur normalisé par sa valeur nominal, qui doit rester très faible), + "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur, + normalisé au point nominal, qui doit rester proche de 1), et + "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur, + normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit + rester proche de 0). + + Exemple : + ``{"ResiduFormula":"CenteredDL"}`` -- 2.39.2