The Herbie API allows applications to interface with Herbie using HTTP requests. The API is designed to be stateless: the order in which endpoints are called shouldn't matter.

All the endpoints listed below respond to POST requests unless otherwise specified. A typical example of sending a POST request to a running Herbie server is:

curl -d \ '{"formula": "(FPCore (x) (- (sqrt (+ x 1))))", "seed": 5}' \ -H 'Content-Type: application/json' \ http://127.0.0.1:8000/api/sample

Request:

{ formula: <FPCore expression>, seed: <random seed for point generation> }

Response:

{ points: [[point, exact], ... ] }

The `sample`

endpoint allows the user to request a
sample of points given the FPCore expression and a seed.

Returns a collection of points and the exact evaluation of each
point with the given spec. The results are returned through the
"points" field and are represented by an array of point-exact
pairs with the first value representing the point and the second
value representing the exact evaluation; the exact value of
point `n`

is `points[n][1]`

.

Herbie calculates the "ground truth" by calculating the values with more precise numbers. This can be slow.

Request:

{ formula: <FPCore expression>, sample: [point, ... ] }

Response:

{ points: [[point, exact], ... ] }

The `exacts`

endpoint allows the user to request the
exact value of a set of points evaluated at a real number
specification given as an FPCore expression.

Some points may not be calculable given the FPCore expression.

Returns a collection of points and the exact evaluation of each
point with the given spec. The results are returned through the
"points" field and are represented by an array of point-exact
pairs with the first value representing the point and the second
value representing the exact evaluation; the exact value of
point `n`

is `points[n][1]`

.

Herbie calculates the "ground truth" by calculating the values with more precise numbers. This can be slow.

Request:

{ formula: <FPCore expression>, sample: [point ... ] }

Response:

{ points: [[point, exact], ... ] }

The `calculate`

endpoint allows the user to request
the evaluation of a set of points evaluated at a floating-point
implementation given as an FPCore expression.

Some points may not be calculable given the FPCore expression.

Returns a collection of points and the evaluation of each point
using the given FPCore as a floating-point implementation. The
results are returned through the "points" field and are
represented by an array of point-exact pairs with the first value
representing the point and the second value representing the
evaluated value; the evaluated value of point `n`

is `points[n][1]`

.

Request:

{ formula: <FPCore expression>, sample: [[point, exact], ... ] }

Response:

{ points: [[point, error], ... ] }

The `analyze`

endpoint allows the user to request
error analysis of a set of point-exact pairs and a given
floating-point implementation.

Given a collection of points, their exact values, and an FPCore
expression to analyze on, the `analyze`

endpoint
returns the error for each point for that expression. The error
value returned is Herbie's internal error heuristic.

Request:

{ formula: <FPCore expression>, sample: [[point, exact], ... ] }

Response:

{ alternatives: [alt, ... ], histories: [history, ... ], splitpoints: [splitpoint, ... ] }

The `alternatives`

endpoint allows the user to
request rewrites from Herbie given an expression to rewrite and a
set of point-exact pairs.

Returns a list of alternatives represented by FPCore expressions through the "alternatives" field.

Returns a list of derivations of each alternative through the
"histories" field where `history[n]`

corresponds
to `alternatives[n]`

.

Returns a list of splitpoints for each alternative through the
"splitpoints" field where `splitpoints[n]`

corresponds
to `alternatives[n]`

. `splitpoints[n]`

will
only contain information about the corresponding alternative.s
splitpoints if the alternative is a branch-expression.

Request:

{ formula: <FPCore expression> }

Response:

{ mathjs: <mathjs expression> }

The `mathjs`

endpoint allows the user to translate
FPCore expressions into mathjs expressions.

Request:

{ formula: <FPCore expression>, sample: [point ... ] }

Response:

{ cost: cost }

**Specific Example: sqrt(x+1)-sqrt(x)**

Request:

{ formula: <(FPCore (x) (- (sqrt (+ x 1)) (sqrt x)))>, sample: [ [[1], -1.4142135623730951] ] }

Response:

{ cost: 13120 }

**Lower-Cost Example: (x+1)-(x)**

Request:

{ formula: <(FPCore (x) (- (+ x 1 ) x))>, sample: [ [[1], -1.4142135623730951] ] }

Response:

{ cost: 320 }

The `cost`

endpoint allows the user to request
the evaluation of an expression's overall cost. Cost is
calculated depending on the complexity of operations contained
in the expression.

Given an FPCore expression and a collection of points, returns the cost of the expression. The cost value returned is calculated internally by Herbie.

The points should be of the same format as the points generated in the sample endpoint. Refer to /api/sample for more details.

Note the sample points are not used in the cost calculation. The contents of the points do not matter as long as they are in the correct format as mentioned above.

Request:

{ formula: <FPCore expression>, language: "language" }

Response:

{ result: "translated expression" }

**Specific Example: sqrt(x+1)-sqrt(x)**

Request:

{ formula: <(FPCore (x) (- (sqrt (+ x 1)) (sqrt x)))>, language: "python" }

Response:

{ result: "def expr(x): return math.sqrt((x + 1.0)) - math.sqrt(x)" }

The `translate`

endpoint allows users to translate
FPCore expressions into equivalent expressions in various programming
languages.

Given an FPCore expression and a target language, this endpoint returns the translated expression in the specified language. The language parameter should be a string representing the desired programming language. The response includes the translated expression.

Currently supported languages are: `python`

, `c`

,
`fortran`

, `java`

, `julia`

, `matlab`

,
`wls`

, `tex`

, and `js`

.

The endpoints below are currently a work in progress.

Retrieves the `timeline`

data for a given API call. You may find the job id in either the JSON response or in the headers of the HTTP response for of the endpoints in Herbie.

The timeline is an exception to the others in that it uses a GET request. Below is a sample of what the request might look like. You may consult the `/infra/testApi.mjs`

file for current examples of how to use this API.

curl -X GET \ http://127.0.0.1:8000/api/timeline/0b95161a77fc3e29376bbb013d96c2827e2a1cd7