Merge pull request #42 from yarongvili1/main

Add SWIFFT object APIs as v1.2.0

Dockerfile

@@ -17,7 +17,7 @@ RUN wget https://github.com/catchorg/Catch2/archive/${CATCH2_VERSION}.zip -O Cat
 RUN (CATCH2_VER=$(echo ${CATCH2_VERSION} | sed 's~^v~~'); ln -s Catch2-${CATCH2_VER} Catch2 && cd Catch2 && cmake -Bbuild -H. -DBUILD_TESTING=OFF && MAKEFLAGS=$(( $(nproc) + 1 )) cmake --build build/ --target install)
 
 # get and build LibSWIFFT source code
-ARG LIBSWIFFT_VERSION=v1.1.1
+ARG LIBSWIFFT_VERSION=v1.2.0
 ARG LIBSWIFFT_MCFLAGS=-march=native
 RUN wget https://github.com/gvilitechltd/LibSWIFFT/archive/${LIBSWIFFT_VERSION}.zip -O LibSWIFFT.zip && unzip LibSWIFFT.zip -d .
 RUN (LIBSWIFFT_VER=$(echo ${LIBSWIFFT_VERSION} | sed 's~^v~~'); ln -s LibSWIFFT-${LIBSWIFFT_VER} LibSWIFFT)

Dockerfile.compare-to-K2SN-MSS

@@ -17,7 +17,7 @@ RUN wget https://github.com/catchorg/Catch2/archive/${CATCH2_VERSION}.zip -O Cat
 RUN (CATCH2_VER=$(echo ${CATCH2_VERSION} | sed 's~^v~~'); ln -s Catch2-${CATCH2_VER} Catch2 && cd Catch2 && cmake -Bbuild -H. -DBUILD_TESTING=OFF && MAKEFLAGS=$(( $(nproc) + 1 )) cmake --build build/ --target install)
 
 # get and build LibSWIFFT source code
-ARG LIBSWIFFT_VERSION=v1.1.1
+ARG LIBSWIFFT_VERSION=v1.2.0
 ARG LIBSWIFFT_MCFLAGS=-march=native
 RUN wget https://github.com/gvilitechltd/LibSWIFFT/archive/${LIBSWIFFT_VERSION}.zip -O LibSWIFFT.zip && unzip LibSWIFFT.zip -d .
 RUN (LIBSWIFFT_VER=$(echo ${LIBSWIFFT_VERSION} | sed 's~^v~~'); ln -s LibSWIFFT-${LIBSWIFFT_VER} LibSWIFFT)

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "LibSWIFFT"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "1.1.1"
+PROJECT_NUMBER         = "1.2.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -136,6 +136,27 @@ SWIFFT_Compact(output.data, compact.data); /* optionally, compact the hash */
 
 Assignment and equality operators are available for `Swifft{Input,Output,Compact}` instances. Arithemtic and arithmetic-assignment operators, corresponding to the arithmetic functions in the C API, are available for `SwifftOutput` instances.
 
+SWIFFT Object APIs are available since `v1.2.0` of `LibSWIFFT` and are recommended:
+
+```C
+#include "libswifft/swifft_object.h"
+using namespace LibSwifft;
+/* initialize object APIs once, possibly inside a function: */
+swifft_object_t swifft;
+SWIFFT_InitObject(&swifft);
+/* later, inside a function: */
+SwifftInput input; /* auto-memory-aligned */
+SwifftOutput output; /* auto-memory-aligned */
+SwifftCompact compact; /* optional, auto-memory-aligned */
+/* arithmetic operations are available via swifft.arith, for example: */
+swifft.arith.SWIFFT_ConstSet(input.data, 1);
+/* hash operations are available via swifft.hash, for example: */
+swifft.hash.SWIFFT_Compute(input.data, output.data); /* compute the hash of the input into the output */
+swifft.hash.SWIFFT_Compact(output.data, compact.data); /* optionally, compact the hash */
+```
+
+Using the object APIs makes it easy to switch their implementation in the future. For the complete SWIFFT object APIs, refer to the documentation or to `src/swifft_object.inl`.
+
 ## Building LibSWIFFT
 
 Currently, LibSWIFFT is implemented to be built using GCC. It has been tested on Linux Ubuntu 20.04 LTS using
@@ -179,10 +200,10 @@ By default, the build will be for the native machine. To build with different ma
 cmake -DCMAKE_BUILD_TYPE=Release ../.. -DSWIFFT_MACHINE_COMPILE_FLAGS=-march=skylake
 ```
 
-To build with OpenMP, in particular for parallelizing multiple-block operations, add `-DSWIFFT_ENABLE_OPENMP=on` on the `cmake` command line, for example:
+To build with OpenMP, in particular for parallelizing multiple-block operations, add `-DSWIFFT_ENABLE_OPENMP=on` to the `cmake` command line, for example:
 
 ```sh
-cmake -DCMAKE_BUILD_TYPE=Release ../.. -DSWIFFT_ENABLE_OPENMP=On
+cmake -DCMAKE_BUILD_TYPE=Release -DSWIFFT_ENABLE_OPENMP=On ../..
 ```
 
 After building, run the tests-executable from the `build/release` directory:

RELEASE-CHECKLIST.md

@@ -27,6 +27,8 @@ Performance tests are executed using a release build:
     make
     ./test/swifft_catch "[swifftperf]"
 
+For an OpenMP release build, add the option `-DSWIFFT_ENABLE_OPENMP=On` to the above `cmake` command line.
+
 ## Running Coverage Tests
 
 Coverage tests are executed using a debug build:
@@ -60,4 +62,4 @@ The doxygen configuration was set up using these steps:
   - Set `EXTRACT_ALL` to `YES`
   - Set `EXCLUDE` to `build`
 
-The doxygen generation can be ran using `doxygen doxygen.conf`.
+The doxygen generation can be ran using `doxygen Doxyfile`.

docs/conf.py

@@ -37,7 +37,7 @@
 author = 'Gvili Tech Ltd'
 
 # The full version, including alpha/beta/rc tags
-release = 'v1.1.1'
+release = 'v1.2.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -8,7 +8,7 @@
 
 .. image:: ../assets/LibSWIFFT-logo.png
 
-`LibSWIFFT v1.1.1 <https://doi.org/10.21105/joss.03040>`_ |josspaper|
+`LibSWIFFT v1.2.0 <https://doi.org/10.21105/joss.03040>`_ |josspaper|
 
 .. |josspaper| image:: https://joss.theoj.org/papers/10.21105/joss.03040/status.svg
    :target: https://doi.org/10.21105/joss.03040
@@ -63,7 +63,7 @@ sets to take advantage of available hardware acceleration.
 Production-Ready
 ----------------
 
-LibSWIFFT v1.1.1 ships with over 30 test-cases including millions of checks that
+LibSWIFFT v1.2.0 ships with over 30 test-cases including millions of checks that
 provide excellent coverage of the library's code and the mathematical properties
 of the SWIFFT function it implements:
 
@@ -72,7 +72,7 @@ of the SWIFFT function it implements:
     $ ./test/swifft_catch
 
     ===============================================================================
-    All tests passed (6648383 assertions in 32 test cases)
+    All tests passed (6648384 assertions in 32 test cases)
 
 LibSWIFFT also ships with detailed documentation, including references for its
 :libswifft:`C API <swifft.h>` and :libswifft:`C++ API <LibSwifft>`. It has a
@@ -143,6 +143,27 @@ this:
     SWIFFT_Compute(input.data, sign.data, output.data); /* compute the hash of the signed input into the output */
     SWIFFT_Compact(output.data, compact.data);
 
+For future flexibility in implementation, it is recommended to invoke SWIFFT
+functions via the :libswifft:`SWIFFT object APIs <swifft_object.h>` (since
+`v1.2.0`):
+
+.. code-block:: cpp
+
+    #include "libswifft/swifft_object.h"
+    using namespace LibSwifft;
+    /* initialize object APIs once, possibly inside a function: */
+    swifft_object_t swifft;
+    SWIFFT_InitObject(&swifft);
+    /* later, inside a function: */
+    SwifftInput input; /* auto-memory-aligned */
+    SwifftOutput output; /* auto-memory-aligned */
+    SwifftCompact compact; /* optional, auto-memory-aligned */
+    /* arithmetic operations are available via swifft.arith, for example: */
+    swifft.arith.SWIFFT_ConstSet(input.data, 1);
+    /* hash operations are available via swifft.hash, for example: */
+    swifft.hash.SWIFFT_Compute(input.data, output.data); /* compute the hash of the input into the output */
+    swifft.hash.SWIFFT_Compact(output.data, compact.data); /* optionally, compact the hash */
+
 Rationale
 =========
 

docs/user-guide.rst

@@ -12,11 +12,11 @@ The code repository can be cloned using `git <https://git-scm.com>`_:
     git clone https://github.com/gvilitechltd/LibSWIFFT
     cd LibSWIFFT
 
-To switch to a specific version of LibSWIFFT, such as `v1.1.1`, use:
+To switch to a specific version of LibSWIFFT, such as `v1.2.0`, use:
 
 .. code-block:: sh
 
-    git checkout v1.1.1
+    git checkout v1.2.0
 
 As an alternative to getting the repository, a specific version of LibSWIFFT can
 be obtained from `GitHub <https://github.com/gvilitechltd/LibSWIFFT>`_ by
@@ -25,9 +25,9 @@ Then, unpack the archive and change into the unpacked directory, e.g.:
 
 .. code-block:: sh
 
-    wget https://github.com/gvilitechltd/LibSWIFFT/archive/v1.1.1.zip
-    unzip v1.1.1.zip
-    cd LibSWIFFT-1.1.1
+    wget https://github.com/gvilitechltd/LibSWIFFT/archive/v1.2.0.zip
+    unzip v1.2.0.zip
+    cd LibSWIFFT-1.2.0
 
 Building LibSWIFFT
 ------------------
@@ -73,11 +73,11 @@ By default, the build will be for the native machine. To build with different ma
 
     cmake -DCMAKE_BUILD_TYPE=Release ../.. -DSWIFFT_MACHINE_COMPILE_FLAGS=-march=skylake
 
-To build with OpenMP, in particular for parallelizing multiple-block operations, add `-DSWIFFT_ENABLE_OPENMP=on` on the `cmake` command line, for example:
+To build with OpenMP, in particular for parallelizing multiple-block operations, add `-DSWIFFT_ENABLE_OPENMP=on` to the `cmake` command line, for example:
 
 .. code-block:: sh
 
-    cmake -DCMAKE_BUILD_TYPE=Release ../.. -DSWIFFT_ENABLE_OPENMP=On
+    cmake -DCMAKE_BUILD_TYPE=Release -DSWIFFT_ENABLE_OPENMP=On ../..
 
 After building, run the tests-executable from the `build/release` directory:
 
@@ -139,7 +139,6 @@ Typical code using the C API:
 
 Buffers must be memory-aligned in order to avoid a segmentation fault when passed to `LibSWIFFT` functions: statically allocated buffers should be aligned using `SWIFFT_ALIGN`, and dynamically allocated buffers should use an alignment of `SWIFFT_ALIGNMENT`, e.g., via `aligned_alloc` function in `stdlib.h`. The transformation functions :libswifft:`SWIFFT_ComputeMultiple`, :libswifft:`SWIFFT_ComputeMultipleSigned` and :libswifft:`SWIFFT_CompactMultiple` apply operations to multiple blocks. The arithmetic functions :libswifft:`SWIFFT_ConstSet`, :libswifft:`SWIFFT_ConstAdd`, :libswifft:`SWIFFT_ConstSub`, :libswifft:`SWIFFT_ConstMul`, :libswifft:`SWIFFT_Set`, :libswifft:`SWIFFT_Add`, :libswifft:`SWIFFT_Sub`, :libswifft:`SWIFFT_Mul` provide vectorized and homomorphic operations on an output block, while :libswifft:`SWIFFT_ConstSetMultiple`, :libswifft:`SWIFFT_ConstAddMultiple`, :libswifft:`SWIFFT_ConstSubMultiple`, :libswifft:`SWIFFT_ConstMulMultiple`, :libswifft:`SWIFFT_SetMultiple`, :libswifft:`SWIFFT_AddMultiple`, :libswifft:`SWIFFT_SubMultiple`, :libswifft:`SWIFFT_Mul` provide corresponding operations to multiple blocks.
 
-
 Typical code using the C++ API:
 
 .. code-block:: cpp
@@ -160,3 +159,22 @@ Typical code using the C++ API:
 
 Assignment and equality operators are available for :libswifft:`SwifftInput`, :libswifft:`SwifftOutput`, :libswifft:`SwifftCompact` instances. Arithemtic and arithmetic-assignment operators, corresponding to the arithmetic functions in the C API, are available for :libswifft:`SwifftOutput` instances.
 
+Typical code using the recommended SWIFFT object APIs (since `v1.2.0`):
+
+.. code-block:: cpp
+
+    #include "libswifft/swifft_object.h"
+    using namespace LibSwifft;
+    /* initialize object APIs once, possibly inside a function: */
+    swifft_object_t swifft;
+    SWIFFT_InitObject(&swifft);
+    /* later, inside a function: */
+    SwifftInput input; /* auto-memory-aligned */
+    SwifftOutput output; /* auto-memory-aligned */
+    SwifftCompact compact; /* optional, auto-memory-aligned */
+    /* arithmetic operations are available via swifft.arith, for example: */
+    swifft.arith.SWIFFT_ConstSet(input.data, 1);
+    /* hash operations are available via swifft.hash, for example: */
+    swifft.hash.SWIFFT_Compute(input.data, output.data); /* compute the hash of the input into the output */
+    swifft.hash.SWIFFT_Compact(output.data, compact.data); /* optionally, compact the hash */
+