Skip to content

Commit 63d831e

Browse files
pavpanchekhapavpanchekha
authored
Merge pull request #1353 from herbie-fp/setup-2.3
Set up for Herbie 2.3
2 parents 0cc3b64 + c0c42cd commit 63d831e

40 files changed

+3064
-3
lines changed

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ upgrade:
5353
$(MAKE) install
5454

5555
start-server:
56-
racket -y src/main.rkt web --seed 1 --timeout 150 --num-iters 2 \
56+
racket -y src/main.rkt web --seed 1 --timeout 150 --threads 8 \
5757
--demo --public --prefix /demo/ --port 4053 --save-session www/demo/ \
5858
--log infra/server.log --quiet 2>&1
5959

‎src/config.rkt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@
201201
(if (equal? out "") default out)]
202202
[else default]))
203203

204-
(define *herbie-version* "2.2")
204+
(define *herbie-version* "2.3")
205205

206206
(define *herbie-commit* (git-command "rev-parse" "HEAD" #:default *herbie-version*))
207207

‎src/info.rkt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#lang info
22

33
(define collection "herbie")
4-
(define version "2.2")
4+
(define version "2.3")
55
(define license 'MIT)
66

77
;; Packaging information

‎www/doc/2.3/api-endpoints.html‎

Lines changed: 354 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,354 @@
1+
<!doctype html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8" />
5+
<title>Herbie HTTP API Endpoints</title>
6+
<link rel='stylesheet' type='text/css' href='../../main.css'>
7+
<meta name="viewport" content="width=device-width, initial-scale=1" />
8+
<script type="text/javascript" src="toc.js"></script>
9+
</head>
10+
<body>
11+
<header>
12+
<h1>HTTP API</h1>
13+
<a href="../../"><img class="logo" src="../../logo-car.png" /></a>
14+
<nav>
15+
<ul>
16+
<li><a href="../../demo/">Try</a></li>
17+
<li><a href="installing.html">Install</a></li>
18+
<li><a href="tutorial.html">Learn</a></li>
19+
</ul>
20+
</nav>
21+
</header>
22+
23+
<p>The <a href="../../">Herbie</a> API allows applications to
24+
interface with Herbie using HTTP requests. The API is designed to
25+
be stateless: the order in which endpoints are called shouldn't
26+
matter.</p>
27+
28+
<h2 id="all-endpoints-info">Format for all endpoints</h2>
29+
30+
<p>All the endpoints listed below respond to POST requests unless
31+
otherwise specified. A typical example of sending a POST request
32+
to a running Herbie server is:</p>
33+
34+
<pre class="shell">curl -d \
35+
'{"formula": "(FPCore (x) (- (sqrt (+ x 1))))", "seed": 5}' \
36+
-H 'Content-Type: application/json' \
37+
http://127.0.0.1:8000/api/sample
38+
</pre>
39+
40+
<h2 id="sample">/api/sample</h2>
41+
42+
<details>
43+
<summary>Example input & output</summary>
44+
45+
<p>Request:</p>
46+
47+
<pre>{
48+
formula: &lt;FPCore expression&gt;,
49+
seed: &lt;random seed for point generation&gt;
50+
}</pre>
51+
52+
<p>Response:</p>
53+
54+
<pre>{
55+
points: [[point, exact], ... ]
56+
}</pre>
57+
</details>
58+
59+
<p>The <code>sample</code> endpoint allows the user to request a
60+
sample of points given the FPCore expression and a seed.</p>
61+
62+
<p>Returns a collection of points and the exact evaluation of each
63+
point with the given spec. The results are returned through the
64+
"points" field and are represented by an array of point-exact
65+
pairs with the first value representing the point and the second
66+
value representing the exact evaluation; the exact value of
67+
point <code>n</code> is <code>points[n][1]</code>.</p>
68+
69+
<p>Herbie calculates the "ground truth" by calculating the values
70+
with more precise numbers. This can be slow.</p>
71+
72+
<h2 id="exacts">/api/exacts</h2>
73+
74+
<details>
75+
<summary>Example input & output</summary>
76+
77+
<p>Request:</p>
78+
79+
<pre>{
80+
formula: &lt;FPCore expression&gt;,
81+
sample: [point, ... ]
82+
}</pre>
83+
84+
<p>Response:</p>
85+
86+
<pre>{
87+
points: [[point, exact], ... ]
88+
}</pre>
89+
</details>
90+
91+
<p>The <code>exacts</code> endpoint allows the user to request the
92+
exact value of a set of points evaluated at a real number
93+
specification given as an FPCore expression.</p>
94+
95+
<p>Some points may not be calculable given the FPCore
96+
expression.</p>
97+
98+
<p>Returns a collection of points and the exact evaluation of each
99+
point with the given spec. The results are returned through the
100+
"points" field and are represented by an array of point-exact
101+
pairs with the first value representing the point and the second
102+
value representing the exact evaluation; the exact value of
103+
point <code>n</code> is <code>points[n][1]</code>.</p>
104+
105+
<p>Herbie calculates the "ground truth" by calculating the values
106+
with more precise numbers. This can be slow.</p>
107+
108+
<h2 id="calculate">/api/calculate</h2>
109+
110+
<details>
111+
<summary>Example inputs & outputs</summary>
112+
113+
<p>Request:</p>
114+
115+
<pre>{
116+
formula: &lt;FPCore expression&gt;,
117+
sample: [point ... ]
118+
}</pre>
119+
120+
<p>Response:</p>
121+
122+
<pre>{
123+
points: [[point, exact], ... ]
124+
}</pre>
125+
</details>
126+
127+
<p>The <code>calculate</code> endpoint allows the user to request
128+
the evaluation of a set of points evaluated at a floating-point
129+
implementation given as an FPCore expression.</p>
130+
131+
<p>Some points may not be calculable given the FPCore expression.</p>
132+
133+
<p>Returns a collection of points and the evaluation of each point
134+
using the given FPCore as a floating-point implementation. The
135+
results are returned through the "points" field and are
136+
represented by an array of point-exact pairs with the first value
137+
representing the point and the second value representing the
138+
evaluated value; the evaluated value of point <code>n</code>
139+
is <code>points[n][1]</code>.</p>
140+
141+
<h2 id="analyze">/api/analyze</h2>
142+
143+
<details>
144+
<summary>Example inputs & outputs</summary>
145+
146+
<p>Request:</p>
147+
148+
<pre>{
149+
formula: &lt;FPCore expression&gt;,
150+
sample: [[point, exact], ... ]
151+
}</pre>
152+
153+
<p>Response:</p>
154+
155+
<pre>{
156+
points: [[point, error], ... ]
157+
}</pre>
158+
</details>
159+
160+
<p>The <code>analyze</code> endpoint allows the user to request
161+
error analysis of a set of point-exact pairs and a given
162+
floating-point implementation.</p>
163+
164+
<p>Given a collection of points, their exact values, and an FPCore
165+
expression to analyze on, the <code>analyze</code> endpoint
166+
returns the error for each point for that expression. The error
167+
value returned is Herbie's internal error heuristic.</p>
168+
169+
<h2 id="alternatives">/api/alternatives</h2>
170+
171+
<details>
172+
<summary>Example inputs & outputs</summary>
173+
<p>Request:</p>
174+
175+
<pre>{
176+
formula: &lt;FPCore expression&gt;,
177+
sample: [[point, exact], ... ]
178+
}</pre>
179+
180+
<p>Response:</p>
181+
182+
<pre>{
183+
alternatives: [alt, ... ],
184+
histories: [history, ... ],
185+
splitpoints: [splitpoint, ... ]
186+
}</pre>
187+
</details>
188+
189+
<p>The <code>alternatives</code> endpoint allows the user to
190+
request rewrites from Herbie given an expression to rewrite and a
191+
set of point-exact pairs.</p>
192+
193+
<p>Returns a list of alternatives represented by FPCore
194+
expressions through the "alternatives" field.</p>
195+
196+
<p>Returns a list of derivations of each alternative through the
197+
"histories" field where <code>history[n]</code> corresponds
198+
to <code>alternatives[n]</code>.</p>
199+
200+
<p>Returns a list of splitpoints for each alternative through the
201+
"splitpoints" field where <code>splitpoints[n]</code> corresponds
202+
to <code>alternatives[n]</code>. <code>splitpoints[n]</code> will
203+
only contain information about the corresponding alternative.s
204+
splitpoints if the alternative is a branch-expression.</p>
205+
206+
<h2 id="mathjs">/api/mathjs</h2>
207+
208+
<details>
209+
<summary>Example inputs & outputs</summary>
210+
<p>Request:</p>
211+
212+
<pre>{
213+
formula: &lt;FPCore expression&gt;
214+
}</pre>
215+
216+
<p>Response:</p>
217+
218+
<pre>{
219+
mathjs: &lt;mathjs expression&gt;
220+
}</pre>
221+
</details>
222+
223+
<p>The <code>mathjs</code> endpoint allows the user to translate
224+
FPCore expressions into mathjs expressions.</p>
225+
226+
227+
<h2 id="cost">/api/cost</h2>
228+
229+
<details>
230+
<summary>Example inputs & outputs</summary>
231+
232+
<p>Request:</p>
233+
234+
<pre>{
235+
formula: &lt;FPCore expression&gt;,
236+
sample: [point ... ]
237+
}</pre>
238+
239+
<p>Response:</p>
240+
241+
<pre>{
242+
cost: cost
243+
}</pre>
244+
245+
<p><b>Specific Example: sqrt(x+1)-sqrt(x)</b></p>
246+
247+
<p>Request:</p>
248+
249+
<pre>{
250+
formula: &lt;(FPCore (x) (- (sqrt (+ x 1)) (sqrt x)))&gt;,
251+
sample: [ [[1], -1.4142135623730951] ]
252+
}</pre>
253+
254+
<p>Response:</p>
255+
256+
<pre>{
257+
cost: 13120
258+
}</pre>
259+
260+
<p><b>Lower-Cost Example: (x+1)-(x)</b></p>
261+
262+
<p>Request:</p>
263+
264+
<pre>{
265+
formula: &lt;(FPCore (x) (- (+ x 1 ) x))&gt;,
266+
sample: [ [[1], -1.4142135623730951] ]
267+
}</pre>
268+
269+
<p>Response:</p>
270+
271+
<pre>{
272+
cost: 320
273+
}</pre>
274+
275+
</details>
276+
277+
<p>The <code>cost</code> endpoint allows the user to request
278+
the evaluation of an expression's overall cost. Cost is
279+
calculated depending on the complexity of operations contained
280+
in the expression. </p>
281+
282+
<p>Given an FPCore expression and a collection of points,
283+
returns the cost of the expression. The cost value returned
284+
is calculated internally by Herbie.</p>
285+
286+
<p>The points should be of the same format as the points
287+
generated in the sample endpoint. Refer to /api/sample
288+
for more details. </p>
289+
290+
<p>Note the sample points are not used in the cost calculation.
291+
The contents of the points do not matter as long as they are
292+
in the correct format as mentioned above.</p>
293+
294+
<!-- Translate Endpoint -->
295+
296+
<h2 id="translate">/api/translate</h2>
297+
298+
<details>
299+
<summary>Example inputs & outputs</summary>
300+
301+
<p>Request:</p>
302+
303+
<pre>{
304+
formula: &lt;FPCore expression&gt;,
305+
language: "language"
306+
}</pre>
307+
308+
<p>Response:</p>
309+
310+
<pre>{
311+
result: "translated expression"
312+
}</pre>
313+
314+
<p><b>Specific Example: sqrt(x+1)-sqrt(x)</b></p>
315+
316+
<p>Request:</p>
317+
318+
<pre>{
319+
formula: &lt;(FPCore (x) (- (sqrt (+ x 1)) (sqrt x)))&gt;,
320+
language: "python"
321+
}</pre>
322+
323+
<p>Response:</p>
324+
325+
<pre>{
326+
result: "def expr(x): return math.sqrt((x + 1.0)) - math.sqrt(x)"
327+
}</pre>
328+
329+
</details>
330+
331+
<p>The <code>translate</code> endpoint allows users to translate
332+
FPCore expressions into equivalent expressions in various programming
333+
languages.</p>
334+
335+
<p>Given an FPCore expression and a target language, this endpoint
336+
returns the translated expression in the specified language.
337+
The language parameter should be a string representing the desired
338+
programming language. The response includes the translated expression.</p>
339+
340+
<p>Currently supported languages are: <code>python</code>, <code>c</code>,
341+
<code>fortran</code>, <code>java</code>, <code>julia</code>, <code>matlab</code>,
342+
<code>wls</code>, <code>tex</code>, and <code>js</code>.</p>
343+
<h2>⚠️ Beta endpoints</h2>
344+
<p>The endpoints below are currently a work in progress.</p>
345+
<h2 id="localerror">/api/localerror</h2>
346+
<!--TODO--> Forthcoming.
347+
<h2 id="timeline">/api/timeline/{job-id}</h2>
348+
<p>Retrieves the <code>timeline</code> 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.</p>
349+
<p>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 <code>/infra/testApi.mjs</code> file for current examples of how to use this API.</p>
350+
<pre class="shell">curl -X GET \
351+
http://127.0.0.1:8000/api/timeline/0b95161a77fc3e29376bbb013d96c2827e2a1cd7
352+
</pre>
353+
</body>
354+
</html>

0 commit comments

Comments
 (0)