From b76dd18f67834eb84da69203b5d58075e9e6197f Mon Sep 17 00:00:00 2001 From: Michael Schlottke-Lakemper Date: Fri, 5 Mar 2021 18:39:17 +0100 Subject: [PATCH] Add docstrings to examples (#19) * Update changelog * Add missing docstrings to examples --- CHANGELOG.md | 3 + examples/2_encoders.jl | 40 ++++++++++++ examples/3_levels.jl | 12 ++++ examples/5_rotation.jl | 11 ++++ examples/6_serialization.jl | 13 ++++ examples/7_performance.jl | 123 ++++++++++++++++++++++++++++++++++++ 6 files changed, 202 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0290e3c..6b01b78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ This file only tracks changes at a very high, summarized level, omitting patch r ## SEAL dev * ... +## SEAL v0.4.0 +* Update the wrapper to support SEAL v3.6 + ## SEAL v0.3.0 * Add `examples/6_serialization.jl` and `examples/7_performance.jl` and all corresponding functionality in the library itself diff --git a/examples/2_encoders.jl b/examples/2_encoders.jl index 9635671..3e13b8c 100644 --- a/examples/2_encoders.jl +++ b/examples/2_encoders.jl @@ -3,6 +3,19 @@ include("utilities.jl") using SEAL using Printf + +""" + example_batch_encoder() + +Example to demonstrate encoding and decoding vectors of integers with the BFV scheme. +This function is based on the file `native/examples/2_encoders.cpp` of the original +SEAL library and should yield the exact same output. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp) + +See also: [`example_ckks_encoder`](@ref), [`example_encoders`](@ref) +""" function example_batch_encoder() print_example_banner("Example: Encoders / Batch Encoder") @@ -92,6 +105,19 @@ function example_batch_encoder() print_matrix(pod_result, row_size) end + +""" + example_ckks_encoder() + +Example to demonstrate encoding and decoding vectors of floating point values with the CKKS scheme. +This function is based on the file `native/examples/2_encoders.cpp` of the original +SEAL library and should yield the exact same output. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp) + +See also: [`example_batch_encoder`](@ref), [`example_encoders`](@ref) +""" function example_ckks_encoder() print_example_banner("Example: Encoders / CKKS Encoder") @@ -156,6 +182,20 @@ function example_ckks_encoder() end + +""" + example_encoders() + +Demonstrate how vectors of integers (BFV) or floating point values (CKKS) can be encoded/decoded +with the BFV and CKKS schemes. +This function is based on the file `native/examples/2_encoders.cpp` of the original +SEAL library and should yield the exact same output. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp) + +See also: [`example_batch_encoder`](@ref), [`example_ckks_encoder`](@ref) +""" function example_encoders() print_example_banner("Example: Encoders") diff --git a/examples/3_levels.jl b/examples/3_levels.jl index 04285ec..eaef2d9 100644 --- a/examples/3_levels.jl +++ b/examples/3_levels.jl @@ -4,6 +4,18 @@ using SEAL using Printf +""" + example_levels() + +Illustrate the concept of levels in the BFV and CKKS schemes. +This function is based on the file `native/examples/3_levels.cpp` of the original +SEAL library and should yield the exact same output. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/3_levels.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/3_levels.cpp) + +See also: [`example_bfv_basics`](@ref), [`example_ckks_basics`](@ref) +""" function example_levels() print_example_banner("Example: Levels") diff --git a/examples/5_rotation.jl b/examples/5_rotation.jl index 01849e1..49576ad 100644 --- a/examples/5_rotation.jl +++ b/examples/5_rotation.jl @@ -173,6 +173,17 @@ function example_rotation_ckks() return end + +""" + example_rotation() + +Perform some rotation on data encryped with the BFV and CKKS schemes. This routine is based on the +file `native/examples/5_rotation.cpp` of the original SEAL library and should yield the exact same +output. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/5_rotation.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/5_rotation.cpp) +""" function example_rotation() print_example_banner("Example: Rotation") diff --git a/examples/6_serialization.jl b/examples/6_serialization.jl index c2aa4e1..121a4e0 100644 --- a/examples/6_serialization.jl +++ b/examples/6_serialization.jl @@ -4,6 +4,19 @@ using SEAL using Printf +""" + example_serialization() + +Show example for how to use serialization in a client-server setup, where only the client knows the +secret key and the servers does not have knowledge of any unencrypted data. +This function is based on the file `native/examples/6_serialization.cpp` of the original +SEAL library and should yield the exact same output, except for differences in compression ratios. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/6_serialization.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/6_serialization.cpp) + +See also: [`example_bfv_basics`](@ref), [`example_ckks_basics`](@ref) +""" function example_serialization() print_example_banner("Example: Serialization") diff --git a/examples/7_performance.jl b/examples/7_performance.jl index 7276989..df58564 100644 --- a/examples/7_performance.jl +++ b/examples/7_performance.jl @@ -5,6 +5,23 @@ using Printf using Random +""" + bfv_performance_test(context) + +Perform multiple performance tests with the BFV scheme for the SEAL encryption context given in +`context`. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), + [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref), + [`bfv_performance_test`](@ref) +""" function bfv_performance_test(context) print_parameters(context) println() @@ -190,6 +207,24 @@ function bfv_performance_test(context) println("Average compressed (Zstandard) serialize ciphertext: ", avg_serialize_zstd, " microseconds") end + +""" + ckks_performance_test(context) + +Perform multiple performance tests with the CKKS scheme for the SEAL encryption context given in +`context`. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), + [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref), + [`bfv_performance_test`](@ref) +""" function ckks_performance_test(context) print_parameters(context) println() @@ -368,6 +403,23 @@ function ckks_performance_test(context) flush(stdout) end + +""" + example_bfv_performance_default() + +Perform multiple performance tests of the BFV scheme for several polynomial modulus degrees. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), [`example_bfv_performance_custom`](@ref), + [`bfv_performance_test`](@ref), + [`example_ckks_performance_default`](@ref) +""" function example_bfv_performance_default() print_example_banner("BFV Performance Test with Degrees: 4096, 8192, and 16384") @@ -402,6 +454,24 @@ function example_bfv_performance_default() # bfv_performance_test(SEALContext(enc_parms)) end + +""" + example_bfv_performance_custom() + +Show a terminal menu for selecting a custom polynomial modulus degree and use it for performance +tests with the BFV scheme. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), [`example_bfv_performance_default`](@ref), + [`bfv_performance_test`](@ref), + [`example_ckks_performance_custom`](@ref) +""" function example_bfv_performance_custom() poly_modulus_degree = 0 println() @@ -435,6 +505,23 @@ function example_bfv_performance_custom() bfv_performance_test(SEALContext(enc_parms)) end + +""" + example_ckks_performance_default() + +Perform multiple performance tests of the CKKS scheme for several polynomial modulus degrees. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), [`example_ckks_performance_custom`](@ref), + [`ckks_performance_test`](@ref), + [`example_bfv_performance_default`](@ref) +""" function example_ckks_performance_default() print_example_banner("CKKS Performance Test with Degrees: 4096, 8192, and 16384") @@ -466,6 +553,24 @@ function example_ckks_performance_default() # ckks_performance_test(SEALContext(enc_parms)) end + +""" + example_ckks_performance_custom() + +Show a terminal menu for selecting a custom polynomial modulus degree and use it for performance +tests with the CKKS scheme. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_performance_test`](@ref), [`example_ckks_performance_default`](@ref), + [`ckks_performance_test`](@ref), + [`example_bfv_performance_custom`](@ref) +""" function example_ckks_performance_custom() poly_modulus_degree = 0 println() @@ -494,6 +599,24 @@ function example_ckks_performance_custom() ckks_performance_test(SEALContext(enc_parms)) end + +""" + example_performance_test() + +Show a terminal menu for selecting different performance tests. + +This function is based on the file `native/examples/7_performance.cpp` of the original +SEAL library and should yield the exact same output, except (of course) for the actual performance +numbers. + +* [SEAL](https://github.com/microsoft/SEAL) +* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp) + +See also: [`example_bfv_performance_default`](@ref), [`example_bfv_performance_custom`](@ref), + [`bfv_performance_test`](@ref), + [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref), + [`ckks_performance_test`](@ref) +""" function example_performance_test() print_example_banner("Example: Performance Test")