<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="spec" xml:lang="en">
    <refnamediv>
        <refname>spec</refname>
        <refpurpose>eigenvalues of matrices and pencils</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</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>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A</term>
                <listitem>
                    <para>real or complex square matrix</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>B</term>
                <listitem>
                    <para>real or complex square matrix with same dimensions as
                        <literal> A</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>evals</term>
                <listitem>
                    <para>real or complex vector, the eigenvalues</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>diagevals</term>
                <listitem>
                    <para>real or complex diagonal matrix (eigenvalues along the
                        diagonal)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>alpha</term>
                <listitem>
                    <para>real or complex vector, al./be gives the eigenvalues</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>beta</term>
                <listitem>
                    <para>real vector, al./be gives the eigenvalues</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>R</term>
                <listitem>
                    <para>real or complex invertible square matrix, matrix right
                        eigenvectors.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>L</term>
                <listitem>
                    <para>real or complex invertible square matrix, pencil left
                        eigenvectors.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>R</term>
                <listitem>
                    <para>real or complex invertible square matrix, pencil right
                        eigenvectors.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <variablelist>
            <varlistentry>
                <term>evals=spec(A)</term>
                <listitem>
                    <para>
                        returns in vector <literal>evals</literal> the
                        eigenvalues.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[R,diagevals] =spec(A)</term>
                <listitem>
                    <para>
                        returns in the diagonal matrix <literal>evals</literal> the
                        eigenvalues and in <literal>R</literal> the right
                        eigenvectors.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>evals=spec(A,B)</term>
                <listitem>
                    <para>returns the spectrum of the matrix pencil A - s B, i.e. the
                        roots of the polynomial matrix s B - A.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[alpha,beta] = spec(A,B)</term>
                <listitem>
                    <para>
                        returns the spectrum of the matrix pencil <literal>A- s
                            B
                        </literal>
                        ,i.e. the roots of the polynomial matrix <literal>A - s
                            B
                        </literal>
                        .Generalized eigenvalues alpha and beta are so that the
                        matrix <literal>A - alpha./beta B</literal> is a singular matrix.
                        The eigenvalues are given by <literal>al./be</literal> and if
                        <literal>beta(i) = 0</literal> the ith eigenvalue is at infinity.
                        (For <literal>B = eye(A), alpha./beta</literal> is
                        <literal>spec(A)</literal>). It is usually represented as the pair
                        (alpha,beta), as there is a reasonable interpretation for beta=0,
                        and even for both being zero.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[alpha,beta,R] = spec(A,B)</term>
                <listitem>
                    <para>
                        returns in addition the matrix <literal>R</literal> of
                        generalized right eigenvectors of the pencil.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[al,be,L,R] = spec(A,B)</term>
                <listitem>
                    <para>
                        returns in addition the matrix <literal>L</literal> and
                        <literal>R</literal> of generalized left and right eigenvectors of
                        the pencil.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[al,be,Z] = spec(A,E)</term>
                <listitem>
                    <para>
                        returns the matrix <literal>Z</literal> of right
                        generalized eigen vectors.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[al,be,Q,Z] = spec(A,E)</term>
                <listitem>
                    <para>
                        returns the matrices <literal>Q</literal>
                        and <literal>Z</literal> of right and left generalized
                        eigen vectors.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>For big full / sparse matrix, you can use the Arnoldi module.</para>
    </refsection>
    <refsection>
        <title>References</title>
        <para>Matrix eigenvalues computations are based on the Lapack
            routines
        </para>
        <itemizedlist>
            <listitem>
                <para>DGEEV and ZGEEV when the matrix are not symmetric,</para>
            </listitem>
            <listitem>
                <para>DSYEV and ZHEEV when the matrix are symmetric.</para>
            </listitem>
        </itemizedlist>
        <para>A complex symmetric matrix has conjugate offdiagonal terms and real
            diagonal terms.
        </para>
        <para>Pencil eigenvalues computations are based on the Lapack routines
            DGGEV and ZGGEV.
        </para>
    </refsection>
    <refsection>
        <title>Real and complex matrices</title>
        <para>It must be noticed that the type of the output variables, such as
            evals or R for example, is not necessarily the same as the type of the
            input matrices A and B. In the following paragraph, we analyse the type of
            the output variables in the case where one computes the eigenvalues and
            eigenvectors of one single matrix A.
        </para>
        <itemizedlist>
            <listitem>
                <para>Real A matrix</para>
                <itemizedlist>
                    <listitem>
                        <para>Symmetric</para>
                        <para>The eigenvalues and the eigenvectors are real.</para>
                    </listitem>
                    <listitem>
                        <para>Not symmetric</para>
                        <para>The eigenvalues and eigenvectors are complex.</para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>Complex A matrix</para>
                <itemizedlist>
                    <listitem>
                        <para>Symmetric</para>
                        <para>The eigenvalues are real but the eigenvectors are
                            complex.
                        </para>
                    </listitem>
                    <listitem>
                        <para>Not symmetric</para>
                        <para>The eigenvalues and the eigenvectors are complex.</para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// MATRIX EIGENVALUES
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)

// PENCIL EIGENVALUES
A=rand(3,3);
[al,be,R] = spec(A,eye(A));
al./be
clean(inv(R)*A*R)  //displaying the eigenvalues (generic matrix)
A=A+%i*rand(A);
E=rand(A);
roots(det(A-%s*E))   //complex case
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="poly">poly</link>
            </member>
            <member>
                <link linkend="det">det</link>
            </member>
            <member>
                <link linkend="schur">schur</link>
            </member>
            <member>
                <link linkend="bdiag">bdiag</link>
            </member>
            <member>
                <link linkend="colcomp">colcomp</link>
            </member>
            <member>
                <link linkend="dsaupd">dsaupd</link>
            </member>
            <member>
                <link linkend="dnaupd">dnaupd</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
