Merge pull request #1326 from herbie-fp/cleanup-docs

Write documentation on adding a platform

Author: pavpanchekha

src/api/server.rkt

@@ -171,9 +171,7 @@
                          *reeval-pts*
                          *node-limit*
                          *max-find-range-depth*
-                         *pareto-mode*
                          *platform-name*
-                         *loose-plugins*
                          *functions*)
    (activate-platform! (*platform-name*))
    ; not sure if the above code is actaully needed.
@@ -292,9 +290,7 @@
                          *reeval-pts*
                          *node-limit*
                          *max-find-range-depth*
-                         *pareto-mode*
                          *platform-name*
-                         *loose-plugins*
                          *functions*)
    (activate-platform! (*platform-name*))
    (define worker-thread
@@ -506,7 +502,7 @@
                  `(:pre ,(prog->fpcore (test-pre test) (test-context test))))
            ,@(if (equal? (test-spec test) empty)
                  '()
-                 `(:herbie-spec ,(prog->fpcore (test-spec test) (test-context test))))
+                 `(:spec ,(prog->fpcore (test-spec test) (test-context test))))
            ,@(if (equal? (test-expected test) #t)
                  '()
                  `(:herbie-expected ,(test-expected test)))

src/config.rkt

@@ -28,16 +28,7 @@
         [localize . ()]
         [generate . (rr taylor proofs evaluate)]
         [reduce . (regimes binary-search branch-expressions)]
-        [rules
-         . (arithmetic polynomials
-                       fractions
-                       exponents
-                       trigonometry
-                       hyperbolic
-                       numerics
-                       special
-                       bools
-                       branches)]
+        [rules . (arithmetic polynomials fractions exponents trigonometry hyperbolic)]
         [dump . ()]))
 
 (define (flag-deprecated? category flag)
@@ -51,6 +42,10 @@
     [('reduce 'avg-error) #t]
     [('localize 'costs) #t]
     [('localize 'errors) #t]
+    [('rules 'numerics) #t]
+    [('rules 'special) #t]
+    [('rules 'bools) #t]
+    [('rules 'branches) #t]
     [(_ _) #f]))
 
 ; `hash-copy` returns a mutable hash, which makes `dict-update` invalid
@@ -111,6 +106,10 @@
      (eprintf "The localize:errors option has been removed.\n")
      (eprintf "  Herbie no longer performs localization.\n")
      (eprintf "See <herbie://herbie.uwplse.org/doc/~a/options.html> for more.\n" *herbie-version*)]
+    [('rules _)
+     (eprintf "The rules:~a ruleset has been removed.\n")
+     (eprintf "  These rules are no longer used by Herbie.\n")
+     (eprintf "See <herbie://herbie.uwplse.org/doc/~a/options.html> for more.\n" *herbie-version*)]
     [(_ _) (void)]))
 
 (define (changed-flags)
@@ -154,7 +153,6 @@
 (define *binary-search-accuracy* (make-parameter 48))
 
 ;; Pherbie related options
-(define *pareto-mode* (make-parameter #t))
 (define *pareto-pick-limit* (make-parameter 5))
 
 ;; If `:precision` is unspecified, which representation should we use?
@@ -163,9 +161,6 @@
 ;; The platform that Herbie will evaluate with.
 (define *platform-name* (make-parameter (if (equal? (system-type 'os) 'windows) "c-windows" "c")))
 
-;; Plugins loaded locally rather than through Racket.
-(define *loose-plugins* (make-parameter '()))
-
 ;; Sets the number of total points for Herbie to sample.
 (define *reeval-pts* (make-parameter 8000))
 

src/core/regimes.rkt

@@ -40,7 +40,6 @@
     (cond
       [(null? alts) '()]
       ; Only return one option if not pareto mode
-      [(and (not (*pareto-mode*)) (not (equal? alts sorted))) '()]
       [else
        (define-values (opt new-errs)
          (infer-splitpoints branch-exprs alts err-lsts #:errs errs ctx pcontext))

src/main.rkt

@@ -99,23 +99,12 @@
      during sampling. May fix \"Cannot sample enough valid points\" but will slow."
      (format "[Default: ~a iterations]" (*max-find-range-depth*)))
     (*max-find-range-depth* (string->number num))]
-   [("--no-pareto")
-    ("Disables Pareto-Herbie (Pherbie). Pareto-mode performs accuracy and expression cost
-     optimization and extracts multiple output expressions that are Pareto-optimal. Disabling
-     this feature forces Herbie to extract a single, most-accurate output expression."
-     "[Default: Pareto-Herbie enabled]")
-    (*pareto-mode* #f)]
    [("--profile") "Whether to profile each run (no-op, always on)" (void)]
-   #:multi [("--plugin")
-            path
-            ("Path to a Herbie plugin." "Allows for dynamic loading of \"loose\" plugins.")
-            (dynamic-require path #f)
-            (*loose-plugins* (cons path (*loose-plugins*)))]
-   [("-o" "--disable")
-    flag
-    ("Disable a search flag (formatted category:name)."
-     "See `+o/--enable` for the full list of search flags.")
-    (apply disable-flag! (string->flag flag))]
+   #:multi [("-o" "--disable")
+            flag
+            ("Disable a search flag (formatted category:name)."
+             "See `+o/--enable` for the full list of search flags.")
+            (apply disable-flag! (string->flag flag))]
    [("+o" "--enable")
     flag
     ("Enable a search flag (formatted category:name)."

src/reports/make-graph.rkt

@@ -92,14 +92,12 @@
                             (format-accuracy (apply max (map ulps->bits end-error)) repr #:unit "%")))
           ,(render-large "Time" (format-time time))
           ,(render-large "Alternatives" (~a (length end-exprs)))
-          ,(if (*pareto-mode*)
-               (render-large "Speedup"
-                             (if speedup
-                                 (~r speedup #:precision '(= 1))
-                                 "N/A")
-                             "×"
-                             #:title "Relative speed of fastest alternative that improves accuracy.")
-               ""))
+          ,(render-large "Speedup"
+                         (if speedup
+                             (~r speedup #:precision '(= 1))
+                             "N/A")
+                         "×"
+                         #:title "Relative speed of fastest alternative that improves accuracy."))
      ,(render-warnings warnings)
      ,(render-specification test)
      (figure ([id "graphs"])

www/doc.html

@@ -36,7 +36,8 @@ <h2>Documentation</h2>
     <li><a href="doc/latest/input.html">Input format</a>: what sorts of expressions Herbie supports.</li>
     <li><a href="doc/latest/options.html">Command-line flags</a>: modifying Herbie's behavior.</li>
     <li><a href="doc/latest/error.html">What is error?</a>: how Herbie measures floating-point error.</li>
-    <li><a href="doc/latest/faq.html">FAQ</a>: troubleshooting Herbie.</li>
+    <li><a href="doc/latest/faq.html">Warnings and Errors</a>: troubleshooting Herbie.</li>
+    <li><a href="doc/latest/platforms.html">Platforms</a>: how to write a new Herbie compilation target.</li>
     <li><a href="doc/latest/release-notes.html">Release Notes</a>: the biggest and latest changes to Herbie.</li>
   </ul>
 

www/doc/2.2/input.html

@@ -43,14 +43,11 @@ <h2 id="sec1">FPCore format</h2>
   mathematical expressions. FPCore looks like this:</p>
 
   <pre>(FPCore (<var>inputs ...</var>) <var>properties ...</var> <var>expression</var>)</pre>
-  <pre>(FPCore <var>name</var> (<var>inputs ...</var>) <var>properties ...</var> <var>expression</var>)</pre>
 
   <p>
     Each <var>input</var> is a variable name, like <code>x</code>,
     used in the <var>expression</var>. Properties are used to specify
     additional information about the <var>expression</var>'s context.
-    If <var>name</var> is specified, the function can be referenced in
-    subsequent FPCore declarations in the file.
   </p>
 
   <p>
@@ -63,17 +60,12 @@ <h2 id="sec1">FPCore format</h2>
 
   <p>
     The semicolon (<kbd>;</kbd>) character introduces a line comment.
-    We recommend the <code>.fpcore</code> file extension for Herbie input files.
+    We recommend the <code>.fpcore</code> file extension for FPCore files.
   </p>
 
   <h2>Supported functions</h2>
 
-  <p>
-    Herbie supports all functions
-    from <a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/math.h.html">math.h</a>
-    with floating-point-only inputs and outputs. The best supported
-    functions include:
-  </p>
+  <p>FPCore expressions can use any of the following functions:</p>
 
   <dl class="function-list">
     <dt><code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>fabs</code></dt>
@@ -95,13 +87,12 @@ <h2>Supported functions</h2>
   </dl>
 
   <p>Herbie also supports the constants <code>PI</code>
-  and <code>E</code>. Use <code>-</code> for both subtraction and negation.</p>
+  and <code>E</code>. Use <code>-</code> for both subtraction and
+  negation.</p>
 
-  <p>Herbie links against your computer's <code>libm</code> to
-  evaluate these functions. So, each function has the same behavior in
-  Herbie as in your code. You can instead use
-  the <a href="#precisions"><code>racket</code> precision</a> if you
-  instead want reproducible behavior.</p>
+  <p>However, how Herbie evaluates these functions, their cost, and
+  what additional functions are available depends on
+  the <a href="platforms.rkt">platform</a> you select.</p>
 
   <h2 id="conditionals">Conditionals</h2>
 
@@ -122,7 +113,7 @@ <h2 id="conditionals">Conditionals</h2>
     <dd>The two boolean values</dd>
   </dl>
 
-  <p>The comparison functions support chained comparisons with more than two arguments;
+  <p>The comparison operators support chained comparisons with more than two arguments;
     for example <code>(&lt; 1 x 10)</code> means <code>1 < x < 10</code>.</p>
 
   <h2 id="intermediates">Intermediate variables</h2>
@@ -157,8 +148,9 @@ <h2 id="intermediates">Intermediate variables</h2>
 
   <p>Internally, Herbie treats intermediate values only as a
   notational convenience, and inlines their values before improving
-  the formula's accuracy. Using intermediate variables will therefore
-  not produce a more accurate result or help Herbie run faster.</p>
+  the formula&apos;s accuracy. Using intermediate variables will
+  therefore not produce a more accurate result or help Herbie run
+  faster.</p>
 
   <h2 id="specs">Specifications</h2>
 
@@ -175,8 +167,9 @@ <h2 id="specs">Specifications</h2>
   :spec (sin (/ 1 x))
   (+ (/ 1 x) (/ 1 (* 6 (pow x 3)))))</pre>
 
-  <p>Herbie will only use the <code>:spec</code> expression to
-  evaluate error, not to search for accurate expressions.</p>
+  <p>Herbie will use the <code>:spec</code> expression to evaluate
+  error, but use body expression as a starting-point for finding
+  more accurate expressions.</p>
 
   <h2 id="preconditions">Preconditions</h2>
 
@@ -205,39 +198,25 @@ <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
-  a <a href="plugins.html">plugin system</a> to load additional
+  <p><a href="platforms.html">Platforms<a/> can also add additional
   precisions.</p>
 
-  <p>Herbie won't produce mixed-precision code unless you allow it to
-  do so, using the <code>:herbie-conversions</code> property:</p>
-
-  <dl class="function-list">
-    <dt><code>:herbie-conversions<br/>([<var>prec1</var> <var>prec2</var>] ...)</code></dt>
-    <dd>Expressions in precision <code>prec1</code>, can be rewriten
-    to use precision <code>prec2</code>, and vice versa.</dd>
-  </dl>
-
-  <p>All conversions are assumed to be bidirectional. For example, if
-  you specify <code>:herbie-conversions ([binary64 binary32])</code>,
-  Herbie will be able to add conversions between single- and
-  double-precision floating-point.</p>
-
   <h2 id="properties">Miscellaneous Input Properties</h2>
 
+  <p>A <var>name</var> can be provided before the argument list to
+  name an FPCore. That FPCore can then be called in other, later
+  FPCores.</p>
+
   <p>Herbie uses the <code>:name</code> property to name FPCores in
   its UI. Its value ought to be a string.</p>
 
   <p>Herbie allows <code>:alt</code> properties to specify additional
-  "developer targets"; these might be other alternatives you've tried
-  that you want to compare against.</p>
+  "developer targets"; these might be other alternatives you&apos;ve
+  tried that you want to compare against.</p>
 
-  <p>Herbie's benchmark suite also uses properties for continuous
+  <p>Herbie&apos;s benchmark suite also uses properties for continuous
   integration, but these are not officially supported and their use is
   discouraged.</p>