add two_pow member function to MontgomeryForm, and improve asm

Author: hurchalla

CMakeLists.txt

@@ -8,7 +8,8 @@ if(TARGET hurchalla_modular_arithmetic)
     return()
 endif()
 
-cmake_minimum_required(VERSION 3.14)
+# later versions are probably fine, but are untested
+cmake_minimum_required(VERSION 3.14...4.03)
 
 project(hurchalla_modular_arithmetic VERSION 1.0.0 LANGUAGES CXX)
 
@@ -19,30 +20,18 @@ if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
 endif()
 
 
-# TODO: this section seems slightly messy for detecting/setting up testing
-# --------------------
-option(TEST_HURCHALLA_LIBS
-       "Build the tests for all Hurchalla library projects."
-       OFF)
-
 # if this is the top level CMakeLists.txt, add testing options, and enable
 # testing when testing options have been set to ON.
 if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
     option(TEST_HURCHALLA_MODULAR_ARITHMETIC
         "Build the tests for the Hurchalla modular arithmetic library project."
         ON)
-    if(TEST_HURCHALLA_MODULAR_ARITHMETIC OR TEST_HURCHALLA_LIBS)
+    option(FORCE_TEST_HURCHALLA_CPP11_STANDARD
+       "If testing this library, ensure we build googletest and tests using -std=c++11")
+    if(TEST_HURCHALLA_MODULAR_ARITHMETIC)
         enable_testing()
         # include(CTest)
     endif()
-elseif(TEST_HURCHALLA_LIBS)
-    # If TEST_HURCHALLA_LIBS is set to ON, enable_testing() should have been
-    # called either directly or indirectly by the top level project. (Note that
-    # if a project calls include(CTest), the included CTest.cmake defines a
-    # BUILT_TESTING option and calls enable_testing if BUILD_TESTING is ON.)
-    if (NOT CMAKE_TESTING_ENABLED)
-        message(FATAL_ERROR "Fatal error: TEST_HURCHALLA_LIBS was set, but enable_testing() was never called")
-    endif()
 endif()
 
 
@@ -92,9 +81,7 @@ target_include_directories(hurchalla_modular_arithmetic
 
 # if this is the top level CMakeLists.txt
 if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
-    if(TEST_HURCHALLA_MODULAR_ARITHMETIC OR TEST_HURCHALLA_LIBS)
+    if(TEST_HURCHALLA_MODULAR_ARITHMETIC)
         add_subdirectory(test)
     endif()
-elseif(TEST_HURCHALLA_LIBS)
-    add_subdirectory(test)
 endif()

README.md

@@ -1,12 +1,22 @@
-# The "Clockwork" Modular Arithmetic Library
+# The Clockwork Modular Arithmetic library
 
 ![Alt text](images/clockxtrasmall_border2.jpg?raw=true "Clock Gears, photo by Krzysztof Golik, licensed CC BY-SA 4.0")
 
-Clockwork is a high performance, easy to use Modular Arithmetic library for C++ provided as a "header-only" library, for up to 128 bit integer types, with extensive support for Montgomery arithmetic.  If you want or need Montgomery arithmetic in this range, or general modular arithmetic functions, Clockwork is almost certainly the fastest and easiest library you could use.  For best performance make sure you define the standard C++ macro NDEBUG.
+Clockwork is a high performance, easy to use Modular Arithmetic library for C++ provided as a "header-only" library, supporting up to 128 bit integer types, and providing extensive support for Montgomery arithmetic.  If you want or need Montgomery arithmetic in this range, or general modular arithmetic functions, Clockwork is almost certainly the fastest and easiest library you could use.  For best performance make sure you define the standard C++ macro NDEBUG.  
+
+The library requires only C++11, and works with all higher versions of the C++ standard.
 
 ## Design goals
 
-Clockwork is designed to be a flexible and bulletproof library with the best performance achievable for modular arithmetic of native (on the CPU) integer types.  For integer types that are double the native bit width (e.g. 128 bit), performance should still be close to ideal, though not as completely optimized as for native types.  Larger than 128 bit types are permissible by [specialization](https://github.com/hurchalla/util/blob/master/include/hurchalla/util/traits/ut_numeric_limits.h); however a library like [GMP](https://gmplib.org/) is likely to be a better choice for such sizes.
+Clockwork is designed to be a flexible and bulletproof library with the best performance achievable for modular arithmetic using standard C++ language integer types (e.g. uint32_t or uint64_t) and the language extension types \_\_uint128_t and \_\_int128_t.  Larger than 128 bit types are permissible by [specialization](https://github.com/hurchalla/util/blob/master/include/hurchalla/util/traits/ut_numeric_limits.h); however a library like [GMP](https://gmplib.org/) is likely to be a better choice for such sizes.
+
+## Requirements
+
+The Clockwork library requires only compiler support for C++11, which is essentially supported universally at this point.
+
+For good performance you *must* ensure that the standard macro NDEBUG (see <cassert>) is defined when compiling.  
+
+Compilers that are confirmed to build this library without warnings or errors on Ubuntu linux (x64) include clang6, clang10, clang18, gcc7, gcc10, gcc13, and intel compiler 19.  On Windows, Microsoft Visual C++ 2017, 2019, 2022 are all confirmed to build the library without warnings or errors.  On MacOS, clang16 and gcc14 are confirmed to build without warnings or errors.  The library is intended for use on all architectures (e.g. x86/64, ARM, RISC-V), but has so far been tested only with x86, x64 (Windows and Ubuntu), and ARM64 (MacOS).
 
 ## Status
 
@@ -36,7 +46,7 @@ It may help to see a simple [example project with CMake](examples/example_with_c
 
 ### Without CMake
 
-If you're not using CMake for your project, you'll need to install/copy Clockwork's modular arithmetic headers and dependencies to some directory in order to use them.  To do this, first clone this git repository onto your system.  You'll need CMake on your system (at least temporarily), so install CMake if you don't have it.  Then from your shell run the following commands:  
+If you're not using CMake for your project, you'll need to install Clockwork's modular arithmetic headers and its dependencies to some directory in order to use them.  To do this, first clone this git repository onto your system.  You'll need to have CMake (at least temporarily) on your system, so install CMake if you don't have it.  Then from your shell run the following commands:  
 
 >cd *path_of_the_cloned_modular_arithmetic_repository*  
 >mkdir tmp  
@@ -63,9 +73,9 @@ From the modular_arithmetic group, the files *absolute_value_difference.h*, *mod
 *hurchalla::modular_addition_prereduced_inputs(T a, T b, T modulus)*.  Returns (a+b)%modulus, performed as if a and b have infinite precision and thus as if (a+b) is never subject to integer overflow.  
 *hurchalla::modular_multiplication_prereduced_inputs(T a, T b, T modulus)*.   Returns (a\*b)%modulus, performed as if a and b have infinite precision.  
 *hurchalla::modular_multiplicative_inverse(T a, T modulus)*.  Returns the multiplicative inverse of a if it exists, and otherwise returns 0.  
-*hurchalla::modular_pow(T base, T exponent, T modulus)*.  Returns the modular exponentiation of base^exponent (mod modulus).  
+*hurchalla::modular_pow(T base, T exponent, T modulus)*.  Returns the modular exponentiation of base to the exponent (mod modulus).  
 
-From the montgomery_arithmetic group, the file *MontgomeryForm.h* provides the easy to use (and zero cost abstraction) class *hurchalla::MontgomeryForm*, which has member functions for effortlessly performing operations in the Montgomery domain.  These operations include converting to/from Montgomery domain, add, subtract, multiply, square, [fused-multiply-add/sub](https://jeffhurchalla.com/2022/05/01/the-montgomery-multiply-accumulate), pow, gcd, and more.  For improved performance in some situations, the file *montgomery_form_aliases.h* provides simple aliases for faster (with limitations on allowed modulus) instantiations of the class MontgomeryForm.
+From the montgomery_arithmetic group, the file *MontgomeryForm.h* provides the easy to use (and zero cost abstraction) class *hurchalla::MontgomeryForm*, which has simple member functions for performing operations in the Montgomery domain.  These operations include converting to/from Montgomery domain, add, subtract, multiply, square, [fused-multiply-add/sub](https://jeffhurchalla.com/2022/05/01/the-montgomery-multiply-accumulate), pow, gcd, and more.  For improved performance, if you can guarantee your modulus will be under half or under a quarter of the maximum value of your integer type T, the file *montgomery_form_aliases.h* provides aliases of the class MontgomeryForm which typically run ~5-10% faster.
 
 For an easy demonstration of MontgomeryForm, you can see one of the [examples](examples/example_without_cmake).
 

build_tests.sh

@@ -526,12 +526,29 @@ exit_on_failure () {
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 
 
+# We don't usually want to force c++11 standard, since that requires that we use
+# an older version of googletest that was the final version to support C++11.
+# That googletest version's CMakeLists.txt isn't updated for more recent CMake
+# versions, and so we have to work around CMake deprecation warnings and errors
+# (you can see how this is done in FetchGoogleTest.cmake), which isn't a good
+# normal practice to do.  However, it is good to prove that our library is C++11
+# compatible from time to time.  To force c+11, change the line below to true.
+force_cpp11=false
+
+
+if [ "$force_cpp11" = true ]; then
+  force_cpp11_testing="ON"
+else
+  force_cpp11_testing="OFF"
+fi
+
 
 if [ "${mode,,}" = "release" ]; then
     pushd script_dir > /dev/null 2>&1
     build_dir=build/release_$compiler_name$compiler_version
     mkdir -p $build_dir
-    cmake -S. -B./$build_dir -DTEST_HURCHALLA_LIBS=ON \
+    cmake -S. -B./$build_dir -DTEST_HURCHALLA_MODULAR_ARITHMETIC=ON \
+            -DFORCE_TEST_HURCHALLA_CPP11_STANDARD=$force_cpp11_testing \
             -DCMAKE_BUILD_TYPE=Release \
             -DCMAKE_CXX_FLAGS="$cpp_standard  $cpp_stdlib \
             $test_avoid_cselect  $test_heavyweight \
@@ -546,7 +563,8 @@ elif [ "${mode,,}" = "debug" ]; then
     pushd script_dir > /dev/null 2>&1
     build_dir=build/debug_$compiler_name$compiler_version
     mkdir -p $build_dir
-    cmake -S. -B./$build_dir -DTEST_HURCHALLA_LIBS=ON \
+    cmake -S. -B./$build_dir -DTEST_HURCHALLA_MODULAR_ARITHMETIC=ON \
+            -DFORCE_TEST_HURCHALLA_CPP11_STANDARD=$force_cpp11_testing \
             -DCMAKE_BUILD_TYPE=Debug \
             -DCMAKE_EXE_LINKER_FLAGS="$clang_ubsan_link_flags" \
             -DCMAKE_CXX_FLAGS="$cpp_standard  $cpp_stdlib \
@@ -566,17 +584,11 @@ fi
 
 
 # -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON
-# cmake  -S.  -B./build_tmp  -DCMAKE_CXX_FLAGS="-std=c++17"  -DTEST_HURCHALLA_LIBS=ON  -DCMAKE_BUILD_TYPE=Debug  -DCMAKE_CXX_COMPILER=icpc  -DCMAKE_C_COMPILER=icc
+# cmake  -S.  -B./build_tmp  -DCMAKE_CXX_FLAGS="-std=c++17"  -DTEST_HURCHALLA_MODULAR_ARITHMETIC=ON  -DCMAKE_BUILD_TYPE=Debug  -DCMAKE_CXX_COMPILER=icpc  -DCMAKE_C_COMPILER=icc
 # cmake --build ./build_tmp --config Debug
 
 
 if [ "$run_tests" = true ]; then
-#  ./$build_dir/test_ndebug_programming_by_contract --gtest_break_on_failure
-#  exit_on_failure
-#  ./$build_dir/test_programming_by_contract --gtest_break_on_failure
-#  exit_on_failure
-  ./$build_dir/test_hurchalla_util --gtest_break_on_failure
-  exit_on_failure
   ./$build_dir/test_hurchalla_modular_arithmetic --gtest_break_on_failure
   exit_on_failure
 fi

modular_arithmetic/CMakeLists.txt

@@ -8,7 +8,8 @@ if(TARGET hurchalla_basic_modular_arithmetic)
     return()
 endif()
 
-cmake_minimum_required(VERSION 3.14)
+# later versions are probably fine, but are untested
+cmake_minimum_required(VERSION 3.14...4.03)
 
 project(hurchalla_basic_modular_arithmetic VERSION 1.0.0 LANGUAGES CXX)
 
@@ -73,7 +74,7 @@ include(FetchContent)
 FetchContent_Declare(
     hurchalla_util
     GIT_REPOSITORY https://github.com/hurchalla/util.git
-    GIT_TAG        master
+    GIT_TAG        9163344ee69f21a21cb8928dd30fc2ff15e94f0c
 )
 FetchContent_MakeAvailable(hurchalla_util)
 

modular_arithmetic/include/hurchalla/modular_arithmetic/detail/impl_modular_pow.h

@@ -22,11 +22,13 @@ namespace hurchalla { namespace detail {
 // For details, see http://en.wikipedia.org/wiki/Modular_exponentiation
 // note: uses a static member function to disallow ADL.
 struct impl_modular_pow {
-  template <typename T>
-  HURCHALLA_FORCE_INLINE static T call(T base, T exponent, T modulus)
+  template <typename T, typename U>
+  HURCHALLA_FORCE_INLINE static T call(T base, U exponent, T modulus)
   {
     static_assert(ut_numeric_limits<T>::is_integer, "");
     static_assert(!(ut_numeric_limits<T>::is_signed), "");
+    static_assert(ut_numeric_limits<U>::is_integer, "");
+    static_assert(!(ut_numeric_limits<U>::is_signed), "");
     HPBC_PRECONDITION2(modulus > 1);
 
     namespace hc = ::hurchalla;
@@ -51,7 +53,7 @@ struct impl_modular_pow {
     T result = hc::conditional_select((exponent & 1u), base, static_cast<T>(1));
     while (exponent > 1)
     {
-       exponent = static_cast<T>(exponent >> 1);
+       exponent = static_cast<U>(exponent >> 1);
        base = hc::modular_multiplication_prereduced_inputs(base, base, modulus);
        if (exponent & 1u) {
           result = hc::modular_multiplication_prereduced_inputs(