# 14.2. Checking algorithm “*ControledFunctionTest*”¶

## 14.2.1. Description¶

This verification algorithm allows to analyze in a simple way the stability of an operator during its execution. The operator is any operator, so it can be the observation operator as well as the evolution operator , as long as it is provided in each case according to the Requirements for functions describing an operator. The operator is considered as depending on a vector variable and on a control vector variable , the two not necessarily being of the same size, and returning another vector variable .

The algorithm verifies that the operator is working correctly and that its call is compatible with its usage in ADAO algorithms. In practice, it allows to call one or several times the operator, activating or not the “debug” mode during execution.

Statistics on input and output vectors are given for each execution of operator, and an another global statistic is given at the end. The precision of printed outputs can be controlled to facilitate automatic tests of operator. It may also be useful to check the entries themselves beforehand with the intended test Checking algorithm “InputValuesTest”.

## 14.2.2. Optional and required commands¶

The general required commands, available in the editing user graphical or textual interface, are the following:

- CheckingPoint
*Vector*. The variable indicates the vector used as the state around which to perform the required check, noted and similar to the background . It is defined as a “*Vector*” or “*VectorSerie*” type object. Its availability in output is conditioned by the boolean “*Stored*” associated with input.

- ObservationOperator
*Operator*. The variable indicates the observation operator, usually noted as , which transforms the input parameters to results to be compared to observations . Its value is defined as a “*Function*” type object or a “*Matrix*” type one. In the case of “*Function*” type, different functional forms can be used, as described in the section Requirements for functions describing an operator. If there is some control included in the observation, the operator has to be applied to a pair .

- ControlInput
*Vector*. This variable indicates the control vector used to force the evolution model at each step, usually noted as . Its value is defined as a “*Vector*” or “*VectorSerie*” type object. When there is no control, it has to be a void string ‘’.

The general optional commands, available in the editing user graphical or
textual interface, are indicated in List of commands and keywords for an ADAO checking case.
Moreover, the parameters of the command “*AlgorithmParameters*” allow to choose
the specific options, described hereafter, of the algorithm. See
Description of options of an algorithm by “AlgorithmParameters” for the good use of this
command.

The options are the following:

- NumberOfPrintedDigits
*Integer value*. This key indicates the number of digits of precision for floating point printed output. The default is 5, with a minimum of 0.Example:

`{"NumberOfPrintedDigits":5}`

- NumberOfRepetition
*Integer value*. This key indicates the number of time to repeat the function evaluation. The default is 1.Example:

`{"NumberOfRepetition":3}`

- SetDebug
*Boolean value*. This variable leads to the activation, or not, of the debug mode during the function or operator evaluation. The default is “False”, the choices are “True” or “False”.Example:

`{"SetDebug":False}`

- ShowElementarySummary
*Boolean value*. This variable leads to the activation, or not, of the calculation and display of a summary at each elementary evaluation of the test. The default value is “True”, the choices are “True” or “False”.Example :

`{"ShowElementarySummary":False}`

- StoreSupplementaryCalculations
*List of names*. This list indicates the names of the supplementary variables, that can be available during or at the end of the algorithm, if they are initially required by the user. Their availability involves, potentially, costly calculations or memory consumptions. The default is then a void list, none of these variables being calculated and stored by default (excepted the unconditional variables). The possible names are in the following list (the detailed description of each named variable is given in the following part of this specific algorithmic documentation, in the sub-section “*Information and variables available at the end of the algorithm*”): [ “CurrentState”, “SimulatedObservationAtCurrentState”, ].Example :

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

## 14.2.3. Information and variables available at the end of the algorithm¶

At the output, after executing the algorithm, there are information and
variables originating from the calculation. The description of
Variables and information available at the output show the way to obtain them by the method
named `get`

, of the variable “*ADD*” of the post-processing in graphical
interface, or of the case in textual interface. The input variables, available
to the user at the output in order to facilitate the writing of post-processing
procedures, are described in the Inventory of potentially available information at the output.

**Permanent outputs (non conditional)**

The unconditional outputs of the algorithm are the following:

None

**Set of on-demand outputs (conditional or not)**

The whole set of algorithm outputs (conditional or not), sorted by alphabetical order, is the following:

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

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

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

## 14.2.4. Python (TUI) use examples¶

Here is one or more very simple examples of the proposed algorithm and its parameters, written in [DocR] Textual User Interface for ADAO (TUI/API). Moreover, when it is possible, the information given as input also allows to define an equivalent case in [DocR] Graphical User Interface for ADAO (GUI/EFICAS).

### 14.2.4.1. First example¶

This example describes the test that the given operator works properly, and
that its call proceeds in a way compatible with its common use in the ADAO
algorithms. The required information are minimal, namely here an operator
(described for the test by the command “*ObservationOperator*”), a
particular state to test it on (described for the test by
the command “*CheckingPoint*”) and a control (described for
the test by the command “*ControlInput*”), both being not necessarily of the
same size.

The test is repeated a configurable number of times, and a final statistic
makes it possible to quickly verify the operator’s good behavior. The simplest
diagnostic consists in checking, at the very end of the display, the order of
magnitude of variations in the values indicated as the mean of the differences between the
repeated outputs and their mean, under the part entitled “*Characteristics of
the mean of the differences between the outputs Y and their mean Ym*”. For a
satisfactory operator, these values should be close to the numerical zero.

```
# -*- 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()
```

The execution result is the following:

```
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. Second example¶

This new example describes the test of the correct operation of a given
operator named `ControledQuadFunction`

, available under its functional form.
It is defined by the command “*ObservationOperator*” as
Second functional form: three operators direct, tangent and adjoint (here, even with this functional form, one
can exceptionally not define the tangent and adjoint forms of the operator
because they are not useful in this test). Using the command “*CheckingPoint*”,
one add also a particular state to test the operator on, and
using the command “*ControlInput*”, one add a fixed control .

The test is arbitrarily repeated here 15 times, and a final statistic makes it
possible to quickly verify the operator’s good behavior. The simplest
diagnostic consists in checking, at the very end of the display, the order of
magnitude of variations in the values indicated as the mean of the differences
between the repeated outputs and their mean, under the part entitled
“*Characteristics of the mean of the differences between the outputs Y and
their mean Ym*”. For a satisfactory operator, these values should be close to
the numerical zero.

```
# -*- coding: utf-8 -*-
#
from numpy import array, ravel
def ControledQuadFunction( pair ):
"""
Controlled quadratic simulation
"""
coefficients, control = pair
#
u, v = list(ravel(control))
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, # Empty operator (not None) as not used
"Adjoint":0, # Empty operator (not None) as not used
} )
case.set( "ControlInput", Vector = (1, 0) )
case.setAlgorithmParameters(
Algorithm='ControledFunctionTest',
Parameters={
'NumberOfRepetition' : 15,
'NumberOfPrintedDigits' : 3,
'ShowElementarySummary':False,
},
)
case.execute()
```

The execution result is the following:

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

## 14.2.5. See also¶

References to other sections: