scilab/modules/elementary_functions/help/en_US/exponential/power.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <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="en" xml:id="power">
   3     <refnamediv>
   4         <refname>power</refname>
   5         <refpurpose>(^,.^) power operation</refpurpose>
   6     </refnamediv>
   7     <refsynopsisdiv>
   8         <title>Syntax</title>
   9         <synopsis>t=A^b
  10             t=A**b
  11             t=A.^b
  12         </synopsis>
  13     </refsynopsisdiv>
  14     <refsection>
  15         <title>Arguments</title>
  16         <variablelist>
  17             <varlistentry>
  18                 <term>A,t</term>
  19                 <listitem>
  20                     <para>scalar, polynomial or rational matrix.</para>
  21                 </listitem>
  22             </varlistentry>
  23             <varlistentry>
  24                 <term>b</term>
  25                 <listitem>
  26                     <para>a scalar, a vector or a scalar matrix.</para>
  27                 </listitem>
  28             </varlistentry>
  29         </variablelist>
  30     </refsection>
  31     <refsection>
  32         <title>Description</title>
  33         <itemizedlist>
  34             <listitem>
  35                 <para>
  36                     If <literal>A</literal> is a square matrix and <literal>b</literal> is a scalar then  <literal>A^b</literal> is the matrix <literal>A</literal> to the power <literal>b</literal>.
  37                 </para>
  38             </listitem>
  39             <listitem>
  40                 <para>
  41                     If <literal>b</literal> is a scalar and <literal>A</literal> a matrix then
  42                     <literal>A.^b</literal>  is the matrix formed by the element of
  43                     <literal>A</literal> to the power <literal>b</literal> (element-wise power). If
  44                     <literal>A</literal> is a vector and <literal>b</literal> is a scalar then
  45                     <literal>A^b</literal> and <literal>A.^b</literal> performs the same operation
  46                     (i.e. element-wise power).
  47                 </para>
  48             </listitem>
  49             <listitem>
  50                 <para>
  51                     If <literal>A</literal> is a scalar and <literal>b</literal> is a square matrix <literal>A^b</literal> is the matrix <literal> expm(log(A) * b)</literal>.
  52                 </para>
  53                 <para>
  54                     If <literal>A</literal> is a scalar and <literal>b</literal> is a vector <literal>A^b</literal> and <literal>A.^b</literal> are the vector formed by  <literal> a^(b(i,j))</literal>.
  55                 </para>
  56                 <para>
  57                     If <literal>A</literal> is a scalar and <literal>b</literal> is a matrix <literal>A.^b</literal> is the matrix formed by  <literal> a^(b(i,j))</literal>.
  58                 </para>
  59             </listitem>
  60             <listitem>
  61                 <para>
  62                     If <literal>A</literal> and <literal>b</literal> are vectors (matrices) of the same size <literal>A.^b</literal> is the  <literal>A(i)^b(i)</literal> vector (<literal>A(i,j)^b(i,j)</literal> matrix).
  63                 </para>
  64             </listitem>
  65         </itemizedlist>
  66     </refsection>
  67     <refsection>
  68         <title>Additional Remarks</title>
  69         <para>
  70             <note> Notes: </note>
  71         </para>
  72         <para>
  73             1. For square matrices <literal>A^p</literal> is computed through successive matrices
  74             multiplications if <literal>p</literal> is a positive integer, and by <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
  75         </para>
  76         <para>
  77             2. If <varname>A</varname> is a square and Hermitian matrix and <varname>p</varname> is a non-integer scalar,
  78             <literal>A^p</literal> is computed as:
  79         </para>
  80         <para>
  81             <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).
  82         </para>
  83         <para>
  84             <varname>u</varname> and <varname>s</varname> are determined by <code>[u,s] = schur(A)</code> .
  85         </para>
  86         <para>
  87             3. If <varname>A</varname> is not a Hermitian matrix and <varname>p</varname> is a non-integer scalar,
  88             <literal>A^p</literal> is computed as:
  89         </para>
  90         <para>
  91             <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).
  92         </para>
  93         <para>
  94             <varname>d</varname> and <varname>v</varname> are determined by <code>[d,v] = bdiag(A+0*%i)</code> .
  95         </para>
  96         <para>
  97             4. If <varname>A</varname> and <varname>p</varname> are real or complex numbers,
  98             <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by:
  99         </para>
 100         <para>
 101             <code>A^p = exp(p*log(A))</code> (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ).
 102         </para>
 103         <para>
 104             5. If <varname>A</varname> is a square matrix and <varname>p</varname> is a real or complex number,
 105             <literal>A.^p</literal> is the <emphasis>principal value</emphasis> computed as:
 106         </para>
 107         <para>
 108             <code>A.^p = exp(p*log(A))</code> (same as case 4 above).
 109         </para>
 110         <para>
 111             6. <literal>**</literal> and <literal>^</literal> operators are synonyms.
 112         </para>
 113         <para>
 114             <warning>
 115                 Exponentiation is right-associative in Scilab contrarily to Matlab® and Octave.
 116                 For example 2^3^4 is equal to 2^(3^4) in Scilab but is equal to (2^3)^4 in Matlab®
 117                 and Octave.
 118             </warning>
 119         </para>
 120     </refsection>
 121     <refsection>
 122         <title>Examples</title>
 123         <programlisting role="example"><![CDATA[
 124 A=[1 2;3 4];
 125 A^2.5,
 126 A.^2.5
 127 (1:10)^2
 128 (1:10).^2
 129
 130 A^%i
 131 A.^%i
 132 exp(%i*log(A))
 133
 134 s=poly(0,'s')
 135 s^(1:10)
 136  ]]></programlisting>
 137     </refsection>
 138     <refsection role="see also">
 139         <title>See also</title>
 140         <simplelist type="inline">
 141             <member>
 142                 <link linkend="exp">exp</link>
 143             </member>
 144             <member>
 145                 <link linkend="hat">hat</link>
 146             </member>
 147         </simplelist>
 148     </refsection>
 149 </refentry>