Xcos load: use a valid port type value
[scilab.git] / 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&#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.
116             </warning>
117         </para>
118     </refsection>
119     <refsection>
120         <title>Examples</title>
121         <programlisting role="example"><![CDATA[ 
122 A=[1 2;3 4];
123 A^2.5,
124 A.^2.5
125 (1:10)^2
126 (1:10).^2
127
128 A^%i
129 A.^%i
130 exp(%i*log(A))
131
132 s=poly(0,'s')
133 s^(1:10)
134  ]]></programlisting>
135     </refsection>
136     <refsection role="see also">
137         <title>See Also</title>
138         <simplelist type="inline">
139             <member>
140                 <link linkend="exp">exp</link>
141             </member>
142             <member>
143                 <link linkend="hat">hat</link>
144             </member>
145         </simplelist>
146     </refsection>
147 </refentry>