13.17. List of commands and keywords for data assimilation or optimisation case¶

We summarize here all the commands available to describe a calculation case by avoiding the particularities of each algorithm. It is therefore a common inventory of commands.

The set of commands for an data assimilation or optimisation case is related to the description of a calculation case, that is a Data Assimilation procedure or an Optimization procedure.

The first term describes the choice between calculation or checking. In the graphical interface, each of the three types of calculation, individually more oriented to data assimilation, optimization methods or methods with reduction (some algorithms are simultaneously in various categories), is imperatively indicated by one of these commands:

ASSIMILATION_STUDY: Required command. This is the general command describing one case using data assimilation methods. In the graphical interface, it hierarchically contains all the other commands.

OPTIMIZATION_STUDY: Required command. This is the general command describing one case using optimization methods. In the graphical interface, it hierarchically contains all the other commands.

REDUCTION_STUDY: Required command. This is the general command describing one case using methods with reduction. In the graphical interface, it hierarchically contains all the other commands.

The nested terms are sorted in alphabetical order. They are not necessarily required for all algorithms. The various commands are the following:

AlgorithmParameters: Dictionary. This variable indicates the data assimilation or optimization algorithm chosen by the keyword “Algorithm”, and its potential optional parameters. The potential choices by this keyword “Algorithm” are available through the graphical interface or in the reference documentation containing a specific sub-section for each of them. There are for example the “3DVAR”, the “Blue”, etc. Optionally, the command also allows to add parameters to control the chosen algorithm. Their values are defined either explicitly or in a “Dict” type object. See the Description of options of an algorithm by “AlgorithmParameters” for the detailed use of this command part.

Background: Vector. The variable indicates the background or initial vector used, previously noted as $\mathbf{x}^b$ . 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 $\mathbf{B}$ . 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.

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

Debug: Boolean value. This variable define the level of trace and intermediary debug information. The choices are limited between 0 (for False) and 1 (for True).

EvolutionError: Matrix. The variable indicates the evolution error covariance matrix, usually noted as $\mathbf{Q}$ . 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.

EvolutionModel: Operator. The variable indicates the evolution model operator, usually noted $M$ , which describes an elementary step of evolution. 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 $U$ included in the evolution model, the operator has to be applied to a pair $(X,U)$ .

ExecuteInContainer: String. This variable allows to choose the execution mode in YACS in a specific container. In its absence or if its value is “No”, no separate container is used for execution and it runs in the main YACS process. If its value is “Mono”, a specific YACS container is created and it is used to host the execution of all nodes in the same process. If its value is “Multi”, a specific YACS container is created and it is used to host the execution of each node in a specific process. The default value is “No”, and the possible choices are “No”, “Mono” and “Multi”.

Warning

In its present version, this command is experimental, and therefore remains subject to changes in future versions.

InputVariables: Optional command. This variable allows to indicates the name and size of physical variables that are bundled together in the state vector. This information is dedicated to data processed inside an algorithm.

Observation: List of vectors. The variable indicates the observation vector used for data assimilation or optimization, and usually noted $\mathbf{y}^o$ . 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 $\mathbf{R}$ . 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.

ObservationOperator: Operator. The variable indicates the observation operator, usually noted as $H$ , which transforms the input parameters $\mathbf{x}$ to results $\mathbf{y}$ to be compared to observations $\mathbf{y}^o$ . 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 $U$ included in the observation, the operator has to be applied to a pair $(X,U)$ .

Observers: List of functions linked to variables. This command allows to set internal observers, that are functions linked with a particular variable, which will be executed each time this variable is modified. It is a convenient way to monitor variables of interest during the data assimilation or optimization process, by printing or plotting it, etc. Common templates are provided to help the user to start or to quickly make his case.

OutputVariables: Optional command. This variable allows to indicates the name and size of physical variables that are bundled together in the output observation vector. This information is dedicated to data processed inside an algorithm.

StudyName: String. This variable is an open string to identify or describe the ADAO study by a name or a sentence.

StudyRepertory: String. If available, the directory specified by this string is used as base name for calculation, and also used to find all the script files given by name without path, that can define some other commands by scripts.

UserDataInit: Script name. This variable allows to initialize some parameters or data automatically before algorithm input processing. It indicates a script file name to be executed before entering in initialization phase of chosen variables.

UserPostAnalysis: Multiline string. This variable allows to process some parameters or data automatically after data assimilation or optimization algorithm processing. Its value is defined either as a predefined pattern name, or as a script file name, or as a string, allowing to put post-processing code directly inside the ADAO case. Common templates are provided to help the user to start or to quickly make his case. We refer to the description of Requirements to describe a post-processing after an ADAO calculation for the list of templates and their format. Important note: this processing is only performed when the case is executed in TUI or exported to YACS.