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:

(1 + x) - x, titled “Cancel like terms”
(x + 1)² - 1, titled “Expanding a square”
((x + y) + z) - (x + (y + z)), titled “Commute and associate”

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
Seed: #(3123212801 2137904229 2993294009 3035080405 3708006222 26032508)
herbie>

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.

Batch processing FPCore

Alternatively, you can run Herbie on a file with multiple expressions in it, producing the output expressions to a file:

$ herbie improve bench/tutorial.fpcore out.fpcore
Seed: #(3123212801 2137904229 2993294009 3035080405 3708006222 26032508)
  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.