7055f457d2ebb71744b695164edaf506d7f56034
[scilab.git] / scilab / modules / sparse / help / ja_JP / matrixmanip / sprand.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) 2010 - DIGITEO - Michael Baudin
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="sprand" xml:lang="ja">
15     <refnamediv>
16         <refname>sprand</refname>
17         <refpurpose>ランダム疎行列</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>呼び出し手順</title>
21         <synopsis>sp=sprand(nrows,ncols,density [,typ])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>パラメータ</title>
25         <variablelist>
26             <varlistentry>
27                 <term>nrows</term>
28                 <listitem>
29                     <para>整数 (行数)</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>ncols</term>
34                 <listitem>
35                     <para>整数 (列数)</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>density</term>
40                 <listitem>
41                     <para>占有率 (密度)</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>typ</term>
46                 <listitem>
47                     <para>
48                         文字列, <literal>"uniform"</literal> (デフォルト) または
49                         <literal>"normal"</literal>
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>sp</term>
55                 <listitem>
56                     <para>疎行列</para>
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60     </refsection>
61     <refsection>
62         <title>説明</title>
63         <para>
64             <literal>sp=sprand(nrows,ncols,density)</literal> は,
65             <literal>nrows</literal> 行<literal>ncols</literal>列,
66             近似的に<literal>density*nrows*ncols</literal>個の非ゼロ
67             エントリを有する疎行列<literal>sp</literal>を返します.
68         </para>
69         <para>
70             <literal>density</literal>パラメータは
71             <literal>[0,1]</literal> の範囲で指定されます.
72             そうでない場合,
73             自動的にこの範囲に変換されます.
74             このため, 0 より小さいか 1より大きい density を使用しても,
75             エラーも警告も発生しません:
76             式<literal>density=max(min(density,1),0)</literal>が使用されます.
77         </para>
78         <para>
79             <literal>typ="uniform"</literal>の場合, 一様分布の
80             値 [0,1]が生成されます.
81             <literal>typ="normal"</literal> の場合,正規分布の
82             値が生成されます (平均=0 および標準偏差=1).
83         </para>
84         <para>
85             出力行列のエントリは指定された分布関数<literal>typ</literal>に
86             基づき計算されます.
87             非ゼロ要素のインデックスはランダムに計算され,
88             非ゼロの平均的な数は<literal>density</literal>となります.
89             実際のインデックスの値は,指数分布関数により計算されます.
90             ただし,分布関数のパラメータは同時に計算されます.
91         </para>
92         <para>
93             副作用として,<literal>rand</literal>および
94             <literal>grand</literal>ランダム数値生成器の状態はこの関数により修正されます.
95             非ゼロエントリのインデックスは指数分布関数およびgrand関数から計算されます.
96             行列の値はユーザーにより指定される分布関数(すなわち uniform または normal)
97             およびrand関数から計算されます.
98         </para>
99     </refsection>
100     <refsection>
101         <title>例</title>
102         <para>
103             以下の例では,近似的に密度0.001の
104             100x1000疎行列を生成します.
105             すなわち,およそ 100*1000*0.001=100個の非ゼロエントリとなります.
106         </para>
107         <programlisting role="example"><![CDATA[  
108 // 行列のエントリは一様分布となります.
109 W=sprand(100,1000,0.001);
110 // 行列のエントリは正規分布となります.
111 W=sprand(100,1000,0.001,"normal");
112  ]]></programlisting>
113         <para>
114             以下のスクリプトは,
115             行列のエントリが指定した分布を有することを確認します.
116             非ゼロエントリを取得するためにspget関数を用います.
117             次に,エントリの最小値,最大値,平均を計算し,
118             limit値と比較します.
119         </para>
120         <programlisting role="example"><![CDATA[  
121 typ = "normal"; 
122 // typ = "uniform";
123 nrows = 1000;
124 ncols = 2000;
125 density = 1/100;
126 s=sprand(nrows,ncols,density,typ);
127 nnzs=nnz(s);
128 [ij,v]=spget(s);
129 [%inf -%inf 0 %inf 1] // Limit values for "normal"
130 [nnzs min(v) mean(v) max(v) variance(v)]
131 [%inf 0 0.5 1 1/12] // Limit values for "uniform"
132  ]]></programlisting>
133         <para>
134             以下のスクリプトでは,ランダムに選択したエントリのインデックスを調べ,
135             正しい分布を有することを確認します.
136             一様分布の<literal>kmax</literal>ランダム疎行列を生成します.
137             ここで,各行列について,生成する非ゼロのエントリのインデックスについて
138             考えます.
139             すなわち, 
140             <literal>i=1,2,...,nrows</literal>
141             および <literal>j=1,2,...,ncols</literal>rとなる
142             各<literal>i</literal> および <literal>j</literal>について
143             イベント <literal>Aij = {エントリ (i,j) が非ゼロ}</literal>
144             が発生するかどうかを調べます.
145             行列<literal>C(i,j)</literal>はイベント<literal>Aij</literal>
146             が発生する回数を保存します.
147             行列 <literal>R(k)</literal> は,<literal>k=1,2,...,kmax</literal>
148             について試行回数<literal>k</literal>の実際の密度を保存します.
149         </para>
150         <programlisting role="example"><![CDATA[
151     kmax = 1000;
152     ncols=10;
153     nrows=15;
154     density=0.01;
155     typ="uniform";
156     C=zeros(nrows,ncols);
157     R=[];
158     for k=1:kmax
159       M=sprand(nrows,ncols,density,typ);
160       NZ=find(M<>0);
161       NZratio = size(NZ,"*")/(nrows*ncols);
162       R=[R NZratio];
163       C(NZ)=C(NZ)+1;
164     end
165  ]]></programlisting>
166         <para>
167             このアルゴリズムが実行される場合(時々必要となる可能性があります),
168             アルゴリズムが正しく実行されていることを確認するために
169             要素の統計値を計算することができます.
170         </para>
171         <programlisting role="no-scilab-exec"><![CDATA[
172   // A_ijの期待値は
173   density * kmax
174   // この値を実際のイベントと比較 :
175   C
176   // 平均値は期待値に近くなります.
177   [density*kmax mean(C)]
178   // 密度は密度の期待値に近くなります
179   [density mean(R)]
180   ]]></programlisting>
181     </refsection>
182     <refsection role="see also">
183         <title>参照</title>
184         <simplelist type="inline">
185             <member>
186                 <link linkend="sparse">sparse</link>
187             </member>
188             <member>
189                 <link linkend="full">full</link>
190             </member>
191             <member>
192                 <link linkend="rand">rand</link>
193             </member>
194             <member>
195                 <link linkend="speye">speye</link>
196             </member>
197         </simplelist>
198     </refsection>
199 </refentry>