Command-line Options

The 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 commands

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:

herbie web

Use Herbie through your browser. herbie web starts a web server for running Herbie on your local machine, and directs a browser to visit that server.

herbie shell

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 input file or directory, and outputs the result to output, which will be a single file of FPCore outputs.

herbie report input output

Runs Herbie on the expressions in the input file 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, web and 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.

General options

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.

--seed S

The random seed, which changes the randomly-selected points that Herbie evaluates candidate expressions on. The seed is a number between 0 and 2³¹ (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.

--num-iters N

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.

--num-points N

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.

--timeout T

The timeout to use per-example, in seconds. A fractional number of seconds can be given.

--threads N, for improve and reports

Enables multi-threaded operation. By default, no threads are used. A number can be passed to this option to use that many threads, or yes can be passed to tell Herbie to use all but one of the hardware threads.

Web shell options

The web tool runs Herbie as a web server, and connects to it from your browser. It has additional options to control this server.

--port N

The port to run the Herbie server on. The default port is 8000.

--save-session dir

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.

--log file

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.

--quiet

When set, a browser is not started to point to the server main page, and a smaller banner is printed to the command line.

Rulesets

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 --disable rules:group and --enable 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 using them.

The full list of rule groups is:

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.

Search options

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 Herbie.

Each option can be turned off with the -o X or --disable X command-line flag, and turned on with the +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 output expressions.

precision:double

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.

precision:fallback

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.

setup:simplify

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 chosen.

setup:early-exit

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.

generate:rr

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.

generate:taylor

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 formulas.

generate:simplify

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.

reduce:regimes

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 programming.

reduce:simplify

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 off.

reduce:avg-error

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 accuracy.

reduce:binary-search

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.

reduce:branch-expressions

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 accuracy.

Upgrading from Herbie 1.0

Herbie 1.0 used a different command line syntax, without multiple tools. Translate like so:

• herbie-1.0 → herbie-1.1 shell
• 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.