14.2. Algorithme de vérification « ControledFunctionTest »

14.2.1. Description

Cet algorithme de vérification permet d’analyser de manière simple la stabilité d’un opérateur F lors de son exécution. L’opérateur est quelconque, et il peut donc être celui d’observation \mathcal{H} comme celui d’évolution \mathcal{D}, pourvu qu’il soit fourni dans chaque cas selon les Conditions requises pour les fonctions décrivant un opérateur. L’opérateur F est considéré comme dépendant d’une variable vectorielle \mathbf{x} et d’un contrôle \mathbf{u}, les deux n’étant pas nécessairement de la même taille, et restituant une autre variable vectorielle \mathbf{y}.

L’algorithme vérifie que l’opérateur 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 \mathbf{x} en entrée et \mathbf{y} en sortie est indiquée lors de chaque exécution de l’opérateur, et une autre statistique globale est fournie de manière récapitulative à la fin. La précision d’affichage est contrôlable pour permettre l’automatisation des tests d’opérateur. Il peut être aussi utile de vérifier préalablement les entrées elles-mêmes avec le test prévu Algorithme de vérification « InputValuesTest ».

14.2.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.

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).

ControlInput

Vecteur. La variable indique le vecteur de contrôle utilisé pour forcer le modèle d’évolution à chaque pas, usuellement noté \mathbf{U}. Sa valeur est définie comme un objet de type « Vector » ou « VectorSerie ». Lorsqu’il n’y a pas de contrôle, sa valeur doit être une chaîne vide “”.

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 :

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}

NumberOfRepetition

Valeur entière. Cette clé indique le nombre de fois où répéter l’évaluation de la fonction. La valeur par défaut est 1.

Exemple : {"NumberOfRepetition":3}

SetDebug

Valeur booléenne. La variable conduit à l’activation, ou pas, du mode de débogage durant l’évaluation de la fonction ou de l’opérateur. La valeur par défaut est « True », les choix sont « True » ou « False ».

Exemple : {"SetDebug":False}

ShowElementarySummary

Valeur booléenne. La variable conduit à l’activation, ou pas, du calcul et de l’affichage d’un résumé à chaque évaluation élémentaire du test. La valeur par défaut est « True », les choix sont « True » ou « False ».

Exemple : {"ShowElementarySummary":False}

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 », « SimulatedObservationAtCurrentState », ].

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

14.2.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 :

Aucune

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")[:]

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.2.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).

14.2.4.1. Premier exemple

Cet exemple décrit le test du bon fonctionnement d’un opérateur quelconque, et que son appel se déroule de manière compatible avec son usage courant dans les algorithmes d’ADAO. Les informations nécessaires sont minimales, à savoir ici un opérateur (décrit pour le test par la commande d’observation « ObservationOperator »), un état particulier \mathbf{x} sur lequel le tester (décrit pour le test par la commande « CheckingPoint ») et un contrôle \mathbf{u} (décrit pour le test par la commande « ControlInput »), les deux n’étant pas nécessairement de la même taille.

Le test est répété un nombre paramétrable de fois, et une statistique finale permet de vérifier rapidement le bon comportement de l’opérateur. Le diagnostic le plus simple consiste à vérifier, à la toute fin de l’affichage, l’ordre de grandeur des variations des valeurs indiquées comme la moyenne des différences entre les sorties répétées et leur moyenne, sous la partie titrée « Characteristics of the mean of the differences between the outputs Y and their mean Ym ». Pour un opérateur satisfaisant, ces valeurs doivent être proches du zéro numérique.

# -*- 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.setObservationOperator( Matrix = eye(3) )
case.setAlgorithmParameters(
    Algorithm='ControledFunctionTest',
    Parameters={
        'NumberOfRepetition' : 5,
        'NumberOfPrintedDigits' : 2,
        'ShowElementarySummary':False,
        },
    )
case.setControlInput( Vector = 1. )
case.execute()

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


     CONTROLEDFUNCTIONTEST
     =====================

     This test allows to analyze the (repetition of the) launch of some
     given simulation operator F, applied to one single vector x and to
     one control vector u as arguments, in a sequential way.
     The output shows simple statistics related to its successful execution,
     or related to the similarities of repetition of its execution.

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

     Characteristics of input vector X, internally converted:
       Type...............: <class 'numpy.ndarray'>
       Length of vector...: 3
       Minimum value......: 0.00e+00
       Maximum value......: 2.00e+00
       Mean of vector.....: 1.00e+00
       Standard error.....: 8.16e-01
       L2 norm of vector..: 2.24e+00

     Characteristics of control parameter U, internally converted:
       Type...............: <class 'numpy.ndarray'>
       Length of vector...: 1
       Minimum value......: 1.00e+00
       Maximum value......: 1.00e+00
       Mean of vector.....: 1.00e+00
       Standard error.....: 0.00e+00
       L2 norm of vector..: 1.00e+00

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

===> Beginning of repeated evaluation, without activating debug

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

===> End of repeated evaluation, without deactivating debug

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

===> Launching statistical summary calculation for 5 states

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

===> Statistical analysis of the outputs obtained through sequential repeated evaluations

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

     Number of evaluations...........................: 5

     Characteristics of the whole set of outputs Y:
       Size of each of the outputs...................: 3
       Minimum value of the whole set of outputs.....: 0.00e+00
       Maximum value of the whole set of outputs.....: 2.00e+00
       Mean of vector of the whole set of outputs....: 1.00e+00
       Standard error of the whole set of outputs....: 8.16e-01

     Characteristics of the vector Ym, mean of the outputs Y:
       Size of the mean of the outputs...............: 3
       Minimum value of the mean of the outputs......: 0.00e+00
       Maximum value of the mean of the outputs......: 2.00e+00
       Mean of the mean of the outputs...............: 1.00e+00
       Standard error of the mean of the outputs.....: 8.16e-01

     Characteristics of the mean of the differences between the outputs Y and their mean Ym:
       Size of the mean of the differences...........: 3
       Minimum value of the mean of the differences..: 0.00e+00
       Maximum value of the mean of the differences..: 0.00e+00
       Mean of the mean of the differences...........: 0.00e+00
       Standard error of the mean of the differences.: 0.00e+00

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

     End of the "CONTROLEDFUNCTIONTEST" verification

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

14.2.4.2. Deuxième exemple

Ce nouvel exemple décrit le test du bon fonctionnement d’un opérateur quelconque nommé ControledQuadFunction, disponible sous forme fonctionnelle. Il est défini par la commande « ObservationOperator » selon la Seconde forme fonctionnelle : trois opérateurs direct, tangent et adjoint (ici, même avec cette forme fonctionnelle, on peut exceptionnellement ne pas définir les formes tangente et adjointe de l’opérateur car elles ne sont pas utiles dans ce test). Par la commande « CheckingPoint », on ajoute aussi un état particulier \mathbf{x} sur lequel tester l’opérateur, et par la commande « ControlInput » on ajoute un contrôle fixe \mathbf{u}.

Ce test est arbitrairement répété ici 15 fois, et une statistique finale permet de vérifier rapidement le bon comportement de l’opérateur. Le diagnostic le plus simple consiste à vérifier, à la toute fin de l’affichage, l’ordre de grandeur des variations des valeurs indiquées comme la moyenne des différences entre les sorties répétées et leur moyenne, sous la partie titrée « Characteristics of the mean of the differences between the outputs Y and their mean Ym ». Pour qu’un opérateur soit satisfaisant, ces valeurs doivent être proches du zéro numérique.

# -*- coding: utf-8 -*-
#
from numpy import array, ravel
def ControledQuadFunction( paire ):
    """
    Simulation quadratique contrôlée
    """
    coefficients, controle = paire
    #
    u, v    = list(ravel(controle))
    a, b, c = list(ravel(coefficients))
    x_points = (-5, 0, 1, 3, 10)
    y_points = []
    for x in x_points:
        y_points.append( (a*x*x + b*x + c + v) * u )
    return array(y_points)
#
from adao import adaoBuilder
case = adaoBuilder.New()
case.set( 'CheckingPoint', Vector = array([1., 1., 1.]), Stored=True )
case.set( 'ObservationOperator', ThreeFunctions = {
    "Direct" :ControledQuadFunction,
    "Tangent":0, # Opérateur vide (et pas None) car non utilisé
    "Adjoint":0, # Opérateur vide (et pas None) car non utilisé
    } )
case.set( "ControlInput", Vector = (1, 0) )
case.setAlgorithmParameters(
    Algorithm='ControledFunctionTest',
    Parameters={
        'NumberOfRepetition' : 15,
        'NumberOfPrintedDigits' : 3,
        'ShowElementarySummary':False,
        },
    )
case.execute()

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


     CONTROLEDFUNCTIONTEST
     =====================

     This test allows to analyze the (repetition of the) launch of some
     given simulation operator F, applied to one single vector x and to
     one control vector u as arguments, in a sequential way.
     The output shows simple statistics related to its successful execution,
     or related to the similarities of repetition of its execution.

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

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

     Characteristics of control parameter U, internally converted:
       Type...............: <class 'numpy.ndarray'>
       Length of vector...: 2
       Minimum value......: 0.000e+00
       Maximum value......: 1.000e+00
       Mean of vector.....: 5.000e-01
       Standard error.....: 5.000e-01
       L2 norm of vector..: 1.000e+00

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

===> Beginning of repeated evaluation, without activating debug

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

===> End of repeated evaluation, without deactivating debug

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

===> Launching statistical summary calculation for 15 states

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

===> Statistical analysis of the outputs obtained through sequential repeated evaluations

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

     Number of evaluations...........................: 15

     Characteristics of the whole set of outputs Y:
       Size of each of the outputs...................: 5
       Minimum value of the whole set of outputs.....: 1.000e+00
       Maximum value of the whole set of outputs.....: 1.110e+02
       Mean of vector of the whole set of outputs....: 2.980e+01
       Standard error of the whole set of outputs....: 4.123e+01

     Characteristics of the vector Ym, mean of the outputs Y:
       Size of the mean of the outputs...............: 5
       Minimum value of the mean of the outputs......: 1.000e+00
       Maximum value of the mean of the outputs......: 1.110e+02
       Mean of the mean of the outputs...............: 2.980e+01
       Standard error of the mean of the outputs.....: 4.123e+01

     Characteristics of the mean of the differences between the outputs Y and their mean Ym:
       Size of the mean of the differences...........: 5
       Minimum value of the mean of the differences..: 0.000e+00
       Maximum value of the mean of the differences..: 0.000e+00
       Mean of the mean of the differences...........: 0.000e+00
       Standard error of the mean of the differences.: 0.000e+00

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

     End of the "CONTROLEDFUNCTIONTEST" verification

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