Command-line Options

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

Herbie commands

Herbie provides several subcommands, which offer interactive and batch modes for both the command line and the web interface:

racket -l herbie web
Use Herbie through your browser using a local server. This server can also be used from Odyssey.
racket -l herbie shell
Use Herbie via a command-line shell. Enter an FPCore expression and Herbie prints faster and more accurate alternatives.
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 the web subcommand for interactive use with detailed reports that include 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 subcommand --help to view available command-line options for a subcommand. This command also shows undocumented subcommands not listed on this page.

General options

General options apply to all subcommands and are passed after the subcommand name but before other arguments, like this:

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

Options must go before subcommand arguments like input and output paths.

--platform P
Herbie's backend platform, which affects the operations available to Herbie, their accuracies, and their costs. The platform name is either one of the built-in platforms, or the path to a custom platform. In general, it's best to select the platform that most closely matches the programming language and hardware where you will be running floating-point code.
--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). Two runs of Herbie with the same seed should produce identical results. By default, a random seed is chosen.
--timeout T
The timeout to use per-input, in seconds. A fractional number of seconds can be given. By default, no timeout is used.
--threads N
Enables multi-threaded operation. By default, no threads are used. The argument is the number of threads to use, or yes to use all of the hardware threads.
--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 attempts Herbie makes to improve accuracy. The default, 4, suffices for most programs, and more iterations are rarely beneficial. But increase this option, say to 6, can sometimes lead to more accurate or faster results.
--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 a "Cannot sample enough valid points" error.
--num-enodes N
The number of equivalence graph nodes to use when doing algebraic reasoning. The default is 4000. Increasing this option will slow Herbie down, but may improve results slightly.

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

Search options

These options enable or disable 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, try adjusting the --num-analysis flag.
generate:rr
This option, on by default, uses algebraic rewriting to generate candidate programs. This is Herbie's primary method of improving accuracy, and we do not recommend turning off this option.
generate:taylor
This option, on by default, uses series expansion to generate candidate programs. If turned off, Herbie will not use series expansion, which may help accuracy in some ranges while leaving Herbie unable to solve certain under- and overflow issues.
generate:evaluate
This option, on by default, uses arbitrary-precision arithmetic to generate candidate programs, specifically by exactly computing some constant expressions. If turned off, these exact computations won't be performed and Herbie won't be able to improve accuracy in those cases.
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). Instead of turning this option off, consider increasing your platform's if cost to discourage branches.
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.