From 0c657c1bbac92389e7d7d7a681223c54e24a263b Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Sun, 27 Sep 2015 14:53:12 +0200 Subject: [PATCH] Documentation correction and improvements --- doc/en/ref_algorithm_4DVAR.rst | 263 +++++++++++++++++ doc/en/ref_algorithm_ExtendedKalmanFilter.rst | 7 + doc/en/ref_algorithm_QuantileRegression.rst | 10 + .../ref_algorithm_UnscentedKalmanFilter.rst | 7 + doc/en/reference.rst | 1 + doc/en/tui.rst | 5 + doc/fr/ref_algorithm_3DVAR.rst | 4 +- doc/fr/ref_algorithm_4DVAR.rst | 273 ++++++++++++++++++ doc/fr/ref_algorithm_AdjointTest.rst | 4 +- doc/fr/ref_algorithm_Blue.rst | 4 +- doc/fr/ref_algorithm_EnsembleBlue.rst | 4 +- doc/fr/ref_algorithm_ExtendedBlue.rst | 4 +- doc/fr/ref_algorithm_ExtendedKalmanFilter.rst | 15 +- doc/fr/ref_algorithm_FunctionTest.rst | 4 +- doc/fr/ref_algorithm_GradientTest.rst | 4 +- doc/fr/ref_algorithm_KalmanFilter.rst | 10 +- doc/fr/ref_algorithm_LinearLeastSquares.rst | 4 +- doc/fr/ref_algorithm_LinearityTest.rst | 4 +- .../ref_algorithm_NonLinearLeastSquares.rst | 4 +- ...ef_algorithm_ParticleSwarmOptimization.rst | 4 +- doc/fr/ref_algorithm_QuantileRegression.rst | 15 +- doc/fr/ref_algorithm_SamplingTest.rst | 4 +- doc/fr/ref_algorithm_TangentTest.rst | 4 +- .../ref_algorithm_UnscentedKalmanFilter.rst | 11 +- doc/fr/reference.rst | 1 + doc/fr/tui.rst | 6 + 26 files changed, 637 insertions(+), 39 deletions(-) create mode 100644 doc/en/ref_algorithm_4DVAR.rst create mode 100644 doc/fr/ref_algorithm_4DVAR.rst diff --git a/doc/en/ref_algorithm_4DVAR.rst b/doc/en/ref_algorithm_4DVAR.rst new file mode 100644 index 0000000..19a0415 --- /dev/null +++ b/doc/en/ref_algorithm_4DVAR.rst @@ -0,0 +1,263 @@ +.. + Copyright (C) 2008-2015 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. index:: single: 4DVAR +.. _section_ref_algorithm_4DVAR: + +Calculation algorithm "*4DVAR*" +------------------------------- + +.. warning:: + + in its present version, this algorithm is experimental, and so changes can be + required in forthcoming versions. + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system, by a +variational minimization method of the classical :math:`J` function in data +assimilation: + +.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\sum_{t\in T}(\mathbf{y^o}(t)-H(\mathbf{x},t))^T.\mathbf{R}^{-1}.(\mathbf{y^o}(t)-H(\mathbf{x},t)) + +which is usually designed as the "*4D-VAR*" function (see for example +[Talagrand97]_). It is well suited in cases of non-linear observation and +evolution operators, its application domain is similar to the one of Kalman +filters, specially the :ref:`section_ref_algorithm_ExtendedKalmanFilter` or the +:ref:`section_ref_algorithm_UnscentedKalmanFilter`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: AlgorithmParameters +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Bounds +.. index:: single: ConstrainedBy +.. index:: single: EstimationOf +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreSupplementaryCalculations + +The general required commands, available in the editing user interface, are the +following: + + Background + *Required command*. This indicates the background or initial vector used, + previously noted as :math:`\mathbf{x}^b`. Its value is defined as a + "*Vector*" or a *VectorSerie*" type object. + + BackgroundError + *Required command*. This indicates the background error covariance matrix, + previously noted as :math:`\mathbf{B}`. Its value is defined as a "*Matrix*" + type object, a "*ScalarSparseMatrix*" type object, or a + "*DiagonalSparseMatrix*" type object. + + Observation + *Required command*. This indicates the observation vector used for data + assimilation or optimization, previously noted as :math:`\mathbf{y}^o`. It + is defined as a "*Vector*" or a *VectorSerie* type object. + + ObservationError + *Required command*. This indicates the observation error covariance matrix, + previously noted as :math:`\mathbf{R}`. It is defined as a "*Matrix*" type + object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*" + type object. + + ObservationOperator + *Required command*. This indicates the observation operator, previously + noted :math:`H`, which transforms the input parameters :math:`\mathbf{x}` to + results :math:`\mathbf{y}` to be compared to observations + :math:`\mathbf{y}^o`. Its value is defined as a "*Function*" type object or + a "*Matrix*" type one. In the case of "*Function*" type, different + functional forms can be used, as described in the section + :ref:`section_ref_operator_requirements`. If there is some control :math:`U` + included in the observation, the operator has to be applied to a pair + :math:`(X,U)`. + +The general optional commands, available in the editing user interface, are +indicated in :ref:`section_ref_assimilation_keywords`. Moreover, the parameters +of the command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_Algorithm_Parameters` for the good use of this +command. + +The options of the algorithm are the following: + + Minimizer + This key allows to choose the optimization minimizer. The default choice is + "LBFGSB", and the possible ones are "LBFGSB" (nonlinear constrained + minimizer, see [Byrd95]_, [Morales11]_ and [Zhu97]_), "TNC" (nonlinear + constrained minimizer), "CG" (nonlinear unconstrained minimizer), "BFGS" + (nonlinear unconstrained minimizer), "NCG" (Newton CG minimizer). It is + strongly recommended to stay with the default. + + Example : ``{"Minimizer":"LBFGSB"}`` + + Bounds + This key allows to define upper and lower bounds for every state variable + being optimized. Bounds have to be given by a list of list of pairs of + lower/upper bounds for each variable, with possibly ``None`` every time + there is no bound. The bounds can always be specified, but they are taken + into account only by the constrained optimizers. + + Example : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,None],[None,None]]}`` + + ConstrainedBy + This key allows to choose the method to take into account the bounds + constraints. The only one available is the "EstimateProjection", which + projects the current state estimate on the bounds constraints. + + Example : ``{"ConstrainedBy":"EstimateProjection"}`` + + MaximumNumberOfSteps + This key indicates the maximum number of iterations allowed for iterative + optimization. The default is 15000, which is very similar to no 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. + + Example : ``{"MaximumNumberOfSteps":100}`` + + CostDecrementTolerance + 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. + + Example : ``{"CostDecrementTolerance":1.e-7}`` + + EstimationOf + This key allows to choose the type of estimation to be performed. It can be + either state-estimation, with a value of "State", or parameter-estimation, + with a value of "Parameters". The default choice is "State". + + ProjectedGradientTolerance + This key indicates a limit value, leading to stop successfully the iterative + optimization process when all the components of the projected gradient are + under this limit. It is only used for constrained optimizers. The default is + -1, that is the internal default of each minimizer (generally 1.e-5), and it + is not recommended to change it. + + Example : ``{"ProjectedGradientTolerance":-1}`` + + GradientNormTolerance + This key indicates a limit value, leading to stop successfully the + iterative optimization process when the norm of the gradient is under this + limit. It is only used for non-constrained optimizers. The default is + 1.e-5 and it is not recommended to change it. + + Example : ``{"GradientNormTolerance":1.e-5}`` + + StoreSupplementaryCalculations + This list indicates the names of the supplementary variables that can be + available at the end of the algorithm. It involves potentially costly + calculations or memory consumptions. The default is a void list, none of + these variables being calculated and stored by default. The possible names + are in the following list: ["BMA", "CostFunctionJ", "CurrentOptimum", + "CurrentState", "IndexOfOptimum"]. + + Example : ``{"StoreSupplementaryCalculations":["BMA", "CurrentState"]}`` + +Information and variables available at the end of the algorithm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +At the output, after executing the algorithm, there are variables and +information originating from the calculation. The description of +:ref:`section_ref_output_variables` show the way to obtain them by the method +named ``get`` of the variable "*ADD*" of the post-processing. The input +variables, available to the user at the output in order to facilitate the +writing of post-processing procedures, are described in the +:ref:`subsection_r_o_v_Inventaire`. + +The unconditional outputs of the algorithm are the following: + + Analysis + *List of vectors*. Each element is an optimal state :math:`\mathbf{x}*` in + optimization or an analysis :math:`\mathbf{x}^a` in data assimilation. + + Example : ``Xa = ADD.get("Analysis")[-1]`` + + CostFunctionJ + *List of values*. Each element is a value of the error function :math:`J`. + + Example : ``J = ADD.get("CostFunctionJ")[:]`` + + CostFunctionJb + *List of values*. Each element is a value of the error function :math:`J^b`, + that is of the background difference part. + + Example : ``Jb = ADD.get("CostFunctionJb")[:]`` + + CostFunctionJo + *List of values*. Each element is a value of the error function :math:`J^o`, + that is of the observation difference part. + + Example : ``Jo = ADD.get("CostFunctionJo")[:]`` + +The conditional outputs of the algorithm are the following: + + BMA + *List of vectors*. Each element is a vector of difference between the + background and the optimal state. + + Example : ``bma = ADD.get("BMA")[-1]`` + + CurrentOptimum + *List of vectors*. Each element is the optimal state obtained at the current + step of the optimization algorithm. It is not necessarely the last state. + + Exemple : ``Xo = ADD.get("CurrentOptimum")[:]`` + + CurrentState + *List of vectors*. Each element is a usual state vector used during the + optimization algorithm procedure. + + Example : ``Xs = ADD.get("CurrentState")[:]`` + + IndexOfOptimum + *List of integers*. Each element is the iteration index of the optimum + obtained at the current step the optimization algorithm. It is not + necessarely the number of the last iteration. + + Exemple : ``i = ADD.get("IndexOfOptimum")[-1]`` + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + +Bibliographical references: + - [Byrd95]_ + - [Morales11]_ + - [Talagrand97]_ diff --git a/doc/en/ref_algorithm_ExtendedKalmanFilter.rst b/doc/en/ref_algorithm_ExtendedKalmanFilter.rst index 9619316..6ff9fe9 100644 --- a/doc/en/ref_algorithm_ExtendedKalmanFilter.rst +++ b/doc/en/ref_algorithm_ExtendedKalmanFilter.rst @@ -100,6 +100,13 @@ The options of the algorithm are the following: Example : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,1.e99],[-1.e99,1.e99]]}`` + ConstrainedBy + This key allows to choose the method to take into account the bounds + constraints. The only one available is the "EstimateProjection", which + projects the current state estimate on the bounds constraints. + + Example : ``{"ConstrainedBy":"EstimateProjection"}`` + EstimationOf This key allows to choose the type of estimation to be performed. It can be either state-estimation, with a value of "State", or parameter-estimation, diff --git a/doc/en/ref_algorithm_QuantileRegression.rst b/doc/en/ref_algorithm_QuantileRegression.rst index 06f777a..89b6a0f 100644 --- a/doc/en/ref_algorithm_QuantileRegression.rst +++ b/doc/en/ref_algorithm_QuantileRegression.rst @@ -46,6 +46,7 @@ Optional and required commands .. index:: single: Minimizer .. index:: single: MaximumNumberOfSteps .. index:: single: CostDecrementTolerance +.. index:: single: Bounds .. index:: single: StoreSupplementaryCalculations The general required commands, available in the editing user interface, are the @@ -103,6 +104,15 @@ The options of the algorithm are the following: Example : ``{"CostDecrementTolerance":1.e-7}`` + Bounds + This key allows to define upper and lower bounds for every state variable + being optimized. Bounds have to be given by a list of list of pairs of + lower/upper bounds for each variable, with possibly ``None`` every time + there is no bound. The bounds can always be specified, but they are taken + into account only by the constrained optimizers. + + Example : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,None],[None,None]]}`` + StoreSupplementaryCalculations This list indicates the names of the supplementary variables that can be available at the end of the algorithm. It involves potentially costly diff --git a/doc/en/ref_algorithm_UnscentedKalmanFilter.rst b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst index 9512bdb..2beb47c 100644 --- a/doc/en/ref_algorithm_UnscentedKalmanFilter.rst +++ b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst @@ -106,6 +106,13 @@ The options of the algorithm are the following: Example : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,1.e99],[-1.e99,1.e99]]}`` + ConstrainedBy + This key allows to choose the method to take into account the bounds + constraints. The only one available is the "EstimateProjection", which + projects the current state estimate on the bounds constraints. + + Example : ``{"ConstrainedBy":"EstimateProjection"}`` + EstimationOf This key allows to choose the type of estimation to be performed. It can be either state-estimation, with a value of "State", or parameter-estimation, diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 079f26e..c3daa50 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -95,6 +95,7 @@ The mathematical notations used afterward are explained in the section ref_assimilation_keywords ref_algorithm_3DVAR + ref_algorithm_4DVAR ref_algorithm_Blue ref_algorithm_EnsembleBlue ref_algorithm_ExtendedBlue diff --git a/doc/en/tui.rst b/doc/en/tui.rst index d10371e..578d667 100644 --- a/doc/en/tui.rst +++ b/doc/en/tui.rst @@ -30,6 +30,11 @@ **[DocR]** Textual Application Programming Interface for the user (API/TUI) ================================================================================ +.. warning:: + + in its present version, this text programming interface (TUI) is experimental, + and so changes can be required in forthcoming versions. + This section presents advanced usage of the ADAO module using its text programming interface (API/TUI). This interface gives ability to create a calculation object in a similar way than the case building obtained through the diff --git a/doc/fr/ref_algorithm_3DVAR.rst b/doc/fr/ref_algorithm_3DVAR.rst index 6fc8671..aad3412 100644 --- a/doc/fr/ref_algorithm_3DVAR.rst +++ b/doc/fr/ref_algorithm_3DVAR.rst @@ -99,8 +99,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_4DVAR.rst b/doc/fr/ref_algorithm_4DVAR.rst new file mode 100644 index 0000000..325286c --- /dev/null +++ b/doc/fr/ref_algorithm_4DVAR.rst @@ -0,0 +1,273 @@ +.. + Copyright (C) 2008-2015 EDF R&D + + This file is part of SALOME ADAO module. + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com + + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D + +.. index:: single: 4DVAR +.. _section_ref_algorithm_4DVAR: + +Algorithme de calcul "*4DVAR*" +------------------------------ + +.. warning:: + + dans sa présente version, cet algorithme est expérimental, et reste donc + susceptible de changements dans les prochaines versions. + +Description ++++++++++++ + +Cet algorithme réalise une estimation de l'état d'un système dynamique, par une +méthode de minimisation variationnelle de la fonctionnelle :math:`J` d'écart +classique en assimilation de données : + +.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+\sum_{t\in T}(\mathbf{y^o}(t)-H(\mathbf{x},t))^T.\mathbf{R}^{-1}.(\mathbf{y^o}(t)-H(\mathbf{x},t)) + +qui est usuellement désignée comme la fonctionnelle "*4D-VAR*" (voir par exemple +[Talagrand97]_). Il est bien adapté aux cas d'opérateurs d'observation et +d'évolution non-linéaires, son domaine d'application est comparable aux +algorithmes de filtrage de Kalman et en particulier +l':ref:`section_ref_algorithm_ExtendedKalmanFilter` ou +l':ref:`section_ref_algorithm_UnscentedKalmanFilter`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: AlgorithmParameters +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Bounds +.. index:: single: ConstrainedBy +.. index:: single: EstimationOf +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreSupplementaryCalculations + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + Background + *Commande obligatoire*. Elle définit le vecteur d'ébauche ou + d'initialisation, noté précédemment :math:`\mathbf{x}^b`. Sa valeur est + définie comme un objet de type "*Vector*" ou de type "*VectorSerie*". + + BackgroundError + *Commande obligatoire*. Elle définit la matrice de covariance des erreurs + d'ébauche, notée précédemment :math:`\mathbf{B}`. Sa valeur est définie + comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de + type "*DiagonalSparseMatrix*". + + Observation + *Commande obligatoire*. Elle définit le vecteur d'observation utilisé en + assimilation de données ou en optimisation, et noté précédemment + :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type "*Vector*" + ou de type "*VectorSerie*". + + ObservationError + *Commande obligatoire*. Elle définit la matrice de covariance des erreurs + d'ébauche, notée précédemment :math:`\mathbf{R}`. Sa valeur est définie + comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de + type "*DiagonalSparseMatrix*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, noté + précédemment :math:`H`, qui transforme les paramètres d'entrée + :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux + observations :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de + type "*Function*" ou de type "*Matrix*". Dans le cas du type "*Function*", + différentes formes fonctionnelles peuvent être utilisées, comme décrit dans + la section :ref:`section_ref_operator_requirements`. Si un contrôle + :math:`U` est inclus dans le modèle d'observation, l'opérateur doit être + appliqué à une paire :math:`(X,U)`. + +Les commandes optionnelles générales, disponibles dans l'interface en édition, +sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + Minimizer + Cette clé permet de changer le minimiseur pour l'optimiseur. Le choix par + défaut est "LBFGSB", et les choix possibles sont "LBFGSB" (minimisation non + linéaire sous contraintes, voir [Byrd95]_, [Morales11]_ et [Zhu97]_), "TNC" + (minimisation non linéaire sous contraintes), "CG" (minimisation non + linéaire sans contraintes), "BFGS" (minimisation non linéaire sans + contraintes), "NCG" (minimisation de type gradient conjugué de Newton). Il + est fortement conseillé de conserver la valeur par défaut. + + Exemple : ``{"Minimizer":"LBFGSB"}`` + + Bounds + Cette clé permet de définir des bornes supérieure et inférieure pour chaque + variable d'état optimisée. Les bornes doivent être données par une liste de + liste de paires de bornes inférieure/supérieure pour chaque variable, avec + une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les bornes peuvent + toujours être spécifiées, mais seuls les optimiseurs sous contraintes les + prennent en compte. + + Exemple : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,None],[None,None]]}`` + + ConstrainedBy + Cette clé permet d'indiquer la méthode de prise en compte des contraintes de + bornes. La seule disponible est "EstimateProjection", qui projete + l'estimation de l'état courant sur les contraintes de bornes. + + Exemple : ``{"ConstrainedBy":"EstimateProjection"}`` + + MaximumNumberOfSteps + Cette clé indique le nombre maximum d'itérations possibles en optimisation + itérative. Le défaut est 15000, qui est très similaire à une 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. + + Exemple : ``{"MaximumNumberOfSteps":100}`` + + CostDecrementTolerance + 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. + + Exemple : ``{"CostDecrementTolerance":1.e-7}`` + + EstimationOf + Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être + soit une estimation de l'état, avec la valeur "State", ou une estimation de + paramètres, avec la valeur "Parameters". Le choix par défaut est "State". + + Exemple : ``{"EstimationOf":"Parameters"}`` + + ProjectedGradientTolerance + Cette clé indique une valeur limite, conduisant à arrêter le processus + itératif d'optimisation lorsque toutes les composantes du gradient projeté + sont en-dessous de cette limite. C'est utilisé uniquement par les + optimiseurs sous contraintes. Le défaut est -1, qui désigne le défaut + interne de chaque optimiseur (usuellement 1.e-5), et il n'est pas recommandé + de le changer. + + Exemple : ``{"ProjectedGradientTolerance":-1}`` + + GradientNormTolerance + Cette clé indique une valeur limite, conduisant à arrêter le processus + itératif d'optimisation lorsque la norme du gradient est en dessous de cette + limite. C'est utilisé uniquement par les optimiseurs sans contraintes. Le + défaut est 1.e-5 et il n'est pas recommandé de le changer. + + Exemple : ``{"GradientNormTolerance":1.e-5}`` + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs ou du stockage coûteux. La valeur par défaut est une liste vide, + aucune de ces variables n'étant calculée et stockée par défaut. Les noms + possibles sont dans la liste suivante : ["BMA", "CostFunctionJ", + "CurrentOptimum", "CurrentState", "IndexOfOptimum"]. + + Exemple : ``{"StoreSupplementaryCalculations":["BMA", "CurrentState"]}`` + +Informations et variables disponibles à la fin de l'algorithme +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +En sortie, après exécution de l'algorithme, on dispose d'informations et de +variables issues du calcul. La description des +:ref:`section_ref_output_variables` indique la manière de les obtenir par la +méthode nommée ``get`` de la variable "*ADD*" du post-processing. Les variables +d'entrée, mises à disposition de l'utilisateur en sortie pour faciliter +l'écriture des procédures de post-processing, sont décrites dans +l':ref:`subsection_r_o_v_Inventaire`. + +Les sorties non conditionnelles de l'algorithme sont les suivantes: + + Analysis + *Liste de vecteurs*. Chaque élément est un état optimal :math:`\mathbf{x}*` + en optimisation ou une analyse :math:`\mathbf{x}^a` en assimilation de + données. + + Exemple : ``Xa = ADD.get("Analysis")[-1]`` + + CostFunctionJ + *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart + :math:`J`. + + Exemple : ``J = ADD.get("CostFunctionJ")[:]`` + + CostFunctionJb + *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart + :math:`J^b`, c'est-à-dire de la partie écart à l'ébauche. + + Exemple : ``Jb = ADD.get("CostFunctionJb")[:]`` + + CostFunctionJo + *Liste de valeurs*. Chaque élément est une valeur de fonctionnelle d'écart + :math:`J^o`, c'est-à-dire de la partie écart à l'observation. + + Exemple : ``Jo = ADD.get("CostFunctionJo")[:]`` + +Les sorties conditionnelles de l'algorithme sont les suivantes: + + BMA + *Liste de vecteurs*. Chaque élément est un vecteur d'écart entre + l'ébauche et l'état optimal. + + Exemple : ``bma = ADD.get("BMA")[-1]`` + + CurrentOptimum + *Liste de vecteurs*. Chaque élément est le vecteur d'état optimal au pas de + temps courant au cours du déroulement de l'algorithme d'optimisation. Ce + n'est pas nécessairement le dernier état. + + Exemple : ``Xo = ADD.get("CurrentOptimum")[:]`` + + CurrentState + *Liste de vecteurs*. Chaque élément est un vecteur d'état courant utilisé + au cours du déroulement de l'algorithme d'optimisation. + + Exemple : ``Xs = ADD.get("CurrentState")[:]`` + + IndexOfOptimum + *Liste d'entiers*. Chaque élément est l'index d'itération de l'optimum + obtenu au cours du déroulement de l'algorithme d'optimisation. Ce n'est pas + nécessairement le numéro de la dernière itération. + + Exemple : ``i = ADD.get("IndexOfOptimum")[-1]`` + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + +Références bibliographiques : + - [Byrd95]_ + - [Morales11]_ + - [Talagrand97]_ diff --git a/doc/fr/ref_algorithm_AdjointTest.rst b/doc/fr/ref_algorithm_AdjointTest.rst index a8b0acf..118e1ae 100644 --- a/doc/fr/ref_algorithm_AdjointTest.rst +++ b/doc/fr/ref_algorithm_AdjointTest.rst @@ -76,8 +76,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_Blue.rst b/doc/fr/ref_algorithm_Blue.rst index f862141..2d78e8c 100644 --- a/doc/fr/ref_algorithm_Blue.rst +++ b/doc/fr/ref_algorithm_Blue.rst @@ -98,8 +98,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_EnsembleBlue.rst b/doc/fr/ref_algorithm_EnsembleBlue.rst index 04b7c02..1f75fef 100644 --- a/doc/fr/ref_algorithm_EnsembleBlue.rst +++ b/doc/fr/ref_algorithm_EnsembleBlue.rst @@ -90,8 +90,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_ExtendedBlue.rst b/doc/fr/ref_algorithm_ExtendedBlue.rst index ffbe23e..bba2e3d 100644 --- a/doc/fr/ref_algorithm_ExtendedBlue.rst +++ b/doc/fr/ref_algorithm_ExtendedBlue.rst @@ -95,8 +95,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst index 4cc49b3..316285a 100644 --- a/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst +++ b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst @@ -31,8 +31,8 @@ Description +++++++++++ Cet algorithme réalise une estimation de l'état d'un système dynamique par un -filtre de Kalman étendu, utilisant un calcul non linéaire de l'état et de l'évolution -incrémentale (processus). +filtre de Kalman étendu, utilisant un calcul non linéaire de l'état et de +l'évolution incrémentale (processus). Commandes requises et optionnelles ++++++++++++++++++++++++++++++++++ @@ -87,8 +87,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. @@ -103,6 +103,13 @@ Les options de l'algorithme sont les suivantes: Exemple : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,1.e99],[-1.e99,1.e99]]}`` + ConstrainedBy + Cette clé permet d'indiquer la méthode de prise en compte des contraintes de + bornes. La seule disponible est "EstimateProjection", qui projete + l'estimation de l'état courant sur les contraintes de bornes. + + Exemple : ``{"ConstrainedBy":"EstimateProjection"}`` + EstimationOf Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être soit une estimation de l'état, avec la valeur "State", ou une estimation de diff --git a/doc/fr/ref_algorithm_FunctionTest.rst b/doc/fr/ref_algorithm_FunctionTest.rst index 9a0abc4..ac11448 100644 --- a/doc/fr/ref_algorithm_FunctionTest.rst +++ b/doc/fr/ref_algorithm_FunctionTest.rst @@ -74,8 +74,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_GradientTest.rst b/doc/fr/ref_algorithm_GradientTest.rst index ee8bbb0..83ae79c 100644 --- a/doc/fr/ref_algorithm_GradientTest.rst +++ b/doc/fr/ref_algorithm_GradientTest.rst @@ -119,8 +119,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_KalmanFilter.rst b/doc/fr/ref_algorithm_KalmanFilter.rst index ef4872c..d1c1d40 100644 --- a/doc/fr/ref_algorithm_KalmanFilter.rst +++ b/doc/fr/ref_algorithm_KalmanFilter.rst @@ -34,9 +34,9 @@ Cet algorithme r filtre de Kalman. Il est théoriquement réservé aux cas d'opérateurs d'observation et d'évolution -incrémentale (processus) linéaires, même s'il fonctionne parfois dans les cas "faiblement" -non-linéaire. On peut vérifier la linéarité de l'opérateur d'observation à -l'aide de l':ref:`section_ref_algorithm_LinearityTest`. +incrémentale (processus) linéaires, même s'il fonctionne parfois dans les cas +"faiblement" non-linéaire. On peut vérifier la linéarité de l'opérateur +d'observation à l'aide de l':ref:`section_ref_algorithm_LinearityTest`. En cas de non-linéarité, même peu marquée, on lui préférera l':ref:`section_ref_algorithm_ExtendedKalmanFilter` ou @@ -93,8 +93,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_LinearLeastSquares.rst b/doc/fr/ref_algorithm_LinearLeastSquares.rst index 1b754ed..f6a389f 100644 --- a/doc/fr/ref_algorithm_LinearLeastSquares.rst +++ b/doc/fr/ref_algorithm_LinearLeastSquares.rst @@ -82,8 +82,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_LinearityTest.rst b/doc/fr/ref_algorithm_LinearityTest.rst index 3a9cb4b..f9d0077 100644 --- a/doc/fr/ref_algorithm_LinearityTest.rst +++ b/doc/fr/ref_algorithm_LinearityTest.rst @@ -142,8 +142,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst index 5f4e708..e15e3c6 100644 --- a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst +++ b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst @@ -92,8 +92,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst index 4a841d6..fea8960 100644 --- a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst +++ b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst @@ -96,8 +96,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_QuantileRegression.rst b/doc/fr/ref_algorithm_QuantileRegression.rst index 6ae741a..a705fa1 100644 --- a/doc/fr/ref_algorithm_QuantileRegression.rst +++ b/doc/fr/ref_algorithm_QuantileRegression.rst @@ -46,6 +46,7 @@ Commandes requises et optionnelles .. index:: single: Minimizer .. index:: single: MaximumNumberOfSteps .. index:: single: CostDecrementTolerance +.. index:: single: Bounds .. index:: single: StoreSupplementaryCalculations Les commandes requises générales, disponibles dans l'interface en édition, sont @@ -75,8 +76,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. @@ -104,6 +105,16 @@ Les options de l'algorithme sont les suivantes: Exemple : ``{"CostDecrementTolerance":1.e-7}`` + Bounds + Cette clé permet de définir des bornes supérieure et inférieure pour chaque + variable d'état optimisée. Les bornes doivent être données par une liste de + liste de paires de bornes inférieure/supérieure pour chaque variable, avec + une valeur ``None`` chaque fois qu'il n'y a pas de borne. Les bornes peuvent + toujours être spécifiées, mais seuls les optimiseurs sous contraintes les + prennent en compte. + + Exemple : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,None],[None,None]]}`` + StoreSupplementaryCalculations Cette liste indique les noms des variables supplémentaires qui peuvent être disponibles à la fin de l'algorithme. Cela implique potentiellement des diff --git a/doc/fr/ref_algorithm_SamplingTest.rst b/doc/fr/ref_algorithm_SamplingTest.rst index 04c1dec..0ae57f9 100644 --- a/doc/fr/ref_algorithm_SamplingTest.rst +++ b/doc/fr/ref_algorithm_SamplingTest.rst @@ -112,8 +112,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_TangentTest.rst b/doc/fr/ref_algorithm_TangentTest.rst index 2058572..fd36480 100644 --- a/doc/fr/ref_algorithm_TangentTest.rst +++ b/doc/fr/ref_algorithm_TangentTest.rst @@ -86,8 +86,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. diff --git a/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst index 87b5b1a..d639211 100644 --- a/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst +++ b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst @@ -92,8 +92,8 @@ les suivantes: Les commandes optionnelles générales, disponibles dans l'interface en édition, sont indiquées dans la :ref:`section_ref_assimilation_keywords`. De plus, les -paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options -particulières, décrites ci-après, de l'algorithme. On se reportera à la +paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les +options particulières, décrites ci-après, de l'algorithme. On se reportera à la :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette commande. @@ -108,6 +108,13 @@ Les options de l'algorithme sont les suivantes: Exemple : ``{"Bounds":[[2.,5.],[1.e-2,10.],[-30.,1.e99],[-1.e99,1.e99]]}`` + ConstrainedBy + Cette clé permet d'indiquer la méthode de prise en compte des contraintes de + bornes. La seule disponible est "EstimateProjection", qui projete + l'estimation de l'état courant sur les contraintes de bornes. + + Exemple : ``{"ConstrainedBy":"EstimateProjection"}`` + EstimationOf Cette clé permet de choisir le type d'estimation à réaliser. Cela peut être soit une estimation de l'état, avec la valeur "State", ou une estimation de diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index 774e0c5..8ac5bff 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -97,6 +97,7 @@ ADAO. Les notations math ref_assimilation_keywords ref_algorithm_3DVAR + ref_algorithm_4DVAR ref_algorithm_Blue ref_algorithm_EnsembleBlue ref_algorithm_ExtendedBlue diff --git a/doc/fr/tui.rst b/doc/fr/tui.rst index 5928c60..a549430 100644 --- a/doc/fr/tui.rst +++ b/doc/fr/tui.rst @@ -30,6 +30,12 @@ **[DocR]** Interface de programmation textuelle pour l'utilisateur (API/TUI) ================================================================================ +.. warning:: + + dans sa présente version, cette interface de programmation textuelle (TUI) est + expérimentale, et reste donc susceptible de changements dans les prochaines + versions. + Cette section présente des méthodes avancées d'usage du module ADAO à l'aide de son interface de programmation textuelle (API/TUI). Cette interface permet de créer un objet de calcul de manière similaire à la construction d'un cas par -- 2.39.2