* Bugs 16090 16163 fixed: prbs_a(n,nc) infringed nc & slow. Page overhauled
[scilab.git] / scilab / modules / cacsd / help / en_US / prbs_a.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) INRIA -
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="prbs_a">
20     <refnamediv>
21         <refname>prbs_a</refname>
22         <refpurpose>Generates a pseudo random binary sequence</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             u = prbs_a(n, nc)
28             u = prbs_a(n, nc, ids)
29             u = prbs_a(n, nc, positions)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>n</term>
37                 <listitem>
38                     positive integer: length of the sequence.
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>nc</term>
43                 <listitem>
44                     integer in [0, n-1]: number of commutations required.
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>positions</term>
49                 <listitem>
50                     vector of integers in [0, n-1]: indices of required commutations in u.
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>u</term>
55                 <listitem>
56                     Row vector of n values in {-1, 1}.
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60     </refsection>
61     <refsection>
62         <title>Description</title>
63         <para>
64             <literal>prbs_a()</literal> will be usefull to simulate the behavior of a 2-state
65             random system.
66         </para>
67         <para>
68             <literal>u = prbs_a(n, nc)</literal> builds and returns a row vector
69             <varname>u</varname> made of <varname>n</varname> values -1 or +1, in which
70             <varname>nc</varname> commutations from -1 to 1 or from 1 to -1 occur at random
71             positions in the vector.
72         </para>
73         <para>
74             The initial state <literal>u(1)</literal> has an equiprobable value -1 or +1.
75         </para>
76         <para>
77             The distribution of commutations positions along <varname>u</varname> is statistically
78             uniform.
79         </para>
80         <note>
81             The positions of commutations can be retrieved with
82             <literal>find(u(2:$) &lt;> u(1:$-1))</literal>.
83         </note>
84         <para>
85             <literal>prbs_a(n,,positions)</literal> does the same, but sets commutations at the
86             given <varname>positions</varname>, instead of at random ones. <varname>nc</varname>
87             is then ignored. Setting a commutation at a position = i insures that
88             <literal>u(i+1)</literal> will be <literal>-u(i)</literal>.
89         </para>
90         <para>
91             The initial state can be imposed with a trivial post-processing of the result.
92             For instance, imposing <literal>u(1)=-1</literal> will be done with
93             <literal>if u(1)==1, u = -u; end</literal>.
94         </para>
95     </refsection>
96     <refsection>
97         <title>Examples</title>
98         <programlisting role="example"><![CDATA[
99 clf
100 u = prbs_a(20, 7)
101 subplot(1,2,1)
102 plot2d2(1:20, u, rect=[0,-1.2,20,1.2]);
103 find(u(2:$) <> u(1:$-1))
104
105 u = prbs_a(100, 20);
106 subplot(1,2,2)
107 plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
108  ]]></programlisting>
109     <screen><![CDATA[
110 --> u = prbs_a(20, 7)
111  u  =
112    1. -1. -1. -1. -1.  1. -1.  1.  1.  1. -1. -1. -1. -1.  1.  1.  1.  1. -1. -1.
113
114 --> find(u(2:$) <> u(1:$-1))
115  ans  =
116    1.   5.   6.   7.   10.   14.   18.
117 ]]></screen>
118         <scilab:image>
119             u = prbs_a(20, 7)
120             subplot(1,2,1)
121             plot2d2(1:20, u, rect=[0,-1.2,20,1.2]);
122
123             u = prbs_a(100, 20);
124             subplot(1,2,2)
125             plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
126
127             gcf().axes_size = [700 300];
128         </scilab:image>
129         <para/>
130         <para>
131             Example at given positions:
132         </para>
133         <programlisting role="example"><![CDATA[
134 clf
135 u = prbs_a(100, , [13 20 25 40 65 67 80 90 91]);
136 plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
137 length(u)
138 find(u(2:$)<>u(1:$-1))
139  ]]></programlisting>
140     <screen><![CDATA[
141 --> length(u)
142  ans =
143   100
144
145 --> find(u(2:$)<>u(1:$-1))
146  ans  =
147    13.   20.   25.   40.   65.   67.   80.   90.   91.
148 ]]></screen>
149         <scilab:image>
150             u = prbs_a(100, , [13 20 25 40 65 67 80 90 91]);
151             plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
152
153             gcf().axes_size = [400 300];
154         </scilab:image>
155     </refsection>
156     <refsection role="see also">
157         <title>See Also</title>
158         <simplelist type="inline">
159             <member>
160                 <link linkend="noisegen">noisegen</link>
161             </member>
162             <member>
163                 <link linkend="grand">grand</link>
164             </member>
165             <member>
166                 <link linkend="sprand">sprand</link>
167             </member>
168             <member>
169                 <link linkend="sysrand">sysrand</link>
170             </member>
171             <member>
172                 <link linkend="randpencil">randpencil</link>
173             </member>
174         </simplelist>
175     </refsection>
176     <refsection role="history">
177         <title>History</title>
178         <revhistory>
179             <revision>
180                 <revnumber>6.1.0</revnumber>
181                 <revdescription>
182                     <listitem>
183                         prbs_a() now strictly complies with nc.
184                     </listitem>
185                     <listitem>
186                         The probability of the initial state u(1) is now unbiased: +1 and -1 are
187                         strictly equiprobable.
188                     </listitem>
189                 </revdescription>
190             </revision>
191         </revhistory>
192     </refsection>
193 </refentry>