Using Herbie from the Command Line

Herbie rewrites floating point expressions to make them more accurate. The expressions could come from anywhere—your source code, mathematical papers, or even the output of Herbgrind, our tool for finding inaccurate expressions in binaries. This tutorial runs Herbie on the benchmark programs that Herbie ships with.

Herbie can be used from the command-line or from the browser. This page covers using Herbie from the command line.

Input expressions

Herbie ships a collection of benchmarks in its bench/ directory. For example, bench/tutorial.fpcore contains the following code:

(FPCore (x)
  :name "Cancel like terms"
  (- (+ 1 x) x))

(FPCore (x)
  :name "Expanding a square"
  (- (sqr (+ x 1)) 1))

(FPCore (x y z)
  :name "Commute and associate"
  (- (+ (+ x y) z) (+ x (+ y z))))

This code defines three floating point expressions that we want to run Herbie on:

You can check out our input format documentation for more about the Herbie input format.

The Herbie shell

The Herbie shell lets you interact with Herbie, typing in benchmark expressions and seeing the outputs. Run the Herbie shell:

herbie shell

After a few seconds, Herbie will start up and wait for input:

$ herbie shell
Herbie 1.2 with seed #(891614428 1933754021 544017565 2852994348 404070416 672462396)
Find help on , exit with Ctrl-D

The printed seed can be used to reproduce a Herbie run. You can now paste inputs directly into your terminal for Herbie to improve:

(FPCore (x) :name "Cancel like terms" (- (+ 1 x) x))
(FPCore (x) ... 1)

Interactive use is helpful if you want to play with different expressions and try multiple variants, informed by Herbie's advice. Note that Herbie will print a variety of additional information (like its error estimates and how long it took to process your input) in the ... portion of the output.

Batch processing FPCore

Alternatively, you can run Herbie on a file with multiple expressions in it, producing the output expressions to a file. This mode is intended for use by scripts.

$ herbie improve bench/tutorial.fpcore out.fpcore
Seed: 921081490
  1/3   [ 1563.552ms]	Cancel like terms	(29→ 0)
  2/3   [ 4839.121ms]	Expanding a square	(38→ 0)
  3/3   [ 3083.238ms]	Commute and associate	( 0→ 0)

The output file out.fpcore contains more accurate versions of each program:

;; seed: #(3123212801 2137904229 2993294009 3035080405 3708006222 26032508)

(FPCore (x) 1)
(FPCore (x) (* (+ 2 x) x))
(FPCore (x y z) 0)

Note that the order of expressions is identical. For more control over Herbie, see the documentation of Herbie's command-line options.