<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="rand">
  <refmeta>
    <refentrytitle>rand</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>rand</refname>
    <refpurpose>
      Generates a controlled random number series.
      <indexterm id="IndexRand"><primary>rand</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Output is a controlled random number series between -<emphasis>amp</emphasis> and +<emphasis>amp</emphasis>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>rand</command> xamp [, iseed] [, isel] [, ibase]</synopsis>

    <synopsis>kr <command>rand</command> xamp [, iseed] [, isel] [, ibase]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>iseed</emphasis> (optional, default=0.5) -- a seed value for the recursive pseudo-random formula. A value between 0 and 1 will produce an initial output of <emphasis>kamp * iseed</emphasis>. A value greater than 1 will be seeded from the system clock. A negative value will cause seed re-initialization to be skipped. The default seed value is .5.
    </para>

    <para>
      <emphasis>isel</emphasis> (optional, default=0) -- if zero, a 16-bit number is generated. If non-zero, a 31-bit random number is generated. Default is 0.
    </para>

    <para>
      <emphasis>ioffset</emphasis> (optional, default=0) -- a base value added to the random result. New in Csound version 4.03.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kamp, xamp</emphasis> -- range over which random numbers are distributed.
    </para>

    <para>
      <emphasis>kcps, xcps</emphasis> -- the frequency which new random numbers are generated.
    </para>

    <para>
      The internal pseudo-random formula produces values which are uniformly distributed over the range <emphasis>kamp</emphasis> to <emphasis>-kamp</emphasis>. <emphasis>rand</emphasis> will thus generate uniform white noise with an R.M.S value of <emphasis>kamp / root 2</emphasis>.
    </para>

    <para>
      The remaining units produce band-limited noise: the <emphasis>kcps</emphasis> and <emphasis>xcps</emphasis> parameters permit the user to specify that new random numbers are to be generated at a rate less than the sampling or control frequencies.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the rand opcode. It uses the files <ulink url="examples/rand.orc"><citetitle>rand.orc</citetitle></ulink> and <ulink url="examples/rand.sco"><citetitle>rand.sco</citetitle></ulink>.

      <example>
        <title>Example of the rand opcode.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/rand.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/rand.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="randh"><citetitle>randh</citetitle></link>,
      <link linkend="randi"><citetitle>randi</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Example written by &namekevin;.</para>
    <para>Thanks to a note from &namejohn;, I changed the names of the parameters.</para>
  </refsect1>
</refentry>
