herbie command has several
subcommands and allows multiple options that influence its search
procedure and the types of solutions it finds. These options apply
both to the report generator and the one-off command-line tool.
Herbie can be run both interactively and in batch mode, and can
generate output intended either for the command line or the web. We
call these different ways of running Herbie different tools. Herbie
provides four tools:
- Use Herbie through your browser.
starts a web server for running Herbie on your local machine, and
directs a browser to visit that server.
- Starts a command-line interactive shell for using Herbie.
Enter an FPCore expression and Herbie
will print its more-accurate version.
herbie improve input output
- Runs Herbie on the expressions in the
or directory, and outputs the result to
will be a single file of FPCore outputs.
herbie report input output
- Runs Herbie on the expressions in the
or directory, and produces a directory of HTML web pages that
describe Herbie's output, how it derived that output, and
additional charts and information about the improvement process.
These pages can be viewed in any browser (though with
a quirk for Chrome).
We recommend using the web tools,
report, since HTML allows Herbie to give you more
information about how and why it improved a floating-point
expression's accuracy. Particularly useful are the graphs it
produces of error versus input, which can help you understand
whether Herbie's improvements matter for your user cases.
For any tool, you can run
herbie tool --help
to see a listing of all available command-line options. This listing
will include unsupported options not listed on this page.
These options can be set on any tool. Pass them after the tool
name but before other arguments, such as:
herbie improve --timeout 60 in.fpcore out.fpcore
Arguments cannot be put anywhere else.
- The random seed, which changes the randomly-selected points
that Herbie evaluates candidate expressions on. The seed is a
number between 0 and 231 (exclusive both ends). This
option can be used to make Herbie's results reproducible or to
compare two different runs. Prior versions of Herbie used a
different format for seeds, which is also still supported.
- The number of improvements Herbie attempts to make to the
program. The default, 4, suffices for most programs and helps
keep Herbie fast. If this is set very high, Herbie may run out
of things to do and terminate before the given number of
iterations, but in practice iterations beyond the first few
rarely lead to lower error. This option can be increased to 5 or
higher to check that there aren't further improvements that Herbie
could seek out.
- The number of randomly-selected points used to evaluate
candidate expressions. The default, 256, gives good behavior for
most programs. The more points sampled, the slower Herbie is.
This option can be increased to 512 or 1024 if Herbie gives very
inconsistent results between runs with different seeds.
- The timeout to use per-example, in seconds. A fractional
number of seconds can be given.
--threads N, for
- Enables multi-threaded operation. By default, no threads are
used. A number can be passed to this option to use that many
yes can be passed to tell Herbie to use
all but one of the hardware threads.
Web shell options
web tool runs Herbie as a web server, and
connects to it from your browser. It has additional options to
control this server.
- The port to run the Herbie server on. The default port is 8000.
- Save all the reports for expressions enterred into the web
shell to this directory. The directory is also used as a
cache of already-computed expressions.
- Write a web access log to this file. The file is formatted
similarly to Apache logs. If Herbie crashes for some reason, this
log will not contain a traceback.
- When set, a browser is not started to point to the server main
page, and a smaller banner is printed to the command line.
Herbie uses a set of rewrite rules to define the changes it is
allowed to make to formulas to improve their accuracy. These rules
can be turned on and off in groups using
rules:group. In general, enabling more rules
should only improve the accuracy of Herbie's output. However, if
certain functions are not available on your platform, disabling
the rules associated with those functions will prevent Herbie from
The full list of rule groups is:
|Rule Group||Topic of rewrite rules|
|arithmetic||Basic arithmetic facts|
|polynomials||Factoring and powers|
|hyperbolic||Hyperbolic trigonometric identities|
|special||Special mathematical functions|
|complex||Complex number arithmetic|
|numerics||Special numerical functions |
All groups except
numerics are enabled by default,
and we recommend turning it on if these functions are available in
your language. If complex arithmetic or special mathematical
functions are poorly implemented in your language, you may wish to
disable those rule groups as well.
These options influence the fine properties of Herbie's search, most
importantly the types of transformations that Herbie uses to find
candidate programs. These options offer very fine-grained control
over Herbie's output, and are only recommended for advanced uses of
Each option can be turned off with the
--disable X command-line flag, and turned on with
+o X or
--enable X. The defaults are
the recommended options; turning a default-on option off typically
results in less-accurate results, while turning a default-off
option on typically results in more-complex and more-surprising
- This option, on by default, tells Herbie to treat its input as
double-precision calculations. If turned off, Herbie treats its
input as a single-precision calculation.
- This option, on by default, tells Herbie to use fallback
functions if a native implementation is not found for any
operations. If turned off, operations with no native
implementation will be disabled from use in the input or output.
You will want to turn this option off if you are concerned with
the specific behavior of libm functions.
- This option, on by default, simplifies the expression before
passing it to Herbie. If turned off, Herbie will not simplify
input programs before improving them. You will want to turn off
this option if simplifying the program will create a lot of
error, say if the association of operations is cleverly
- This option, off by default, causes Herbie to exit without
modifying the input program if it determines that the input
program has less than 0.1 bits of error. You will want to turn
this option on if you are running Herbie on a large corpus of
programs that you do not believe to be inaccurate.
- This option, on by default, uses Herbie's recursive rewriting
algorithm to generate candidate programs. If turned off, Herbie
will use a non-recursive rewriting algorithm, which will
substantially limit the candidates Herbie finds. You will rarely
want to turn this option off.
- This option, on by default, uses series expansion to produce
new candidates during the main improvement loop. If turned off,
Herbie will not use series expansion in the main improvement loop.
You will want to turn this option off if you want to avoid
series-expansion-based rewrites, such as if you need to preserve
the equivalence of the input and output expressions as real-number
- This option, on by default, simplifies candidates during the
main improvement loop. If turned off, candidates will not be
simplified, which typically results in much less accurate
expressions, since simplification is often necessary for
cancelling terms. You will rarely want to turn this option off.
- This option, on by default, uses Herbie's regime inference
algorithm to branch between several program candidates. If
turned off, branches will not be inferred and the output program
will be straight-line code (if the input was). You will want to
turn this option off if your programming environment makes
branches very expensive, such as in some cases of GPU
- This option, on by default, uses a final simplification pass
after all improvements have been made. This sometimes improves
accuracy further. If turned off, this final simplification pass
will not be done. You will rarely want to turn this option
- This option, on by default, causes Herbie to output the
candidate with the best average error over the chosen inputs. If
turned off, Herbie will choose the candidate with the least
maximum error instead. This usually produces programs with worse
overall accuracy. You may want to turn this option off if
worst-case accuracy is more important to you than overall
- This option, on by default, uses binary search to refine the
values used in
if statement conditionals. This
makes different runs of Herbie produce more similar results, and
improves accuracy near those values. If turned off, binary
search will not be used, and the branch values will be less
accurately chosen. You will want to turn this option off if
behavior near branches is not important to you, in which case
turning off this option will make Herbie slightly faster.
- This option, on by default, allows Herbie to branch on
expressions, not just variables. This can improve accuracy on
regime branching, but can significantly increase the runtime,
particularly for large programs. If turned off, Herbie will only
try to branch on variables. You may want to turn this option off
if Herbie runtime is more important to you than expression
Upgrading from Herbie 1.0
Herbie 1.0 used
a different command line
syntax, without multiple tools. Translate like so:
herbie-1.0 file →
herbie-1.1 improve file -
herbie-1.0 files ... →
cat files ... | herbie-1.1 improve - -
Alternatively, collect the files into a directory and run
herbie-1.1 improve dir/ -
The new syntax somewhat changes Herbie's behavior, such as by
using the input expression as the output if Herbie times out. It
also makes it easier to write Herbie's output to a file without
using command-line redirection. The old syntax still works but is
deprecated and will be removed in the next release.