From: Jean-Philippe ARGAUD Date: Wed, 9 Jul 2014 20:04:33 +0000 (+0200) Subject: Rewriting and completing reference documentation ([DocR] X-Git-Tag: V7_5_0rc1~16 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=79a0414cc78b6a9503750d4f69a1015e5ab575d2;p=modules%2Fadao.git Rewriting and completing reference documentation ([DocR] --- diff --git a/doc/en/advanced.rst b/doc/en/advanced.rst index d5c67c2..a7af236 100644 --- a/doc/en/advanced.rst +++ b/doc/en/advanced.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_advanced: ================================================================================ -Advanced usage of the ADAO module +**[DocU]** Advanced usage of the ADAO module ================================================================================ This section presents advanced methods to use the ADAO module, how to get more diff --git a/doc/en/bibliography.rst b/doc/en/bibliography.rst index c50be48..785d556 100644 --- a/doc/en/bibliography.rst +++ b/doc/en/bibliography.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_bibliography: ================================================================================ @@ -10,13 +33,21 @@ Bibliography .. [Bocquet04] Bocquet M., *Introduction aux principes et méthodes de l'assimilation de données en géophysique*, Lecture Notes, 2004-2008, http://cerea.enpc.fr/HomePages/bocquet/assim.pdf +.. [Buchinsky98] Buchinsky M., *Recent Advances in Quantile Regression Models: A Practical Guidline for Empirical Research*, Journal of Human Resources, 33(1), pp.88-126, 1998 + .. [Byrd95] Byrd R. H., Lu P., Nocedal J., *A Limited Memory Algorithm for Bound Constrained Optimization*, SIAM Journal on Scientific and Statistical Computing, 16(5), pp.1190-1208, 1995 +.. [Cade03] Cade B. S., Noon B. R., *A Gentle Introduction to Quantile Regression for Ecologists*, Frontiers in Ecology and the Environment, 1(8), pp.412-420, 2003 + .. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997 .. [Kalnay03] Kalnay E., *Atmospheric Modeling, Data Assimilation and Predictability*, Cambridge University Press, 2003 -.. [Morales11] Morales J.L., Nocedal J., *L-BFGS-B: Remark on Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, Vol 38(1), 2011 +.. [Koenker00] Koenker R., Hallock K. F., *Quantile Regression: an Introduction*, 2000, available at http://www.econ.uiuc.edu/~roger/research/intro/intro.html + +.. [Koenker01] Koenker R., Hallock K. F., *Quantile Regression*, Journal of Economic Perspectives, 15(4), pp.143-156, 2001 + +.. [Morales11] Morales J.L., Nocedal J., *L-BFGS-B: Remark on Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 38(1), 2011 .. [Salome] *SALOME The Open Source Integration Platform for Numerical Simulation*, http://www.salome-platform.org/ @@ -34,4 +65,6 @@ Bibliography .. [WikipediaQR] Wikipedia, *Quantile regression*, https://en.wikipedia.org/wiki/Quantile_regression -.. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, Vol 23(4), pp.550-560, 1997 +.. [WikipediaUKF] Wikipedia, *Unscented Kalman filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter + +.. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997 diff --git a/doc/en/conf.py b/doc/en/conf.py index c3dfd6f..4c516de 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -77,7 +77,7 @@ release = '%s'%module_version.version.replace('_','\_') # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/doc/en/examples.rst b/doc/en/examples.rst index f1d63b7..f962a90 100644 --- a/doc/en/examples.rst +++ b/doc/en/examples.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_examples: ================================================================================ -Tutorials on using the ADAO module +**[DocU]** Tutorials on using the ADAO module ================================================================================ .. |eficas_new| image:: images/eficas_new.png diff --git a/doc/en/glossary.rst b/doc/en/glossary.rst index adb2388..9de73bf 100644 --- a/doc/en/glossary.rst +++ b/doc/en/glossary.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_glossary: Glossary diff --git a/doc/en/index.rst b/doc/en/index.rst index 14c47ec..5bafebc 100644 --- a/doc/en/index.rst +++ b/doc/en/index.rst @@ -1,3 +1,28 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_home: + ================================================================================ ADAO documentation ================================================================================ @@ -46,8 +71,8 @@ Table of contents theory using examples - reference advanced + reference license glossary bibliography diff --git a/doc/en/intro.rst b/doc/en/intro.rst index f6d7c18..b4542fe 100644 --- a/doc/en/intro.rst +++ b/doc/en/intro.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_intro: ================================================================================ diff --git a/doc/en/license.rst b/doc/en/license.rst index a8d8bbb..c95f64c 100644 --- a/doc/en/license.rst +++ b/doc/en/license.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_license: ================================================================================ @@ -38,6 +61,9 @@ references given below: * *ADAO, a SALOME module for Data Assimilation and Optimization*, http://www.salome-platform.org/ + * *ADAO, un module SALOME pour l'Assimilation de Donnees et l'Aide a + l'Optimisation*, http://www.salome-platform.org/ + * *SALOME The Open Source Integration Platform for Numerical Simulation*, http://www.salome-platform.org/ diff --git a/doc/en/ref_algorithm_3DVAR.rst b/doc/en/ref_algorithm_3DVAR.rst new file mode 100644 index 0000000..cb20894 --- /dev/null +++ b/doc/en/ref_algorithm_3DVAR.rst @@ -0,0 +1,169 @@ +.. + Copyright (C) 2008-2014 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: 3DVAR +.. _section_ref_algorithm_3DVAR: + +Calculation algorithm "*3DVAR*" +------------------------------- + +Description ++++++++++++ + +This algorithm performs a state estimation by variational minimization of the +classical :math:`J` function in static data assimilation: + +.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) + +which is usually designed as the "*3D-VAR*" function (see for example +[Talagrand97]_). + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Minimizer +.. index:: single: Bounds +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` 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. + + 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. + + 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. + + 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. + + 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. + + 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. + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", + "SigmaObs2", "MahalanobisConsistency"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_LinearityTest` + +Bibliographical references: + - [Byrd95]_ + - [Morales11]_ + - [Talagrand97]_ diff --git a/doc/en/ref_algorithm_AdjointTest.rst b/doc/en/ref_algorithm_AdjointTest.rst new file mode 100644 index 0000000..dfdb9b0 --- /dev/null +++ b/doc/en/ref_algorithm_AdjointTest.rst @@ -0,0 +1,114 @@ +.. + Copyright (C) 2008-2014 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: AdjointTest +.. _section_ref_algorithm_AdjointTest: + +Checking algorithm "*AdjointTest*" +---------------------------------- + +Description ++++++++++++ + +This algorithm allows to check the quality of the adjoint operator, by +calculating a residue with known theoretical properties. + +One can observe the following residue, which is the difference of two scalar +products: + +.. math:: R(\alpha) = | < TangentF_x(\mathbf{dx}) , \mathbf{y} > - < \mathbf{dx} , AdjointF_x(\mathbf{y}) > | + +that has to remain equal to zero at the calculation precision. One take +:math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code. +:math:`\mathbf{y}` has to be in the image of :math:`F`. If it is not given, one +take :math:`\mathbf{y} = F(\mathbf{x})`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: SetSeed + +The general required commands, available in the editing user interface, are the +following: + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + AmplitudeOfInitialDirection + This key indicates the scaling of the initial perturbation build as a vector + used for the directional derivative around the nominal checking point. The + default is 1, that means no scaling. + + EpsilonMinimumExponent + This key indicates the minimal exponent value of the power of 10 coefficient + to be used to decrease the increment multiplier. The default is -8, and it + has to be between 0 and -20. For example, its default value leads to + calculate the residue of the formula with a fixed increment multiplied from + 1.e0 to 1.e-8. + + InitialDirection + This key indicates the vector direction used for the directional derivative + around the nominal checking point. It has to be a vector. If not specified, + this direction defaults to a random perturbation around zero of the same + vector size than the checking point. + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_TangentTest` + - :ref:`section_ref_algorithm_GradientTest` diff --git a/doc/en/ref_algorithm_Blue.rst b/doc/en/ref_algorithm_Blue.rst new file mode 100644 index 0000000..231238d --- /dev/null +++ b/doc/en/ref_algorithm_Blue.rst @@ -0,0 +1,124 @@ +.. + Copyright (C) 2008-2014 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: Blue +.. _section_ref_algorithm_Blue: + +Calculation algorithm "*Blue*" +------------------------------ + +Description ++++++++++++ + +This algorithm realizes a BLUE (Best Linear Unbiased Estimator) type estimation +of the state of a system. More precisely, it is an Aitken estimator. + +This algorithm is always the fastest of all the assimilation algorithms of ADAO. +It is theoretically reserved for observation operator cases which are linear, +even if it sometimes works in "slightly" non-linear cases. One can verify the +linearity of the observation operator with the help of the +:ref:`section_ref_algorithm_LinearityTest`. + +In case of non-linearity, even slightly marked, it will be easily prefered the +:ref:`section_ref_algorithm_ExtendedBlue` or the +:ref:`section_ref_algorithm_3DVAR`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", + "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` + +Bibliographical references: + - [Bouttier99]_ diff --git a/doc/en/ref_algorithm_EnsembleBlue.rst b/doc/en/ref_algorithm_EnsembleBlue.rst new file mode 100644 index 0000000..2ee3a74 --- /dev/null +++ b/doc/en/ref_algorithm_EnsembleBlue.rst @@ -0,0 +1,107 @@ +.. + Copyright (C) 2008-2014 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: EnsembleBlue +.. _section_ref_algorithm_EnsembleBlue: + +Calculation algorithm "*EnsembleBlue*" +-------------------------------------- + +Description ++++++++++++ + +This algorithm realizes a BLUE (Best Linear Unbiased Estimator, which is here an +Aitken estimator) type estimation of the state of a system by an ensemble +method. To work, one must give a set of backgrounds, their number determining +the size of the ensemble for the estimation. + +It is theoretically reserved for observation operator cases which are linear, +but has to work also in "slightly" non-linear cases. One can verify the +linearity of the observation operator with the help of the +:ref:`section_ref_algorithm_LinearityTest`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: SetSeed + +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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_Blue` diff --git a/doc/en/ref_algorithm_ExtendedBlue.rst b/doc/en/ref_algorithm_ExtendedBlue.rst new file mode 100644 index 0000000..3086e42 --- /dev/null +++ b/doc/en/ref_algorithm_ExtendedBlue.rst @@ -0,0 +1,119 @@ +.. + Copyright (C) 2008-2014 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: ExtendedBlue +.. _section_ref_algorithm_ExtendedBlue: + +Calculation algorithm "*ExtendedBlue*" +-------------------------------------- + +Description ++++++++++++ + +This algorithm realizes an extended BLUE (Best Linear Unbiased Estimator) type +estimation of the state of a system. + +This algorithm is a partially non-linear generalization of the +:ref:`section_ref_algorithm_Blue`. It is equivalent for a linear observation +operator. One can verify the linearity of the observation operator with the help +of the :ref:`section_ref_algorithm_LinearityTest`. + +In case of non-linearity, it is close to the :ref:`section_ref_algorithm_3DVAR`, +without being entirely equivalent. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", + "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/en/ref_algorithm_ExtendedKalmanFilter.rst b/doc/en/ref_algorithm_ExtendedKalmanFilter.rst new file mode 100644 index 0000000..549cb91 --- /dev/null +++ b/doc/en/ref_algorithm_ExtendedKalmanFilter.rst @@ -0,0 +1,127 @@ +.. + Copyright (C) 2008-2014 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: ExtendedKalmanFilter +.. _section_ref_algorithm_ExtendedKalmanFilter: + +Calculation algorithm "*ExtendedKalmanFilter*" +---------------------------------------------- + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system by a +extended Kalman Filter, using a non-linear calculation of the state. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. 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: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + 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 extreme values every time there + is no bound (``None`` is not allowed when there is no bound). + + ConstrainedBy + This key allows to define the method to take bounds into account. The + possible methods are in the following list: ["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, + with a value of "Parameters". The default choice is "State". + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "Innovation"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` diff --git a/doc/en/ref_algorithm_FunctionTest.rst b/doc/en/ref_algorithm_FunctionTest.rst new file mode 100644 index 0000000..0019ff5 --- /dev/null +++ b/doc/en/ref_algorithm_FunctionTest.rst @@ -0,0 +1,96 @@ +.. + Copyright (C) 2008-2014 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: FunctionTest +.. _section_ref_algorithm_FunctionTest: + +Checking algorithm "FunctionTest" +--------------------------------- + +Description ++++++++++++ + +This algorithm allows to verify that the observation operator is working +correctly and that its call is compatible with its usage in ADAO algorithms. In +practice, it allows to call one or several times the operator, activating or not +the "debug" mode during execution. + +Statistics on input and output vectors for each execution of operator are given, +and an another global statistic is given at the end of the checking algorithm. +The precision of printed outputs can be controlled to facilitate automatic tests +of operator. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: NumberOfPrintedDigits +.. index:: single: NumberOfRepetition +.. index:: single: SetDebug + +The general required commands, available in the editing user interface, are the +following: + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + NumberOfPrintedDigits + This key indicates the number of digits of precision for floating point + printed output. The default is 5, with a minimum of 0. + + NumberOfRepetition + This key indicates the number of time to repeat the function evaluation. The + default is 1. + + SetDebug + This key requires the activation, or not, of the debug mode during the + function evaluation. The default is "True", the choices are "True" or + "False". + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/en/ref_algorithm_GradientTest.rst b/doc/en/ref_algorithm_GradientTest.rst new file mode 100644 index 0000000..cf45bda --- /dev/null +++ b/doc/en/ref_algorithm_GradientTest.rst @@ -0,0 +1,139 @@ +.. + Copyright (C) 2008-2014 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: GradientTest +.. _section_ref_algorithm_GradientTest: + +Checking algorithm "*GradientTest*" +----------------------------------- + +Description ++++++++++++ + +This algorithm allows to check the quality of the adjoint operator, by +calculating a residue with known theoretical properties. Different residue +formula are available. + +In any cases, one take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code. + +"Taylor" residue +**************** + +One observe the residue coming from the Taylor development of the :math:`F` +function, normalized by the value at the nominal point: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} + +If the residue is decreasing and the decrease change in :math:`\alpha^2` with +respect to :math:`\alpha`, until a certain level after which the residue remains +small and constant, it signifies that the :math:`F` is linear and that the +residue is decreasing due to the error coming from :math:`\nabla_xF` term +calculation. + +"Norm" residue +************** + +One observe the residue based on the gradient approximation: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{\alpha} + +which has to remain stable until the calculation precision is reached. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: ResiduFormula +.. index:: single: SetSeed + +The general required commands, available in the editing user interface, are the +following: + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + AmplitudeOfInitialDirection + This key indicates the scaling of the initial perturbation build as a vector + used for the directional derivative around the nominal checking point. The + default is 1, that means no scaling. + + EpsilonMinimumExponent + This key indicates the minimal exponent value of the power of 10 coefficient + to be used to decrease the increment multiplier. The default is -8, and it + has to be between 0 and -20. For example, its default value leads to + calculate the residue of the scalar product formula with a fixed increment + multiplied from 1.e0 to 1.e-8. + + InitialDirection + This key indicates the vector direction used for the directional derivative + around the nominal checking point. It has to be a vector. If not specified, + this direction defaults to a random perturbation around zero of the same + vector size than the checking point. + + ResiduFormula + This key indicates the residue formula that has to be used for the test. The + default choice is "Taylor", and the possible ones are "Taylor" (residue of + the Taylor development of the operator, which has to decrease with the + square power of the perturbation) and "Norm" (residue obtained by taking the + norm of the Taylor development at zero order approximation, which + approximate the gradient, and which has to remain constant). + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_TangentTest` + - :ref:`section_ref_algorithm_AdjointTest` diff --git a/doc/en/ref_algorithm_KalmanFilter.rst b/doc/en/ref_algorithm_KalmanFilter.rst new file mode 100644 index 0000000..7112a91 --- /dev/null +++ b/doc/en/ref_algorithm_KalmanFilter.rst @@ -0,0 +1,124 @@ +.. + Copyright (C) 2008-2014 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: KalmanFilter +.. _section_ref_algorithm_KalmanFilter: + +Calculation algorithm "*KalmanFilter*" +-------------------------------------- + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system by a +Kalman Filter. + +It is theoretically reserved for observation and incremental evolution operators +cases which are linear, even if it sometimes works in "slightly" non-linear +cases. One can verify the linearity of the observation operator with the help of +the :ref:`section_ref_algorithm_LinearityTest`. + +In case of non-linearity, even slightly marked, it will be preferred the +:ref:`section_ref_algorithm_ExtendedKalmanFilter` or the +:ref:`section_ref_algorithm_UnscentedKalmanFilter`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: EstimationOf +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + 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". + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "Innovation"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` diff --git a/doc/en/ref_algorithm_LinearLeastSquares.rst b/doc/en/ref_algorithm_LinearLeastSquares.rst new file mode 100644 index 0000000..8d1bbde --- /dev/null +++ b/doc/en/ref_algorithm_LinearLeastSquares.rst @@ -0,0 +1,117 @@ +.. + Copyright (C) 2008-2014 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: LinearLeastSquares +.. _section_ref_algorithm_LinearLeastSquares: + +Calculation algorithm "*LinearLeastSquares*" +-------------------------------------------- + +Description ++++++++++++ + +This algorithm realizes a "Least Squares" linear type estimation of the state of +a system. It is similar to the :ref:`section_ref_algorithm_Blue`, without its +background part. + +This algorithm is always the fastest of all the optimization algorithms of ADAO. +It is theoretically reserved for observation operator cases which are linear, +even if it sometimes works in "slightly" non-linear cases. One can verify the +linearity of the observation operator with the help of the +:ref:`section_ref_algorithm_LinearityTest`. + +In all cases, it is recommanded to prefer at least the +:ref:`section_ref_algorithm_Blue`, or the +:ref:`section_ref_algorithm_ExtendedBlue` or the +:ref:`section_ref_algorithm_3DVAR`. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. index:: single: StoreSupplementaryCalculations + +The general required commands, available in the editing user interface, are the +following: + + 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["OMA"]. + +*Tips for this algorithm:* + + As the *"Background"* and *"BackgroundError"* commands are required for ALL + the calculation algorithms in the interface, you have to provide a value, + even if these commands are not required for this algorithm, and will not be + used. The simplest way is to give "1" as a STRING for both. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/en/ref_algorithm_LinearityTest.rst b/doc/en/ref_algorithm_LinearityTest.rst new file mode 100644 index 0000000..6465747 --- /dev/null +++ b/doc/en/ref_algorithm_LinearityTest.rst @@ -0,0 +1,190 @@ +.. + Copyright (C) 2008-2014 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: LinearityTest +.. _section_ref_algorithm_LinearityTest: + +Checking algorithm "*LinearityTest*" +------------------------------------ + +Description ++++++++++++ + +This algorithm allows to check the linear quality of the operator, by +calculating a residue with known theoretical properties. Different residue +formula are available. + +In any cases, one take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code. + +"CenteredDL" residue +******************** + +One observe the following residue, coming from the centered difference of the +:math:`F` values at nominal point and at perturbed points, normalized by the +value at the nominal point: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) + F(\mathbf{x}-\alpha*\mathbf{dx}) - 2*F(\mathbf{x}) ||}{|| F(\mathbf{x}) ||} + +If it stays constantly really small with respect to 1, the linearity hypothesis +of :math:`F` is verified. + +If the residue is varying, or if it is of order 1 or more, and it is small only +at a certain order of increment, the linearity hypothesis of :math:`F` is not +verified. + +If the residue is decreasing and the decrease change in :math:`\alpha^2` with +respect to :math:`\alpha`, it signifies that the gradient is correctly +calculated until the stopping level of the quadratic decrease. + +"Taylor" residue +**************** + +One observe the residue coming from the Taylor development of the :math:`F` +function, normalized by the value at the nominal point: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} + +If it stay constantly really small with respect to 1, the linearity hypothesis +of :math:`F` is verified. + +If the residue is varying, or if it is of order 1 or more, and it is small only +at a certain order of increment, the linearity hypothesis of :math:`F` is not +verified. + +If the residue is decreasing and the decrease change in :math:`\alpha^2` with +respect to :math:`\alpha`, it signifies that the gradient is correctly +calculated until the stopping level of the quadratic decrease. + +"NominalTaylor" residue +*********************** + +One observe the residue build from two approximations of order 1 of +:math:`F(\mathbf{x})`, normalized by the value at the nominal point: + +.. math:: R(\alpha) = \max(|| F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||,|| F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||) + +If the residue stays constant equal to 1 at less than 2 or 3 percents (that that +:math:`|R-1|` stays equal to 2 or 3 percents), the linearity hypothesis of +:math:`F` is verified. + +If it is equal to 1 only on part of the variation domain of increment +:math:`\alpha`, it is on this sub-domain that the linearity hypothesis of +:math:`F` is verified. + +"NominalTaylorRMS" residue +************************** + +One observe the residue build from two approximations of order 1 of +:math:`F(\mathbf{x})`, normalized by the value at the nominal point, on which +one estimate the quadratic root mean square (RMS) with the value at the nominal +point: + +.. math:: R(\alpha) = \max(RMS( F(\mathbf{x}), F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||,RMS( F(\mathbf{x}), F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||) + +If it stay constantly equal to 0 at less than 1 or 2 percents, the linearity +hypothesis of :math:`F` is verified. + +If it is equal to 0 only on part of the variation domain of increment +:math:`\alpha`, it is on this sub-domain that the linearity hypothesis of +:math:`F` is verified. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: ResiduFormula +.. index:: single: SetSeed + +The general required commands, available in the editing user interface, are the +following: + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + AmplitudeOfInitialDirection + This key indicates the scaling of the initial perturbation build as a vector + used for the directional derivative around the nominal checking point. The + default is 1, that means no scaling. + + EpsilonMinimumExponent + This key indicates the minimal exponent value of the power of 10 coefficient + to be used to decrease the increment multiplier. The default is -8, and it + has to be between 0 and -20. For example, its default value leads to + calculate the residue of the scalar product formula with a fixed increment + multiplied from 1.e0 to 1.e-8. + + InitialDirection + This key indicates the vector direction used for the directional derivative + around the nominal checking point. It has to be a vector. If not specified, + this direction defaults to a random perturbation around zero of the same + vector size than the checking point. + + ResiduFormula + This key indicates the residue formula that has to be used for the test. The + default choice is "CenteredDL", and the possible ones are "CenteredDL" + (residue of the difference between the function at nominal point and the + values with positive and negative increments, which has to stay very small), + "Taylor" (residue of the Taylor development of the operator normalized by + the nominal value, which has to stay very small), "NominalTaylor" (residue + of the order 1 approximations of the operator, normalized to the nominal + point, which has to stay close to 1), and "NominalTaylorRMS" (residue of the + order 1 approximations of the operator, normalized by RMS to the nominal + point, which has to stay close to 0). + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_FunctionTest` diff --git a/doc/en/ref_algorithm_NonLinearLeastSquares.rst b/doc/en/ref_algorithm_NonLinearLeastSquares.rst new file mode 100644 index 0000000..b9abc19 --- /dev/null +++ b/doc/en/ref_algorithm_NonLinearLeastSquares.rst @@ -0,0 +1,168 @@ +.. + Copyright (C) 2008-2014 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: NonLinearLeastSquares +.. _section_ref_algorithm_NonLinearLeastSquares: + +Calculation algorithm "*NonLinearLeastSquares*" +----------------------------------------------- + +Description ++++++++++++ + +This algorithm realizes a state estimation by variational minimization of the +classical :math:`J` function of weighted "Least Squares": + +.. math:: J(\mathbf{x})=(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) + +It is similar to the :ref:`section_ref_algorithm_3DVAR`, without its background +part. The background, required in the interface, is only used as an initial +point for the variational minimization. + +In all cases, it is recommended to prefer the :ref:`section_ref_algorithm_3DVAR` +for its stability as for its behaviour during optimization. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Minimizer +.. index:: single: Bounds +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreInternalVariables +.. 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. + + 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` 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. + + 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. + + 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 due to algorithm internal control requirements. + + 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. + + 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. + + 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. + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. 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", "OMA", "OMB", "Innovation"]. + +*Tips for this algorithm:* + + As the *"BackgroundError"* command is required for ALL the calculation + algorithms in the interface, you have to provide a value, even if this + command is not required for this algorithm, and will not be used. The + simplest way is to give "1" as a STRING. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_3DVAR` + +Bibliographical references: + - [Byrd95]_ + - [Morales11]_ diff --git a/doc/en/ref_algorithm_ObserverTest.rst b/doc/en/ref_algorithm_ObserverTest.rst new file mode 100644 index 0000000..7c00b68 --- /dev/null +++ b/doc/en/ref_algorithm_ObserverTest.rst @@ -0,0 +1,65 @@ +.. + Copyright (C) 2008-2014 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: ObserverTest +.. _section_ref_algorithm_ObserverTest: + +Checking algorithm "ObserverTest" +--------------------------------- + +Description ++++++++++++ + +This algorithm allows to verify an external function, given by the user, used as +an *observer*. This external function can be applied to every of the variables +that can be potentially observed. It is activated only on those who are +explicitly associated with the *observer* in the interface. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: Observers + +The general required commands, available in the editing user interface, are the +following: + + Observers + *Optional command*. This command allows to set internal observers, that are + functions linked with a particular variable, which will be executed each + time this variable is modified. It is a convenient way to monitor variables + of interest during the data assimilation or optimization process, by + printing or plotting it, etc. Common templates are provided to help the user + to start or to quickly make his case. + +The general optional commands, available in the editing user interface, are +indicated in :ref:`section_ref_assimilation_keywords`. + +*Tips for this algorithm:* + + Because *"CheckingPoint"* and *"ObservationOperator"* are required commands + for ALL checking algorithms in the interface, you have to provide a value + for them, despite the fact that these commands are not required for + *"ObserverTest"*, and will not be used. The easiest way is to give "1" as a + STRING for both, *"ObservationOperator"* having to be of type *Matrix*. diff --git a/doc/en/ref_algorithm_ParticleSwarmOptimization.rst b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst new file mode 100644 index 0000000..3168aff --- /dev/null +++ b/doc/en/ref_algorithm_ParticleSwarmOptimization.rst @@ -0,0 +1,159 @@ +.. + Copyright (C) 2008-2014 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: ParticleSwarmOptimization +.. _section_ref_algorithm_ParticleSwarmOptimization: + +Calculation algorithm "*ParticleSwarmOptimization*" +--------------------------------------------------- + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system by a +particle swarm. + +This is an optimization method allowing for global minimum search of a general +function of type :math:`L^1`, :math:`L^2` or :math:`L^{\infty}`, with or without +weights. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: MaximumNumberOfSteps +.. index:: single: NumberOfInsects +.. index:: single: SwarmVelocity +.. index:: single: GroupRecallRate +.. index:: single: QualityCriterion +.. index:: single: BoxBounds +.. index:: single: SetSeed +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + MaximumNumberOfSteps + This key indicates the maximum number of iterations allowed for iterative + optimization. The default is 50, which is an arbitrary limit. It is then + recommended to adapt this parameter to the needs on real problems. + + NumberOfInsects + This key indicates the number of insects or particles in the swarm. The + default is 100, which is a usual default for this algorithm. + + SwarmVelocity + This key indicates the part of the insect velocity which is imposed by the + swarm. It is a positive floating point value. The default value is 1. + + GroupRecallRate + This key indicates the recall rate at the best swarm insect. It is a + floating point value between 0 and 1. The default value is 0.5. + + QualityCriterion + This key indicates the quality criterion, minimized to find the optimal + state estimate. The default is the usual data assimilation criterion named + "DA", the augmented weighted least squares. The possible criteria has to be + in the following list, where the equivalent names are indicated by the sign + "=": ["AugmentedWeightedLeastSquares"="AWLS"="DA", + "WeightedLeastSquares"="WLS", "LeastSquares"="LS"="L2", + "AbsoluteValue"="L1", "MaximumError"="ME"] + + BoxBounds + This key allows to define upper and lower bounds for *increments* on every + state variable being optimized (and not on state variables themselves). + Bounds have to be given by a list of list of pairs of lower/upper bounds for + each increment on variable, with extreme values every time there is no bound + (``None`` is not allowed when there is no bound). This key is required and + there is no default values. + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. 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", "OMA", "OMB", "Innovation"]. + +See also +++++++++ + +References to other sections: + - [WikipediaPSO]_ diff --git a/doc/en/ref_algorithm_QuantileRegression.rst b/doc/en/ref_algorithm_QuantileRegression.rst new file mode 100644 index 0000000..9a2d989 --- /dev/null +++ b/doc/en/ref_algorithm_QuantileRegression.rst @@ -0,0 +1,127 @@ +.. + Copyright (C) 2008-2014 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: QuantileRegression +.. _section_ref_algorithm_QuantileRegression: + +Calculation algorithm "*QuantileRegression*" +-------------------------------------------- + +Description ++++++++++++ + +This algorithm allows to estimate the conditional quantiles of the state +parameters distribution, expressed with a model of the observed variables. These +are then the quantiles on the observed variables which will allow to determine +the model parameters that satisfy to the quantiles conditions. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: Observation +.. index:: single: ObservationOperator +.. index:: single: Quantile +.. index:: single: Minimizer +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: StoreInternalVariables +.. 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. + + 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. + + 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + Quantile + This key allows to define the real value of the desired quantile, between + 0 and 1. The default is 0.5, corresponding to the median. + + 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. + + CostDecrementTolerance + This key indicates a limit value, leading to stop successfully the + iterative optimization process when the cost function or the surrogate + 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. + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. 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", "OMA", "OMB", "Innovation"]. + +*Tips for this algorithm:* + + As the *"BackgroundError"* and *"ObservationError"* commands are required + for ALL the calculation algorithms in the interface, you have to provide a + value, even if these commands are not required for this algorithm, and will + not be used. The simplest way is to give "1" as a STRING for both. + +See also +++++++++ + +Bibliographical references: + - [Buchinsky98]_ + - [Cade03]_ + - [Koenker00]_ + - [Koenker01]_ + - [WikipediaQR]_ diff --git a/doc/en/ref_algorithm_TangentTest.rst b/doc/en/ref_algorithm_TangentTest.rst new file mode 100644 index 0000000..4f83d15 --- /dev/null +++ b/doc/en/ref_algorithm_TangentTest.rst @@ -0,0 +1,122 @@ +.. + Copyright (C) 2008-2014 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: TangentTest +.. _section_ref_algorithm_TangentTest: + +Checking algorithm "*TangentTest*" +---------------------------------- + +Description ++++++++++++ + +This algorithm allows to check the quality of the tangent operator, by +calculating a residue with known theoretical properties. + +One can observe the following residue, which is the comparison of increments +using the tangent linear operator: + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{|| \alpha * TangentF_x * \mathbf{dx} ||} + +which has to remain stable in :math:`1+O(\alpha)` until the calculation +precision is reached. + +When :math:`|R-1|/\alpha` is less or equal to a stable value when :math:`\alpha` +is varying, the tangent is valid, until the calculation precision is reached. + +If :math:`|R-1|/\alpha` is really small, the calculation code :math:`F` is +almost linear or quasi-linear (which can be verified by the +:ref:`section_ref_algorithm_LinearityTest`), and the tangent is valid until the +calculation precision is reached. + +One take :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` and +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` is the calculation code. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: SetSeed + +The general required commands, available in the editing user interface, are the +following: + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + AmplitudeOfInitialDirection + This key indicates the scaling of the initial perturbation build as a vector + used for the directional derivative around the nominal checking point. The + default is 1, that means no scaling. + + EpsilonMinimumExponent + This key indicates the minimal exponent value of the power of 10 coefficient + to be used to decrease the increment multiplier. The default is -8, and it + has to be between 0 and -20. For example, its default value leads to + calculate the residue of the scalar product formula with a fixed increment + multiplied from 1.e0 to 1.e-8. + + InitialDirection + This key indicates the vector direction used for the directional derivative + around the nominal checking point. It has to be a vector. If not specified, + this direction defaults to a random perturbation around zero of the same + vector size than the checking point. + + SetSeed + This key allow to give an integer in order to fix the seed of the random + generator used to generate the ensemble. A convenient value is for example + 1000. By default, the seed is left uninitialized, and so use the default + initialization from the computer. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_AdjointTest` + - :ref:`section_ref_algorithm_GradientTest` diff --git a/doc/en/ref_algorithm_UnscentedKalmanFilter.rst b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst new file mode 100644 index 0000000..9938481 --- /dev/null +++ b/doc/en/ref_algorithm_UnscentedKalmanFilter.rst @@ -0,0 +1,143 @@ +.. + Copyright (C) 2008-2014 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: UnscentedKalmanFilter +.. _section_ref_algorithm_UnscentedKalmanFilter: + +Calculation algorithm "*UnscentedKalmanFilter*" +----------------------------------------------- + +Description ++++++++++++ + +This algorithm realizes an estimation of the state of a dynamic system by a +"unscented" Kalman Filter, avoiding to have to perform the tangent and adjoint +operators for the observation and evolution operators, as in the simple or +extended Kalman filter. + +Optional and required commands +++++++++++++++++++++++++++++++ + +.. 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: Alpha +.. index:: single: Beta +.. index:: single: Kappa +.. index:: single: Reconditioner +.. index:: single: StoreInternalVariables +.. 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`. In particular, the +optional command "*AlgorithmParameters*" allows to choose the specific options, +described hereafter, of the algorithm. See +:ref:`section_ref_options_AlgorithmParameters` for the good use of this command. + +The options of the algorithm are the following: + + 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 extreme values every time there + is no bound (``None`` is not allowed when there is no bound). + + ConstrainedBy + This key allows to define the method to take bounds into account. The + possible methods are in the following list: ["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, + with a value of "Parameters". The default choice is "State". + + Alpha, Beta, Kappa, Reconditioner + These keys are internal scaling parameters. "Alpha" requires a value between + 1.e-4 and 1. "Beta" has an optimal value of 2 for Gaussian *a priori* + distribution. "Kappa" requires an integer value, and the right default is + obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3 + and 10, it defaults to 1. + + StoreInternalVariables + This Boolean key allows to store default internal variables, mainly the + current state during iterative optimization process. Be careful, this can be + a numerically costly choice in certain calculation cases. The default is + "False". + + 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. The default is a void list, none of these variables being + calculated and stored by default. The possible names are in the following + list: ["APosterioriCovariance", "BMA", "Innovation"]. + +See also +++++++++ + +References to other sections: + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + +Bibliographical references: + - [WikipediaUKF]_ diff --git a/doc/en/ref_assimilation_keywords.rst b/doc/en/ref_assimilation_keywords.rst new file mode 100644 index 0000000..d1322cd --- /dev/null +++ b/doc/en/ref_assimilation_keywords.rst @@ -0,0 +1,174 @@ +.. + Copyright (C) 2008-2014 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: ASSIMILATION_STUDY +.. _section_ref_assimilation_keywords: + +List of commands and keywords for an ADAO calculation case +---------------------------------------------------------- + +.. index:: single: Algorithm +.. index:: single: AlgorithmParameters +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: ControlInput +.. index:: single: Debug +.. index:: single: EvolutionError +.. index:: single: EvolutionModel +.. index:: single: InputVariables +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Observer +.. index:: single: Observers +.. index:: single: Observer Template +.. index:: single: OutputVariables +.. index:: single: Study_name +.. index:: single: Study_repertory +.. index:: single: UserDataInit +.. index:: single: UserPostAnalysis +.. index:: single: UserPostAnalysis Template + +This set of commands is related to the description of a calculation case, +that is a *Data Assimilation* procedure or an *Optimization* procedure. The +terms are ordered in alphabetical order, except the first, which describes +choice between calculation or checking. + +The different commands are the following: + + **ASSIMILATION_STUDY** + *Required command*. This is the general command describing the data + assimilation or optimization case. It hierarchically contains all the other + commands. + + Algorithm + *Required command*. This is a string to indicate the data assimilation or + optimization algorithm chosen. The choices are limited and available through + the GUI. There exists for example "3DVAR", "Blue"... See below the list of + algorithms and associated parameters, each described by a subsection. + + AlgorithmParameters + *Optional command*. This command allows to add some optional parameters to + control the data assimilation or optimization algorithm. Its value is + defined as a "*Dict*" type object. See the section + :ref:`section_ref_options_AlgorithmParameters` for for the correct use of + this command. + + 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*" 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. + + ControlInput + *Optional command*. This indicates the control vector used to force the + evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value + is defined as a "*Vector*" or a *VectorSerie* type object. When there is no + control, it has to be a void string ''. + + Debug + *Optional command*. This define the level of trace and intermediary debug + information. The choices are limited between 0 (for False) and 1 (for + True). + + EvolutionError + *Optional command*. This indicates the evolution error covariance matrix, + usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type + object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*" + type object. + + EvolutionModel + *Optional command*. This indicates the evolution model operator, usually + noted :math:`M`, which describes an elementary step of evolution. 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 evolution model, the operator has + to be applied to a pair :math:`(X,U)`. + + InputVariables + *Optional command*. This command allows to indicates the name and size of + physical variables that are bundled together in the state vector. This + information is dedicated to data processed inside an algorithm. + + 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)`. + + Observers + *Optional command*. This command allows to set internal observers, that are + functions linked with a particular variable, which will be executed each + time this variable is modified. It is a convenient way to monitor variables + of interest during the data assimilation or optimization process, by + printing or plotting it, etc. Common templates are provided to help the user + to start or to quickly make his case. + + OutputVariables + *Optional command*. This command allows to indicates the name and size of + physical variables that are bundled together in the output observation + vector. This information is dedicated to data processed inside an algorithm. + + Study_name + *Required command*. This is an open string to describe the ADAO study by a + name or a sentence. + + Study_repertory + *Optional command*. If available, this directory is used as base name for + calculation, and used to find all the script files, given by name without + path, that can be used to define some other commands by scripts. + + UserDataInit + *Optional command*. This commands allows to initialize some parameters or + data automatically before algorithm input processing. It indicates a script + file name to be executed before entering in initialization phase of chosen + variables. + + UserPostAnalysis + *Optional command*. This commands allows to process some parameters or data + automatically after data assimilation or optimization algorithm processing. + Its value is defined as a script file or a string, allowing to put + post-processing code directly inside the ADAO case. Common templates are + provided to help the user to start or to quickly make his case. diff --git a/doc/en/ref_checking_keywords.rst b/doc/en/ref_checking_keywords.rst new file mode 100644 index 0000000..29e7437 --- /dev/null +++ b/doc/en/ref_checking_keywords.rst @@ -0,0 +1,108 @@ +.. + Copyright (C) 2008-2014 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: CHECKING_STUDY +.. _section_ref_checking_keywords: + +List of commands and keywords for an ADAO checking case +------------------------------------------------------- + +.. index:: single: Algorithm +.. index:: single: AlgorithmParameters +.. index:: single: CheckingPoint +.. index:: single: Debug +.. index:: single: ObservationOperator +.. index:: single: Observer +.. index:: single: Observers +.. index:: single: Observer Template +.. index:: single: Study_name +.. index:: single: Study_repertory +.. index:: single: UserDataInit + +This set of commands is related to the description of a checking case, that is a +procedure to check required properties on information, used somewhere else by a +calculation case. The terms are ordered in alphabetical order, except the first, +which describes the choice between calculation or checking. + +The different commands are the following: + + **CHECKING_STUDY** + *Required command*. This is the general command describing the checking + case. It hierarchically contains all the other commands. + + Algorithm + *Required command*. This is a string to indicate the checking algorithm chosen. + The choices are limited and available through the GUI. There exists for + example "FunctionTest", "AdjointTest"... See below the list of algorithms + and associated parameters, each described by a subsection. + + AlgorithmParameters + *Optional command*. This command allows to add some optional parameters to + control the data assimilation or optimization algorithm. Its value is + defined as a "*Dict*" type object. See the section + :ref:`section_ref_options_AlgorithmParameters` for for the correct use of + this command. + + CheckingPoint + *Required command*. This indicates the vector used as the state around which + to perform the required check, noted :math:`\mathbf{x}` and similar to the + background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object. + + Debug + *Optional command*. This define the level of trace and intermediary debug + information. The choices are limited between 0 (for False) and 1 (for + True). + + 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)`. + + Observers + *Optional command*. This command allows to set internal observers, that are + functions linked with a particular variable, which will be executed each + time this variable is modified. It is a convenient way to monitor variables + of interest during the data assimilation or optimization process, by + printing or plotting it, etc. Common templates are provided to help the user + to start or to quickly make his case. + + Study_name + *Required command*. This is an open string to describe the ADAO study by a + name or a sentence. + + Study_repertory + *Optional command*. If available, this directory is used as base name for + calculation, and used to find all the script files, given by name without + path, that can be used to define some other commands by scripts. + + UserDataInit + *Optional command*. This commands allows to initialize some parameters or + data automatically before algorithm input processing. It indicates a script + file name to be executed before entering in initialization phase of chosen + variables. diff --git a/doc/en/ref_covariance_requirements.rst b/doc/en/ref_covariance_requirements.rst new file mode 100644 index 0000000..fe64eba --- /dev/null +++ b/doc/en/ref_covariance_requirements.rst @@ -0,0 +1,137 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_covariance_requirements: + +Requirements to describe covariance matrices +-------------------------------------------- + +Multiple covariance matrices are required to implement the data assimilation or +optimization procedures. The main ones are the background error covariance +matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix, +noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symmetric +semi-definite positive matrix. + +There are 3 practical methods for the user to provide a covariance matrix. These +methods are chosen by the "*INPUT_TYPE*" keyword of each defined covariance +matrix, as shown by the following figure: + + .. eficas_covariance_matrix: + .. image:: images/eficas_covariance_matrix.png + :align: center + :width: 100% + .. centered:: + **Choosing covariance matrix representation** + +First matrix form: using "*Matrix*" representation +++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: Matrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +This first form is the default and more general one. The covariance matrix +:math:`\mathbf{M}` has to be fully specified. Even if the matrix is symmetric by +nature, the entire :math:`\mathbf{M}` matrix has to be given. + +.. math:: \mathbf{M} = \begin{pmatrix} + m_{11} & m_{12} & \cdots & m_{1n} \\ + m_{21} & m_{22} & \cdots & m_{2n} \\ + \vdots & \vdots & \vdots & \vdots \\ + m_{n1} & \cdots & m_{nn-1} & m_{nn} + \end{pmatrix} + +It can be either a Python Numpy array or a matrix, or a list of lists of values +(that is, a list of rows). For example, a simple diagonal unitary background +error covariance matrix :math:`\mathbf{B}` can be described in a Python script +file as:: + + BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]] + +or:: + + BackgroundError = numpy.eye(...) + +Second matrix form: using "*ScalarSparseMatrix*" representation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScalarSparseMatrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +On the opposite, this second form is a very simplified method to provide a +matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive +multiple of the identity matrix. This matrix can then be specified in a unique +way by the multiplier :math:`m`: + +.. math:: \mathbf{M} = m \times \begin{pmatrix} + 1 & 0 & \cdots & 0 \\ + 0 & 1 & \cdots & 0 \\ + \vdots & \vdots & \vdots & \vdots \\ + 0 & \cdots & 0 & 1 + \end{pmatrix} + +The multiplier :math:`m` has to be a floating point or integer positive value +(if it is negative, which is impossible for a positive covariance matrix, it is +converted to positive value). For example, a simple diagonal unitary background +error covariance matrix :math:`\mathbf{B}` can be described in a python script +file as:: + + BackgroundError = 1. + +or, better, by a "*String*" directly in the ADAO case. + +Third matrix form: using "*DiagonalSparseMatrix*" representation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: DiagonalSparseMatrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +This third form is also a simplified method to provide a matrix, but a little +more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is +already supposed to be diagonal, but the user has to specify all the positive +diagonal values. The matrix can then be specified only by a vector +:math:`\mathbf{V}` which will be set on a diagonal matrix: + +.. math:: \mathbf{M} = \begin{pmatrix} + v_{1} & 0 & \cdots & 0 \\ + 0 & v_{2} & \cdots & 0 \\ + \vdots & \vdots & \vdots & \vdots \\ + 0 & \cdots & 0 & v_{n} + \end{pmatrix} + +It can be either a Python Numpy array or a matrix, or a list or a list of list +of positive values (in all cases, if some are negative, which is impossible, +they are converted to positive values). For example, a simple diagonal unitary +background error covariance matrix :math:`\mathbf{B}` can be described in a +python script file as:: + + BackgroundError = [1, 1 ... 1] + +or:: + + BackgroundError = numpy.ones(...) diff --git a/doc/en/ref_entry_types.rst b/doc/en/ref_entry_types.rst new file mode 100644 index 0000000..683b354 --- /dev/null +++ b/doc/en/ref_entry_types.rst @@ -0,0 +1,103 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_entry_types: + +List of possible input types +---------------------------- + +.. index:: single: Dict +.. index:: single: Function +.. index:: single: Matrix +.. index:: single: ScalarSparseMatrix +.. index:: single: DiagonalSparseMatrix +.. index:: single: String +.. index:: single: Script +.. index:: single: Vector + +Each ADAO variable has a pseudo-type to help filling it and validation. The +different pseudo-types are: + +.. index:: single: Dict + +**Dict** + This indicates a variable that has to be filled by a Python dictionary + ``{"key":"value...}``, usually given either as a string or as a script file. + +.. index:: single: Function + +**Function** + This indicates a variable that has to be filled by a Python function, + usually given as a script file or a component method. + +.. index:: single: Matrix + +**Matrix** + This indicates a variable that has to be filled by a matrix, usually given + either as a string or as a script file. + +.. index:: single: ScalarSparseMatrix + +**ScalarSparseMatrix** + This indicates a variable that has to be filled by a unique number (which + will be used to multiply an identity matrix), usually given either as a + string or as a script file. + +.. index:: single: DiagonalSparseMatrix + +**DiagonalSparseMatrix** + This indicates a variable that has to be filled by a vector (which will be + used to replace the diagonal of an identity matrix), usually given either as + a string or as a script file. + +.. index:: single: Script + +**Script** + This indicates a script given as an external file. It can be described by a + full absolute path name or only by the file name without path. If the file + is given only by a file name without path, and if a study directory is also + indicated, the file is searched in the given directory. + +.. index:: single: String + +**String** + This indicates a string giving a literal representation of a matrix, a + vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a + square 2x2 matrix. + +.. index:: single: Vector + +**Vector** + This indicates a variable that has to be filled by a vector, usually given + either as a string or as a script file. + +.. index:: single: VectorSerie + +**VectorSerie** + This indicates a variable that has to be filled by a list of + vectors, usually given either as a string or as a script file. + +When a command or keyword can be filled by a script file name, the script has to +contain a variable or a method that has the same name as the one to be filled. +In other words, when importing the script in a YACS Python node, it must create +a variable of the good name in the current name space of the node. diff --git a/doc/en/ref_operator_requirements.rst b/doc/en/ref_operator_requirements.rst new file mode 100644 index 0000000..120edcb --- /dev/null +++ b/doc/en/ref_operator_requirements.rst @@ -0,0 +1,268 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_operator_requirements: + +Requirements for functions describing an operator +------------------------------------------------- + +The operators for observation and evolution are required to implement the data +assimilation or optimization procedures. They include the physical simulation by +numerical calculations, but also the filtering and restriction to compare the +simulation to observation. The evolution operator is considered here in its +incremental form, representing the transition between two successive states, and +is then similar to the observation operator. + +Schematically, an operator has to give a output solution given the input +parameters. Part of the input parameters can be modified during the optimization +procedure. So the mathematical representation of such a process is a function. +It was briefly described in the section :ref:`section_theory` and is generalized +here by the relation: + +.. math:: \mathbf{y} = O( \mathbf{x} ) + +between the pseudo-observations :math:`\mathbf{y}` and the parameters +:math:`\mathbf{x}` using the observation or evolution operator :math:`O`. The +same functional representation can be used for the linear tangent model +:math:`\mathbf{O}` of :math:`O` and its adjoint :math:`\mathbf{O}^*`, also +required by some data assimilation or optimization algorithms. + +On input and output of these operators, the :math:`\mathbf{x}` and +:math:`\mathbf{y}` variables or their increments are mathematically vectors, +and they are given as non-oriented vectors (of type list or Numpy array) or +oriented ones (of type Numpy matrix). + +Then, **to describe completely an operator, the user has only to provide a +function that fully and only realize the functional operation**. + +This function is usually given as a script that can be executed in a YACS node. +This script can without difference launch external codes or use internal SALOME +calls and methods. If the algorithm requires the 3 aspects of the operator +(direct form, tangent form and adjoint form), the user has to give the 3 +functions or to approximate them. + +There are 3 practical methods for the user to provide an operator functional +representation. These methods are chosen in the "*FROM*" field of each operator +having a "*Function*" value as "*INPUT_TYPE*", as shown by the following figure: + + .. eficas_operator_function: + .. image:: images/eficas_operator_function.png + :align: center + :width: 100% + .. centered:: + **Choosing an operator functional representation** + +First functional form: using "*ScriptWithOneFunction*" +++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithOneFunction +.. index:: single: DirectOperator +.. index:: single: DifferentialIncrement +.. index:: single: CenteredFiniteDifference + +The first one consist in providing only one potentially non-linear function, and +to approximate the tangent and the adjoint operators. This is done by using the +keyword "*ScriptWithOneFunction*" for the description of the chosen operator in +the ADAO GUI. The user have to provide the function in a script, with a +mandatory name "*DirectOperator*". For example, the script can follow the +template:: + + def DirectOperator( X ): + """ Direct non-linear simulation operator """ + ... + ... + ... + return Y=O(X) + +In this case, the user has also provide a value for the differential increment +(or keep the default value), using through the GUI the keyword +"*DifferentialIncrement*", which has a default value of 1%. This coefficient +will be used in the finite differences approximation to build the tangent and +adjoint operators. The finite differences approximation order can also be chosen +through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an +uncentered schema of first order (which is the default value), and with 1 for a +centered schema of second order (of twice the first order computational cost). + +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 implementation. + +**Important warning:** the name "*DirectOperator*" is mandatory, and the type of +the ``X`` argument can be either a list, a numpy array or a numpy 1D-matrix. The +user has to treat these cases in his function. + +Second functional form: using "*ScriptWithFunctions*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithFunctions +.. index:: single: DirectOperator +.. index:: single: TangentOperator +.. index:: single: AdjointOperator + +**In general, it is recommended to use the first functional form rather than +the second one. A small performance improvement is not a good reason to use a +detailed implementation as this second functional form.** + +The second one consist in providing directly the three associated operators +:math:`O`, :math:`\mathbf{O}` and :math:`\mathbf{O}^*`. This is done by using +the keyword "*ScriptWithFunctions*" for the description of the chosen operator +in the ADAO GUI. The user have to provide three functions in one script, with +three mandatory names "*DirectOperator*", "*TangentOperator*" and +"*AdjointOperator*". For example, the script can follow the template:: + + def DirectOperator( X ): + """ Direct non-linear simulation operator """ + ... + ... + ... + return something like Y + + def TangentOperator( (X, dX) ): + """ Tangent linear operator, around X, applied to dX """ + ... + ... + ... + return something like Y + + def AdjointOperator( (X, Y) ): + """ Adjoint operator, around X, applied to Y """ + ... + ... + ... + return something like X + +Another time, this second operator definition allow easily to test the +functional forms before their use in an ADAO case, reducing the complexity of +operator implementation. + +For some algorithms, it is required that the tangent and adjoint functions can +return the matrix equivalent to the linear operator. In this case, when +respectively the ``dX`` or the ``Y`` arguments are ``None``, the user has to +return the associated matrix. + +**Important warning:** the names "*DirectOperator*", "*TangentOperator*" and +"*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX`` +arguments can be either a python list, a numpy array or a numpy 1D-matrix. The +user has to treat these cases in his script. + +Third functional form: using "*ScriptWithSwitch*" ++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithSwitch +.. index:: single: DirectOperator +.. index:: single: TangentOperator +.. index:: single: AdjointOperator + +**It is recommended not to use this third functional form without a solid +numerical or physical reason. A performance improvement is not a good reason to +use the implementation complexity of this third functional form. Only an +inability to use the first or second forms justifies the use of the third.** + +This third form give more possibilities to control the execution of the three +functions representing the operator, allowing advanced usage and control over +each execution of the simulation code. This is done by using the keyword +"*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI. +The user have to provide a switch in one script to control the execution of the +direct, tangent and adjoint forms of its simulation code. The user can then, for +example, use other approximations for the tangent and adjoint codes, or +introduce more complexity in the argument treatment of the functions. But it +will be far more complicated to implement and debug. + +If, however, you want to use this third form, we recommend using the following +template for the switch. It requires an external script or code named here +"*Physical_simulation_functions.py*", containing three functions named +"*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously. +Here is the switch template:: + + import Physical_simulation_functions + import numpy, logging + # + method = "" + for param in computation["specificParameters"]: + if param["name"] == "method": + method = param["value"] + if method not in ["Direct", "Tangent", "Adjoint"]: + raise ValueError("No valid computation method is given") + logging.info("Found method is \'%s\'"%method) + # + logging.info("Loading operator functions") + Function = Physical_simulation_functions.DirectOperator + Tangent = Physical_simulation_functions.TangentOperator + Adjoint = Physical_simulation_functions.AdjointOperator + # + logging.info("Executing the possible computations") + data = [] + if method == "Direct": + logging.info("Direct computation") + Xcurrent = computation["inputValues"][0][0][0] + data = Function(numpy.matrix( Xcurrent ).T) + if method == "Tangent": + logging.info("Tangent computation") + Xcurrent = computation["inputValues"][0][0][0] + dXcurrent = computation["inputValues"][0][0][1] + data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T) + if method == "Adjoint": + logging.info("Adjoint computation") + Xcurrent = computation["inputValues"][0][0][0] + Ycurrent = computation["inputValues"][0][0][1] + data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T)) + # + logging.info("Formatting the output") + it = numpy.ravel(data) + outputValues = [[[[]]]] + for val in it: + outputValues[0][0][0].append(val) + # + result = {} + result["outputValues"] = outputValues + result["specificOutputInfos"] = [] + result["returnCode"] = 0 + result["errorMessage"] = "" + +All various modifications could be done from this template hypothesis. + +Special case of controlled evolution or observation operator +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In some cases, the evolution or the observation operator is required to be +controlled by an external input control, given *a priori*. In this case, the +generic form of the incremental model is slightly modified as follows: + +.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u}) + +where :math:`\mathbf{u}` is the control over one state increment. In this case, +the direct operator has to be applied to a pair of variables :math:`(X,U)`. +Schematically, the operator has to be set as:: + + def DirectOperator( (X, U) ): + """ Direct non-linear simulation operator """ + ... + ... + ... + return something like X(n+1) (evolution) or Y(n+1) (observation) + +The tangent and adjoint operators have the same signature as previously, noting +that the derivatives has to be done only partially against :math:`\mathbf{x}`. +In such a case with explicit control, only the second functional form (using +"*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*") +can be used. diff --git a/doc/en/ref_options_AlgorithmParameters.rst b/doc/en/ref_options_AlgorithmParameters.rst new file mode 100644 index 0000000..151b482 --- /dev/null +++ b/doc/en/ref_options_AlgorithmParameters.rst @@ -0,0 +1,49 @@ +.. + Copyright (C) 2008-2014 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: AlgorithmParameters +.. _section_ref_options_AlgorithmParameters: + +Description of options of an algorithm by "*AlgorithmParameters*" +----------------------------------------------------------------- + +Each algorithm can be controlled using some generic or specific options, given +through the "*AlgorithmParameters*" optional command in a script file or a +string, as follows for example in a Python file:: + + AlgorithmParameters = { + "StoreInternalVariables" : True, + "MaximumNumberOfSteps" : 25, + "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], + } + +To give the "*AlgorithmParameters*" values by a string, directly in the EFICAS +interface, one must enclose a standard dictionary definition between simple +quotes, as for example:: + + '{"StoreInternalVariables":True,"MaximumNumberOfSteps":25}' + +If an option is specified by the user for an algorithm that doesn't support it, +the option is simply left unused and don't stop the treatment. The meaning of +the acronyms or particular names can be found in the :ref:`genindex` or the +:ref:`section_glossary`. diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 1acc0a0..124d4a1 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -1,11 +1,37 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_reference: ================================================================================ -Reference description of the ADAO commands and keywords +**[DocR]** Reference description of the ADAO commands and keywords ================================================================================ -This section presents the reference description of the ADAO commands and -keywords available through the GUI or through scripts. +The following sections present the reference description of the ADAO commands +and keywords available through the GUI or through scripts. A first common +section presents in general the :ref:`section_reference_entry`. After that, one +describes successively the :ref:`section_reference_assimilation` and the +:ref:`section_reference_checking`. Each command or keyword to be defined through the ADAO GUI has some properties. The first property is to be *required*, *optional* or only factual, describing a @@ -15,1324 +41,75 @@ some specified values. The EFICAS editor GUI having build-in validating capacities, the properties of the commands or keywords given through this GUI are automatically correct. -The mathematical notations used afterward are explained in the section -:ref:`section_theory`. - -Examples of using these commands are available in the section -:ref:`section_examples` and in example files installed with ADAO module. - -List of possible input types ----------------------------- - -.. index:: single: Dict -.. index:: single: Function -.. index:: single: Matrix -.. index:: single: ScalarSparseMatrix -.. index:: single: DiagonalSparseMatrix -.. index:: single: String -.. index:: single: Script -.. index:: single: Vector - -Each ADAO variable has a pseudo-type to help filling it and validation. The -different pseudo-types are: - -**Dict** - This indicates a variable that has to be filled by a Python dictionary - ``{"key":"value...}``, usually given either as a string or as a script file. - -**Function** - This indicates a variable that has to be filled by a Python function, - usually given as a script file or a component method. - -**Matrix** - This indicates a variable that has to be filled by a matrix, usually given - either as a string or as a script file. - -**ScalarSparseMatrix** - This indicates a variable that has to be filled by a unique number (which - will be used to multiply an identity matrix), usually given either as a - string or as a script file. - -**DiagonalSparseMatrix** - This indicates a variable that has to be filled by a vector (which will be - used to replace the diagonal of an identity matrix), usually given either as - a string or as a script file. - -**Script** - This indicates a script given as an external file. It can be described by a - full absolute path name or only by the file name without path. If the file - is given only by a file name without path, and if a study directory is also - indicated, the file is searched in the given directory. - -**String** - This indicates a string giving a literal representation of a matrix, a - vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a - square 2x2 matrix. - -**Vector** - This indicates a variable that has to be filled by a vector, usually given - either as a string or as a script file. - -**VectorSerie** - This indicates a variable that has to be filled by a list of - vectors, usually given either as a string or as a script file. - -When a command or keyword can be filled by a script file name, the script has to -contain a variable or a method that has the same name as the one to be filled. -In other words, when importing the script in a YACS Python node, it must create -a variable of the good name in the current namespace of the node. - -Reference description for ADAO calculation cases ------------------------------------------------- - -List of commands and keywords for an ADAO calculation case -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ASSIMILATION_STUDY -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: Background -.. index:: single: BackgroundError -.. index:: single: ControlInput -.. index:: single: Debug -.. index:: single: EvolutionError -.. index:: single: EvolutionModel -.. index:: single: InputVariables -.. index:: single: Observation -.. index:: single: ObservationError -.. index:: single: ObservationOperator -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: OutputVariables -.. index:: single: Study_name -.. index:: single: Study_repertory -.. index:: single: UserDataInit -.. index:: single: UserPostAnalysis -.. index:: single: UserPostAnalysis Template - -The first set of commands is related to the description of a calculation case, -that is a *Data Assimilation* procedure or an *Optimization* procedure. The -terms are ordered in alphabetical order, except the first, which describes -choice between calculation or checking. The different commands are the -following: - -**ASSIMILATION_STUDY** - *Required command*. This is the general command describing the data - assimilation or optimization case. It hierarchically contains all the other - commands. - -**Algorithm** - *Required command*. This is a string to indicate the data assimilation or - optimization algorithm chosen. The choices are limited and available through - the GUI. There exists for example "3DVAR", "Blue"... See below the list of - algorithms and associated parameters in the following subsection `Optional - and required commands for calculation algorithms`_. - -**AlgorithmParameters** - *Optional command*. This command allows to add some optional parameters to - control the data assimilation or optimization algorithm. Its value is - defined as a "*Dict*" type object. See below the list of algorithms and - associated parameters in the following subsection `Optional and required - commands for calculation algorithms`_. - -**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*" 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. - -**ControlInput** - *Optional command*. This indicates the control vector used to force the - evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value - is defined as a "*Vector*" or a *VectorSerie* type object. When there is no - control, it has to be a void string ''. - -**Debug** - *Optional command*. This define the level of trace and intermediary debug - information. The choices are limited between 0 (for False) and 1 (for - True). - -**EvolutionError** - *Optional command*. This indicates the evolution error covariance matrix, - usually noted as :math:`\mathbf{Q}`. It is defined as a "*Matrix*" type - object, a "*ScalarSparseMatrix*" type object, or a "*DiagonalSparseMatrix*" - type object. - -**EvolutionModel** - *Optional command*. This indicates the evolution model operator, usually - noted :math:`M`, which describes an elementary step of evolution. 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 following subsection `Requirements for functions describing - an operator`_. If there is some control :math:`U` included in the evolution - model, the operator has to be applied to a pair :math:`(X,U)`. - -**InputVariables** - *Optional command*. This command allows to indicates the name and size of - physical variables that are bundled together in the state vector. This - information is dedicated to data processed inside an algorithm. - -**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 following subsection - `Requirements for functions describing an operator`_. If there is some - control :math:`U` included in the observation, the operator has to be - applied to a pair :math:`(X,U)`. - -**Observers** - *Optional command*. This command allows to set internal observers, that are - functions linked with a particular variable, which will be executed each - time this variable is modified. It is a convenient way to monitor variables - of interest during the data assimilation or optimization process, by - printing or plotting it, etc. Common templates are provided to help the user - to start or to quickly make his case. - -**OutputVariables** - *Optional command*. This command allows to indicates the name and size of - physical variables that are bundled together in the output observation - vector. This information is dedicated to data processed inside an algorithm. - -**Study_name** - *Required command*. This is an open string to describe the ADAO study by a - name or a sentence. - -**Study_repertory** - *Optional command*. If available, this directory is used as base name for - calculation, and used to find all the script files, given by name without - path, that can be used to define some other commands by scripts. - -**UserDataInit** - *Optional command*. This commands allows to initialize some parameters or - data automatically before data assimilation or optimization algorithm input - processing. It indicates a script file name to be executed before entering - in initialization phase of chosen variables. - -**UserPostAnalysis** - *Optional command*. This commands allows to process some parameters or data - automatically after data assimilation or optimization algorithm processing. - Its value is defined as a script file or a string, allowing to put - post-processing code directly inside the ADAO case. Common templates are - provided to help the user to start or to quickly make his case. - -Optional and required commands for calculation algorithms -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: 3DVAR -.. index:: single: Blue -.. index:: single: ExtendedBlue -.. index:: single: EnsembleBlue -.. index:: single: KalmanFilter -.. index:: single: ExtendedKalmanFilter -.. index:: single: UnscentedKalmanFilter -.. index:: single: LinearLeastSquares -.. index:: single: NonLinearLeastSquares -.. index:: single: ParticleSwarmOptimization -.. index:: single: QuantileRegression - -.. index:: single: AlgorithmParameters -.. index:: single: Bounds -.. index:: single: CostDecrementTolerance -.. index:: single: GradientNormTolerance -.. index:: single: GroupRecallRate -.. index:: single: MaximumNumberOfSteps -.. index:: single: Minimizer -.. index:: single: NumberOfInsects -.. index:: single: ProjectedGradientTolerance -.. index:: single: QualityCriterion -.. index:: single: Quantile -.. index:: single: SetSeed -.. index:: single: StoreInternalVariables -.. index:: single: StoreSupplementaryCalculations -.. index:: single: SwarmVelocity - -Each algorithm can be controlled using some generic or specific options, given -through the "*AlgorithmParameters*" optional command in a script file or a -string, as follows for example in a file:: - - AlgorithmParameters = { - "Minimizer" : "LBFGSB", - "MaximumNumberOfSteps" : 25, - "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], - } - -To give the "*AlgorithmParameters*" values by string, one must enclose a -standard dictionary definition between simple quotes, as for example:: - - '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}' - -This section describes the available options algorithm by algorithm. In -addition, for each algorithm, the required commands/keywords are given, being -described in `List of commands and keywords for an ADAO calculation case`_. If -an option is specified by the user for an algorithm that doesn't support it, the -option is simply left unused and don't stop the treatment. The meaning of the -acronyms or particular names can be found in the :ref:`genindex` or the -:ref:`section_glossary`. - -**"Blue"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", - "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. - -**"ExtendedBlue"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", - "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. - -**"LinearLeastSquares"** - - *Required commands* - *"Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["OMA"]. - -**"3DVAR"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "OMA", "OMB", "Innovation", - "SigmaObs2", "MahalanobisConsistency"]. - -**"NonLinearLeastSquares"** - - *Required commands* - *"Background", - "Observation", "ObservationError", - "ObservationOperator"* - - 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. - - 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. - - 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 due to algorithm internal control requirements. - - 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. - - 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. - - 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. - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. 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", "OMA", "OMB", "Innovation"]. - -**"EnsembleBlue"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - -**"KalmanFilter"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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". - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "Innovation"]. - -**"ExtendedKalmanFilter"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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 extreme values every time there - is no bound (``None`` is not allowed when there is no bound). - - ConstrainedBy - This key allows to define the method to take bounds into account. The - possible methods are in the following list: ["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, - with a value of "Parameters". The default choice is "State". - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "Innovation"]. - -**"UnscentedKalmanFilter"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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 extreme values every time there - is no bound (``None`` is not allowed when there is no bound). - - ConstrainedBy - This key allows to define the method to take bounds into account. The - possible methods are in the following list: ["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, - with a value of "Parameters". The default choice is "State". - - Alpha, Beta, Kappa, Reconditioner - These keys are internal scaling parameters. "Alpha" requires a value between - 1.e-4 and 1. "Beta" has an optimal value of 2 for Gaussian *a priori* - distribution. "Kappa" requires an integer value, and the right default is - obtained by setting it to 0. "Reconditioner" requires a value between 1.e-3 - and 10, it defaults to 1. - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. The default is a void list, none of these variables being - calculated and stored by default. The possible names are in the following - list: ["APosterioriCovariance", "BMA", "Innovation"]. - -**"ParticleSwarmOptimization"** - - *Required commands* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - MaximumNumberOfSteps - This key indicates the maximum number of iterations allowed for iterative - optimization. The default is 50, which is an arbitrary limit. It is then - recommended to adapt this parameter to the needs on real problems. - - NumberOfInsects - This key indicates the number of insects or particles in the swarm. The - default is 100, which is a usual default for this algorithm. - - SwarmVelocity - This key indicates the part of the insect velocity which is imposed by the - swarm. It is a positive floating point value. The default value is 1. - - GroupRecallRate - This key indicates the recall rate at the best swarm insect. It is a - floating point value between 0 and 1. The default value is 0.5. - - QualityCriterion - This key indicates the quality criterion, minimized to find the optimal - state estimate. The default is the usual data assimilation criterion named - "DA", the augmented weighted least squares. The possible criteria has to be - in the following list, where the equivalent names are indicated by the sign - "=": ["AugmentedWeightedLeastSquares"="AWLS"="DA", - "WeightedLeastSquares"="WLS", "LeastSquares"="LS"="L2", - "AbsoluteValue"="L1", "MaximumError"="ME"] - - BoxBounds - This key allows to define upper and lower bounds for *increments* on every - state variable being optimized (and not on state variables themselves). - Bounds have to be given by a list of list of pairs of lower/upper bounds for - each increment on variable, with extreme values every time there is no bound - (``None`` is not allowed when there is no bound). This key is required and - there is no default values. - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". - - 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. 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", "OMA", "OMB", "Innovation"]. - -**"QuantileRegression"** - - *Required commands* - *"Background", - "Observation", - "ObservationOperator"* +.. _section_reference_entry: - Quantile - This key allows to define the real value of the desired quantile, between - 0 and 1. The default is 0.5, corresponding to the median. +======================================================================================== +**[DocR]** General entries, functions and matrices +======================================================================================== - Minimizer - This key allows to choose the optimization minimizer. The default choice - and only available choice is "MMQR" (Majorize-Minimize for Quantile - Regression). +This section describes in general the different possible entry types, and the +functional or matrix forms that can be used. The mathematical notations used +afterwards are explained in the section :ref:`section_theory`. - 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. +.. toctree:: + :maxdepth: 1 + + ref_entry_types + ref_options_AlgorithmParameters + ref_operator_requirements + ref_covariance_requirements - CostDecrementTolerance - This key indicates a limit value, leading to stop successfully the - iterative optimization process when the cost function or the surrogate - 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. +.. _section_reference_assimilation: - StoreInternalVariables - This Boolean key allows to store default internal variables, mainly the - current state during iterative optimization process. Be careful, this can be - a numerically costly choice in certain calculation cases. The default is - "False". +============================================================================================ +**[DocR]** Data assimilation or optimization calculation cases +============================================================================================ - 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. 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", "OMA", "OMB", "Innovation"]. +This section describes the data assimilation or optimization algorithms +available in ADAO, detailing their usage characteristics and their options. -Reference description for ADAO checking cases ---------------------------------------------- - -List of commands and keywords for an ADAO checking case -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: CHECKING_STUDY -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: CheckingPoint -.. index:: single: Debug -.. index:: single: ObservationOperator -.. index:: single: Study_name -.. index:: single: Study_repertory -.. index:: single: UserDataInit - -The second set of commands is related to the description of a checking case, -that is a procedure to check required properties on information somewhere else -by a calculation case. The terms are ordered in alphabetical order, except the -first, which describes choice between calculation or checking. The different -commands are the following: - -**CHECKING_STUDY** - *Required command*. This is the general command describing the checking - case. It hierarchically contains all the other commands. - -**Algorithm** - *Required command*. This is a string to indicate the test algorithm chosen. - The choices are limited and available through the GUI. There exists for - example "FunctionTest", "AdjointTest"... See below the list of algorithms - and associated parameters in the following subsection `Optional and required - commands for checking algorithms`_. - -**AlgorithmParameters** *Optional command*. This command allows to add some - optional parameters to control the data assimilation or optimization - algorithm. It is defined as a "*Dict*" type object, that is, given as a - script. See below the list of algorithms and associated parameters in the - following subsection `Optional and required commands for checking - algorithms`_. - -**CheckingPoint** - *Required command*. This indicates the vector used as the state around which - to perform the required check, noted :math:`\mathbf{x}` and similar to the - background :math:`\mathbf{x}^b`. It is defined as a "*Vector*" type object. - -**Debug** - *Optional command*. This define the level of trace and intermediary debug - information. The choices are limited between 0 (for False) and 1 (for - True). - -**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`. It is defined as a "*Function*" type object. Different - functional forms can be used, as described in the following subsection - `Requirements for functions describing an operator`_. If there is some - control :math:`U` included in the observation, the operator has to be - applied to a pair :math:`(X,U)`. - -**Observers** - *Optional command*. This command allows to set internal observers, that are - functions linked with a particular variable, which will be executed each - time this variable is modified. It is a convenient way to monitor variables - of interest during the data assimilation or optimization process, by - printing or plotting it, etc. Common templates are provided to help the user - to start or to quickly make his case. - -**Study_name** - *Required command*. This is an open string to describe the study by a name - or a sentence. - -**Study_repertory** - *Optional command*. If available, this directory is used as base name for - calculation, and used to find all the script files, given by name without - path, that can be used to define some other commands by scripts. - -**UserDataInit** - *Optional command*. This commands allows to initialize some parameters or - data automatically before data assimilation algorithm processing. - -Optional and required commands for checking algorithms -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: AdjointTest -.. index:: single: FunctionTest -.. index:: single: GradientTest -.. index:: single: LinearityTest -.. index:: single: ObserverTest -.. index:: single: TangentTest - -.. index:: single: AlgorithmParameters -.. index:: single: AmplitudeOfInitialDirection -.. index:: single: EpsilonMinimumExponent -.. index:: single: InitialDirection -.. index:: single: ResiduFormula -.. index:: single: SetSeed - -We recall that each algorithm can be controlled using some generic or specific -options, given through the "*AlgorithmParameters*" optional command, as follows -for example:: - - AlgorithmParameters = { - "AmplitudeOfInitialDirection" : 1, - "EpsilonMinimumExponent" : -8, - } - -To give the "*AlgorithmParameters*" values by string, one must enclose a -standard dictionary definition between simple quotes, as for example:: - - '{"AmplitudeOfInitialDirection" : 1, "EpsilonMinimumExponent" : -8}' - -If an option is specified by the user for an algorithm that doesn't support it, -the option is simply left unused and don't stop the treatment. The meaning of -the acronyms or particular names can be found in the :ref:`genindex` or the -:ref:`section_glossary`. In addition, for each algorithm, the required -commands/keywords are given, being described in `List of commands and keywords -for an ADAO checking case`_. - -**"AdjointTest"** - - *Required commands* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - This key indicates the scaling of the initial perturbation build as a vector - used for the directional derivative around the nominal checking point. The - default is 1, that means no scaling. - - EpsilonMinimumExponent - This key indicates the minimal exponent value of the power of 10 coefficient - to be used to decrease the increment multiplier. The default is -8, and it - has to be between 0 and -20. For example, its default value leads to - calculate the residue of the formula with a fixed increment multiplied from - 1.e0 to 1.e-8. - - InitialDirection - This key indicates the vector direction used for the directional derivative - around the nominal checking point. It has to be a vector. If not specified, - this direction defaults to a random perturbation around zero of the same - vector size than the checking point. - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - -**"FunctionTest"** - - *Required commands* - *"CheckingPoint", - "ObservationOperator"* - - NumberOfPrintedDigits - This key indicates the number of digits of precision for floating point - printed output. The default is 5, with a minimum of 0. - - NumberOfRepetition - This key indicates the number of time to repeat the function evaluation. The - default is 1. - - SetDebug - This key requires the activation, or not, of the debug mode during the - function evaluation. The default is "True", the choices are "True" or - "False". - -**"GradientTest"** - - *Required commands* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - This key indicates the scaling of the initial perturbation build as a vector - used for the directional derivative around the nominal checking point. The - default is 1, that means no scaling. - - EpsilonMinimumExponent - This key indicates the minimal exponent value of the power of 10 coefficient - to be used to decrease the increment multiplier. The default is -8, and it - has to be between 0 and -20. For example, its default value leads to - calculate the residue of the scalar product formula with a fixed increment - multiplied from 1.e0 to 1.e-8. - - InitialDirection - This key indicates the vector direction used for the directional derivative - around the nominal checking point. It has to be a vector. If not specified, - this direction defaults to a random perturbation around zero of the same - vector size than the checking point. - - ResiduFormula - This key indicates the residue formula that has to be used for the test. The - default choice is "Taylor", and the possible ones are "Taylor" (residue of - the Taylor development of the operator, which has to decrease with the - square power of the perturbation) and "Norm" (residue obtained by taking the - norm of the Taylor development at zero order approximation, which - approximate the gradient, and which has to remain constant). - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - -**"LinearityTest"** - - *Required commands* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - This key indicates the scaling of the initial perturbation build as a vector - used for the directional derivative around the nominal checking point. The - default is 1, that means no scaling. - - EpsilonMinimumExponent - This key indicates the minimal exponent value of the power of 10 coefficient - to be used to decrease the increment multiplier. The default is -8, and it - has to be between 0 and -20. For example, its default value leads to - calculate the residue of the scalar product formula with a fixed increment - multiplied from 1.e0 to 1.e-8. - - InitialDirection - This key indicates the vector direction used for the directional derivative - around the nominal checking point. It has to be a vector. If not specified, - this direction defaults to a random perturbation around zero of the same - vector size than the checking point. - - ResiduFormula - This key indicates the residue formula that has to be used for the test. The - default choice is "CenteredDL", and the possible ones are "CenteredDL" - (residue of the difference between the function at nominal point and the - values with positive and negative increments, which has to stay very small), - "Taylor" (residue of the Taylor development of the operator normalized by - the nominal value, which has to stay very small), "NominalTaylor" (residue - of the order 1 approximations of the operator, normalized to the nominal - point, which has to stay close to 1), and "NominalTaylorRMS" (residue of the - order 1 approximations of the operator, normalized by RMS to the nominal - point, which has to stay close to 0). - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - -**"ObserverTest"** - - *Required commands* - *"Observers"* - - *Tip for this command:* - Because *"CheckingPoint"* and *"ObservationOperator"* are required commands - for ALL checking algorithms in the interface, you have to provide a value - for them, despite the fact that these commands are not required for - *"ObserverTest"*, and will not be used. The easiest way is to give "1" as a - STRING for both, *"ObservationOperator"* having to be of type *Matrix*. - -**"TangentTest"** - - *Required commands* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - This key indicates the scaling of the initial perturbation build as a vector - used for the directional derivative around the nominal checking point. The - default is 1, that means no scaling. - - EpsilonMinimumExponent - This key indicates the minimal exponent value of the power of 10 coefficient - to be used to decrease the increment multiplier. The default is -8, and it - has to be between 0 and -20. For example, its default value leads to - calculate the residue of the scalar product formula with a fixed increment - multiplied from 1.e0 to 1.e-8. - - InitialDirection - This key indicates the vector direction used for the directional derivative - around the nominal checking point. It has to be a vector. If not specified, - this direction defaults to a random perturbation around zero of the same - vector size than the checking point. - - SetSeed - This key allow to give an integer in order to fix the seed of the random - generator used to generate the ensemble. A convenient value is for example - 1000. By default, the seed is left uninitialized, and so use the default - initialization from the computer. - -Requirements for functions describing an operator -------------------------------------------------- - -The operators for observation and evolution are required to implement the data -assimilation or optimization procedures. They include the physical simulation by -numerical calculations, but also the filtering and restriction to compare the -simulation to observation. The evolution operator is considered here in its -incremental form, representing the transition between two successive states, and -is then similar to the observation operator. - -Schematically, an operator has to give a output solution given the input -parameters. Part of the input parameters can be modified during the optimization -procedure. So the mathematical representation of such a process is a function. -It was briefly described in the section :ref:`section_theory` and is generalized -here by the relation: - -.. math:: \mathbf{y} = O( \mathbf{x} ) - -between the pseudo-observations :math:`\mathbf{y}` and the parameters -:math:`\mathbf{x}` using the observation or evolution operator :math:`O`. The -same functional representation can be used for the linear tangent model -:math:`\mathbf{O}` of :math:`O` and its adjoint :math:`\mathbf{O}^*`, also -required by some data assimilation or optimization algorithms. - -On input and output of these operators, the :math:`\mathbf{x}` and -:math:`\mathbf{y}` variables or their increments are mathematically vectors, -and they are given as non-oriented vectors (of type list or Numpy array) or -oriented ones (of type Numpy matrix). - -Then, **to describe completely an operator, the user has only to provide a -function that fully and only realize the functional operation**. - -This function is usually given as a script that can be executed in a YACS node. -This script can without difference launch external codes or use internal SALOME -calls and methods. If the algorithm requires the 3 aspects of the operator -(direct form, tangent form and adjoint form), the user has to give the 3 -functions or to approximate them. - -There are 3 practical methods for the user to provide an operator functional -representation. These methods are chosen in the "*FROM*" field of each operator -having a "*Function*" value as "*INPUT_TYPE*", as shown by the following figure: - - .. eficas_operator_function: - .. image:: images/eficas_operator_function.png - :align: center - :width: 100% - .. centered:: - **Choosing an operator functional representation** - -First functional form: using "*ScriptWithOneFunction*" -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithOneFunction -.. index:: single: DirectOperator -.. index:: single: DifferentialIncrement -.. index:: single: CenteredFiniteDifference - -The first one consist in providing only one potentially non-linear function, and -to approximate the tangent and the adjoint operators. This is done by using the -keyword "*ScriptWithOneFunction*" for the description of the chosen operator in -the ADAO GUI. The user have to provide the function in a script, with a -mandatory name "*DirectOperator*". For example, the script can follow the -template:: - - def DirectOperator( X ): - """ Direct non-linear simulation operator """ - ... - ... - ... - return Y=O(X) - -In this case, the user has also provide a value for the differential increment -(or keep the default value), using through the GUI the keyword -"*DifferentialIncrement*", which has a default value of 1%. This coefficient -will be used in the finite differences approximation to build the tangent and -adjoint operators. The finite differences approximation order can also be chosen -through the GUI, using the keyword "*CenteredFiniteDifference*", with 0 for an -uncentered schema of first order (which is the default value), and with 1 for a -centered schema of second order (of twice the first order computational cost). - -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 implementation. - -**Important warning:** the name "*DirectOperator*" is mandatory, and the type of -the ``X`` argument can be either a list, a numpy array or a numpy 1D-matrix. The -user has to treat these cases in his function. - -Second functional form: using "*ScriptWithFunctions*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithFunctions -.. index:: single: DirectOperator -.. index:: single: TangentOperator -.. index:: single: AdjointOperator - -**In general, it is recommended to use the first functional form rather than -the second one. A small performance improvement is not a good reason to use a -detailed implementation as this second functional form.** - -The second one consist in providing directly the three associated operators -:math:`O`, :math:`\mathbf{O}` and :math:`\mathbf{O}^*`. This is done by using -the keyword "*ScriptWithFunctions*" for the description of the chosen operator -in the ADAO GUI. The user have to provide three functions in one script, with -three mandatory names "*DirectOperator*", "*TangentOperator*" and -"*AdjointOperator*". For example, the script can follow the template:: - - def DirectOperator( X ): - """ Direct non-linear simulation operator """ - ... - ... - ... - return something like Y - - def TangentOperator( (X, dX) ): - """ Tangent linear operator, around X, applied to dX """ - ... - ... - ... - return something like Y - - def AdjointOperator( (X, Y) ): - """ Adjoint operator, around X, applied to Y """ - ... - ... - ... - return something like X - -Another time, this second operator definition allow easily to test the -functional forms before their use in an ADAO case, reducing the complexity of -operator implementation. - -For some algorithms, it is required that the tangent and adjoint functions can -return the matrix equivalent to the linear operator. In this case, when -respectively the ``dX`` or the ``Y`` arguments are ``None``, the user has to -return the associated matrix. - -**Important warning:** the names "*DirectOperator*", "*TangentOperator*" and -"*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX`` -arguments can be either a python list, a numpy array or a numpy 1D-matrix. The -user has to treat these cases in his script. - -Third functional form: using "*ScriptWithSwitch*" -+++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithSwitch -.. index:: single: DirectOperator -.. index:: single: TangentOperator -.. index:: single: AdjointOperator - -**It is recommended not to use this third functional form without a solid -numerical or physical reason. A performance improvement is not a good reason to -use the implementation complexity of this third functional form. Only an -inability to use the first or second forms justifies the use of the third.** - -This third form give more possibilities to control the execution of the three -functions representing the operator, allowing advanced usage and control over -each execution of the simulation code. This is done by using the keyword -"*ScriptWithSwitch*" for the description of the chosen operator in the ADAO GUI. -The user have to provide a switch in one script to control the execution of the -direct, tangent and adjoint forms of its simulation code. The user can then, for -example, use other approximations for the tangent and adjoint codes, or -introduce more complexity in the argument treatment of the functions. But it -will be far more complicated to implement and debug. - -If, however, you want to use this third form, we recommend using the following -template for the switch. It requires an external script or code named here -"*Physical_simulation_functions.py*", containing three functions named -"*DirectOperator*", "*TangentOperator*" and "*AdjointOperator*" as previously. -Here is the switch template:: - - import Physical_simulation_functions - import numpy, logging - # - method = "" - for param in computation["specificParameters"]: - if param["name"] == "method": - method = param["value"] - if method not in ["Direct", "Tangent", "Adjoint"]: - raise ValueError("No valid computation method is given") - logging.info("Found method is \'%s\'"%method) - # - logging.info("Loading operator functions") - Function = Physical_simulation_functions.DirectOperator - Tangent = Physical_simulation_functions.TangentOperator - Adjoint = Physical_simulation_functions.AdjointOperator - # - logging.info("Executing the possible computations") - data = [] - if method == "Direct": - logging.info("Direct computation") - Xcurrent = computation["inputValues"][0][0][0] - data = Function(numpy.matrix( Xcurrent ).T) - if method == "Tangent": - logging.info("Tangent computation") - Xcurrent = computation["inputValues"][0][0][0] - dXcurrent = computation["inputValues"][0][0][1] - data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T) - if method == "Adjoint": - logging.info("Adjoint computation") - Xcurrent = computation["inputValues"][0][0][0] - Ycurrent = computation["inputValues"][0][0][1] - data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T)) - # - logging.info("Formatting the output") - it = numpy.ravel(data) - outputValues = [[[[]]]] - for val in it: - outputValues[0][0][0].append(val) - # - result = {} - result["outputValues"] = outputValues - result["specificOutputInfos"] = [] - result["returnCode"] = 0 - result["errorMessage"] = "" - -All various modifications could be done from this template hypothesis. - -Special case of controled evolution or observation operator -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -In some cases, the evolution or the observation operator is required to be -controlled by an external input control, given *a priori*. In this case, the -generic form of the incremental model is slightly modified as follows: - -.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u}) - -where :math:`\mathbf{u}` is the control over one state increment. In this case, -the direct operator has to be applied to a pair of variables :math:`(X,U)`. -Schematically, the operator has to be set as:: - - def DirectOperator( (X, U) ): - """ Direct non-linear simulation operator """ - ... - ... - ... - return something like X(n+1) (evolution) or Y(n+1) (observation) - -The tangent and adjoint operators have the same signature as previously, noting -that the derivatives has to be done only partially against :math:`\mathbf{x}`. -In such a case with explicit control, only the second functional form (using -"*ScriptWithFunctions*") and third functional form (using "*ScriptWithSwitch*") -can be used. - -Requirements to describe covariance matrices --------------------------------------------- - -Multiple covariance matrices are required to implement the data assimilation or -optimization procedures. The main ones are the background error covariance -matrix, noted as :math:`\mathbf{B}`, and the observation error covariance matrix, -noted as :math:`\mathbf{R}`. Such a matrix is required to be a squared symetric -semi-definite positive matrix. - -There are 3 practical methods for the user to provide a covariance matrix. These -methods are chosen by the "*INPUT_TYPE*" keyword of each defined covariance -matrix, as shown by the following figure: - - .. eficas_covariance_matrix: - .. image:: images/eficas_covariance_matrix.png - :align: center - :width: 100% - .. centered:: - **Choosing covariance matrix representation** - -First matrix form: using "*Matrix*" representation -++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: Matrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError - -This first form is the default and more general one. The covariance matrix -:math:`\mathbf{M}` has to be fully specified. Even if the matrix is symmetric by -nature, the entire :math:`\mathbf{M}` matrix has to be given. - -.. math:: \mathbf{M} = \begin{pmatrix} - m_{11} & m_{12} & \cdots & m_{1n} \\ - m_{21} & m_{22} & \cdots & m_{2n} \\ - \vdots & \vdots & \vdots & \vdots \\ - m_{n1} & \cdots & m_{nn-1} & m_{nn} - \end{pmatrix} - -It can be either a Python Numpy array or a matrix, or a list of lists of values -(that is, a list of rows). For example, a simple diagonal unitary background -error covariance matrix :math:`\mathbf{B}` can be described in a Python script -file as:: - - BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]] - -or:: - - BackgroundError = numpy.eye(...) - -Second matrix form: using "*ScalarSparseMatrix*" representation -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScalarSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError - -On the opposite, this second form is a very simplified method to provide a -matrix. The covariance matrix :math:`\mathbf{M}` is supposed to be a positive -multiple of the identity matrix. This matrix can then be specified in a unique -way by the multiplier :math:`m`: - -.. math:: \mathbf{M} = m \times \begin{pmatrix} - 1 & 0 & \cdots & 0 \\ - 0 & 1 & \cdots & 0 \\ - \vdots & \vdots & \vdots & \vdots \\ - 0 & \cdots & 0 & 1 - \end{pmatrix} - -The multiplier :math:`m` has to be a floating point or integer positive value -(if it is negative, which is impossible for a positive covariance matrix, it is -converted to positive value). For example, a simple diagonal unitary background -error covariance matrix :math:`\mathbf{B}` can be described in a python script -file as:: - - BackgroundError = 1. - -or, better, by a "*String*" directly in the ADAO case. - -Third matrix form: using "*DiagonalSparseMatrix*" representation -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: DiagonalSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError - -This third form is also a simplified method to provide a matrix, but a little -more powerful than the second one. The covariance matrix :math:`\mathbf{M}` is -already supposed to be diagonal, but the user has to specify all the positive -diagonal values. The matrix can then be specified only by a vector -:math:`\mathbf{V}` which will be set on a diagonal matrix: +Some examples on these commands usage are available in the section +:ref:`section_examples` and in the sample files installed with the ADAO module. +The mathematical notations used afterward are explained in the section +:ref:`section_theory`. -.. math:: \mathbf{M} = \begin{pmatrix} - v_{1} & 0 & \cdots & 0 \\ - 0 & v_{2} & \cdots & 0 \\ - \vdots & \vdots & \vdots & \vdots \\ - 0 & \cdots & 0 & v_{n} - \end{pmatrix} +.. toctree:: + :maxdepth: 1 + + ref_assimilation_keywords + ref_algorithm_3DVAR + ref_algorithm_LinearLeastSquares + ref_algorithm_NonLinearLeastSquares + ref_algorithm_Blue + ref_algorithm_ExtendedBlue + ref_algorithm_EnsembleBlue + ref_algorithm_KalmanFilter + ref_algorithm_ExtendedKalmanFilter + ref_algorithm_UnscentedKalmanFilter + ref_algorithm_ParticleSwarmOptimization + ref_algorithm_QuantileRegression + +.. _section_reference_checking: -It can be either a Python Numpy array or a matrix, or a list or a list of list -of positive values (in all cases, if some are negative, which is impossible, -they are converted to positive values). For example, a simple diagonal unitary -background error covariance matrix :math:`\mathbf{B}` can be described in a -python script file as:: +================================================================================ +**[DocR]** Checking cases +================================================================================ - BackgroundError = [1, 1 ... 1] +This section describes the checking algorithms available in ADAO, detailing +their usage characteristics and their options. -or:: +Some examples on these commands usage are available in the section +:ref:`section_examples` and in the sample files installed with the ADAO module. +The mathematical notations used afterward are explained in the section +:ref:`section_theory`. - BackgroundError = numpy.ones(...) +.. toctree:: + :maxdepth: 1 + + ref_checking_keywords + ref_algorithm_AdjointTest + ref_algorithm_FunctionTest + ref_algorithm_GradientTest + ref_algorithm_LinearityTest + ref_algorithm_ObserverTest + ref_algorithm_TangentTest diff --git a/doc/en/theory.rst b/doc/en/theory.rst index 34eba10..ea7dd4a 100644 --- a/doc/en/theory.rst +++ b/doc/en/theory.rst @@ -1,8 +1,31 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_theory: -================================================================================ -A brief introduction to Data Assimilation and Optimization -================================================================================ +================================================================================= +**[DocT]** A brief introduction to Data Assimilation and Optimization +================================================================================= .. index:: single: Data Assimilation .. index:: single: true state diff --git a/doc/en/using.rst b/doc/en/using.rst index 0c8bf5c..9ea6fe6 100644 --- a/doc/en/using.rst +++ b/doc/en/using.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_using: ================================================================================ -Using the ADAO module +**[DocU]** Using the ADAO module ================================================================================ .. |eficas_new| image:: images/eficas_new.png diff --git a/doc/fr/advanced.rst b/doc/fr/advanced.rst index 576e58a..6dffd55 100644 --- a/doc/fr/advanced.rst +++ b/doc/fr/advanced.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_advanced: ================================================================================ -Usages avancés du module ADAO +**[DocU]** Usages avancés du module ADAO ================================================================================ Cette section présente des méthodes avancées d'usage du module ADAO, comment diff --git a/doc/fr/bibliography.rst b/doc/fr/bibliography.rst index 900d0a5..7154dce 100644 --- a/doc/fr/bibliography.rst +++ b/doc/fr/bibliography.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_bibliography: ================================================================================ @@ -10,13 +33,21 @@ Bibliographie .. [Bocquet04] Bocquet M., *Introduction aux principes et méthodes de l'assimilation de données en géophysique*, Lecture Notes, 2004-2008, http://cerea.enpc.fr/HomePages/bocquet/assim.pdf +.. [Buchinsky98] Buchinsky M., *Recent Advances in Quantile Regression Models: A Practical Guidline for Empirical Research*, Journal of Human Resources, 33(1), pp.88-126, 1998 + .. [Byrd95] Byrd R. H., Lu P., Nocedal J., *A Limited Memory Algorithm for Bound Constrained Optimization*, SIAM Journal on Scientific and Statistical Computing, 16(5), pp.1190-1208, 1995 +.. [Cade03] Cade B. S., Noon B. R., *A Gentle Introduction to Quantile Regression for Ecologists*, Frontiers in Ecology and the Environment, 1(8), pp.412-420, 2003 + .. [Ide97] Ide K., Courtier P., Ghil M., Lorenc A. C., *Unified notation for data assimilation: operational, sequential and variational*, Journal of the Meteorological Society of Japan, 75(1B), pp.181-189, 1997 .. [Kalnay03] Kalnay E., *Atmospheric Modeling, Data Assimilation and Predictability*, Cambridge University Press, 2003 -.. [Morales11] Morales J.L., Nocedal J., *L-BFGS-B: Remark on Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, Vol 38(1), 2011 +.. [Koenker00] Koenker R., Hallock K. F., *Quantile Regression: an Introduction*, 2000, available at http://www.econ.uiuc.edu/~roger/research/intro/intro.html + +.. [Koenker01] Koenker R., Hallock K. F., *Quantile Regression*, Journal of Economic Perspectives, 15(4), pp.143-156, 2001 + +.. [Morales11] Morales J.L., Nocedal J., *L-BFGS-B: Remark on Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 38(1), 2011 .. [Salome] *SALOME The Open Source Integration Platform for Numerical Simulation*, http://www.salome-platform.org/ @@ -34,4 +65,6 @@ Bibliographie .. [WikipediaQR] Wikipedia, *Quantile regression*, https://en.wikipedia.org/wiki/Quantile_regression -.. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, Vol 23(4), pp.550-560, 1997 +.. [WikipediaUKF] Wikipedia, *Unscented Kalman filter*, https://en.wikipedia.org/wiki/Unscented_Kalman_filter + +.. [Zhu97] Zhu C., Byrd R. H., Nocedal J., *L-BFGS-B: Algorithm 778: L-BFGS-B, FORTRAN routines for large scale bound constrained optimization*, ACM Transactions on Mathematical Software, 23(4), pp.550-560, 1997 diff --git a/doc/fr/examples.rst b/doc/fr/examples.rst index 9f37d4e..38bde56 100644 --- a/doc/fr/examples.rst +++ b/doc/fr/examples.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_examples: ================================================================================ -Tutoriaux sur l'utilisation du module ADAO +**[DocU]** Tutoriaux sur l'utilisation du module ADAO ================================================================================ .. |eficas_new| image:: images/eficas_new.png diff --git a/doc/fr/glossary.rst b/doc/fr/glossary.rst index 3bfeba7..caaaf32 100644 --- a/doc/fr/glossary.rst +++ b/doc/fr/glossary.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_glossary: Glossaire diff --git a/doc/fr/index.rst b/doc/fr/index.rst index 29a35c0..45b5913 100644 --- a/doc/fr/index.rst +++ b/doc/fr/index.rst @@ -1,3 +1,28 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_home: + ================================================================================ Documentation ADAO ================================================================================ @@ -25,7 +50,7 @@ La documentation de ce module est divis une :ref:`section_intro`. La seconde partie présente :ref:`section_theory`, et à leurs concepts. La troisième partie explique comment :ref:`section_using`. La quatrième partie présente des exemples d'utilisation sous la forme de -:ref:`section_examples`. La cinquième partie détaille la +:ref:`section_examples`. La cinquième partie détaille la :ref:`section_reference`. Les utilisateurs intéressés par un accès rapide au module peuvent s'arrêter avant la lecture de cette partie, mais un usage utile du module nécessite de lire et de revenir régulièrement aux troisième et @@ -53,8 +78,8 @@ Table des mati theory using examples - reference advanced + reference license glossary bibliography diff --git a/doc/fr/intro.rst b/doc/fr/intro.rst index 9995c75..71d30bb 100644 --- a/doc/fr/intro.rst +++ b/doc/fr/intro.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_intro: ================================================================================ diff --git a/doc/fr/license.rst b/doc/fr/license.rst index 2fcf9b7..d48a55b 100644 --- a/doc/fr/license.rst +++ b/doc/fr/license.rst @@ -1,3 +1,26 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_license: ================================================================================ diff --git a/doc/fr/ref_algorithm_3DVAR.rst b/doc/fr/ref_algorithm_3DVAR.rst new file mode 100644 index 0000000..4b17494 --- /dev/null +++ b/doc/fr/ref_algorithm_3DVAR.rst @@ -0,0 +1,175 @@ +.. + Copyright (C) 2008-2014 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: 3DVAR +.. _section_ref_algorithm_3DVAR: + +Algorithme de calcul "*3DVAR*" +------------------------------ + +Description ++++++++++++ + +Cet algorithme réalise une estimation d'état par minimisation variationnelle de +la fonctionnelle :math:`J` d'écart classique en assimilation de données +statique: + +.. math:: J(\mathbf{x})=(\mathbf{x}-\mathbf{x}^b)^T.\mathbf{B}^{-1}.(\mathbf{x}-\mathbf{x}^b)+(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) + +qui est usuellement désignée comme la fonctionnelle "*3D-VAR*" (voir par exemple +[Talagrand97]_). + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Minimizer +.. index:: single: Bounds +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` 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. + + 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. + + 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. + + 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. + + 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. + + 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. + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", + "Innovation", "SigmaObs2", "MahalanobisConsistency"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_LinearityTest` + +Références bibliographiques : + - [Byrd95]_ + - [Morales11]_ + - [Talagrand97]_ diff --git a/doc/fr/ref_algorithm_AdjointTest.rst b/doc/fr/ref_algorithm_AdjointTest.rst new file mode 100644 index 0000000..8b7b586 --- /dev/null +++ b/doc/fr/ref_algorithm_AdjointTest.rst @@ -0,0 +1,117 @@ +.. + Copyright (C) 2008-2014 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: AdjointTest +.. _section_ref_algorithm_AdjointTest: + +Algorithme de vérification "*AdjointTest*" +------------------------------------------ + +Description ++++++++++++ + +Cet algorithme permet de vérifier la qualité de l'opérateur adjoint, en +calculant un résidu dont les propriétés théoriques sont connues. + +On observe le résidu suivant, qui est la différence de deux produits scalaires : + +.. math:: R(\alpha) = | < TangentF_x(\mathbf{dx}) , \mathbf{y} > - < \mathbf{dx} , AdjointF_x(\mathbf{y}) > | + +qui doit rester constamment égal à zéro à la précision du calcul. On prend +:math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul. +:math:`\mathbf{y}` doit être dans l'image de :math:`F`. S'il n'est pas donné, on +prend :math:`\mathbf{y} = F(\mathbf{x})`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: SetSeed + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, notée + 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*". 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_checking_keywords`. En particulier, la +commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + AmplitudeOfInitialDirection + Cette clé indique la mise à l'échelle de la perturbation initiale construite + comme un vecteur utilisé pour la dérivée directionnelle autour du point + nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas + de mise à l'échelle. + + EpsilonMinimumExponent + Cette clé indique la valeur de l'exposant minimal du coefficient en + puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur + de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et + -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la + formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. + + InitialDirection + Cette clé indique la direction vectorielle utilisée pour la dérivée + directionnelle autour du point nominal de vérification. Cela doit être un + vecteur. Si elle n'est pas spécifiée, la direction par défaut est une + perturbation par défaut autour de zéro de la même taille vectorielle que le + point de vérification. + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation par défaut de l'ordinateur. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_TangentTest` + - :ref:`section_ref_algorithm_GradientTest` diff --git a/doc/fr/ref_algorithm_Blue.rst b/doc/fr/ref_algorithm_Blue.rst new file mode 100644 index 0000000..96537dc --- /dev/null +++ b/doc/fr/ref_algorithm_Blue.rst @@ -0,0 +1,127 @@ +.. + Copyright (C) 2008-2014 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: Blue +.. _section_ref_algorithm_Blue: + +Algorithme de calcul "*Blue*" +----------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de type BLUE (Best Linear Unbiased +Estimator) de l'état d'un système. De manière précise, c'est un estimateur +d'Aitken. + +Cet algorithme est toujours le plus rapide de l'ensemble des algorithmes +d'assimilation d'ADAO. Il est théoriquement réservé aux cas d'opérateurs +d'observation 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 aisément +l':ref:`section_ref_algorithm_ExtendedBlue` ou +l':ref:`section_ref_algorithm_3DVAR`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", + "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` + +Références bibliographiques : + - [Bouttier99]_ diff --git a/doc/fr/ref_algorithm_EnsembleBlue.rst b/doc/fr/ref_algorithm_EnsembleBlue.rst new file mode 100644 index 0000000..282b017 --- /dev/null +++ b/doc/fr/ref_algorithm_EnsembleBlue.rst @@ -0,0 +1,109 @@ +.. + Copyright (C) 2008-2014 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: EnsembleBlue +.. _section_ref_algorithm_EnsembleBlue: + +Algorithme de calcul "*EnsembleBlue*" +------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de type BLUE (Best Linear Unbiased +Estimator, qui est ici un estimateur d'Aitken) de l'état d'un système par +méthode d'ensemble. Pour fonctionner, il faut fournir un ensemble d'ébauches, +dont le nombre déterminera la taille de l'ensemble pour l'estimation. + +Il est théoriquement réservé aux cas d'opérateurs d'observation linéaires, mais +doit fonctionner aussi 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`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: SetSeed + +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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation de l'ordinateur. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_Blue` diff --git a/doc/fr/ref_algorithm_ExtendedBlue.rst b/doc/fr/ref_algorithm_ExtendedBlue.rst new file mode 100644 index 0000000..93ffc6d --- /dev/null +++ b/doc/fr/ref_algorithm_ExtendedBlue.rst @@ -0,0 +1,121 @@ +.. + Copyright (C) 2008-2014 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: ExtendedBlue +.. _section_ref_algorithm_ExtendedBlue: + +Algorithme de calcul "*ExtendedBlue*" +------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de type BLUE étendu (Best Linear Unbiased +Estimator, étendu) de l'état d'un système. + +Cet algorithme est une généralisation partiellement non-linéaire de +l':ref:`section_ref_algorithm_Blue`. Il lui est équivalent pour un opérateur +d'observation 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 non-linéaire, il se rapproche de l':ref:`section_ref_algorithm_3DVAR`, sans +lui être entièrement équivalent. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", + "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst new file mode 100644 index 0000000..bd89b92 --- /dev/null +++ b/doc/fr/ref_algorithm_ExtendedKalmanFilter.rst @@ -0,0 +1,131 @@ +.. + Copyright (C) 2008-2014 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: ExtendedKalmanFilter +.. _section_ref_algorithm_ExtendedKalmanFilter: + +Algorithme de calcul "*ExtendedKalmanFilter*" +--------------------------------------------- + +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). + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. 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: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + 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 extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas + une valeur autorisée lorsqu'il n'y a pas de borne). + + ConstrainedBy + Cette clé permet de définir la méthode pour prendre en compte les bornes. Les + méthodes possibles sont dans la liste suivante : ["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 + paramètres, avec la valeur "Parameters". Le choix par défaut est "State". + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` diff --git a/doc/fr/ref_algorithm_FunctionTest.rst b/doc/fr/ref_algorithm_FunctionTest.rst new file mode 100644 index 0000000..0e838f2 --- /dev/null +++ b/doc/fr/ref_algorithm_FunctionTest.rst @@ -0,0 +1,100 @@ +.. + Copyright (C) 2008-2014 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: FunctionTest +.. _section_ref_algorithm_FunctionTest: + +Algorithme de vérification "*FunctionTest*" +------------------------------------------- + +Description ++++++++++++ + +Cet algorithme permet de vérifier que l'opérateur d'observation fonctionne +correctement et que son appel se déroule de manière compatible avec son usage +dans les algorithmes d'ADAO. De manière pratique, il permet d'appeler une ou +plusieurs fois l'opérateur, en activant ou non le mode "debug" lors de +l'exécution. + +Une statistique sur les vecteurs en entrée et en sortie de chaque exécution de +l'opérateur est indiquée, et une autre globale est fournie de manière +récapitulative à la fin de l'algorithme de vérification. La précision +d'affichage est contrôlable pour permettre l'automatisation des tests +d'opérateur. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: NumberOfPrintedDigits +.. index:: single: NumberOfRepetition +.. index:: single: SetDebug + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, notée + 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*". 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_checking_keywords`. En particulier, la +commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + NumberOfPrintedDigits + Cette clé indique le nombre de décimales de précision pour les affichages de + valeurs réelles. La valeur par défaut est 5, avec un minimum de 0. + + NumberOfRepetition + Cette clé indique le nombre de fois où répéter l'évaluation de la fonction. + La valeur par défaut est 1. + + SetDebug + Cette clé requiert l'activation, ou pas, du mode de débogage durant + l'évaluation de la fonction. La valeur par défaut est "True", les choix sont + "True" ou "False". + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/fr/ref_algorithm_GradientTest.rst b/doc/fr/ref_algorithm_GradientTest.rst new file mode 100644 index 0000000..a353da0 --- /dev/null +++ b/doc/fr/ref_algorithm_GradientTest.rst @@ -0,0 +1,147 @@ +.. + Copyright (C) 2008-2014 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: GradientTest +.. _section_ref_algorithm_GradientTest: + +Algorithme de vérification "*GradientTest*" +------------------------------------------- + +Description ++++++++++++ + +Cet algorithme permet de vérifier la qualité du gradient de l'opérateur, en +calculant un résidu dont les propriétés théoriques sont connues. Plusieurs +formules de résidu sont disponibles. + +Dans tous les cas, on prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul. + +Résidu "Taylor" +*************** + +On observe le résidu issu du développement de Taylor de la fonction :math:`F`, +normalisée par la valeur au point nominal : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} + +Si le résidu décroit et que la décroissance se fait en :math:`\alpha^2` selon +:math:`\alpha`, cela signifie que le gradient est bien calculé jusqu'à la +précision d'arrêt de la décroissance quadratique et que :math:`F` n'est pas +linéaire. + +Si le résidu décroit et que la décroissance se fait en :math:`\alpha` selon +:math:`\alpha`, jusqu'à un certain seuil après lequel le résidu est faible et +constant, cela signifie que :math:`F` est linéaire et que le résidu décroit à +partir de l'erreur faite dans le calcul du terme :math:`\nabla_xF`. + +Résidu "Norm" +************* + +On observe le résidu, qui est basé sur une approximation du gradient : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{\alpha} + +qui doit rester constant jusqu'à ce que l'on atteigne la précision du calcul. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: ResiduFormula +.. index:: single: SetSeed + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, notée + 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*". 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_checking_keywords`. En particulier, la +commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + AmplitudeOfInitialDirection + Cette clé indique la mise à l'échelle de la perturbation initiale construite + comme un vecteur utilisé pour la dérivée directionnelle autour du point + nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas + de mise à l'échelle. + + EpsilonMinimumExponent + Cette clé indique la valeur de l'exposant minimal du coefficient en + puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur + de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et + -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la + formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. + + InitialDirection + Cette clé indique la direction vectorielle utilisée pour la dérivée + directionnelle autour du point nominal de vérification. Cela doit être un + vecteur. Si elle n'est pas spécifiée, la direction par défaut est une + perturbation par défaut autour de zéro de la même taille vectorielle que le + point de vérification. + + ResiduFormula + Cette clé indique la formule de résidu qui doit être utilisée pour le test. + Le choix par défaut est "Taylor", et les choix possibles sont "Taylor" + (résidu du développement de Taylor de l'opérateur, qui doit décroître comme + le carré de la perturbation) et "Norm" (résidu obtenu en prenant la norme du + développement de Taylor à l'ordre 0, qui approxime le gradient, et qui doit + rester constant). + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation par défaut de l'ordinateur. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_TangentTest` + - :ref:`section_ref_algorithm_AdjointTest` diff --git a/doc/fr/ref_algorithm_KalmanFilter.rst b/doc/fr/ref_algorithm_KalmanFilter.rst new file mode 100644 index 0000000..b4c4e49 --- /dev/null +++ b/doc/fr/ref_algorithm_KalmanFilter.rst @@ -0,0 +1,126 @@ +.. + Copyright (C) 2008-2014 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: KalmanFilter +.. _section_ref_algorithm_KalmanFilter: + +Algorithme de calcul "*KalmanFilter*" +------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de l'état d'un système dynamique par un +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`. + +En cas de non-linéarité, même peu marquée, on lui préférera +l':ref:`section_ref_algorithm_ExtendedKalmanFilter` ou +l':ref:`section_ref_algorithm_UnscentedKalmanFilter`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: EstimationOf +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + 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". + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + - :ref:`section_ref_algorithm_UnscentedKalmanFilter` diff --git a/doc/fr/ref_algorithm_LinearLeastSquares.rst b/doc/fr/ref_algorithm_LinearLeastSquares.rst new file mode 100644 index 0000000..9ffd510 --- /dev/null +++ b/doc/fr/ref_algorithm_LinearLeastSquares.rst @@ -0,0 +1,120 @@ +.. + Copyright (C) 2008-2014 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: LinearLeastSquares +.. _section_ref_algorithm_LinearLeastSquares: + +Algorithme de calcul "*LinearLeastSquares*" +------------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation linéaire de type "Moindres Carrés" +pondérés. Il est similaire à l':ref:`section_ref_algorithm_Blue` +amputé de sa partie ébauche. + +Cet algorithme est toujours le plus rapide de l'ensemble des algorithmes +d'optimisation d'ADAO. Il est théoriquement réservé aux cas d'opérateurs +d'observation 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`. + +Dans tous les cas, il est recommandé de lui préférer au minimum +l':ref:`section_ref_algorithm_Blue`, voire +l':ref:`section_ref_algorithm_ExtendedBlue` ou +l':ref:`section_ref_algorithm_3DVAR`. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: StoreInternalVariables +.. index:: single: StoreSupplementaryCalculations + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["OMA"]. + +*Astuce pour cet algorithme :* + + Comme les commandes *"Background"* et *"BackgroundError"* sont requises pour + TOUS les algorithmes de calcul dans l'interface, vous devez fournir une + valeur, malgré le fait que ces commandes ne sont pas requises pour + cet algorithme, et ne seront pas utilisées. La manière la plus simple est + de donner "1" comme un STRING pour les deux. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_Blue` + - :ref:`section_ref_algorithm_ExtendedBlue` + - :ref:`section_ref_algorithm_3DVAR` + - :ref:`section_ref_algorithm_LinearityTest` diff --git a/doc/fr/ref_algorithm_LinearityTest.rst b/doc/fr/ref_algorithm_LinearityTest.rst new file mode 100644 index 0000000..e18cb23 --- /dev/null +++ b/doc/fr/ref_algorithm_LinearityTest.rst @@ -0,0 +1,194 @@ +.. + Copyright (C) 2008-2014 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: LinearityTest +.. _section_ref_algorithm_LinearityTest: + +Algorithme de vérification "*LinearityTest*" +-------------------------------------------- + +Description ++++++++++++ + +Cet algorithme permet de vérifier la qualité de linéarité de l'opérateur, en +calculant un résidu dont les propriétés théoriques sont connues. Plusieurs +formules de résidu sont utilisables. + +Dans tous les cas, on prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul. + +Résidu "CenteredDL" +******************* + +On observe le résidu suivant, provenant de la différence centrée des valeurs de +:math:`F` au point nominal et aux points perturbés, normalisée par la valeur au +point nominal : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) + F(\mathbf{x}-\alpha*\mathbf{dx}) - 2*F(\mathbf{x}) ||}{|| F(\mathbf{x}) ||} + +S'il reste constamment très faible par rapport à 1, l'hypothèse de linéarité +de :math:`F` est vérifiée. + +Si le résidu varie, ou qu'il est de l'ordre de 1 ou plus, et qu'il n'est +faible qu'à partir d'un certain ordre d'incrément, l'hypothèse de linéarité +de :math:`F` n'est pas vérifiée. + +Si le résidu décroit et que la décroissance se fait en :math:`\alpha^2` selon +:math:`\alpha`, cela signifie que le gradient est bien calculé jusqu'au niveau +d'arrêt de la décroissance quadratique. + +Résidu "Taylor" +*************** + +On observe le résidu issu du développement de Taylor de la fonction :math:`F`, +normalisée par la valeur au point nominal : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) - \alpha * \nabla_xF(\mathbf{dx}) ||}{|| F(\mathbf{x}) ||} + +S'il reste constamment trés faible par rapport à 1, l'hypothèse de linéarité +de :math:`F` est vérifiée. + +Si le résidu varie, ou qu'il est de l'ordre de 1 ou plus, et qu'il n'est +faible qu'à partir d'un certain ordre d'incrément, l'hypothèse de linéarité +de :math:`F` n'est pas vérifiée. + +Si le résidu décroit et que la décroissance se fait en :math:`\alpha^2` selon +:math:`\alpha`, cela signifie que le gradient est bien calculé jusqu'au niveau +d'arrêt de la décroissance quadratique. + +Résidu "NominalTaylor" +********************** + +On observe le résidu obtenu à partir de deux approximations d'ordre 1 de +:math:`F(\mathbf{x})`, normalisées par la valeur au point nominal : + +.. math:: R(\alpha) = \max(|| F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||,|| F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) || / || F(\mathbf{x}) ||) + +S'il reste constamment égal à 1 à moins de 2 ou 3 pourcents prés (c'est-à-dire +que :math:`|R-1|` reste égal à 2 ou 3 pourcents), c'est que l'hypothèse de +linéarité de :math:`F` est vérifiée. + +S'il est égal à 1 sur une partie seulement du domaine de variation de +l'incrément :math:`\alpha`, c'est sur sous-domaine que l'hypothèse de linéarité +de :math:`F` est vérifiée. + +Résidu "NominalTaylorRMS" +************************* + +On observe le résidu obtenu à partir de deux approximations d'ordre 1 de +:math:`F(\mathbf{x})`, normalisées par la valeur au point nominal, dont on +calcule l'écart quadratique (RMS) avec la valeur au point nominal : + +.. math:: R(\alpha) = \max(RMS( F(\mathbf{x}), F(\mathbf{x}+\alpha*\mathbf{dx}) - \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||,RMS( F(\mathbf{x}), F(\mathbf{x}-\alpha*\mathbf{dx}) + \alpha * F(\mathbf{dx}) ) / || F(\mathbf{x}) ||) + +S'il reste constamment égal à 0 à moins de 1 ou 2 pourcents prés, c'est +que l'hypothèse de linéarité de F est vérifiée. + +S'il est égal à 0 sur une partie seulement du domaine de variation de +l'incrément :math:`\alpha`, c'est sur cette partie que l'hypothèse de linéarité +de F est vérifiée. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: ResiduFormula +.. index:: single: SetSeed + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, notée + 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*". 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_checking_keywords`. En particulier, la +commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + AmplitudeOfInitialDirection + Cette clé indique la mise à l'échelle de la perturbation initiale construite + comme un vecteur utilisé pour la dérivée directionnelle autour du point + nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas + de mise à l'échelle. + + EpsilonMinimumExponent + Cette clé indique la valeur de l'exposant minimal du coefficient en + puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur + de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et + -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la + formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. + + InitialDirection + Cette clé indique la direction vectorielle utilisée pour la dérivée + directionnelle autour du point nominal de vérification. Cela doit être un + vecteur. Si elle n'est pas spécifiée, la direction par défaut est une + perturbation par défaut autour de zéro de la même taille vectorielle que le + point de vérification. + + ResiduFormula + Cette clé indique la formule de résidu qui doit être utilisée pour le test. + Le choix par défaut est "CenteredDL", et les choix possibles sont + "CenteredDL" (résidu de la différence entre la fonction au point nominal et + ses valeurs avec des incréments positif et négatif, qui doit rester très + faible), "Taylor" (résidu du développement de Taylor de l'opérateur + normalisé par sa valeur nominal, qui doit rester très faible), + "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur, + normalisé au point nominal, qui doit rester proche de 1), et + "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur, + normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit + rester proche de 0). + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation par défaut de l'ordinateur. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_FunctionTest` diff --git a/doc/fr/ref_algorithm_NonLinearLeastSquares.rst b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst new file mode 100644 index 0000000..bb87078 --- /dev/null +++ b/doc/fr/ref_algorithm_NonLinearLeastSquares.rst @@ -0,0 +1,177 @@ +.. + Copyright (C) 2008-2014 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: NonLinearLeastSquares +.. _section_ref_algorithm_NonLinearLeastSquares: + +Algorithme de calcul "*NonLinearLeastSquares*" +---------------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation d'état par minimisation variationnelle de +la fonctionnelle :math:`J` d'écart classique de "Moindres Carrés" pondérés: + +.. math:: J(\mathbf{x})=(\mathbf{y}^o-\mathbf{H}.\mathbf{x})^T.\mathbf{R}^{-1}.(\mathbf{y}^o-\mathbf{H}.\mathbf{x}) + +Il est similaire à l':ref:`section_ref_algorithm_3DVAR` amputé de sa partie +ébauche. L'ébauche, requise dans l'interface, ne sert que de point initial pour +la minimisation variationnelle. + +Dans tous les cas, il est recommandé de lui préférer +l':ref:`section_ref_algorithm_3DVAR` pour sa stabilité comme pour son +comportement lors de l'optimisation. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Minimizer +.. index:: single: Bounds +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: ProjectedGradientTolerance +.. index:: single: GradientNormTolerance +.. index:: single: StoreInternalVariables +.. 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*". + + 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` 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), "LM" + (minimisation non linéaire de type Levenberg-Marquard). Il est fortement + conseillé de conserver la valeur par défaut. + + 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. + + 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. + + 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. + + 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. + + 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. + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", + "Innovation", "SigmaObs2", "MahalanobisConsistency"]. + +*Astuce pour cet algorithme :* + + Comme la commande *"BackgroundError"* est requise pour TOUS les algorithmes + de calcul dans l'interface, vous devez fournir une valeur, malgré le fait + que cette commande n'est pas requise pour cet algorithme, et ne sera pas + utilisée. La manière la plus simple est de donner "1" comme un STRING. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_3DVAR` + +Références bibliographiques : + - [Byrd95]_ + - [Morales11]_ diff --git a/doc/fr/ref_algorithm_ObserverTest.rst b/doc/fr/ref_algorithm_ObserverTest.rst new file mode 100644 index 0000000..5ff94cf --- /dev/null +++ b/doc/fr/ref_algorithm_ObserverTest.rst @@ -0,0 +1,68 @@ +.. + Copyright (C) 2008-2014 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: ObserverTest +.. _section_ref_algorithm_ObserverTest: + +Algorithme de vérification "*ObserverTest*" +------------------------------------------- + +Description ++++++++++++ + +Cet algorithme permet de vérifier une fonction externe et fournie par +l'utilisateur, utilisée comme un *observer*. Cette fonction externe peut être +appliquée à chacune des variables potentiellement observables. Elle n'est +activée que sur celles qui sont explicitement associées avec l'*observer* dans +l'interface. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: Observers + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + Observers + *Commande obligatoire*. Elle permet de définir des observateurs internes, + qui sont des fonctions liées à une variable particulière, qui sont exécutées + chaque fois que cette variable est modifiée. C'est une manière pratique de + suivre des variables d'intérêt durant le processus d'assimilation de données + ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples + courants (squelettes) sont fournis pour aider l'utilisateur ou pour + faciliter l'élaboration d'un cas. + +Les commandes optionnelles générales, disponibles dans l'interface en édition, +sont indiquées dans la :ref:`section_ref_checking_keywords`. + +*Astuce pour cet algorithme :* + + Comme les commandes *"CheckingPoint"* et *"ObservationOperator"* sont + requises pour TOUS les algorithmes de vérification dans l'interface, vous + devez fournir une valeur, malgré le fait que ces commandes ne sont pas + requises pour *"ObserverTest"*, et ne seront pas utilisées. La manière la + plus simple est de donner "1" comme un STRING pour les deux, + l'*"ObservationOperator"* devant être de type *Matrix*. diff --git a/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst new file mode 100644 index 0000000..22aacdf --- /dev/null +++ b/doc/fr/ref_algorithm_ParticleSwarmOptimization.rst @@ -0,0 +1,163 @@ +.. + Copyright (C) 2008-2014 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: ParticleSwarmOptimization +.. _section_ref_algorithm_ParticleSwarmOptimization: + +Algorithme de calcul "*ParticleSwarmOptimization*" +-------------------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de l'état d'un système dynamique par un +essaim particulaire. + +C'est une méthode d'optimisation permettant la recherche du minimum global d'une +fonctionnelle quelconque de type :math:`L^1`, :math:`L^2` ou :math:`L^{\infty}`, +avec ou sans pondérations. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: MaximumNumberOfSteps +.. index:: single: NumberOfInsects +.. index:: single: SwarmVelocity +.. index:: single: GroupRecallRate +.. index:: single: QualityCriterion +.. index:: single: BoxBounds +.. index:: single: SetSeed +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + MaximumNumberOfSteps + Cette clé indique le nombre maximum d'itérations possibles en optimisation + itérative. Le défaut est 50, qui est une limite arbitraire. Il est ainsi + recommandé d'adapter ce paramètre aux besoins pour des problèmes réels. + + NumberOfInsects + Cette clé indique le nombre d'insectes ou de particules dans l'essaim. La + valeur par défaut est 100, qui est une valeur par défaut usuelle pour cet + algorithme. + + SwarmVelocity + Cette clé indique la part de la vitesse d'insecte qui est imposée par + l'essaim. C'est une valeur réelle positive. Le défaut est de 1. + + GroupRecallRate + Cette clé indique le taux de rappel vers le meilleur insecte de l'essaim. + C'est une valeur réelle comprise entre 0 et 1. Le défaut est de 0.5. + + QualityCriterion + Cette clé indique le critère de qualité, qui est minimisé pour trouver + l'estimation optimale de l'état. Le défaut est le critère usuel de + l'assimilation de données nommé "DA", qui est le critère de moindres carrés + pondérés augmentés. Les critères possibles sont dans la liste suivante, dans + laquelle les noms équivalents sont indiqués par un signe "=" : + ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS", + "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"] + + BoxBounds + Cette clé permet de définir des bornes supérieure et inférieure pour chaque + incrément de variable d'état optimisée (et non pas chaque variable d'état + elle-même). Les bornes doivent être données par une liste de liste de paires + de bornes inférieure/supérieure pour chaque incrément de variable, avec une + valeur extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas une + valeur autorisée lorsqu'il n'y a pas de borne). Cette clé est requise et il + n'y a pas de valeurs par défaut. + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation par défaut de l'ordinateur. + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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", "OMA", "OMB", "Innovation"]. + +Voir aussi +++++++++++ + +Références bibliographiques : + - [WikipediaPSO]_ diff --git a/doc/fr/ref_algorithm_QuantileRegression.rst b/doc/fr/ref_algorithm_QuantileRegression.rst new file mode 100644 index 0000000..1be544f --- /dev/null +++ b/doc/fr/ref_algorithm_QuantileRegression.rst @@ -0,0 +1,130 @@ +.. + Copyright (C) 2008-2014 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: QuantileRegression +.. _section_ref_algorithm_QuantileRegression: + +Algorithme de calcul "*QuantileRegression*" +------------------------------------------- + +Description ++++++++++++ + +Cet algorithme permet d'estimer les quantiles conditionnels de la distribution +des paramètres d'état, exprimés à l'aide d'un modèle des variables observées. Ce +sont donc les quantiles sur les variables observées qui vont permettre de +déterminer les paramètres de modèles satisfaisant aux conditions de quantiles. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: Background +.. index:: single: Observation +.. index:: single: ObservationOperator +.. index:: single: Quantile +.. index:: single: Minimizer +.. index:: single: MaximumNumberOfSteps +.. index:: single: CostDecrementTolerance +.. index:: single: StoreInternalVariables +.. 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*". + + 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*". + + 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + Quantile + Cette clé permet de définir la valeur réelle du quantile recherché, entre 0 + et 1. La valeur par défaut est 0.5, correspondant à la médiane. + + 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. + + 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-6, et il est recommandé de + l'adapter aux besoins pour des problèmes réels. + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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", "OMA", "OMB", "Innovation"]. + +*Astuce pour cet algorithme :* + + Comme les commandes *"BackgroundError"* et *"ObservationError"* sont + requises pour TOUS les algorithmes de calcul dans l'interface, vous devez + fournir une valeur, malgré le fait que ces commandes ne sont pas requises + pour cet algorithme, et ne seront pas utilisées. La manière la plus simple + est de donner "1" comme un STRING pour les deux. + +Voir aussi +++++++++++ + +Références bibliographiques : + - [Buchinsky98]_ + - [Cade03]_ + - [Koenker00]_ + - [Koenker01]_ + - [WikipediaQR]_ diff --git a/doc/fr/ref_algorithm_TangentTest.rst b/doc/fr/ref_algorithm_TangentTest.rst new file mode 100644 index 0000000..5a5c3ef --- /dev/null +++ b/doc/fr/ref_algorithm_TangentTest.rst @@ -0,0 +1,127 @@ +.. + Copyright (C) 2008-2014 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: TangentTest +.. _section_ref_algorithm_TangentTest: + +Algorithme de vérification "*TangentTest*" +------------------------------------------ + +Description ++++++++++++ + +Cet algorithme permet de vérifier la qualité de l'opérateur tangent, en +calculant un résidu dont les propriétés théoriques sont connues. + +On observe le résidu suivant, provenant du rapport d'incréments utilisant +l'opérateur linéaire tangent : + +.. math:: R(\alpha) = \frac{|| F(\mathbf{x}+\alpha*\mathbf{dx}) - F(\mathbf{x}) ||}{|| \alpha * TangentF_x * \mathbf{dx} ||} + +qui doit rester stable en :math:`1+O(\alpha)` jusqu'à ce que l'on atteigne la +précision du calcul. + +Lorsque :math:`|R-1|/\alpha` est inférieur ou égal à une valeur stable lorsque +:math:`\alpha` varie, le tangent est valide, jusqu'à ce que l'on atteigne la +précision du calcul. + +Si :math:`|R-1|/\alpha` est très faible, le code de calcul :math:`F` est +vraisemblablement linéaire ou quasi-linéaire (ce que l'on peut vérifier par +l':ref:`section_ref_algorithm_LinearityTest`), et le tangent est valide jusqu'à +ce que l'on atteigne la précision du calcul. + +On prend :math:`\mathbf{dx}_0=Normal(0,\mathbf{x})` et +:math:`\mathbf{dx}=\alpha*\mathbf{dx}_0`. :math:`F` est le code de calcul. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. index:: single: CheckingPoint +.. index:: single: ObservationOperator +.. index:: single: AmplitudeOfInitialDirection +.. index:: single: EpsilonMinimumExponent +.. index:: single: InitialDirection +.. index:: single: SetSeed + +Les commandes requises générales, disponibles dans l'interface en édition, sont +les suivantes: + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + ObservationOperator + *Commande obligatoire*. Elle indique l'opérateur d'observation, notée + 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*". 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_checking_keywords`. En particulier, la +commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + AmplitudeOfInitialDirection + Cette clé indique la mise à l'échelle de la perturbation initiale construite + comme un vecteur utilisé pour la dérivée directionnelle autour du point + nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas + de mise à l'échelle. + + EpsilonMinimumExponent + Cette clé indique la valeur de l'exposant minimal du coefficient en + puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur + de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et + -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la + formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. + + InitialDirection + Cette clé indique la direction vectorielle utilisée pour la dérivée + directionnelle autour du point nominal de vérification. Cela doit être un + vecteur. Si elle n'est pas spécifiée, la direction par défaut est une + perturbation par défaut autour de zéro de la même taille vectorielle que le + point de vérification. + + SetSeed + Cette clé permet de donner un nombre entier pour fixer la graine du + générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est + par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle + utilise ainsi l'initialisation par défaut de l'ordinateur. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_FunctionTest` + - :ref:`section_ref_algorithm_AdjointTest` + - :ref:`section_ref_algorithm_GradientTest` diff --git a/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst new file mode 100644 index 0000000..a3b3b1b --- /dev/null +++ b/doc/fr/ref_algorithm_UnscentedKalmanFilter.rst @@ -0,0 +1,147 @@ +.. + Copyright (C) 2008-2014 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: UnscentedKalmanFilter +.. _section_ref_algorithm_UnscentedKalmanFilter: + +Algorithme de calcul "*UnscentedKalmanFilter*" +---------------------------------------------- + +Description ++++++++++++ + +Cet algorithme réalise une estimation de l'état d'un système dynamique par un +filtre de Kalman "unscented", permettant d'éviter de devoir calculer les +opérateurs tangent ou adjoint pour les opérateurs d'observation ou d'évolution, +comme dans les filtres de Kalman simple ou étendu. + +Commandes requises et optionnelles +++++++++++++++++++++++++++++++++++ + +.. 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: Alpha +.. index:: single: Beta +.. index:: single: Kappa +.. index:: single: Reconditioner +.. index:: single: StoreInternalVariables +.. 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`. En particulier, +la commande optionnelle "*AlgorithmParameters*" permet d'indiquer les options +particulières, décrites ci-après, de l'algorithme. On se reportera à la +:ref:`section_ref_options_AlgorithmParameters` pour le bon usage de cette +commande. + +Les options de l'algorithme sont les suivantes: + + 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 extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas + une valeur autorisée lorsqu'il n'y a pas de borne). + + ConstrainedBy + Cette clé permet de définir la méthode pour prendre en compte les bornes. Les + méthodes possibles sont dans la liste suivante : ["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 + paramètres, avec la valeur "Parameters". Le choix par défaut est "State". + + Alpha, Beta, Kappa, Reconditioner + Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert + une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour + une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière, + dont la bonne valeur par défaut est obtenue en la mettant à 0. + "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut + étant 1. + + StoreInternalVariables + Cette clé booléenne permet de stocker les variables internes par défaut, + principalement l'état courant lors d'un processus itératif. Attention, cela + peut être un choix numériquement coûteux dans certains cas de calculs. La + valeur par défaut est "False". + + StoreSupplementaryCalculations + Cette liste indique les noms des variables supplémentaires qui peuvent être + disponibles à la fin de l'algorithme. Cela implique potentiellement des + calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. + +Voir aussi +++++++++++ + +Références vers d'autres sections : + - :ref:`section_ref_algorithm_KalmanFilter` + - :ref:`section_ref_algorithm_ExtendedKalmanFilter` + +Références bibliographiques : + - [WikipediaUKF]_ diff --git a/doc/fr/ref_assimilation_keywords.rst b/doc/fr/ref_assimilation_keywords.rst new file mode 100644 index 0000000..3589e52 --- /dev/null +++ b/doc/fr/ref_assimilation_keywords.rst @@ -0,0 +1,184 @@ +.. + Copyright (C) 2008-2014 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: ASSIMILATION_STUDY +.. _section_ref_assimilation_keywords: + +Liste des commandes et mots-clés pour un cas d'assimilation de données ou d'optimisation +---------------------------------------------------------------------------------------- + +.. index:: single: Algorithm +.. index:: single: AlgorithmParameters +.. index:: single: Background +.. index:: single: BackgroundError +.. index:: single: ControlInput +.. index:: single: Debug +.. index:: single: EvolutionError +.. index:: single: EvolutionModel +.. index:: single: InputVariables +.. index:: single: Observation +.. index:: single: ObservationError +.. index:: single: ObservationOperator +.. index:: single: Observer +.. index:: single: Observers +.. index:: single: Observer Template +.. index:: single: OutputVariables +.. index:: single: Study_name +.. index:: single: Study_repertory +.. index:: single: UserDataInit +.. index:: single: UserPostAnalysis +.. index:: single: UserPostAnalysis Template + +Ce jeu de commandes est lié à la description d'un cas de calcul, qui est une +procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes sont +classés par ordre alphabétique, sauf le premier, qui décrit le choix entre le +calcul ou la vérification. + +Les différentes commandes sont les suivantes: + + **ASSIMILATION_STUDY** + *Commande obligatoire*. C'est la commande générale qui décrit le cas + d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement + toutes les autres commandes. + + Algorithm + *Commande obligatoire*. C'est une chaîne de caractère qui indique + l'algorithme d'assimilation de données ou d'optimisation choisi. Les choix + sont limités et disponibles à travers l'interface graphique. Il existe par + exemple le "3DVAR", le "Blue"... Voir plus loin la liste des algorithmes et + des paramètres associés, chacun décrit par une sous-section. + + AlgorithmParameters + *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour + contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa + valeur est définie comme un objet de type "*Dict*". Voir la + :ref:`section_ref_options_AlgorithmParameters` pour l'usage correct de cette + commande. + + 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*". + + 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*". + + ControlInput + *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour + forcer le modèle d'évolution à chaque pas, usuellement noté + :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*" + ou de type "*VectorSerie*". Lorsqu'il n'y a pas de contrôle, sa valeur doit + être une chaîne vide ''. + + Debug + *Commande optionnelle*. Elle définit le niveau de sorties et d'informations + intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et + 1 (pour True). + + EvolutionError + *Commande optionnelle*. Elle définit la matrice de covariance des erreurs + d'évolution, usuellement notée :math:`\mathbf{Q}`. Sa valeur est définie + comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de + type "*DiagonalSparseMatrix*". + + EvolutionModel + *Commande optionnelle*. Elle indique l'opérateur d'évolution du modèle, + usuellement noté :math:`M`, qui décrit un pas élémentaire d'évolution. 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'évolution, l'opérateur doit être appliqué à une + paire :math:`(X,U)`. + + InputVariables + *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des + variables physiques qui sont rassemblées dans le vecteur d'état. Cette + information est destinée à être utilisée dans le traitement algorithmique + interne des données. + + 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)`. + + Observers + *Commande optionnelle*. Elle permet de définir des observateurs internes, + qui sont des fonctions liées à une variable particulière, qui sont exécutées + chaque fois que cette variable est modifiée. C'est une manière pratique de + suivre des variables d'intérêt durant le processus d'assimilation de données + ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples + courants (squelettes) sont fournis pour aider l'utilisateur ou pour + faciliter l'élaboration d'un cas. + + OutputVariables + *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des + variables physiques qui sont rassemblées dans le vecteur d'observation. + Cette information est destinée à être utilisée dans le traitement + algorithmique interne des données. + + Study_name + *Commande obligatoire*. C'est une chaîne de caractères quelconque pour + décrire l'étude ADAO par un nom ou une déclaration. + + Study_repertory + *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base + pour les calculs, et il est utilisé pour trouver les fichiers de script, + donnés par nom sans répertoire, qui peuvent être utilisés pour définir + certaines variables. + + UserDataInit + *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou + certaines données automatiquement avant le traitement de données d'entrée + pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un + nom de fichier de script à exécuter avant d'entrer dans l'initialisation des + variables choisies. + + UserPostAnalysis + *Commande optionnelle*. Elle permet de traiter des paramètres ou des + résultats après le déroulement de l'algorithme d'assimilation de données ou + d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne + de caractères, permettant de produire directement du code de post-processing + dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider + l'utilisateur ou pour faciliter l'élaboration d'un cas. diff --git a/doc/fr/ref_checking_keywords.rst b/doc/fr/ref_checking_keywords.rst new file mode 100644 index 0000000..06fda97 --- /dev/null +++ b/doc/fr/ref_checking_keywords.rst @@ -0,0 +1,113 @@ +.. + Copyright (C) 2008-2014 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: CHECKING_STUDY +.. _section_ref_checking_keywords: + +Liste des commandes et mots-clés pour un cas de vérification +------------------------------------------------------------ + +.. index:: single: Algorithm +.. index:: single: AlgorithmParameters +.. index:: single: CheckingPoint +.. index:: single: Debug +.. index:: single: ObservationOperator +.. index:: single: Observer +.. index:: single: Observers +.. index:: single: Observer Template +.. index:: single: Study_name +.. index:: single: Study_repertory +.. index:: single: UserDataInit + +Ce jeu de commandes est lié à la description d'un cas de vérification, qui est +une procédure pour vérifier les propriétés d'une information requise, utilisée +ailleurs par un cas de calcul. Les termes sont classés par ordre alphabétique, +sauf le premier, qui décrit le choix entre le calcul ou la vérification. + +Les différentes commandes sont les suivantes: + + **CHECKING_STUDY** + *Commande obligatoire*. C'est la commande générale qui décrit le cas de + vérification. Elle contient hiérarchiquement toutes les autres commandes. + + Algorithm + *Commande obligatoire*. C'est une chaîne de caractère qui indique + l'algorithme de test choisi. Les choix sont limités et disponibles à travers + l'interface graphique. Il existe par exemple "FunctionTest", + "AdjointTest"... Voir plus loin la liste des algorithmes et des paramètres + associés, chacun décrit par une sous-section. + + AlgorithmParameters + *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour + contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa + valeur est définie comme un objet de type "*Dict*". Voir la + :ref:`section_ref_options_AlgorithmParameters` pour l'usage correct de cette + commande. + + CheckingPoint + *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour + duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à + l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type + "*Vector*". + + Debug + *Commande optionnelle*. Elle définit le niveau de sorties et d'informations + intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et + 1 (pour True). + + 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)`. + + Observers + *Commande optionnelle*. Elle permet de définir des observateurs internes, + qui sont des fonctions liées à une variable particulière, qui sont exécutées + chaque fois que cette variable est modifiée. C'est une manière pratique de + suivre des variables d'intérêt durant le processus d'assimilation de données + ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples + courants (squelettes) sont fournis pour aider l'utilisateur ou pour + faciliter l'élaboration d'un cas. + + Study_name + *Commande obligatoire*. C'est une chaîne de caractères quelconque pour + décrire l'étude ADAO par un nom ou une déclaration. + + Study_repertory + *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base + pour les calculs, et il est utilisé pour trouver les fichiers de script, + donnés par nom sans répertoire, qui peuvent être utilisés pour définir + certaines variables. + + UserDataInit + *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou + certaines données automatiquement avant le traitement de données d'entrée + pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un + nom de fichier de script à exécuter avant d'entrer dans l'initialisation des + variables choisies. diff --git a/doc/fr/ref_covariance_requirements.rst b/doc/fr/ref_covariance_requirements.rst new file mode 100644 index 0000000..cafd48e --- /dev/null +++ b/doc/fr/ref_covariance_requirements.rst @@ -0,0 +1,140 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_covariance_requirements: + +Exigences pour décrire les matrices de covariance +------------------------------------------------- + +De multiples matrices de covariance sont nécessaires pour mettre en oeuvre des +procédures d'assimilation de données ou d'optimisation. Les principales sont la +matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la +matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`. Une +telle matrice doit être une matrice carré symétrique semi-définie positive. + +Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de +covariance. Ces méthodes sont choisies à l'aide du mot-clé "*INPUT_TYPE*" de +chaque matrice de covariance, comme montré dans la figure qui suit : + + .. eficas_covariance_matrix: + .. image:: images/eficas_covariance_matrix.png + :align: center + :width: 100% + .. centered:: + **Choisir la représentation d'une matrice de covariance** + +Première forme matricielle : utiliser la représentation "*Matrix*" +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: Matrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +La première forme est le défaut et la plus générale. La matrice de covariance +:math:`\mathbf{M}` doit être entièrement spécifiée. Même si la matrice est +symétrique par nature, la totalité de la matrice :math:`\mathbf{M}` doit être +donnée. + +.. math:: \mathbf{M} = \begin{pmatrix} + m_{11} & m_{12} & \cdots & m_{1n} \\ + m_{21} & m_{22} & \cdots & m_{2n} \\ + \vdots & \vdots & \vdots & \vdots \\ + m_{n1} & \cdots & m_{nn-1} & m_{nn} + \end{pmatrix} + +Cela peut être réalisé soit par un vecteur ou une matrice Numpy, soit par une +liste de listes de valeurs (c'est-à-dire une liste de lignes). Par exemple, une +matrice simple diagonale unitaire de covariances des erreurs d'ébauche +:math:`\mathbf{B}` peut être décrite dans un fichier de script Python par:: + + BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]] + +ou:: + + BackgroundError = numpy.eye(...) + +Seconde forme matricielle : utiliser la représentation "*ScalarSparseMatrix*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScalarSparseMatrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +Au contraire, la seconde forme matricielle est une méthode très simplifiée pour +définir une matrice. La matrice de covariance :math:`\mathbf{M}` est supposée +être un multiple positif de la matrice identité. Cette matrice peut alors être +spécifiée de manière unique par le multiplicateur :math:`m`: + +.. math:: \mathbf{M} = m \times \begin{pmatrix} + 1 & 0 & \cdots & 0 \\ + 0 & 1 & \cdots & 0 \\ + \vdots & \vdots & \vdots & \vdots \\ + 0 & \cdots & 0 & 1 + \end{pmatrix} + +Le multiplicateur :math:`m` doit être un nombre réel ou entier positif (s'il +est négatif, ce qui est impossible car une matrice de covariance est positive, +il est convertit en nombre positif). Par exemple, une simple matrice diagonale +unitaire de covariances des erreurs d'ébauche :math:`\mathbf{B}` peut être +décrite dans un fichier de script Python par:: + + BackgroundError = 1. + +ou, mieux, par un "*String*" directement dans le cas ADAO. + +Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: DiagonalSparseMatrix +.. index:: single: BackgroundError +.. index:: single: EvolutionError +.. index:: single: ObservationError + +La troisième forme est aussi une méthode simplifiée pour fournir la matrice, +mais un peu plus puissante que la seconde. La matrice de covariance +:math:`\mathbf{M}` est toujours considérée comme diagonale, mais l'utilisateur +doit spécifier toutes les valeurs positives situées sur la diagonale. La matrice +peut alors être définie uniquement par un vecteur :math:`\mathbf{V}` qui se +retrouve ensuite sur la diagonale: + +.. math:: \mathbf{M} = \begin{pmatrix} + v_{1} & 0 & \cdots & 0 \\ + 0 & v_{2} & \cdots & 0 \\ + \vdots & \vdots & \vdots & \vdots \\ + 0 & \cdots & 0 & v_{n} + \end{pmatrix} + +Cela peut être réalisé soit par vecteur ou une matrice Numpy, soit par +une liste, soit par une liste de listes de valeurs positives (dans tous les cas, +si certaines valeurs sont négatives, elles sont converties en valeurs +positives). Par exemple, un matrice simple diagonale unitaire des covariances +des erreurs d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de +script Python par:: + + BackgroundError = [1, 1 ... 1] + +ou:: + + BackgroundError = numpy.ones(...) diff --git a/doc/fr/ref_entry_types.rst b/doc/fr/ref_entry_types.rst new file mode 100644 index 0000000..20affed --- /dev/null +++ b/doc/fr/ref_entry_types.rst @@ -0,0 +1,102 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_entry_types: + +Liste des types d'entrées possibles +----------------------------------- + +Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la +valider. Les différents pseudo-types sont: + +.. index:: single: Dict + +**Dict** + Cela indique une variable qui doit être remplie avec un dictionnaire Python + ``{"clé":"valeur"...}``, usuellement donné soit par une chaîne de caractères + soit par un fichier script. + +.. index:: single: Function + +**Function** + Cela indique une variable qui doit être donnée comme une fonction Python, + usuellement donnée soit par une chaîne de caractères soit par un fichier + script. + +.. index:: single: Matrix + +**Matrix** + Cela indique une variable qui doit être donnée comme une matrice, + usuellement donnée soit par une chaîne de caractères soit par un fichier + script. + +.. index:: single: ScalarSparseMatrix + +**ScalarSparseMatrix** + Cela indique une variable qui doit être donnée comme un nombre unique (qui + sera utilisé pour multiplier une matrice identité), usuellement donné soit + par une chaîne de caractères soit par un fichier script. + +.. index:: single: DiagonalSparseMatrix + +**DiagonalSparseMatrix** + Cela indique une variable qui doit , (qui sera + utilisé pour remplacer la diagonale d'une matrice identité), usuellement + donné soit par une chaîne de caractères soit par un fichier script. + +.. index:: single: Script + +**Script** + Cela indique un script donné comme un fichier externe. Il peut être désigné + par un nom de fichier avec chemin complet ou seulement par un nom de fichier + sans le chemin. Si le fichier est donné uniquement par un nom sans chemin, + et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans + le répertoire d'étude donné. + +.. index:: single: String + +**String** + Cela indique une chaîne de caractères fournissant une représentation + littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme + par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille + 2x2. + +.. index:: single: Vector + +**Vector** + Cela indique une variable qui doit être remplie comme un vecteur, + usuellement donné soit par une chaîne de caractères soit par un fichier + script. + +.. index:: single: VectorSerie + +**VectorSerie** + Cela indique une variable qui doit être remplie comme une liste de vecteurs, + usuellement donnée soit par une chaîne de caractères soit par un fichier + script. + +Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script, +ce script doit présenter une variable ou une méthode que porte le même nom que +la variable à remplir. En d'autres mots, lorsque l'on importe le script dans un +noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de +nommage courant du noeud. diff --git a/doc/fr/ref_operator_requirements.rst b/doc/fr/ref_operator_requirements.rst new file mode 100644 index 0000000..a533fbe --- /dev/null +++ b/doc/fr/ref_operator_requirements.rst @@ -0,0 +1,278 @@ +.. + Copyright (C) 2008-2014 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 + +.. _section_ref_operator_requirements: + +Exigences pour les fonctions décrivant un opérateur +--------------------------------------------------- + +Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en +oeuvre les procédures d'assimilation de données ou d'optimisation. Ils +comprennent la simulation physique par des calculs numériques, mais aussi le +filtrage et de restriction pour comparer la simulation à l'observation. +L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui +représente la transition entre deux états successifs, et il est alors similaire +à l'opérateur d'observation. + +Schématiquement, un opérateur doit donner une solution étant donné les +paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au +cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un +tel processus est une fonction. Il a été brièvement décrit dans la section +:ref:`section_theory` et il est généralisée ici par la relation: + +.. math:: \mathbf{y} = O( \mathbf{x} ) + +entre les pseudo-observations :math:`\mathbf{y}` et les paramètres +:math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution +:math:`O`. La même représentation fonctionnelle peut être utilisée pour le +modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint +:math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes +d'assimilation de données ou d'optimisation. + +En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et +:math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et +ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur +Numpy) ou orientés (de type matrice Numpy). + +Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à +fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière +complète**. + +Cette fonction est généralement donnée comme un script qui peut être exécuté +dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes +externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme +nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme +adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer. + +Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation +fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*" +de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le +montre la figure suivante: + + .. eficas_operator_function: + .. image:: images/eficas_operator_function.png + :align: center + :width: 100% + .. centered:: + **Choisir une représentation fonctionnelle de l'opérateur** + +Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithOneFunction +.. index:: single: DirectOperator +.. index:: single: DifferentialIncrement +.. index:: single: CenteredFiniteDifference + +La première consiste à ne fournir qu'une seule fonction potentiellement non +linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en +utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de +l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir +la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par +exemple, le script peut suivre le modèle suivant:: + + def DirectOperator( X ): + """ Opérateur direct de simulation non-linéaire """ + ... + ... + ... + return Y=O(X) + +Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément +différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface +graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par +défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies +pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation +différences finies peut aussi être choisi à travers l'interface, en utilisant le +mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du +premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du +second ordre (qui coûte numériquement deux fois plus cher que le premier ordre). + +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 +complexité de l'implémentation de l'opérateur. + +**Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le +type de l'argument X peut être une liste, un vecteur ou une matrice Numpy. +L'utilisateur doit traiter ces cas dans sa fonction. + +Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*" +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithFunctions +.. index:: single: DirectOperator +.. index:: single: TangentOperator +.. index:: single: AdjointOperator + +**En général, il est recommandé d'utiliser la première forme fonctionnelle +plutôt que la seconde. Un petit accroissement de performances n'est pas une +bonne raison pour utiliser l'implémentation détaillée de cette seconde forme +fonctionnelle.** + +La seconde consiste à fournir directement les trois opérateurs liés :math:`O`, +:math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le +mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans +l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions +dans un script, avec trois noms obligatoires "*DirectOperator*", +"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre +le squelette suivant:: + + def DirectOperator( X ): + """ Opérateur direct de simulation non-linéaire """ + ... + ... + ... + return quelque chose comme Y + + def TangentOperator( (X, dX) ): + """ Opérateur linéaire tangent, autour de X, appliqué à dX """ + ... + ... + ... + return quelque chose comme Y + + def AdjointOperator( (X, Y) ): + """ Opérateur adjoint, autour de X, appliqué à Y """ + ... + ... + ... + return quelque chose comme X + +Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester +les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la +complexité de l'implémentation de l'opérateur. + +Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse +renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque, +respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur +doit renvoyer la matrice associée. + +**Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*" +et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``, +``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy. +L'utilisateur doit traiter ces cas dans ses fonctions. + +Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. index:: single: ScriptWithSwitch +.. index:: single: DirectOperator +.. index:: single: TangentOperator +.. index:: single: AdjointOperator + +**Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans +une solide raison numérique ou physique. Un accroissement de performances n'est +pas une bonne raison pour utiliser la complexité de cette troisième forme +fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes +justifie l'usage de la troisième.** + +La troisième forme donne de plus grandes possibilités de contrôle de l'exécution +des trois fonctions représentant l'opérateur, permettant un usage et un contrôle +avancés sur chaque exécution du code de simulation. C'est réalisable en +utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à +travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script +unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente +et adjointe du code de simulation. L'utilisateur peut alors, par exemple, +utiliser des approximations pour les codes tangent et adjoint, ou introduire une +plus grande complexité du traitement des arguments des fonctions. Mais cette +démarche sera plus difficile à implémenter et à déboguer. + +Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se +baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier +script ou un code externe nommé ici "*Physical_simulation_functions.py*", +contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" and +"*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage:: + + import Physical_simulation_functions + import numpy, logging + # + method = "" + for param in computation["specificParameters"]: + if param["name"] == "method": + method = param["value"] + if method not in ["Direct", "Tangent", "Adjoint"]: + raise ValueError("No valid computation method is given") + logging.info("Found method is \'%s\'"%method) + # + logging.info("Loading operator functions") + Function = Physical_simulation_functions.DirectOperator + Tangent = Physical_simulation_functions.TangentOperator + Adjoint = Physical_simulation_functions.AdjointOperator + # + logging.info("Executing the possible computations") + data = [] + if method == "Direct": + logging.info("Direct computation") + Xcurrent = computation["inputValues"][0][0][0] + data = Function(numpy.matrix( Xcurrent ).T) + if method == "Tangent": + logging.info("Tangent computation") + Xcurrent = computation["inputValues"][0][0][0] + dXcurrent = computation["inputValues"][0][0][1] + data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T) + if method == "Adjoint": + logging.info("Adjoint computation") + Xcurrent = computation["inputValues"][0][0][0] + Ycurrent = computation["inputValues"][0][0][1] + data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T)) + # + logging.info("Formatting the output") + it = numpy.ravel(data) + outputValues = [[[[]]]] + for val in it: + outputValues[0][0][0].append(val) + # + result = {} + result["outputValues"] = outputValues + result["specificOutputInfos"] = [] + result["returnCode"] = 0 + result["errorMessage"] = "" + +Toutes les modifications envisageables peuvent être faites à partir de cette +hypothèse de squelette. + +Cas spécial d'un opérateur d'évolution avec contrôle +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé +par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la +forme générique du modèle incrémental est légèrement modifié comme suit: + +.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u}) + +où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. Dans ce cas, +l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`. +Schématiquement, l'opérateur doit être constuit comme suit:: + + def DirectOperator( (X, U) ): + """ Opérateur direct de simulation non-linéaire """ + ... + ... + ... + return quelque chose comme X(n+1) (évolution) ou Y(n+1) (observation) + +Les opérateurs tangent et adjoint ont la même signature que précédemment, en +notant que les dérivées doivent être faites seulement partiellement par rapport +à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième +forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme +fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées. diff --git a/doc/fr/ref_options_AlgorithmParameters.rst b/doc/fr/ref_options_AlgorithmParameters.rst new file mode 100644 index 0000000..2ca0e14 --- /dev/null +++ b/doc/fr/ref_options_AlgorithmParameters.rst @@ -0,0 +1,50 @@ +.. + Copyright (C) 2008-2014 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: AlgorithmParameters +.. _section_ref_options_AlgorithmParameters: + +Description des options d'un algorithme par "*AlgorithmParameters*" +------------------------------------------------------------------- + +Chaque algorithme peut être contrôlé en utilisant des options particulières, +données à travers la commande optionnelle "*AlgorithmParameters*", à la manière +de l'exemple qui suit, dans un fichier Python:: + + AlgorithmParameters = { + "StoreInternalVariables" : True, + "MaximumNumberOfSteps" : 25, + "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], + } + +Pour donner les valeurs de la commande "*AlgorithmParameters*" par une chaîne de +caractères, directement dans l'interface EFICAS, on doit utiliser des guillemets +simples pour fournir une définition standard de dictionnaire, comme par +exemple:: + + '{"StoreInternalVariables":True,"MaximumNumberOfSteps":25}' + +Si une option est spécifiée par l'utilisateur pour un algorithme qui ne la +supporte pas, cette option est simplement laissée inutilisée et ne bloque pas le +traitement. La signification des acronymes ou des noms particuliers peut être +trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`. diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index bbd5b12..db138c8 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -1,11 +1,38 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_reference: ================================================================================ -Description de référence des commandes et mots-clés ADAO +**[DocR]** Description de référence des commandes et mots-clés ADAO ================================================================================ -Cette section présente la description de référence des commandes et mots-clés -ADAO disponibles à travers l'interface graphique (GUI) ou à travers des scripts. +Les sections suivantes présentent la description de référence des commandes et +mots-clés ADAO disponibles à travers l'interface graphique (GUI) ou à travers +des scripts. Une première section commune présente de manière générale les +:ref:`section_reference_entry`. Ensuite, on décrit successivement les +:ref:`section_reference_assimilation` et les :ref:`section_reference_checking`. + Chaque commande ou mot-clé à définir par l'interface graphique (GUI) a des propriétés particulières. La première propriété est d'être *requise*, *optionnelle* ou simplement utile, décrivant un type d'entrée. La seconde @@ -15,1388 +42,77 @@ n'importe quelle valeur autoris intrinsèques de validation, les propriétés des commandes ou mots-clés données à l'aide de l'interface graphique sont automatiquement correctes. -Les notations mathématiques utilisées ci-dessous sont expliquées dans la section -:ref:`section_theory`. - -Des exemples sur l'usage de ces commandes sont disponibles dans la section -:ref:`section_examples` et dans les fichiers d'exemple installés avec le module -ADAO. - -Liste des types d'entrées possibles ------------------------------------ - -.. index:: single: Dict -.. index:: single: Function -.. index:: single: Matrix -.. index:: single: ScalarSparseMatrix -.. index:: single: DiagonalSparseMatrix -.. index:: single: String -.. index:: single: Script -.. index:: single: Vector - -Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la -valider. Les différents pseudo-types sont: - -**Dict** - Cela indique une variable qui doit être remplie avec un dictionnaire Python - ``{"clé":"valeur"...}``, usuellement donné soit par une chaîne de caractères - soit par un fichier script. - -**Function** - Cela indique une variable qui doit être donnée comme une fonction Python, - usuellement donnée soit par une chaîne de caractères soit par un fichier - script. - -**Matrix** - Cela indique une variable qui doit être donnée comme une matrice, - usuellement donnée soit par une chaîne de caractères soit par un fichier - script. - -**ScalarSparseMatrix** - Cela indique une variable qui doit être donnée comme un nombre unique (qui - sera utilisé pour multiplier une matrice identité), usuellement donné soit - par une chaîne de caractères soit par un fichier script. - -**DiagonalSparseMatrix** - Cela indique une variable qui doit , (qui sera - utilisé pour remplacer la diagonale d'une matrice identité), usuellement - donné soit par une chaîne de caractères soit par un fichier script. - -**Script** - Cela indique un script donné comme un fichier externe. Il peut être désigné - par un nom de fichier avec chemin complet ou seulement par un nom de fichier - sans le chemin. Si le fichier est donné uniquement par un nom sans chemin, - et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans - le répertoire d'étude donné. - -**String** - Cela indique une chaîne de caractères fournissant une représentation - littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme - par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille - 2x2. - -**Vector** - Cela indique une variable qui doit être remplie comme un vecteur, - usuellement donné soit par une chaîne de caractères soit par un fichier - script. - -**VectorSerie** - Cela indique une variable qui doit être remplie comme une liste de vecteurs, - usuellement donnée soit par une chaîne de caractères soit par un fichier - script. - -Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script, -ce script doit présenter une variable ou une méthode que porte le même nom que -la variable à remplir. En d'autres mots, lorsque l'on importe le script dans un -noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de -nommage courant du noeud. - -Description de référence pour les cas de calcul ADAO ----------------------------------------------------- - -Liste des commandes et mots-clés pour un cas de calcul ADAO -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ASSIMILATION_STUDY -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: Background -.. index:: single: BackgroundError -.. index:: single: ControlInput -.. index:: single: Debug -.. index:: single: EvolutionError -.. index:: single: EvolutionModel -.. index:: single: InputVariables -.. index:: single: Observation -.. index:: single: ObservationError -.. index:: single: ObservationOperator -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: OutputVariables -.. index:: single: Study_name -.. index:: single: Study_repertory -.. index:: single: UserDataInit -.. index:: single: UserPostAnalysis -.. index:: single: UserPostAnalysis Template - -La première série de commandes est liée à la description d'un cas de calcul, qui -est une procédure d'*Assimilation de Données* ou d'*Optimisation*. Les termes -sont classés par ordre alphabétique, sauf le premier, qui décrit le choix entre -le calcul ou la vérification. Les différentes commandes sont les suivantes: - -**ASSIMILATION_STUDY** - *Commande obligatoire*. C'est la commande générale qui décrit le cas - d'assimilation de données ou d'optimisation. Elle contient hiérarchiquement - toutes les autres commandes. - -**Algorithm** - *Commande obligatoire*. C'est une chaîne de caractère qui indique l'algorithme - d'assimilation de données ou d'optimisation choisi. Les choix sont limités - et disponibles à travers l'interface graphique. Il existe par exemple le - "3DVAR", le "Blue"... Voir plus loin la liste des algorithmes et des - paramètres associés dans la sous-section `Commandes optionnelles et requises - pour les algorithmes de calcul`_. - -**AlgorithmParameters** - *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour - contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa - valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste - des algorithmes et des paramètres associés dans la sous-section `Commandes - optionnelles et requises pour les algorithmes de calcul`_. - -**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*". - -**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*". - -**ControlInput** - *Commande optionnelle*. Elle indique le vecteur de contrôle utilisé pour - forcer le modèle d'évolution à chaque pas, usuellement noté - :math:`\mathbf{U}`. Sa valeur est définie comme un objet de type "*Vector*" - ou de type *VectorSerie*. Lorsqu'il n'y a pas de contrôle, sa valeur doit - être une chaîne vide ''. - -**Debug** - *Commande optionnelle*. Elle définit le niveau de sorties et d'informations - intermédiaires de débogage. Les choix sont limités entre 0 (pour False) and - 1 (pour True). - -**EvolutionError** - *Commande optionnelle*. Elle définit la matrice de covariance des erreurs - d'évolution, usuellement notée :math:`\mathbf{Q}`. Sa valeur est définie - comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de - type "*DiagonalSparseMatrix*". - -**EvolutionModel** - *Commande optionnelle*. Elle indique l'opérateur d'évolution du modèle, - usuellement noté :math:`M`, qui décrit un pas élémentaire d'évolution. 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 sous-section - suivante `Exigences pour les fonctions décrivant un opérateur`_. Si un - contrôle :math:`U` est inclus dans le modèle d'évolution, l'opérateur doit - être appliqué à une paire :math:`(X,U)`. - -**InputVariables** - *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des - variables physiques qui sont rassemblées dans le vecteur d'état. Cette - information est destinée à être utilisée dans le traitement algorithmique - interne des données. - -**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ée - 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 sous-section suivante `Exigences pour les fonctions décrivant un - opérateur`_. 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)`. - -**Observers** - *Commande optionnelle*. Elle permet de définir des observateurs internes, - qui sont des fonctions liées à une variable particulière, qui sont exécutées - chaque fois que cette variable est modifiée. C'est une manière pratique de - suivre des variables d'intérêt durant le processus d'assimilation de données - ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples - courants (squelettes) sont fournis pour aider l'utilisateur ou pour - faciliter l'élaboration d'un cas. - -**OutputVariables** - *Commande optionnelle*. Elle permet d'indiquer le nom et la taille des - variables physiques qui sont rassemblées dans le vecteur d'observation. - Cette information est destinée à être utilisée dans le traitement - algorithmique interne des données. - -**Study_name** - *Commande obligatoire*. C'est une chaîne de caractères quelconque pour - décrire l'étude ADAO par un nom ou une déclaration. - -**Study_repertory** - *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base - pour les calculs, et il est utilisé pour trouver les fichiers de script, - donnés par nom sans répertoire, qui peuvent être utilisés pour définir - certaines variables. - -**UserDataInit** - *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou - certaines données automatiquement avant le traitement de données d'entrée - pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un - nom de fichier de script à exécuter avant d'entrer dans l'initialisation des - variables choisies. - -**UserPostAnalysis** - *Commande optionnelle*. Elle permet de traiter des paramètres ou des - résultats après le déroulement de l'algorithme d'assimilation de données ou - d'optimisation. Sa valeur est définie comme un fichier script ou une chaîne - de caractères, permettant de produire directement du code de post-processing - dans un cas ADAO. Des exemples courants (squelettes) sont fournis pour aider - l'utilisateur ou pour faciliter l'élaboration d'un cas. - -Commandes optionnelles et requises pour les algorithmes de calcul -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: 3DVAR -.. index:: single: Blue -.. index:: single: ExtendedBlue -.. index:: single: EnsembleBlue -.. index:: single: KalmanFilter -.. index:: single: ExtendedKalmanFilter -.. index:: single: UnscentedKalmanFilter -.. index:: single: LinearLeastSquares -.. index:: single: NonLinearLeastSquares -.. index:: single: ParticleSwarmOptimization -.. index:: single: QuantileRegression - -.. index:: single: AlgorithmParameters -.. index:: single: Bounds -.. index:: single: CostDecrementTolerance -.. index:: single: GradientNormTolerance -.. index:: single: GroupRecallRate -.. index:: single: MaximumNumberOfSteps -.. index:: single: Minimizer -.. index:: single: NumberOfInsects -.. index:: single: ProjectedGradientTolerance -.. index:: single: QualityCriterion -.. index:: single: Quantile -.. index:: single: SetSeed -.. index:: single: StoreInternalVariables -.. index:: single: StoreSupplementaryCalculations -.. index:: single: SwarmVelocity - -Chaque algorithme peut être contrôlé en utilisant des options génériques ou -particulières, données à travers la commande optionnelle "*AlgorithmParameters*" -dans un fichier script ou une chaîne de caractères, à la manière de l'exemple -qui suit dans un fichier:: - - AlgorithmParameters = { - "Minimizer" : "LBFGSB", - "MaximumNumberOfSteps" : 25, - "StoreSupplementaryCalculations" : ["APosterioriCovariance","OMA"], - } - -Pour donner les valeurs de la commande "*AlgorithmParameters*" par une chaîne de -caractères, on doit utiliser des guillemets simples pour fournir une définition -standard de dictionnaire, comme par exemple:: - - '{"Minimizer":"LBFGSB","MaximumNumberOfSteps":25}' - -Cette section décrit les options disponibles algorithme par algorithme. De plus, -pour chaque algorithme, les commandes/mots-clés obligatoires sont indiqués. Si -une option est spécifiée par l'utilisateur pour un algorithme qui ne la supporte -pas, cette option est simplement laissée inutilisée et ne bloque pas le -traitement. La signification des acronymes ou des noms particuliers peut être -trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`. - -**"Blue"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", - "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. - -**"ExtendedBlue"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", - "Innovation", "SigmaBck2", "SigmaObs2", "MahalanobisConsistency"]. - -**"LinearLeastSquares"** - - *Commandes obligatoires* - *"Observation", "ObservationError", - "ObservationOperator"* - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["OMA"]. - -**"3DVAR"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", - "Innovation", "SigmaObs2", "MahalanobisConsistency"]. - -**"NonLinearLeastSquares"** - - *Commandes obligatoires* - *"Background", - "Observation", "ObservationError", - "ObservationOperator"* - - 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "OMA", "OMB", - "Innovation", "SigmaObs2", "MahalanobisConsistency"]. - -**"EnsembleBlue"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation de l'ordinateur. - -**"KalmanFilter"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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". - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. - -**"ExtendedKalmanFilter"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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 extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas - une valeur autorisée lorsqu'il n'y a pas de borne). - - ConstrainedBy - Cette clé permet de définir la méthode pour prendre en compte les bornes. Les - méthodes possibles sont dans la liste suivante : ["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 - paramètres, avec la valeur "Parameters". Le choix par défaut est "State". - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. - -**"UnscentedKalmanFilter"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - 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 extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas - une valeur autorisée lorsqu'il n'y a pas de borne). - - ConstrainedBy - Cette clé permet de définir la méthode pour prendre en compte les bornes. Les - méthodes possibles sont dans la liste suivante : ["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 - paramètres, avec la valeur "Parameters". Le choix par défaut est "State". - - Alpha, Beta, Kappa, Reconditioner - Ces clés sont des paramètres de mise à l'échelle interne. "Alpha" requiert - une valeur comprise entre 1.e-4 et 1. "Beta" a une valeur optimale de 2 pour - une distribution *a priori* gaussienne. "Kappa" requiert une valeur entière, - dont la bonne valeur par défaut est obtenue en la mettant à 0. - "Reconditioner" requiert une valeur comprise entre 1.e-3 et 10, son défaut - étant 1. - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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 : ["APosterioriCovariance", "BMA", "Innovation"]. - -**"ParticleSwarmOptimization"** - - *Commandes obligatoires* - *"Background", "BackgroundError", - "Observation", "ObservationError", - "ObservationOperator"* - - MaximumNumberOfSteps - Cette clé indique le nombre maximum d'itérations possibles en optimisation - itérative. Le défaut est 50, qui est une limite arbitraire. Il est ainsi - recommandé d'adapter ce paramètre aux besoins pour des problèmes réels. - - NumberOfInsects - Cette clé indique le nombre d'insectes ou de particules dans l'essaim. La - valeur par défaut est 100, qui est une valeur par défaut usuelle pour cet - algorithme. - - SwarmVelocity - Cette clé indique la part de la vitesse d'insecte qui est imposée par - l'essaim. C'est une valeur réelle positive. Le défaut est de 1. - - GroupRecallRate - Cette clé indique le taux de rappel vers le meilleur insecte de l'essaim. - C'est une valeur réelle comprise entre 0 et 1. Le défaut est de 0.5. - - QualityCriterion - Cette clé indique le critère de qualité, qui est minimisé pour trouver - l'estimation optimale de l'état. Le défaut est le critère usuel de - l'assimilation de données nommé "DA", qui est le critère de moindres carrés - pondérés augmentés. Les critères possibles sont dans la liste suivante, dans - laquelle les noms équivalents sont indiqués par un signe "=" : - ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS", - "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"] - - BoxBounds - Cette clé permet de définir des bornes supérieure et inférieure pour chaque - incrément de variable d'état optimisée (et non pas chaque variable d'état - elle-même). Les bornes doivent être données par une liste de liste de paires - de bornes inférieure/supérieure pour chaque incrément de variable, avec une - valeur extrême chaque fois qu'il n'y a pas de borne (``None`` n'est pas une - valeur autorisée lorsqu'il n'y a pas de borne). Cette clé est requise et il - n'y a pas de valeurs par défaut. - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation par défaut de l'ordinateur. - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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", "OMA", "OMB", "Innovation"]. - -**"QuantileRegression"** - - *Commandes obligatoires* - *"Background", - "Observation", - "ObservationOperator"* +.. _section_reference_entry: - Quantile - Cette clé permet de définir la valeur réelle du quantile recherché, entre 0 - et 1. La valeur par défaut est 0.5, correspondant à la médiane. +======================================================================================== +**[DocR]** Entrées générales, fonctions et matrices +======================================================================================== - Minimizer - Cette clé permet de choisir l'optimiseur pour l'optimisation. Le choix par - défaut et le seul disponible est "MMQR" (Majorize-Minimize for Quantile - Regression). - - 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. - - 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-6, et il est recommandé de - l'adapter aux besoins pour des problèmes réels. - - StoreInternalVariables - Cette clé booléenne permet de stocker les variables internes par défaut, - principalement l'état courant lors d'un processus itératif. Attention, cela - peut être un choix numériquement coûteux dans certains cas de calculs. La - valeur par défaut est "False". - - StoreSupplementaryCalculations - Cette liste indique les noms des variables supplémentaires qui peuvent être - disponibles à la fin de l'algorithme. Cela implique potentiellement des - calculs 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", "OMA", "OMB", "Innovation"]. - -Description de référence pour les cas de vérification ADAO ----------------------------------------------------------- - -Liste des commandes et mots-clés pour un cas de vérification ADAO -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: CHECKING_STUDY -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: CheckingPoint -.. index:: single: Debug -.. index:: single: ObservationOperator -.. index:: single: Study_name -.. index:: single: Study_repertory -.. index:: single: UserDataInit - -Le second jeu de commandes est liée à la description d'un cas de vérification, -qui est une procédure pour vérifier les propriétés requises ailleurs sur -l'information par un cas de calcul. Les termes sont classés par ordre -alphabétique, sauf le premier, qui décrit le choix entre le calcul ou la -vérification. Les différentes commandes sont les suivantes: - -**CHECKING_STUDY** - *Commande obligatoire*. C'est la commande générale qui décrit le cas de - vérification. Elle contient hiérarchiquement toutes les autres commandes. - -**Algorithm** - *Commande obligatoire*. C'est une chaîne de caractère qui indique - l'algorithme de test choisi. Les choix sont limités et disponibles à travers - l'interface graphique. Il existe par exemple "FunctionTest", - "AdjointTest"... Voir plus loin la liste des algorithmes et des paramètres - associés dans la sous-section `Commandes optionnelles et requises pour les - algorithmes de vérification`_. - -**AlgorithmParameters** - *Commande optionnelle*. Elle permet d'ajouter des paramètres optionnels pour - contrôler l'algorithme d'assimilation de données ou d'optimisation. Sa - valeur est définie comme un objet de type "*Dict*". Voir plus loin la liste - des algorithmes et des paramètres associés dans la sous-section `Commandes - optionnelles et requises pour les algorithmes de vérification`_. - -**CheckingPoint** - *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour - duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à - l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type - "*Vector*". - -**Debug** - *Commande optionnelle*. Elle définit le niveau de sorties et d'informations - intermédiaires de débogage. Les choix sont limités entre 0 (pour False) et - 1 (pour True). - -**ObservationOperator** - *Commande obligatoire*. Elle indique l'opérateur d'observation, notée - 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*". Différentes formes fonctionnelles peuvent être utilisées, - comme décrit dans la sous-section suivante `Exigences pour les fonctions - décrivant un opérateur`_. 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)`. - -**Observers** - *Commande optionnelle*. Elle permet de définir des observateurs internes, - qui sont des fonctions liées à une variable particulière, qui sont exécutées - chaque fois que cette variable est modifiée. C'est une manière pratique de - suivre des variables d'intérêt durant le processus d'assimilation de données - ou d'optimisation, en l'affichant ou en la traçant, etc. Des exemples - courants (squelettes) sont fournis pour aider l'utilisateur ou pour - faciliter l'élaboration d'un cas. - -**Study_name** - *Commande obligatoire*. C'est une chaîne de caractères quelconque pour - décrire l'étude ADAO par un nom ou une déclaration. - -**Study_repertory** - *Commande optionnelle*. S'il existe, ce répertoire est utilisé comme base - pour les calculs, et il est utilisé pour trouver les fichiers de script, - donnés par nom sans répertoire, qui peuvent être utilisés pour définir - certaines variables. - -**UserDataInit** - *Commande optionnelle*. Elle permet d'initialiser certains paramètres ou - certaines données automatiquement avant le traitement de données d'entrée - pour l'assimilation de données ou l'optimisation. Pour cela, elle indique un - nom de fichier de script à exécuter avant d'entrer dans l'initialisation des - variables choisies. - -Commandes optionnelles et requises pour les algorithmes de vérification -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: AdjointTest -.. index:: single: FunctionTest -.. index:: single: GradientTest -.. index:: single: LinearityTest -.. index:: single: ObserverTest -.. index:: single: TangentTest - -.. index:: single: AlgorithmParameters -.. index:: single: AmplitudeOfInitialDirection -.. index:: single: EpsilonMinimumExponent -.. index:: single: InitialDirection -.. index:: single: ResiduFormula -.. index:: single: SetSeed - -On rappelle que chaque algorithme peut être contrôlé en utilisant des options -génériques ou particulières, données à travers la commande optionnelle -"*AlgorithmParameters*", à la manière de l'exemple qui suit dans un fichier:: - - AlgorithmParameters = { - "AmplitudeOfInitialDirection" : 1, - "EpsilonMinimumExponent" : -8, - } - -Pour donner les valeurs de la commande "*AlgorithmParameters*" par une chaîne de -caractères, on doit utiliser des guillemets simples pour fournir une définition -standard de dictionnaire, comme par exemple:: - - '{"AmplitudeOfInitialDirection" : 1, "EpsilonMinimumExponent" : -8}' - -Si une option est spécifiée par l'utilisateur pour un algorithme qui ne la -supporte pas, cette option est simplement laissée inutilisée et ne bloque pas le -traitement. La signification des acronymes ou des noms particuliers peut être -trouvée dans l':ref:`genindex` ou dans le :ref:`section_glossary`. De plus, pour -chaque algorithme, les commandes/mots-clés sont donnés, décrits dans `Liste des -commandes et mots-clés pour un cas de vérification ADAO`_. - -**"AdjointTest"** - - *Commandes obligatoires* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - Cette clé indique la mise à l'échelle de la perturbation initiale construite - comme un vecteur utilisé pour la dérivée directionnelle autour du point - nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas - de mise à l'échelle. - - EpsilonMinimumExponent - Cette clé indique la valeur de l'exposant minimal du coefficient en - puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur - de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et - -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la - formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. - - InitialDirection - Cette clé indique la direction vectorielle utilisée pour la dérivée - directionnelle autour du point nominal de vérification. Cela doit être un - vecteur. Si elle n'est pas spécifiée, la direction par défaut est une - perturbation par défaut autour de zéro de la même taille vectorielle que le - point de vérification. - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation par défaut de l'ordinateur. - -**"FunctionTest"** - - *Commandes obligatoires* - *"CheckingPoint", - "ObservationOperator"* - - NumberOfPrintedDigits - Cette clé indique le nombre de décimales de précision pour les affichages de - valeurs réelles. La valeur par défaut est de 5, avec un minimum de 0. - - NumberOfRepetition - Cette clé indique le nombre de fois où répéter l'évaluation de la fonction. - La valeur vaut 1. - - SetDebug - Cette clé requiert l'activation, ou pas, du mode de débogage durant - l'évaluation de la fonction. La valeur par défaut est "True", les choix sont - "True" ou "False". - -**"GradientTest"** - - *Commandes obligatoires* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - Cette clé indique la mise à l'échelle de la perturbation initiale construite - comme un vecteur utilisé pour la dérivée directionnelle autour du point - nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas - de mise à l'échelle. - - EpsilonMinimumExponent - Cette clé indique la valeur de l'exposant minimal du coefficient en - puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur - de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et - -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la - formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. - - InitialDirection - Cette clé indique la direction vectorielle utilisée pour la dérivée - directionnelle autour du point nominal de vérification. Cela doit être un - vecteur. Si elle n'est pas spécifiée, la direction par défaut est une - perturbation par défaut autour de zéro de la même taille vectorielle que le - point de vérification. - - ResiduFormula - Cette clé indique la formule de résidu qui doit être utilisée pour le test. - Le choix par défaut est "Taylor", et les choix possibles sont "Taylor" - (résidu du développement de Taylor de l'opérateur, qui doit décroître comme - le carré de la perturbation) et "Norm" (résidu obtenu en prenant la norme du - développement de Taylor à l'ordre 0, qui approxime le gradient, et qui doit - rester constant). - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation par défaut de l'ordinateur. - -**"LinearityTest"** - - *Commandes obligatoires* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - Cette clé indique la mise à l'échelle de la perturbation initiale construite - comme un vecteur utilisé pour la dérivée directionnelle autour du point - nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas - de mise à l'échelle. - - EpsilonMinimumExponent - Cette clé indique la valeur de l'exposant minimal du coefficient en - puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur - de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et - -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la - formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. - - InitialDirection - Cette clé indique la direction vectorielle utilisée pour la dérivée - directionnelle autour du point nominal de vérification. Cela doit être un - vecteur. Si elle n'est pas spécifiée, la direction par défaut est une - perturbation par défaut autour de zero de la même taille vectorielle que le - point de vérification. - - ResiduFormula - Cette clé indique la formule de résidu qui doit être utilisée pour le test. - Le choix par défaut est "CenteredDL", et les choix possibles sont - "CenteredDL" (résidu de la différence entre la fonction au point nominal et - ses valeurs avec des incréments positif et négatif, qui doit rester très - faible), "Taylor" (résidu du développement de Taylor de l'opérateur - normalisé par sa valeur nominal, qui doit rester très faible), - "NominalTaylor" (résidu de l'approximation à l'ordre 1 de l'opérateur, - normalisé au point nominal, qui doit rester proche de 1), et - "NominalTaylorRMS" (résidu de l'approximation à l'ordre 1 de l'opérateur, - normalisé par l'écart quadratique moyen (RMS) au point nominal, qui doit - rester proche de 0). - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation par défaut de l'ordinateur. - -**"ObserverTest"** - - *Commandes obligatoires* - *"Observers"* - - *Astuce pour cette commande :* - Comme les commandes *"CheckingPoint"* et *"ObservationOperator"* sont - requises pour TOUS les algorithmes de vérification dans l'interface, vous - devez fournir une valeur, malgré le fait que ces commandes ne sont pas - requises pour *"ObserverTest"*, et ne seront pas utilisées. La manière la - plus simple est de donner "1" comme un STRING pour les deux, - l'*"ObservationOperator"* devant être de type *Matrix*. - -**"TangentTest"** - - *Commandes obligatoires* - *"CheckingPoint", - "ObservationOperator"* - - AmplitudeOfInitialDirection - Cette clé indique la mise à l'échelle de la perturbation initiale construite - comme un vecteur utilisé pour la dérivée directionnelle autour du point - nominal de vérification. La valeur par défaut est de 1, ce qui signifie pas - de mise à l'échelle. - - EpsilonMinimumExponent - Cette clé indique la valeur de l'exposant minimal du coefficient en - puissance de 10 qui doit être utilisé pour faire décroître le multiplicateur - de l'incrément. La valeur par défaut est de -8, et elle doit être entre 0 et - -20. Par exemple, la valeur par défaut conduit à calculer le résidu de la - formule avec un incrément fixe multiplié par 1.e0 jusqu'à 1.e-8. - - InitialDirection - Cette clé indique la direction vectorielle utilisée pour la dérivée - directionnelle autour du point nominal de vérification. Cela doit être un - vecteur. Si elle n'est pas spécifiée, la direction par défaut est une - perturbation par défaut autour de zero de la même taille vectorielle que le - point de vérification. - - SetSeed - Cette clé permet de donner un nombre entier pour fixer la graine du - générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est - par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle - utilise ainsi l'initialisation par défaut de l'ordinateur. - -Exigences pour les fonctions décrivant un opérateur ---------------------------------------------------- - -Les opérateurs d'observation et d'évolution sont nécessaires pour mettre en -oeuvre les procédures d'assimilation de données ou d'optimisation. Ils -comprennent la simulation physique par des calculs numériques, mais aussi le -filtrage et de restriction pour comparer la simulation à l'observation. -L'opérateur d'évolution est ici considéré dans sa forme incrémentale, qui -représente la transition entre deux états successifs, et il est alors similaire -à l'opérateur d'observation. - -Schématiquement, un opérateur doit donner une solution étant donné les -paramètres d'entrée. Une partie des paramètres d'entrée peut être modifiée au -cours de la procédure d'optimisation. Ainsi, la représentation mathématique d'un -tel processus est une fonction. Il a été brièvement décrit dans la section -:ref:`section_theory` et il est généralisée ici par la relation: - -.. math:: \mathbf{y} = O( \mathbf{x} ) - -entre les pseudo-observations :math:`\mathbf{y}` et les paramètres -:math:`\mathbf{x}` en utilisant l'opérateur d'observation ou d'évolution -:math:`O`. La même représentation fonctionnelle peut être utilisée pour le -modèle linéaire tangent :math:`\mathbf{O}` de :math:`O` et son adjoint -:math:`\mathbf{O}^*`, qui sont aussi requis par certains algorithmes -d'assimilation de données ou d'optimisation. - -En entrée et en sortie de ces opérateurs, les variables :math:`\mathbf{x}` et -:math:`\mathbf{y}` ou leurs incréments sont mathématiquement des vecteurs, et -ils sont donc passés comme des vecteurs non-orientés (de type liste ou vecteur -Numpy) ou orientés (de type matrice Numpy). - -Ensuite, **pour décrire complètement un opérateur, l'utilisateur n'a qu'à -fournir une fonction qui réalise uniquement l'opération fonctionnelle de manière -complète**. - -Cette fonction est généralement donnée comme un script qui peut être exécuté -dans un noeud YACS. Ce script peut aussi, sans différences, lancer des codes -externes ou utiliser des appels et des méthodes internes SALOME. Si l'algorithme -nécessite les 3 aspects de l'opérateur (forme directe, forme tangente et forme -adjointe), l'utilisateur doit donner les 3 fonctions ou les approximer. - -Il existe 3 méthodes effectives pour l'utilisateur de fournir une représentation -fonctionnelle de l'opérateur. Ces méthodes sont choisies dans le champ "*FROM*" -de chaque opérateur ayant une valeur "*Function*" comme "*INPUT_TYPE*", comme le -montre la figure suivante: - - .. eficas_operator_function: - .. image:: images/eficas_operator_function.png - :align: center - :width: 100% - .. centered:: - **Choisir une représentation fonctionnelle de l'opérateur** - -Première forme fonctionnelle : utiliser "*ScriptWithOneFunction*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithOneFunction -.. index:: single: DirectOperator -.. index:: single: DifferentialIncrement -.. index:: single: CenteredFiniteDifference - -La première consiste à ne fournir qu'une seule fonction potentiellement non -linéaire, et d'approximer les opérateurs tangent et adjoint. Ceci est fait en -utilisant le mot-clé "*ScriptWithOneFunction*" pour la description de -l'opérateur choisi dans l'interface graphique ADAO. L'utilisateur doit fournir -la fonction dans un script, avec un nom obligatoire "*DirectOperator*". Par -exemple, le script peut suivre le modèle suivant:: - - def DirectOperator( X ): - """ Opérateur direct de simulation non-linéaire """ - ... - ... - ... - return Y=O(X) - -Dans ce cas, l'utilisateur doit aussi fournir une valeur pour l'incrément -différentiel (ou conserver la valeur par défaut), en utilisant dans l'interface -graphique (GUI) le mot-clé "*DifferentialIncrement*", qui a une valeur par -défaut de 1%. Ce coefficient est utilisé dans l'approximation différences finies -pour construire les opérateurs tangent et adjoint. L'ordre de l'approximation -différences finies peut aussi être choisi à travers l'interface, en utilisant le -mot-clé "*CenteredFiniteDifference*", avec 0 pour un schéma non centré du -premier ordre (qui est la valeur par défaut), et avec 1 pour un schéma centré du -second ordre (qui coûte numériquement deux fois plus cher que le premier ordre). - -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 -complexité de l'implémentation de l'opérateur. - -**Avertissement important :** le nom "*DirectOperator*" est obligatoire, et le -type de l'argument X peut être une liste, un vecteur ou une matrice Numpy. -L'utilisateur doit traiter ces cas dans sa fonction. - -Seconde forme fonctionnelle : utiliser "*ScriptWithFunctions*" -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithFunctions -.. index:: single: DirectOperator -.. index:: single: TangentOperator -.. index:: single: AdjointOperator - -**En général, il est recommandé d'utiliser la première forme fonctionnelle -plutôt que la seconde. Un petit accroissement de performances n'est pas une -bonne raison pour utiliser l'implémentation détaillée de cette seconde forme -fonctionnelle.** - -La seconde consiste à fournir directement les trois opérateurs liés :math:`O`, -:math:`\mathbf{O}` et :math:`\mathbf{O}^*`. C'est effectué en utilisant le -mot-clé "*ScriptWithFunctions*" pour la description de l'opérateur choisi dans -l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir trois fonctions -dans un script, avec trois noms obligatoires "*DirectOperator*", -"*TangentOperator*" et "*AdjointOperator*". Par exemple, le script peut suivre -le squelette suivant:: - - def DirectOperator( X ): - """ Opérateur direct de simulation non-linéaire """ - ... - ... - ... - return quelque chose comme Y - - def TangentOperator( (X, dX) ): - """ Opérateur linéaire tangent, autour de X, appliqué à dX """ - ... - ... - ... - return quelque chose comme Y - - def AdjointOperator( (X, Y) ): - """ Opérateur adjoint, autour de X, appliqué à Y """ - ... - ... - ... - return quelque chose comme X - -Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester -les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la -complexité de l'implémentation de l'opérateur. - -Pour certains algorithmes, il faut que les fonctions tangente et adjointe puisse -renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas, lorsque, -respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, l'utilisateur -doit renvoyer la matrice associée. - -**Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*" -et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``, -``Y``, ``dX`` peut être une liste, un vecteur ou une matrice Numpy. -L'utilisateur doit traiter ces cas dans ses fonctions. - -Troisième forme fonctionnelle : utiliser "*ScriptWithSwitch*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScriptWithSwitch -.. index:: single: DirectOperator -.. index:: single: TangentOperator -.. index:: single: AdjointOperator - -**Il est recommandé de ne pas utiliser cette troisième forme fonctionnelle sans -une solide raison numérique ou physique. Un accroissement de performances n'est -pas une bonne raison pour utiliser la complexité de cette troisième forme -fonctionnelle. Seule une impossibilité à utiliser les première ou seconde formes -justifie l'usage de la troisième.** - -La troisième forme donne de plus grandes possibilités de contrôle de l'exécution -des trois fonctions représentant l'opérateur, permettant un usage et un contrôle -avancés sur chaque exécution du code de simulation. C'est réalisable en -utilisant le mot-clé "*ScriptWithSwitch*" pour la description de l'opérateur à -travers l'interface graphique (GUI) d'ADAO. L'utilisateur doit fournir un script -unique aiguillant, selon un contrôle, l'exécution des formes directe, tangente -et adjointe du code de simulation. L'utilisateur peut alors, par exemple, -utiliser des approximations pour les codes tangent et adjoint, ou introduire une -plus grande complexité du traitement des arguments des fonctions. Mais cette -démarche sera plus difficile à implémenter et à déboguer. - -Toutefois, si vous souhaitez utiliser cette troisième forme, on recommande de se -baser sur le modèle suivant pour le script d'aiguillage. Il nécessite un fichier -script ou un code externe nommé ici "*Physical_simulation_functions.py*", -contenant trois fonctions nommées "*DirectOperator*", "*TangentOperator*" and -"*AdjointOperator*" comme précédemment. Voici le squelette d'aiguillage:: - - import Physical_simulation_functions - import numpy, logging - # - method = "" - for param in computation["specificParameters"]: - if param["name"] == "method": - method = param["value"] - if method not in ["Direct", "Tangent", "Adjoint"]: - raise ValueError("No valid computation method is given") - logging.info("Found method is \'%s\'"%method) - # - logging.info("Loading operator functions") - Function = Physical_simulation_functions.DirectOperator - Tangent = Physical_simulation_functions.TangentOperator - Adjoint = Physical_simulation_functions.AdjointOperator - # - logging.info("Executing the possible computations") - data = [] - if method == "Direct": - logging.info("Direct computation") - Xcurrent = computation["inputValues"][0][0][0] - data = Function(numpy.matrix( Xcurrent ).T) - if method == "Tangent": - logging.info("Tangent computation") - Xcurrent = computation["inputValues"][0][0][0] - dXcurrent = computation["inputValues"][0][0][1] - data = Tangent(numpy.matrix(Xcurrent).T, numpy.matrix(dXcurrent).T) - if method == "Adjoint": - logging.info("Adjoint computation") - Xcurrent = computation["inputValues"][0][0][0] - Ycurrent = computation["inputValues"][0][0][1] - data = Adjoint((numpy.matrix(Xcurrent).T, numpy.matrix(Ycurrent).T)) - # - logging.info("Formatting the output") - it = numpy.ravel(data) - outputValues = [[[[]]]] - for val in it: - outputValues[0][0][0].append(val) - # - result = {} - result["outputValues"] = outputValues - result["specificOutputInfos"] = [] - result["returnCode"] = 0 - result["errorMessage"] = "" - -Toutes les modifications envisageables peuvent être faites à partir de cette -hypothèse de squelette. - -Cas spécial d'un opérateur d'évolution avec contrôle -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Dans certains cas, l'opérateur d'évolution ou d'observation doit être contrôlé -par un contrôle d'entrée externe, qui est donné *a priori*. Dans ce cas, la -forme générique du modèle incrémental est légèrement modifié comme suit: - -.. math:: \mathbf{y} = O( \mathbf{x}, \mathbf{u}) - -où :math:`\mathbf{u}` est le contrôle sur l'incrément d'état. Dans ce cas, -l'opérateur direct doit être appliqué à une paire de variables :math:`(X,U)`. -Schématiquement, l'opérateur doit être constuit comme suit:: - - def DirectOperator( (X, U) ): - """ Opérateur direct de simulation non-linéaire """ - ... - ... - ... - return quelque chose comme X(n+1) (évolution) ou Y(n+1) (observation) - -Les opérateurs tangent et adjoint ont la même signature que précédemment, en -notant que les dérivées doivent être faites seulement partiellement par rapport -à :math:`\mathbf{x}`. Dans un tel cas de contrôle explicite, seule la deuxième -forme fonctionnelle (en utilisant "*ScriptWithFunctions*") et la troisième forme -fonctionnelle (en utilisant "*ScriptWithSwitch*") peuvent être utilisées. - -Exigences pour décrire les matrices de covariance -------------------------------------------------- - -De multiples matrices de covariance sont nécessaires pour mettre en oeuvre des -procédures d'assimilation de données ou d'optimisation. Les principales sont la -matrice de covariance des erreurs d'ébauche, notée :math:`\mathbf{B}`, et la -matrice de covariance des erreurs d'observation, notée :math:`\mathbf{R}`. Une -telle matrice doit être une matrice carré symétrique semi-définie positive. - -Il y a 3 méthodes pratiques pour l'utilisateur pour fournir une matrice de -covariance. Ces méthodes sont choisies à l'aide du mot-clé "*INPUT_TYPE*" de -chaque matrice de covariance, comme montré dans la figure qui suit : - - .. eficas_covariance_matrix: - .. image:: images/eficas_covariance_matrix.png - :align: center - :width: 100% - .. centered:: - **Choisir la représentation d'une matrice de covariance** - -Première forme matricielle : utiliser la représentation "*Matrix*" -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: Matrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError - -La première forme est le défaut et la plus générale. La matrice de covariance -:math:`\mathbf{M}` doit être entièrement spécifiée. Même si la matrice est -symétrique par nature, la totalité de la matrice :math:`\mathbf{M}` doit être -donnée. - -.. math:: \mathbf{M} = \begin{pmatrix} - m_{11} & m_{12} & \cdots & m_{1n} \\ - m_{21} & m_{22} & \cdots & m_{2n} \\ - \vdots & \vdots & \vdots & \vdots \\ - m_{n1} & \cdots & m_{nn-1} & m_{nn} - \end{pmatrix} - - -Cela peut être réalisé soit par un vecteur ou une matrice Numpy, soit par une -liste de listes de valeurs (c'est-à-dire une liste de lignes). Par exemple, une -matrice simple diagonale unitaire de covariances des erreurs d'ébauche -:math:`\mathbf{B}` peut être décrite dans un fichier de script Python par:: - - BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]] - -ou:: - - BackgroundError = numpy.eye(...) - -Seconde forme matricielle : utiliser la représentation "*ScalarSparseMatrix*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. index:: single: ScalarSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError - -Au contraire, la seconde forme matricielle est une méthode très simplifiée pour -définir une matrice. La matrice de covariance :math:`\mathbf{M}` est supposée -être un multiple positif de la matrice identité. Cette matrice peut alors être -spécifiée de manière unique par le multiplicateur :math:`m`: - -.. math:: \mathbf{M} = m \times \begin{pmatrix} - 1 & 0 & \cdots & 0 \\ - 0 & 1 & \cdots & 0 \\ - \vdots & \vdots & \vdots & \vdots \\ - 0 & \cdots & 0 & 1 - \end{pmatrix} - -Le multiplicateur :math:`m` doit être un nombre réel ou entier positif (s'il -est négatif, ce qui est impossible car une matrice de covariance est positive, -il est convertit en nombre positif). Par exemple, une simple matrice diagonale -unitaire de covariances des erreurs d'ébauche :math:`\mathbf{B}` peut être -décrite dans un fichier de script Python par:: +Cette section décrit de manière générale les différents types d'entrées +possibles, et les formes fonctionnelles ou matricielles que l'on peut utiliser. +Les notations mathématiques utilisées sont expliquées dans la section +:ref:`section_theory`. - BackgroundError = 1. +.. toctree:: + :maxdepth: 1 + + ref_entry_types + ref_options_AlgorithmParameters + ref_operator_requirements + ref_covariance_requirements -ou, mieux, par un "*String*" directement dans le cas ADAO. +.. _section_reference_assimilation: -Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +============================================================================================ +**[DocR]** Cas d'assimilation de données ou d'optimisation +============================================================================================ -.. index:: single: DiagonalSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError +Cette section décrit les algorithmes d'assimilation de données ou d'optimisation +disponibles dans ADAO, détaillant leurs caractéristiques d'utilisation et leurs +options. -La troisième forme est aussi une méthode simplifiée pour fournir la matrice, -mais un peu plus puissante que la seconde. La matrice de covariance -:math:`\mathbf{M}` est toujours considérée comme diagonale, mais l'utilisateur -doit spécifier toutes les valeurs positives situées sur la diagonale. La matrice -peut alors être définie uniquement par un vecteur :math:`\mathbf{V}` qui se -retrouve ensuite sur la diagonale: +Des exemples sur l'usage de ces commandes sont disponibles dans la section +:ref:`section_examples` et dans les fichiers d'exemple installés avec le module +ADAO. Les notations mathématiques utilisées sont expliquées dans la section +:ref:`section_theory`. -.. math:: \mathbf{M} = \begin{pmatrix} - v_{1} & 0 & \cdots & 0 \\ - 0 & v_{2} & \cdots & 0 \\ - \vdots & \vdots & \vdots & \vdots \\ - 0 & \cdots & 0 & v_{n} - \end{pmatrix} +.. toctree:: + :maxdepth: 1 + + ref_assimilation_keywords + ref_algorithm_3DVAR + ref_algorithm_LinearLeastSquares + ref_algorithm_NonLinearLeastSquares + ref_algorithm_Blue + ref_algorithm_ExtendedBlue + ref_algorithm_EnsembleBlue + ref_algorithm_KalmanFilter + ref_algorithm_ExtendedKalmanFilter + ref_algorithm_UnscentedKalmanFilter + ref_algorithm_ParticleSwarmOptimization + ref_algorithm_QuantileRegression + +.. _section_reference_checking: -Cela peut être réalisé soit par vecteur ou une matrice Numpy, soit par -une liste, soit par une liste de listes de valeurs positives (dans tous les cas, -si certaines valeurs sont négatives, elles sont converties en valeurs -positives). Par exemple, un matrice simple diagonale unitaire des covariances -des erreurs d'ébauche :math:`\mathbf{B}` peut être décrite dans un fichier de -script Python par:: +================================================================================ +**[DocR]** Cas de vérification +================================================================================ - BackgroundError = [1, 1 ... 1] +Cette section décrit les algorithmes de vérification disponibles dans ADAO, +détaillant leurs caractéristiques d'utilisation et leurs options. -ou:: +Des exemples sur l'usage de ces commandes sont disponibles dans la section +:ref:`section_examples` et dans les fichiers d'exemple installés avec le module +ADAO. Les notations mathématiques utilisées sont expliquées dans la section +:ref:`section_theory`. - BackgroundError = numpy.ones(...) +.. toctree:: + :maxdepth: 1 + + ref_checking_keywords + ref_algorithm_AdjointTest + ref_algorithm_FunctionTest + ref_algorithm_GradientTest + ref_algorithm_LinearityTest + ref_algorithm_ObserverTest + ref_algorithm_TangentTest diff --git a/doc/fr/theory.rst b/doc/fr/theory.rst index c464032..2ea088e 100644 --- a/doc/fr/theory.rst +++ b/doc/fr/theory.rst @@ -1,8 +1,31 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_theory: -================================================================================ -Une brève introduction à l'Assimilation de Données et à l'Optimisation -================================================================================ +================================================================================= +**[DocT]** Une brève introduction à l'Assimilation de Données et à l'Optimisation +================================================================================= .. index:: single: Data Assimilation .. index:: single: assimilation de données diff --git a/doc/fr/using.rst b/doc/fr/using.rst index 0a7e18d..a0319da 100644 --- a/doc/fr/using.rst +++ b/doc/fr/using.rst @@ -1,7 +1,30 @@ +.. + Copyright (C) 2008-2014 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 + .. _section_using: ================================================================================ -Utiliser le module ADAO +**[DocU]** Utiliser le module ADAO ================================================================================ .. |eficas_new| image:: images/eficas_new.png