From a47acfb199262cd968276bcaaee2ce57a30f2eee Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Mon, 4 Apr 2022 13:14:18 +0200 Subject: [PATCH] Documentation improvements and review --- doc/en/advanced.rst | 25 ++++++++++--------- doc/en/snippets/CostDecrementTolerance.rst | 2 +- doc/en/snippets/CostDecrementTolerance_6.rst | 2 +- doc/en/snippets/MaximumNumberOfIterations.rst | 2 +- doc/fr/advanced.rst | 20 +++++++-------- 5 files changed, 26 insertions(+), 25 deletions(-) diff --git a/doc/en/advanced.rst b/doc/en/advanced.rst index 2877cdd..695c07d 100644 --- a/doc/en/advanced.rst +++ b/doc/en/advanced.rst @@ -534,8 +534,8 @@ for other ones like the :ref:`section_ref_algorithm_DerivativeFreeOptimization` or :ref:`section_ref_algorithm_QuantileRegression`. In practice, a value between 10 and 30 is recommended to make this control parameter effective and still obtain an optimal search of good quality. For an optimal search of -sufficient quality, this restriction should not be set too strictly, i.e. a -limit of 30 should be better than 10. +sufficient quality, this restriction should not be set too strictly, i.e. a 30 +iteration limit should be more favorable than a 10 iteration limit. **A second way to control convergence is to adapt the relative decrement tolerance in the minimization of the cost functional considered**. This @@ -551,16 +551,17 @@ manifested by many successive iterations on almost identical states. finite difference approximation, primarily for the observation operator and a single-operator representation**. The control of this property is done with the keyword "*DifferentialIncrement*" which sets the definition using the -:ref:`section_ref_operator_one`. Its default value is 1%, and it can usually be -adjusted between :math:`10^{-5}` and :math:`10^{-3}` (although it is wise to -check carefully the relevance of its value, it is easy in ADAO to change this -parameter). The convergence criterion must then be adjusted so that it does not -exceed the order of magnitude of this approximation. In practice, it is -sufficient to set the "*CostDecrementTolerance*" criterion to approximately the -same precision (i.e. with an order of magnitude more or less) as the -"*DifferentialIncrement*" criterion. This way of improvement is also to be -completed with analyses using the :ref:`section_ref_algorithm_LinearityTest` -and :ref:`section_ref_algorithm_GradientTest`. +:ref:`section_ref_operator_one`. Its default value is :math:`10^{-2}` (or 1%), +and it can usually be adjusted between :math:`10^{-5}` and :math:`10^{-3}` +(although it is wise to check carefully the relevance of its value, it is easy +in ADAO to change this parameter). The convergence criterion must then be +adjusted so that it does not exceed the order of magnitude of this +approximation. In practice, it is sufficient to set the +"*CostDecrementTolerance*" criterion to approximately the same precision (i.e. +with an order of magnitude more or less) as the "*DifferentialIncrement*" +criterion. This way of improvement is also to be completed with analyses using +the :ref:`section_ref_algorithm_LinearityTest` and +:ref:`section_ref_algorithm_GradientTest`. From experience, it is *a priori* not recommended to use other means to control convergence, even if they exist. These parameter adjustments are simple to diff --git a/doc/en/snippets/CostDecrementTolerance.rst b/doc/en/snippets/CostDecrementTolerance.rst index 7b7b4a2..7dbbc2f 100644 --- a/doc/en/snippets/CostDecrementTolerance.rst +++ b/doc/en/snippets/CostDecrementTolerance.rst @@ -5,7 +5,7 @@ CostDecrementTolerance the iterative optimization process when the cost function decreases less than this tolerance at the last step. The default is 1.e-7, and it is recommended to adapt it to the needs on real problems. One can refer to the section - describing ways for ref:`subsection_iterative_convergence_control` for more + describing ways for :ref:`subsection_iterative_convergence_control` for more detailed recommendations. Example: diff --git a/doc/en/snippets/CostDecrementTolerance_6.rst b/doc/en/snippets/CostDecrementTolerance_6.rst index fe4a2a7..1f58693 100644 --- a/doc/en/snippets/CostDecrementTolerance_6.rst +++ b/doc/en/snippets/CostDecrementTolerance_6.rst @@ -5,7 +5,7 @@ CostDecrementTolerance the iterative optimization process when the cost function decreases less than this tolerance at the last step. The default is 1.e-6, and it is recommended to adapt it to the needs on real problems. One can refer to the section - describing ways for ref:`subsection_iterative_convergence_control` for more + describing ways for :ref:`subsection_iterative_convergence_control` for more detailed recommendations. Example: diff --git a/doc/en/snippets/MaximumNumberOfIterations.rst b/doc/en/snippets/MaximumNumberOfIterations.rst index 5325099..0aa003b 100644 --- a/doc/en/snippets/MaximumNumberOfIterations.rst +++ b/doc/en/snippets/MaximumNumberOfIterations.rst @@ -7,7 +7,7 @@ MaximumNumberOfIterations needs on real problems. For some optimizers, the effective stopping step can be slightly different of the limit due to algorithm internal control requirements. One can refer to the section describing ways for - ref:`subsection_iterative_convergence_control` for more detailed + :ref:`subsection_iterative_convergence_control` for more detailed recommendations. Example: diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst index 94b362b..896fc5d 100644 --- a/doc/fr/advanced.rst +++ b/doc/fr/advanced.rst @@ -582,8 +582,8 @@ ou :ref:`section_ref_algorithm_QuantileRegression`. Dans la pratique, on recommande une valeur comprise entre 10 et 30 pour rendre ce paramètre de contrôle effectif et obtenir quand même une recherche optimale de bonne qualité. Pour une recherche optimale de qualité suffisante, il convient de ne -pas fixer cette restriction trop strictement, c'est-à-dire qu'une limite de 30 -devrait être mieux que 10. +pas fixer cette restriction trop strictement, c'est-à-dire qu'une limite à 30 +itérations devrait être plus favorable qu'une limite à 10 itérations. **Un second moyen de contrôle de la convergence est d'adapter la tolérance de décroissance relative dans la minimisation de la fonctionnelle de coût @@ -602,14 +602,14 @@ défaut de l'approximation par différences finies, essentiellement pour l'opérateur d'observation et une représentation en mono-opérateur**. Le contrôle de cette propriété se fait à l'aide du mot-clé "*DifferentialIncrement*" qui paramètre la définition à l'aide de la -:ref:`section_ref_operator_one`. Sa valeur par défaut est de 1%, et il peut -généralement être ajusté entre :math:`10^{-5}` et :math:`10^{-3}` (même s'il -est sage de vérifier soigneusement la pertinence de sa valeur, il est aisé dans -ADAO de modifier ce paramètre). Le critère de convergence doit ensuite être -ajusté de telle sorte qu'il ne surpasse pas l'ordre de grandeur de cette -approximation. En pratique, on peut se contenter de fixer le critère -"*CostDecrementTolerance*" à peu près à la même précision (c'est-à-dire avec un -ordre de grandeur de plus ou de moins) que le critère +:ref:`section_ref_operator_one`. Sa valeur par défaut est de :math:`10^{-2}` +(ou 1%), et il peut généralement être ajusté entre :math:`10^{-5}` et +:math:`10^{-3}` (même s'il est sage de vérifier soigneusement la pertinence de +sa valeur, il est aisé dans ADAO de modifier ce paramètre). Le critère de +convergence doit ensuite être ajusté de telle sorte qu'il ne surpasse pas +l'ordre de grandeur de cette approximation. En pratique, on peut se contenter +de fixer le critère "*CostDecrementTolerance*" à peu près à la même précision +(c'est-à-dire avec un ordre de grandeur de plus ou de moins) que le critère "*DifferentialIncrement*". Ce moyen d'amélioration est aussi à compléter d'analyses à l'aide des :ref:`section_ref_algorithm_LinearityTest` et :ref:`section_ref_algorithm_GradientTest`. -- 2.39.2