<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA -
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2019 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * 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="en" xml:id="prbs_a">
    <refnamediv>
        <refname>prbs_a</refname>
        <refpurpose>Generates a pseudo random binary sequence</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            u = prbs_a(n, nc)
            u = prbs_a(n, nc, ids)
            u = prbs_a(n, nc, positions)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>n</term>
                <listitem>
                    positive integer: length of the sequence.
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nc</term>
                <listitem>
                    integer in [0, n-1]: number of commutations required.
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>positions</term>
                <listitem>
                    vector of integers in [0, n-1]: indices of required commutations in u.
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>u</term>
                <listitem>
                    Row vector of n values in {-1, 1}.
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>prbs_a()</literal> will be useful to simulate the behavior of a 2-state
            random system.
        </para>
        <para>
            <literal>u = prbs_a(n, nc)</literal> builds and returns a row vector
            <varname>u</varname> made of <varname>n</varname> values -1 or +1, in which
            <varname>nc</varname> commutations from -1 to 1 or from 1 to -1 occur at random
            positions in the vector.
        </para>
        <para>
            The initial state <literal>u(1)</literal> has an equiprobable value -1 or +1.
        </para>
        <para>
            The distribution of commutation positions along <varname>u</varname> is statistically
            uniform.
        </para>
        <note>
            The positions of commutations can be retrieved with
            <literal>find(u(2:$) &lt;> u(1:$-1))</literal>.
        </note>
        <para>
            <literal>prbs_a(n,,positions)</literal> does the same, but sets commutations at the
            given <varname>positions</varname>, instead of at random ones. <varname>nc</varname>
            is then ignored. Setting a commutation at a position = i ensures that
            <literal>u(i+1)</literal> will be <literal>-u(i)</literal>.
        </para>
        <para>
            The initial state can be imposed with a trivial post-processing of the result.
            For instance, imposing <literal>u(1)=-1</literal> will be done with
            <literal>if u(1)==1, u = -u; end</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
clf
u = prbs_a(20, 7)
subplot(1,2,1)
plot2d2(1:20, u, rect=[0,-1.2,20,1.2]);
find(u(2:$) <> u(1:$-1))

u = prbs_a(100, 20);
subplot(1,2,2)
plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
 ]]></programlisting>
    <screen><![CDATA[
--> u = prbs_a(20, 7)
 u  =
   1. -1. -1. -1. -1.  1. -1.  1.  1.  1. -1. -1. -1. -1.  1.  1.  1.  1. -1. -1.

--> find(u(2:$) <> u(1:$-1))
 ans  =
   1.   5.   6.   7.   10.   14.   18.
]]></screen>
        <scilab:image>
            u = prbs_a(20, 7)
            subplot(1,2,1)
            plot2d2(1:20, u, rect=[0,-1.2,20,1.2]);

            u = prbs_a(100, 20);
            subplot(1,2,2)
            plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);

            gcf().axes_size = [700 300];
        </scilab:image>
        <para/>
        <para>
            Example at given positions:
        </para>
        <programlisting role="example"><![CDATA[
clf
u = prbs_a(100, , [13 20 25 40 65 67 80 90 91]);
plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);
length(u)
find(u(2:$)<>u(1:$-1))
 ]]></programlisting>
    <screen><![CDATA[
--> length(u)
 ans =
  100

--> find(u(2:$)<>u(1:$-1))
 ans  =
   13.   20.   25.   40.   65.   67.   80.   90.   91.
]]></screen>
        <scilab:image>
            u = prbs_a(100, , [13 20 25 40 65 67 80 90 91]);
            plot2d2(1:100, u, rect=[0,-1.2,100,1.2]);

            gcf().axes_size = [400 300];
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="grand">grand</link>
            </member>
            <member>
                <link linkend="grand">grand</link>
            </member>
            <member>
                <link linkend="sprand">sprand</link>
            </member>
            <member>
                <link linkend="randpencil">randpencil</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    <listitem>
                        prbs_a() now strictly complies with nc.
                    </listitem>
                    <listitem>
                        The probability of the initial state u(1) is now unbiased: +1 and -1 are
                        strictly equiprobable.
                    </listitem>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
