b2442bc0dfe18efd0e4f454fde878a2f8fa1cc11
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / 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>Calling Sequence</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 matrix (or vector) <literal>A^b</literal> and <literal>A.^b</literal> are the matrices (or vectors) formed by  <literal> a^(b(i,j))</literal>.
52                 </para>
53             </listitem>
54             <listitem>
55                 <para>
56                     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).
57                 </para>
58             </listitem>
59         </itemizedlist>
60     </refsection>
61     <refsection>
62         <title>Additional Remarks</title>
63         <para>
64             <note> Notes: </note>
65         </para>
66         <para>
67             1. For square matrices <literal>A^p</literal> is computed through successive matrices 
68             multiplications if <literal>p</literal> is a positive integer, and by <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
69         </para>
70         <para>
71             2. If <varname>A</varname> is a square and Hermitian matrix and <varname>p</varname> is a non-integer scalar,
72             <literal>A^p</literal> is computed as:
73         </para>
74         <para>
75             <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). 
76         </para>
77         <para>
78             <varname>u</varname> and <varname>s</varname> are determined by <code>[u,s] = schur(A)</code> . 
79         </para>
80         <para>
81             3. If <varname>A</varname> is not a Hermitian matrix and <varname>p</varname> is a non-integer scalar,
82             <literal>A^p</literal> is computed as:
83         </para>
84         <para>
85             <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). 
86         </para>
87         <para>
88             <varname>d</varname> and <varname>v</varname> are determined by <code>[d,v] = bdiag(A+0*%i)</code> . 
89         </para>
90         <para>
91             4. If <varname>A</varname> and <varname>p</varname> are real or complex numbers,
92             <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by:
93         </para>
94         <para>
95             <code>A^p = exp(p*log(A))</code> (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ). 
96         </para>
97         <para>
98             5. If <varname>A</varname> is a square matrix and <varname>p</varname> is a real or complex number,
99             <literal>A.^p</literal> is the <emphasis>principal value</emphasis> computed as:
100         </para>
101         <para>
102             <code>A.^p = exp(p*log(A))</code> (same as case 4 above). 
103         </para>
104         <para>
105             6. <literal>**</literal> and <literal>^</literal> operators are synonyms.
106         </para>
107         <para>
108             <warning>
109                 Exponentiation is right-associative in Scilab contrarily to Matlab&#174; and Octave. For example 2^3^4 is equal to 2^(3^4) in Scilab but is equal to (2^3)^4 in Matlab&#174; and Octave.
110             </warning>
111         </para>
112     </refsection>
113     <refsection>
114         <title>Examples</title>
115         <programlisting role="example"><![CDATA[ 
116 A=[1 2;3 4];
117 A^2.5,
118 A.^2.5
119 (1:10)^2
120 (1:10).^2
121
122 A^%i
123 A.^%i
124 exp(%i*log(A))
125
126 s=poly(0,'s')
127 s^(1:10)
128  ]]></programlisting>
129     </refsection>
130     <refsection role="see also">
131         <title>See Also</title>
132         <simplelist type="inline">
133             <member>
134                 <link linkend="exp">exp</link>
135             </member>
136             <member>
137                 <link linkend="hat">hat</link>
138             </member>
139         </simplelist>
140     </refsection>
141 </refentry>