14.1. Algorithme de vérification « AdjointTest »¶

14.1.1. Description¶

Cet algorithme permet de vérifier la qualité de l’adjoint d’un opérateur $F$ , en calculant un résidu dont les propriétés théoriques sont connues. Le test est applicable à un opérateur quelconque, d’évolution comme d’observation.

Pour toutes les formules, avec $\mathbf{x}$ le point courant de vérification, on prend $\mathbf{dx}_0=Normal(0,\mathbf{x})$ et $\mathbf{dx}=\alpha_0*\mathbf{dx}_0$ avec $\alpha_0$ un paramètre utilisateur de mise à l’échelle, par défaut à 1. $F$ est l’opérateur ou le code de calcul (qui est ici défini par la commande d’opérateur d’observation « ObservationOperator »).

On observe le résidu suivant, qui est la différence de deux produits scalaires :

$R(\alpha) = | < TangentF_x(\mathbf{dx}) , \mathbf{y} > - < \mathbf{dx} , AdjointF_x(\mathbf{y}) > |$

dans lequel la quantité optionnelle $\mathbf{y}$ doit être dans l’image de $F$ . Si elle n’est pas donnée, on prend son évaluation par défaut $\mathbf{y} = F(\mathbf{x})$ .

Ce résidu doit rester constamment égal à zéro à la précision du calcul.

14.1.2. Commandes requises et optionnelles¶

Les commandes générales requises, disponibles en édition dans l’interface graphique ou textuelle, sont les suivantes :

CheckingPoint: Vecteur. La variable désigne le vecteur utilisé comme l’état autour duquel réaliser le test requis, noté $\mathbf{x}$ , similaire à l’ébauche $\mathbf{x}^b$ . Sa valeur est définie comme un objet de type « Vector » ou « VectorSerie ». Sa disponibilité en sortie est conditionnée par le booléen « Stored » associé en entrée.

Observation: Liste de vecteurs. La variable désigne le vecteur d’observation utilisé en assimilation de données ou en optimisation, et usuellement noté $\mathbf{y}^o$ . Sa valeur est définie comme un objet de type « Vector » si c’est une unique observation (temporelle ou pas) ou « VectorSerie » si c’est une succession d’observations. Sa disponibilité en sortie est conditionnée par le booléen « Stored » associé en entrée.

ObservationOperator: Opérateur. La variable désigne l’opérateur d’observation, usuellement noté $H$ , qui transforme les paramètres d’entrée $\mathbf{x}$ en résultats $\mathbf{y}$ qui sont à comparer aux observations $\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 Conditions requises pour les fonctions décrivant un opérateur. Si un contrôle $U$ est inclus dans le modèle d’observation, l’opérateur doit être appliqué à une paire $(X,U)$ .

Les commandes optionnelles générales, disponibles en édition dans l’interface graphique ou textuelle, sont indiquées dans la Liste des commandes et mots-clés pour un cas de vérification. De plus, les paramètres de la commande « AlgorithmParameters » permettent d’indiquer les options particulières, décrites ci-après, de l’algorithme. On se reportera à la Description des options d’un algorithme par « AlgorithmParameters » pour le bon usage de cette commande.

Les options sont les suivantes :

AmplitudeOfInitialDirection

Valeur réelle. 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 qu’il n’y a aucune mise à l’échelle.

Exemple : {"AmplitudeOfInitialDirection":0.5}

EpsilonMinimumExponent

Valeur entière. 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 négative 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.

Exemple : {"EpsilonMinimumExponent":-12}

InitialDirection

Vecteur. 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 de la même taille que celle du point de vérification. Si elle n’est pas spécifiée, la direction par défaut est une perturbation vectorielle autour de zéro de la même taille que le point de vérification.

Exemple : {"InitialDirection":[0.1,0.1,100.,3} pour un espace d’état de dimension 4

NumberOfPrintedDigits

Valeur entière. 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.

Exemple : {"NumberOfPrintedDigits":5}

SetSeed

Valeur entière. Cette clé permet de donner un nombre entier pour fixer la graine du générateur aléatoire utilisé dans l’algorithme. Par défaut, la graine est laissée non initialisée, et elle utilise ainsi l’initialisation par défaut de l’ordinateur, qui varie donc à chaque étude. Pour assurer la reproductibilité de résultats impliquant des tirages aléatoires, il est fortement conseillé d’initialiser la graine. Une valeur simple est par exemple 123456789. Il est conseillé de mettre un entier à plus de 6 ou 7 chiffres pour bien initialiser le générateur aléatoire.

Exemple : {"SetSeed":123456789}

StoreSupplementaryCalculations

Liste de noms. Cette liste indique les noms des variables supplémentaires, qui peuvent être disponibles au cours du déroulement ou à la fin de l’algorithme, si elles sont initialement demandées par l’utilisateur. Leur disponibilité implique, potentiellement, des calculs ou du stockage coûteux. La valeur par défaut est donc une liste vide, aucune de ces variables n’étant calculée et stockée par défaut (sauf les variables inconditionnelles). Les noms possibles pour les variables supplémentaires sont dans la liste suivante (la description détaillée de chaque variable nommée est donnée dans la suite de cette documentation par algorithme spécifique, dans la sous-partie « Informations et variables disponibles à la fin de l’algorithme ») : [ « CurrentState », « Residu », « SimulatedObservationAtCurrentState », ].

Exemple : {"StoreSupplementaryCalculations":["CurrentState", "Residu"]}

14.1.3. Informations et variables disponibles à la fin de l’algorithme¶

En sortie, après exécution de l’algorithme, on dispose d’informations et de variables issues du calcul. La description des Variables et informations disponibles en sortie indique la manière de les obtenir par la méthode nommée get, de la variable « ADD » du post-processing en interface graphique, ou du cas en interface textuelle. Les variables d’entrée, mises à disposition de l’utilisateur en sortie pour faciliter l’écriture des procédures de post-processing, sont décrites dans l”Inventaire des informations potentiellement disponibles en sortie.

Sorties permanentes (non conditionnelles)

Les sorties non conditionnelles de l’algorithme sont les suivantes :

Residu

Liste de valeurs. Chaque élément est la valeur du résidu particulier vérifié lors du déroulement de l’algorithme, selon l’ordre des tests effectués.

Exemple : r = ADD.get("Residu")[:]

Ensemble des sorties à la demande (conditionnelles ou non)

L’ensemble des sorties (conditionnelles ou non) de l’algorithme, classées par ordre alphabétique, est le suivant :

CurrentState

Liste de vecteurs. Chaque élément est un vecteur d’état courant utilisé au cours du déroulement itératif de l’algorithme utilisé.

Exemple : xs = ADD.get("CurrentState")[:]

Residu

Liste de valeurs. Chaque élément est la valeur du résidu particulier vérifié lors du déroulement de l’algorithme, selon l’ordre des tests effectués.

Exemple : r = ADD.get("Residu")[:]

SimulatedObservationAtCurrentState

Liste de vecteurs. Chaque élément est un vecteur d’observation simulé par l’opérateur d’observation à partir de l’état courant, c’est-à-dire dans l’espace des observations.

Exemple : hxs = ADD.get("SimulatedObservationAtCurrentState")[-1]

14.1.4. Exemples d’utilisation en Python (TUI)¶

Voici un ou des exemples très simple d’usage de l’algorithme proposé et de ses paramètres, écrit en [DocR] Interface textuelle pour l’utilisateur (TUI/API). De plus, lorsque c’est possible, les informations indiquées en entrée permettent aussi de définir un cas équivalent en interface graphique [DocR] Interface graphique pour l’utilisateur (GUI/EFICAS).

Cet exemple décrit le test de la qualité de l’adjoint d’un opérateur quelconque, dont la formulation directe est donnée et dont la formulation adjointe est ici approximée par défaut. Les informations nécessaires sont minimales, à savoir ici un opérateur $F$ (décrit pour le test par la commande d’observation « ObservationOperator »), et un état $\mathbf{x}^b$ sur lequel le tester (décrit pour le test par la commande « CheckingPoint »). Une observation $\mathbf{y}^o$ peut être donnée comme ici (décrit pour le test par la commande « Observation »). On a paramétré la sortie pour fixer l’impression, par exemple pour faciliter la comparaison automatique.

La vérification pratique consiste à observer si le résidu est constamment égal à zéro à la précision du calcul.

# -*- coding: utf-8 -*-
#
from numpy import array, eye
from adao import adaoBuilder
case = adaoBuilder.New()
case.setCheckingPoint( Vector = array([0., 1., 2.]), Stored=True )
case.setObservation( Vector = [10., 11., 12.] )
case.setObservationOperator( Matrix = eye(3), )
case.setAlgorithmParameters(
    Algorithm='AdjointTest',
    Parameters={
        'EpsilonMinimumExponent' :-12,
        'NumberOfPrintedDigits' : 3,
        'SetSeed' : 1234567,
        },
    )
case.execute()

Le résultat de son exécution est le suivant :

     ADJOINTTEST
     ===========

     This test allows to analyze the quality of an adjoint operator associated
     to some given direct operator F, applied to one single vector argument x.
     If the adjoint operator is approximated and not given, the test measures
     the quality of the automatic approximation, around an input checking point X.

===> Information before launching:
     -----------------------------

     Characteristics of input vector X, internally converted:
       Type...............: <class 'numpy.ndarray'>
       Length of vector...: 3
       Minimum value......: 0.000e+00
       Maximum value......: 2.000e+00
       Mean of vector.....: 1.000e+00
       Standard error.....: 8.165e-01
       L2 norm of vector..: 2.236e+00

     ---------------------------------------------------------------------------

===> Numerical quality indicators:
     -----------------------------

     Using the "ScalarProduct" formula, one observes the residue R which is the
     difference of two scalar products:

         R(Alpha) = | < TangentF_X(dX) , Y > - < dX , AdjointF_X(Y) > |

     which must remain constantly equal to zero to the accuracy of the calculation.
     One takes dX0 = Normal(0,X) and dX = Alpha*dX0, where F is the calculation
     operator. If it is given, Y must be in the image of F. If it is not given,
     one takes Y = F(X).

     (Remark: numbers that are (about) under 2e-16 represent 0 to machine precision)


     -------------------------------------------------------------
       i   Alpha     ||X||       ||Y||       ||dX||     R(Alpha)
     -------------------------------------------------------------
        0  1e+00   2.236e+00   1.910e+01   3.536e+00   0.000e+00
        1  1e-01   2.236e+00   1.910e+01   3.536e-01   0.000e+00
        2  1e-02   2.236e+00   1.910e+01   3.536e-02   0.000e+00
        3  1e-03   2.236e+00   1.910e+01   3.536e-03   0.000e+00
        4  1e-04   2.236e+00   1.910e+01   3.536e-04   0.000e+00
        5  1e-05   2.236e+00   1.910e+01   3.536e-05   0.000e+00
        6  1e-06   2.236e+00   1.910e+01   3.536e-06   0.000e+00
        7  1e-07   2.236e+00   1.910e+01   3.536e-07   0.000e+00
        8  1e-08   2.236e+00   1.910e+01   3.536e-08   0.000e+00
        9  1e-09   2.236e+00   1.910e+01   3.536e-09   0.000e+00
       10  1e-10   2.236e+00   1.910e+01   3.536e-10   0.000e+00
       11  1e-11   2.236e+00   1.910e+01   3.536e-11   0.000e+00
       12  1e-12   2.236e+00   1.910e+01   3.536e-12   0.000e+00
     -------------------------------------------------------------

     End of the "ADJOINTTEST" verification by the "ScalarProduct" formula.

     ---------------------------------------------------------------------------

14.1.5. Voir aussi¶

Références vers d’autres sections :