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 -X POST -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/local-error

Forthcoming.