<?xml version="1.0" encoding="UTF-8"?>
<!--
 * 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>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            t = A ^ b
            t = A ** b
            t = A .^ b
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>A, t  </term>
                <listitem>
                    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>
                    scalaire, vecteur, ou matrice d'entiers encodés, de nombres décimaux,
                    ou de nombres complexes.
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            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>
            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 ^ %i
A .^ %i
exp(%i*log(A))

s = poly(0,'s')
s ^ (1:10)
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <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>
