From: Jean-Philippe ARGAUD <jean-philippe.argaud@edf.fr>
Date: Sun, 8 Mar 2020 19:54:51 +0000 (+0100)
Subject: Improvement of operator documentation
X-Git-Tag: V9_5_0a2~2
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=7a626c040c9a5146b43da0adfa5381e829293323;p=modules%2Fadao.git

Improvement of operator documentation
---

diff --git a/doc/en/ref_operator_requirements.rst b/doc/en/ref_operator_requirements.rst
index 0844a29..7dda4f8 100644
--- a/doc/en/ref_operator_requirements.rst
+++ b/doc/en/ref_operator_requirements.rst
@@ -171,7 +171,7 @@ can follow the template::
         ...
         ...
         ...
-        return something like Y
+        return "a vector similar to Y"
 
     def TangentOperator( pair = (X, dX) ):
         """ Tangent linear operator, around X, applied to dX """
@@ -179,7 +179,7 @@ can follow the template::
         ...
         ...
         ...
-        return something like Y
+        return "a vector similar to Y"
 
     def AdjointOperator( pair = (X, Y) ):
         """ Adjoint operator, around X, applied to Y """
@@ -187,16 +187,40 @@ can follow the template::
         ...
         ...
         ...
-        return something like X
+        return "a vector similar to X"
 
 Another time, this second operator definition allow easily to test the
 functional forms before their use in an ADAO case, reducing the complexity of
 operator implementation.
 
-For some algorithms, it is required that the tangent and adjoint functions can
-return the matrix equivalent to the linear operator. In this case, when
-respectively the ``dX`` or the ``Y`` arguments are ``None``, the user script
-has to return the associated matrix.
+For some algorithms (in particular filters without ensemble), it is required
+that the tangent and adjoint functions can return the matrix equivalent to the
+linear operator. In this case, when respectively the ``dX`` or the ``Y``
+arguments are ``None``, the user script has to return the associated matrix.
+The templates of the "*TangentOperator*" and "*AddOperator*" functions then
+become the following::
+
+    def TangentOperator( pair = (X, dX) ):
+        """ Tangent linear operator, around X, applied to dX """
+        X, dX = pair
+        ...
+        ...
+        ...
+        if dX is None or len(dX) == 0:
+            return "the matrix of the tangent linear operator"
+        else:
+            return "a vector similar to Y"
+
+    def AdjointOperator( pair = (X, Y) ):
+        """ Adjoint operator, around X, applied to Y """
+        X, Y = pair
+        ...
+        ...
+        ...
+        if Y is None or len(Y) == 0:
+            return "the adjoint linear operator matrix"
+        else:
+            return "a vector similar to X"
 
 **Important warning:** the names "*DirectOperator*", "*TangentOperator*" and
 "*AdjointOperator*" are mandatory, and the type of the ``X``, Y``, ``dX``
diff --git a/doc/fr/ref_operator_requirements.rst b/doc/fr/ref_operator_requirements.rst
index c1bcbde..34d42e9 100644
--- a/doc/fr/ref_operator_requirements.rst
+++ b/doc/fr/ref_operator_requirements.rst
@@ -179,7 +179,7 @@ suivre le squelette suivant::
         ...
         ...
         ...
-        return quelque chose comme Y
+        return "un vecteur similaire à Y"
 
     def TangentOperator( paire = (X, dX) ):
         """ Opérateur linéaire tangent, autour de X, appliqué à dX """
@@ -187,7 +187,7 @@ suivre le squelette suivant::
         ...
         ...
         ...
-        return quelque chose comme Y
+        return "un vecteur similaire à Y"
 
     def AdjointOperator( paire = (X, Y) ):
         """ Opérateur adjoint, autour de X, appliqué à Y """
@@ -195,16 +195,40 @@ suivre le squelette suivant::
         ...
         ...
         ...
-        return quelque chose comme X
+        return "un vecteur similaire à X"
 
 Un nouvelle fois, cette seconde définition d'opérateur permet aisément de tester
 les formes fonctionnelles avant de les utiliser dans le cas ADAO, réduisant la
 complexité de l'implémentation de l'opérateur.
 
-Pour certains algorithmes, il faut que les fonctions tangente et adjointe
-puisse renvoyer les matrices équivalentes à l'opérateur linéaire. Dans ce cas,
-lorsque, respectivement, les arguments ``dX`` ou ``Y`` valent ``None``, le
-script de l'utilisateur doit renvoyer la matrice associée.
+Pour certains algorithmes (en particulier les filtres non ensemblistes), il
+faut que les fonctions tangente et adjointe puisse renvoyer les matrices
+équivalentes à l'opérateur linéaire. Dans ce cas, lorsque, respectivement, les
+arguments ``dX`` ou ``Y`` valent ``None``, le script de l'utilisateur doit
+renvoyer la matrice associée. Les squelettes des fonctions "*TangentOperator*"
+et "*AdjointOperator*" deviennent alors les suivants::
+
+    def TangentOperator( paire = (X, dX) ):
+        """ Opérateur linéaire tangent, autour de X, appliqué à dX """
+        X, dX = paire
+        ...
+        ...
+        ...
+        if dX is None or len(dX) == 0:
+            return "la matrice de l'opérateur linéaire tangent"
+        else:
+            return "un vecteur similaire à Y"
+
+    def AdjointOperator( paire = (X, Y) ):
+        """ Opérateur adjoint, autour de X, appliqué à Y """
+        X, Y = paire
+        ...
+        ...
+        ...
+        if Y is None or len(Y) == 0:
+            return "la matrice de l'opérateur linéaire adjoint"
+        else:
+            return "un vecteur similaire à X"
 
 **Avertissement important :** les noms "*DirectOperator*", "*TangentOperator*"
 et "*AdjointOperator*" sont obligatoires, et le type des arguments ``X``,