Deprecated icicle/api headers and updated examples/docs (#740)

docs/docs/icicle/programmers_guide/cpp.md

@@ -183,15 +183,59 @@ struct DeviceProperties {
 
 ## Compute APIs
 
-### Multi-Scalar Multiplication (MSM) Example
+### Including Curves and Fields
+
+To use a specific elliptic curve (e.g., BN254) or its associated fields, include the relevant header files. For example:
+
+```cpp
+#include "icicle/msm.h"
+#include "icicle/curves/params/bn254.h"
+```
+
+The bn254 namespace includes key types like:
+
+- **scalar_t**: Scalar field elements.
+- **projective_t**: Points on the elliptic curve in projective coordinates.
+- **affine_t**: Points on the elliptic curve in affine coordinates.
+
+### Namespace Usage
+
+There are two ways to access types and functionality for a specific field or curve:
+
+1. **Bring the Namespace into Scope**
+This approach simplifies the code but may cause conflicts if multiple curves are used:
+
+```cpp
+using namespace bn254;
+
+scalar_t s;           // Scalar field element
+projective_t p;       // Point in projective coordinates
+affine_t a;           // Point in affine coordinates
+```
+
+2. **Use Fully Qualified Names**
+This is recommended if you are working with multiple curves or libraries to avoid namespace conflicts:
+
+```cpp
+bn254::scalar_t s;    // Scalar field element
+bn254::projective_t p; // Point in projective coordinates
+bn254::affine_t a;    // Point in affine coordinates
+```
+
+### Leveraging Template APIs
+
+ICICLE’s APIs are designed to work seamlessly with templated types, enabling flexibility and type safety. For example:
+
+#### Multi-Scalar Multiplication (MSM) Example
 
 Icicle provides high-performance compute APIs such as the Multi-Scalar Multiplication (MSM) for cryptographic operations. Here's a simple example of how to use the MSM API.
 
 ```cpp
 #include <iostream>
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
 
+#include "icicle/curves/params/bn254.h"
+#include "icicle/msm.h"
 using namespace bn254;
 
 int main()
@@ -245,15 +289,16 @@ int main()
 }
 ```
 
-### Polynomial Operations Example
+#### Polynomial Operations Example
 
 Here's another example demonstrating polynomial operations using Icicle:
 
 ```cpp
 #include <iostream>
 #include "icicle/runtime.h"
+#include "icicle/curves/params/bn254.h"
+#include "icicle/ntt.h"
 #include "icicle/polynomials/polynomials.h"
-#include "icicle/api/bn254.h"
 
 using namespace bn254;
 

examples/c++/best-practice-ntt/example.cpp

@@ -4,7 +4,8 @@
 #include <chrono>
 
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
+#include "icicle/ntt.h"
+#include "icicle/curves/params/bn254.h"
 using namespace bn254;
 
 #include "examples_utils.h"

examples/c++/install-and-use-icicle/example.cpp

@@ -1,7 +1,9 @@
 #include <iostream>
 #include <cassert>
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
+
+#include "icicle/curves/params/bn254.h"
+#include "icicle/ntt.h"
 
 using namespace bn254; // This makes scalar_t a bn254 scalar instead of bn254::scalar_t
 

examples/c++/msm/README.md

@@ -11,7 +11,9 @@
 3. Call msm api
 
 ```c++
-#include "icicle/api/bn254.h"
+#include "icicle/msm.h"
+#include "icicle/curves/params/bn254.h"
+using namespace bn254;
 ...
 MSMConfig config = default_msm_config();
 ...

examples/c++/msm/example.cpp

@@ -3,7 +3,8 @@
 #include <iomanip>
 
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
+#include "icicle/msm.h"
+#include "icicle/curves/params/bn254.h"
 using namespace bn254;
 
 #include "examples_utils.h"
@@ -38,7 +39,7 @@ int main(int argc, char* argv[])
   std::cout << "\nRunning MSM kernel with on-host inputs" << std::endl;
   // Execute the MSM kernel
   START_TIMER(MSM_host_mem);
-  ICICLE_CHECK(bn254_msm(scalars.get(), points.get(), msm_size, &config, &result));
+  ICICLE_CHECK(msm(scalars.get(), points.get(), msm_size, config, &result));
   END_TIMER(MSM_host_mem, "MSM from host-memory took");
   std::cout << projective_t::to_affine(result) << std::endl;
 
@@ -91,7 +92,7 @@ int main(int argc, char* argv[])
   config.are_points_on_device = false;
   g2_projective_t g2_result;
   START_TIMER(MSM_g2);
-  ICICLE_CHECK(bn254_g2_msm(scalars.get(), g2_points.get(), msm_size, &config, &g2_result));
+  ICICLE_CHECK(msm(scalars.get(), g2_points.get(), msm_size, config, &g2_result));
   END_TIMER(MSM_g2, "MSM G2 from host-memory took");
   std::cout << g2_projective_t::to_affine(g2_result) << std::endl;
 

examples/c++/ntt/README.md

@@ -11,7 +11,9 @@
 3. Call ntt api
 
 ```c++
-#include "icicle/api/bn254.h"
+#include "icicle/ntt.h"
+#include "icicle/curves/params/bn254.h"
+using namespace bn254;
 ...
 auto ntt_init_domain_cfg = default_ntt_init_domain_config();
 ...

examples/c++/ntt/example.cpp

@@ -2,7 +2,8 @@
 
 #include "icicle/runtime.h"
 
-#include "icicle/api/bn254.h"
+#include "icicle/ntt.h"
+#include "icicle/curves/params/bn254.h"
 using namespace bn254;
 
 #include "examples_utils.h"

examples/c++/pedersen-commitment/example.cpp

@@ -3,7 +3,7 @@
 #include <cassert>
 
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
+#include "icicle/msm.h"
 #include "icicle/curves/params/bn254.h"
 using namespace bn254;
 
@@ -150,7 +150,7 @@ int main(int argc, char** argv)
   std::cout << "Executing MSM" << std::endl;
   auto config = default_msm_config();
   START_TIMER(msm);
-  bn254_msm(scalars, points, N + 1, &config, &result);
+  ICICLE_CHECK(msm(scalars, points, N + 1, config, &result));
   END_TIMER(msm, "Time to execute MSM");
 
   std::cout << "Computed commitment: " << result << std::endl;

examples/c++/polynomial-api/example.cpp

@@ -1,7 +1,9 @@
 #include <iostream>
 #include <cassert>
 
-#include "icicle/api/bn254.h"
+#include "icicle/ntt.h"
+#include "icicle/msm.h"
+#include "icicle/curves/params/bn254.h"
 #include "icicle/polynomials/polynomials.h"
 
 #include "examples_utils.h"

examples/c++/polynomial-multiplication/example.cpp

@@ -3,7 +3,9 @@
 #include <memory>
 
 #include "icicle/runtime.h"
-#include "icicle/api/bn254.h"
+#include "icicle/ntt.h"
+#include "icicle/vec_ops.h"
+#include "icicle/curves/params/bn254.h"
 using namespace bn254;
 
 #include "examples_utils.h"
@@ -38,7 +40,7 @@ int main(int argc, char** argv)
   // init domain
   scalar_t basic_root = scalar_t::omega(NTT_LOG_SIZE);
   auto config = default_ntt_init_domain_config();
-  bn254_ntt_init_domain(&basic_root, &config);
+  ICICLE_CHECK(ntt_init_domain(basic_root, config));
 
   // (1) cpu allocation
   auto polyA = std::make_unique<scalar_t[]>(NTT_SIZE);
@@ -65,8 +67,8 @@ int main(int argc, char** argv)
     ntt_config.are_inputs_on_device = false;
     ntt_config.are_outputs_on_device = true;
     ntt_config.ordering = Ordering::kNM;
-    ICICLE_CHECK(bn254_ntt(polyA.get(), NTT_SIZE, NTTDir::kForward, &ntt_config, d_polyA));
-    ICICLE_CHECK(bn254_ntt(polyB.get(), NTT_SIZE, NTTDir::kForward, &ntt_config, d_polyB));
+    ICICLE_CHECK(ntt(polyA.get(), NTT_SIZE, NTTDir::kForward, ntt_config, d_polyA));
+    ICICLE_CHECK(ntt(polyB.get(), NTT_SIZE, NTTDir::kForward, ntt_config, d_polyB));
 
     // (4) multiply A,B
     VecOpsConfig config = default_vec_ops_config();
@@ -94,7 +96,7 @@ int main(int argc, char** argv)
   benchmark(false); // warmup
   benchmark(true);
 
-  ICICLE_CHECK(bn254_ntt_release_domain());
+  ntt_release_domain<scalar_t>();
 
   return 0;
 }

examples/c++/risc0/example.cpp

@@ -6,7 +6,8 @@
 
 #include "examples_utils.h"
 #include "icicle/polynomials/polynomials.h"
-#include "icicle/api/babybear.h"
+#include "icicle/ntt.h"
+#include "icicle/fields/stark_fields/babybear.h"
 
 using namespace babybear;
 

icicle/backend/cpu/src/curve/cpu_mont_conversion.cpp

@@ -22,7 +22,7 @@ cpu_convert_mont(const Device& device, const T* input, size_t n, bool is_into, c
 REGISTER_AFFINE_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<affine_t>);
 REGISTER_PROJECTIVE_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<projective_t>);
 
-#ifdef G2
+#ifdef G2_ENABLED
 REGISTER_AFFINE_G2_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<g2_affine_t>);
 REGISTER_PROJECTIVE_G2_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<g2_projective_t>);
 #endif // G2

icicle/backend/cpu/src/curve/cpu_msm.cpp

@@ -7,7 +7,7 @@
 REGISTER_MSM_PRE_COMPUTE_BASES_BACKEND("CPU", (cpu_msm_precompute_bases<affine_t, projective_t>));
 REGISTER_MSM_BACKEND("CPU", (cpu_msm<affine_t, projective_t>));
 
-#ifdef G2
+#ifdef G2_ENABLED
 REGISTER_MSM_G2_PRE_COMPUTE_BASES_BACKEND("CPU", (cpu_msm_precompute_bases<g2_affine_t, g2_projective_t>));
 REGISTER_MSM_G2_BACKEND("CPU", (cpu_msm<g2_affine_t, g2_projective_t>));
 #endif

icicle/backend/cpu/src/field/cpu_vec_ops.cpp

@@ -372,7 +372,7 @@ class VectorOpTask : public TaskBase
 public:
   T m_intermidiate_res;    // pointer to the output. Can be a vector or scalar pointer
   uint64_t m_idx_in_batch; // index in the batch. Used in intermediate res tasks
-}; // class VectorOpTask
+};
 
 #define NOF_OPERATIONS_PER_TASK 512
 #define CONFIG_NOF_THREADS_KEY  "n_threads"

icicle/backend/cpu/src/hash/cpu_poseidon2.cpp

@@ -147,7 +147,7 @@ namespace icicle {
         ICICLE_LOG_ERROR
           << "cpu_poseidon2_init_default_constants: T (width) must be one of [2, 3, 4, 8, 12, 16, 20, 24]\n";
         return eIcicleError::INVALID_ARGUMENT;
-      } // switch (T) {
+      }
       if (full_rounds == 0 && partial_rounds == 0) { // All arrays are empty in this case.
         continue;
       }

icicle/cmake/target_editor.cmake

@@ -53,7 +53,7 @@ endfunction()
 
 function(handle_g2 TARGET FEATURE_LIST)
   if(G2 AND "G2" IN_LIST FEATURE_LIST)
-    target_compile_definitions(${TARGET} PUBLIC G2=${G2})
+    target_compile_definitions(${TARGET} PUBLIC G2_ENABLED=${G2})
     set(G2 "G2" CACHE BOOL "Enable G2 feature" FORCE)
   else()
     set(G2 OFF CACHE BOOL "G2 not available for this curve" FORCE)

icicle/include/icicle/api/babybear.h

@@ -1,3 +1,28 @@
+// *****************************************************************************
+// * DEPRECATED HEADER FILE                                                    *
+// *****************************************************************************
+// * This header file is deprecated and should not be used in new code.        *
+// * It is maintained only for backward compatibility and may be removed in    *
+// * a future release.                                                         *
+// *                                                                           *
+// * Deprecation Date: January 15, 2025                                        *
+// *                                                                           *
+// * Please migrate to using template headers with the corresponding types.    *
+// * For example:                                                              *
+// *                                                                           *
+// *   #include "icicle/fields/stark_fields/babybear.h"                        *
+// *   #include "icicle/ntt.h"                                                 *
+// *   #include "icicle/vec_ops.h"                                             *
+// *                                                                           *
+// *   Option 1: Bring the namespace into scope (simplifies usage):            *
+// *     using namespace babybear;                                             *
+// *     scalar_t a;                                                           *
+// *                                                                           *
+// *   Option 2: Use fully qualified names (avoids namespace conflicts):       *
+// *     babybear::scalar_t a;                                                 *
+// *                                                                           *
+// *****************************************************************************
+
 // WARNING: This file is auto-generated by a script.
 // Any changes made to this file may be overwritten.
 // Please modify the code generation script instead.

icicle/include/icicle/api/bls12_377.h

@@ -1,3 +1,37 @@
+// *****************************************************************************
+// * DEPRECATED HEADER FILE                                                    *
+// *****************************************************************************
+// * This header file is deprecated and should not be used in new code.        *
+// * It is maintained only for backward compatibility and may be removed in    *
+// * a future release.                                                         *
+// *                                                                           *
+// * Deprecation Date: January 15, 2025                                        *
+// *                                                                           *
+// * Please migrate to using template headers with the corresponding types.    *
+// * For example:                                                              *
+// *                                                                           *
+// *   #include "icicle/curves/params/bls12_377.h"                             *
+// *   #include "icicle/msm.h"                                                 *
+// *   #include "icicle/ntt.h"                                                 *
+// *   #include "icicle/vec_ops.h"                                             *
+// *                                                                           *
+// *   Option 1: Bring the namespace into scope (simplifies usage):            *
+// *     using namespace bls12_377;                                            *
+// *     scalar_t a;                                                           *
+// *     projective_t p;                                                       *
+// *     affine_t q;                                                           *
+// *                                                                           *
+// *   Option 2: Use fully qualified names (avoids namespace conflicts):       *
+// *     bls12_377::scalar_t a;                                                *
+// *     bls12_377::projective_t p;                                            *
+// *     bls12_377::affine_t q;                                                *
+// *                                                                           *
+// * Note: The bls12_377 namespace also includes other types such as G2 types, *
+// *       which are not explicitly mentioned here but are accessible through  *
+// *       the same pattern of usage.                                          *
+// *                                                                           *
+// *****************************************************************************
+
 // WARNING: This file is auto-generated by a script.
 // Any changes made to this file may be overwritten.
 // Please modify the code generation script instead.

icicle/include/icicle/api/bls12_381.h

@@ -1,3 +1,38 @@
+
+// *****************************************************************************
+// * DEPRECATED HEADER FILE                                                    *
+// *****************************************************************************
+// * This header file is deprecated and should not be used in new code.        *
+// * It is maintained only for backward compatibility and may be removed in    *
+// * a future release.                                                         *
+// *                                                                           *
+// * Deprecation Date: January 15, 2025                                        *
+// *                                                                           *
+// * Please migrate to using template headers with the corresponding types.    *
+// * For example:                                                              *
+// *                                                                           *
+// *   #include "icicle/curves/params/bls12_381.h"                             *
+// *   #include "icicle/msm.h"                                                 *
+// *   #include "icicle/ntt.h"                                                 *
+// *   #include "icicle/vec_ops.h"                                             *
+// *                                                                           *
+// *   Option 1: Bring the namespace into scope (simplifies usage):            *
+// *     using namespace bls12_381;                                            *
+// *     scalar_t a;                                                           *
+// *     projective_t p;                                                       *
+// *     affine_t q;                                                           *
+// *                                                                           *
+// *   Option 2: Use fully qualified names (avoids namespace conflicts):       *
+// *     bls12_381::scalar_t a;                                                *
+// *     bls12_381::projective_t p;                                            *
+// *     bls12_381::affine_t q;                                                *
+// *                                                                           *
+// * Note: The bls12_381 namespace also includes other types such as G2 types, *
+// *       which are not explicitly mentioned here but are accessible through  *
+// *       the same pattern of usage.                                          *
+// *                                                                           *
+// *****************************************************************************
+
 // WARNING: This file is auto-generated by a script.
 // Any changes made to this file may be overwritten.
 // Please modify the code generation script instead.