It is also recalled that one have to choose the type "*multi*" for the default
container in order to launch the scheme, to allow a really parallel execution.
+.. _subsection_iterative_convergence_control:
+
+Convergence control for calculation cases and iterative algorithms
+------------------------------------------------------------------
+
+.. index:: single: Convergence
+.. index:: single: Iterative convergence
+
+There are many reasons to want to control the convergence of available
+calculation cases or algorithms in ADAO. For example, one may want
+*repeatability* of optimal solutions, certified *quality*, *stability* of
+optimal search conditions in studies, *saving of global computation time*, etc.
+Moreover, we notice that the methods used in ADAO are frequently iterative,
+reinforcing the interest of this convergence control.
+
+By default, **the available calculation cases or algorithms in ADAO give access
+to multiple ways to control their convergence, specially adapted to each
+method**. These controls are derived from classical optimization theory and
+from the possibilities of each algorithm. The default values of the controls
+are chosen to ensure an optimal search for high quality simulation functions
+with "*standard*" behavior (regularity, physical and numerical quality...),
+which is not necessarily the main property of real simulations due to various
+constraints. It is therefore quite normal to adapt the convergence criteria to
+the study cases encountered, but it is an expert approach to establish the
+correct adaptation.
+
+There are fairly generic ways to control the optimal search and the convergence
+of algorithms. We indicate here the most useful ones, in a non-exhaustive way,
+and with the significant restriction that there are many exceptions to the
+recommendations made. To go further, this generic information must be completed
+by the information specific to each algorithm or calculation case, indicated in
+the documentation of the different :ref:`section_reference_assimilation`.
+
+**A first way is to limit the default number of iterations in the iterative
+search processes**. Even if this is not the best theoretical way to control the
+algorithm, it is very effective in a real study process. For this purpose, the
+keyword "*MaximumNumberOfSteps*" exists in all cases of calculations that
+support it, and its default value is usually set to an equivalent of infinity
+so that it is not the stopping criterion. This is the case for calculations
+based on variational methods such as :ref:`section_ref_algorithm_3DVAR`,
+:ref:`section_ref_algorithm_4DVAR` and
+:ref:`section_ref_algorithm_NonLinearLeastSquares`, but this is also the case
+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.
+
+**A second way to control convergence is to adapt the relative decrement
+tolerance in the minimization of the cost functional considered**. This
+tolerance is controlled by the keyword "*CostDecrementTolerance*" in the
+algorithms that support it. The default value is rather strict, it is chosen
+for a theoretical convergence control when the numerical simulations are of
+high numerical quality. In practice, it can be adapted without hesitation to be
+between :math:`10^{-5}` and :math:`10^{-2}`. This adaptation allows in
+particular to reduce or avoid the difficulties of optimal search which are
+manifested by many successive iterations on almost identical states.
+
+**A third way to improve convergence is to adapt the default setting of the
+finite difference approximation, primarily for the observation operator**. 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.
+
+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
+implement, and it is favorable to try them (in twin experiments or not) because
+they solve many problems encountered in practice.
+
.. _subsection_new_adao_version:
Switching from a version of ADAO to a newer one
internal cache mechanism is used to restrict the number of operator evaluations
at the minimum possible in a sequential or parallel execution scheme for
numerical approximations of the tangent and adjoint operators, to avoid
-redundant calculations.
+redundant calculations. One can refer to the section dealing with
+:ref:`subsection_iterative_convergence_control` to discover the interaction
+with the convergence parameters.
This first operator definition form allows easily to test the functional form
before its use in an ADAO case, greatly reducing the complexity of operator
*Real value*. This key indicates a limit value, leading to stop successfully
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.
+ 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
+ detailed recommendations.
Example:
``{"CostDecrementTolerance":1.e-7}``
*Real value*. This key indicates a limit value, leading to stop successfully
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.
+ 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
+ detailed recommendations.
Example:
``{"CostDecrementTolerance":1.e-6}``
limit on iterations. It is then recommended to adapt this parameter to the
needs on real problems. For some optimizers, the effective stopping step can
be slightly different of the limit due to algorithm internal control
- requirements.
+ requirements. One can refer to the section describing ways for
+ ref:`subsection_iterative_convergence_control` for more detailed
+ recommendations.
Example:
``{"MaximumNumberOfSteps":100}``
"*multi*" pour le lancement du schéma, pour permettre une exécution
véritablement parallèle.
+.. _subsection_iterative_convergence_control:
+
+Contrôler la convergence pour des cas de calculs et algorithmes itératifs
+-------------------------------------------------------------------------
+
+.. index:: single: Convergence
+.. index:: single: Convergence itérative
+
+Il existe de nombreuses raisons de vouloir contrôler la convergence des cas de
+calculs ou algorithmes disponibles dans ADAO. Par exemple, on peut vouloir de
+la *reproductibilité* des solutions optimales, une *qualité* certifiée, une
+*stabilité* des conditions de recherche optimale en études, une *économie du
+temps de calcul* global, etc. De plus, on remarque que les méthodes utilisées
+dans ADAO sont fréquemment itératives, renforçant l'intérêt de ce contrôle de
+convergence.
+
+Par défaut, **les cas de calculs ou algorithmes disponibles dans ADAO donnent
+accès à de multiples moyens de contrôler leur convergence, spécialement adaptés
+à chaque méthode**. Ces moyens de contrôle sont issus de la théorie classique
+de l'optimisation et des capacités de chaque algorithme. Les valeurs par défaut
+des contrôles sont choisies pour assurer une recherche optimale de qualité sur
+des fonctions de simulation aux comportements "*standards*" (régularité,
+qualité physique et numérique...), ce qui n'est pas forcément la propriété
+principale des simulations réelles en raison de contraintes variées. Il est
+donc tout à fait normal d'adapter les critères de convergence aux cas d'études
+rencontrés, mais c'est une démarche d'expertise que d'établir la bonne
+adaptation.
+
+Il existe des manières assez génériques de contrôler la recherche optimale et
+la convergence des algorithmes. On en indique ici les plus utiles, de manière
+non exhaustive, et avec l'importante réserve qu'il y a fréquemment des
+exceptions aux recommandations formulées. Pour aller plus loin, ces
+informations génériques sont impérativement à compléter par les informations
+spécifiques à chaque algorithme ou cas de calcul, indiquées dans la
+documentation des différents :ref:`section_reference_assimilation`.
+
+**Un premier moyen est de limiter le nombre d'itérations par défaut dans les
+processus de recherches itératives**. Même si ce n'est pas la meilleure manière
+théorique de contrôler l'algorithme, elle est très efficace dans un processus
+d'étude réelle. Pour cela, le mot-clé "*MaximumNumberOfSteps*" existe dans tous
+les cas de calculs qui le supportent, et sa valeur par défaut est usuellement
+fixée à un équivalent de l'infini pour que ce ne soit pas le critère d'arrêt.
+C'est le cas pour les calculs à base de méthodes variationnelles comme les
+:ref:`section_ref_algorithm_3DVAR`, :ref:`section_ref_algorithm_4DVAR` et
+:ref:`section_ref_algorithm_NonLinearLeastSquares`, mais c'est aussi le cas
+pour d'autres comme les :ref:`section_ref_algorithm_DerivativeFreeOptimization`
+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.
+
+**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
+considérée**. Cette tolérance est contrôlée par le mot-clé
+"*CostDecrementTolerance*" dans les algorithmes qui le supportent. La valeur
+par défaut est plutôt stricte, elle est choisie pour un contrôle théorique de
+convergence lorsque les simulations numériques sont d'une qualité numérique
+importante. Dans la pratique, elle peut être adaptée sans hésitation pour
+valoir entre :math:`10^{-5}` et :math:`10^{-2}`. Cette adaptation permet en
+particulier de réduire ou d'éviter les difficultés de recherche optimale qui se
+manifestent par de nombreuses itérations successives portant sur des états
+presque identiques.
+
+**Un troisième moyen d'améliorer la convergence est d'adapter le réglage par
+défaut de l'approximation par différences finies, essentiellement pour
+l'opérateur d'observation**. 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
+"*DifferentialIncrement*".
+
+Par expérience, il n'est *a priori* pas recommandé d'utiliser d'autres moyens
+de contrôler la convergence, même s'il en existe. Ces ajustements de paramètres
+sont simples à mettre en œuvre, et il est favorable de les essayer (en
+expériences jumelles ou pas) car ils résolvent de nombreux problèmes rencontrés
+en pratique.
+
.. _subsection_new_adao_version:
Passer d'une version d'ADAO à une nouvelle
interne permet de limiter le nombre d'évaluations de l'opérateur au minimum
possible du point de vue de l'exécution séquentielle ou parallèle des
approximations numériques des opérateurs tangent et adjoint, pour éviter des
-calculs redondants.
+calculs redondants. On se reportera à la partie permettant de
+:ref:`subsection_iterative_convergence_control` pour connaître l'interaction
+avec les paramètres relatifs à la convergence.
Cette première forme de définition de l'opérateur permet aisément de tester la
forme fonctionnelle avant son usage dans un cas ADAO, réduisant notablement la
*Valeur réelle*. Cette clé indique une valeur limite, conduisant à arrêter le
processus itératif d'optimisation lorsque la fonction coût décroît moins que
cette tolérance au dernier pas. Le défaut est de 1.e-7, et il est recommandé
- de l'adapter aux besoins pour des problèmes réels.
+ de l'adapter aux besoins pour des problèmes réels. On peut se reporter à la
+ partie décrivant les manières de
+ :ref:`subsection_iterative_convergence_control` pour des recommandations plus
+ détaillées.
Exemple :
``{"CostDecrementTolerance":1.e-7}``
*Valeur réelle*. Cette clé indique une valeur limite, conduisant à arrêter le
processus itératif d'optimisation lorsque la fonction coût décroît moins que
cette tolérance au dernier pas. Le défaut est de 1.e-6, et il est recommandé
- de l'adapter aux besoins pour des problèmes réels.
+ de l'adapter aux besoins pour des problèmes réels. On peut se reporter à la
+ partie décrivant les manières de
+ :ref:`subsection_iterative_convergence_control` pour des recommandations plus
+ détaillées.
Exemple :
``{"CostDecrementTolerance":1.e-6}``
absence de limite sur les itérations. Il est ainsi recommandé d'adapter ce
paramètre aux besoins pour des problèmes réels. Pour certains optimiseurs, le
nombre de pas effectif d'arrêt peut être légèrement différent de la limite à
- cause d'exigences de contrôle interne de l'algorithme.
+ cause d'exigences de contrôle interne de l'algorithme. On peut se reporter à
+ la partie décrivant les manières de
+ :ref:`subsection_iterative_convergence_control` pour des recommandations plus
+ détaillées.
Exemple :
``{"MaximumNumberOfSteps":100}``
