Added performance tips to README (#74)

intel · Nov 8, 2021 · a0b9029 · a0b9029
1 parent 52117a9
commit a0b9029
Showing 1 changed file with 23 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 [![Build and Test](https://github.com/intel/hexl/actions/workflows/github-ci.yml/badge.svg?branch=main)](https://github.com/intel/hexl/actions/workflows/github-ci.yml)
 
 # Intel Homomorphic Encryption Acceleration Library (HEXL)
-Intel:registered: HEXL is an open-source library which provides efficient implementations of integer arithmetic on Galois fields. Such arithmetic is prevalent in cryptography, particularly in homomorphic encryption (HE) schemes. Intel HEXL targets integer arithmetic with word-sized primes, typically 40-60 bits. Intel HEXL provides an API for 64-bit unsigned integers and targets Intel CPUs. For more details on Intel HEXL, see our [whitepaper](https://arxiv.org/abs/2103.16400.pdf)
+Intel:registered: HEXL is an open-source library which provides efficient implementations of integer arithmetic on Galois fields. Such arithmetic is prevalent in cryptography, particularly in homomorphic encryption (HE) schemes. Intel HEXL targets integer arithmetic with word-sized primes, typically 30-60 bits. Intel HEXL provides an API for 64-bit unsigned integers and targets Intel CPUs. For more details on Intel HEXL, see our [whitepaper](https://arxiv.org/abs/2103.16400.pdf). For tips on best performance, see [Performance](#performance)
 
 ## Contents
 - [Intel Homomorphic Encryption Acceleration Library (HEXL)](#intel-homomorphic-encryption-acceleration-library-hexl)
@@ -13,6 +13,7 @@ Intel:registered: HEXL is an open-source library which provides efficient implem
     - [Compiling Intel HEXL](#compiling-intel-hexl)
       - [Linux and Mac](#linux-and-mac)
       - [Windows](#windows)
+  - [Performance](#performance)
   - [Testing Intel HEXL](#testing-intel-hexl)
   - [Benchmarking Intel HEXL](#benchmarking-intel-hexl)
   - [Using Intel HEXL](#using-intel-hexl)
@@ -62,20 +63,19 @@ Intel HEXL requires the following dependencies:
 | CMake       | >= 3.5.1                                     |
 | Compiler    | gcc >= 7.0, clang++ >= 5.0, MSVC >= 2019     |
 
-For best performance, we recommend compiling with clang++-12. We also recommend using a processor with Intel AVX512DQ support, with best performance on processors supporting Intel AVX512-IFMA52. To determine if your processor supports AVX512-IFMA52, simply look for `HEXL_HAS_AVX512IFMA` during the configure step (see [Compiling Intel HEXL](#compiling-intel-hexl)).
 
 ### Compile-time options
 In addition to the standard CMake build options, Intel HEXL supports several compile-time flags to configure the build.
 For convenience, they are listed below:
 
-| CMake option                     | Values                 |                                                                          |
-| ---------------------------------| ---------------------- | ------------------------------------------------------------------------ |
-| HEXL_BENCHMARK                | ON / OFF (default ON)  | Set to ON to enable benchmark suite via Google benchmark                 |
-| HEXL_COVERAGE                 | ON / OFF (default OFF) | Set to ON to enable coverage report of unit-tests                        |
-| HEXL_DOCS                     | ON / OFF (default OFF) | Set to ON to enable building of documentation                            |
-| HEXL_SHARED_LIB               | ON / OFF (default OFF) | Set to ON to enable building shared library                              |
-| HEXL_TESTING                  | ON / OFF (default ON)  | Set to ON to enable building of unit-tests                               |
-| HEXL_TREAT_WARNING_AS_ERROR   | ON / OFF (default OFF) | Set to ON to treat all warnings as error                                 |
+| CMake option                  | Values   | Default |                                                             |
+| ------------------------------| ---------| --------| ----------------------------------------------------------- |
+| HEXL_BENCHMARK                | ON / OFF | ON      | Set to ON to enable benchmark suite via Google benchmark    |
+| HEXL_COVERAGE                 | ON / OFF | OFF     | Set to ON to enable coverage report of unit-tests           |
+| HEXL_SHARED_LIB               | ON / OFF | OFF     | Set to ON to enable building shared library                 |
+| HEXL_DOCS                     | ON / OFF | OFF     | Set to ON to enable building of documentation               |
+| HEXL_TESTING                  | ON / OFF | ON      | Set to ON to enable building of unit-tests                  |
+| HEXL_TREAT_WARNING_AS_ERROR   | ON / OFF | OFF     | Set to ON to treat all warnings as error                    |
 
 ### Compiling Intel HEXL
 To compile Intel HEXL from source code, first clone the repository and change directories to the where the source has been cloned.
@@ -130,15 +130,26 @@ cmake -S . -B build -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release -DCMAK
 ```
 before proceeding with the build and installation directions above.
 
+## Performance
+For best performance, we recommend using Intel HEXL on a Linux system with the clang++-12 compiler. We also recommend using a processor with Intel AVX512DQ support, with best performance on processors supporting Intel AVX512-IFMA52. To determine if your processor supports AVX512-IFMA52, simply look for `-- Setting HEXL_HAS_AVX512IFMA` printed during the configure step.
+
+See the below table for setting the modulus `q` for best performance.
+| Instruction Set  | Bound on modulus `q` |
+|------------------|----------------------|
+| AVX512-DQ        | `q < 2^30`           |
+| AVX512-IFMA52    | `q < 2^50`           |
+
+Some speedup is still expected for moduli `q > 2^30` using the AVX512-DQ instruction set.
+
 ## Testing Intel HEXL
-To run a set of unit tests via Googletest, configure and build Intel HEXL with `-DHEXL_TESTING=ON` (see [Compile-time options](#compile-time-options)).
+To run a set of unit tests via [Googletest](https://github.com/google/googletest), configure and build Intel HEXL with `-DHEXL_TESTING=ON` (see [Compile-time options](#compile-time-options)).
 Then, run
 ```bash
 cmake --build build --target unittest
 ```
 The unit-test executable itself is located at `build/test/unit-test` on Linux and Mac, and at `build\test\Release\unit-test.exe` or `build\test\Debug\unit-test.exe` on Windows.
 ## Benchmarking Intel HEXL
-To run a set of benchmarks via Google benchmark, configure and build Intel HEXL with `-DHEXL_BENCHMARK=ON` (see [Compile-time options](#compile-time-options)).
+To run a set of benchmarks via [Google benchmark](https://github.com/google/benchmark), configure and build Intel HEXL with `-DHEXL_BENCHMARK=ON` (see [Compile-time options](#compile-time-options)).
 Then, run
 ```bash
 cmake --build build --target bench