Command-line Options

The herbie command has subcommands and options that influence both its user interface and the quality of its output.

Herbie commands

There are a few different methods for interacting with Herbie, which we call tools. For example, Herbie can be run both interactively or in batch mode, and can generate output intended for the command line or for the web. Herbie provides four of these tools as subcommands:

racket -l herbie web
Use Herbie through your browser. The web command runs Herbie on your local machine and opens its main page in your browser.
racket -l herbie shell
Use Herbie via a command-line shell. Enter an FPCore expression and Herbie will print its more-accurate version.
racket -l herbie improve input output
Run Herbie on the expressions in the file or directory input. The results are written to output, a single file in FPCore format.
racket -l herbie report input output
Run Herbie on the expressions in the file or directory input. The results are written to output, a directory of HTML reports. Viewing these requires a web server.

We recommend web which produces reports with lots of information about floating-point accuracy, including graphs of error versus input values and plots comparing cost and accuracy. This can help you understand whether Herbie's improvements matter for your use case.

Use herbie tool --help to view available command-line options for a tool. This command also shows undocumented subcommands 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, like this:

racket -l herbie report --timeout 60 in.fpcore out/

Arguments cannot go before options.

--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 231 (not including the latter). This option can be used to make Herbie's results reproducible or to compare two different runs. If not specified, a random seed is chosen.
--num-points N
The number of input points Herbie uses to evaluate candidate expressions. The default, 256, is a good balance for most programs. Increasing this option, say to 512 or 1024, will slow Herbie down but may make its results more consistent.
--num-iters N
The number of times Herbie attempts to improve accuracy. The default, 4, suffices for most programs and helps keep Herbie fast; in practice iterations beyond the first few rarely lead to lower error. Increase this option, say to 6, to check that there aren't further improvements that Herbie could seek out.
--num-analysis N
The number of input subdivisions to use when searching for valid input points. The default is 12. Increasing this option will slow Herbie down, but may fix the "Cannot sample enough valid points" error.
--num-enodes N
The number of equivalence graph nodes to use when doing algebraic reasoning. The default is 8000. Increasing this option will slow Herbie down, but may improve results slightly.
--timeout T
The timeout to use per-input, in seconds. A fractional number of seconds can be given.
--threads N (for the improve and report tools)
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 of the hardware threads.
--no-pareto
Disables cost-aware search. Herbie will only return a single program, which optimizes exclusively for accuracy. Herbie will be slightly faster as a result.

Web shell options

The web tool runs Herbie and connects to it from your browser. It has options to control the underlying web server.

--port N
The port the Herbie server runs on. The default port is 8000.
--save-session dir
Save all the reports to this directory. The directory also caches previously-computed expressions.
--log file
Write an access log to this file, formatted like an Apache log. This log does not contain crash tracebacks.
--quiet
By default, but not when this option is set, a browser is automatically started to show the Herbie page. This option also shrinks the text printed on start up.
--no-browser
This flag disables the default behavior of opening the Herbie page in your default browser.
--public
When set, users on other computers can connect to the demo and use it. (In other words, the server listens on 0.0.0.0.) Essential when Herbie is run from Docker.

Rulesets

Herbie uses rewrite rules to change programs and improve accuracy. The --disable rules:group and --enable rules:group options turn rule sets on and off. In general, turning a ruleset on makes Herbie produce more accurate programs.

The full list of rule groups is:

Rule GroupTopic of rewrite rules
arithmeticBasic arithmetic facts
polynomialsFactoring and powers
fractionsFraction arithmetic
exponentsExponentiation identities
trigonometryTrigonometric identities
hyperbolicHyperbolic trigonometric identities
boolsBoolean operator identities
branchesif statement simplification
specialThe gamma and error functions
numericsNumerical shorthands expm1, log1p, fma, and hypot

Search options

These options change the types of transformations that Herbie uses to find candidate programs. We recommend sticking to the defaults.

Each option can be turned off with the -o or --disable command-line flag and on with +o or --enable. Turning an option off typically results in less-accurate results, while turning a option on typically results in more confusing output expressions.

setup:search
This option, on by default, uses interval subdivision search to help compute ground truth for complicated expressions. If turned off, Herbie will be slightly faster, but may hit the "Cannot sample enough valid points" error more often. Instead of turning this option off, you may want to adjust the --num-analysis flag instead.
setup:simplify
This option, on by default, simplifies the expression before starting the Herbie improvement loop. If turned off, Herbie's results will likely be somewhat worse, but its output program may be more similar to the input program.
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 Herbie's creativity.
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. If turned off, Herbie's results will more likely be algebraically equivalent to the input expression, but may be less accurate.
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.
generate:proofs
This option, on by default, generates step-by-step derivations for HTML reports. If turned off, the step-by-step derivations will be absent, and Herbie will be slightly faster.
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). Turn this option off if your programming environment makes branches very expensive, such as on a GPU.
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. 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 inferred branches. If turned off, different runs of Herbie will be less consistent, and accuracy near branches will suffer.
reduce:branch-expressions
This option, on by default, allows Herbie to branch on expressions, not just variables. This slows Herbie down, particularly for large programs. If turned off, Herbie will only try to branch on variables.