Metadata-Version: 2.1
Name: titanfp
Version: 0.1.0
Summary: number systems research with FPBench, including implementation of posits
Author-email: Bill Zorn <billzorn@cs.washington.edu>, Brett Saiki <bsaiki@cs.washington.edu>
License: MIT License
        
        Copyright (c) 2017 Bill
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/billzorn/titanic
Project-URL: Issues, https://github.com/billzorn/titanic/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1
Requires-Dist: gmpy2>=2.2
Requires-Dist: antlr4-python3-runtime~=4.9.3

# Titanic

Titanic is a tool for designing and experimenting
with novel computer arithmetic formats.
It builds on the GNU MPFR library for arbitrary-precision arithmetic,
providing additional support for low-level floating-point behaviors
such as precise control of rounding and precision tracking.

Titanic uses the [FPCore](http://fpbench.org/spec/)
benchmark format for floating-point computations.
Reference interpereters are provided for the FPCore language
using both [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754)
and [posit](https://posithub.org/index) arithmetics,
as well as fixed-point.
These interpreters can also interface with each other
(and with custom user-defined arithmetics)
to perform multiple precision, multiple format computations.

## Dependencies

A quick list of what you need to get this running on a Ubuntu 20.04 system:

- antlr4.9.3, and a java runtime for it (default-jdk works)
- make gcc g++
- python3 python3-venv python3-dev
- libgmp-dev libmpfr-dev libmpc-dev
- npm and nodejs for the webtool

## Setup guide

Here's a list of steps to "install" the tools and make sure they are working.

### OS dependencies

Usually I use more modern Ubuntu LTS releases (16.04 - 20.04). The following should install all of the package-manager level dependencies needed. On other systems, the commands might vary.

`sudo apt install make gcc g++ python3 python3-venv python3-dev libgmp-dev libmpfr-dev libmpc-dev default-jdk`

A recent-ish version of node (16+) is required for the webdemo, unfortunately this does not just `sudo apt install` on Ubuntu 20.04 (you get node 10). The easiest way is probably to stick the prebuilt binaries in some local folder and just invoke npm from there.

### Clone the repo somewhere

`git clone git@github.com:billzorn/titanic.git`

or, for https (i.e. for read only access)

`git clone https://github.com/billzorn/titanic.git`

### Make a Python3 virtual environment

Hopefully Python3.8 is around, so we can use that. Python3.7 also works fine.

```
cd titanic/
python3 -m venv .env
source .env/bin/activate
pip install --upgrade pip
pip install --upgrade -r requirements.txt
```

### Set up the ANTLR4 grammars for FPCore

I use the ANTLR4 tool to generate lexers and parsers for the FPCore language. The generated code is Python, but the generator itself (the ANTLR tool) is Java. First we need to download the latest ANTLR version:

```
cd titanic/titanfp/fpbench/antlr
wget "https://www.antlr.org/download/antlr-4.9.3-complete.jar"
```

4.9.3 is known working with Java 8 and is hardcoded in the requirements and the antlr Makefile. Newer versions of ANTLR4 may require Java versions after Java 8.

Now we can run it, to make the generated Python files that Titanic will expect to exist to provide the lexer and parser:

`make clean && make`

At this point, Titanic should be working. We can test it easily by seeing if the webtool works.

### Set up the Webtool

The Webtool (or webdemo, as the repo calls it) is a big webpack thing that depends on a NodeJS package for deployment. First we need to install the node package:

```
cd titanic/titanfp/web
npm install
```

This might spit out a lot of stuff and complain, but hopefully it works.

### Launch the webtool

Now we can enter the arcane build command to bring up the webtool server. Run this from the root of the Titanic repo (i.e. `titanic/`), and make sure the virtual environment is active (i.e. this shell has run `.env/bin/activate`).

`(cd titanfp/web && npm run build-debug) && python -m titanfp.web.webdemo --serve titanfp/web/dist --host "" --port 8009`

This will attempt to host the webdemo on port 8009; you can visit it with a browser to see if it's working.

Click "Check out the Titanic Evaluator webtool" at the bottom: a split screen interface should appear, with some code on the right and controls on the left. Type any number (i.e. 1.3) into the FPCore arguments box, and click Evalue FPCore underneath: you should see back the same value in the output log, and probably something in the termanil where the webserver is running.

Stop the sever by closing stdin (Ctrl-d) in the terminal.
