Skip to content

Commit 6142850

Browse files
bksaikibksaiki
committed
propagate doc changes to 1.7
1 parent 36197ba commit 6142850

23 files changed

+339
-175
lines changed

‎www/doc/1.7/diagrams.html‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!doctype html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8" />
5+
<title>Diagrams</title>
6+
<link rel='stylesheet' type='text/css' href="../../main.css">
7+
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
8+
<meta name="viewport" content="width=device-width, initial-scale=1" />
9+
</head>
10+
<body>
11+
<header>
12+
<a href="../.."><img class="logo" src="../../logo.png" /></a>
13+
<h1>Diagrams</h1>
14+
</header>
15+
16+
<figure>
17+
<img width="100%" src="system-1.6.png" alt="System diagram of Herbie" />
18+
</figure>
19+
20+
<p>
21+
High-level system diagram of Herbie. It highlights Herbie's core architecture,
22+
external libraries, and user interactions.
23+
Basic flow: Herbie passes user input (expression, precondition, etc.) to the
24+
mainloop (scheduler) which alternates between generate and test phases multiple times,
25+
maintaining and improving a set of accurate expressions at each iteration.
26+
Once the generate-and-test phase is complete, Herbie extracts either
27+
one or many output expressions using an algorithm called regime inference.
28+
Regime inference chooses the "best" (usually most accurate)
29+
generated candidate expression or combines multple candidates,
30+
each "best" on a smaller part of the input range, with a branch condition.
31+
</p>
32+
33+
</body>
34+
</html>

‎www/doc/1.7/docker.html‎

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ <h1>Installing with Docker</h1>
1515

1616
<p>
1717
<a href="../../">Herbie</a> is available
18-
through <a href="https://www.docker.com/">Docker</a>, which is a
18+
through <a href="https://www.docker.com/">Docker</a>, which is
1919
sort of like a virtual machine. This page describes how to install
20-
the <a href="https://hub.docker.com/uwplse/herbie">official Docker
20+
the <a href="https://hub.docker.com/r/uwplse/herbie">official Docker
2121
image</a> for Herbie.
2222
</p>
2323

@@ -33,34 +33,33 @@ <h2>Installing Herbie via Docker</h2>
3333
First, <a href="https://docs.docker.com/installation/">install
3434
Docker</a>. Docker supports Windows, macOS, and Linux. Depending
3535
on how you install Docker, you may need to prefix
36-
the <code>docker</code> command with <code>sudo</code> or run them
36+
the <code>docker</code> commands with <code>sudo</code> or run them
3737
as the administrative user.
3838
</p>
3939

40-
<p>With Docker installed, download the Herbie image:</p>
41-
42-
<pre class="shell">docker pull uwplse/herbie</pre>
43-
44-
<p>You can now run Herbie:</p>
40+
<p>With Docker installed, you can run the <a href="using-cli.html">Herbie shell</a> with:</p>
4541

4642
<pre>docker run -it uwplse/herbie shell</pre>
4743

48-
<p>This will run the <a href="using-cli.html">Herbie shell</a>,
49-
reading input from the standard input.</p>
44+
<p>This will read input from the standard input.</p>
5045

5146
<p>Note that Herbie in Docker is more limited; for example, it will
5247
not recognize plugins installed outside the Docker container.</p>
5348

54-
<h2>Running the web shell</h2>
49+
<h2>Running the web interface</h2>
5550

56-
<p>Running the web shell in Docker requires exposing the ports
57-
inside the container. The Herbie Docker image binds to port 80 by
58-
default; use the <code>-p &lt;hostport&gt;:80</code> option to
59-
Docker to expose Herbie on whatever port you choose.
60-
</p>
51+
<p>
52+
You can run the Herbie web server locally with
6153

6254
<pre class="shell">docker run -it --rm -p 8000:80 uwplse/herbie</pre>
6355

56+
and access the server at <a href="http://localhost:8000">http://localhost:8000</a>.
57+
</p>
58+
<p>
59+
(Herbie's Docker image binds to port 80 by
60+
default; this command uses the <code>-p &lt;hostport&gt;:80</code> option to expose Herbie on port 8000.)
61+
</p>
62+
6463
<p>
6564
If you are using the <code>--log</code>
6665
or <code>--save-session</code> flags for the web shell,
@@ -107,5 +106,30 @@ <h2>Generating files and reports</h2>
107106
have the correct permissions set.
108107
</p>
109108

109+
<h2>For developers: updating the Docker image + Dockerfile</h2>
110+
111+
<p>
112+
For building and testing, first clone the repo and confirm that Herbie builds correctly with <code>make install</code>.
113+
</p>
114+
<p>
115+
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.
116+
</p>
117+
<p>
118+
Once you are ready to build:
119+
<pre class="shell">docker build -t herbie-testbuild .</pre>
120+
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
121+
<pre class="shell">docker run -p 8000:80 -it herbie-testbuild</pre>
122+
and see the web demo in the host machine's browser at <code>http://localhost:8000</code>.
123+
</p>
124+
125+
<p>
126+
To open a shell in a running container for testing, first get the container ID with
127+
<pre class="shell">docker ps</pre>
128+
and then open a shell in the container as root with
129+
<pre class="shell">docker exec -it &lt;CONTAINER ID&gt; sh</pre>
130+
131+
The code and egg-herbie binaries should be under <code>/src</code>.
132+
</p>
133+
110134
</body>
111135
</html>

‎www/doc/1.7/egg-rr-seed-variance.png‎

762 KB
Loading

‎www/doc/1.7/faq.html‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ <h3 id="ground-truth">Could not determine a ground truth</h3>
6666

6767
<p>
6868
Herbie raises this warning when some inputs require more than
69-
10 000 bits to compute an exact ground truth. For example, to
69+
10,000 bits to compute an exact ground truth. For example, to
7070
compute <code>(/ (exp x) (exp x))</code> for very
7171
large <code>x</code>, absurdly large exponents would be required.
7272
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>
9393
Consider creating a plugin to support them.
9494
</p>
9595

96-
<h3 id="value-to-string">Could uniquely print <var>val</var></h3>
96+
<h3 id="value-to-string">Could not uniquely print <var>val</var></h3>
9797

9898
<p>
9999
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>
111111
failed to simplify the output.
112112
</p>
113113

114+
<h3 id="unused-variable">Unused variable <var>var</var></h3>
115+
116+
<p>
117+
The input FPCore contains a variable that is not
118+
used in the body expression.
119+
</p>
120+
121+
<h3 id="strange-variable">Strange variable <var>var</var></h3>
122+
123+
<p>
124+
The input expression contains a variable that is similar in name
125+
to named constants, e.g. <var>e</var> instead of <var>E</var>.
126+
</p>
114127

115128
<h2>Known bugs</h2>
116129

‎www/doc/1.7/input.html‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,9 @@ <h2 id="precisions">Precisions</h2>
170170
<dd>Single-precision IEEE-754 floating point</dd>
171171
<dt><code>binary64</code></dt>
172172
<dd>Double-precision IEEE-754 floating point</dd>
173+
<dt><code>racket</code></dt>
174+
<dd>Like <code>binary64</code>, but using Racket math functions
175+
rather than your computer's <code>libm</code>.</dd>
173176
</dl>
174177

175178
<p>By default, <code>binary64</code> is assumed. Herbie also has
@@ -187,7 +190,7 @@ <h2 id="conversions">Conversions</h2>
187190
<dt><code>:herbie-conversions<br/>([<var>prec1</var> <var>prec2</var>] ...)</code></dt>
188191
<dd>If an expression is computed with precision <code>prec1</code>,
189192
Herbie is allowed to rewrite all (or some) of the expression so it
190-
is computed with precision <code>prec2</code>.</dd>
193+
is computed with precision <code>prec2</code> and vice versa.</dd>
191194
</dl>
192195

193196
<p>For example, to let Herbie introduce single-precision

‎www/doc/1.7/installing.html‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ <h1>Installing Herbie</h1>
1919
<a href="../../">Herbie</a> supports Linux, macOS, and Windows. It
2020
can be installed from a package or from source. To start, install
2121
<a href="https://racket-lang.org">Racket</a>, which Herbie is
22-
written in. (Herbie is also available as
22+
written in. Install <a href="https://www.rust-lang.org/">Rust</a>
23+
when building from source. (Herbie is also available as
2324
a <a href="docker.html">Docker image</a>.)
2425
</p>
2526

@@ -45,13 +46,11 @@ <h2>Installing Herbie from source</h2>
4546
<p>
4647
Install Rust, using <a href="https://rustup.rs/">rustup</a> or via some other means.
4748
Versions as old as 1.60.0 are supported.
48-
Also install Racket, version 8.0 or later, either using the the
49-
<a href="http://download.racket-lang.org/racket-v8.5.html">official installer</a>
50-
or distro-provided packages.
51-
</p>
49+
This installation method supports Windows, macOS, and Linux for various architectures.
50+
</p>
5251

53-
<p>
54-
Once Racket and Rust are installed, download the Herbie source
52+
<p>
53+
Once Racket and Rust are installed, download the Herbie source
5554
<a href="https://github.com/uwplse/herbie">from GitHub</a> with:
5655
</p>
5756

@@ -75,7 +74,7 @@ <h2>Installing Herbie from source</h2>
7574
<ul>
7675
<li>On Windows, <code>AppData\Roaming\Racket\8.5\bin</code> in your user folder.</li>
7776
<li>On macOS, <code>Library/Racket/8.5/bin</code> in your home folder.</li>
78-
<li>On Linux, <code>.racket/8.5/bin</code> in your home directory.</li>
77+
<li>On Linux, <code>.local/share/racket/8.5/bin</code> in your home directory.</li>
7978
</ul>
8079

8180
<p>
@@ -86,7 +85,11 @@ <h2>Installing Herbie from source</h2>
8685

8786
<h2>Installing Herbie from a package</h2>
8887

89-
<p>Once Racket is installed, install Herbie from a package with:</p>
88+
<p>
89+
This installation method supports Windows, macOS, and Linux for x86-64.
90+
This method of installation will fail for Apple M1 systems and other ARM architectures.
91+
Once Racket is installed, install Herbie from a package with:
92+
</p>
9093

9194
<pre class="shell">raco pkg install --auto herbie</pre>
9295

@@ -95,13 +98,13 @@ <h2>Installing Herbie from a package</h2>
9598
<p>
9699
This command installs Herbie and its dependencies, compiles it for
97100
faster startup, and places the <code>herbie</code> executable in
98-
your Racket user path:
101+
your Racket user path (example paths for Racket 8.1):
99102
</p>
100103

101104
<ul>
102105
<li>On Windows, <code>AppData\Roaming\Racket\8.5\bin</code> in your user folder.</li>
103106
<li>On macOS, <code>Library/Racket/8.5/bin</code> in your home folder.</li>
104-
<li>On Linux, <code>.racket/8.5/bin</code> in your home directory.</li>
107+
<li>On Linux, <code>.local/share/racket/8.5/bin</code> in your home directory.</li>
105108
</ul>
106109

107110
<p>

‎www/doc/1.7/interactive-preconditions.png‎

20 KB
Loading

‎www/doc/1.7/old-rr-seed-variance.png‎

826 KB
Loading

‎www/doc/1.7/options.html‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,8 @@ <h2>General options</h2>
116116
<dd>Enables multi-objective improvement. Herbie will attempt to simultaneously
117117
optimize for both accuracy and expression cost. Rather than generating
118118
a single "ideal" output expression, Herbie will generate many output expressions.
119-
This mode is still considered experimental. This <em>will</em> take a long time to run.
120-
We recommend timeouts measured in hours.</dd>
119+
This mode is still considered experimental. With this option, Herbie will
120+
take a <em>long</em> time to run. We recommend timeouts measured in hours.</dd>
121121
</dl>
122122

123123
<h2>Web shell options</h2>
@@ -176,10 +176,6 @@ <h2>Rulesets</h2>
176176
<tr><td>numerics</td><td>Numerical compounds <code>expm1</code>, <code>log1p</code>, <code>fma</code>, and <code>hypot</code></td></tr>
177177
</table>
178178

179-
<p>All groups except <code>numerics</code> are enabled by default.
180-
We recommend turning <code>numerics</code> on if these functions are
181-
available in your language.</p>
182-
183179
<h2>Search options</h2>
184180

185181
<p>

‎www/doc/1.7/plugins.html‎

Lines changed: 43 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -38,29 +38,52 @@ <h2>Posit arithmetic</h2>
3838
bit posits) are available, but are poorly supported.</p>
3939

4040

41-
<h2 id="complex">Complex Numbers</h2>
41+
<h2 id="complex">Complex numbers</h2>
4242

43-
<p>The <kbd>complex-herbie</kbd> plugin implements support for
44-
complex numbers. Install it with:</p>
43+
<p>The <kbd>complex-herbie</kbd> plugin has been removed as of Herbie 1.6.
44+
This plugin may be brought back in the future.
4545

46-
<pre class="shell">raco pkg install --auto complex-herbie</pre>
46+
<h2 id="complex">Generic floating-point numbers</h2>
4747

48-
<p>Herbie input parameters are always real numbers; complex
49-
numbers must be constructed with <code>complex</code>. The
50-
functions <code>re</code>, <code>im</code>, and <code>conj</code>
51-
are available on complex numbers, along with the arithmetic
52-
operators, <code>exp</code>, <code>log</code>, <code>pow</code>,
53-
and <code>sqrt</code>. Complex and real operations use the same
54-
syntax, but cannot be mixed: <code>(+ (complex 1 2) 1)</code> is not
55-
valid. Herbie reports type errors in such situations.</p>
48+
<p>The <kbd>float-herbie</kbd> plugin implements support for any IEEE-754
49+
binary floating-point number. To install, check out the
50+
<a href="https://github.com/bksaiki/float-herbie">source code</a>
51+
and run
52+
</p>
53+
54+
<pre class="shell">raco pkg install</pre>
55+
56+
<p>
57+
at the top-level directory of the repository.
58+
Once <kbd>float-herbie</kbd> is installed,
59+
specify <code>:precision (float <i>ex</i> <i>nb</i>)</code>
60+
to inform Herbie that it should assume the core's inputs and outputs are
61+
floating-point numbers with <i>ex</i> exponent bits and <i>nb</i> total bits
62+
(sign bit + mantissa bits + exponent bits).
63+
</p>
5664

57-
<p>Complex operations are implemented by
58-
<a href="https://docs.racket-lang.org/reference/numbers.html#%28tech._complex._number%29">Racket</a>,
59-
so results may differ (slightly) from complex numbers in some other
60-
language, especially for non-finite complex numbers. In the future,
61-
we hope to support complex-number arguments and fully support all
62-
complex-number operations.</p>
65+
<h2 id="complex">Generic fixed-point numbers</h2>
6366

67+
<p>The <kbd>fixedpoint-herbie</kbd> plugin implements support for any fixed-point number.
68+
To install, check out the
69+
<a href="https://github.com/bksaiki/fixedpoint-herbie">source code</a>
70+
and run
71+
</p>
72+
73+
<pre class="shell">raco pkg install</pre>
74+
75+
<p>
76+
at the top-level directory of the repository.
77+
Once <kbd>fixedpoint-herbie</kbd> is installed,
78+
specify <code>:precision (fixed <i>nb</i> <i>sc</i>)</code>
79+
to inform Herbie that it should assume the core's inputs and outputs are
80+
signed fixed-point numbers with <i>nb</i> total bits and a scaling factor of
81+
2<sup><i>sc</i></sup> (integer formats have a scaling factor of 2<sup>0</sup>).
82+
This plugin also supports unsigned fixed-point numbers specified by
83+
<code>:precision (ufixed <i>nb</i> <i>sc</i>)</code> and provides
84+
simpler aliases for integer formats with <code>:precision (integer <i>nb</i>)</code>
85+
and <code>:precision (uinteger <i>nb</i>)</code>.
86+
</p>
6487

6588
<h2>Developing plugins</h2>
6689

@@ -364,15 +387,13 @@ <h2>Developing plugins</h2>
364387
<dt>
365388
<code>
366389
<table>
367-
<tr><td>(<b>register-representation!</b> </td><td> <i>name</i> <i>repr</i>)</td></tr>
390+
<tr><td>(<b>register-representation-alias!</b> </td><td> <i>name</i> <i>repr</i>)</td></tr>
368391
</table>
369392
</code>
370393
</dt>
371-
<dd>An alternate form of <code>register-representation!</code> used for representation aliasing.
394+
<dd>Adds an alias <i>name</i> for an existing representation <i>repr</i>.
372395
If two representations are equivalent, e.g. <i>(float 8 32)</i> and <i>binary32</i>,
373396
this procedure can be used to declare the two representations equivalent.
374-
The field <i>repr</i> is an existing representation object and <i>name</i>
375-
is an alias that should be associated with it.
376397
</dd>
377398

378399
<dt>

0 commit comments

Comments
 (0)