householder documentation page was missing some improvements
[scilab.git] / scilab / modules / linear_algebra / help / ja_JP / factorization / householder.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2015 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  -->
16
17 <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="householder">
18     
19     <refnamediv>
20         <refname>householder</refname>
21         <refpurpose>ハウスホルダー直交鏡映行列</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>呼び出し手順</title>
25         <synopsis>
26             householder         // demo
27             u     = householder(v [,w])
28             [u, H] = householder(v [,w])
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection role="arguments">
32         <title>引数</title>
33         <variablelist>
34             <varlistentry>
35                 <term>v</term>
36                 <listitem>
37                     <para>実数または複素数の列ベクトル</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>w</term>
42                 <listitem>
43                     <para>
44                         <literal>v</literal>と同じ大きさの実数または複素数の列ベクトル.
45                         デフォルト値は<literal>eye(v)</literal>((Ox) axis).
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>u</term>
51                 <listitem>
52                     <para>
53                         unit vector lying in the <literal>(v,w)</literal> plane and orthogonal
54                         to the bisectrix of <literal>(v,w)</literal>.
55                         Column of size(v) of real or complex numbers.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>H</term>
61                 <listitem>
62                     <para>
63                         Orthogonal Householder reflexion matrix: <literal>H= eye() - 2*u*u'</literal>.
64                         <varname>H</varname> is such that <literal>inv(H)==H</literal>,
65                         <literal>H'==H</literal>, and <literal>det(H)==-1</literal>.
66                     </para>
67                     <para>
68                         If <varname>v</varname> and <varname>w</varname> are real,
69                         <literal>H*v</literal> is proportional to <varname>w</varname>.
70                     </para>
71                 </listitem>
72             </varlistentry>
73         </variablelist>
74     </refsection>
75     <refsection role="description">
76         <title>説明</title>
77         <para>
78             <literal>householder(..)</literal> computes the unit vector <varname>u</varname>
79             lying in the <literal>(v,w)</literal> plane and orthogonal to the bisectrix of
80             <literal>(v,w)</literal>.
81         </para>
82         <para>
83             If <varname>v</varname> and <varname>w</varname> are proportional:
84             <itemizedlist>
85                 <listitem>
86                     <para>
87                         If they are opposite, <literal>u= v/|v|</literal> is returned.
88                     </para>
89                 </listitem>
90                 <listitem>
91                     If they are real and have the same direction, <varname>u</varname> is set
92                     in the (xOy) plane with a priori <literal>u(1)>0</literal>, and orthogonal to
93                     <varname>v</varname> (<literal>u'*v==0</literal>). However,
94                     <itemizedlist>
95                         <listitem>
96                             If they are along (Ox), <literal>u = (Oy+)</literal> is returned instead.
97                         </listitem>
98                         <listitem>
99                             If <varname>v</varname> and <varname>w</varname> are scalars with same
100                             signs, the orthogonal sub-space is restricted to <literal>{0}</literal>
101                             that can't be normalized:
102                             <varname>u</varname> and <varname>H</varname> are then set to
103                             <literal>%nan</literal>.
104                         </listitem>
105                     </itemizedlist>
106                 </listitem>
107             </itemizedlist>
108         </para>
109         
110         <para>
111             If the related reflexion matrix <varname>H</varname> is computed, for any point A
112             of column coordinates <literal>a</literal>, <literal>H*a</literal> are the coordinates of
113             the reflected image of A (see the example below).
114         </para>
115         <note>
116             If <varname>v</varname> or/and <varname>w</varname> are in row, they are priorly
117             transposed into columns.
118         </note>
119         <warning>
120             If <varname>v</varname> or/and <varname>w</varname> are <literal>[]</literal>,
121             <literal>[]</literal> is returned for <varname>u</varname> and <varname>H</varname>.
122         </warning>
123     </refsection>
124     <refsection role="examples">
125         <title>例</title>
126         <programlisting role="example"><![CDATA[
127 a = [ rand(1,1) 0  0 ]';
128 [ra hm] = householder(a);
129 [a ra hm*a ]
130 norm(ra)
131
132 b = rand(3,1);
133 [rb, hm] = householder(b);
134 [b rb eye(b) clean(hm*b) ]
135 norm(rb)
136
137 [rb2b, hm] = householder(b, 2*b);
138 [b rb2b clean(hm*b ./ b) ]  // last column must be uniform
139 norm(rb2b)                  // must be 1
140
141 c = rand(3,1);
142 [rbc, hm] = householder(b,c);
143 norm(rbc)          // must be 1
144 hm*b ./c           // must be uniform
145
146 d = b + %i*c;
147 e = rand(3,1) + %i*rand(3,1);
148 [rde, hm] = householder(d,e);
149 norm(rbc)               // must be 1
150 clean(inv(hm) - hm)     // must be zeros(3,3)
151 clean(hm' - hm)         // must be zeros(3,3)
152 clean(det(hm))          // must be -1
153  ]]></programlisting>
154         
155         <para>
156             <emphasis role="bold">Application:</emphasis> Reflected image of an object w.r. to a given plane
157         </para>
158         <programlisting role="example"><![CDATA[
159 // (OA) = [0 0 1] is reflected in O into (OB) = [ 1 1 0.3 ]:
160 [n, H] = householder([0 0 1]', [ 1 1 0.3 ]');
161 // "n" is the unit vector orthogonal to the reflecting plane
162
163 // Emitting object (feature from shell demo):
164 u = linspace(0,2*%pi,40);
165 v = linspace(0,2*%pi,20);
166 Xe = (cos(u).*u)'*(1+cos(v)/2)+10;
167 Ye = (u/2)'*sin(v);
168 Ze = (sin(u).*u)'*(1+cos(v)/2);
169
170 // Reflected object:
171 Pe = [ Xe(:)' ; Ye(:)' ; Ze(:)'];
172 Pr = H*Pe;
173 Xr = matrix(Pr(1,:),40,-1);
174 Yr = matrix(Pr(2,:),40,-1);
175 Zr = matrix(Pr(3,:),40,-1);
176
177 // Reflecting plane containing O: n(1).x + n(2).y + n(3).z = 0
178 //   Sampling space:
179 x = linspace(min([Xe(:);Xr(:)]), max([Xe(:);Xr(:)]),20);
180 y = linspace(min([Ye(:);Yr(:)]), max([Ye(:);Yr(:)]),20);
181 [X, Y] = meshgrid(x,y);
182 //   Generating the mirror:
183 deff("z = mirror(x,y,n)","z = -n(1)/n(3)*x - n(2)/n(3)*y")
184 Zm = mirror(X,Y,n);
185
186 // Plotting:
187 clf
188 drawlater
189 f = gcf();
190 f.color_map = [ 0.8 0.8 0.8 ; jetcolormap(100)];
191 surf(Xe,Ye,Ze)
192 surf(X,Y,Zm)
193 surf(Xr,Yr,Zr)
194 a = gca();
195 a.isoview = "on";
196 a.rotation_angles = [74 123];
197 a.children.color_flag = 0;
198 a.children.color_mode = 0;
199 a.children(1).foreground = color("red");
200 a.children(2).foreground = 1;
201 a.children(3).foreground = color("green");
202 drawnow
203  ]]></programlisting>
204         <scilab:image>
205             householder();
206         </scilab:image>
207     </refsection>
208     
209     <refsection role="see also">
210         <title>参照</title>
211         <simplelist type="inline">
212             <member>
213                 <link linkend="qr">qr</link>
214             </member>
215             <member>
216                 <link linkend="givens">givens</link>
217             </member>
218         </simplelist>
219         
220     </refsection>
221     <refsection role="history">
222         <title>履歴</title>
223         <revhistory>
224             <revision>
225                 <revnumber>6.0</revnumber>
226                 <revdescription>
227                     <para>Householder reflexion matrix added as second output parameter.
228                         Demo householder() added. Help page reviewed.
229                     </para>
230                 </revdescription>
231             </revision>
232         </revhistory>
233     </refsection>
234 </refentry>