doc/fr/ref_algorithm_SamplingTest.rst

   1 ..
   2    Copyright (C) 2008-2015 EDF R&D
   3
   4    This file is part of SALOME ADAO module.
   5
   6    This library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19
  20    See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21
  22    Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  23
  24 .. index:: single: SamplingTest
  25 .. _section_ref_algorithm_SamplingTest:
  26
  27 Algorithme de vérification "*SamplingTest*"
  28 -------------------------------------------
  29
  30 Description
  31 +++++++++++
  32
  33 Cet algorithme permet d'établir les valeurs, liées à un état :math:`\mathbf{x}`,
  34 d'une fonctionnelle d'erreur :math:`J` quelconque de type :math:`L^1`,
  35 :math:`L^2` ou :math:`L^{\infty}`, avec ou sans pondérations, et de l'opérateur
  36 d'observation, pour un échantillon d'états donné a priori. La fonctionnelle
  37 d'erreur par défaut est celle de moindres carrés pondérés augmentés,
  38 classiquement utilisée en assimilation de données.
  39
  40 Il est utile pour tester la sensibilité, de la fonctionnelle :math:`J`, en
  41 particulier, aux variations de l'état :math:`\mathbf{x}`. Lorsque un état n'est
  42 pas observable, une valeur *"NaN"* est retournée.
  43
  44 L'échantillon des états :math:`\mathbf{x}` peut être fourni explicitement ou
  45 sous la forme d'hyper-cubes, explicites ou échantillonnés selon des lois
  46 courantes. Attention à la taille de l'hyper-cube (et donc au nombre de calculs)
  47 qu'il est possible d'atteindre, elle peut rapidement devenir importante.
  48
  49 Pour apparaître pour l'utilisateur, les résultats de l'échantillonnage doivent
  50 être demandés explicitement. On utilise pour cela, sur la variable désirée, la
  51 sauvegarde finale à l'aide du mot-clé "*UserPostAnalysis*" ou le traitement en
  52 cours de calcul à l'aide des "*observer*" adaptés.
  53
  54 Pour effectuer un échantillonnage distribué ou plus complexe, voir d'autres
  55 modules disponibles dans SALOME : PARAMETRIC ou OPENTURNS.
  56
  57 Commandes requises et optionnelles
  58 ++++++++++++++++++++++++++++++++++
  59
  60 .. index:: single: AlgorithmParameters
  61 .. index:: single: CheckingPoint
  62 .. index:: single: BackgroundError
  63 .. index:: single: Observation
  64 .. index:: single: ObservationError
  65 .. index:: single: ObservationOperator
  66 .. index:: single: SampleAsnUplet
  67 .. index:: single: SampleAsExplicitHyperCube
  68 .. index:: single: SampleAsMinMaxStepHyperCube
  69 .. index:: single: SampleAsIndependantRandomVariables
  70 .. index:: single: QualityCriterion
  71 .. index:: single: SetDebug
  72 .. index:: single: SetSeed
  73 .. index:: single: StoreSupplementaryCalculations
  74
  75 Les commandes requises générales, disponibles dans l'interface en édition, sont
  76 les suivantes:
  77
  78   CheckingPoint
  79     *Commande obligatoire*. Elle définit le vecteur utilisé comme l'état autour
  80     duquel réaliser le test requis, noté :math:`\mathbf{x}` et similaire à
  81     l'ébauche :math:`\mathbf{x}^b`. Sa valeur est définie comme un objet de type
  82     "*Vector*".
  83
  84   BackgroundError
  85     *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
  86     d'ébauche, notée précédemment :math:`\mathbf{B}`. Sa valeur est définie
  87     comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
  88     type "*DiagonalSparseMatrix*".
  89
  90   Observation
  91     *Commande obligatoire*. Elle définit le vecteur d'observation utilisé en
  92     assimilation de données ou en optimisation, et noté précédemment
  93     :math:`\mathbf{y}^o`. Sa valeur est définie comme un objet de type "*Vector*"
  94     ou de type "*VectorSerie*".
  95
  96   ObservationError
  97     *Commande obligatoire*. Elle définit la matrice de covariance des erreurs
  98     d'ébauche, notée précédemment :math:`\mathbf{R}`. Sa valeur est définie
  99     comme un objet de type "*Matrix*", de type "*ScalarSparseMatrix*", ou de
 100     type "*DiagonalSparseMatrix*".
 101
 102   ObservationOperator
 103     *Commande obligatoire*. Elle indique l'opérateur d'observation, notée
 104     précédemment :math:`H`, qui transforme les paramètres d'entrée
 105     :math:`\mathbf{x}` en résultats :math:`\mathbf{y}` qui sont à comparer aux
 106     observations :math:`\mathbf{y}^o`.  Sa valeur est définie comme un objet de
 107     type "*Function*". Différentes formes fonctionnelles peuvent être
 108     utilisées, comme décrit dans la section
 109     :ref:`section_ref_operator_requirements`. Si un contrôle :math:`U` est
 110     inclus dans le modèle d'observation, l'opérateur doit être appliqué à une
 111     paire :math:`(X,U)`.
 112
 113 Les commandes optionnelles générales, disponibles dans l'interface en édition,
 114 sont indiquées dans la :ref:`section_ref_checking_keywords`. De plus, les
 115 paramètres de la commande "*AlgorithmParameters*" permettent d'indiquer les options
 116 particulières, décrites ci-après, de l'algorithme. On se reportera à la
 117 :ref:`section_ref_options_Algorithm_Parameters` pour le bon usage de cette
 118 commande.
 119
 120 Les options de l'algorithme sont les suivantes:
 121
 122   SampleAsnUplet
 123     Cette clé décrit les points de calcul sous la forme d'une liste de n-uplets,
 124     chaque n-uplet étant un état.
 125
 126     Exemple : ``{"SampleAsnUplet":[[0,1,2,3],[4,3,2,1],[-2,3,-4,5]]}`` pour 3 points dans un espace d'état de dimension 4
 127
 128   SampleAsExplicitHyperCube
 129     Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
 130     donne la liste des échantillonnages explicites de chaque variable comme une
 131     liste. C'est donc une liste de listes, chacune étant de taille
 132     potentiellement différente.
 133
 134     Exemple : ``{"SampleAsExplicitHyperCube":[[0.,0.25,0.5,0.75,1.], [-2,2,1]]}`` pour un espace d'état de dimension 2
 135
 136   SampleAsMinMaxStepHyperCube
 137     Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont on
 138     donne la liste des échantillonnages implicites de chaque variable par un
 139     triplet *[min,max,step]*. C'est donc une liste de la même taille que celle
 140     de l'état. Les bornes sont incluses.
 141
 142     Exemple : ``{"SampleAsMinMaxStepHyperCube":[[0.,1.,0.25],[-1,3,1]]}`` pour un espace d'état de dimension 2
 143
 144   SampleAsIndependantRandomVariables
 145     Cette clé décrit les points de calcul sous la forme d'un hyper-cube, dont
 146     les points sur chaque axe proviennent de l'échantillonnage aléatoire
 147     indépendant de la variable d'axe, selon la spécification de la
 148     distribution, de ses paramètres et du nombre de points de l'échantillon,
 149     sous la forme d'une liste ``['distribution', [parametres], nombre]`` pour
 150     chaque axe. Les distributions possibles sont 'normal' de paramètres
 151     (mean,std), 'lognormal' de paramètres (mean,sigma), 'uniform' de paramètres
 152     (low,high), ou 'weibull' de paramètre (shape). C'est donc une liste de la
 153     même taille que celle de l'état.
 154
 155     Exemple : ``{"SampleAsIndependantRandomVariables":[ ['normal',[0.,1.],3], ['uniform',[-2,2],4]]`` pour un espace d'état de dimension 2
 156
 157   QualityCriterion
 158     Cette clé indique le critère de qualité, qui est utilisé pour trouver
 159     l'estimation de l'état. Le défaut est le critère usuel de l'assimilation de
 160     données nommé "DA", qui est le critère de moindres carrés pondérés
 161     augmentés. Les critères possibles sont dans la liste suivante, dans laquelle
 162     les noms équivalents sont indiqués par un signe "=" :
 163     ["AugmentedWeightedLeastSquares"="AWLS"="DA", "WeightedLeastSquares"="WLS",
 164     "LeastSquares"="LS"="L2", "AbsoluteValue"="L1", "MaximumError"="ME"].
 165
 166     Exemple : ``{"QualityCriterion":"DA"}``
 167
 168   SetDebug
 169     Cette clé requiert l'activation, ou pas, du mode de débogage durant
 170     l'évaluation de la fonction. La valeur par défaut est "True", les choix sont
 171     "True" ou "False".
 172
 173     Exemple : ``{"SetDebug":False}``
 174
 175   SetSeed
 176     Cette clé permet de donner un nombre entier pour fixer la graine du
 177     générateur aléatoire utilisé pour générer l'ensemble. Un valeur pratique est
 178     par exemple 1000. Par défaut, la graine est laissée non initialisée, et elle
 179     utilise ainsi l'initialisation par défaut de l'ordinateur.
 180
 181     Exemple : ``{"SetSeed":1000}``
 182
 183   StoreSupplementaryCalculations
 184     Cette liste indique les noms des variables supplémentaires qui peuvent être
 185     disponibles à la fin de l'algorithme. Cela implique potentiellement des
 186     calculs ou du stockage coûteux. La valeur par défaut est une liste vide,
 187     aucune de ces variables n'étant calculée et stockée par défaut. Les noms
 188     possibles sont dans la liste suivante : ["CostFunctionJ", "CurrentState",
 189     "Innovation", "SimulatedObservationAtCurrentState"].
 190
 191     Exemple : ``{"StoreSupplementaryCalculations":["CostFunctionJ", "SimulatedObservationAtCurrentState"]}``
 192
 193 Voir aussi
 194 ++++++++++
 195
 196 Références vers d'autres sections :
 197   - :ref:`section_ref_algorithm_FunctionTest`
 198
 199 Références vers d'autres modules SALOME :
 200   - PARAMETRIC, voir le *Guide utilisateur du module PARAMETRIC* dans le menu principal *Aide* de l'environnement SALOME
 201   - OPENTURNS, voir le *Guide utilisateur du module OPENTURNS* dans le menu principal *Aide* de l'environnement SALOME