* Bug #13810 fixed - householder(v, k*v) returned column of %nan. Input parameters...
[scilab.git] / scilab / modules / linear_algebra / help / fr_FR / 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 <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="fr" xml:id="householder">
17     <refnamediv>
18         <refname>householder</refname>
19         <refpurpose>Matrice de Householder  </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Séquence d'appel</title>
23         <synopsis>         householder         // demo</synopsis>
24         <synopsis> u     = householder(v [,w])</synopsis>
25         <synopsis>[u, H] = householder(v [,w])</synopsis>
26     </refsynopsisdiv>
27     <refsection role="arguments">
28         <title>Paramètres</title>
29         <variablelist>
30             <varlistentry>
31                 <term>v  </term>
32                 <listitem>
33                     <para>vecteur colonne réel ou complexe
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>w  </term>
39                 <listitem>
40                     <para>
41                         vecteur colonne réel ou complexe de même taille que <literal>v</literal>
42                         La valeur par défaut est <literal>eye(v)</literal> (axe (Ox)).
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>u  </term>
48                 <listitem>
49                     <para>
50                         vecteur unitaire résidant dans le plan <literal>(v,w)</literal> et orthogonal
51                         à la bissectrice de <literal>(v,w)</literal>.
52                         Colonne de nombres réels ou complexes, de taille size(v).
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>H</term>
58                 <listitem>
59                     <para>
60                         Matrice orthogonale de réflexion de Householder : <literal>H= eye() - 2*u*u'</literal>.
61                         <varname>H</varname> est telle que <literal>inv(H)==H</literal>,
62                         <literal>H'==H</literal>, et <literal>det(H)==-1</literal>.
63                     </para>
64                     <para>
65                         Si <varname>v</varname> et <varname>w</varname> sont des vecteurs réels,
66                         <literal>H*v</literal> est colinéaire à <varname>w</varname>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70         </variablelist>
71     </refsection>
72     <refsection>
73         <title role="description">Description</title>
74         <para>
75             <literal>householder(..)</literal> calcule le vecteur unitaire <varname>u</varname>
76             résidant dans le plan <literal>(v,w)</literal> et orthogonal à la bissectrice de
77             <literal>(v,w)</literal>.
78         </para>
79         <para>
80             Si <varname>v</varname> et <varname>w</varname> sont proportionels :
81             <itemizedlist>
82                 <listitem>
83                     S'ils sont opposés, <literal>u= v/|v|</literal> est retourné.
84                 </listitem>
85                 <listitem>
86                     S'ils sont à coordonnées réelles et sont dans la même direction,
87                     <varname>u</varname> est choisi dans le
88                     plan (xOy) avec a priori <literal>u(1)>0</literal>, et orthogonal à
89                     <varname>v</varname> (<literal>u'*v==0</literal>). Cependant,
90                     <itemizedlist>
91                         <listitem>
92                             S'ils sont selon (Ox), <literal>u = (Oy+)</literal> est retourné.
93                         </listitem>
94                         <listitem>
95                             S'ils sont scalaires (et de mêmes signes),
96                             le sous-espace orthogonal est réduit à <literal>{0}</literal> qui n'est
97                             pas normalisable :
98                             <varname>u</varname> et <varname>H</varname> sont mis à <literal>%nan</literal>.
99                         </listitem>
100                     </itemizedlist>
101                 </listitem>
102             </itemizedlist>
103         </para>
104         
105         <para>
106             Si la matrice de réflexion <varname>H</varname> correspondante est calculée,
107             pour tout point A de coordonnées <literal>a</literal> en colonne, <literal>H*a</literal>
108             sont les coordonnées de l'image de A réfléchie sur P.
109         </para>
110         <note>
111             Si <varname>v</varname> ou/et <varname>w</varname> sont des vecteurs ligne,
112             ils sont préalablement transposés en colonnes.
113         </note>
114         <warning>
115             Si <varname>v</varname> ou/et <varname>w</varname> sont <literal>[]</literal>,
116             <varname>u</varname> et <varname>H</varname> valent alors <literal>[]</literal>.
117         </warning>
118     </refsection>
119     <refsection role="examples">
120         <title>Exemples</title>
121         <programlisting role="example"><![CDATA[
122 a = [ rand(1,1) 0  0 ]';
123 [ra hm] = householder(a);
124 [a ra hm*a ]
125 norm(ra)
126
127 b = rand(3,1);
128 [rb, hm] = householder(b);
129 [b rb eye(b) clean(hm*b) ]
130 norm(rb)
131
132 [rb2b, hm] = householder(b, 2*b);
133 [b rb2b clean(hm*b ./ b) ]  // last column must be uniform
134 norm(rb2b)                  // must be 1
135
136 c = rand(3,1);
137 [rbc, hm] = householder(b,c);
138 norm(rbc)          // must be 1
139 hm*b ./c           // must be uniform
140
141 d = b + %i*c;
142 e = rand(3,1) + %i*rand(3,1);
143 [rde, hm] = householder(d,e);
144 norm(rbc)               // must be 1
145 clean(inv(hm) - hm)     // must be zeros(3,3)
146 clean(hm' - hm)         // must be zeros(3,3)
147 clean(det(hm))          // must be -1
148  ]]></programlisting>
149         
150         <para>APPLICATION : Image réfléchie d'un objet</para>
151         <programlisting role="example"><![CDATA[
152 // (OA) = [0 0 1] se réfléchit en O en (OB) = [ 1 1 0.3 ]:
153 [n, H] = householder([0 0 1]', [ 1 1 0.3 ]');
154 // "n" est la normale au plan réflecteur
155
156 // Objet source :
157 u = linspace(0,2*%pi,40);
158 v = linspace(0,2*%pi,20);
159 Xe = (cos(u).*u)'*(1+cos(v)/2)+10;
160 Ye = (u/2)'*sin(v);
161 Ze = (sin(u).*u)'*(1+cos(v)/2);
162
163 // Image réfléchie de l'object :
164 P = [ Xe(:)' ; Ye(:)' ; Ze(:)'];
165 Pr = H*P;
166 Xr = matrix(Pr(1,:),40,-1);
167 Yr = matrix(Pr(2,:),40,-1);
168 Zr = matrix(Pr(3,:),40,-1);
169
170 // Plan réflecteur contnant O : n(1).x + n(2).y + n(3).z = 0:
171 //  Grille d'espace :
172 x = linspace(min([Xe(:);Xr(:)]), max([Xe(:);Xr(:)]),20);
173 y = linspace(min([Ye(:);Yr(:)]), max([Ye(:);Yr(:)]),20);
174 [X, Y] = meshgrid(x,y);
175 //  Création du plan:
176 deff("z = mirror(x,y,n)","z = -n(1)/n(3)*x - n(2)/n(3)*y")
177 Zm = mirror(X,Y,n);
178
179 // Illustration graphique :
180 clf
181 drawlater
182 f = gcf();
183 f.color_map = [ 0.8 0.8 0.8 ; jetcolormap(100)];
184 surf(Xe,Ye,Ze)
185 surf(X,Y,Zm)
186 surf(Xr,Yr,Zr)
187 a = gca();
188 a.isoview = "on";
189 a.rotation_angles = [74 123];
190 a.children.color_flag = 0;
191 a.children.color_mode = 0;
192 a.children(1).foreground = color("red");
193 a.children(2).foreground = 1;
194 a.children(3).foreground = color("green");
195 drawnow
196  ]]></programlisting>
197         <scilab:image>
198             householder();
199         </scilab:image>
200     </refsection>
201     <refsection role="see also">
202         <title>Voir aussi</title>
203         <simplelist type="inline">
204             <member>
205                 <link linkend="qr">qr</link>
206             </member>
207             <member>
208                 <link linkend="givens">givens</link>
209             </member>
210         </simplelist>
211     </refsection>
212     <refsection role="history">
213         <title>Historique</title>
214         <revhistory>
215             <revision>
216                 <revnumber>6.0</revnumber>
217                 <revdescription>
218                     <para>Matrice de réflexion de Householder fournie en second paramètre de sortie.
219                         Demo householder() ajoutée. Page d'aide revue.
220                     </para>
221                 </revdescription>
222             </revision>
223         </revhistory>
224     </refsection>
225 </refentry>