householder documentation page was missing some improvements
[scilab.git] / scilab / modules / linear_algebra / help / pt_BR / factorization / householder.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
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 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="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="householder" xml:lang="pt">
17     <refnamediv>
18         <refname>householder</refname>
19         <refpurpose>matriz de reflexão ortogonal de Householder</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Seqüência de Chamamento</title>
23         <synopsis>
24             householder         // demo
25             u     = householder(v [,w])
26             [u, H] = householder(v [,w])
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection role="arguments">
30         <title>Parâmetros</title>
31         <variablelist>
32             <varlistentry>
33                 <term>v</term>
34                 <listitem>
35                     <para>vetor coluna de reais ou complexos</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>w</term>
40                 <listitem>
41                     <para>vetor coluna de reais ou complexos com o mesmo tamanho que
42                         <varname>v</varname>. Valor padrão é <literal>eye(v)</literal> ((Ox) axis)
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>u</term>
48                 <listitem>
49                     <para>
50                         unit vector lying in the <literal>(v,w)</literal> plane and orthogonal
51                         to the bisectrix of <literal>(v,w)</literal>.
52                         Column of size(v) of real or complex numbers.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>H</term>
58                 <listitem>
59                     <para>
60                         Orthogonal Householder reflexion matrix: <literal>H= eye() - 2*u*u'</literal>.
61                         <varname>H</varname> is such that <literal>inv(H)==H</literal>,
62                         <literal>H'==H</literal>, and <literal>det(H)==-1</literal>.
63                     </para>
64                     <para>
65                         If <varname>v</varname> and <varname>w</varname> are real,
66                         <literal>H*v</literal> is proportional to <varname>w</varname>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70         </variablelist>
71     </refsection>
72     <refsection role="description">
73         <title>Descrição</title>
74         <para>
75             <literal>householder(..)</literal> computes the unit vector <varname>u</varname>
76             lying in the <literal>(v,w)</literal> plane and orthogonal to the bisectrix of
77             <literal>(v,w)</literal>.
78         </para>
79         <para>
80             If <varname>v</varname> and <varname>w</varname> are proportional:
81             <itemizedlist>
82                 <listitem>
83                     <para>
84                         If they are opposite, <literal>u= v/|v|</literal> is returned.
85                     </para>
86                 </listitem>
87                 <listitem>
88                     If they are real and have the same direction, <varname>u</varname> is set
89                     in the (xOy) plane with a priori <literal>u(1)>0</literal>, and orthogonal to
90                     <varname>v</varname> (<literal>u'*v==0</literal>). However,
91                     <itemizedlist>
92                         <listitem>
93                             If they are along (Ox), <literal>u = (Oy+)</literal> is returned instead.
94                         </listitem>
95                         <listitem>
96                             If <varname>v</varname> and <varname>w</varname> are scalars with same
97                             signs, the orthogonal sub-space is restricted to <literal>{0}</literal>
98                             that can't be normalized:
99                             <varname>u</varname> and <varname>H</varname> are then set to
100                             <literal>%nan</literal>.
101                         </listitem>
102                     </itemizedlist>
103                 </listitem>
104             </itemizedlist>
105         </para>
106         
107         <para>
108             If the related reflexion matrix <varname>H</varname> is computed, for any point A
109             of column coordinates <literal>a</literal>, <literal>H*a</literal> are the coordinates of
110             the reflected image of A (see the example below).
111         </para>
112         <note>
113             If <varname>v</varname> or/and <varname>w</varname> are in row, they are priorly
114             transposed into columns.
115         </note>
116         <warning>
117             If <varname>v</varname> or/and <varname>w</varname> are <literal>[]</literal>,
118             <literal>[]</literal> is returned for <varname>u</varname> and <varname>H</varname>.
119         </warning>
120     </refsection>
121     <refsection role="examples">
122         <title>Exemplos</title>
123         <programlisting role="example"><![CDATA[
124 a = [ rand(1,1) 0  0 ]';
125 [ra hm] = householder(a);
126 [a ra hm*a ]
127 norm(ra)
128
129 b = rand(3,1);
130 [rb, hm] = householder(b);
131 [b rb eye(b) clean(hm*b) ]
132 norm(rb)
133
134 [rb2b, hm] = householder(b, 2*b);
135 [b rb2b clean(hm*b ./ b) ]  // last column must be uniform
136 norm(rb2b)                  // must be 1
137
138 c = rand(3,1);
139 [rbc, hm] = householder(b,c);
140 norm(rbc)          // must be 1
141 hm*b ./c           // must be uniform
142
143 d = b + %i*c;
144 e = rand(3,1) + %i*rand(3,1);
145 [rde, hm] = householder(d,e);
146 norm(rbc)               // must be 1
147 clean(inv(hm) - hm)     // must be zeros(3,3)
148 clean(hm' - hm)         // must be zeros(3,3)
149 clean(det(hm))          // must be -1
150  ]]></programlisting>
151         
152         <para>
153             <emphasis role="bold">Application:</emphasis> Reflected image of an object w.r. to a given plane
154         </para>
155         <programlisting role="example"><![CDATA[
156 // (OA) = [0 0 1] is reflected in O into (OB) = [ 1 1 0.3 ]:
157 [n, H] = householder([0 0 1]', [ 1 1 0.3 ]');
158 // "n" is the unit vector orthogonal to the reflecting plane
159
160 // Emitting object (feature from shell demo):
161 u = linspace(0,2*%pi,40);
162 v = linspace(0,2*%pi,20);
163 Xe = (cos(u).*u)'*(1+cos(v)/2)+10;
164 Ye = (u/2)'*sin(v);
165 Ze = (sin(u).*u)'*(1+cos(v)/2);
166
167 // Reflected object:
168 Pe = [ Xe(:)' ; Ye(:)' ; Ze(:)'];
169 Pr = H*Pe;
170 Xr = matrix(Pr(1,:),40,-1);
171 Yr = matrix(Pr(2,:),40,-1);
172 Zr = matrix(Pr(3,:),40,-1);
173
174 // Reflecting plane containing O: n(1).x + n(2).y + n(3).z = 0
175 //   Sampling space:
176 x = linspace(min([Xe(:);Xr(:)]), max([Xe(:);Xr(:)]),20);
177 y = linspace(min([Ye(:);Yr(:)]), max([Ye(:);Yr(:)]),20);
178 [X, Y] = meshgrid(x,y);
179 //   Generating the mirror:
180 deff("z = mirror(x,y,n)","z = -n(1)/n(3)*x - n(2)/n(3)*y")
181 Zm = mirror(X,Y,n);
182
183 // Plotting:
184 clf
185 drawlater
186 f = gcf();
187 f.color_map = [ 0.8 0.8 0.8 ; jetcolormap(100)];
188 surf(Xe,Ye,Ze)
189 surf(X,Y,Zm)
190 surf(Xr,Yr,Zr)
191 a = gca();
192 a.isoview = "on";
193 a.rotation_angles = [74 123];
194 a.children.color_flag = 0;
195 a.children.color_mode = 0;
196 a.children(1).foreground = color("red");
197 a.children(2).foreground = 1;
198 a.children(3).foreground = color("green");
199 drawnow
200  ]]></programlisting>
201         <scilab:image>
202             householder();
203         </scilab:image>
204     </refsection>
205     <refsection role="see also">
206         <title>Ver Também</title>
207         <simplelist type="inline">
208             <member>
209                 <link linkend="qr">qr</link>
210             </member>
211             <member>
212                 <link linkend="givens">givens</link>
213             </member>
214         </simplelist>
215     </refsection>
216     <refsection role="history">
217         <title>Histórico</title>
218         <revhistory>
219             <revision>
220                 <revnumber>6.0</revnumber>
221                 <revdescription>
222                     <para>Householder reflexion matrix added as second output parameter.
223                         Demo householder() added. Help page reviewed.
224                     </para>
225                 </revdescription>
226             </revision>
227         </revhistory>
228     </refsection>
229 </refentry>