[doc] power() improved page
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / exponential / power.xml
index 4872795..5760fcf 100644 (file)
@@ -1,5 +1,21 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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="fr" xml:id="power">
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+-->
+<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="fr" xml:id="power">
     <refnamediv>
         <refname>power</refname>
         <refpurpose>élévation à la puissance (^,.^)   </refpurpose>
     <refsynopsisdiv>
         <title>Séquence d'appel</title>
         <synopsis>
-            t=A^b
-            t=A**b
-            t=A.^b
+            t = A ^ b
+            t = A ** b
+            t = A .^ b
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Paramètres</title>
         <variablelist>
             <varlistentry>
-                <term>A,t  </term>
+                <term>A, t  </term>
                 <listitem>
-                    <para>matrice réelle, complexe, polynomiale ou rationnelle
-                    </para>
+                    scalaire, vecteur, ou matrice de nombres entiers encodés, de nombres
+                    ou polynômes ou fractions rationnelles à coefficients réels ou complexes.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>b  </term>
                 <listitem>
-                    <para>matrice réelle, complexe, polynomiale ou rationnelle
-                    </para>
+                    scalaire, vecteur, ou matrice d'entiers encodés, de nombres décimaux,
+                    ou de nombres complexes.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
-    </refsection>
-    <refsection>
-        <title>Description</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Si <literal>A</literal> est une matrice carrée et <literal>b</literal> un scalaire alors  <literal>A^b</literal> est la matrice <literal>A</literal> élevée à la puissance <literal>b</literal>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    Si <literal>b</literal> est un un scalaire et <literal>A</literal> une matrice alors <literal>A.^b</literal>  est la matrice formée par les éléments de <literal>A</literal> élevés à la puissance <literal>b</literal> (puissance élément par élément). Si <literal>A</literal> est un vecteur et <literal>b</literal> un scalaire alors  <literal>A^b</literal> et <literal>A.^b</literal> donnent le même résultat (puissance élément par élément).
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    Si <literal>A</literal> est un scalaire et <literal>b</literal> est une matrice carrée <literal>A^b</literal> est la matrice <literal>expm(log(A)*b)</literal>.
-                </para>
-                <para>
-                    Si <literal>A</literal> est un scalaire et <literal>b</literal> est une matrice <literal>A.^b</literal> est une matrice de même taille que b dont les termes sont égaux à <literal> a^(b(i,j))</literal>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    Si <literal>A</literal> et <literal>b</literal> sont des matrices de même taille <literal>A.^b</literal> est la matrice dont les termes sont égaux à <literal>A(i,j)^b(i,j)</literal>.
-                </para>
-            </listitem>
-        </itemizedlist>
         <para>
-            Notes :
+            Si un opérande sont des entiers encodés, l'autre peut être uniquement des entiers
+            encodés ou des nombres réels.
         </para>
         <para>
-            -
-            Pour les matrices carrées <literal>A^p</literal> est calculé par multiplications successives si <literal>p</literal> est un entier positif, et par diagonalisation sinon.
-        </para>
-        <para>
-            -
-            Les opérateurs <literal>**</literal> et <literal>^</literal> sont synonymes.
-        </para>
-        <para>
-            <warning>
-                L'élévation à la puissance est associative à droite dans Scilab contrairement à
-                Matlab® et Octave. Par exemple 2^3^4 est égal à 2^(3^4) dans Scilab mais est égal à
-                (2^3)^4 dans Matlab® et Octave.
-            </warning>
+            Si <varname>A</varname> sont des polynômes ou des fractions rationnelles,
+            <varname>b</varname> peut uniquement être un entier décimal (positif ou négatif).
         </para>
     </refsection>
     <refsection>
+        <title>Description</title>
+        <refsect3>
+            <title>.^ : puissances respectives par élément</title>
+            <para>
+                Si <varname>A</varname> ou <varname>b</varname> est scalaire, il est préalablement
+                répliqué à la taille de l'autre, par A*ones(b) ou b*ones(A).
+                Sinon, <varname>A</varname> et <varname>b</varname> doivent avoir la même taille.
+            </para>
+            <para>
+                Alors, pour chaque élément numéro i, <literal>t(i) = A(i)^b(i)</literal>
+                est calculé.
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>^ : puissance matricielle</title>
+            <para>
+                L'opérateur ^ est équivalent à .^ dans les cas suivants :
+                <itemizedlist>
+                    <listitem>
+                        <varname>A</varname> est scalaire et <varname>b</varname> est un vecteur.
+                    </listitem>
+                    <listitem>
+                        <varname>A</varname> est un vecteur et <varname>b</varname> est scalaire.
+                    </listitem>
+                </itemizedlist>
+                Sinon, <varname>A</varname> ou <varname>b</varname> doit être scalaire, et l'autre
+                opérande  doit être une matrice carrée :
+                <itemizedlist>
+                    <listitem>
+                        <para>
+                            Si <varname>A</varname> est scalaire et <varname>b</varname> est carrée,
+                            alors <literal>A^b</literal> est la matrice
+                            <literal>expm(log(A) * b)</literal>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+                            Si <varname>A</varname> est carrée et <varname>b</varname> est scalaire,
+                            alors <literal>A^b</literal> est la matrice
+                            <varname>A</varname> à la puissane <varname>b</varname>.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect3>
+        <refsect3>
+            <title>Autres remarques</title>
+            <orderedlist>
+                <listitem>
+                    <para>
+                        Si <varname>A</varname> est une matrice carrée, <literal>A^p</literal> est
+                        calculé par multiplications successives si <literal>p</literal> est un
+                        entier positif, et par diagonalisation sinon (détails en remarques n°2 et 3
+                        ci-dessous).
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        If <varname>A</varname> is a square and Hermitian matrix and <literal>p</literal>
+                        is a non-integer scalar, <literal>A^p</literal> is computed as:
+                    </para>
+                    <para>
+                        <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).
+                    </para>
+                    <para>
+                        <literal>u</literal> and <literal>s</literal> are determined by
+                        <code>[u,s] = schur(A)</code> .
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        If <varname>A</varname> is not a Hermitian matrix and <literal>p</literal> is a
+                        non-integer scalar, <literal>A^p</literal> is computed as:
+                    </para>
+                    <para>
+                        <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).
+                    </para>
+                    <para>
+                        <literal>d</literal> and <literal>v</literal> are determined by
+                        <code>[d,v] = bdiag(A+0*%i)</code>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        If <varname>A</varname> and <literal>p</literal> are real or complex numbers,
+                        <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by
+                    </para>
+                    <para>
+                        <code>A^p = exp(p*log(A))</code>
+                    </para>
+                    <para>
+                        (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ).
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        If <varname>A</varname> is a square matrix and <literal>p</literal> is a real or
+                        complex number, <literal>A.^p</literal> is the <emphasis>principal value</emphasis>
+                        computed as:
+                    </para>
+                    <para>
+                        <code>A.^p = exp(p*log(A))</code> (same as case 4 above).
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Les opérateurs <literal>**</literal> et <literal>^</literal> sont équivalents.
+                    </para>
+                </listitem>
+            </orderedlist>
+            <para>
+                <warning>
+                    L'élévation à la puissance est associative à droite dans Scilab contrairement à
+                    Matlab® et Octave. Par exemple 2^3^4 est égal à 2^(3^4) dans Scilab mais est égal à
+                    (2^3)^4 dans Matlab® et Octave.
+                </warning>
+            </para>
+        </refsect3>
+    </refsection>
+    <refsection>
         <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-A=[1 2;3 4];
-A^2.5,
-A.^2.5
-(1:10)^2
-(1:10).^2
+A = [1 2 ; 3 4];
+A ^ 2.5,
+A .^ 2.5
+(1:10) ^ 2
+(1:10) .^ 2
+
+A ^ %i
+A .^ %i
+exp(%i*log(A))
 
-s=poly(0,'s')
-s^(1:10)
+s = poly(0,'s')
+s ^ (1:10)
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -97,8 +203,27 @@ s^(1:10)
                 <link linkend="exp">exp</link>
             </member>
             <member>
+                <link linkend="expm">expm</link>
+            </member>
+            <member>
                 <link linkend="hat">hat</link>
             </member>
+            <member>
+                <link linkend="inv">inv</link>
+            </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>Historique</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0.0</revnumber>
+                <revdescription>
+                    Avec des nombres décimaux ou complexes, <literal>scalaire ^ matriceCarrée</literal>
+                    produit désormais <literal>expm(log(scalaire)*matriceCarrée)</literal> au lieu
+                    de <literal>scalaire .^ matriceCarrée</literal>.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>