From ff568b5e818d04048009926a7fa2ea537d2e656d Mon Sep 17 00:00:00 2001
From: Kenji Rikitake <kenji.rikitake@acm.org>
Date: Fri, 4 Nov 2016 14:53:10 +0900
Subject: Add jump functions to rand module

Jump functions returns the state after performing jump calculation to a
rand module internal state, which is equivalent to perform a large
number of calls of calculating new states for XorShift*/+ algorithms.
This commit add jump functions for exsplus and exs1024 algorithms, and a
wrapper function jump/1.  The wrapper function will cause error with
reason "not_implemented" if the jump function for the algorithm is not
implemented.

This commit adds following new functionalities:

  - Add new functions rand:jump/0 and rand:jump/1

  - Add the member jump to type alg_handler(), a fun for performing
    the jump function

  - Add jump functions for exsplus, equivalent to 2^64 calls

  - Add jump functions for exs1024, equivalent to 2^512 calls

  - Revise seed_put/1, seed/1, seed/2
    See <https://github.com/erlang/otp/pull/1235#discussion_r86950557>

  - Add dummy jump function for exs64 calling
    erlang:error(not_implemented)

  - Add jump function test cases as follows:

    * Add Common Test group reference_jump
    * Add tests for jump/0 to reference_jump_procdict/1
    * Rename tests for jump/1 to reference_jump_state/1
    * Rename gen_jump/1 to gen_jump_1/1
    * Add Common Tests reference_jump_procdict and reference_jump_state
      to the group reference_jump

  - Add jump function documentation

This commit also changes the Copyright year for Kenji Rikitake's code
from 2015 to 2015-2016.
---
 lib/stdlib/doc/src/rand.xml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'lib/stdlib/doc/src/rand.xml')

diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml
index 1dcc3de000..1364a3277b 100644
--- a/lib/stdlib/doc/src/rand.xml
+++ b/lib/stdlib/doc/src/rand.xml
@@ -41,6 +41,11 @@
       Sebastiano Vigna</url>. The normal distribution algorithm uses the
       <url href="http://www.jstatsoft.org/v05/i08">Ziggurat Method by Marsaglia
       and Tsang</url>.</p>
+    <p>For some algorithms, jump functions are provided for generating
+        non-overlapping sequences for parallel computations.
+        The jump functions perform calculations
+        equivalent to perform a large number of repeated calls
+        for calculating new states. </p>
 
     <p>The following algorithms are provided:</p>
 
@@ -48,14 +53,17 @@
       <tag><c>exsplus</c></tag>
       <item>
         <p>Xorshift116+, 58 bits precision and period of 2^116-1</p>
+        <p>Jump function: equivalent to 2^64 calls</p>
       </item>
       <tag><c>exs64</c></tag>
       <item>
         <p>Xorshift64*, 64 bits precision and a period of 2^64-1</p>
+        <p>Jump function: not available</p>
       </item>
       <tag><c>exs1024</c></tag>
       <item>
         <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p>
+        <p>Jump function: equivalent to 2^512 calls</p>
       </item>
     </taglist>
 
@@ -155,6 +163,33 @@ S0 = rand:seed_s(exsplus),
       </desc>
     </func>
 
+    <func>
+      <name name="jump" arity="0"/>
+      <fsummary>Return the seed after performing jump calculation
+          to the state in the process dictionary.</fsummary>
+      <desc><marker id="jump-0" />
+          <p>Returns the state
+              after performing jump calculation
+              to the state in the process dictionary.</p>
+      <p>This function generates a <c>not_implemented</c> error exception
+           when the jump function is not implemented for
+           the algorithm specified in the state
+           in the process dictionary.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="jump" arity="1"/>
+      <fsummary>Return the seed after performing jump calculation.</fsummary>
+      <desc><marker id="jump-1" />
+          <p>Returns the state after performing jump calculation
+              to the given state. </p>
+      <p>This function generates a <c>not_implemented</c> error exception
+           when the jump function is not implemented for
+           the algorithm specified in the state.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="normal" arity="0"/>
       <fsummary>Return a standard normal distributed random float.</fsummary>
-- 
cgit v1.2.3