# 11.3. Variables and informations available at the output¶

## How to obtain the information available at the output¶

At the output, after executing data assimilation, optimization or checking study, there are variables and information originating from the calculation. The obtaining of this information is then carried out in a standardized way using the post-processing step of calculation.

The step is easily identified by the user into its ADAO definition case (by the
keyword “*UserPostAnalysis*”) or in its YACS execution scheme (by nodes or
blocks located after the calculation block, and graphically connected to the
output port “*algoResults*” of the calculation block):

- In the case where the user defines the post-processing in his ADAO case, it uses an external script file or commands in the field type “
*String*” or “*Template*”. The script it provides has a fixed variable “*ADD*” in the namespace. - In the case where the user defines the post-processing in its YACS scheme by a Python node located after the block of calculation, it should add a input port of type “
*pyobj*” named for example “*Study*”, graphically connected to the output port “*algoResults*” of the calculation block. The Python post-processing node must then start with`ADD = Study.getResults()`

.

Templates are given hereafter as Examples of Python scripts to obtain or treat the outputs. In all cases,
the post-processing of the user has in the namespace a variable whose name is
“*ADD*”, and whose only available method is named `get`

. The arguments of this
method are an output information name, as described in the
Inventory of potentially available information at the output.

For example, to have the optimal state after a data assimilation or optimization calculation, one use the following call:

```
ADD.get("Analysis")
```

This call returns a list of values of the requested notion (or, in the case of
input variables that are by nature only a unique specimen, the value itself).
One can then request a particular item in the list by the standard list commands
(especially `[-1]`

for the last, and `[:]`

for all items).

## Examples of Python scripts to obtain or treat the outputs¶

These examples present Python commands or scripts which allow to obtain or to
treat the output of an algorithm run. To help the user, they are directly
available in the user interface, when building the ADAO case in the embedded
case editor, in the “*Template*” type fields. In an equivalent way, these
commands can be integrated in an external user script (and inserted in the ADAO
case by a “*Script*” type input) or can exist as a string, including line feeds
(and inserted in the ADAO case by a “*String*” type input). Lot of variants can
be build from these simple examples, the main objective being to help the user
to elaborate the exact procedure he needs in output.

The first example (named “*AnalysisPrinter*” in the inputs of type “*Template*”
for “*UserPostAnalysis*” section) consists in printing, in the standard log
output, the value of the analysis or the optimal state, noted as
in the section [DocT] A brief introduction to Data Assimilation and Optimization. It is realized by
the commands:

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

The `numpy.ravel`

function is here to be sure that the `xa`

variable will
contain a real unidimensional vector, whatever the previous computing choices
are.

A second example (named “*AnalysisSaver*” in the inputs of type “*Template*”
for “*UserPostAnalysis*” section) consists in saving on file the value of the
analysis or the optimal state . It is realized by the
commands:

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

The chosen recording file is a text one named `/tmp/analysis.txt`

.

It is easy to combine these two examples by building a third one (named
“*AnalysisPrinterAndSaver*” in the inputs of type “*Template*” for
“*UserPostAnalysis*” section). It consists in simultaneously printing in the
standard log output and in saving on file the value of . It
is realized by the commands:

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

To facilitate these examples extension for user needs, we recall that all the SALOME functions are available at the same level than these commands. The user can for example request for graphical representation with the PARAVIS [1] or other modules, for computing operations driven by YACS [2] or an another module, etc.

Other usage examples are also given for STEP 4: Supplement and modify the YACS scheme, and save it of the [DocR] Graphical User Interface for ADAO (GUI/EFICAS) section, or in part [DocU] Tutorials on using the ADAO module in SALOME.

## Cross compliance of the information available at the output¶

The availability of information after the calculation is conditioned by the fact that they have been calculated or requested.

Each algorithm does not necessarily provide the same information, and not necessarily for example uses the same intermediate quantities. Thus, there is information that are always present such as the optimal state resulting from the calculation. The other information are only present for certain algorithms and/or if they have been requested before the execution of the calculation.

It is recalled that the user can request additional information during the
preparation of its ADAO case, using the optional control “*AlgorithmParameters*” of
ADAO case. Reference will be made to the
Description of options of an algorithm by “AlgorithmParameters” for the proper use of this
command, and to the description of each algorithm for the information available
by algorithm. One can also ask to keep some input information by changing the
boolean “* * Stored” associated with it in the edition of the ADAO case.

## Inventory of potentially available information at the output¶

The main set of potentially available information at the output is listed here regardless of algorithms, for inventory. One has to look directly to algorithm details to get full inventory.

The optimal state is an information that is always naturally available after an optimization or a data assimilation calculation. It is indicated by the following keywords:

- Analysis

List of vectors. Each element of this variable is an optimal state in optimization or an analysis in data assimilation.Example:

`Xa = ADD.get("Analysis")[-1]`

The following variables are input variables. They are made available to the
user at the output in order to facilitate the writing of post-processing
procedures, and are conditioned by a user request using a boolean “*Stored*”
at the input. All these returned input variables can be obtained with the
standard command “.get(…)”, which return the unique object given on input.

- Background
Vector. The variable indicates the background or initial vector used, previously noted as . Its value is defined as a “Vector” or “VectorSerie” type object. Its availability in output is conditioned by the boolean “Stored” associated with input.

- BackgroundError
Matrix. This indicates the background error covariance matrix, previously noted as . Its value is defined as a “Matrix” type object, a “ScalarSparseMatrix” type object, or a “DiagonalSparseMatrix” type object, as described in detail in the section Requirements to describe covariance matrices. Its availability in output is conditioned by the boolean “Stored” associated with input.

- EvolutionError
Matrix. The variable indicates the evolution error covariance matrix, usually noted as . It is defined as a “Matrix” type object, a “ScalarSparseMatrix” type object, or a “DiagonalSparseMatrix” type object, as described in detail in the section Requirements to describe covariance matrices. Its availability in output is conditioned by the boolean “Stored” associated with input.

- Observation
List of vectors. The variable indicates the observation vector used for data assimilation or optimization, and usually noted . Its value is defined as an object of type “Vector” if it is a single observation (temporal or not) or “VectorSeries” if it is a succession of observations. Its availability in output is conditioned by the boolean “Stored” associated in input.

- ObservationError
Matrix. The variable indicates the observation error covariance matrix, usually noted as . It is defined as a “Matrix” type object, a “ScalarSparseMatrix” type object, or a “DiagonalSparseMatrix” type object, as described in detail in the section Requirements to describe covariance matrices. Its availability in output is conditioned by the boolean “Stored” associated with input.

All other information are conditioned by the algorithm and/or the user requests of availability. The main ones are the following, in alphabetical order:

- APosterioriCorrelations

List of matrices. Each element is ana posteriorierror correlations matrix of the optimal state, coming from the covariance matrix. In order to get them, thisa posteriorierror covariances calculation has to be requested at the same time.Example:

`C = ADD.get("APosterioriCorrelations")[-1]`

- APosterioriCovariance

List of matrices. Each element is ana posteriorierror covariance matrix of the optimal state.Example:

`A = ADD.get("APosterioriCovariance")[-1]`

- APosterioriStandardDeviations

List of matrices. Each element is ana posteriorierror standard errors diagonal matrix of the optimal state, coming from the covariance matrix. In order to get them, thisa posteriorierror covariances calculation has to be requested at the same time.Example:

`S = ADD.get("APosterioriStandardDeviations")[-1]`

- APosterioriVariances

List of matrices. Each element is ana posteriorierror variance errors diagonal matrix of the optimal state, coming from the covariance matrix. In order to get them, thisa posteriorierror covariances calculation has to be requested at the same time.Example:

`V = ADD.get("APosterioriVariances")[-1]`

- BMA

List of vectors. Each element is a vector of difference between the background and the optimal state.Example:

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

- CostFunctionJ

List of values. Each element is a value of the chosen error function .Example:

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

- CostFunctionJb

List of values. Each element is a value of the error function , that is of the background difference part. If this part does not exist in the error function, its value is zero.Example:

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

- CostFunctionJo

List of values. Each element is a value of the error function , that is of the observation difference part.Example:

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

- CostFunctionJAtCurrentOptimum

List of values. Each element is a value of the error function . At each step, the value corresponds to the optimal state found from the beginning.Example:

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

- CostFunctionJbAtCurrentOptimum

List of values. Each element is a value of the error function . At each step, the value corresponds to the optimal state found from the beginning. If this part does not exist in the error function, its value is zero.Example:

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

- CostFunctionJoAtCurrentOptimum

List of values. Each element is a value of the error function , that is of the observation difference part. At each step, the value corresponds to the optimal state found from the beginning.Example:

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

- CurrentOptimum

List of vectors. Each element is the optimal state obtained at the usual step of the iterative algorithm procedure of the optimization algorithm. It is not necessarily the last state.Example:

`Xo = ADD.get("CurrentOptimum")[:]`

- CurrentState

List of vectors. Each element is a usual state vector used during the iterative algorithm procedure.Example:

`Xs = ADD.get("CurrentState")[:]`

- IndexOfOptimum

List of integers. Each element is the iteration index of the optimum obtained at the current step of the iterative algorithm procedure of the optimization algorithm. It is not necessarily the number of the last iteration.Example:

`i = ADD.get("IndexOfOptimum")[-1]`

- Innovation

List of vectors. Each element is an innovation vector, which is in static the difference between the optimal and the background, and in dynamic the evolution increment.Example:

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

- InnovationAtCurrentState

List of vectors. Each element is an innovation vector at current state before analysis.Example:

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

- OMA

List of vectors. Each element is a vector of difference between the observation and the optimal state in the observation space.Example:

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

- OMB

List of vectors. Each element is a vector of difference between the observation and the background state in the observation space.Example:

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

- Residu

List of values. Each element is the value of the particular residue checked during the running of the algorithm, in the order of the tests.Example:

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

- SimulatedObservationAtBackground

List of vectors. Each element is a vector of observation simulated by the observation operator from the background . It is the forecast from the background, and it is sometimes called “Dry”.Example:

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

- SimulatedObservationAtCurrentOptimum

List of vectors. Each element is a vector of observation simulated from the optimal state obtained at the current step the optimization algorithm, that is, in the observation space.Example:

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

- SimulatedObservationAtCurrentState

List of vectors. Each element is an observed vector simulated by the observation operator from the current state, that is, in the observation space.Example:

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

- SimulatedObservationAtOptimum

List of vectors. Each element is a vector of observation obtained by the observation operator from simulation on the analysis or optimal state . It is the observed forecast from the analysis or the optimal state, and it is sometimes called “Forecast”.Example:

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

- SimulationQuantiles

List of vector series. Each element is a series of observation column vectors, corresponding, for a particular quantile required by the user, to the observed state that achieves the requested quantile. Each observation column vector is rendered in the same order as the quantile values required by the user.Example:

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

[1] | For more information on PARAVIS, see the PARAVIS module and its integrated help available from the main menu Help of the SALOME platform. |

[2] | For more information on YACS, see the YACS module and its integrated help available from the main menu Help of the SALOME platform. |