HTTP API

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.

Format for all endpoints

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

/api/sample

Example input & output

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.

/api/exacts

Example input & output

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.

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

/api/calculate

Example inputs & outputs

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

/api/analyze

Example inputs & outputs

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.

/api/alternatives

Example inputs & outputs

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.

/api/mathjs

Example inputs & outputs

Request:

{
  formula: <FPCore expression>
}

Response:

{
  mathjs: <mathjs expression>
}

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

/api/cost

Example inputs & outputs

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.

/api/translate

Example inputs & outputs

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.

⚠️ Beta endpoints

The endpoints below are currently a work in progress.

/api/localerror

Forthcoming.

/api/timeline/{job-id}

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