Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added performance tips to README #74

Merged
merged 1 commit into from
Oct 6, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down