<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2021 - 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="spec">
    <refnamediv>
        <refname>spec</refname>
        <refpurpose>
            valeurs propres, et vecteurs propres d'une matrice ou d'un faisceau de matrices
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            evals          = spec(A)
            [R, diagevals] = spec(A)

            evals               = spec(A, B)
            [alpha, beta]       = spec(A, B)
            [alpha, beta, Z]    = spec(A, B)
            [alpha, beta, Q, Z] = spec(A, B)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>A, B</term>
                <listitem>
                    Matrices carrées réelles ou complexes, de mêmes tailles.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>evals</term>
                <listitem>
                    Vecteur réel ou complexe
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>diagevals</term>
                <listitem>
                    Matrice carrée diagonale réelle ou complexe : les éléments diagonaux sont
                    les valeurs propres.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>R</term>
                <listitem>
                    Matrice carrée inversible réelle ou complexe des vecteurs propres à droite.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>alpha, beta</term>
                <listitem>
                    Vecteurs de mêmes tailles: valeurs propres généralisées du faisceau
                    de matrices <literal>A - s.B</literal>.
                    alpha./beta donne les valeurs propres.
                    <varname>alpha</varname> est à valeurs réelles ou complexes.
                    <varname>beta</varname> est à valeurs réelles.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Q</term>
                <listitem>
                    Matrice carrée inversible réelle ou complexe des vecteurs propres
                    généralisés à gauche.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Z</term>
                <listitem>
                    Matrice carrée inversible réelle ou complexe des vecteurs propres
                    généralisés à droite.
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            <emphasis role="bold">evals = spec(A)</emphasis> calcule les valeurs propres de
            <literal>A</literal> et les fournit dans le vecteur <literal>evals</literal>.
        </para>
        <para>
            <emphasis role="bold">[R, diagevals] = spec(A)</emphasis> fournit les valeurs propres
            sur la diagonale de la matrice diagonale <varname>diagevals</varname>.
            La matrice <varname>R</varname> produite contient les vecteurs propres à droite
            (s'ils existent). Voir Aussi <literal>bdiag(…)</literal>.
        </para>
        <para>
            Lorsque <literal>spec(A)</literal> est utilisée pour une seule matrice,
            le caractère réel ou complexe des résultats est le suivant :
            <informaltable border="1">
            <tr><th>matrice A</th>
                <td colspan="2" align="center">Réelle</td><td colspan="2" align="center">Complexe</td>
            </tr>
            <tr align="center"><td> </td>
                <td>Symétrique</td><td>Asymétrique</td><td>Hermitienne</td><td>Non hermitienne</td>
            </tr>
            <tr><th>Valeurs propres</th>
                <td>réelles</td>   <td>complexes</td>  <td>réelles</td>   <td>complexes</td>
            </tr>
            <tr><th>Vecteurs propres</th>
                <td>réels</td>     <td>complexes</td>  <td>complexes</td> <td>complexes</td>
            </tr>
            </informaltable>
        </para>
        <para>
            Une matrice complexe hermitienne est égale à sa transposée conjuguée.
        </para>
        <refsect3>
            <title>Faisceau matriciel A - s.B</title>
            <para>
                <emphasis role="bold">evals = spec(A, B)</emphasis> retourne le  spectre du faisceau
                <literal>A - s.B</literal>, c'est à dire les racines du déterminant de la matrice de
                polynômes <literal>A - s.B</literal>.
            </para>
            <para>
                <emphasis role="bold">[alpha, beta] = spec(A, B)</emphasis>
                retourne les valeurs propres généralisées <varname>alpha</varname> et
                <varname>beta</varname> du faisceau, telles que <literal>alpha./beta</literal>
                sont les valeurs propres usuelles, c'est à dire les racines du déterminant de
                la matrice de polynômes <literal>s E - A</literal>.
                La matrice <literal>A - alpha./beta × B</literal> est alors singulière.
                Si <literal>beta(i) = 0</literal>, la i<superscript>ème</superscript>
                valeur propre est infinie.
            </para>
            <para>
                Pour <literal>B = eye(A)</literal>, <literal>alpha./beta</literal> est
                égal à <literal>spec(A)</literal>.
            </para>
            <para>
                <emphasis role="bold">[alpha, beta, Z] = spec(A, B)</emphasis>
                produit en outre la matrice <literal>Z</literal> des vecteurs propres
                généralisés à droite.
            </para>
            <para>
                <emphasis role="bold">[alpha, beta, Q, Z] = spec(A, B)</emphasis>
                permet finalement d'obtenir la matrice <literal>Q</literal> des vecteurs
                propres généralisés à gauche.
            </para>
        </refsect3>
        <para>
            <note>
                Pour les matrices denses ou creuses de grande taille, la fonction
                <link linkend="eigs">eigs</link> peut être utilisée.
            </note>
        </para>
    </refsection>
    <refsection>
        <title>Fonctions utilisées</title>
        <para>
            Le calcul des valeurs propres des matrices est basé sur les programmes Lapack
        </para>
        <itemizedlist>
            <listitem>
                <para>DGEEV and ZGEEV, lorsque la matrice A n'est ni symétrique ni hermitienne.</para>
            </listitem>
            <listitem>
                <para>DSYEV and ZHEEV, lorsque la matrice A est symétrique ou hermitienne.</para>
            </listitem>
        </itemizedlist>
        <para>
            Le calcul des valeurs propres des faisceaux est basé sur les programmes
            Lapack routines DGGEV et ZGGEV.
        </para>
    </refsection>
    <refsection role="examples">
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
// Valeurs propres d'une matrice
A = diag([1,2,3]);
X = rand(3,3);
A = inv(X)*A*X;
spec(A)

x = poly(0,'x');
pol = det(x*eye(3,3)-A)
roots(pol)

[S,X] = bdiag(A);
clean(inv(X)*A*X)

// Valeurs et vecteurs propres d'un faisceau de matrices
A = rand(3,3);
[al, be, Z] = spec(A,eye(A));al./be
clean(inv(Z)*A*Z)    // affiche les valeurs propres (matrice générique)
A = A+%i*rand(A);
E = rand(A);
roots(det(%s*E-A))   // cas à valeurs propres complexes
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="eigs">eigs</link>
            </member>
            <member>
                <link linkend="bdiag">bdiag</link>
            </member>
            <member>
                <link linkend="schur">schur</link>
            </member>
            <member>
                <link linkend="colcomp">colcomp</link>
            </member>
            <member>
                <link linkend="det">det</link>
            </member>
            <member>
                <link linkend="poly">poly</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
