[doc] power() improved page
[scilab.git] / scilab / modules / elementary_functions / help / en_US / exponential / power.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2012 - 2016 - Scilab Enterprises
5  * Copyright (C) 2020 - Samuel GOUGEON
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  *
14 -->
15 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18           xml:lang="en" xml:id="power">
19     <refnamediv>
20         <refname>power</refname>
21         <refpurpose>(^,.^) power operation</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26             t = A ^ b
27             t = A ** b
28             t = A .^ b
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>A, t</term>
36                 <listitem>
37                     a scalar, vector, or matrix of encoded integers, decimal or complex numbers,
38                     polynomials, or rationals.
39                     <para/>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>b</term>
44                 <listitem>
45                     a scalar, vector, or matrix of encoded integers, decimal or complex numbers.
46                     <para/>
47                 </listitem>
48             </varlistentry>
49         </variablelist>
50         <para>
51             If an operand are encoded integers, the other one can be only encoded integers or real
52             numbers.
53         </para>
54         <para>
55             If <varname>A</varname> are polynomials or rationals, <varname>b</varname> can only be
56             a single decimal (positive or negative) integer.
57         </para>
58     </refsection>
59     <refsection>
60         <title>Description</title>
61         <refsect3>
62             <title>.^ by-element power</title>
63             <para>
64                 If <varname>A</varname> or <varname>b</varname> is scalar, it is first
65                 replicated to the size of the other, with A*ones(b) or b*ones(A).
66                 Otherwise, <varname>A</varname> and <varname>b</varname> must have the same size.
67             </para>
68             <para>
69                 Then, for each element of index i, <literal>t(i) = A(i)^b(i)</literal>
70                 is computed.
71             </para>
72         </refsect3>
73         <refsect3>
74             <title>^ matricial power</title>
75             <para>
76                 The ^ operator is equivalent to the .^ by-element power in the following cases:
77                 <itemizedlist>
78                     <listitem>
79                         <varname>A</varname> is scalar and <varname>b</varname> is a vector.
80                     </listitem>
81                     <listitem>
82                         <varname>A</varname> is a vector and <varname>b</varname> is scalar.
83                     </listitem>
84                 </itemizedlist>
85                 Otherwise, <varname>A</varname> or <varname>b</varname> must be a scalar,
86                 and the other one must be a square matrix:
87                 <itemizedlist>
88                     <listitem>
89                         <para>
90                             If <varname>A</varname> is scalar and <varname>b</varname> is
91                             a square matrix, then <literal>A^b</literal> is the matrix
92                             <literal>expm(log(A) * b)</literal>
93                         </para>
94                     </listitem>
95                     <listitem>
96                         <para>
97                             If <varname>A</varname> is a square matrix and <varname>b</varname>
98                             is scalar, then  <literal>A^b</literal> is the matrix
99                             <varname>A</varname> to the power <varname>b</varname>.
100                         </para>
101                     </listitem>
102                 </itemizedlist>
103             </para>
104         </refsect3>
105         <refsect3>
106             <title>Remarks</title>
107             <orderedlist>
108                 <listitem>
109                     <para>
110                         For square matrices <literal>A^p</literal> is computed through successive
111                         matrices multiplications if <literal>p</literal> is a positive integer, and by
112                         <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
113                     </para>
114                 </listitem>
115                 <listitem>
116                     <para>
117                         If <varname>A</varname> is a square and Hermitian matrix and <literal>p</literal>
118                         is a non-integer scalar, <literal>A^p</literal> is computed as:
119                     </para>
120                     <para>
121                         <code>A^p = u*diag(diag(s).^p)*u'</code> (For real matrix <varname>A</varname>,
122                         only the real part of the answer is taken into account).
123                     </para>
124                     <para>
125                         <literal>u</literal> and <literal>s</literal> are determined by
126                         <code>[u,s] = schur(A)</code> .
127                     </para>
128                 </listitem>
129                 <listitem>
130                     <para>
131                         If <varname>A</varname> is not a Hermitian matrix and <literal>p</literal> is a
132                         non-integer scalar, <literal>A^p</literal> is computed as:
133                     </para>
134                     <para>
135                         <code>A^p = v*diag(diag(d).^p)*inv(v)</code> (For real matrix <varname>A</varname>,
136                         only the real part of the answer is taken into account).
137                     </para>
138                     <para>
139                         <literal>d</literal> and <literal>v</literal> are determined by
140                         <code>[d,v] = bdiag(A+0*%i)</code>.
141                     </para>
142                 </listitem>
143                 <listitem>
144                     <para>
145                         If <varname>A</varname> and <literal>p</literal> are real or complex numbers,
146                         <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by
147                     </para>
148                     <para>
149                         <code>A^p = exp(p*log(A))</code>
150                     </para>
151                     <para>
152                         (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ).
153                     </para>
154                 </listitem>
155                 <listitem>
156                     <para>
157                         If <varname>A</varname> is a square matrix and <literal>p</literal> is a real or
158                         complex number, <literal>A.^p</literal> is the <emphasis>principal value</emphasis>
159                         computed as:
160                     </para>
161                     <para>
162                         <code>A.^p = exp(p*log(A))</code> (same as case 4 above).
163                     </para>
164                 </listitem>
165                 <listitem>
166                     <para>
167                         <literal>**</literal> and <literal>^</literal> operators are synonyms.
168                     </para>
169                 </listitem>
170             </orderedlist>
171             <para>
172                 <warning>
173                     Exponentiation is right-associative in Scilab, contrarily to MatlabĀ® and Octave.
174                     For example 2^3^4 is equal to 2^(3^4) in Scilab, but to (2^3)^4 in MatlabĀ® and Octave.
175                 </warning>
176             </para>
177         </refsect3>
178     </refsection>
179     <refsection>
180         <title>Examples</title>
181         <programlisting role="example"><![CDATA[
182 A = [1 2 ; 3 4];
183 A ^ 2.5,
184 A .^ 2.5
185 (1:10) ^ 2
186 (1:10) .^ 2
187
188 A ^ %i
189 A .^ %i
190 exp(%i*log(A))
191
192 s = poly(0,'s')
193 s ^ (1:10)
194  ]]></programlisting>
195     </refsection>
196     <refsection role="see also">
197         <title>See also</title>
198         <simplelist type="inline">
199             <member>
200                 <link linkend="exp">exp</link>
201             </member>
202             <member>
203                 <link linkend="expm">expm</link>
204             </member>
205             <member>
206                 <link linkend="hat">hat</link>
207             </member>
208             <member>
209                 <link linkend="inv">inv</link>
210             </member>
211         </simplelist>
212     </refsection>
213     <refsection role="history">
214         <title>History</title>
215         <revhistory>
216             <revision>
217                 <revnumber>6.0.0</revnumber>
218                 <revdescription>
219                     With decimal or complex numbers, <literal>scalar ^ squareMat</literal> now
220                     yields <literal>expm(log(scalar)*squareMat)</literal> instead of
221                     <literal>scalar .^ squareMat</literal>
222                 </revdescription>
223             </revision>
224         </revhistory>
225     </refsection>
226 </refentry>