From aaa6766e31efe63b025c3476f73e880ef29c4dc8 Mon Sep 17 00:00:00 2001 From: Jean-Philippe ARGAUD Date: Tue, 5 Mar 2019 15:45:24 +0100 Subject: [PATCH] Updating documentation by review and snippets (6): EN part --- doc/en/ref_assimilation_keywords.rst | 130 +++++------------- doc/en/ref_checking_keywords.rst | 85 ++++-------- doc/en/snippets/ASSIMILATION_STUDY.rst | 6 + doc/en/snippets/AlgorithmParameters.rst | 13 ++ doc/en/snippets/CHECKING_STUDY.rst | 5 + doc/en/snippets/ControlInput.rst | 7 + doc/en/snippets/Debug.rst | 6 + doc/en/snippets/Header2Algo00.rst | 4 + doc/en/snippets/Header2Algo01.rst | 2 + doc/en/snippets/Header2Algo02.rst | 5 + doc/en/snippets/Header2Algo03AdOp.rst | 8 ++ doc/en/snippets/Header2Algo03Chck.rst | 8 ++ doc/en/snippets/Header2Algo04.rst | 12 ++ doc/en/snippets/Header2Algo05.rst | 1 + doc/en/snippets/Header2Algo06.rst | 4 + doc/en/snippets/Header2Algo07.rst | 1 + doc/en/snippets/Header2Algo08.rst | 1 + doc/en/snippets/InputVariables.rst | 6 + .../snippets/JacobianMatrixAtBackground.rst | 10 ++ .../snippets/JacobianMatrixAtCurrentState.rst | 10 ++ doc/en/snippets/JacobianMatrixAtOptimum.rst | 10 ++ doc/en/snippets/KalmanGainAtOptimum.rst | 9 ++ doc/en/snippets/OutputVariables.rst | 6 + doc/en/snippets/StudyName.rst | 5 + doc/en/snippets/StudyRepertory.rst | 6 + doc/en/snippets/UserDataInit.rst | 7 + doc/en/snippets/UserPostAnalysis.rst | 9 ++ 27 files changed, 219 insertions(+), 157 deletions(-) create mode 100644 doc/en/snippets/ASSIMILATION_STUDY.rst create mode 100644 doc/en/snippets/AlgorithmParameters.rst create mode 100644 doc/en/snippets/CHECKING_STUDY.rst create mode 100644 doc/en/snippets/ControlInput.rst create mode 100644 doc/en/snippets/Debug.rst create mode 100644 doc/en/snippets/Header2Algo00.rst create mode 100644 doc/en/snippets/Header2Algo01.rst create mode 100644 doc/en/snippets/Header2Algo02.rst create mode 100644 doc/en/snippets/Header2Algo03AdOp.rst create mode 100644 doc/en/snippets/Header2Algo03Chck.rst create mode 100644 doc/en/snippets/Header2Algo04.rst create mode 100644 doc/en/snippets/Header2Algo05.rst create mode 100644 doc/en/snippets/Header2Algo06.rst create mode 100644 doc/en/snippets/Header2Algo07.rst create mode 100644 doc/en/snippets/Header2Algo08.rst create mode 100644 doc/en/snippets/InputVariables.rst create mode 100644 doc/en/snippets/JacobianMatrixAtBackground.rst create mode 100644 doc/en/snippets/JacobianMatrixAtCurrentState.rst create mode 100644 doc/en/snippets/JacobianMatrixAtOptimum.rst create mode 100644 doc/en/snippets/KalmanGainAtOptimum.rst create mode 100644 doc/en/snippets/OutputVariables.rst create mode 100644 doc/en/snippets/StudyName.rst create mode 100644 doc/en/snippets/StudyRepertory.rst create mode 100644 doc/en/snippets/UserDataInit.rst create mode 100644 doc/en/snippets/UserPostAnalysis.rst diff --git a/doc/en/ref_assimilation_keywords.rst b/doc/en/ref_assimilation_keywords.rst index 1848a96..d019304 100644 --- a/doc/en/ref_assimilation_keywords.rst +++ b/doc/en/ref_assimilation_keywords.rst @@ -27,21 +27,6 @@ List of commands and keywords for an ADAO calculation case ---------------------------------------------------------- -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: ControlInput -.. index:: single: Debug -.. index:: single: InputVariables -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: OutputVariables -.. index:: single: StudyName -.. index:: single: StudyRepertory -.. index:: single: UserDataInit -.. index:: single: UserPostAnalysis -.. index:: single: UserPostAnalysis Template - This set of commands is related to the description of a calculation case, that is a *Data Assimilation* procedure or an *Optimization* procedure. The terms are ordered in alphabetical order, except the first, which describes @@ -49,83 +34,38 @@ choice between calculation or checking. The different commands are the following: - **ASSIMILATION_STUDY** - *Required command*. This is the general command describing the data - assimilation or optimization case. It hierarchically contains all the other - commands. - - AlgorithmParameters - *Required command*. This indicates the data assimilation or optimization - algorithm chosen by the keyword "*Algorithm*", and its potential optional - parameters. The algorithm choices are available through the GUI. There - exists for example "3DVAR", "Blue"... Each algorithm is defined, below, by a - specific subsection. Optionally, the command allows also to add some - parameters to control the algorithm. Their values are defined either - explicitly or in a "*Dict*" type object. See the - :ref:`section_ref_options_Algorithm_Parameters` for the detailed use of this - command part. - - .. include:: snippets/Background.rst - - .. include:: snippets/BackgroundError.rst - - ControlInput - *Optional command*. This indicates the control vector used to force the - evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value - is defined as a "*Vector*" or a *VectorSerie* type object. When there is no - control, it has to be a void string ''. - - Debug - *Optional command*. This define the level of trace and intermediary debug - information. The choices are limited between 0 (for False) and 1 (for - True). - - .. include:: snippets/EvolutionError.rst - - .. include:: snippets/EvolutionModel.rst - - InputVariables - *Optional command*. This command 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. - - .. include:: snippets/Observation.rst - - .. include:: snippets/ObservationError.rst - - .. include:: snippets/ObservationOperator.rst - - Observers - *Optional command*. 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 command 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 - *Required command*. This is an open string to describe the ADAO study by a - name or a sentence. - - StudyRepertory - *Optional command*. If available, this directory is used as base name for - calculation, and used to find all the script files, given by name without - path, that can be used to define some other commands by scripts. - - UserDataInit - *Optional command*. This commands 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 - *Optional command*. This commands allows to process some parameters or data - automatically after data assimilation or optimization algorithm processing. - Its value is defined as a script file or 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. +.. include:: snippets/ASSIMILATION_STUDY.rst + +.. include:: snippets/AlgorithmParameters.rst + +.. include:: snippets/Background.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/ControlInput.rst + +.. include:: snippets/Debug.rst + +.. include:: snippets/EvolutionError.rst + +.. include:: snippets/EvolutionModel.rst + +.. include:: snippets/InputVariables.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. include:: snippets/Observers.rst + +.. include:: snippets/OutputVariables.rst + +.. include:: snippets/StudyName.rst + +.. include:: snippets/StudyRepertory.rst + +.. include:: snippets/UserDataInit.rst + +.. include:: snippets/UserPostAnalysis.rst diff --git a/doc/en/ref_checking_keywords.rst b/doc/en/ref_checking_keywords.rst index bb38c9b..7a72535 100644 --- a/doc/en/ref_checking_keywords.rst +++ b/doc/en/ref_checking_keywords.rst @@ -27,16 +27,6 @@ List of commands and keywords for an ADAO checking case ------------------------------------------------------- -.. index:: single: Algorithm -.. index:: single: AlgorithmParameters -.. index:: single: Debug -.. index:: single: Observer -.. index:: single: Observers -.. index:: single: Observer Template -.. index:: single: StudyName -.. index:: single: StudyRepertory -.. index:: single: UserDataInit - This set of commands is related to the description of a checking case, that is a procedure to check required properties on information, used somewhere else by a calculation case. The terms are ordered in alphabetical order, except the first, @@ -44,55 +34,26 @@ which describes the choice between calculation or checking. The different commands are the following: - **CHECKING_STUDY** - *Required command*. This is the general command describing the checking - case. It hierarchically contains all the other commands. - - AlgorithmParameters - *Required command*. This indicates the checking algorithm chosen by the - keyword "*Algorithm*", and its potential optional parameters. The algorithm - choices are available through the GUI. There exists for example - "FunctionTest", "GradientTest"... Each algorithm is defined, below, by a - specific subsection. Optionaly, the command allows also to add some - parameters to control the algorithm. Their values are defined either - explicitly or in a "*Dict*" type object. See the - :ref:`section_ref_options_Algorithm_Parameters` for the detailed use of this - command part. - - .. include:: snippets/CheckingPoint.rst - - .. include:: snippets/BackgroundError.rst - - Debug - *Optional command*. This define the level of trace and intermediary debug - information. The choices are limited between 0 (for False) and 1 (for - True). - - .. include:: snippets/Observation.rst - - .. include:: snippets/ObservationError.rst - - .. include:: snippets/ObservationOperator.rst - - Observers - *Optional command*. 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. - - StudyName - *Required command*. This is an open string to describe the ADAO study by a - name or a sentence. - - StudyRepertory - *Optional command*. If available, this directory is used as base name for - calculation, and used to find all the script files, given by name without - path, that can be used to define some other commands by scripts. - - UserDataInit - *Optional command*. This commands 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. +.. include:: snippets/CHECKING_STUDY.rst + +.. include:: snippets/AlgorithmParameters.rst + +.. include:: snippets/CheckingPoint.rst + +.. include:: snippets/BackgroundError.rst + +.. include:: snippets/Debug.rst + +.. include:: snippets/Observation.rst + +.. include:: snippets/ObservationError.rst + +.. include:: snippets/ObservationOperator.rst + +.. include:: snippets/Observers.rst + +.. include:: snippets/StudyName.rst + +.. include:: snippets/StudyRepertory.rst + +.. include:: snippets/UserDataInit.rst diff --git a/doc/en/snippets/ASSIMILATION_STUDY.rst b/doc/en/snippets/ASSIMILATION_STUDY.rst new file mode 100644 index 0000000..458414f --- /dev/null +++ b/doc/en/snippets/ASSIMILATION_STUDY.rst @@ -0,0 +1,6 @@ +.. index:: single: ASSIMILATION_STUDY + +**ASSIMILATION_STUDY** + *Required command*. This is the general command describing the data + assimilation or optimization case. It hierarchically contains all the other + commands. diff --git a/doc/en/snippets/AlgorithmParameters.rst b/doc/en/snippets/AlgorithmParameters.rst new file mode 100644 index 0000000..64674f4 --- /dev/null +++ b/doc/en/snippets/AlgorithmParameters.rst @@ -0,0 +1,13 @@ +.. index:: single: Algorithm +.. index:: single: AlgorithmParameters + +AlgorithmParameters + *Required command*. This indicates the data assimilation or optimization + algorithm chosen by the keyword "*Algorithm*", and its potential optional + parameters. The algorithm choices are available through the GUI. There + exists for example "3DVAR", "Blue"... Each algorithm is defined, below, by a + specific subsection. Optionally, the command allows also to add some + parameters to control the algorithm. Their values are defined either + explicitly or in a "*Dict*" type object. See the + :ref:`section_ref_options_Algorithm_Parameters` for the detailed use of this + command part. diff --git a/doc/en/snippets/CHECKING_STUDY.rst b/doc/en/snippets/CHECKING_STUDY.rst new file mode 100644 index 0000000..81236f7 --- /dev/null +++ b/doc/en/snippets/CHECKING_STUDY.rst @@ -0,0 +1,5 @@ +.. index:: single: CHECKING_STUDY + +**CHECKING_STUDY** + *Required command*. This is the general command describing the checking + case. It hierarchically contains all the other commands. diff --git a/doc/en/snippets/ControlInput.rst b/doc/en/snippets/ControlInput.rst new file mode 100644 index 0000000..2d91ce3 --- /dev/null +++ b/doc/en/snippets/ControlInput.rst @@ -0,0 +1,7 @@ +.. index:: single: ControlInput + +ControlInput + *Optional command*. This indicates the control vector used to force the + evolution model at each step, usually noted as :math:`\mathbf{U}`. Its value + is defined as a "*Vector*" or a *VectorSerie* type object. When there is no + control, it has to be a void string ''. diff --git a/doc/en/snippets/Debug.rst b/doc/en/snippets/Debug.rst new file mode 100644 index 0000000..126edb1 --- /dev/null +++ b/doc/en/snippets/Debug.rst @@ -0,0 +1,6 @@ +.. index:: single: Debug + +Debug + *Optional command*. This define the level of trace and intermediary debug + information. The choices are limited between 0 (for False) and 1 (for + True). diff --git a/doc/en/snippets/Header2Algo00.rst b/doc/en/snippets/Header2Algo00.rst new file mode 100644 index 0000000..95d3520 --- /dev/null +++ b/doc/en/snippets/Header2Algo00.rst @@ -0,0 +1,4 @@ +.. warning:: + + in its present version, this algorithm is experimental, and so changes can be + required in forthcoming versions. diff --git a/doc/en/snippets/Header2Algo01.rst b/doc/en/snippets/Header2Algo01.rst new file mode 100644 index 0000000..76ed395 --- /dev/null +++ b/doc/en/snippets/Header2Algo01.rst @@ -0,0 +1,2 @@ +Description ++++++++++++ diff --git a/doc/en/snippets/Header2Algo02.rst b/doc/en/snippets/Header2Algo02.rst new file mode 100644 index 0000000..5d20770 --- /dev/null +++ b/doc/en/snippets/Header2Algo02.rst @@ -0,0 +1,5 @@ +Optional and required commands +++++++++++++++++++++++++++++++ + +The general required commands, available in the editing user graphical or +textual interface, are the following: diff --git a/doc/en/snippets/Header2Algo03AdOp.rst b/doc/en/snippets/Header2Algo03AdOp.rst new file mode 100644 index 0000000..255ef17 --- /dev/null +++ b/doc/en/snippets/Header2Algo03AdOp.rst @@ -0,0 +1,8 @@ +The general optional commands, available in the editing user graphical or +textual interface, are indicated in :ref:`section_ref_assimilation_keywords`. +Moreover, the parameters of the command "*AlgorithmParameters*" allows to +choose the specific options, described hereafter, of the algorithm. See +:ref:`section_ref_options_Algorithm_Parameters` for the good use of this +command. + +The options of the algorithm are the following: diff --git a/doc/en/snippets/Header2Algo03Chck.rst b/doc/en/snippets/Header2Algo03Chck.rst new file mode 100644 index 0000000..b7fbc3e --- /dev/null +++ b/doc/en/snippets/Header2Algo03Chck.rst @@ -0,0 +1,8 @@ +The general optional commands, available in the editing user graphical or +textual interface, are indicated in :ref:`section_ref_checking_keywords`. +Moreover, the parameters of the command "*AlgorithmParameters*" allow to choose +the specific options, described hereafter, of the algorithm. See +:ref:`section_ref_options_Algorithm_Parameters` for the good use of this +command. + +The options of the algorithm are the following: diff --git a/doc/en/snippets/Header2Algo04.rst b/doc/en/snippets/Header2Algo04.rst new file mode 100644 index 0000000..08bb3fa --- /dev/null +++ b/doc/en/snippets/Header2Algo04.rst @@ -0,0 +1,12 @@ +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 +:ref:`section_ref_output_variables` 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 :ref:`subsection_r_o_v_Inventaire`. + +The unconditional outputs of the algorithm are the following: diff --git a/doc/en/snippets/Header2Algo05.rst b/doc/en/snippets/Header2Algo05.rst new file mode 100644 index 0000000..ed4d265 --- /dev/null +++ b/doc/en/snippets/Header2Algo05.rst @@ -0,0 +1 @@ +The conditional outputs of the algorithm are the following: diff --git a/doc/en/snippets/Header2Algo06.rst b/doc/en/snippets/Header2Algo06.rst new file mode 100644 index 0000000..9208fa5 --- /dev/null +++ b/doc/en/snippets/Header2Algo06.rst @@ -0,0 +1,4 @@ +See also +++++++++ + +References to other sections: diff --git a/doc/en/snippets/Header2Algo07.rst b/doc/en/snippets/Header2Algo07.rst new file mode 100644 index 0000000..67f929f --- /dev/null +++ b/doc/en/snippets/Header2Algo07.rst @@ -0,0 +1 @@ +Bibliographical references: diff --git a/doc/en/snippets/Header2Algo08.rst b/doc/en/snippets/Header2Algo08.rst new file mode 100644 index 0000000..1425eaf --- /dev/null +++ b/doc/en/snippets/Header2Algo08.rst @@ -0,0 +1 @@ +References to other SALOME modules: diff --git a/doc/en/snippets/InputVariables.rst b/doc/en/snippets/InputVariables.rst new file mode 100644 index 0000000..5b93ac7 --- /dev/null +++ b/doc/en/snippets/InputVariables.rst @@ -0,0 +1,6 @@ +.. index:: single: InputVariables + +InputVariables + *Optional command*. This command 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. diff --git a/doc/en/snippets/JacobianMatrixAtBackground.rst b/doc/en/snippets/JacobianMatrixAtBackground.rst new file mode 100644 index 0000000..4ae42b1 --- /dev/null +++ b/doc/en/snippets/JacobianMatrixAtBackground.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtBackground + +JacobianMatrixAtBackground + *List of matrices*. Each element is the jacobian matrix of partial + derivatives of the output of the observation operator with respect to the + input parameters, one column of derivatives per parameter. It is calculated + at the initial state. + + Example: + ``GradH = ADD.get("JacobianMatrixAtBackground")[-1]`` diff --git a/doc/en/snippets/JacobianMatrixAtCurrentState.rst b/doc/en/snippets/JacobianMatrixAtCurrentState.rst new file mode 100644 index 0000000..0a6984d --- /dev/null +++ b/doc/en/snippets/JacobianMatrixAtCurrentState.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtCurrentState + +JacobianMatrixAtCurrentState + *List of matrices*. Each element is the jacobian matrix of partial + derivatives of the output of the observation operator with respect to the input + parameters, one column of derivatives per parameter. It is calculated at the + current state. + + Example: + ``GradH = ADD.get("JacobianMatrixAtCurrentState")[-1]`` diff --git a/doc/en/snippets/JacobianMatrixAtOptimum.rst b/doc/en/snippets/JacobianMatrixAtOptimum.rst new file mode 100644 index 0000000..b2487e2 --- /dev/null +++ b/doc/en/snippets/JacobianMatrixAtOptimum.rst @@ -0,0 +1,10 @@ +.. index:: single: JacobianMatrixAtOptimum + +JacobianMatrixAtOptimum + *List of matrices*. Each element is the jacobian matrix of partial + derivatives of the output of the observation operator with respect to the + input parameters, one column of derivatives per parameter. It is calculated + at the optimal state. + + Example: + ``GradH = ADD.get("JacobianMatrixAtOptimum")[-1]`` diff --git a/doc/en/snippets/KalmanGainAtOptimum.rst b/doc/en/snippets/KalmanGainAtOptimum.rst new file mode 100644 index 0000000..bd76582 --- /dev/null +++ b/doc/en/snippets/KalmanGainAtOptimum.rst @@ -0,0 +1,9 @@ +.. index:: single: KalmanGainAtOptimum + +KalmanGainAtOptimum + *List of matrices*. Each element is a standard Kalman gain matrix, evaluated + using the linearized observation operator. It is calculated at the optimal + state. + + Example: + ``KG = ADD.get("KalmanGainAtOptimum")[-1]`` diff --git a/doc/en/snippets/OutputVariables.rst b/doc/en/snippets/OutputVariables.rst new file mode 100644 index 0000000..d303cc6 --- /dev/null +++ b/doc/en/snippets/OutputVariables.rst @@ -0,0 +1,6 @@ +.. index:: single: OutputVariables + +OutputVariables + *Optional command*. This command 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. diff --git a/doc/en/snippets/StudyName.rst b/doc/en/snippets/StudyName.rst new file mode 100644 index 0000000..9790252 --- /dev/null +++ b/doc/en/snippets/StudyName.rst @@ -0,0 +1,5 @@ +.. index:: single: StudyName + +StudyName + *Required command*. This is an open string to describe the ADAO study by a + name or a sentence. diff --git a/doc/en/snippets/StudyRepertory.rst b/doc/en/snippets/StudyRepertory.rst new file mode 100644 index 0000000..f18433c --- /dev/null +++ b/doc/en/snippets/StudyRepertory.rst @@ -0,0 +1,6 @@ +.. index:: single: StudyRepertory + +StudyRepertory + *Optional command*. If available, this directory is used as base name for + calculation, and used to find all the script files, given by name without + path, that can be used to define some other commands by scripts. diff --git a/doc/en/snippets/UserDataInit.rst b/doc/en/snippets/UserDataInit.rst new file mode 100644 index 0000000..e37e23d --- /dev/null +++ b/doc/en/snippets/UserDataInit.rst @@ -0,0 +1,7 @@ +.. index:: single: UserDataInit + +UserDataInit + *Optional command*. This commands 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. diff --git a/doc/en/snippets/UserPostAnalysis.rst b/doc/en/snippets/UserPostAnalysis.rst new file mode 100644 index 0000000..9ffcfb9 --- /dev/null +++ b/doc/en/snippets/UserPostAnalysis.rst @@ -0,0 +1,9 @@ +.. index:: single: UserPostAnalysis +.. index:: single: UserPostAnalysis Template + +UserPostAnalysis + *Optional command*. This commands allows to process some parameters or data + automatically after data assimilation or optimization algorithm processing. + Its value is defined as a script file or 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. -- 2.39.2