Skip to content

Commit 6d38056

Browse files
yshekelyshekel
authored
Deprecated icicle/api headers and updated examples/docs (#740)
1 parent d4a8153 commit 6d38056

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+359
-295
lines changed

‎docs/docs/icicle/programmers_guide/cpp.md

+49-4
Original file line numberDiff line numberDiff line change
@@ -183,15 +183,59 @@ struct DeviceProperties {
183183
184184
## Compute APIs
185185
186-
### Multi-Scalar Multiplication (MSM) Example
186+
### Including Curves and Fields
187+
188+
To use a specific elliptic curve (e.g., BN254) or its associated fields, include the relevant header files. For example:
189+
190+
```cpp
191+
#include "icicle/msm.h"
192+
#include "icicle/curves/params/bn254.h"
193+
```
194+
195+
The bn254 namespace includes key types like:
196+
197+
- **scalar_t**: Scalar field elements.
198+
- **projective_t**: Points on the elliptic curve in projective coordinates.
199+
- **affine_t**: Points on the elliptic curve in affine coordinates.
200+
201+
### Namespace Usage
202+
203+
There are two ways to access types and functionality for a specific field or curve:
204+
205+
1. **Bring the Namespace into Scope**
206+
This approach simplifies the code but may cause conflicts if multiple curves are used:
207+
208+
```cpp
209+
using namespace bn254;
210+
211+
scalar_t s; // Scalar field element
212+
projective_t p; // Point in projective coordinates
213+
affine_t a; // Point in affine coordinates
214+
```
215+
216+
2. **Use Fully Qualified Names**
217+
This is recommended if you are working with multiple curves or libraries to avoid namespace conflicts:
218+
219+
```cpp
220+
bn254::scalar_t s; // Scalar field element
221+
bn254::projective_t p; // Point in projective coordinates
222+
bn254::affine_t a; // Point in affine coordinates
223+
```
224+
225+
### Leveraging Template APIs
226+
227+
ICICLE’s APIs are designed to work seamlessly with templated types, enabling flexibility and type safety. For example:
228+
229+
#### Multi-Scalar Multiplication (MSM) Example
187230

188231
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.
189232

190233
```cpp
191234
#include <iostream>
192235
#include "icicle/runtime.h"
193-
#include "icicle/api/bn254.h"
194236

237+
#include "icicle/curves/params/bn254.h"
238+
#include "icicle/msm.h"
195239
using namespace bn254;
196240

197241
int main()
@@ -245,15 +289,16 @@ int main()
245289
}
246290
```
247291

248-
### Polynomial Operations Example
292+
#### Polynomial Operations Example
249293

250294
Here's another example demonstrating polynomial operations using Icicle:
251295

252296
```cpp
253297
#include <iostream>
254298
#include "icicle/runtime.h"
299+
#include "icicle/curves/params/bn254.h"
300+
#include "icicle/ntt.h"
255301
#include "icicle/polynomials/polynomials.h"
256-
#include "icicle/api/bn254.h"
257302

258303
using namespace bn254;
259304

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
#include <chrono>
55

66
#include "icicle/runtime.h"
7-
#include "icicle/api/bn254.h"
7+
#include "icicle/ntt.h"
8+
#include "icicle/curves/params/bn254.h"
89
using namespace bn254;
910

1011
#include "examples_utils.h"

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

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
#include <iostream>
22
#include <cassert>
33
#include "icicle/runtime.h"
4-
#include "icicle/api/bn254.h"
4+
5+
#include "icicle/curves/params/bn254.h"
6+
#include "icicle/ntt.h"
57

68
using namespace bn254; // This makes scalar_t a bn254 scalar instead of bn254::scalar_t
79

‎examples/c++/msm/README.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111
3. Call msm api
1212

1313
```c++
14-
#include "icicle/api/bn254.h"
14+
#include "icicle/msm.h"
15+
#include "icicle/curves/params/bn254.h"
16+
using namespace bn254;
1517
...
1618
MSMConfig config = default_msm_config();
1719
...

‎examples/c++/msm/example.cpp

+4-3
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
#include <iomanip>
44

55
#include "icicle/runtime.h"
6-
#include "icicle/api/bn254.h"
6+
#include "icicle/msm.h"
7+
#include "icicle/curves/params/bn254.h"
78
using namespace bn254;
89

910
#include "examples_utils.h"
@@ -38,7 +39,7 @@ int main(int argc, char* argv[])
3839
std::cout << "\nRunning MSM kernel with on-host inputs" << std::endl;
3940
// Execute the MSM kernel
4041
START_TIMER(MSM_host_mem);
41-
ICICLE_CHECK(bn254_msm(scalars.get(), points.get(), msm_size, &config, &result));
42+
ICICLE_CHECK(msm(scalars.get(), points.get(), msm_size, config, &result));
4243
END_TIMER(MSM_host_mem, "MSM from host-memory took");
4344
std::cout << projective_t::to_affine(result) << std::endl;
4445

@@ -91,7 +92,7 @@ int main(int argc, char* argv[])
9192
config.are_points_on_device = false;
9293
g2_projective_t g2_result;
9394
START_TIMER(MSM_g2);
94-
ICICLE_CHECK(bn254_g2_msm(scalars.get(), g2_points.get(), msm_size, &config, &g2_result));
95+
ICICLE_CHECK(msm(scalars.get(), g2_points.get(), msm_size, config, &g2_result));
9596
END_TIMER(MSM_g2, "MSM G2 from host-memory took");
9697
std::cout << g2_projective_t::to_affine(g2_result) << std::endl;
9798

‎examples/c++/ntt/README.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111
3. Call ntt api
1212

1313
```c++
14-
#include "icicle/api/bn254.h"
14+
#include "icicle/ntt.h"
15+
#include "icicle/curves/params/bn254.h"
16+
using namespace bn254;
1517
...
1618
auto ntt_init_domain_cfg = default_ntt_init_domain_config();
1719
...

‎examples/c++/ntt/example.cpp

+2-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
#include "icicle/runtime.h"
44

5-
#include "icicle/api/bn254.h"
5+
#include "icicle/ntt.h"
6+
#include "icicle/curves/params/bn254.h"
67
using namespace bn254;
78

89
#include "examples_utils.h"

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
#include <cassert>
44

55
#include "icicle/runtime.h"
6-
#include "icicle/api/bn254.h"
6+
#include "icicle/msm.h"
77
#include "icicle/curves/params/bn254.h"
88
using namespace bn254;
99

@@ -150,7 +150,7 @@ int main(int argc, char** argv)
150150
std::cout << "Executing MSM" << std::endl;
151151
auto config = default_msm_config();
152152
START_TIMER(msm);
153-
bn254_msm(scalars, points, N + 1, &config, &result);
153+
ICICLE_CHECK(msm(scalars, points, N + 1, config, &result));
154154
END_TIMER(msm, "Time to execute MSM");
155155

156156
std::cout << "Computed commitment: " << result << std::endl;

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

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
#include <iostream>
22
#include <cassert>
33

4-
#include "icicle/api/bn254.h"
4+
#include "icicle/ntt.h"
5+
#include "icicle/msm.h"
6+
#include "icicle/curves/params/bn254.h"
57
#include "icicle/polynomials/polynomials.h"
68

79
#include "examples_utils.h"

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

+7-5
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
#include <memory>
44

55
#include "icicle/runtime.h"
6-
#include "icicle/api/bn254.h"
6+
#include "icicle/ntt.h"
7+
#include "icicle/vec_ops.h"
8+
#include "icicle/curves/params/bn254.h"
79
using namespace bn254;
810

911
#include "examples_utils.h"
@@ -38,7 +40,7 @@ int main(int argc, char** argv)
3840
// init domain
3941
scalar_t basic_root = scalar_t::omega(NTT_LOG_SIZE);
4042
auto config = default_ntt_init_domain_config();
41-
bn254_ntt_init_domain(&basic_root, &config);
43+
ICICLE_CHECK(ntt_init_domain(basic_root, config));
4244

4345
// (1) cpu allocation
4446
auto polyA = std::make_unique<scalar_t[]>(NTT_SIZE);
@@ -65,8 +67,8 @@ int main(int argc, char** argv)
6567
ntt_config.are_inputs_on_device = false;
6668
ntt_config.are_outputs_on_device = true;
6769
ntt_config.ordering = Ordering::kNM;
68-
ICICLE_CHECK(bn254_ntt(polyA.get(), NTT_SIZE, NTTDir::kForward, &ntt_config, d_polyA));
69-
ICICLE_CHECK(bn254_ntt(polyB.get(), NTT_SIZE, NTTDir::kForward, &ntt_config, d_polyB));
70+
ICICLE_CHECK(ntt(polyA.get(), NTT_SIZE, NTTDir::kForward, ntt_config, d_polyA));
71+
ICICLE_CHECK(ntt(polyB.get(), NTT_SIZE, NTTDir::kForward, ntt_config, d_polyB));
7072

7173
// (4) multiply A,B
7274
VecOpsConfig config = default_vec_ops_config();
@@ -94,7 +96,7 @@ int main(int argc, char** argv)
9496
benchmark(false); // warmup
9597
benchmark(true);
9698

97-
ICICLE_CHECK(bn254_ntt_release_domain());
99+
ntt_release_domain<scalar_t>();
98100

99101
return 0;
100102
}

‎examples/c++/risc0/example.cpp

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66

77
#include "examples_utils.h"
88
#include "icicle/polynomials/polynomials.h"
9-
#include "icicle/api/babybear.h"
9+
#include "icicle/ntt.h"
10+
#include "icicle/fields/stark_fields/babybear.h"
1011

1112
using namespace babybear;
1213

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ cpu_convert_mont(const Device& device, const T* input, size_t n, bool is_into, c
2222
REGISTER_AFFINE_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<affine_t>);
2323
REGISTER_PROJECTIVE_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<projective_t>);
2424

25-
#ifdef G2
25+
#ifdef G2_ENABLED
2626
REGISTER_AFFINE_G2_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<g2_affine_t>);
2727
REGISTER_PROJECTIVE_G2_CONVERT_MONTGOMERY_BACKEND("CPU", cpu_convert_mont<g2_projective_t>);
2828
#endif // G2

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
REGISTER_MSM_PRE_COMPUTE_BASES_BACKEND("CPU", (cpu_msm_precompute_bases<affine_t, projective_t>));
88
REGISTER_MSM_BACKEND("CPU", (cpu_msm<affine_t, projective_t>));
99

10-
#ifdef G2
10+
#ifdef G2_ENABLED
1111
REGISTER_MSM_G2_PRE_COMPUTE_BASES_BACKEND("CPU", (cpu_msm_precompute_bases<g2_affine_t, g2_projective_t>));
1212
REGISTER_MSM_G2_BACKEND("CPU", (cpu_msm<g2_affine_t, g2_projective_t>));
1313
#endif

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -372,7 +372,7 @@ class VectorOpTask : public TaskBase
372372
public:
373373
T m_intermidiate_res; // pointer to the output. Can be a vector or scalar pointer
374374
uint64_t m_idx_in_batch; // index in the batch. Used in intermediate res tasks
375-
}; // class VectorOpTask
375+
};
376376

377377
#define NOF_OPERATIONS_PER_TASK 512
378378
#define CONFIG_NOF_THREADS_KEY "n_threads"

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

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

‎icicle/cmake/target_editor.cmake

+1-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ endfunction()
5353

5454
function(handle_g2 TARGET FEATURE_LIST)
5555
if(G2 AND "G2" IN_LIST FEATURE_LIST)
56-
target_compile_definitions(${TARGET} PUBLIC G2=${G2})
56+
target_compile_definitions(${TARGET} PUBLIC G2_ENABLED=${G2})
5757
set(G2 "G2" CACHE BOOL "Enable G2 feature" FORCE)
5858
else()
5959
set(G2 OFF CACHE BOOL "G2 not available for this curve" FORCE)

‎icicle/include/icicle/api/babybear.h

+25
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
// *****************************************************************************
2+
// * DEPRECATED HEADER FILE *
3+
// *****************************************************************************
4+
// * This header file is deprecated and should not be used in new code. *
5+
// * It is maintained only for backward compatibility and may be removed in *
6+
// * a future release. *
7+
// * *
8+
// * Deprecation Date: January 15, 2025 *
9+
// * *
10+
// * Please migrate to using template headers with the corresponding types. *
11+
// * For example: *
12+
// * *
13+
// * #include "icicle/fields/stark_fields/babybear.h" *
14+
// * #include "icicle/ntt.h" *
15+
// * #include "icicle/vec_ops.h" *
16+
// * *
17+
// * Option 1: Bring the namespace into scope (simplifies usage): *
18+
// * using namespace babybear; *
19+
// * scalar_t a; *
20+
// * *
21+
// * Option 2: Use fully qualified names (avoids namespace conflicts): *
22+
// * babybear::scalar_t a; *
23+
// * *
24+
// *****************************************************************************
25+
126
// WARNING: This file is auto-generated by a script.
227
// Any changes made to this file may be overwritten.
328
// Please modify the code generation script instead.

‎icicle/include/icicle/api/bls12_377.h

+34
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1+
// *****************************************************************************
2+
// * DEPRECATED HEADER FILE *
3+
// *****************************************************************************
4+
// * This header file is deprecated and should not be used in new code. *
5+
// * It is maintained only for backward compatibility and may be removed in *
6+
// * a future release. *
7+
// * *
8+
// * Deprecation Date: January 15, 2025 *
9+
// * *
10+
// * Please migrate to using template headers with the corresponding types. *
11+
// * For example: *
12+
// * *
13+
// * #include "icicle/curves/params/bls12_377.h" *
14+
// * #include "icicle/msm.h" *
15+
// * #include "icicle/ntt.h" *
16+
// * #include "icicle/vec_ops.h" *
17+
// * *
18+
// * Option 1: Bring the namespace into scope (simplifies usage): *
19+
// * using namespace bls12_377; *
20+
// * scalar_t a; *
21+
// * projective_t p; *
22+
// * affine_t q; *
23+
// * *
24+
// * Option 2: Use fully qualified names (avoids namespace conflicts): *
25+
// * bls12_377::scalar_t a; *
26+
// * bls12_377::projective_t p; *
27+
// * bls12_377::affine_t q; *
28+
// * *
29+
// * Note: The bls12_377 namespace also includes other types such as G2 types, *
30+
// * which are not explicitly mentioned here but are accessible through *
31+
// * the same pattern of usage. *
32+
// * *
33+
// *****************************************************************************
34+
135
// WARNING: This file is auto-generated by a script.
236
// Any changes made to this file may be overwritten.
337
// Please modify the code generation script instead.

‎icicle/include/icicle/api/bls12_381.h

+35
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,38 @@
1+
2+
// *****************************************************************************
3+
// * DEPRECATED HEADER FILE *
4+
// *****************************************************************************
5+
// * This header file is deprecated and should not be used in new code. *
6+
// * It is maintained only for backward compatibility and may be removed in *
7+
// * a future release. *
8+
// * *
9+
// * Deprecation Date: January 15, 2025 *
10+
// * *
11+
// * Please migrate to using template headers with the corresponding types. *
12+
// * For example: *
13+
// * *
14+
// * #include "icicle/curves/params/bls12_381.h" *
15+
// * #include "icicle/msm.h" *
16+
// * #include "icicle/ntt.h" *
17+
// * #include "icicle/vec_ops.h" *
18+
// * *
19+
// * Option 1: Bring the namespace into scope (simplifies usage): *
20+
// * using namespace bls12_381; *
21+
// * scalar_t a; *
22+
// * projective_t p; *
23+
// * affine_t q; *
24+
// * *
25+
// * Option 2: Use fully qualified names (avoids namespace conflicts): *
26+
// * bls12_381::scalar_t a; *
27+
// * bls12_381::projective_t p; *
28+
// * bls12_381::affine_t q; *
29+
// * *
30+
// * Note: The bls12_381 namespace also includes other types such as G2 types, *
31+
// * which are not explicitly mentioned here but are accessible through *
32+
// * the same pattern of usage. *
33+
// * *
34+
// *****************************************************************************
35+
136
// WARNING: This file is auto-generated by a script.
237
// Any changes made to this file may be overwritten.
338
// Please modify the code generation script instead.

0 commit comments

Comments
 (0)