.. _section_notations:
-Notations and conventions
-=========================
+Notations and common conventions
+================================
In all this documentation, we use standard notations of linear algebra, data
assimilation (as described in [Ide97]_) and optimization.
List of possible input types
----------------------------
-Each ADAO variable has a pseudo-type to help filling it and validation. These
-pseudo-types explicitly represent some simple computing or mathematical types.
-Two pseudo-types, purely computing ones, allows to designate how the input
-variables are provided:
+Each variable to be entered for the use of ADAO can be represented by means of
+particular "pseudo-types", which help to logically fill it in and validate it
+computationaly. These pseudo-types explicitly represent mathematical forms
+(:ref:`section_ref_entry_types_math`) or simple computer forms
+(:ref:`section_ref_entry_types_info`), which are detailed here.
+:ref:`section_notations` are also used, together with
+:ref:`section_ref_entry_types_names`.
-.. index:: single: Script
+.. _section_ref_entry_types_math:
-**Script**
- This indicates a script given as an external file. It can be described by a
- full absolute path name or only by the file name without path. If the file
- is given only by a file name without path, and if a study directory is also
- indicated, the file is searched in the given study directory.
+Pseudo-types of mathematical representation of data
++++++++++++++++++++++++++++++++++++++++++++++++++++
-.. index:: single: String
+The inputs are described according to the simplest possible logic, in
+mathematical representation, for algorithms or calculation tools.
-**String**
- This indicates a string giving a literal representation of a matrix, a
- vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
- square 2x2 matrix.
+.. include:: snippets/EntryTypeVector.rst
-The various other pseudo-types are as follows. The variables they apply
-themselves may be either a data string (a "*String*"), or a script file (a
-"*Script*"):
+.. include:: snippets/EntryTypeVectorSerie.rst
-.. index:: single: Dict
+.. include:: snippets/EntryTypeMatrix.rst
-**Dict**
- This indicates a variable that has to be filled by a Python dictionary
- ``{"key":"value...}``.
+.. include:: snippets/EntryTypeFunction.rst
-.. index:: single: Function
+.. include:: snippets/EntryTypeDict.rst
-**Function**
- This indicates a variable that has to be filled by a Python function. The
- functions are special entries described by the
- :ref:`section_ref_operator_requirements`.
+The variables to which these pseudo-types apply can themselves be given using
+the following computer descriptions.
-.. index:: single: Matrix
+.. _section_ref_entry_types_info:
-**Matrix**
- This indicates a variable that has to be filled by a matrix.
+Pseudo-types of digital data description
+++++++++++++++++++++++++++++++++++++++++
-.. index:: single: ScalarSparseMatrix
+Three pseudo-types, purely computer-based, are used to specify the way in which
+input variables are provided.
-**ScalarSparseMatrix**
- This indicates a variable that has to be filled by a unique number (which
- will be used to multiply an identity matrix).
+.. include:: snippets/EntryTypeScript.rst
-.. index:: single: DiagonalSparseMatrix
+.. include:: snippets/EntryTypeString.rst
-**DiagonalSparseMatrix**
- This indicates a variable that has to be filled by a vector (which will be
- used as the diagonal of a square matrix).
+.. include:: snippets/EntryTypeDataFile.rst
-.. index:: single: Vector
+.. _section_ref_entry_types_names:
-**Vector**
- This indicates a variable that has to be filled by a vector.
+Information on the names required for file entries
+++++++++++++++++++++++++++++++++++++++++++++++++++
-.. index:: single: VectorSerie
-
-**VectorSerie**
- This indicates a variable that has to be filled by a list of vectors.
-
-.. index:: single: DataFile
-.. index:: single: ColNames
-.. index:: single: ColMajor
-
-**DataFile**, **ColNames**, **ColMajor**
- This indicates the file name for data of text type (TXT, CSV, TSV...) or
- binary type (NPY, NPZ, SDF...), ordered in rows (``ColMajor=False``) or in
- lines (``ColMajor=True``),of which is selected all the variables or only
- those of ``ColNames`` list.
-
-When a command or keyword can be filled by a script file name, specified by the
-pseudo-type "*Script*", the script has to contain a variable or a method that
-has the same name as the one to be filled. In other words, when importing the
-script in a Python command or a YACS Python node, it must create a variable of
-the good name in the current name space of the node. For example, a Python
-script making available the background variable, named "*Background*", must
-have the following form::
+When a command or keyword can be entered using a script file identified by the
+pseudo-type "*Script*", this script must contain a variable or method that has
+the same name than the variable to be completed. In other words, when importing
+such a script into a Python command or Python node, it must create a variable
+of the correct name in the current namespace of the node. For example, a Python
+script making available the draft variable, named "*Background*", must have the
+following form::
+ ...
...
Background =...
...
+ ...
+
+Its import thus makes it possible to create the variable "*Background*" in the
+current namespace. The dots"..." symbolize any code around this particular line
+beginning.
-Its import allows the creation of the variable "*Background*". The dots "..."
-symbolize any code around this particular beginning of the line.
+Similarly, when a particular vector can be filled in using a data file
+designated by the pseudo-type "*DataFile*", the information in the file
+"*DataFile*" must be named after the vector to be loaded.
--- /dev/null
+.. index:: single: DataFile
+.. index:: single: ColNames
+.. index:: single: ColMajor
+
+**DataFile**, **ColNames**, **ColMajor**
+ This indicates data given in an external file. It can be described by a
+ full absolute path name or only by the file name without path. If the file
+ is given only by a file name without path, and if a study directory is also
+ indicated, the file is searched in the given study directory. The content
+ of the file can be:
+
+ - in text format (simple text in a file with a ".txt" or ".dat" extension,
+ text with comma delimiter in a file with a ".csv" extension, text with
+ tabulation delimiter in a file with a ".tsv" extension)
+ - in binary format (single-variable in a Numpy file with a ".npy"
+ extension, multi-variables in a NumpyZ file with a ".npz" extension)
+
+ By default, the values of a variable has to be ordered in rows
+ ("ColMajor=False"), but they can also be ordered in lines
+ ("ColMajor=True").
+
+ Without information or with a void list, all the values of all the
+ variables are used, but one can also select only the ones of the variables
+ that are indicated in the name list in "ColNames".
+
+ Example of CSV file for "*Observation*" variable in "*DataFile*" ::
+
+ # CSV file with delimiter ";" or ","
+ # ==================================
+ # Comment line beginning with #
+ # The next line is dedicated to variable naming
+ Alpha1;Observation;Alpha2
+ 0.1234;5.6789;9.0123
+ 1.2345;2.3456;3.
+ 2.3456;3.4567;4.56
+ 3.;4.;5.
+ 4;5;6
+ 5.123;6.789;7.8
+
+ Example of TXT file for "*Observation*" variable in "*DataFile*" ::
+
+ # Fichier TXT à séparateur espace
+ # TXT file with space delimiter
+ # =============================
+ # Ligne de commentaires quelconques débutant par #
+ # Ligne suivante réservée au nommage des variables
+ Alpha1 Observation Alpha2
+ 0.1234 5.6789 9.0123
+ 1.2345 2.3456 3.
+ 2.3456 3.4567 4.56
+ 3. 4. 5.
+ 4 5 6
+ 5.123 6.789 7.8
+
+.. warning::
+
+ It is recommended to check text or binary files before using them as an
+ input of this type. Various checks are carried out on loading, but the
+ variety of potential errors is great. In practice, by respecting the
+ requirements for naming variables and comments, text files from programs or
+ spreadsheets are (most of the time) compatible.
--- /dev/null
+.. index:: single: Dict
+
+**Dict**
+ This indicates a variable that has to be filled by a Python dictionary
+ ``{"key":"value...}``.
--- /dev/null
+.. index:: single: Function
+
+**Function**
+ This indicates a variable that must be given as a function in the Python
+ sense.. The functions are special entries described by the
+ :ref:`section_ref_operator_requirements`.
--- /dev/null
+.. index:: single: Matrix
+
+**Matrix**
+ This indicates a variable that has to be filled by a matrix. The
+ matrices are special entries described by the
+ :ref:`section_ref_covariance_requirements`.
--- /dev/null
+.. index:: single: Script
+
+**Script**
+ This indicates a script given as an external file. It can be described by a
+ full absolute path name or only by the file name without path. If the file
+ is given only by a file name without path, and if a study directory is also
+ indicated, the file is searched in the given study directory.
--- /dev/null
+.. index:: single: String
+
+**String**
+ This indicates a string giving a literal representation of a matrix, a
+ vector or a vector series, such as "1 2 ; 3 4" or "[[1,2],[3,4]]" for a
+ square 2x2 matrix.
--- /dev/null
+.. index:: single: Vector
+
+**Vector**
+ This indicates a variable that has to be filled as a vector. It is a simple
+ ordered collection of real numbers. The vectors can be described in row or
+ column version without making any difference.
--- /dev/null
+.. index:: single: VectorSerie
+
+**VectorSerie**
+ This indicates a variable that has to be filled in as a list of vectors. It
+ is an ordered collection of vectors.
.. _section_notations:
-Notations et conventions
-========================
+Notations et conventions communes
+=================================
Dans cette documentation, on utilise les notations standards de l'algèbre
linéaire, de l'assimilation de données (comme décrit dans [Ide97]_) et de
.. _section_ref_entry_types:
-Liste des types d'entrées possibles
------------------------------------
+Liste des types d'entrées possibles pour les variables utilisateurs
+-------------------------------------------------------------------
-Chaque variable ADAO présente un pseudo-type qui aide à la remplir et à la
-valider. Ces pseudo-types représentent explicitement des formes informatiques ou
-mathématiques simples. Deux pseudo-types, purement informatiques, permettent de
-désigner la manière dont on fournit les variables en entrée:
+Chaque variable à renseigner pour l'utilisation d'ADAO peut être représentée à
+l'aide de "pseudo-types" particuliers, qui aident à la remplir logiquement et à
+la valider informatiquement. Ces pseudo-types représentent explicitement des
+formes mathématiques (:ref:`section_ref_entry_types_math`) ou informatiques
+simples (:ref:`section_ref_entry_types_info`), que l'on détaille ici. On
+utilise aussi les :ref:`section_notations`, en même temps que les
+:ref:`section_ref_entry_types_names`.
-.. index:: single: Script
+.. _section_ref_entry_types_math:
-**Script**
- Cela indique un script donné comme un fichier externe. Il peut être désigné
- par un nom de fichier avec chemin complet ou seulement par un nom de fichier
- sans le chemin. Si le fichier est donné uniquement par un nom sans chemin,
- et si un répertoire d'étude est aussi indiqué, le fichier est recherché dans
- le répertoire d'étude donné.
+Pseudo-types de représentation mathématique des données
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.. index:: single: String
+Les entrées sont décrites selon une logique la plus simple possible, de
+représentation mathématique, pour des algorithmes ou outils de calculs.
-**String**
- Cela indique une chaîne de caractères fournissant une représentation
- littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs, comme
- par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de taille
- 2x2.
+.. include:: snippets/EntryTypeVector.rst
-Les différents autres pseudo-types sont les suivants. Les variables auxquelles
-ils s'appliquent peuvent elles-mêmes être données soit par une chaîne de
-caractères (un "*String*"), soit par un fichier script (un "*Script*"):
+.. include:: snippets/EntryTypeVectorSerie.rst
-.. index:: single: Dict
+.. include:: snippets/EntryTypeMatrix.rst
-**Dict**
- Cela indique une variable qui doit être remplie avec un dictionnaire Python
- ``{"clé":"valeur"...}``.
+.. include:: snippets/EntryTypeFunction.rst
-.. index:: single: Function
+.. include:: snippets/EntryTypeDict.rst
-**Function**
- Cela indique une variable qui doit être donnée comme une fonction Python.
- Les fonctions sont des entrées spéciales décrites par des
- :ref:`section_ref_operator_requirements`.
+Les variables auxquelles ces pseudo-types s'appliquent peuvent elles-mêmes être
+données à l'aide des descriptions informatiques qui suivent.
-.. index:: single: Matrix
+.. _section_ref_entry_types_info:
-**Matrix**
- Cela indique une variable qui doit être donnée comme une matrice.
+Pseudo-types de description informatique des données
+++++++++++++++++++++++++++++++++++++++++++++++++++++
-.. index:: single: ScalarSparseMatrix
+Trois pseudo-types, purement informatiques, permettent de désigner la manière
+dont on fournit les variables en entrée.
-**ScalarSparseMatrix**
- Cela indique une variable qui doit être donnée comme un nombre unique (qui
- sera ensuite utilisé pour multiplier une matrice identité).
+.. include:: snippets/EntryTypeScript.rst
-.. index:: single: DiagonalSparseMatrix
+.. include:: snippets/EntryTypeString.rst
-**DiagonalSparseMatrix**
- Cela indique une variable qui doit doit être donnée comme un vecteur, (qui
- sera ensuite utilisé comme la diagonale d'une matrice carrée).
+.. include:: snippets/EntryTypeDataFile.rst
-.. index:: single: Vector
+.. _section_ref_entry_types_names:
-**Vector**
- Cela indique une variable qui doit être remplie comme un vecteur.
+Informations sur les noms imposés pour les entrées par fichier
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.. index:: single: VectorSerie
-
-**VectorSerie**
- Cela indique une variable qui doit être remplie comme une liste de vecteurs.
-
-.. index:: single: DataFile
-.. index:: single: ColNames
-.. index:: single: ColMajor
-
-**DataFile**, **ColNames**, **ColMajor**
- Cela indique le nom d'un fichier de données de type texte (TXT, CSV,
- TSV...) ou de type binaire (NPY, NPZ, SDF...), rangées en colonnes
- (``ColMajor=False``) ou rangées en lignes (``ColMajor=True``), dont on
- sélectionne toutes les variables ou uniquement celles de la liste
- ``ColNames``.
-
-Lorsqu'une commande ou un mot-clé peut être rempli par un nom de fichier script
-désigné par le pseudo-type "*Script*", ce script doit présenter une variable ou
-une méthode que porte le même nom que la variable à remplir. En d'autres
-termes, lorsque l'on importe le script dans une commande Python ou un noeud
-Python de YACS, il doit créer une variable du bon nom dans l'espace de nommage
-courant du noeud. Par exemple, un script Python rendant disponible la variable
-d'ébauche, nommée "*Background*", doit présenter la forme suivante::
+Lorsqu'une commande ou un mot-clé peuvent être renseignés à l'aide d'un fichier
+script désigné par le pseudo-type "*Script*", ce script doit présenter une
+variable ou une méthode qui porte le même nom que la variable à remplir. En
+d'autres termes, lorsque l'on importe un tel script dans une commande Python ou
+un noeud Python de YACS, il doit créer une variable du bon nom dans l'espace de
+nommage courant du noeud. Par exemple, un script Python rendant disponible la
+variable d'ébauche, nommée "*Background*", doit présenter la forme suivante ::
+ ...
...
Background =...
...
+ ...
+
+Son importation permet ainsi de créer la variable "*Background*" dans l'espace
+de nommage courant. Les points "..." symbolisent du code quelconque autour de
+ce début particulier de ligne.
-Son importation permet ainsi de créer la variable "*Background*". Les points
-"..." symbolisent du code quelconque autour de ce début particulier de ligne.
+De la même manière, lorsqu'un vecteur particulier peut être renseigné à l'aide
+d'un fichier de données désigné par le pseudo-type "*DataFile*", les
+informations présentes dans le fichier "*DataFile*" doivent porter le nom du
+vecteur à charger.
--- /dev/null
+.. index:: single: DataFile
+.. index:: single: ColNames
+.. index:: single: ColMajor
+
+**DataFile**, **ColNames**, **ColMajor**
+ Cela indique des données fournies dans un fichier externe. Il peut être
+ désigné par un nom de fichier avec chemin complet ou seulement par un nom
+ de fichier sans le chemin. Si le fichier est donné uniquement par un nom
+ sans chemin, et si un répertoire d'étude est aussi indiqué, le fichier est
+ recherché dans le répertoire d'étude donné. Le contenu du fichier peut
+ être :
+
+ - en format texte (texte simple dans un fichier à extension ".txt" ou
+ ".dat", texte à séparateur virgule ou point-virgule dans un fichier à
+ extension ".csv", texte à séparateur tabulation dans un fichier à
+ extension ".tsv")
+ - en format binaire (mono-variable dans un fichier Numpy à extension
+ ".npy", multi-variables dans un fichier NumpyZ à extension ".npz").
+
+ Par défaut, les valeurs d'une variable doivent être rangées en colonnes
+ ("ColMajor=False"), mais elles peuvent aussi être rangées en lignes
+ ("ColMajor=True").
+
+ Sans précision ou avec une liste vide pour les noms de variable, on utilise
+ les valeurs toutes les variables, mais on peut aussi sélectionner
+ uniquement celles des variables indiquées dans la liste indiquée de noms
+ dans "ColNames".
+
+ Exemple de fichier CSV pour la variable "*Observation*" en "*DataFile*" ::
+
+ # Fichier CSV à séparateur ";" ou ","
+ # ===================================
+ # Ligne de commentaires débutant par #
+ # La ligne suivante est réservée au nommage des variables
+ Alpha1;Observation;Alpha2
+ 0.1234;5.6789;9.0123
+ 1.2345;2.3456;3.
+ 2.3456;3.4567;4.56
+ 3.;4.;5.
+ 4;5;6
+ 5.123;6.789;7.8
+
+ Exemple de fichier TXT pour la variable "*Observation*" en "*DataFile*" ::
+
+ # Fichier TXT à séparateur espace
+ # ===============================
+ # Ligne de commentaires débutant par #
+ # La ligne suivante est réservée au nommage des variables
+ Alpha1 Observation Alpha2
+ 0.1234 5.6789 9.0123
+ 1.2345 2.3456 3.
+ 2.3456 3.4567 4.56
+ 3. 4. 5.
+ 4 5 6
+ 5.123 6.789 7.8
+
+.. warning::
+
+ Il est recommandé de vérifier les fichiers textes ou binaires, avant de les
+ utiliser en entrée de ce type. Diverses vérifications sont effectuées au
+ chargement, mais la variété des erreurs potentielles est grande. Dans la
+ pratique, en respectant les exigences de nommage des variables et de
+ commentaires, des fichiers textes issus de programmes ou de tableurs sont
+ (la plupart du temps) compatibles.
--- /dev/null
+.. index:: single: Dict
+
+**Dict**
+ Cela indique une variable qui doit être remplie comme un dictionnaire au
+ sens Python ``{"clé":"valeur"...}``.
--- /dev/null
+.. index:: single: Function
+
+**Function**
+ Cela indique une variable qui doit être donnée comme une fonction au sens
+ Python. Les fonctions sont des entrées spéciales qui peuvent être décrites
+ selon les :ref:`section_ref_operator_requirements`.
--- /dev/null
+.. index:: single: Matrix
+
+**Matrix**
+ Cela indique une variable qui doit être donnée comme une matrice. Les
+ matrices sont des entrées spéciales qui peuvent être décrites selon les
+ :ref:`section_ref_covariance_requirements`.
--- /dev/null
+.. index:: single: Script
+
+**Script**
+ Cela indique un script donné comme un fichier externe. Il peut être désigné
+ par un nom de fichier avec chemin complet ou seulement par un nom de
+ fichier sans le chemin. Si le fichier est donné uniquement par un nom sans
+ chemin, et si un répertoire d'étude est aussi indiqué, le fichier est
+ recherché dans le répertoire d'étude donné.
--- /dev/null
+.. index:: single: String
+
+**String**
+ Cela indique une chaîne de caractères fournissant une représentation
+ littérale d'une matrice, d'un vecteur ou d'une collection de vecteurs,
+ comme par exemple "1 2 ; 3 4" ou "[[1,2],[3,4]]" pour une matrice carrée de
+ taille 2x2.
--- /dev/null
+.. index:: single: Vector
+
+**Vector**
+ Cela indique une variable qui doit être remplie comme un vecteur. C'est une
+ simple collection ordonnée de nombres réels. Les vecteurs peuvent être
+ décrits en version ligne ou colonne sans faire de différence.
--- /dev/null
+.. index:: single: VectorSerie
+
+**VectorSerie**
+ Cela indique une variable qui doit être remplie comme une liste de
+ vecteurs. C'est une collection ordonnée de vecteurs.
