* Bug #12916 fixed - Improve the "power" help paged. 41/12541/2
Mehran Khorshidi [Fri, 13 Sep 2013 18:39:09 +0000 (20:39 +0200)]
Change-Id: I903cb8ae358fec7297c3f1b6c0aacab14d7a338c

scilab/CHANGES_5.5.X
scilab/modules/core/help/en_US/1_keywords/power.xml

index cdaa3c3..23e2985 100644 (file)
@@ -672,3 +672,5 @@ Bug Fixes
 
 * Bug #12911 fixed - Matlab to Scilab dictionary help page updated for eig.
 
+* Bug #12916 fixed - power help page improved.
+
index 7057b8e..59ea002 100644 (file)
                 </para>
             </listitem>
         </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Additional Remarks</title>
+        <para>
+            <note> Notes: </note>
+        </para>
+        <para>
+            1. For square matrices <literal>A^p</literal> is computed through successive matrices 
+            multiplications if <literal>p</literal> is a positive integer, and by <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
+        </para>
+        <para>
+            2. If <varname>A</varname> is a square and Hermitian matrix and <varname>p</varname> is a non-integer scalar,
+            <literal>A^p</literal> is computed as:
+        </para>
+        <para>
+            <code>A^p = u*diag(diag(s).^p)*u'</code> (For real matrix <varname>A</varname>, only the real part of the answer is taken into account). 
+        </para>
+        <para>
+            <varname>u</varname> and <varname>s</varname> are determined by <code>[u,s] = schur(A)</code> . 
+        </para>
         <para>
-            Notes:
+            3. If <varname>A</varname> is not a Hermitian matrix and <varname>p</varname> is a non-integer scalar,
+            <literal>A^p</literal> is computed as:
         </para>
         <para>
-            -
-            For square matrices <literal>A^p</literal> is computed through successive
-            matrices multiplications if <literal>p</literal> is a positive integer, and by
-            diagonalization if not.
+            <code>A^p = v*diag(diag(d).^p)*inv(v)</code> (For real matrix <varname>A</varname>, only the real part of the answer is taken into account). 
         </para>
         <para>
-            -
-            <literal>**</literal> and <literal>^</literal> operators are synonyms.
+            <varname>d</varname> and <varname>v</varname> are determined by <code>[d,v] = bdiag(A+0*%i)</code> . 
+        </para>
+        <para>
+            4. If <varname>A</varname> and <varname>p</varname> are real or complex numbers,
+            <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by:
+        </para>
+        <para>
+            <code>A^p = exp(p*log(A))</code> (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ). 
+        </para>
+        <para>
+            5. If <varname>A</varname> is a square matrix and <varname>p</varname> is a real or complex number,
+            <literal>A.^p</literal> is the <emphasis>principal value</emphasis> computed as:
+        </para>
+        <para>
+            <code>A.^p = exp(p*log(A))</code> (same as case 4 above). 
+        </para>
+        <para>
+            6. <literal>**</literal> and <literal>^</literal> operators are synonyms.
         </para>
     </refsection>
     <refsection>
@@ -80,6 +114,10 @@ A.^2.5
 (1:10)^2
 (1:10).^2
 
+A^%i
+A.^%i
+exp(%i*log(A))
+
 s=poly(0,'s')
 s^(1:10)
  ]]></programlisting>