X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=doc%2Ffr%2Freference.rst;h=68d4f3e61a83770604b035984f778698ee150e67;hb=4738c3cb4185d4a742c6b6a30c331002eb469c4c;hp=dca5ac8182e46e91c9fdbeb326082e4f0db1ee27;hpb=68108fb2ebc65883e445abf925b7febcff03de6d;p=modules%2Fadao.git diff --git a/doc/fr/reference.rst b/doc/fr/reference.rst index dca5ac8..68d4f3e 100644 --- a/doc/fr/reference.rst +++ b/doc/fr/reference.rst @@ -1,1385 +1,146 @@ -.. _section_reference: - -================================================================================ -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. -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 -propriété est d'être une variable "ouverte" avec un type fixé mais avec -n'importe quelle valeur autorisée par le type, ou une variable "fermée", limitée -à des valeurs spécifiées. L'éditeur graphique EFICAS disposant de capacités -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: Observers -.. index:: single: OutputVariables -.. index:: single: Study_name -.. index:: single: Study_repertory -.. index:: single: UserDataInit -.. index:: single: UserPostAnalysis - -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*". 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*". 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). On - conseille 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 peuvent ê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). On - conseille 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 peuvent ê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 peuvent ê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. Les bornes peuvent - toujours être spécifiées, mais seuls les optimiseurs sous contraintes les - prennent en compte. - - 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 peuvent ê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. Les bornes peuvent - toujours être spécifiées, mais seuls les optimiseurs sous contraintes les - prennent en compte. - - 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. +.. + Copyright (C) 2008-2021 EDF R&D - 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. + This file is part of SALOME ADAO module. - 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 "=" : - ["AugmentedPonderatedLeastSquares"="APLS"="DA", - "PonderatedLeastSquares"="PLS", "LeastSquares"="LS"="L2", - "AbsoluteValue"="L1", "MaximumError"="ME"] + 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. - 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. + 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. - 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". + 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 - 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"]. + See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com -**"QuantileRegression"** + Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D - *Commandes obligatoires* - *"Background", - "Observation", - "ObservationOperator"* - - 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. - - 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, - } - -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} +.. _section_reference: +================================================================================ +**[DocR]** Description de référence des commandes et mots-clés ADAO +================================================================================ -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:: +Les sections suivantes présentent la description de référence des commandes et +mots-clés ADAO disponibles à travers l'interface textuelle (TUI), graphique +(GUI) ou à travers des scripts. Les deux premières sections communes présentent +les :ref:`section_reference_entry` et les +:ref:`section_reference_special_entry`. Ensuite, on décrit successivement les +:ref:`section_reference_assimilation` et les :ref:`section_reference_checking`. - BackgroundError = [[1, 0 ... 0], [0, 1 ... 0] ... [0, 0 ... 1]] +Chaque commande ou mot-clé à définir par la TUI ou la 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 propriété est d'être +une variable "ouverte" avec un type fixé mais avec n'importe quelle valeur +autorisée par le type, ou une variable "fermée", limitée à des valeurs +spécifiées. L'éditeur graphique GUI intégré disposant de capacités 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. -ou:: +.. _section_reference_entry: - BackgroundError = numpy.eye(...) +======================================================================================== +**[DocR]** Entrées et sorties générales +======================================================================================== -Seconde forme matricielle : utiliser la représentation "*ScalarSparseMatrix*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Cette section décrit de manière générale les différentes possibilités de types +d'entrées et de variables de sortie que l'on peut utiliser. Les notations +mathématiques utilisées sont expliquées dans la section :ref:`section_theory`. -.. index:: single: ScalarSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError +.. toctree:: + :maxdepth: 1 -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`: + ref_entry_types + ref_options_AlgorithmParameters + ref_output_variables -.. 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} +.. _section_reference_special_entry: -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:: +======================================================================================== +**[DocR]** Entrées spéciales : fonctions, matrices, "*observer*" +======================================================================================== - BackgroundError = 1. +Cette section décrit les entrées spéciales, comme 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`. -ou, mieux, par un "*String*" directement dans le cas ADAO. +.. toctree:: + :maxdepth: 1 -Troisième forme matricielle : utiliser la représentation "*DiagonalSparseMatrix*" -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + ref_operator_requirements + ref_covariance_requirements + ref_observers_requirements -.. index:: single: DiagonalSparseMatrix -.. index:: single: BackgroundError -.. index:: single: EvolutionError -.. index:: single: ObservationError +.. _section_reference_assimilation: -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: +============================================================================================ +**[DocR]** Cas d'assimilation de données ou d'optimisation +============================================================================================ -.. 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} +Cette section décrit les choix algorithmiques pour utiliser des méthodes +d'assimilation de données, des méthodes d'optimisation ou des méthodes avec +réduction, disponibles dans ADAO, détaillant leurs caractéristiques +d'utilisation et leurs options. -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:: +Des exemples sur l'usage de ces commandes sont disponibles dans la section +:ref:`section_tutorials_in_salome`, dans la section +:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés +avec ADAO. Les notations mathématiques utilisées sont expliquées dans la +section :ref:`section_theory`. + +.. toctree:: + :maxdepth: 1 + + ref_algorithm_3DVAR + ref_algorithm_4DVAR + ref_algorithm_Blue + ref_algorithm_DerivativeFreeOptimization + ref_algorithm_DifferentialEvolution + ref_algorithm_EnsembleBlue + ref_algorithm_EnsembleKalmanFilter + ref_algorithm_ExtendedBlue + ref_algorithm_ExtendedKalmanFilter + ref_algorithm_KalmanFilter + ref_algorithm_LinearLeastSquares + ref_algorithm_NonLinearLeastSquares + ref_algorithm_ParticleSwarmOptimization + ref_algorithm_QuantileRegression + ref_algorithm_TabuSearch + ref_algorithm_UnscentedKalmanFilter + ref_assimilation_keywords + +.. _section_reference_checking: - BackgroundError = [1, 1 ... 1] +================================================================================ +**[DocR]** Cas de vérification +================================================================================ -ou:: +Cette section décrit les algorithmes de vérification disponibles dans ADAO, +détaillant leurs caractéristiques d'utilisation et leurs options. - BackgroundError = numpy.ones(...) +Des exemples sur l'usage de ces commandes sont disponibles dans la section +:ref:`section_tutorials_in_salome`, dans la section +:ref:`section_tutorials_in_python` et dans les fichiers d'exemple installés +avec ADAO. Les notations mathématiques utilisées sont expliquées dans la +section :ref:`section_theory`. + +.. toctree:: + :maxdepth: 1 + + ref_algorithm_AdjointTest + ref_algorithm_FunctionTest + ref_algorithm_GradientTest + ref_algorithm_InputValuesTest + ref_algorithm_LinearityTest + ref_algorithm_LocalSensitivityTest + ref_algorithm_ObserverTest + ref_algorithm_ParallelFunctionTest + ref_algorithm_SamplingTest + ref_algorithm_TangentTest + ref_checking_keywords