An Approach to Generate Correctly Rounded Math Libraries for New Floating Point Variants

Abstract :

This file describes the artifact for the paper, An Approach to Generate Correctly Rounded Math Libraries for New Floating Point Variants. We describe the list of claims made by the paper, the installation instructions, and evaluation instructions. We provide complete instructions to manually install the artifact on Ubuntu-16.04 or Ubuntu-18.04. We also provide a docker image with all pre-requisite and installations complete.

_________________________________________________________________________________________________

* Hardware recommendation:

All of our evaluations were performed on a machine with Intel Xeon Gold 6130 machine with 2.10GHz processor and 32GB of RAM, which runs Ubuntu-16.04-LTS. However, we predict that the artifact should be functional with modern machines with 16GB of RAM, running Ubuntu-16.04 or Ubuntu-18.04 operating system.

_________________________________________________________________________________________________

* Claims made from the paper:

All claims to be evaluated in the artifact are found in Section 5. Experimental Evaluation.

(1) Our technique successfully generates polynomials that are used in the correctly rounded math library functions for bfloat16, posit16, and float (claimed in Table 1).

(2) The math library functions created using our technique produces the correctly rounded result for all inputs (claimed in Table 1).

(3) Using glibc's float math library to compute the 10^x function for bfloat16 does not produce the correctly rounded result. Similarly, using glibc's float math library to compute log2(x) function for float does not produce the correctly rounded result. (claimed in Table 1)

(4) On average, ourLibm's functions are 1.79x faster when compared to glibc's float library and 2.3x faster over glibc's double math library. Also we claim specific speedup of each math library function (claimed in Figure 11)

(5) We also report ourLibm's posit16 function speedup compared to SoftPosit-Math library in Figure 12.

(6) Section 5.3.3 reports 1.02x speedup of ourLibm's log2(x) for float compared to glibc's log2(x) for float.

_________________________________________________________________________________________________

* INSTALLATION GUIDE:

There are two methods to install the artifact: (1) Installing docker and downloading the docker image for the artifact or (2) Manual installation. We recommend to use the docker image provided to expedite the installation process.

** DOWNLOADING PREBUILT DOCKER IMAGE

    We have prebuilt a docker image and hosted it in the docker hub.

(1) Install docker if not already installed by following the installation documentation in this link: https://docs.docker.com/install/

    We recommend installing docker and evaluating our artifact on a machine with Ubuntu. Although docker can be used with Windows or MacOS, docker may run on top of a linux VM

(2) Download the prebuilt docker image by using the command:

    $ sudo docker pull jpl169/popl21artifact

    The docker image is roughly 1GB

(3) Run the docker image:

    $ sudo docker run -it jpl169/popl21artifact

(4) If running the docker image on macOS, increase docker's memory resource. You can increase memory resource by going to docker->preference->Resources. 12GB ~ 16GB of memory usage should be sufficient.

(5) Installation is complete. Go to EVALUATION GUIDE section.

** MANUAL INSTALLATION

(1) To install and evaluate the artifact manually, first install a list of prerequisites:

    $ sudo apt-get update
    $ sudo apt-get install build-essential cmake git libgmp3-dev libmpfr-dev zlib1g zlib1g-dev bc  wget python python3 python3-pip
    $ python3 -m pip install matplotlib

(2) Download and install soplex 4.0.1:
    
    Please download soplex-4.0.1 from https://soplex.zib.de/index.php#download.

    $ tar -xvf soplex-4.0.1.tar
    $ cd soplex-4.0.1
    $ mkdir build
    $ cd build
    $ cmake ..
    $ make
    $ cd ../..

(3) Download and compile SoftPosit :
    $ git clone https://gitlab.com/cerlane/SoftPosit.git
        $ cd SoftPosit/build/Linux-x86_64-GCC/
        $ make
        $ cd ../../..

(4) Download and compile softposit-math :
    $ git clone https://gitlab.com/cerlane/softposit-math.git
    $ cd softposit-math/build/
    $ ./make.sh
    $ cd ../..

(5) Set the following environment variables:
    $ export SOFTPOSITPATH=<path to SoftPosit directory>
    $ export SOPLEXPATH=<path to soplex-4.0.1 directory>
    $ export SOFTPOSITMATHPATH=<path to softposit-math>

(6.a) Download POPL21 artifact from github
    $ git clone https://github.com/jpl169/POPL21-artifact.git
    $ cd POPL21-artifact

(6.b) Or, download POPL21-artifact.tar this Zenodo page and untar the file:
    $ tar -xvf POPL21-artifact.tar
    $ cd POPL21-artifact

(7) Installation is complete. Go to EVALUATION GUIDE section.

_________________________________________________________________________________________________

* EVALUATION GUIDE FOR THE ARTIFACT

    If you have followed one of the two installation methods in the INSTALLATION GUIDE section, you should be in POPL21-artifact directory.

(1) Generating the polynomials for ourLibm (Claim 1):

    To test our technique in generating the polynomials, run the bash script,

    $ ./runFunctionGen.sh

    This script will take roughly 20 minutes. This script creates a number of header files that contains coefficients for each elementary function generated by our function generator. These header files are used to build the library for correctness testing and performance testing. The header files are located in:
    - functiongen/bfloat16/full/headers : for bfloat16 functions - 10 header files
    - function/posit16/full/headers : for posit16 functions - 6 header files
    - function/float/sampling/headers : for log2 function for float - 1 header file

    To check that our function generator created header files, you can build ourLibm math library and verify that no error message is showing. To do so, go to POPL21-artifact folder and:

    $ make

(2) Checking the correctness of ourLibm (Claim 2 & 3):
    
    To test the correctness of ourLibm, run the bash script,
    
    $ ./runLibTest.sh

    This script will take roughly 2 minutes. Once the script terminates, you will see LibTestResult.txt in POPL21-artifact directory. For each representation (bfloat16, posit16, and float), we list the available functions, and whether ourLib produces the correctly rounded value for all inputs. If ourLib produces the correctly rounded value for all inputs for a particular function, you will see the message "Function returns correct values for all inputs." You should see this message for ALL functions. This experiment tests for claim (2).

    Additionally, you should see an additional message for bfloat16's EXP10 function and float's LOG2 function that says, "Using Glibc's float mlib computes X/Y values incorrectly." This message indicates that using glibc mlib's float math library to compute the result of bfloat16's EXP10 or float's LOG2, then X number of inputs produce incorrect results. This message correlates to the claim (3).

(3) Checking the speedup of ourLibm (Claim 4, 5, & 6):

    - To test the speedup of ourLibm, run the bash script,
    
    $ ./runOverheadTest.sh

    This script will take roughly 10~20 minutes. Once the script terminates, you will see the following files:

    (a) bfloatOverheadFull.pdf - This file shows the graph presented in Figure 11 (a)
    (b) bfloatOverheadInternal.pdf - This file shows the graph presented in Figure 11 (b)
    (c) positOverheadInternal.pdf - This file shows the graph presented in Figure 12
    (d) F32OvhdRslt.txt - This file shows the speedup of ourLibm's log2(x) for float compared to glibc mlib's log2(x) for float.

    - If you're using docker to evaluate the artifact, you can copy the pdf's from the container to your host machine using the following commands:

    $ exit
    $ sudo docker container ls -a  (Find the correct container id)
    $ sudo docker cp <container id>:/home/POPL21-artifact/bfloatOverheadFull.pdf .
    $ sudo docker cp <container id>:/home/POPL21-artifact/bfloatOverheadInternal.pdf .
    $ sudo docker cp <container id>:/home/POPL21-artifact/positOverheadInternal.pdf .

    - To go back into docker container, use the following commands:

    $ sudo docker start <container id>
    $ sudo docker attach <container id>

    To evaluate the result, compare the graphs from the pdf against Figure 11 and Figure 12. The speedup may be differ greatly between hardware architecture.

    Additionally, the file F32OvhdRslt.txt shows the speedup of ourLibm's log2(x) for float compared to glibc mlib's log2(x) for float. Since the submission, we have improved our technique in generating the polynomial and the range reduction technique for log2(x). Hence, you should see a significantly higher speedup (roughly 1.2x over glibc's float library and 1.5x over double library).

_________________________________________________________________________________________________

* CASE STUDY: COMPARISON BETWEEN GENERATED POLYNOMIAL AND OURLIBM IMPLEMENTATION

If you are interested in the source code of ourLibm, the source code is located in "source" directory. The source code is separated into the math library functions for bfloat16, posit16, and float in its own sub-directory. The case study shown in Section 5.4 describes our experiences in creating the math library functions, and hence, reflects the code in the source code.

(1) Section 5.4.1: 10^x for Bfloat16

    The source code of 10^x of Bfloat16 is located in source/bfloat16/exp10.cpp. The coefficients used in this source code is located in functiongen/bfloat16/full/headers/exp10.h. The special cases and range reduction technique used in the file should match with the description in Section 5.4.1

(2) Section 5.4.2: ln(x), log2(x), and log10(x) for Bfloat16

    The source code of ln(x), log2(x), and log10(x) for Bfloat16 is located in source/bfloat16/log.cpp, source/bfloat16/log2.cpp, and source/bfloat16/log10.cpp, respectively. The coefficients used in these source codes does are located in functiongen/fbloat16/full/header/log.h, functiongen/fbloat16/full/header/log2.h, and functiongen/fbloat16/full/header/log10.h, respectively. The special cases and range reduction technique used in the file should match with the description in Section 5.4.2

(3) Section 5.4.3: log2(x) for 32-bit float

    The source code of log2(x) for 32-bit float is located in source/float/log2.cpp. The coefficients used in these source code is located in functiongen/float/sampling/log2.h. Since the submission, we made several improvements to ourLibm and the technique. Hence, the range reduction technique and the polynomial used in the implementation is different from the description in Section 5.4.3. The new implementation produces the correct result for ALL inputs, not just inputs between 1 and 2. 

    We provide a script that checks whether our log2(x) function for float produces the correctly rounded result for all inputs. This claim is not a part of our submission, and we provide this script for the completeness. This script will take roughly 2-3 hours to complete. To run the script, use the command:

    $ ./runFullLog2ForFloat.sh

    Once the script finishes, you will find LibTestFulLog2Float.txt. This file should say "Function returns correct values for all inputs."