hg.stevelosh.com > docs.stevelosh.com

fdfd0925e959 

cl-pcg: Update site.
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Thu, 23 Mar 2017 13:56:10 +0000
parents c448037d3088
children ce8a7b89014e
branches/tags (none)
files cl-pcg/index.html cl-pcg/reference/index.html cl-pcg/usage/index.html

Changes

--- a/cl-pcg/index.html	Tue Mar 14 13:35:05 2017 +0000
+++ b/cl-pcg/index.html	Thu Mar 23 13:56:10 2017 +0000
@@ -15,7 +15,7 @@
 <p><code>cl-pcg</code> is a <a href="http://www.pcg-random.org/">permuted congruential generator</a> implementation in pure
 Common Lisp.</p>
 <ul>
-<li><strong>License:</strong> MIT/X11</li>
+<li><strong>License:</strong> MIT</li>
 <li><strong>Documentation:</strong> <a href="https://sjl.bitbucket.io/cl-pcg/">https://sjl.bitbucket.io/cl-pcg/</a></li>
 <li><strong>Mercurial:</strong> <a href="https://bitbucket.org/sjl/cl-pcg/">https://bitbucket.org/sjl/cl-pcg/</a></li>
 <li><strong>Git:</strong> <a href="https://github.com/sjl/cl-pcg/">https://github.com/sjl/cl-pcg/</a></li>
--- a/cl-pcg/reference/index.html	Tue Mar 14 13:35:05 2017 +0000
+++ b/cl-pcg/reference/index.html	Thu Mar 23 13:56:10 2017 +0000
@@ -19,9 +19,102 @@
 don't touch it.</p>
 <div class="toc">
 <ul>
-<li><a href="#package-pcg">Package PCG</a></li>
+<li><a href="#package-pcg">Package PCG</a><ul>
+<li><a href="#make-pcg-function">MAKE-PCG (function)</a></li>
+<li><a href="#make-pcg-function_1">MAKE-PCG% (function)</a></li>
+<li><a href="#pcg-struct">PCG (struct)</a></li>
+<li><a href="#pcg-advance-function">PCG-ADVANCE (function)</a></li>
+<li><a href="#pcg-advance-function_1">PCG-ADVANCE% (function)</a></li>
+<li><a href="#pcg-random-function">PCG-RANDOM (function)</a></li>
+<li><a href="#pcg-random-function_1">PCG-RANDOM% (function)</a></li>
+<li><a href="#pcg-random-bounded-function">PCG-RANDOM-BOUNDED% (function)</a></li>
+<li><a href="#pcg-random-float-function">PCG-RANDOM-FLOAT% (function)</a></li>
+<li><a href="#pcg-rewind-function">PCG-REWIND (function)</a></li>
+<li><a href="#pcg-rewind-function_1">PCG-REWIND% (function)</a></li>
+</ul>
+</li>
 </ul></div>
 <h2 id="package-pcg">Package <code>PCG</code></h2>
+<h3 id="make-pcg-function"><code>MAKE-PCG</code> (function)</h3>
+<div class="codehilite"><pre><span/>(MAKE-PCG &amp;KEY (SEED NIL) (STREAM-ID 0))
+</pre></div>
+
+
+<p>Create and return a new PCG.</p>
+<p>If <code>seed</code> is <code>nil</code>, a fresh random seed will be generated with the
+  implementation's <code>cl:random</code> function, as if by:</p>
+<div class="codehilite"><pre><span/>(random ... (make-random-state t))
+</pre></div>
+
+
+<h3 id="make-pcg-function_1"><code>MAKE-PCG%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(MAKE-PCG% SEED STREAM-ID)
+</pre></div>
+
+
+<p>Create and return a new <code>pcg</code> for the given <code>seed</code> and <code>stream-id</code>.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
+<h3 id="pcg-struct"><code>PCG</code> (struct)</h3>
+<p>Slots: <code>STATE</code>, <code>INCREMENT</code></p>
+<h3 id="pcg-advance-function"><code>PCG-ADVANCE</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-ADVANCE PCG STEPS)
+</pre></div>
+
+
+<p>Advance the state of <code>pcg</code> by <code>steps</code> steps.</p>
+<p>This function returns <code>nil</code> and is only useful for its side effects.</p>
+<h3 id="pcg-advance-function_1"><code>PCG-ADVANCE%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-ADVANCE% PCG STEPS)
+</pre></div>
+
+
+<p>Advance the state of <code>pcg</code> by <code>steps</code> steps.</p>
+<p>This function returns <code>nil</code> and is only useful for its side effects.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
+<h3 id="pcg-random-function"><code>PCG-RANDOM</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-RANDOM PCG BOUND &amp;OPTIONAL MAX INCLUSIVE?)
+</pre></div>
+
+
+<h3 id="pcg-random-function_1"><code>PCG-RANDOM%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-RANDOM% PCG)
+</pre></div>
+
+
+<p>Return a random <code>(unsigned-byte 32)</code>.</p>
+<p>As a side effect, the state of <code>pcg</code> will be advanced.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
+<h3 id="pcg-random-bounded-function"><code>PCG-RANDOM-BOUNDED%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-RANDOM-BOUNDED% PCG BOUND)
+</pre></div>
+
+
+<p>Return a random integer between <code>0</code> (inclusive) and <code>bound</code> (exclusive).</p>
+<p>As a side effect, the state of <code>pcg</code> will be advanced.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
+<h3 id="pcg-random-float-function"><code>PCG-RANDOM-FLOAT%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-RANDOM-FLOAT% PCG)
+</pre></div>
+
+
+<p>Return a random <code>single-float</code> between <code>0.0</code> and <code>1.0</code>.</p>
+<p>As a side effect, the state of <code>pcg</code> will be advanced.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
+<h3 id="pcg-rewind-function"><code>PCG-REWIND</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-REWIND PCG STEPS)
+</pre></div>
+
+
+<p>Rewind the state of <code>pcg</code> by <code>steps</code> steps.</p>
+<p>This function returns <code>nil</code> and is only useful for its side effects.</p>
+<h3 id="pcg-rewind-function_1"><code>PCG-REWIND%</code> (function)</h3>
+<div class="codehilite"><pre><span/>(PCG-REWIND% PCG STEPS)
+</pre></div>
+
+
+<p>Rewind the state of <code>pcg</code> by <code>steps</code> steps.</p>
+<p>This function returns <code>nil</code> and is only useful for its side effects.</p>
+<p>This is a low-level function that assumes you are passing in the correct types.</p>
                 </div>
             <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a> in Reykjavík, Iceland.</i></p>
 <script>
--- a/cl-pcg/usage/index.html	Tue Mar 14 13:35:05 2017 +0000
+++ b/cl-pcg/usage/index.html	Thu Mar 23 13:56:10 2017 +0000
@@ -12,9 +12,119 @@
         <div class="wrap">
             <header><h1><a href="..">cl-pcg</a></h1></header>
                 <div class="markdown">
-<h1 id="usage"><a href="">Usage</a></h1><p>cl-pcg is...</p>
+<h1 id="usage"><a href="">Usage</a></h1><p><code>cl-pcg</code> is a <a href="http://www.pcg-random.org/">permuted congruential generator</a> implementation in pure
+Common Lisp.  It provides a high-level API and a low-level API.</p>
 <div class="toc">
-<ul/></div>
+<ul>
+<li><a href="#the-high-level-api">The High-Level API</a><ul>
+<li><a href="#creating-a-generator">Creating a Generator</a></li>
+<li><a href="#generating-numbers">Generating Numbers</a></li>
+<li><a href="#the-global-generator">The Global Generator</a></li>
+<li><a href="#advancing-rewinding">Advancing &amp; Rewinding</a></li>
+</ul>
+</li>
+<li><a href="#the-low-level-api">The Low-Level API</a></li>
+<li><a href="#limitations">Limitations</a></li>
+</ul></div>
+<h2 id="the-high-level-api">The High-Level API</h2>
+<p>The high-level API is what you should start (and probably end) with.  It
+typechecks the arguments you pass in and offers a nice interface for generating
+random numbers.</p>
+<h3 id="creating-a-generator">Creating a Generator</h3>
+<p>To create a generator you can use the <code>make-pcg</code> function:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*gen*</span> <span class="p">(</span><span class="nv">make-pcg</span><span class="p">))</span>
+</pre></div>
+
+
+<p><code>make-pcg</code> takes two keyword parameters:</p>
+<ul>
+<li><code>:seed</code> should be an <code>(unsigned-byte 64)</code>.  If omitted a random seed will be
+  generated with the underlying implementation's <code>cl:random</code> function.</li>
+<li><code>:stream-id</code> should be an <code>(unsigned-byte 32)</code>.  The default is <code>0</code>.  Streams
+  provide a way to "split" a PCG into multiple generators — check out the PCG
+  site for more information on this.</li>
+</ul>
+<p>Once you've got a PCG object you can use it to generate some numbers.</p>
+<h3 id="generating-numbers">Generating Numbers</h3>
+<p>You can use the <code>pcg-random</code> function to generate random numbers:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*gen*</span> <span class="p">(</span><span class="nv">make-pcg</span><span class="p">))</span>
+
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">10</span><span class="p">)</span>
+<span class="c1">; =&gt; a random number from 0 (inclusive) to 10 (exclusive)</span>
+</pre></div>
+
+
+<p><code>pcg-random</code> is flexible and takes a number of optional arguments to help you
+generate the kinds of numbers you need.  Its lambda list looks like this:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">pcg</span> <span class="nv">bound</span> <span class="k">&amp;optional</span> <span class="nb">max</span> <span class="nv">inclusive?</span><span class="p">)</span>
+</pre></div>
+
+
+<p>If only <code>bound</code> is given, the function acts much like <code>cl:random</code>.</p>
+<p>If <code>max</code> is also given, a random number in <code>[bound, max)</code> is chosen.</p>
+<p>If <code>inclusive?</code> is also given, a random number in <code>[bound, max]</code> is chosen.</p>
+<p>For example:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*gen*</span> <span class="p">(</span><span class="nv">make-pcg</span><span class="p">))</span>
+
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">10</span><span class="p">)</span>      <span class="c1">; =&gt; [0, 10)</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">15</span> <span class="mi">28</span><span class="p">)</span>   <span class="c1">; =&gt; [15, 28)</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">15</span> <span class="mi">28</span> <span class="no">t</span><span class="p">)</span> <span class="c1">; =&gt; [15, 28] &lt;- inclusive endpoint!</span>
+</pre></div>
+
+
+<p><code>pcg-random</code> can also generate <code>single-float</code>s if <code>bound</code> and/or <code>max</code> are given
+as <code>single-float</code>s:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*gen*</span> <span class="p">(</span><span class="nv">make-pcg</span><span class="p">))</span>
+
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mf">10.0</span><span class="p">)</span>     <span class="c1">; =&gt; [0.0, 10.0]</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">0</span> <span class="mf">10.0</span><span class="p">)</span>   <span class="c1">; =&gt; [0.0, 10.0]</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mf">-1.0</span> <span class="mf">1.0</span><span class="p">)</span> <span class="c1">; =&gt; [-1.0, 1.0]</span>
+</pre></div>
+
+
+<h3 id="the-global-generator">The Global Generator</h3>
+<p>If you don't want to bother creating a fresh PCG object you can pass <code>t</code> to the
+high-level API to use a globally-defined one:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nv">pcg-random</span> <span class="no">t</span> <span class="mi">10</span><span class="p">)</span>
+</pre></div>
+
+
+<h3 id="advancing-rewinding">Advancing &amp; Rewinding</h3>
+<p>Sometimes it can be useful to advance or rewind a generator by a certain number
+of steps.  The <code>(pcg-advance pcg steps)</code> and <code>(pcg-rewind pcg steps)</code> can be
+used to do this:</p>
+<div class="codehilite"><pre><span/><span class="p">(</span><span class="nb">defparameter</span> <span class="vg">*gen*</span> <span class="p">(</span><span class="nv">make-pcg</span><span class="p">))</span>
+
+<span class="c1">;; Get three numbers</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 708</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 964</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 400</span>
+
+<span class="c1">;; Rewind three steps</span>
+<span class="p">(</span><span class="nv">pcg-rewind</span> <span class="vg">*gen*</span> <span class="mi">3</span><span class="p">)</span>
+
+<span class="c1">;; Get the same three numbers</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 708</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 964</span>
+<span class="p">(</span><span class="nv">pcg-random</span> <span class="vg">*gen*</span> <span class="mi">1000</span><span class="p">)</span> <span class="c1">; =&gt; 400</span>
+</pre></div>
+
+
+<p>These functions are <code>O(log₂(steps))</code> so they'll be fast even for ludicrously
+large values of <code>steps</code>.</p>
+<h2 id="the-low-level-api">The Low-Level API</h2>
+<p>The low-level API is what you want if you need raw speed.  It consists of all
+functions in the API whose names end in <code>%</code>, like <code>pcg-random%</code>.  All of these
+functions are <code>declaim</code>ed inline for easy embedding into hot loops.</p>
+<p>As an arbitrary example, the main function in this API (<code>pcg-random%</code>) is about
+100 bytes of machine code, so it's suitable for inlining when you really need
+performance.</p>
+<p>The low-level API assumes you will pass in arguments of the correct type.  If
+you fuck this up, all bets are off.  Read the code to figure out exactly what
+you need to pass in (or just use the high-level API like a sane person).</p>
+<h2 id="limitations">Limitations</h2>
+<p>You can only generate 32-bit integers, and only single floats.  This will change
+whenever I get around to fixing things up.</p>
                 </div>
             <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a> in Reykjavík, Iceland.</i></p>
 <script>