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>