<?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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="ja" xml:id="schur">

    <refnamediv>

        <refname>schur</refname>

        <refpurpose>行列およびペンシルの[ソートされた] Schur 分解</refpurpose>

    </refnamediv>

    <refsynopsisdiv>

        <title>呼び出し手順</title>

        <synopsis>[U,T] = schur(A)

            [U,dim [,T] ]=schur(A,flag)

            [U,dim [,T] ]=schur(A,extern1)



            [As,Es [,Q,Z]]=schur(A,E)

            [As,Es [,Q],Z,dim] = schur(A,E,flag)

            [Z,dim] = schur(A,E,flag)

            [As,Es [,Q],Z,dim]= schur(A,E,extern2)

            [Z,dim]= schur(A,E,extern2)

        </synopsis>

    </refsynopsisdiv>

    <refsection>

        <title>引数</title>

        <variablelist>

            <varlistentry>

                <term>A</term>

                <listitem>

                    <para>実数または複素数の正方行列.</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>E</term>

                <listitem>

                    <para>

                        <literal>A</literal>と同じ次元の実数または複素数の正方行列.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>flag</term>

                <listitem>

                    <para>

                        文字列 (<literal>'c'</literal> または <literal>'d'</literal>)

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>extern1</term>

                <listitem>

                    <para>an ``external'', 以下の参照</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>extern2</term>

                <listitem>

                    <para>an ``external'', 以下の参照</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>U</term>

                <listitem>

                    <para>直交またはユニタリ正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>Q</term>

                <listitem>

                    <para>直交またはユニタリ正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>Z</term>

                <listitem>

                    <para>o直交またはユニタリ正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>T</term>

                <listitem>

                    <para>上三角または準三角正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>As</term>

                <listitem>

                    <para>上三角または準三角正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>Es</term>

                <listitem>

                    <para>上三角正方行列</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>dim</term>

                <listitem>

                    <para>整数</para>

                </listitem>

            </varlistentry>

        </variablelist>

    </refsection>

    <refsection>

        <title>説明</title>

        <para>

            Schur 形式, 行列およびペンシルのソートされた Schur 形式

        </para>

        <variablelist>

            <varlistentry>

                <term>行列Schur形式</term>

                <listitem>

                    <variablelist>

                        <varlistentry>

                            <term>通常のSchur形式:</term>

                            <listitem>

                                <para>

                                    <literal>[U,T] = schur(A)</literal> は,

                                    <literal>A = U*T*U'</literal> および <literal>U'*U =  eye(U)</literal>となるような

                                    Schur行列<literal>T</literal> およびユニタリ行列 <literal>U</literal>

                                    を出力します.

                                    Schur(<literal>A</literal>)は,<literal>T</literal>を返します.

                                    <literal>A</literal> が複素数の場合, 複素Schur形式は,行列<literal>T</literal>に返します.

                                    複素Schur形式は,<literal>A</literal>の固有値を対角項に有する上三角行列です.

                                    <literal>A</literal> が実数の場合, 実数Schur形式が返されます.

                                    実数Schur形式は,対角項に実数固有値、複素数固有値を対角項の2x2ブロックに

                                    有します.

                                </para>

                            </listitem>

                        </varlistentry>

                        <varlistentry>

                            <term>ソートされたSchur形式</term>

                            <listitem>

                                <para>

                                    <literal>[U,dim]=schur(A,'c')</literal> は,

                                    <literal>A</literal>を Schur 形式に変換する

                                    ユニタリ行列 <literal>U</literal> を返します.

                                    更に,<literal>U</literal>の最初の列 dim は,

                                    実部が負の固有値(安定な"連続時間"固有値空間)

                                    に関連する<literal>A</literal>の固有値空間

                                    の基底を構成します.

                                </para>

                                <para>

                                    <literal>[U,dim]=schur(A,'d')</literal> は,

                                    <literal>A</literal>を Schur 形式に変換する

                                    ユニタリ行列 <literal>U</literal> を返します.

                                    更に,<literal>U</literal>の最初の列 dim は,

                                    大きさが1未満の固有値(安定な"離散時間"固有値空間)

                                    に関連する<literal>A</literal>の固有値空間

                                    の基底を構成します.

                                </para>

                                <para>

                                    <literal>[U,dim]=schur(A,extern1)</literal> は,

                                    <literal>A</literal>を Schur 形式に変換する

                                    ユニタリ行列<literal>U</literal>を返します.

                                    更に,<literal>U</literal>の最初の列 dim は,

                                    外部関数 <literal>extern1</literal> (詳細は external 参照)

                                    により選択された固有値に関連する<literal>A</literal>の固有値空間

                                    の基底を構成します.

                                    この external はScilab関数またはCまたはFortranプロシージャにより

                                    次のように記述することができます:

                                </para>

                                <variablelist>

                                    <varlistentry>

                                        <term>Scilab関数</term>

                                        <listitem>

                                            <para>

                                                <literal>extern1</literal>が

                                                Scilab関数により記述される場合,

                                                以下の呼び出し手順を有する必要があります:

                                                <literal>s=extern1(Ev)</literal>, ただし <literal>Ev</literal> は固有値,

                                                <literal>s</literal> は論理値です.

                                            </para>

                                        </listitem>

                                    </varlistentry>

                                    <varlistentry>

                                        <term>C または Fortran プロシージャ</term>

                                        <listitem>

                                            <para>

                                                <literal>extern1</literal> がCまたはFortran関数により

                                                記述される場合,以下の呼び出し手順を有する必要があります:

                                                <literal>int extern1(double *EvR, double *EvI)</literal>

                                                ただし <literal>EvR</literal> および <literal>EvI</literal> は

                                                固有値の実部および虚部です.

                                                trueまたはゼロでない戻り値は,選択された固有値を意味します.

                                            </para>

                                        </listitem>

                                    </varlistentry>

                                </variablelist>

                            </listitem>

                        </varlistentry>

                    </variablelist>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term>ペンシルSchur形式</term>

                <listitem>

                    <variablelist>

                        <varlistentry>

                            <term>通常のペンシルSchur形式</term>

                            <listitem>

                                <para>

                                    <literal>[As,Es] = schur(A,E)</literal> は,

                                    対<literal>A, E</literal>の一般化Schur形式である

                                    準三角行列<literal>As</literal>行列および三角行列<literal>Es</literal>

                                    を出力します.

                                </para>

                                <para>

                                    <literal>[As,Es,Q,Z] = schur(A,E)</literal>は,更に

                                    <literal>As=Q'*A*Z</literal> および <literal>Es=Q'*E*Z</literal>となるような

                                    2つのユニタリ行列<literal>Q</literal> および <literal>Z</literal>を返します.

                                </para>

                            </listitem>

                        </varlistentry>

                        <varlistentry>

                            <term>ソートされたSchur形式:</term>

                            <listitem>

                                <para>

                                    <literal>[As,Es,Z,dim] = schur(A,E,'c')</literal>は,

                                    ペンシル<literal>s*E-A</literal>の実数一般化Schur形式を返します.

                                    更に, <literal>Z</literal>の最初の列 dim は,

                                    実部が負の固有値 (安定な"連続時間"一般化固有値空間)に関連する

                                    固有値空間の基底を構成します.

                                </para>

                                <para>

                                    <literal>[As,Es,Z,dim] = schur(A,E,'d')</literal>

                                </para>

                                <para>

                                    は,ペンシル<literal>s*E-A</literal>の

                                    実数一般化Schur形式を返します.

                                    更に, <literal>Z</literal>の最初の列 dim は,

                                    大きさ1未満の固有値 (安定な"離散時間"一般化固有値空間)に関連する

                                    固有値空間の基底を構成します.

                                </para>

                                <para>

                                    <literal>[As,Es,Z,dim] = schur(A,E,extern2)</literal>

                                </para>

                                <para>

                                    は,ペンシル<literal>s*E-A</literal>の実一般化Schur形式を返します.

                                    更に, <literal>Z</literal>の最初の列 dim は,

                                    関数<literal>extern2</literal>により指定された規則に基づき選択された

                                    ペンシルの固有値に関する固有値空間の基底を構成します.

                                    (詳細は external 参照)

                                    この external は Scilab 関数またはCまたはFortranプロシージャ

                                    により次のように記述することができます:

                                </para>

                                <variablelist>

                                    <varlistentry>

                                        <term>Scilab関数</term>

                                        <listitem>

                                            <para>

                                                <literal>extern2</literal>がScilab関数により記述される場合,

                                                以下の呼び出し手順を有する必要があります:

                                                <literal>s=extern2(Alpha,Beta)</literal>, ただし <literal>Alpha</literal> および

                                                <literal>Beta</literal> は一般化固有値および論理値 <literal>s</literal>

                                                を定義します.

                                            </para>

                                        </listitem>

                                    </varlistentry>

                                    <varlistentry>

                                        <term>C またはFortranプロシージャ</term>

                                        <listitem>

                                            <para>

                                                if external <literal>extern2</literal> がCまたはFortran関数により

                                                記述される場合,以下の呼び出し手順を有する必要があります:

                                            </para>

                                            <para>

                                                <literal>int extern2(double *AlphaR, double *AlphaI, double *Beta)</literal>

                                            </para>

                                            <para>

                                                : <literal>A</literal> および <literal>E</literal> が実数の場合.

                                            </para>

                                            <para>

                                                <literal>int extern2(double *AlphaR, double *AlphaI, double *BetaR, double *BetaI)</literal>

                                            </para>

                                            <para>

                                                : <literal>A</literal> および <literal>E</literal> が複素数の場合.

                                                <literal>Alpha</literal>, および <literal>Beta</literal> は一般化固有値を定義します.

                                                trueまたは非ゼロの戻り値は,選択された一般化固有値を意味します.

                                            </para>

                                        </listitem>

                                    </varlistentry>

                                </variablelist>

                            </listitem>

                        </varlistentry>

                    </variablelist>

                </listitem>

            </varlistentry>

        </variablelist>

    </refsection>

    <refsection>

        <title>参考</title>

        <para>

            行列Schur形式の計算はLapackルーチンDGEES および ZGEESに基づいています.

        </para>

        <para>

            ペンシルSchur形式の計算はLapackルーチンDGGES および ZGGESに基づいています.

        </para>

    </refsection>

    <refsection>

        <title>例</title>

        <programlisting role="example"><![CDATA[
//行列Schur形式
//----------------------
A=diag([-0.9,-2,2,0.9]);X=rand(A);A=inv(X)*A*X;
[U,T]=schur(A);T

[U,dim,T]=schur(A,'c');
T(1:dim,1:dim)      //安定な連続時間固有値

function t=mytest(Ev),t=abs(Ev)<0.95,endfunction
[U,dim,T]=schur(A,mytest);
T(1:dim,1:dim)

// Cの同じ関数 (コンパイラが必要)
cd TMPDIR;
C=['int mytest(double *EvR, double *EvI) {' //the C code
   'if (*EvR * *EvR + *EvI * *EvI < 0.9025) return 1;'
   'else return 0; }';]
mputl(C,TMPDIR+'/mytest.c')


//構築/リンク
lp=ilib_for_link('mytest','mytest.c',[],'c');
link(lp,'mytest','c');

//実行
[U,dim,T]=schur(A,'mytest');
//ペンシルのSchur形式
//----------------------
F=[-1,%s, 0,   1;
    0,-1,5-%s, 0;
    0, 0,2+%s, 0;
    1, 0, 0, -2+%s];
A=coeff(F,0);E=coeff(F,1);
[As,Es,Q,Z]=schur(A,E);
Q'*F*Z //これはAs+%s*Esです


[As,Es,Z,dim] = schur(A,E,'c')
function t=mytest(Alpha,Beta),t=real(Alpha)<0,endfunction
[As,Es,Z,dim] = schur(A,E,mytest)

//Fortranの同じ関数 (コンパイラが必要)
ftn=['integer function mytestf(ar,ai,b)' //fortranコード
     'double precision ar,ai,b'
     'mytestf=0'
     'if(ar.lt.0.0d0) mytestf=1'
     'end']
mputl('      '+ftn,TMPDIR+'/mytestf.f')

//build and link
lp=ilib_for_link('mytestf','mytestf.f',[],'F');
link(lp,'mytestf','f');

//実行

[As,Es,Z,dim] = schur(A,E,'mytestf')
 ]]></programlisting>

    </refsection>

    <refsection role="see also">

        <title>参照</title>

        <simplelist type="inline">

            <member>

                <link linkend="spec">spec</link>

            </member>

            <member>

                <link linkend="bdiag">bdiag</link>

            </member>

            <member>

                <link linkend="ricc">ricc</link>

            </member>

            <member>

                <link linkend="pbig">pbig</link>

            </member>

            <member>

                <link linkend="psmall">psmall</link>

            </member>

        </simplelist>

    </refsection>

</refentry>

