<?xml version="1.0" encoding="utf-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS
 *
 * 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="eigs" xml:lang="en">
    <refnamediv>
        <refname>eigs</refname>
        <refpurpose>calculates largest eigenvalues and eigenvectors of matrices</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            d = eigs(A)
            d = eigs(Af, n)
            d = eigs(.., B)
            d = eigs(.., B, k)
            d = eigs(.., B, k, sigma)
            d = eigs(.., B, k, sigma, opts)
            [d, v] = eigs(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A </term>
                <listitem>
                    <para>a full or sparse, real or complex, symmetric or non-symmetric square matrix</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>B</term>
                <listitem>
                    <para>
                        a sparse, real or complex, square matrix with same dimensions as
                        <literal> A</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k</term>
                <listitem>
                    <para>
                      positive integer: number of eigenvalues to be computed. By default,
                      <literal>k=min(n-1, 6)</literal> (<varname>A</varname> real symetric) or
                      <literal>k=min(n-2, 6)</literal> (otherwise) eigen values are computed,
                      with n=size(A,1).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>sigma</term>
                <listitem>
                    <para>a real scalar or a string of length 2</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>opts</term>
                <listitem>
                    <para>a structure</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Af </term>
                <listitem>
                    <para>a function</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n </term>
                <listitem>
                    <para>
                        a scalar, defined only if <literal>A</literal> is a function
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d</term>
                <listitem>
                    <para>a real or complex eigenvalues vector or diagonal matrix (eigenvalues along the diagonal)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>v</term>
                <listitem>
                    <para>
                        real or complex eigenvector matrix
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            The purpose of the eigs function is to compute the largest eigenvalues of sparse, large matrices.
        </para>
        <variablelist>
            <varlistentry>
                <term>d = eigs(A) or d = eigs(Af, n)</term>
                <listitem>
                    <para>
                        solves the eigenvalue problem <literal>A * v = lambda * v</literal>. This calling returns a vector <literal>d</literal> containing the six largest magnitude eigenvalues.
                        <literal>A</literal> is either a square matrix, which can be symmetric or non-symmetric, real or complex, full or sparse.
                    </para>
                    <para>
                        <literal>A</literal> should be represented by a function <literal>Af</literal>. In this instance, a scalar <literal>n</literal> designating
                        the length of the vector argument, must be defined. It must have the following header :
                    </para>
                    <programlisting role="no-scilab-exec">
                        <![CDATA[
function y = A ( x )
 ]]>
                    </programlisting>
                    <para>
                        This function <literal>Af</literal> must return one of the four following expressions :
                        <itemizedlist>
                            <listitem>
                                <term>A * x</term>
                                <para> if sigma is not given or is a string other than 'SM'.</para>
                            </listitem>
                            <listitem>
                                <term>A \ x</term>
                                <para> if sigma is 0 or 'SM'.</para>
                            </listitem>
                            <listitem>
                                <term>(A - sigma * I) \ x</term>
                                <para>for the standard eigenvalue problem, where I is the identity matrix.</para>
                            </listitem>
                            <listitem>
                                <term>(A - sigma * B) \ x</term>
                                <para> for the generalized eigenvalue problem.</para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>[d, v] = eigs(A) or [d, v] = eigs(Af, n)</term>
                <listitem>
                    <para>
                        returns a diagonal matrix <literal>d</literal> containing the six largest magnitude eigenvalues on the diagonal.
                        <literal>v</literal> is a n by six matrix whose columns are the six eigenvectors corresponding to the returned eigenvalues.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d = eigs(A, B)</term>
                <listitem>
                    <para>
                        solves the generalized eigenvalue problem <literal>A * v = lambda  * B * v </literal> with positive, definite matrix <literal>B</literal>.
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                if <literal>B</literal> is not specified, <literal>B = []</literal> is used.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                if <literal>B</literal> is specified, <literal>B</literal> must be the same size as A.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d = eigs(A, B, k)</term>
                <listitem>
                    <para>
                        returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d = eigs(A, B, k, sigma)</term>
                <listitem>
                    <para>
                        returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues determined by <literal>sigma</literal>.
                        <literal>sigma</literal> can be either a real or complex including 0 scalar or string.
                        If sigma is a string of length 2, it takes one of the following values :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>'LM'</literal> compute the <varname>k</varname> largest in magnitude eigenvalues (by default).
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'SM'</literal> compute the <varname>k</varname> smallest in magnitude eigenvalues (same as sigma = 0).
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'LA'</literal> compute the <varname>k</varname> Largest Algebraic eigenvalues, only for real symmetric problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'SA'</literal> compute the <varname>k</varname> Smallest Algebraic eigenvalues, only for real symmetric problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'BE'</literal> compute <varname>k</varname> eigenvalues, half from each end of the spectrum, only for real
                                symmetric problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'LR'</literal> compute the <varname>k</varname> eigenvalues of Largest Real part, only for real non-symmetric or
                                complex problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'SR'</literal> compute the <varname>k</varname> eigenvalues of Smallest Real part, only for real non-symmetric or
                                complex problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'LI'</literal> compute the <varname>k</varname> eigenvalues of Largest Imaginary part, only for real non-symmetric
                                or complex problems.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>'SI'</literal> compute the <varname>k</varname> eigenvalues of Smallest Imaginary part, only for real non-symmetric
                                or complex problems.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>d = eigs(A, B, k, sigma, opts)</term>
                <listitem>
                    <para>
                        If the <literal> opts </literal> structure is specified, different options can be used to compute the <literal>k</literal> eigenvalues :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <term>tol</term>
                                <para>
                                    required convergence tolerance. By default, <literal>tol = %eps</literal>.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>maxiter</term>
                                <para>
                                    maximum number of iterations. By default, <literal>maxiter = 300</literal>.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>ncv</term>
                                <para>
                                    number of Lanzcos basis vectors to use. For real non-symmetric problems, the <literal>ncv</literal> value must be greater or equal than <literal>2 * k + 1 </literal> and, by default, <literal>ncv = min(max(2 * k + 1, 20), nA) </literal>. For real symmetric or complex problems, <literal>ncv</literal> must be greater or equal <literal>2 * k </literal> and, by default, <literal> ncv = min(max(2 * k, 20), nA) </literal> with <literal> nA = size(A, 2) </literal>.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>resid</term>
                                <para>
                                    starting vector whose contains the initial residual vector, possibly from a previous run. By default,
                                    <literal>resid</literal> is a random initial vector.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>cholB</term>
                                <para>
                                    if <literal>chol(B)</literal> is passed rather than <literal>B</literal>. By default, <literal>cholB</literal> is %f.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>isreal</term>
                                <para>
                                    if <literal>Af</literal> is given, <literal>isreal</literal> can be defined. By default, <literal>isreal</literal> is %t.
                                    This argument must not be indicated if <literal>A</literal> is a matrix.
                                </para>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <term>issym</term>
                                <para>
                                    if <literal>Af</literal> is given, <literal>issym</literal> can be defined. By default, <literal>issym</literal> is %f.
                                    This argument must not be indicated if <literal>A</literal> is a matrix.
                                </para>
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>References</title>
        <para>
            This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang.
        </para>
        <itemizedlist>
            <listitem>
                <para>DSAUPD and DSEUPD routines for real symmetric problems,</para>
            </listitem>
            <listitem>
                <para>DNAUPD and DNEUPD routines for real non-symmetric problems.</para>
            </listitem>
            <listitem>
                <para>ZNAUPD and ZNEUPD routines for complex problems.</para>
            </listitem>
        </itemizedlist>
    </refsection>
    <refsection>
        <title>Example for real symmetric problems</title>
        <programlisting role="example">
            <![CDATA[
clear opts
A            = diag(10*ones(10,1));
A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1));

B = eye(10,10);
k = 8;
sigma = 'SM';
opts.cholB = %t;

d = eigs(A)
[d, v] = eigs(A)

d = eigs(A, B, k, sigma)
[d, v] = eigs(A, B, k, sigma)

d = eigs(A, B, k, sigma, opts)
[d, v] = eigs(A, B, k, sigma, opts)

// With sparses
AS = sparse(A);
BS = sparse(B);

d = eigs(AS)
[d, v] = eigs(AS)

d = eigs(AS, BS, k, sigma)
[d, v] = eigs(AS, BS, k, sigma)

d = eigs(AS, BS, k, sigma, opts)
[d, v] = eigs(AS, BS, k, sigma, opts)

// With function
clear opts
function y = fn(x)
   y = A * x;
endfunction

opts.isreal = %t;
opts.issym = %t;

d = eigs(fn, 10, [], k, 'LM', opts)

function y = fn(x)
   y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y = fn(x)
   y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)
 ]]>
        </programlisting>
    </refsection>
    <refsection>
        <title>Example for real non-symmetric problems</title>
        <programlisting role="example">
            <![CDATA[
	clear opts
    A            = diag(10*ones(10,1));
    A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
    A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));

    B = eye(10,10);
    k = 8;
    sigma = 'SM';
    opts.cholB = %t;

    d = eigs(A)
[d, v] = eigs(A)

    d = eigs(A, B, k, sigma)
    [d, v] = eigs(A, B, k, sigma)

    d = eigs(A, B, k, sigma, opts)
    [d, v] = eigs(A, B, k, sigma, opts)

// With sparses
    AS = sparse(A);
    BS = sparse(B);

d = eigs(AS)
[d, v] = eigs(AS)
    d = eigs(AS, BS, k, sigma)
    [d, v] = eigs(AS, BS, k, sigma)

    d = eigs(AS, BS, k, sigma, opts)
    [d, v] = eigs(AS, BS, k, sigma, opts)

    // With function
clear opts
function y = fn(x)
   y = A * x;
endfunction

opts.isreal = %t;
opts.issym = %f;

d = eigs(fn, 10, [], k, 'LM', opts)

function y = fn(x)
   y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y = fn(x)
   y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)
    ]]>
        </programlisting>
    </refsection>
    <refsection>
        <title>Example for complex problems</title>
        <programlisting role="example">
            <![CDATA[
	clear opts
    A            = diag(10*ones(10,1) + %i * ones(10,1));
    A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
    A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));

    B = eye(10,10);
    k = 8;
    sigma = 'LM';
    opts.cholB = %t;

    d = eigs(A)
[d, v] = eigs(A)

    d = eigs(A, B, k, sigma)
    [d, v] = eigs(A, B, k, sigma)
    d = eigs(A, B, k, sigma, opts)
    [d, v] = eigs(A, B, k, sigma, opts)

    // With sparses
    AS = sparse(A);
    BS = sparse(B);

    d = eigs(AS)
[d, v] = eigs(AS)

    d = eigs(AS, BS, k, sigma)
    [d, v] = eigs(AS, BS, k, sigma)

    d = eigs(AS, BS, k, sigma, opts)
    [d, v] = eigs(AS, BS, k, sigma, opts)

    // With function
clear opts
function y = fn(x)
   y = A * x;
endfunction

opts.isreal = %f;
opts.issym = %f;

d = eigs(fn, 10, [], k, 'LM', opts)

function y = fn(x)
   y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y = fn(x)
   y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)
    ]]>
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="spec">spec</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>Function introduced.</revremark>
            </revision>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revremark>
                    dnaupd, dneupd, dsaupd, dseupd, znaupd and zneupd become internal.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
