--- /dev/null
+..
+ 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]_
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,
.. 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
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
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,
ref_assimilation_keywords
ref_algorithm_3DVAR
+ ref_algorithm_4DVAR
ref_algorithm_Blue
ref_algorithm_EnsembleBlue
ref_algorithm_ExtendedBlue
**[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
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.
--- /dev/null
+..
+ 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]_
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.
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.
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.
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.
+++++++++++
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
++++++++++++++++++++++++++++++++++
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.
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
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.
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.
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
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.
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.
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.
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.
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.
.. 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
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.
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
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.
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.
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.
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
ref_assimilation_keywords
ref_algorithm_3DVAR
+ ref_algorithm_4DVAR
ref_algorithm_Blue
ref_algorithm_EnsembleBlue
ref_algorithm_ExtendedBlue
**[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
