<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="random-randomizer.getfloat" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Random\Randomizer::getFloat</refname>
  <refpurpose>Get a uniformly selected float</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="Random\\Randomizer">
   <modifier>public</modifier> <type>float</type><methodname>Random\Randomizer::getFloat</methodname>
   <methodparam><type>float</type><parameter>min</parameter></methodparam>
   <methodparam><type>float</type><parameter>max</parameter></methodparam>
   <methodparam choice="opt"><type>Random\IntervalBoundary</type><parameter>boundary</parameter><initializer>Random\IntervalBoundary::ClosedOpen</initializer></methodparam>
  </methodsynopsis>
  <para>
   Returns a uniformly selected, equidistributed float from a requested interval.
  </para>
  <para>
   Due to the limited precision, not all real numbers can be exactly represented as
   a floating point number.

   If a number cannot be represented exactly, it is rounded to the nearest
   representable exact value.

   Furthermore, floats are not equally dense across the whole number line.

   Because floats use a binary exponent, the distance between two neighboring
   floats doubles at each power of two.

   In other words: There are the same number of representable floats between
   <literal>1.0</literal> and <literal>2.0</literal>
   as they are between
   <literal>2.0</literal> and <literal>4.0</literal>,
   <literal>4.0</literal> and <literal>8.0</literal>,
   <literal>8.0</literal> and <literal>16.0</literal>,
   and so on.
  </para>
  <para>
   Randomly sampling an arbitrary number within the requested interval, for example
   by dividing two integers, might result in a biased distribution for this reason.

   The necessary rounding will cause some floats to be returned more often than
   others, especially around powers of two when the density of floats changes.
  </para>
  <para>
   <methodname>Random\Randomizer::getFloat</methodname> implements an algorithm that
   will return a uniformly selected float from the largest possible set of exactly
   representable and equidistributed floats within the requested interval.

   The distance between the selectable floats (“step size”) matches the distance
   between the floats with the lowest density, i.e. the distance between floats
   at interval boundary with the larger absolute value.

   This means that not all representable floats within a given interval may be
   returned if the interval crosses one or more powers of two.

   Stepping will start from the interval boundary with the larger absolute value
   to ensure the steps align with the exactly representable floats.
  </para>
  <para>
   Closed interval boundaries will always be included in the set of selectable
   floats.

   Thus, if the size of the interval is not an exact multiple of the step size and
   the boundary with the smaller absolute value is a closed boundary, the distance
   between that boundary and its nearest selectable float will be smaller than the
   step size.
  </para>
  <caution>
   <para>
    Post-processing the returned floats is likely going to break the uniform
    equidistribution, because the intermediate floats within a mathematical
    operation are experiencing implicit rounding.

    The requested interval should match the desired interval as closely as possible
    and rounding should only be performed as an explicit operation right before
    displaying the selected number to a user.
   </para>
  </caution>
  <refsect2>
   <title>Explanation of the Algorithm Using Example Values</title>
   <para>
    To give an example of how the algorithm works, consider a floating point
    representation that uses a 3-bit mantissa.

    This representation is capable of representing 8 different floating point
    values between consecutive powers of two.

    This means that between
    <literal>1.0</literal> and <literal>2.0</literal> all steps of size <literal>0.125</literal>
    are exactly representable and between <literal>2.0</literal> and <literal>4.0</literal>
    all steps of size <literal>0.25</literal> are exactly representable.

    In reality PHP’s floats use a 52-bit mantissa and can represent 2<superscript>52</superscript>
    different values between each power of two.

    This means that
    <simplelist><!-- This would benefit from type="inline" -->
     <member><literal>1.0</literal></member>
     <member><literal>1.125</literal></member>
     <member><literal>1.25</literal></member>
     <member><literal>1.375</literal></member>
     <member><literal>1.5</literal></member>
     <member><literal>1.625</literal></member>
     <member><literal>1.75</literal></member>
     <member><literal>1.875</literal></member>
     <member><literal>2.0</literal></member>
     <member><literal>2.25</literal></member>
     <member><literal>2.5</literal></member>
     <member><literal>2.75</literal></member>
     <member><literal>3.0</literal></member>
     <member><literal>3.25</literal></member>
     <member><literal>3.5</literal></member>
     <member><literal>3.75</literal></member>
     <member><literal>4.0</literal></member>
    </simplelist>
    are the exactly representable floats between <literal>1.0</literal>
    and <literal>4.0</literal>.
   </para>
   <para>
    Now consider that <code>$randomizer-&gt;getFloat(1.625, 2.5, IntervalBoundary::ClosedOpen)</code>
    is called, i.e. a random float starting at <literal>1.625</literal> until, but not including,
    <literal>2.5</literal> is requested.

    The algorithm first determines the step size at the boundary with the larger absolute
    value (<literal>2.5</literal>). The step size at that boundary is <literal>0.25</literal>.
   </para>
   <para>
    Note that the size of the requested interval is <literal>0.875</literal>, which is
    not an exact multiple of <literal>0.25</literal>.

    If the algorithm would start stepping at the lower bound <literal>1.625</literal>, it
    would encounter <literal>2.125</literal>, which is not exactly representable and would
    experience implicit rounding.

    Thus the algorithm starts stepping at the upper boundary <literal>2.5</literal>.

    The selectable values are:
    <simplelist>
     <member><literal>2.25</literal></member>
     <member><literal>2.0</literal></member>
     <member><literal>1.75</literal></member>
     <member><literal>1.625</literal></member>
    </simplelist>

    <literal>2.5</literal> is not included, because the upper boundary of the requested
    interval is an open boundary.

    <literal>1.625</literal> is included, even though its distance to the nearest value
    <literal>1.75</literal> is <literal>0.125</literal>, which is smaller than the
    previously determined step size of <literal>0.25</literal>.

    The reason for that is that the requested interval is closed at the lower boundary
    (<literal>1.625</literal>) and closed boundaries are always included.
   </para>
   <para>
    Finally the algorithm uniformly selects one of the four selectable values at random
    and returns it.
   </para>
   <refsect3 xml:id="random-randomizer.getfloat.affine-transformation">
    <title>Why Dividing Two Integers Does Not Work</title>
    <para>
     In the previous example, there are eight representable floating point numbers
     between each sub-interval delimited by a power of two.

     To give an example why dividing two integers would not work well to generate
     a random float, consider that there are 16 equidistributed floating point numbers
     in the right-open interval from <literal>0.0</literal> until, but not including,
     <literal>1.0</literal>. Half of them are the eight exactly representable values
     between <literal>0.5</literal> and <literal>1.0</literal>, the other half are the
     values between <literal>0.0</literal> and <literal>1.0</literal> that the step
     size of <literal>0.0625</literal>.

     These can easily be generated by dividing a random integer between <literal>0</literal>
     and <literal>15</literal> by <literal>16</literal> to obtain one of:

     <simplelist>
      <member><literal>0.0</literal></member>
      <member><literal>0.0625</literal></member>
      <member><literal>0.125</literal></member>
      <member><literal>0.1875</literal></member>
      <member><literal>0.25</literal></member>
      <member><literal>0.3125</literal></member>
      <member><literal>0.375</literal></member>
      <member><literal>0.4375</literal></member>
      <member><literal>0.5</literal></member>
      <member><literal>0.5625</literal></member>
      <member><literal>0.625</literal></member>
      <member><literal>0.6875</literal></member>
      <member><literal>0.75</literal></member>
      <member><literal>0.8125</literal></member>
      <member><literal>0.875</literal></member>
      <member><literal>0.9375</literal></member>
     </simplelist>
    </para>
    <para>
     This random float could be scaled to right-open interval from <literal>1.625</literal>
     until, but not including, <literal>2.75</literal> by multiplying it with the size
     of the interval (<literal>0.875</literal>) and adding the minimum <literal>1.625</literal>.
     This so-called affine transformation would result in the values:

     <simplelist>
      <member><literal>1.625</literal> rounded to <literal>1.625</literal></member>
      <member><literal>1.679</literal> rounded to <literal>1.625</literal></member>
      <member><literal>1.734</literal> rounded to <literal>1.75</literal></member>
      <member><literal>1.789</literal> rounded to <literal>1.75</literal></member>
      <member><literal>1.843</literal> rounded to <literal>1.875</literal></member>
      <member><literal>1.898</literal> rounded to <literal>1.875</literal></member>
      <member><literal>1.953</literal> rounded to <literal>2.0</literal></member>
      <member><literal>2.007</literal> rounded to <literal>2.0</literal></member>
      <member><literal>2.062</literal> rounded to <literal>2.0</literal></member>
      <member><literal>2.117</literal> rounded to <literal>2.0</literal></member>
      <member><literal>2.171</literal> rounded to <literal>2.25</literal></member>
      <member><literal>2.226</literal> rounded to <literal>2.25</literal></member>
      <member><literal>2.281</literal> rounded to <literal>2.25</literal></member>
      <member><literal>2.335</literal> rounded to <literal>2.25</literal></member>
      <member><literal>2.390</literal> rounded to <literal>2.5</literal></member>
      <member><literal>2.445</literal> rounded to <literal>2.5</literal></member>
     </simplelist>

     Note how the upper boundary of <literal>2.5</literal> would be returned, despite
     being an open boundary and thus being excluded.

     Also note how <literal>2.0</literal> and <literal>2.25</literal> are twice as
     likely to be returned compared to the other values.
    </para>
   </refsect3>
  </refsect2>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>min</parameter></term>
     <listitem>
      <para>
       The lower bound of the interval.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>max</parameter></term>
     <listitem>
      <para>
       The upper bound of the interval.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>boundary</parameter></term>
     <listitem>
      <para>
       Specifies whether the interval boundaries are possible return values.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   A uniformly selected, equidistributed float from the interval specified by <parameter>min</parameter>,
   <parameter>max</parameter>, and <parameter>boundary</parameter>.

   Whether <parameter>min</parameter> and <parameter>max</parameter> are possible return values depends
   on the value of <parameter>boundary</parameter>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <itemizedlist>
   <listitem>
    <simpara>
     If the value of <parameter>$min</parameter> is not finite (<function>is_finite</function>),
     a <classname>ValueError</classname> will be thrown.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     If the value of <parameter>$max</parameter> is not finite (<function>is_finite</function>),
     a <classname>ValueError</classname> will be thrown.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     If the requested interval does not contain any values,
     a <classname>ValueError</classname> will be thrown.
    </simpara>
   </listitem>
   &random.engineErrors;
  </itemizedlist>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><methodname>Random\Randomizer::getFloat</methodname> example</title>
   <programlisting role="php">
<![CDATA[
<?php
$randomizer = new \Random\Randomizer();

// Note that the latitude granularity is double the
// longitude’s granularity.
//
// For the latitude the value may be both -90 and 90.
// For the longitude the value may be 180, but not -180, because
// -180 and 180 refer to the same longitude.
printf(
    "Lat: %+.6f Lng: %+.6f",
    $randomizer->getFloat(-90, 90, \Random\IntervalBoundary::ClosedClosed),
    $randomizer->getFloat(-180, 180, \Random\IntervalBoundary::OpenClosed),
);
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Lat: +69.244304 Lng: -53.548951
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    This method implements the γ-section algorithm as published in
    <link xlink:href="&url.random.gamma-section;">
     Drawing Random Floating-Point Numbers from an Interval.
     Frédéric Goualard, ACM Trans. Model. Comput. Simul., 32:3, 2022
    </link>
    to obtain the desired behavioral properties.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><methodname>Random\Randomizer::nextFloat</methodname></member>
   <member><methodname>Random\Randomizer::getInt</methodname></member>
  </simplelist>
 </refsect1>

</refentry>
<!--Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
