We present the artifact for the accepted 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. To ease the installation effort, we provide a docker image with all required softwares installed already. Additionally, we provide complete instructions to manually install the artifact on Ubuntu-16.04 or Ubuntu-18.04. _________________________________________________________________________________________________ * 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 later. _________________________________________________________________________________________________ * 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= $ export SOPLEXPATH= $ export SOFTPOSITMATHPATH= (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 from Zenodo and untar the file: - Zenodo page: https://doi.org/10.5281/zenodo.4067180 $ tar -xvf POPL21-artifact.tar $ cd POPL21-artifact.tar (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 the POPL21-artifact directory. If you are evaluating the artifact using the provided docker image, you will automatically be placed into POPL21-artifact directory when you run the docker image. (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 build the math library: $ make This build will show a divide by zero warning message, which is intended. (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, the result will be outputted to LibTestResult.txt in POPL21-artifact directory. This file reports whether the elementary math functions produce the correctly rounded value for all inputs, for each representation (bfloat16, posit16, and float). You can view the result file using this command: $ cat LibTestResult.txt 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." after the name of the elementary function. You should see this message for ALL functions. This experiment tests for claim (2). You should also 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 :/home/POPL21-artifact/bfloatOverheadFull.pdf . $ sudo docker cp :/home/POPL21-artifact/bfloatOverheadInternal.pdf . $ sudo docker cp :/home/POPL21-artifact/positOverheadInternal.pdf . - To go back into docker container, use the following commands: $ sudo docker start $ sudo docker attach 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 and specific configurations. 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) for float. Our new log2(x) for float produces the correctly rounded value for all inputs now, as opposed to only inputs between 1 to 2 at the time of submission. Additionally, it uses a different type of range reduction technique. Thus, the new speedup may be different compared to claim (6). Nevertheless, we have observed that we have speedup over the glibc libm's double implementation of log2(x). _________________________________________________________________________________________________ * 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."