Revision of help pages for slash and backslash (en_US, ru_RU). 16/11116/2
Stanislav KROTER [Wed, 27 Mar 2013 15:08:15 +0000 (21:08 +0600)]
Change-Id: I65f339a6f4a9c13afe10e715d6da904247c8e4a4

scilab/modules/core/help/en_US/1_keywords/backslash.xml
scilab/modules/core/help/en_US/1_keywords/slash.xml
scilab/modules/core/help/ru_RU/1_keywords/backslash.xml
scilab/modules/core/help/ru_RU/1_keywords/slash.xml

index 1a5baff..e5176c8 100644 (file)
@@ -6,44 +6,44 @@
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
-        <synopsis>x=A\B</synopsis>
+        <synopsis>X=A\B</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Description</title>
         <para>
             Backslash is the left matrix division:
-            <literal>x=A\B</literal> is a solution to <literal>A*x=B</literal>.
+            <code>X=A\B</code> is a solution to <code>A*X=B</code>.
         </para>
         <para>
-            If <literal>A</literal> is square and non-singular <literal>x=A\B</literal> is
-            equivalent to <literal>x=inv(A)*B</literal> in exact arithmetic,
+            If <literal>A</literal> is square and non-singular <code>X=A\B</code> is
+            equivalent to <code>X=inv(A)*B</code> in exact arithmetic,
             but the computations are more accurate and cheaper in floating point arithmetic.
-            Hence, to compute the solution of the linear system of equations <literal>A*x=B</literal>,
-            the backslash operator should be used, and the <literal>inv</literal> function
+            Hence, to compute the solution of the linear system of equations <code>A*X=B</code>,
+            the backslash operator should be used, and the <function>inv</function> function
             should be avoided.
         </para>
         <para>
-            In the case where A is square, the solution <literal>x</literal> can be computed
+            In the case where <literal>A</literal> is square, the solution <literal>X</literal> can be computed
             either from LU factorization or from a linear least squares solver.
-            If the condition number of A is smaller than 1/(10*%eps) (i.e. if A is well conditionned),
+            If the condition number of <literal>A</literal> is smaller than <code>1/(10*%eps)</code> (i.e. if <literal>A</literal> is well conditioned),
             the LU factorization with row pivoting is used.
-            If not (i.e. if A is poorly conditionned), then X is the minimum-norm solution which
+            If not (i.e. if <literal>A</literal> is poorly conditioned), then <literal>X</literal> is the minimum-norm solution which
             minimizes <literal>||A*X-B||</literal> using a complete
-            orthogonal factorization of A (i.e. X is the solution of a linear least squares problem).
+            orthogonal factorization of <literal>A</literal> (i.e. <literal>X</literal> is the solution of a linear least squares problem).
         </para>
         <para>
-            If <literal>A</literal> is not square, <literal>x</literal> is a least square solution,
-            i.e. <literal>norm(A*x-B)</literal> is minimal (Euclidean norm). If <literal>A</literal> is full
-            column rank, the least square solution, <literal>x=A\B</literal>, is uniquely
-            defined (there is a unique <literal>x</literal> which minimizes <literal>norm(A*x-B)</literal>).
+            If <literal>A</literal> is not square, <literal>X</literal> is a least square solution,
+            i.e. <code>norm(A*X-B)</code> is minimal (Euclidean norm). If <literal>A</literal> is full
+            column rank, the least square solution, <code>X=A\B</code>, is uniquely
+            defined (there is a unique <literal>X</literal> which minimizes <code>norm(A*X-B)</code>).
             If <literal>A</literal> is not full column rank, then the least square
-            solution is not unique, and <literal>x=A\B</literal>, in general, is not the solution
-            with minimum norm (the minimum norm solution is <literal>x=pinv(A)*B</literal>).
+            solution is not unique, and <code>X=A\B</code>, in general, is not the solution
+            with minimum norm (the minimum norm solution is <code>X=pinv(A)*B</code>).
         </para>
         <para>
-            <literal>A.\B</literal>  is the matrix with <literal>(i,j)</literal> entry <literal>A(i,j)\B(i,j)</literal>.
-            If <literal>A</literal> (or <literal>B</literal>) is a scalar <literal>A.\B</literal> is equivalent to
-            <literal>A*ones(B).\B</literal> (or <literal>A.\(B*ones(A))</literal>.
+            <code>A.\B</code>  is the matrix with <literal>(i,j)</literal> entry <literal>A(i,j)\B(i,j)</literal>.
+            If <literal>A</literal> (or <literal>B</literal>) is a scalar <code>A.\B</code> is equivalent to
+            <code>A*ones(B).\B</code> (or <code>A.\(B*ones(A))</code>.
         </para>
         <para>
             <literal>A\.B</literal>  is an operator with no predefined meaning. It may be used
index 343a50e..3095bab 100644 (file)
@@ -7,47 +7,55 @@
     <refsection>
         <title>Description</title>
         <para>
-            Right division: <code>x=A/B</code> is the solution of <code>x*B=A</code>.
+            Right division: <code>X=A/B</code> is the solution of <code>X*B=A</code>.
         </para>
         <para>
             The slash (right division) and backslash (left division) operators are linked by the following equation:
             <code>B/A=(A'\B')'</code>.
         </para>
         <para>
-            In the case where A is square, the solution <literal>x</literal> can be computed
-            either from LU factorization or from a linear least squares solver.
-            If the condition number of A is smaller than 1/(10*%eps) (i.e. if A is well conditionned),
-            the LU factorization with row pivoting is used.
-            If not (i.e. if A is poorly conditionned), then X is the minimum-norm solution which
-            minimizes <literal>||A*X-B||</literal> using a complete
-            orthogonal factorization of A (i.e. X is the solution of a linear least squares problem).
+            In the case where <literal>A</literal> is square, the 
+            solution <literal>X</literal> can be computed either from LU 
+            factorization or from a linear least squares solver. If the 
+            condition number of <literal>A</literal> is smaller than 
+            <code>1/(10*%eps)</code> (i.e. if <literal>A</literal> is 
+            well conditioned), the LU factorization with row pivoting is 
+            used. If not (i.e. if <literal>A</literal> is poorly 
+            conditioned), then <literal>X</literal> is the minimum-norm 
+            solution which minimizes <literal>||A*X-B||</literal> using 
+            a complete orthogonal factorization of <literal>A</literal> 
+            (i.e. <literal>X</literal> is the solution of a linear least 
+            squares problem).
         </para>
         <para>
-            <code>A./B</code> is the elementwise right division, i.e. the matrix with
-            entries <literal>A(i,j)/B(i,j)</literal>.
-            If <literal>B</literal> is scalar (1x1 matrix) this operation is the same
-            as <code>A./B*ones(A)</code>.
-            Same convention if <literal>A</literal> is a scalar.
+            <code>A./B</code> is the element-wise right division, i.e. 
+            the matrix with entries <literal>A(i,j)/B(i,j)</literal>.
+            If <literal>B</literal> is scalar (1x1 matrix) this 
+            operation is the same as <code>A./B*ones(A)</code>. Same 
+            convention if <literal>A</literal> is a scalar.
         </para>
         <para>
             <note>
-                Remark that <code>123./B</code> is interpreted as <code>(123.)/B</code>. In this
-                cases dot is part of the  number not of the operator.
+                Remark that <code>123./B</code> is interpreted as 
+                <code>(123.)/B</code>. In this cases dot is part of the  
+                number not of the operator.
             </note>
         </para>
         <para>
             System feed back.  <code>S = G/.K</code> evaluates
-            <code>S = G*(eye() + K*G)^(-1)</code> this operator avoid simplification problem.
+            <code>S = G*(eye() + K*G)^(-1)</code> this operator avoid 
+            simplification problem.
         </para>
         <para>
             <note>
-                Remark that <code>G/.5</code> is interpreted as <code>G/(.5)</code>. In such
-                cases dot is part of the number, not of the operator.
+                Remark that <code>G/.5</code> is interpreted as 
+                <code>G/(.5)</code>. In such cases dot is part of the 
+                number, not of the operator.
             </note>
         </para>
         <para>
-            Comment <code>//</code> comments a line i.e. lines which begin by <code>//</code>
-            are ignored by the interpreter.
+            Comment <code>//</code> comments a line i.e. lines which 
+            begin by <code>//</code> are ignored by the interpreter.
         </para>
     </refsection>
     <refsection>
@@ -86,7 +94,9 @@ a=2 ./ [2,4]; //     1.    0.5
         <revhistory>
             <revision>
                 <revnumber>5.4.1</revnumber>
-                <revremark>The threshold level for conditioning in slash increased.</revremark>
+                <revremark>
+                    The threshold level for conditioning in slash increased.
+                </revremark>
             </revision>
         </revhistory>
     </refsection>
index 572747f..7b64e1b 100644 (file)
@@ -6,46 +6,93 @@
     </refnamediv>
     <refsynopsisdiv>
         <title>Последовательность вызова</title>
-        <synopsis>x=A\b</synopsis>
+        <synopsis>X=A\B</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Описание</title>
         <para>
             Обратный слэш означает левое матричное деление.
-            <literal>x=A\b</literal> является решением для <literal>A*x=b</literal>.
+            <code>X=A\B</code> является решением для <code>A*X=B</code>.
         </para>
         <para>
-            Если <literal>A</literal> -- квадратная и невырожденная, то  <literal>x=A\b</literal> 
-            (уникально определённая) эквивалентно <literal>x=inv(A)*b</literal> (но вычисления гораздо дешевле).
+            Если <literal>A</literal> - квадратная и невырожденная, то  <code>X=A\B</code> 
+            (уникально определённая) эквивалентно <code>X=inv(A)*B</code> в точном арифметическом смысле, однако вычисления гораздо точнее и дешевле в арифметике с плавающей запятой.
+            Следовательно, чтобы вычислить решение линейной системы уравнений <code>A*X=B</code>,
+            следует использовать оператор "обратный слэш", а функцию  <function>inv</function> не следует использовать.
         </para>
         <para>
-            Если <literal>A</literal> не квадратная, то <literal>x</literal> является решением наименьших квадратов,
-            т.е. <literal>norm(A*x-b)</literal> является минимальной (эвклидовой нормой). Если ранг матрицы <literal>A</literal>
-            полный, то решение наименьших квадратов, <literal>x=A\b</literal>, является уникально 
-            определённым (есть уникальное <literal>x</literal>, которое минимизирует <literal>norm(A*x-b)</literal>).
+            В случае, когда <literal>A</literal> - квадратная матрица, 
+            решение <literal>X</literal> может быть вычислено
+            либо через LU-разложение, либо через программу линейного 
+            решения по методу наименьших квадратов.
+            Если число обусловленности матрицы <literal>A</literal> 
+            меньше, чем <code>1/(10*%eps)</code> (то есть, если 
+            <literal>A</literal> хорошо обусловлена),
+            то используется LU-разложение с перестановками строк матрицы.
+            Если нет (то есть, если <literal>A</literal> плохо 
+            обусловлена), то <literal>X</literal> является решением с 
+            минимальной нормой, которое минимизирует
+            <literal>||A*X-B||</literal> используя полное ортогональное 
+            разложение <literal>A</literal> (то есть 
+            <literal>X</literal> - это решение линейной задачи по методу 
+            наименьших квадратов).
+        </para>
+        <para>
+            Если <literal>A</literal> не квадратная, то <literal>X</literal> является решением наименьших квадратов,
+            т.е. <code>norm(A*X-B)</code> является минимальной (эвклидова норма). Если ранг матрицы <literal>A</literal>
+            полный, то решение наименьших квадратов, <code>X=A\B</code>, является уникально 
+            определённым (есть уникальное <literal>X</literal>, которое минимизирует <code>norm(A*X-B)</code>).
             Если ранг матрицы <literal>A</literal> неполный, то решение наименьших квадратов не является уникальным, 
-            и <literal>x=A\b</literal>, в общем, не является решением с минимальной нормой (решение минимальной 
-            нормы равно  <literal>x=pinv(A)*b</literal>).
+            и <code>X=A\B</code>, в общем, не является решением с минимальной нормой (решение минимальной 
+            нормы равно  <code>X=pinv(A)*B</code>).
         </para>
         <para>
-            <literal>A.\B</literal> является матрицей с <literal>(i,j)</literal>-тым элементом, равным <literal>A(i,j)\B(i,j)</literal>.
-            Если <literal>A</literal> (или <literal>B</literal>) является скаляром, то <literal>A.\B</literal> эквивалентно
-            <literal>A*ones(B).\B</literal> (или <literal>A.\(B*ones(A))</literal>.
+            <code>A.\B</code> является матрицей с <literal>(i,j)</literal>-тым элементом, равным <literal>A(i,j)\B(i,j)</literal>.
+            Если <literal>A</literal> (или <literal>B</literal>) является скаляром, то <code>A.\B</code> эквивалентно
+            <code>A*ones(B).\B</code> (или <code>A.\(B*ones(A))</code>.
         </para>
         <para>
             <literal>A\.B</literal> является оператором без предопределённого значения. Он может использоваться 
-            для определения нового оператора (см. <link linkend="overloading">overloading</link>) с тем же самым приоритетом что и <literal>*</literal> или <literal>/</literal>.
+            для определения нового оператора (см. <link linkend="overloading">перегрузку</link>) с тем же самым приоритетом что и <literal>*</literal> или <literal>/</literal>.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[ 
-A=rand(3,2);b=[1;1;1]; x=A\b; y=pinv(A)*b;  x-y
-A=rand(2,3);b=[1;1]; x=A\b; y=pinv(A)*b; x-y, A*x-b, A*y-b
+A=[
+   9.   -36.    30.
+  -36.   192.  -180.
+   30.  -180.   180.
+];
+b=[
+   3.
+  -24.
+   30.
+];
+x=A\b
+A*x-b // close to zero
+
+A=rand(3,2);
+b=[1;1;1];
+x=A\b;
+y=pinv(A)*b;
+x-y
+A=rand(2,3);b=[1;1];
+x=A\b;
+y=pinv(A)*b;
+x-y, A*x-b, A*y-b
 
 // если ранг неполный
-A=rand(3,1)*rand(1,2); b=[1;1;1]; x=A\b; y=pinv(A)*b; A*x-b, A*y-b
-A=rand(2,1)*rand(1,3); b=[1;1]; x=A\b; y=pinv(A)*b; A*x-b, A*y-b 
+A=rand(3,1)*rand(1,2);
+b=[1;1;1];
+x=A\b;
+y=pinv(A)*b;
+A*x-b, A*y-b
+A=rand(2,1)*rand(1,3);
+b=[1;1];
+x=A\b;
+y=pinv(A)*b;
+A*x-b, A*y-b
  
 // Проверка эффективности нескольких программ решения систем линейных уравнений
  
@@ -92,4 +139,15 @@ mprintf('\nвремя, необходимое для решения систем
             </member>
         </simplelist>
     </refsection>
+    <refsection>
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.4.1</revnumber>
+                <revremark>
+                    Пороговый уровень для обусловливания в обратном слэше увеличен.
+                </revremark>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 7ac650f..04fbc7b 100644 (file)
@@ -2,24 +2,47 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ru" xml:id="slash">
     <refnamediv>
         <refname>слэш (косая черта)</refname>
-        <refpurpose>(/) правое деление и обратная связь (комментарий)</refpurpose>
+        <refpurpose>(/) правое деление и обратная связь</refpurpose>
     </refnamediv>
     <refsection>
         <title>Описание</title>
         <para>
-            Правое деление.  <code>x = A / b</code> является решением <code>x * b = A</code>.
+            Правое деление. <code>X=A/B</code> является решением <code>X*B=A</code>.
         </para>
         <para>
-            <code>b/a = (a' \ b')'</code>.
+            Операторы слэш (правое деление) и обратный слэш (левое 
+            деление) связаны следующим выражением: <code>B/A=(A'\B')'</code>.
         </para>
         <para>
-            <code>a ./ b</code> является матрицей с элементами <literal>a(i,j)/ b(i,j)</literal>.
-            Если <literal>b</literal> -- скаляр (матрица размером <literal>1x1</literal>), то эта операция то же самое, что и <code>a ./ b * ones(a)</code>. Аналогично, если скаляром является <literal>a</literal>.
+            В случае, когда <literal>A</literal> - квадратная матрица, 
+            решение <literal>X</literal> может быть вычислено
+            либо через LU-разложение, либо через программу линейного 
+            решения по методу наименьших квадратов.
+            Если число обусловленности матрицы <literal>A</literal> 
+            меньше, чем <code>1/(10*%eps)</code> (то есть, если 
+            <literal>A</literal> хорошо обусловлена),
+            то используется LU-разложение с перестановками строк 
+            матрицы. Если нет (то есть, если <literal>A</literal> плохо 
+            обусловлена), то <literal>X</literal> является решением с 
+            минимальной нормой, которое минимизирует
+            <literal>||A*X-B||</literal> используя полное ортогональное 
+            разложение <literal>A</literal> (то есть 
+            <literal>X</literal> - это решение линейной задачи по методу 
+            наименьших квадратов).
+        </para>
+        <para>
+            <code>A ./ B</code> является матрицей с элементами 
+            <literal>A(i,j)/ B(i,j)</literal>.
+            Если <literal>B</literal> - скаляр (матрица размером 
+            1 на 1), то эта операция то же самое, что и 
+            <code>A ./ B * ones(A)</code>. Аналогично, если скаляром 
+            является <literal>A</literal>.
         </para>
         <para>
             <note>
-                Заметьте, что <code>123./b</code> интерпретируется как <code>(123.)/b</code>.
-                В таких случаях точка является частью числа, а не оператора.
+                Заметьте, что <code>123./B</code> интерпретируется как 
+                <code>(123.)/B</code>. В таких случаях точка является 
+                частью числа, а не оператора.
             </note>
         </para>
         <para>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
+a=[3.,-24.,30.];
+B=[
+   9.   -36.    30.
+  -36.   192.  -180.
+   30.  -180.   180.
+];
+x=a/B
+x*B-a // близко к нулю
+
 a=4 / 2; // Должно быть 2
 a=2 ./ [2,4]; //     1.    0.5
 // Комментарии - это хорошо. Они помогают понять код
@@ -62,4 +94,15 @@ a=2 ./ [2,4]; //     1.    0.5
             </member>
         </simplelist>
     </refsection>
+    <refsection>
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.4.1</revnumber>
+                <revremark>
+                    Пороговый уровень для обусловливания в слэше увеличен.
+                </revremark>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>