Odyssey: An Interactive Numerics Workbench

[Video tutorial (8.5 min)] [Setup]

Odyssey is a tool for interactively rewriting numerical expressions to reduce floating-point error.

Before using Odyssey, please see Running Odyssey below to install dependencies.

Features
Running Odyssey
Submitting Feedback and Getting Help
Release Notes
For Developers

Features

Odyssey displays the local error of expressions. Local error shows how different subexpressions contribute to the total error for an input.

Odyssey generates rewriting suggestions with the state-of-the-art Herbie floating-point expression rewriting tool.

Derivations of Herbie's rewrites are also available.

The sample range of the expression can be adjusted to fit your use case.

A full walkthrough of Odyssey is available in the video tutorial.

If you have any questions about features, please open an issue on Github.

Running Odyssey

Odyssey runs as a VSCode extension. You can install it from the VSCode Marketplace here, but first follow the instructions below to install dependencies.

Dependencies

Odyssey uses a Herbie server to analyze expressions and currently requires you to bring your own Herbie instance. After following the Herbie installation instructions, you can run a Herbie server with

$ herbie web --port 8000 --quiet
# Response should look like:
Herbie 2.0 with seed 552322303
Find help on https://herbie.uwplse.org/, exit with Ctrl-C
Your Web application is running at http://localhost:8000.
Stop this program at any time to terminate the Web Server.

Running the VSCode extension

After starting the Herbie server, run Odyssey from the VSCode command palette by clicking on VSCode and using Ctrl/Command-Shift-P > Odyssey: Herbie.

The server status shown in Odyssey should have the text "Connected."

If the server status is red with the text "No Server", Odyssey can't connect to the Herbie server.

If needed, you can adjust the server address where Odyssey looks for Herbie by clicking on the server status. Make sure that the port Odyssey is connecting to is the same one Herbie is being hosted on.

(Alternative) Running as a standalone web application

Odyssey can also run as a standalone web application.

First, you'll need to install node from https://nodejs.org/en/download/.

Next, clone this repo and build the application:

$ git clone https://github.com/herbie-fp/odyssey
$ cd odyssey
$ npm install
$ npm run compile

Then, after starting the Herbie server, run an HTTP server to serve the index.html file:

$ npx serve -p 3000

Submitting Feedback and Getting Help

Please submit any feedback or bug reports by opening an issue on this repo.

Release Notes

1.0.0

First public release

0.4.0

Rename repo + extension
Still unofficial; expecting to release 1.0 at the beginning of August

0.1.0

First major post-study 1 version

For Developers

Setting up a development environment

$ npm install
# Then use command/control+shift+B to start the auto-compile task
# Each time compilation finishes, you should see a message like "webpack 5.82.1 compiled with 1 warning in 31769 ms"

Testing the extension

Use the "Run and Debug" tab to start an instance of VSCode with the most recent code.

You can see changes to the frontend (webview/index.ts) by simply refreshing the webview, but changes to the host (extension.ts) will only show if the debugger is restarted.

Publishing the extension:

Get publication key from @elmisback, then:

# update "version" in package.json and commit, then
$ npm run publish

Acknowledgements

This work is supported by the U.S. Department of Energy, Office of Science, Office of Advanced Scientific Computing Research, ComPort: Rigorous Testing Methods to Safeguard Software Porting, under Award Number DE-SC0022081.

herbie-fp / odyssey

readme