11.3. Variables et informations disponibles en sortie¶

11.3.1. Comment obtenir les informations disponibles en sortie¶

En sortie, après exécution d’une assimilation de données, d’une optimisation ou d’une vérification, on dispose de variables et d’informations issues du calcul. L’obtention de ces informations se fait ensuite de manière standardisée à l’aide de l’étape de post-processing du calcul.

L’étape est aisément identifiée par l’utilisateur dans son cas ADAO de définition (par le mot-clé « UserPostAnalysis ») ou dans son schéma YACS d’exécution (par des noeuds ou blocs situés après le bloc de calcul, et reliés graphiquement au port de sortie « algoResults » du bloc de calcul):

Dans le cas où l’utilisateur définit le post-processing dans son cas ADAO, il utilise un fichier script externe ou des commandes dans le champ de type « String » ou « Template ». Le script qu’il fournit dispose d’une variable fixe « ADD » dans l’espace de noms.
Dans le cas où l’utilisateur définit le post-processing dans son schéma YACS par un noeud Python situé après le bloc de calcul, il doit ajouter un port d’entrée de type « pyobj » nommé par exemple « Study », relié graphiquement au port de sortie « algoResults » du bloc de calcul. Le noeud Python de post-processing doit ensuite débuter par ADD = Study.getResults().

Des patrons (ou « templates ») sont donnés ci-après en Exemples de scripts Python pour obtenir ou traiter les sorties. Dans tous les cas, le post-processing de l’utilisateur dispose dans l’espace de noms d’une variable dont le nom est « ADD », et dont l’unique méthode utilisable est nommée get. Les arguments de cette méthode sont un nom d’information de sortie, comme décrit dans l”Inventaire des informations potentiellement disponibles en sortie.

Par exemple, pour avoir l’état optimal après un calcul d’assimilation de données ou d’optimisation, on utilise l’appel suivant:

ADD.get("Analysis")

Cet appel renvoie une liste de valeurs de la notion demandée (ou, dans le cas de variables d’entrées qui ne sont par nature qu’en un unique exemplaire, la valeur elle-même). On peut alors demander un élément particulier de la liste par les commandes standards de liste (en particulier [-1] pour le dernier, et [:] pour tous les éléments).

11.3.2. Exemples de scripts Python pour obtenir ou traiter les sorties¶

Ces exemples présentent des commandes ou scripts Python qui permettent d’obtenir ou de traiter les sorties d’une exécution d’algorithme. Pour aider l’utilisateur, ils sont directement disponibles dans l’interface, à la construction du cas ADAO dans l’éditeur intégré de cas, dans les champs de type « Template ». De manière équivalente, ces commandes peuvent être contenues dans un script utilisateur externe (et insérées dans le cas ADAO par l’entrée de type « Script ») ou contenues dans une chaîne de caractères, y compris les retours à la ligne (et insérées dans le cas ADAO par l’entrée de type « String »). De nombreuses variantes peuvent être imaginées à partir de ces exemples simples, l’objectif étant surtout d’aider l’utilisateur à effectuer le traitement exact dont il a besoin en sortie.

Le premier exemple (appelé « AnalysisPrinter » dans les entrées de type « Template » pour la section « UserPostAnalysis ») consiste à afficher, dans la sortie standard d’exécution, la valeur de l’analyse ou de l’état optimal, noté $\mathbf{x}^a$ dans la partie [DocT] Une brève introduction à l’Assimilation de Données et à l’Optimisation. Cela se réalise par les commandes:

import numpy
xa=numpy.ravel(ADD.get('Analysis')[-1])
print('Analysis:',xa)

La fonction numpy.ravel assure simplement que la variable xa contienne un vrai vecteur unidimensionnel, quels que soient les choix informatiques précédents.

Un second exemple (appelé « AnalysisSaver » dans les entrées de type « Template » pour la section « UserPostAnalysis ») consiste à enregistrer sur fichier la valeur de l’analyse ou de l’état optimal $\mathbf{x}^a$ . Cela se réalise par les commandes:

import numpy
xa=numpy.ravel(ADD.get('Analysis')[-1])
f='/tmp/analysis.txt'
print('Analysis saved in "%s"'%f)
numpy.savetxt(f,xa)"

Le fichier d’enregistrement choisi est un fichier texte /tmp/analysis.txt.

Il est aisé de combiner ces deux exemples pour en construire un troisième (appelé « AnalysisPrinterAndSaver » dans les entrées de type « Template » pour la section « UserPostAnalysis »). Il consiste à simultanément afficher dans la sortie standard d’exécution et à enregistrer sur fichier la valeur de $\mathbf{x}^a$ . Cela se réalise par les commandes:

import numpy
xa=numpy.ravel(ADD.get('Analysis')[-1])
print('Analysis:',xa)
f='/tmp/analysis.txt'
print('Analysis saved in "%s"'%f)
numpy.savetxt(f,xa)

Pour faciliter l’extension de ces exemples selon les besoins utilisateurs, on rappelle que l’ensemble des fonctions de SALOME sont disponibles au même niveau que ces commandes. L’utilisateur peut en particulier requérir des actions de représentation graphique avec le module PARAVIS 1 ou d’autres modules, des actions de calcul pilotés par YACS 2 ou un autre module, etc.

D’autres exemples d’utilisation sont aussi donnés en ÉTAPE 4 : Compléter et modifier le schéma YACS, et l’enregistrer de la partie [DocR] Interface graphique pour l’utilisateur (GUI/EFICAS), ou en partie [DocU] Tutoriaux sur l’utilisation du module ADAO dans SALOME.

11.3.3. Conditionnalité des informations disponibles en sortie¶

La disponibilité des informations après le calcul est conditionnée par le fait qu’elles aient été calculées ou demandées.

Chaque algorithme ne fournit pas obligatoirement les mêmes informations, et n’utilise par exemple pas nécessairement les mêmes quantités intermédiaires. Il y a donc des informations toujours présentes comme l’état optimal résultant du calcul. Les autres informations ne sont présentes que pour certains algorithmes et/ou que si elles ont été réclamées avant l’exécution du calcul.

On rappelle que l’utilisateur peut réclamer des informations supplémentaires lors de l’établissement de son cas ADAO, en utilisant la commande optionnelle « AlgorithmParameters » du cas ADAO. On se reportera à la Description des options d’un algorithme par « AlgorithmParameters » pour le bon usage de cette commande, et à la description de chaque algorithme pour les informations disponibles par algorithme. On peut aussi demander à conserver certaines informations en entrée en changeant le booléen « Stored » qui lui est associé dans l’édition du cas ADAO.

11.3.4. Inventaire des informations potentiellement disponibles en sortie¶

Les principales informations potentiellement disponibles en sortie sont indiquées ici indépendamment des algorithmes, pour inventaire. On se reportera directement aux détails des algorithmes pour avoir l’inventaire exhaustif.

L’état optimal est une information qui est toujours naturellement disponible après un calcul d’assimilation de données ou d’optimisation. Il désigné par le mot-clé suivant:

Analysis
Liste de vecteurs. Chaque élément de cette variable est un état optimal $\mathbf{x}^*$ en optimisation, une interpolation ou une analyse $\mathbf{x}^a$ en assimilation de données.

Exemple : xa = ADD.get("Analysis")[-1]

Les variables suivantes sont des variables d’entrée que l’on peut aussi obtenir en sortie. Elles sont mises à disposition de l’utilisateur en sortie pour faciliter l’écriture des procédures de post-processing, et sont conditionnées par une demande utilisateur explicite à l’aide d’un booléen « Stored » en entrée. Toutes ces variables d’entrée restituées sont obtenables par la commande standard « .get(…) », qui s’applique à refournir l’unique objet donné en entrée.

Background
Vecteur. La variable désigne le vecteur d’ébauche ou d’initialisation, usuellement noté $\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.

BackgroundError
Matrice. La variable désigne la matrice de covariance des erreurs d’ébauche, usuellement notée $\mathbf{B}$ . Sa valeur est définie comme un objet de type « Matrix », de type « ScalarSparseMatrix », ou de type « DiagonalSparseMatrix », comme décrit en détail dans la section Conditions requises pour décrire des matrices de covariance. Sa disponibilité en sortie est conditionnée par le booléen « Stored » associé en entrée.

EvolutionError
Matrice. La variable désigne la matrice de covariance des erreurs a priori d’évolution, usuellement notée $\mathbf{Q}$ . Sa valeur est définie comme un objet de type « Matrix », de type « ScalarSparseMatrix », ou de type « DiagonalSparseMatrix », comme décrit en détail dans la section Conditions requises pour décrire des matrices de covariance. 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.

ObservationError
Matrice. La variable désigne la matrice de covariance des erreurs a priori d’ébauche, usuellement notée $\mathbf{R}$ . Cette matrice est définie comme un objet de type « Matrix », de type « ScalarSparseMatrix », ou de type « DiagonalSparseMatrix », comme décrit en détail dans la section Conditions requises pour décrire des matrices de covariance. Sa disponibilité en sortie est conditionnée par le booléen « Stored » associé en entrée.

Toutes les autres informations sont conditionnées par l’algorithme et/ou par la demande utilisateur de disponibilité. Les principales sont les suivantes, par ordre alphabétique:

APosterioriCorrelations
Liste de matrices. Chaque élément est une matrice de corrélations des erreurs a posteriori de l’état optimal, issue de la matrice $\mathbf{A}$ des covariances. Pour en disposer, il faut avoir en même temps demandé le calcul de ces covariances d’erreurs a posteriori.

Exemple : apc = ADD.get("APosterioriCorrelations")[-1]

APosterioriCovariance
Liste de matrices. Chaque élément est une matrice $\mathbf{A}$ de covariances des erreurs a posteriori de l’état optimal.

Exemple : apc = ADD.get("APosterioriCovariance")[-1]

APosterioriStandardDeviations
Liste de matrices. Chaque élément est une matrice diagonale d’écarts-types des erreurs a posteriori de l’état optimal, issue de la matrice $\mathbf{A}$ des covariances. Pour en disposer, il faut avoir en même temps demandé le calcul de ces covariances d’erreurs a posteriori.

Exemple : aps = ADD.get("APosterioriStandardDeviations")[-1]

APosterioriVariances
Liste de matrices. Chaque élément est une matrice diagonale de variances des erreurs a posteriori de l’état optimal, issue de la matrice $\mathbf{A}$ des covariances. Pour en disposer, il faut avoir en même temps demandé le calcul de ces covariances d’erreurs a posteriori.

Exemple : apv = ADD.get("APosterioriVariances")[-1]

BMA
Liste de vecteurs. Chaque élément est un vecteur d’écart entre l’ébauche et l’état optimal.

Exemple : bma = ADD.get("BMA")[-1]

CostFunctionJ
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J$ choisie.

Exemple : J = ADD.get("CostFunctionJ")[:]

CostFunctionJb
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J^b$ , c’est-à-dire de la partie écart à l’ébauche. Si cette partie n’existe pas dans la fonctionnelle, sa valeur est nulle.

Exemple : Jb = ADD.get("CostFunctionJb")[:]

CostFunctionJo
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J^o$ , c’est-à-dire de la partie écart à l’observation.

Exemple : Jo = ADD.get("CostFunctionJo")[:]

CostFunctionJAtCurrentOptimum
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J$ . A chaque pas, la valeur correspond à l’état optimal trouvé depuis le début.

Exemple : JACO = ADD.get("CostFunctionJAtCurrentOptimum")[:]

CostFunctionJbAtCurrentOptimum
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J^b$ , c’est-à-dire de la partie écart à l’ébauche. A chaque pas, la valeur correspond à l’état optimal trouvé depuis le début. Si cette partie n’existe pas dans la fonctionnelle, sa valeur est nulle.

Exemple : JbACO = ADD.get("CostFunctionJbAtCurrentOptimum")[:]

CostFunctionJoAtCurrentOptimum
Liste de valeurs. Chaque élément est une valeur de fonctionnelle d’écart $J^o$ , c’est-à-dire de la partie écart à l’observation. A chaque pas, la valeur correspond à l’état optimal trouvé depuis le début.

Exemple : JoACO = ADD.get("CostFunctionJoAtCurrentOptimum")[:]

CurrentOptimum
Liste de vecteurs. Chaque élément est le vecteur d’état optimal au pas de temps courant au cours du déroulement itératif de l’algorithme d’optimisation utilisé. Ce n’est pas nécessairement le dernier état.

Exemple : xo = ADD.get("CurrentOptimum")[:]

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

IndexOfOptimum
Liste d’entiers. Chaque élément est l’index d’itération de l’optimum obtenu au cours du déroulement itératif de l’algorithme d’optimisation utilisé. Ce n’est pas nécessairement le numéro de la dernière itération.

Exemple : ioo = ADD.get("IndexOfOptimum")[-1]

Innovation
Liste de vecteurs. Chaque élément est un vecteur d’innovation, qui est en statique l’écart de l’optimum à l’ébauche, et en dynamique l’incrément d’évolution.

Exemple : d = ADD.get("Innovation")[-1]

InnovationAtCurrentState
Liste de vecteurs. Chaque élément est un vecteur d’innovation à l’état courant avant analyse.

Exemple : ds = ADD.get("InnovationAtCurrentState")[-1]

OMA
Liste de vecteurs. Chaque élément est un vecteur d’écart entre l’observation et l’état optimal dans l’espace des observations.

Exemple : oma = ADD.get("OMA")[-1]

OMB
Liste de vecteurs. Chaque élément est un vecteur d’écart entre l’observation et l’état d’ébauche dans l’espace des observations.

Exemple : omb = ADD.get("OMB")[-1]

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

SimulatedObservationAtBackground
Liste de vecteurs. Chaque élément est un vecteur d’observation simulé par l’opérateur d’observation à partir de l’ébauche $\mathbf{x}^b$ . C’est la prévision à partir de l’ébauche, elle est parfois appelée « Dry ».

Exemple : hxb = ADD.get("SimulatedObservationAtBackground")[-1]

SimulatedObservationAtCurrentOptimum
Liste de vecteurs. Chaque élément est un vecteur d’observation simulé par l’opérateur d’observation à partir de l’état optimal au pas de temps courant au cours du déroulement de l’algorithme d’optimisation, c’est-à-dire dans l’espace des observations.

Exemple : hxo = ADD.get("SimulatedObservationAtCurrentOptimum")[-1]

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]

SimulatedObservationAtOptimum
Liste de vecteurs. Chaque élément est un vecteur d’observation obtenu par l’opérateur d’observation à partir de la simulation d’analyse ou d’état optimal $\mathbf{x}^a$ . C’est l’observation de la prévision à partir de l’analyse ou de l’état optimal, et elle est parfois appelée « Forecast ».

Exemple : hxa = ADD.get("SimulatedObservationAtOptimum")[-1]

SimulationQuantiles
Liste de séries de vecteurs. Chaque élément est une série de vecteurs colonnes d’observation, correspondant, pour un quantile particulier requis par l’utilisateur, à l’état observé qui réalise le quantile demandé. Chaque vecteur colonne d’observation est restitué dans le même ordre que les valeurs de quantiles requis par l’utilisateur.

Exemple : sQuantiles = ADD.get("SimulationQuantiles")[:]

1: Pour de plus amples informations sur PARAVIS, voir le module PARAVIS et son aide intégrée disponible dans le menu principal Aide de l’environnement SALOME.
2: Pour de plus amples informations sur YACS, voir le module YACS et son aide intégrée disponible dans le menu principal Aide de l’environnement SALOME.