* Bug #13810 fixed - householder(v, k*v) returned column of %nan. Input parameters...
[scilab.git] / scilab / modules / linear_algebra / help / ja_JP / factorization / householder.xml
index 6f8a22e..94c17ed 100644 (file)
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
- * 
+ * Copyright (C) 2015 - Samuel GOUGEON
+ *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * 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="householder">
     
     <refnamediv>
-        
         <refname>householder</refname>
-        
         <refpurpose>ハウスホルダー直交鏡映行列</refpurpose>
-        
     </refnamediv>
-    
     <refsynopsisdiv>
-        
         <title>呼び出し手順</title>
-        
-        <synopsis>u=householder(v [,w])</synopsis>
-        
+        <synopsis>         householder         // demo</synopsis>
+        <synopsis> u     = householder(v [,w])</synopsis>
+        <synopsis>[u, H] = householder(v [,w])</synopsis>
     </refsynopsisdiv>
-    
-    <refsection>
-        
+    <refsection role="arguments">
         <title>引数</title>
-        
         <variablelist>
-            
             <varlistentry>
-                
                 <term>v</term>
-                
                 <listitem>
-                    
                     <para>実数または複素数の列ベクトル</para>
-                    
                 </listitem>
-                
             </varlistentry>
-            
             <varlistentry>
-                
                 <term>w</term>
-                
                 <listitem>
-                    
                     <para>
-                        
                         <literal>v</literal>と同じ大きさの実数または複素数の列ベクトル.
-                        
-                        デフォルト値は<literal>eye(v)</literal>
-                        
+                        デフォルト値は<literal>eye(v)</literal>((Ox) axis).
                     </para>
-                    
                 </listitem>
-                
             </varlistentry>
-            
             <varlistentry>
-                
                 <term>u</term>
-                
                 <listitem>
-                    
-                    <para>実数または複素数の列ベクトル</para>
-                    
+                    <para>
+                        unit vector lying in the <literal>(v,w)</literal> plane and orthogonal
+                        to the bisectrix of <literal>(v,w)</literal>.
+                        Column of size(v) of real or complex numbers.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>H</term>
+                <listitem>
+                    <para>
+                        Orthogonal Householder reflexion matrix: <literal>H= eye() - 2*u*u'</literal>.
+                        <varname>H</varname> is such that <literal>inv(H)==H</literal>,
+                        <literal>H'==H</literal>, and <literal>det(H)==-1</literal>.
+                    </para>
+                    <para>
+                        If <varname>v</varname> and <varname>w</varname> are real,
+                        <literal>H*v</literal> is proportional to <varname>w</varname>.
+                    </para>
                 </listitem>
-                
             </varlistentry>
-            
         </variablelist>
-        
     </refsection>
-    
-    <refsection>
-        
+    <refsection role="description">
         <title>説明</title>
-        
         <para>
-            
-            同じ大きさの列ベクトル
-            
-            <literal>v</literal>, <literal> w</literal> を指定すると, 
-            
-            <literal>householder(v,w)</literal> は,
-            
-            <literal> (eye()-2*u*u')*v</literal>が<literal>w</literal>に比例するような
-            
-            ユニタリ列ベクトル<literal>u</literal>を返します.
-            
-            <literal>(eye()-2*u*u')</literal> はハウスホルダー直交鏡映行列です.
-            
+            <literal>householder(..)</literal> computes the unit vector <varname>u</varname>
+            lying in the <literal>(v,w)</literal> plane and orthogonal to the bisectrix of
+            <literal>(v,w)</literal>.
         </para>
-        
         <para>
-            
-            <literal>w</literal> のデフォルト値は <literal> eye(v)</literal>です. 
-            
-            この場合,ベクトル<literal> (eye()-2*u*u')*v</literal> はベクトル 
-            
-            <literal> eye(v)*norm(v)</literal>です.
-            
+            If <varname>v</varname> and <varname>w</varname> are proportional:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        If they are opposite, <literal>u= v/|v|</literal> is returned.
+                    </para>
+                </listitem>
+                <listitem>
+                    If they are real and have the same direction, <varname>u</varname> is set
+                    in the (xOy) plane with a priori <literal>u(1)>0</literal>, and orthogonal to
+                    <varname>v</varname> (<literal>u'*v==0</literal>). However,
+                    <itemizedlist>
+                        <listitem>
+                            If they are along (Ox), <literal>u = (Oy+)</literal> is returned instead.
+                        </listitem>
+                        <listitem>
+                            If <varname>v</varname> and <varname>w</varname> are scalars with same
+                            signs, the orthogonal sub-space is restricted to <literal>{0}</literal>
+                            that can't be normalized:
+                            <varname>u</varname> and <varname>H</varname> are then set to
+                            <literal>%nan</literal>.
+                        </listitem>
+                    </itemizedlist>
+                </listitem>
+            </itemizedlist>
         </para>
         
+        <para>
+            If the related reflexion matrix <varname>H</varname> is computed, for any point A
+            of column coordinates <literal>a</literal>, <literal>H*a</literal> are the coordinates of
+            the reflected image of A on P.
+        </para>
+        <note>
+            If <varname>v</varname> or/and <varname>w</varname> are in row, they are priorly
+            transposed into columns.
+        </note>
+        <warning>
+            If <varname>v</varname> or/and <varname>w</varname> are <literal>[]</literal>,
+            <literal>[]</literal> is returned for <varname>u</varname> and <varname>H</varname>.
+        </warning>
+    </refsection>
+    <refsection role="examples">
+        <title>例</title>
+        <programlisting role="example"><![CDATA[
+a = [ rand(1,1) 0  0 ]';
+[ra hm] = householder(a);
+[a ra hm*a ]
+norm(ra)
+
+b = rand(3,1);
+[rb, hm] = householder(b);
+[b rb eye(b) clean(hm*b) ]
+norm(rb)
+
+[rb2b, hm] = householder(b, 2*b);
+[b rb2b clean(hm*b ./ b) ]  // last column must be uniform
+norm(rb2b)                  // must be 1
+
+c = rand(3,1);
+[rbc, hm] = householder(b,c);
+norm(rbc)          // must be 1
+hm*b ./c           // must be uniform
+
+d = b + %i*c;
+e = rand(3,1) + %i*rand(3,1);
+[rde, hm] = householder(d,e);
+norm(rbc)               // must be 1
+clean(inv(hm) - hm)     // must be zeros(3,3)
+clean(hm' - hm)         // must be zeros(3,3)
+clean(det(hm))          // must be -1
+ ]]></programlisting>
+        
+        <para>APPLICATION : Reflected image of an object</para>
+        <programlisting role="example"><![CDATA[
+// (OA) = [0 0 1] is reflected in O into (OB) = [ 1 1 0.3 ]:
+[n, H] = householder([0 0 1]', [ 1 1 0.3 ]');
+// "n" is the unit vector orthogonal to the reflecting plane
+
+// Emitting object (feature from shell demo):
+u = linspace(0,2*%pi,40);
+v = linspace(0,2*%pi,20);
+Xe = (cos(u).*u)'*(1+cos(v)/2)+10;
+Ye = (u/2)'*sin(v);
+Ze = (sin(u).*u)'*(1+cos(v)/2);
+
+// Reflected object:
+Pe = [ Xe(:)' ; Ye(:)' ; Ze(:)'];
+Pr = H*Pe;
+Xr = matrix(Pr(1,:),40,-1);
+Yr = matrix(Pr(2,:),40,-1);
+Zr = matrix(Pr(3,:),40,-1);
+
+// Reflecting plane containing O: n(1).x + n(2).y + n(3).z = 0
+//   Sampling space:
+x = linspace(min([Xe(:);Xr(:)]), max([Xe(:);Xr(:)]),20);
+y = linspace(min([Ye(:);Yr(:)]), max([Ye(:);Yr(:)]),20);
+[X, Y] = meshgrid(x,y);
+//   Generating the mirror:
+deff("z = mirror(x,y,n)","z = -n(1)/n(3)*x - n(2)/n(3)*y")
+Zm = mirror(X,Y,n);
+
+// Plotting:
+clf
+drawlater
+f = gcf();
+f.color_map = [ 0.8 0.8 0.8 ; jetcolormap(100)];
+surf(Xe,Ye,Ze)
+surf(X,Y,Zm)
+surf(Xr,Yr,Zr)
+a = gca();
+a.isoview = "on";
+a.rotation_angles = [74 123];
+a.children.color_flag = 0;
+a.children.color_mode = 0;
+a.children(1).foreground = color("red");
+a.children(2).foreground = 1;
+a.children(3).foreground = color("green");
+drawnow
+ ]]></programlisting>
+        <scilab:image>
+            householder();
+        </scilab:image>
     </refsection>
     
     <refsection role="see also">
-        
         <title>参照</title>
-        
         <simplelist type="inline">
-            
             <member>
-                
                 <link linkend="qr">qr</link>
-                
             </member>
-            
             <member>
-                
                 <link linkend="givens">givens</link>
-                
             </member>
-            
         </simplelist>
         
     </refsection>
+    <refsection role="history">
+        <title>履歴</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    <para>Householder reflexion matrix added as second output parameter.
+                        Demo householder() added. Help page reviewed.
+                    </para>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
     
 </refentry>
-