propagate doc changes to 1.7

herbie-fp · Jun 10, 2022 · 6142850 · 6142850
1 parent 36197ba
commit 6142850
Show file tree

Hide file tree

Showing 23 changed files with 339 additions and 175 deletions.
diff --git a/www/doc/1.7/diagrams.html b/www/doc/1.7/diagrams.html
@@ -0,0 +1,34 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>Diagrams</title>
+  <link rel='stylesheet' type='text/css' href="../../main.css">
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <header>
+    <a href="../.."><img class="logo" src="../../logo.png" /></a>
+    <h1>Diagrams</h1>
+  </header>
+
+  <figure>
+    <img width="100%" src="system-1.6.png" alt="System diagram of Herbie" />
+  </figure>
+
+  <p>
+    High-level system diagram of Herbie. It highlights Herbie's core architecture,
+      external libraries, and user interactions.
+    Basic flow: Herbie passes user input (expression, precondition, etc.) to the
+      mainloop (scheduler) which alternates between generate and test phases multiple times,
+      maintaining and improving a set of accurate expressions at each iteration.
+    Once the generate-and-test phase is complete, Herbie extracts either
+      one or many output expressions using an algorithm called regime inference.
+    Regime inference chooses the "best" (usually most accurate)
+      generated candidate expression or combines multple candidates,
+      each "best" on a smaller part of the input range, with a branch condition.
+  </p>
+
+</body>
+</html>
diff --git a/www/doc/1.7/docker.html b/www/doc/1.7/docker.html
@@ -15,9 +15,9 @@ <h1>Installing with Docker</h1>
 
   <p>
     <a href="../../">Herbie</a> is available
-    through <a href="https://www.docker.com/">Docker</a>, which is a
+    through <a href="https://www.docker.com/">Docker</a>, which is
     sort of like a virtual machine. This page describes how to install
-    the <a href="https://hub.docker.com/uwplse/herbie">official Docker
+    the <a href="https://hub.docker.com/r/uwplse/herbie">official Docker
     image</a> for Herbie.
   </p>
 
@@ -33,34 +33,33 @@ <h2>Installing Herbie via Docker</h2>
     First, <a href="https://docs.docker.com/installation/">install
     Docker</a>. Docker supports Windows, macOS, and Linux. Depending
     on how you install Docker, you may need to prefix
-    the <code>docker</code> command with <code>sudo</code> or run them
+    the <code>docker</code> commands with <code>sudo</code> or run them
     as the administrative user.
   </p>
 
-  <p>With Docker installed, download the Herbie image:</p>
-
-  <pre class="shell">docker pull uwplse/herbie</pre>
-
-  <p>You can now run Herbie:</p>
+  <p>With Docker installed, you can run the <a href="using-cli.html">Herbie shell</a> with:</p>
 
   <pre>docker run -it uwplse/herbie shell</pre>
 
-  <p>This will run the <a href="using-cli.html">Herbie shell</a>,
-  reading input from the standard input.</p>
+  <p>This will read input from the standard input.</p>
 
   <p>Note that Herbie in Docker is more limited; for example, it will
   not recognize plugins installed outside the Docker container.</p>
 
-  <h2>Running the web shell</h2>
+  <h2>Running the web interface</h2>
 
-  <p>Running the web shell in Docker requires exposing the ports
-  inside the container. The Herbie Docker image binds to port 80 by
-  default; use the <code>-p &lt;hostport&gt;:80</code> option to
-  Docker to expose Herbie on whatever port you choose.
-  </p>
+  <p>
+    You can run the Herbie web server locally with
 
   <pre class="shell">docker run -it --rm -p 8000:80 uwplse/herbie</pre>
 
+    and access the server at <a href="http://localhost:8000">http://localhost:8000</a>.
+    </p>
+    <p>
+      (Herbie's Docker image binds to port 80 by
+    default; this command uses the <code>-p &lt;hostport&gt;:80</code> option to expose Herbie on port 8000.)
+  </p>
+
   <p>
     If you are using the <code>--log</code>
     or <code>--save-session</code> flags for the web shell,
@@ -107,5 +106,30 @@ <h2>Generating files and reports</h2>
     have the correct permissions set.
   </p>
 
+  <h2>For developers: updating the Docker image + Dockerfile</h2>
+
+  <p>
+    For building and testing, first clone the repo and confirm that Herbie builds correctly with <code>make install</code>.
+  </p>
+  <p>
+    Next, examine the Dockerfile and Makefile together. The Dockerfile should follow a process exactly like the Makefile, except a clean initial environment is assumed. The build may be split into 2 or more stages to limit the size of the resulting image. Each stage consists of a <code>FROM</code> command and a series of further commands to build up the desired environment, and later stages can refer to earlier stages by name--for example, <code>COPY --from=earlier-stage ...</code> can copy files compiled in earlier images. You may need to do things like bumping the version of Rust used for binary compilation or the version of Racket used in production, or adjusting paths to match the newest version of the repo.
+  </p>
+    <p>
+    Once you are ready to build:
+    <pre class="shell">docker build -t herbie-testbuild .</pre>
+    from the repo's main directory will build a new test image with the tag <code>herbie-testbuild</code>. You can run this image with
+    <pre class="shell">docker run -p 8000:80 -it herbie-testbuild</pre>
+    and see the web demo in the host machine's browser at <code>http://localhost:8000</code>.
+  </p>
+
+  <p>
+  To open a shell in a running container for testing, first get the container ID with
+  <pre class="shell">docker ps</pre>
+  and then open a shell in the container as root with
+  <pre class="shell">docker exec -it &lt;CONTAINER ID&gt; sh</pre>
+
+  The code and egg-herbie binaries should be under <code>/src</code>.
+  </p>
+
 </body>
 </html>
diff --git a/www/doc/1.7/egg-rr-seed-variance.png b/www/doc/1.7/egg-rr-seed-variance.png
diff --git a/www/doc/1.7/faq.html b/www/doc/1.7/faq.html
@@ -66,7 +66,7 @@ <h3 id="ground-truth">Could not determine a ground truth</h3>
 
   <p>
     Herbie raises this warning when some inputs require more than
-    10 000 bits to compute an exact ground truth. For example, to
+    10,000 bits to compute an exact ground truth. For example, to
     compute <code>(/ (exp x) (exp x))</code> for very
     large <code>x</code>, absurdly large exponents would be required.
     Herbie discards such inputs and raises this warning. If you see
@@ -93,7 +93,7 @@ <h3 id="deprecated-ops">Operator <var>op</var> is deprecated</h3>
     Consider creating a plugin to support them.
   </p>
 
-  <h3 id="value-to-string">Could uniquely print <var>val</var></h3>
+  <h3 id="value-to-string">Could not uniquely print <var>val</var></h3>
 
   <p>
     Herbie will raise this warning when it needs more than 10,000 bits
@@ -111,6 +111,19 @@ <h3 id="unsound-rules">Unsound rule application detected</h3>
     failed to simplify the output.
   </p>
 
+  <h3 id="unused-variable">Unused variable <var>var</var></h3>
+
+  <p>
+    The input FPCore contains a variable that is not
+      used in the body expression.
+  </p>
+
+  <h3 id="strange-variable">Strange variable <var>var</var></h3>
+
+  <p>
+    The input expression contains a variable that is similar in name
+      to named constants, e.g. <var>e</var> instead of <var>E</var>.
+  </p>
 
   <h2>Known bugs</h2>
 

diff --git a/www/doc/1.7/input.html b/www/doc/1.7/input.html
@@ -170,6 +170,9 @@ <h2 id="precisions">Precisions</h2>
     <dd>Single-precision IEEE-754 floating point</dd>
     <dt><code>binary64</code></dt>
     <dd>Double-precision IEEE-754 floating point</dd>
+    <dt><code>racket</code></dt>
+    <dd>Like <code>binary64</code>, but using Racket math functions
+      rather than your computer's <code>libm</code>.</dd>
   </dl>
 
   <p>By default, <code>binary64</code> is assumed. Herbie also has
@@ -187,7 +190,7 @@ <h2 id="conversions">Conversions</h2>
     <dt><code>:herbie-conversions<br/>([<var>prec1</var> <var>prec2</var>] ...)</code></dt>
     <dd>If an expression is computed with precision <code>prec1</code>,
     Herbie is allowed to rewrite all (or some) of the expression so it
-    is computed with precision <code>prec2</code>.</dd>
+    is computed with precision <code>prec2</code> and vice versa.</dd>
   </dl>
 
   <p>For example, to let Herbie introduce single-precision

diff --git a/www/doc/1.7/installing.html b/www/doc/1.7/installing.html
@@ -19,7 +19,8 @@ <h1>Installing Herbie</h1>
     <a href="../../">Herbie</a> supports Linux, macOS, and Windows. It
     can be installed from a package or from source. To start, install
     <a href="https://racket-lang.org">Racket</a>, which Herbie is
-    written in. (Herbie is also available as
+    written in. Install <a href="https://www.rust-lang.org/">Rust</a>
+    when building from source. (Herbie is also available as
     a <a href="docker.html">Docker image</a>.)
   </p>
 
@@ -45,13 +46,11 @@ <h2>Installing Herbie from source</h2>
   <p>
     Install Rust, using <a href="https://rustup.rs/">rustup</a> or via some other means.
     Versions as old as 1.60.0 are supported.
-    Also install Racket, version 8.0 or later, either using the the
-    <a href="http://download.racket-lang.org/racket-v8.5.html">official installer</a>
-    or distro-provided packages.
-    </p>
+    This installation method supports Windows, macOS, and Linux for various architectures.
+  </p>
 
-    <p>
-      Once Racket and Rust are installed, download the Herbie source
+  <p>
+    Once Racket and Rust are installed, download the Herbie source
     <a href="https://github.com/uwplse/herbie">from GitHub</a> with:
   </p>
 
@@ -75,7 +74,7 @@ <h2>Installing Herbie from source</h2>
   <ul>
     <li>On Windows, <code>AppData\Roaming\Racket\8.5\bin</code> in your user folder.</li>
     <li>On macOS, <code>Library/Racket/8.5/bin</code> in your home folder.</li>
-    <li>On Linux, <code>.racket/8.5/bin</code> in your home directory.</li>
+    <li>On Linux, <code>.local/share/racket/8.5/bin</code> in your home directory.</li>
   </ul>
 
   <p>
@@ -86,7 +85,11 @@ <h2>Installing Herbie from source</h2>
 
   <h2>Installing Herbie from a package</h2>
 
-  <p>Once Racket is installed, install Herbie from a package with:</p>
+  <p>
+    This installation method supports Windows, macOS, and Linux for x86-64.
+    This method of installation will fail for Apple M1 systems and other ARM architectures.
+    Once Racket is installed, install Herbie from a package with:
+  </p>
 
   <pre class="shell">raco pkg install --auto herbie</pre>  
 
@@ -95,13 +98,13 @@ <h2>Installing Herbie from a package</h2>
   <p>
     This command installs Herbie and its dependencies, compiles it for
     faster startup, and places the <code>herbie</code> executable in
-    your Racket user path:
+    your Racket user path (example paths for Racket 8.1):
   </p>
 
   <ul>
     <li>On Windows, <code>AppData\Roaming\Racket\8.5\bin</code> in your user folder.</li>
     <li>On macOS, <code>Library/Racket/8.5/bin</code> in your home folder.</li>
-    <li>On Linux, <code>.racket/8.5/bin</code> in your home directory.</li>
+    <li>On Linux, <code>.local/share/racket/8.5/bin</code> in your home directory.</li>
   </ul>
 
   <p>

diff --git a/www/doc/1.7/interactive-preconditions.png b/www/doc/1.7/interactive-preconditions.png
diff --git a/www/doc/1.7/old-rr-seed-variance.png b/www/doc/1.7/old-rr-seed-variance.png
diff --git a/www/doc/1.7/options.html b/www/doc/1.7/options.html
@@ -116,8 +116,8 @@ <h2>General options</h2>
     <dd>Enables multi-objective improvement. Herbie will attempt to simultaneously
     optimize for both accuracy and expression cost. Rather than generating
     a single "ideal" output expression, Herbie will generate many output expressions.
-    This mode is still considered experimental. This <em>will</em> take a long time to run.
-    We recommend timeouts measured in hours.</dd>
+    This mode is still considered experimental. With this option, Herbie will
+    take a <em>long</em> time to run. We recommend timeouts measured in hours.</dd>
   </dl>
 
   <h2>Web shell options</h2>
@@ -176,10 +176,6 @@ <h2>Rulesets</h2>
     <tr><td>numerics</td><td>Numerical compounds <code>expm1</code>, <code>log1p</code>, <code>fma</code>, and <code>hypot</code></td></tr>
   </table>
 
-  <p>All groups except <code>numerics</code> are enabled by default.
-  We recommend turning <code>numerics</code> on if these functions are
-  available in your language.</p>
-
   <h2>Search options</h2>
 
   <p>

diff --git a/www/doc/1.7/plugins.html b/www/doc/1.7/plugins.html
@@ -38,29 +38,52 @@ <h2>Posit arithmetic</h2>
   bit posits) are available, but are poorly supported.</p>
 
 
-  <h2 id="complex">Complex Numbers</h2>
+  <h2 id="complex">Complex numbers</h2>
 
-  <p>The <kbd>complex-herbie</kbd> plugin implements support for
-  complex numbers. Install it with:</p>
+  <p>The <kbd>complex-herbie</kbd> plugin has been removed as of Herbie 1.6.
+    This plugin may be brought back in the future.
 
-  <pre class="shell">raco pkg install --auto complex-herbie</pre>
+  <h2 id="complex">Generic floating-point numbers</h2>
 
-  <p>Herbie input parameters are always real numbers; complex
-  numbers must be constructed with <code>complex</code>. The
-  functions <code>re</code>, <code>im</code>, and <code>conj</code>
-  are available on complex numbers, along with the arithmetic
-  operators, <code>exp</code>, <code>log</code>, <code>pow</code>,
-  and <code>sqrt</code>. Complex and real operations use the same
-  syntax, but cannot be mixed: <code>(+ (complex 1 2) 1)</code> is not
-  valid. Herbie reports type errors in such situations.</p>
+  <p>The <kbd>float-herbie</kbd> plugin implements support for any IEEE-754
+    binary floating-point number. To install, check out the
+    <a href="https://github.com/bksaiki/float-herbie">source code</a>
+    and run
+  </p>
+
+  <pre class="shell">raco pkg install</pre>
+
+  <p>
+    at the top-level directory of the repository.
+    Once <kbd>float-herbie</kbd> is installed,
+    specify <code>:precision (float <i>ex</i> <i>nb</i>)</code>
+    to inform Herbie that it should assume the core's inputs and outputs are
+    floating-point numbers with <i>ex</i> exponent bits and <i>nb</i> total bits
+    (sign bit + mantissa bits + exponent bits).
+  </p>
 
-  <p>Complex operations are implemented by
-  <a href="https://docs.racket-lang.org/reference/numbers.html#%28tech._complex._number%29">Racket</a>,
-  so results may differ (slightly) from complex numbers in some other
-  language, especially for non-finite complex numbers. In the future,
-  we hope to support complex-number arguments and fully support all
-  complex-number operations.</p>
+  <h2 id="complex">Generic fixed-point numbers</h2>
 
+  <p>The <kbd>fixedpoint-herbie</kbd> plugin implements support for any fixed-point number.
+    To install, check out the
+    <a href="https://github.com/bksaiki/fixedpoint-herbie">source code</a>
+    and run
+  </p>
+
+  <pre class="shell">raco pkg install</pre>
+
+  <p>
+    at the top-level directory of the repository.
+    Once <kbd>fixedpoint-herbie</kbd> is installed,
+    specify <code>:precision (fixed <i>nb</i> <i>sc</i>)</code>
+    to inform Herbie that it should assume the core's inputs and outputs are
+    signed fixed-point numbers with <i>nb</i> total bits and a scaling factor of
+    2<sup><i>sc</i></sup> (integer formats have a scaling factor of 2<sup>0</sup>).
+    This plugin also supports unsigned fixed-point numbers specified by
+    <code>:precision (ufixed <i>nb</i> <i>sc</i>)</code> and provides
+    simpler aliases for integer formats with <code>:precision (integer <i>nb</i>)</code>
+    and <code>:precision (uinteger <i>nb</i>)</code>.
+  </p>
 
   <h2>Developing plugins</h2>
 
@@ -364,15 +387,13 @@ <h2>Developing plugins</h2>
     <dt>
       <code>
       <table>
-        <tr><td>(<b>register-representation!</b> </td><td> <i>name</i> <i>repr</i>)</td></tr>
+        <tr><td>(<b>register-representation-alias!</b> </td><td> <i>name</i> <i>repr</i>)</td></tr>
       </table>
       </code>
     </dt>
-    <dd>An alternate form of <code>register-representation!</code> used for representation aliasing.
+    <dd>Adds an alias <i>name</i> for an existing representation <i>repr</i>.
       If two representations are equivalent, e.g. <i>(float 8 32)</i> and <i>binary32</i>,
       this procedure can be used to declare the two representations equivalent.
-      The field <i>repr</i> is an existing representation object and <i>name</i>
-      is an alias that should be associated with it.
     </dd>
 
     <dt>

diff --git a/www/doc/1.7/quadp-old-branch.png b/www/doc/1.7/quadp-old-branch.png
diff --git a/www/doc/1.7/quadp-short-branch.png b/www/doc/1.7/quadp-short-branch.png
diff --git a/www/doc/1.7/range-input-2.png b/www/doc/1.7/range-input-2.png
diff --git a/www/doc/1.7/range-input.png b/www/doc/1.7/range-input.png