Experimental HEXL Acceleration Integration

Experimental HEXL Acceleration Integration
Update build to use NTL 11.5.1 and GMP 6.2.1

Co-authored-by: @hamishun 
Co-authored-by: @jlhcrawford 
Co-authored-by: @faberga 
Co-authored-by: @fboemer

Author: faberga

CHANGES.md

@@ -1,6 +1,19 @@
 Release Changes
 ===============
 
+HElib 2.2.0, September 2021
+=========================
+(tagged as v2.2.0)
+
+* Intel HEXL integration (experimental)
+  * HEXL NTT acceleration for m as a power of 2
+  * HEXL acceleration to fundamental ciphertext operations
+  * Documentation update
+* Update NTL dependency to version 11.5.1
+* Update GMP dependency to version 6.2.1
+* Update to benchmarks
+* Bug fixes
+
 HElib 2.1.0, March 2021
 =========================
 (tagged as v2.1.0)

CMakeLists.txt

@@ -10,7 +10,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License. See accompanying LICENSE file.
 
-cmake_minimum_required(VERSION 3.10.2 FATAL_ERROR)
+# Enforce CMake v3.20 on MacOS else set minimum to v3.16
+if (APPLE)
+  cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
+else ()
+  cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
+endif ()
 
 project(helib_superbuild LANGUAGES C CXX)
 
@@ -67,9 +72,9 @@ set(HELIB_DEPENDENCIES_DIR "${PROJECT_SOURCE_DIR}/dependencies")
 set(HELIB_TEST_BIN_DIR "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}")
 
 # GMP minimal version to be used if not PACKAGE_BUILD
-set(GMP_MINIMAL_VERSION "6.0.0")
+set(GMP_MINIMAL_VERSION "6.2.0")
 # NTL minimal version to be used if NOT PACKAGE_BUILD
-set(NTL_MINIMAL_VERSION "11.0.0")
+set(NTL_MINIMAL_VERSION "11.4.3")
 
 # The -isysroot flag needs set.
 if ((APPLE OR (CMAKE_CXX_PLATFORM_ID STREQUAL "Darwin")) AND
@@ -108,6 +113,17 @@ if (NOT TARGET_ARCHITECTURE)
       FORCE)
 endif (NOT TARGET_ARCHITECTURE)
 
+set(HELIB_SP_NBITS "0" 
+    CACHE 
+    STRING "Override the bitsize for the ciphertext primes used")
+if (NOT HELIB_SP_NBITS EQUAL 0)
+  # Now check within bounds. NB. zero is special value to not override
+  if (HELIB_SP_NBITS LESS 1 OR HELIB_SP_NBITS GREATER 64)
+    message(FATAL_ERROR "HELIB_SP_NBITS must be in range [1, 64].")
+  endif()
+  add_compile_definitions(HELIB_SP_NBITS=${HELIB_SP_NBITS})
+endif()
+
 # Path containing FindGMP.cmake and FindNTL.cmake
 list(APPEND CMAKE_MODULE_PATH "${HELIB_CMAKE_EXTRA_DIR}")
 
@@ -125,6 +141,7 @@ option(HELIB_DEBUG
        "Build with HELIB_DEBUG (enables extra debugging info, but needs to be initialized)"
        OFF)
 option(ENABLE_TEST "Enable tests" OFF)
+option(USE_INTEL_HEXL "Use Intel HEXL library" OFF)
 option(PEDANTIC_BUILD "Use -Wall -Wpedantic -Wextra -Werror during build" ON)
 
 # Add properties dependent to PACKAGE_BUILD
@@ -176,6 +193,43 @@ if (ENABLE_THREADS AND Threads_NOTFOUND)
   message(FATAL_ERROR "Cannot find pthreads (ENABLE_THREADS is ON).")
 endif ()
 
+# Build optional Intel HEXL library
+if(USE_INTEL_HEXL)
+  # HEXL currently only supported using Library Build
+  if(PACKAGE_BUILD)
+    message(FATAL_ERROR "Intel HEXL currently not supported with Package "
+      "Build. Please use the Library Build when enabling Intel HEXL.")
+  endif(PACKAGE_BUILD)
+
+  if(HEXL_DIR)
+    set(HEXL_DIR
+        ""
+        CACHE
+        STRING "Set location of HEXL cmake data for linking."
+        )
+    set(INIT_HEXL_DIR ${HEXL_DIR})
+  endif()
+
+  # Set minimum version of HEXL
+  set(HEXL_MIN_VERSION 1.2.1)
+
+  find_package(HEXL HINTS ${HEXL_DIR} REQUIRED)
+
+  # Check the version found is greater than the minimum
+  if(HEXL_MIN_VERSION GREATER HEXL_VERSION)
+    message(FATAL_ERROR "Minimum Intel HEXL version required is ${HEXL_MIN_VERSION}, found ${HEXL_VERSION}")
+  else()
+    message("-- Intel HEXL Version: ${HEXL_VERSION} found (minimum required is ${HEXL_MIN_VERSION})")
+  endif()
+
+  if(INIT_HEXL_DIR AND NOT INIT_HEXL_DIR STREQUAL HEXL_DIR)
+    message(WARNING "HEXL location provided '${INIT_HEXL_DIR}' \
+            does not equal chosen '${HEXL_DIR}'.")
+  endif()
+  include_directories(${HEXL_INCLUDE_DIRS})
+  add_compile_definitions(USE_INTEL_HEXL)
+endif(USE_INTEL_HEXL)
+
 # NOTE: Consider reconfiguring everything when PACKAGE_BUILD changes value.
 # Options from the previous value will remain otherwise.
 # Set up extra properties depending on the value of PACKAGE_BUILD
@@ -184,7 +238,7 @@ if (PACKAGE_BUILD)
   # GMP version to be used (and eventually downloaded) if PACKAGE_BUILD
   set(FETCHED_GMP_VERSION "6.2.1")
   # NTL version to be used (and eventually downloaded) if PACKAGE_BUILD
-  set(FETCHED_NTL_VERSION "11.4.3")
+  set(FETCHED_NTL_VERSION "11.5.1")
   # Setting up default compilation output directory
   if (NOT PACKAGE_DIR)
     set(PACKAGE_DIR "helib_pack")
@@ -334,6 +388,7 @@ if (PACKAGE_BUILD)
                -DFETCH_GMP=${FETCH_GMP}
                -DENABLE_TEST=${ENABLE_TEST}
                -DHELIB_DEBUG=${HELIB_DEBUG}
+               -DUSE_INTEL_HEXL=${USE_INTEL_HEXL}
                -DHELIB_PROJECT_ROOT_DIR=${HELIB_PROJECT_ROOT_DIR}
                -DHELIB_CMAKE_EXTRA_DIR=${HELIB_CMAKE_EXTRA_DIR}
                -DHELIB_INCLUDE_DIR=${HELIB_INCLUDE_DIR}

Dockerfile

@@ -1,38 +1,45 @@
 # Building and installing HElib
 
-The HElib build, install, and regression tests suite have been built and tested
-on Ubuntu 18.04, Ubuntu 20.04, Fedora 32, Fedora 33, CentOS 7.8, CentOS 8.2,
-macOS Mojave >=10.14.6, and macOS Catalina >=10.15.7.
+The current HElib build, install, and regression tests suite have been built
+and tested on Ubuntu 20.04 and macOS Catalina >=10.15.7. Previous versions 
+have also included Ubuntu 18.04, Fedora 33, CentOS 8.2, macOS Mojave >=10.14.6.
 
 There are two different ways to build and install HElib. The first one will
 automatically download and build the GMP and NTL dependencies and pack the
 libraries in a relocatable folder. The second way, instead, requires the
 dependencies to be installed by you and available in the system.
 
-**Please read these instructions in full to better choose the type of build that
- is better for you.**
+This release of HElib has experimental support for the Intel® [HEXL](https://github.com/intel/hexl) 
+acceleration library for homomorphic encryption that exploits Intel® Advanced Vector Extensions 512. 
+Instructions to enable and link to HEXL are given 
+[below](#enabling-and-linking-to-intel-hexl).
+
+```diff
+- Please read these instructions in full to better choose the type of build that is best for you.
+```
 
 ## General prerequisites
 
-- GNU make >= 3.82
 - pthreads
-- git >= 1.8.3 (required to build and run the HElib test suite)
+- git >= 2.27 (required to build and run the HElib test suite)
 
-**Linux environment:**
+**Default Linux environment:**
 
-- g++ >= 7.3.1
-- cmake >= 3.10.2
+- GNU make >= 4.2
+- g++ >= 9.3.0  (recommended g++ 10.3.0)
+- cmake >= 3.16
 
 **macOS environment:**
 
-- Apple clang >= 11.0.0 (available with the latest Xcode for the tested versions of macOS)
+- Apple clang >= 12.0.0 (available with the latest Xcode for the tested versions of macOS)
 - Xcode Command Line Tools (can be installed with the command `xcode-select
-  --install` in a teminal)
-- cmake >= 3.17.3 (available from [CMake](https://cmake.org/) or [MacPorts
+  --install` in a terminal)
+- cmake >= 3.20 (available from [CMake](https://cmake.org/) or [MacPorts
   Project](https://www.macports.org/) and [Homebrew](https://brew.sh/) as
   packages)
+- GNU make >= 3.81
 
-**For development:**
+**For HElib development:**
 
 - clang-format >= 9.0.0 (available with your linux distribution and for macOS
   from [MacPorts Project](https://www.macports.org/) and
@@ -108,7 +115,7 @@ some other system-wide path, step 5 may require `sudo` privileges.
 This option involves building HElib on its own, linking against pre-existing
 dependencies (NTL and GMP) on the system.  In this way, the HElib library can be
 moved around, but its dependencies (NTL and GMP) cannot, as they are absolute
-paths.  For this option, you must build GMP >=6.0.0 and NTL >=11.4.3 yourself.
+paths.  For this option, you must build GMP >=6.2.1 and NTL >=11.5.1 yourself.
 For details on how to do this, please see the section on building dependencies
 later.  It is assumed throughout this installation option that the environment
 variables `$GMPDIR` and `$NTLDIR` are set to point to the installation
@@ -170,8 +177,8 @@ Many distributions come with GMP pre-installed. If not, you can install GMP as
 follows.
 
 1. Download GMP from [http://www.gmplib.org](http://www.gmplib.org) -- make sure
-   that you get GMP >=6.0.0 (current version is 6.2.0).
-2. Decompress and cd into the gmp directory (e.g., `gmp-6.2.0`).
+   that you get GMP >=6.2.0 (current version is 6.2.1).
+2. Decompress and cd into the gmp directory (e.g., `gmp-6.2.1`).
 3. GMP is compiled in the standard unix way:
 
 ```bash
@@ -189,9 +196,9 @@ step 3.
 
 You can install NTL as follows:
 
-1. Download NTL >=11.4.3 (current version is 11.4.3) from
-   [http://www.shoup.net/ntl/download.html](http://www.shoup.net/ntl/download.html)
-2. Decompress and cd into the directory, e.g., `ntl-11.4.3/src`
+1. Download NTL >=11.5.1 from
+   [https://libntl.org/download.html](https://libntl.org/download.html)
+2. Decompress and cd into the directory, e.g., `ntl-11.5.1/src`
 3. NTL is configured, built and installed in the standard Unix way (but remember
    to specify the following flags to `configure`):
 
@@ -209,6 +216,42 @@ step 3.
 **NOTE**: if linking against a non-system GMP, pass `GMP_PREFIX=<path/to/gmp>`
 to the `./configure` step.
 
+## Enabling and linking to Intel® HEXL
+**NOTE:** HElib with HEXL acceleration is only supported on the processors with AVX512DQ and 
+AVX512-IFMA such as the 3rd generation Intel® Xeon® or the 11th generation Intel® Core®
+
+**NOTE:** It is currently only possible to use HEXL with HElib when using the
+library build and when building HElib as a static library. i.e.
+`-DPACKAGE_BUILD=OFF` and `-DBUILD_SHARED=OFF`.
+
+First you must download and build HEXL from source.  Currently, HElib only
+works with HEXL version >= 1.2.1 Using git this would be
+
+```bash
+git clone https://github.com/intel/hexl --branch 1.2.1
+```
+Follow the instructions for HEXL installation in the README.md for all
+available options.  Note previous versions of HEXL requires the deprecated
+`-DENABLE_EXPORT=ON` otherwise the cmake metadata for linking a cmake project
+is not created. Modern versions do not have this flag and the metadata is
+created by default.  For a quick start most people will want,
+
+```bash
+cd hexl
+cmake -S . -B build/ [-DCMAKE_INSTALL_PREFIX=<install-location-for-HEXL>/lib/cmake/hexl-1.2.1] 
+cmake --build build -j [<parallel-jobs>]
+cmake --install build
+```
+If you do not provide an optional install location for HEXL the default is
+`/usr/local`.
+
+To enable and link HEXL in HElib, you must configure cmake for HElib with
+`-DUSE_INTEL_HEXL=ON`. If HEXL is not in the default system location or you
+wish to use another installation tell HElib where to find it using
+`-DHEXL_DIR=<install-location-for-hexl>`.
+There is no requirement to provide any HElib subprojects with the location of
+HEXL.
+
 ## HElib build options
 
 ### Generic options
@@ -248,6 +291,8 @@ to the `./configure` step.
 
 - `GMP_DIR`: Prefix of the GMP library.
 - `NTL_DIR`: Prefix of the NTL library.
+- `USE_INTEL_HEXL`: Enable the Intel HEXL library.
+- `HEXL_DIR`: Prefix of the Intel HEXL library.
 
 # Using HElib in a project
 

INSTALL.md

@@ -1 +1 @@
-2.1.0
+2.2.0

VERSION

@@ -48,7 +48,7 @@ set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
     "Debug" "RelWithDebInfo" "Release" "MinSizeRel")
 
 # STRINGS avoids having the 2 newline characters at the end of the string.
-# Alternatively it's possible to use file(READ ...) and then
+# Alternatively it is possible to use file(READ ...) and then
 # string(REGEX REPLACE "\n$" "" HELIB_VERSION "${HELIB_VERSION}")
 file(STRINGS "../VERSION" HELIB_VERSION)
 
@@ -61,7 +61,8 @@ set(TRGTS bgv_basic
           bgv_thinboot
           bgv_fatboot
           ckks_basic
-          IO)
+          IO
+          fft_bench)
 
 # Sources derived from their targets.
 set(SRCS "")

benchmarks/CMakeLists.txt

@@ -9,10 +9,10 @@ Build and install HElib as described in [INSTALL.md](../INSTALL.md).
 ### Build and install google benchmark
 
 Download the library https://github.com/google/benchmark from github, build and
-then install it.
+then install it. We tested with Google Benchmark v1.5.6
 
 ```
-git clone https://github.com/google/benchmark
+git clone https://github.com/google/benchmark.git -b v1.5.6
 cd benchmark
 mkdir build
 cd build

benchmarks/README.md

@@ -0,0 +1,19 @@
+/* Copyright (C) 2021 Intel Corporation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef HELIB_BENCH_COMMON_H
+#define HELIB_BENCH_COMMON_H
+
+#define HE_BENCH_CAPTURE(adding_two_ciphertexts, tiny_params, fn)              \
+  BENCHMARK_CAPTURE(adding_two_ciphertexts, tiny_params, fn(tiny_params))
+
+#endif // HELIB_BENCH_COMMON_H