Tutorial tweaks

Co-authored-by: victorshoup <[email protected]>
Co-authored-by: Jack Crawford <[email protected]>

Author: jlhcrawford

examples/tutorial/01_ckks_basics.cpp

@@ -1,4 +1,4 @@
-/* Copyright (C) 2020 IBM Corp.
+/* Copyright (C) 2020-2021 IBM Corp.
  * This program is Licensed under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -10,11 +10,6 @@
  * limitations under the License. See accompanying LICENSE file.
  */
 
-#include <helib/helib.h>
-
-using namespace std;
-using namespace helib;
-
 // In the CKKS encryption scheme, plaintexts are vectors of real or complex
 // numbers.  The length, n, of these vectors is determined by the choice of
 // parameters, as discussed below.  We often refer to the components of these
@@ -24,11 +19,16 @@ using namespace helib;
 // means Single Instruction Multiple Data), since we can effectively perform
 // the same scalar operation in parallel on all n slots.
 
+#include <helib/helib.h>
+
+using namespace std;
+using namespace helib;
+
 int main(int argc, char* argv[])
 {
   // To get started, we need to choose some parameters.  This is done by
   // initializing a Context object.  Since there are a lot of parameters, many
-  // of them optional, HElib provides a "builder pattern" then lets you provide
+  // of them optional, HElib provides a "builder pattern" than lets you provide
   // these parameters "by name".
 
   Context context =
@@ -194,6 +194,9 @@ int main(int argc, char* argv[])
   // When this is done, if we denote the i-th slot of a ciphertext c by c[i],
   // then we have c3[i] = c0[i]*c1[i] + c2[i]*1.5 for i = 0..n-1.
 
+  // More generally, for a Ctxt c, one can perform c *= d, c += d, or c -= d,
+  // where d can be (among other things) a long, a double, or even a PtxtArray.
+
   //===========================================================================
 
   // Next we decrypt c3.
@@ -220,7 +223,7 @@ int main(int argc, char* argv[])
 
   // Then, we compute the distance between p3 (computed on plaintexts) and pp3
   // (computed homomorphically on ciphertexts). This is computed as
-  //  max{ |p3[i]-pp3[i]| : i = 0..n-1 }
+  // max{ |p3[i]-pp3[i]| : i = 0..n-1 }
   double distance = Distance(p3, pp3);
 
   cout << "distance=" << distance << "\n";

examples/tutorial/02_ckks_depth.cpp

@@ -1,4 +1,4 @@
-/* Copyright (C) 2020 IBM Corp.
+/* Copyright (C) 2020-2021 IBM Corp.
  * This program is Licensed under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -38,15 +38,15 @@ using namespace helib;
 // Given a ciphertext c, one can obtain its capacity by invoking c.capacity(),
 // and one can obtain a bound on its absolute error by invoking c.errorBound().
 
+#include <helib/helib.h>
+
+using namespace std;
+using namespace helib;
+
 int main(int argc, char* argv[])
 {
   Context context =
-      ContextBuilder<CKKS>()
-          .m(32 * 1024)
-          .bits(358)
-          .precision(20)
-          .c(6)
-          .build();
+      ContextBuilder<CKKS>().m(32 * 1024).bits(358).precision(20).c(6).build();
 
   cout << "securityLevel=" << context.securityLevel() << "\n";
 

examples/tutorial/03_ckks_data_movement.cpp

@@ -1,4 +1,4 @@
-/* Copyright (C) 2020 IBM Corp.
+/* Copyright (C) 2020-2021 IBM Corp.
  * This program is Licensed under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -10,24 +10,19 @@
  * limitations under the License. See accompanying LICENSE file.
  */
 
+// In the CKKS encryption scheme, besides SIMD operations that act on the slots
+// of a ciphertext in parallel, it is also possible to move data around among
+// the slots of a ciphertext.
+
 #include <helib/helib.h>
 
 using namespace std;
 using namespace helib;
 
-// In the CKKS encryption scheme, besides SIMD operations that act on the slots
-// of a ciphertext in parallel, it is also possible to move data around among
-// the slots of a ciphertext.
-
 int main(int argc, char* argv[])
 {
   Context context =
-      ContextBuilder<CKKS>()
-        .m(32 * 1024)
-        .bits(358)
-        .precision(30)
-        .c(6)
-        .build();
+      ContextBuilder<CKKS>().m(32 * 1024).bits(358).precision(30).c(6).build();
 
   cout << "securityLevel=" << context.securityLevel() << "\n";
 

examples/tutorial/04_ckks_matmul.cpp

@@ -1,4 +1,4 @@
-/* Copyright (C) 2020 IBM Corp.
+/* Copyright (C) 2020-2021 IBM Corp.
  * This program is Licensed under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -10,16 +10,16 @@
  * limitations under the License. See accompanying LICENSE file.
  */
 
+// In the CKKS encryption scheme, since a ciphertext encrypts a vector of
+// slots, it makes sense to multiply that vector by a matrix.  HElib provides
+// highly optimized routines for multiplying an encrypted vector by a plaintext
+// matrix.
+
 #include <helib/helib.h>
 
 using namespace std;
 using namespace helib;
 
-// In the CKKS encryption scheme, since a ciphertext encrypts a vector
-// of slots, it makes sense to multiply that vector by a matrix.
-// HElib provides highly optimized routines for multiplying
-// an encrypted vector by a plaintext matrix.
-
 // To use these routines, we need to include an extra file:
 #include <helib/matmul.h>
 
@@ -43,12 +43,7 @@ void printMemoryUsage() {}
 int main(int argc, char* argv[])
 {
   Context context =
-      ContextBuilder<CKKS>()
-          .m(16 * 1024)
-          .bits(119)
-          .precision(30)
-          .c(2)
-          .build();
+      ContextBuilder<CKKS>().m(16 * 1024).bits(119).precision(30).c(2).build();
 
   cout << "securityLevel=" << context.securityLevel() << "\n";
 
@@ -76,14 +71,15 @@ int main(int argc, char* argv[])
 
   //===========================================================================
 
-  // We define a plaintext matrix as follows:
+  // We define an n x n plaintext matrix as follows:
   MatMul_CKKS mat(context,
                   [n](long i, long j) { return ((i + j) % n) / double(n); });
 
   // Note that the second parameter of the MatMul_CKKS constructor is of type
   // std::function<double(long, long)>, meaning that it should be a
   // function-like object that takes two long's and returns a double.  In this
-  // example, the actual parameter is a C++ "lambda" object.
+  // example, the actual parameter is a C++ "lambda" object. In input (i, j),
+  // this should return the value of the matrix in row i and column j.
 
   // We now multiply ciphertext c by this matrix:
   c *= mat;

examples/tutorial/05_ckks_multlowlvl.cpp

@@ -1,4 +1,4 @@
-/* Copyright (C) 2020 IBM Corp.
+/* Copyright (C) 2020-2021 IBM Corp.
  * This program is Licensed under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -10,11 +10,6 @@
  * limitations under the License. See accompanying LICENSE file.
  */
 
-#include <helib/helib.h>
-
-using namespace std;
-using namespace helib;
-
 // In the CKKS encryption scheme (as well as in BGV), ciphertext multiplication
 // is a two-step process.  The operation ctxt1 *= ctxt2 is equivalent to the
 // following:
@@ -30,15 +25,15 @@ using namespace helib;
 // can sometimes be exploited to achieve significant speedups, as illustrated
 // here.
 
+#include <helib/helib.h>
+
+using namespace std;
+using namespace helib;
+
 int main(int argc, char* argv[])
 {
   Context context =
-      ContextBuilder<CKKS>()
-          .m(16 * 1024)
-          .bits(119)
-          .precision(20)
-          .c(2)
-          .build();
+      ContextBuilder<CKKS>().m(16 * 1024).bits(119).precision(20).c(2).build();
 
   cout << "securityLevel=" << context.securityLevel() << "\n";
 

examples/tutorial/06_ckks_complex.cpp

@@ -0,0 +1,144 @@
+/* Copyright (C) 2020-2021 IBM Corp.
+ * This program is Licensed under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License. See accompanying LICENSE file.
+ */
+
+// In the CKKS encryption scheme, ciphertexts can encrypt vectors of complex
+// numbers.
+
+#include <helib/helib.h>
+
+#include <helib/matmul.h>
+// This is only needed if you want to do matrix multiplication
+
+using namespace std;
+using namespace helib;
+
+int main(int argc, char* argv[])
+{
+  Context context =
+      ContextBuilder<CKKS>().m(32 * 1024).bits(358).precision(30).c(6).build();
+
+  cout << "securityLevel=" << context.securityLevel() << "\n";
+
+  long n = context.getNSlots();
+
+  SecKey secretKey(context);
+  secretKey.GenSecKey();
+
+  addSome1DMatrices(secretKey);
+  // This only needs to be done if you want to do matrix multiplication
+
+  addSomeFrbMatrices(secretKey);
+  // This only needs to be done if you want to do conjugation
+
+  const PubKey& publicKey = secretKey;
+
+  //===========================================================================
+
+  // Let's encrypt something!
+  vector<std::complex<double>> v0(n);
+  for (long i = 0; i < n; i++)
+    v0[i] = std::complex<double>(cos(2.0 * PI * i / n), sin(2.0 * PI * i / n));
+
+  // A PtxtArray can be initialized with a vector of complex numbers
+  PtxtArray p0(context, v0);
+
+  // Encryption works the same as with real numbers
+  Ctxt c0(publicKey);
+  p0.encrypt(c0);
+
+  //===========================================================================
+
+  // We next create another ciphertext that encrypts random complex numbers:
+
+  PtxtArray p1(context);
+  p1.randomComplex();
+  // this fills each entry of p1 with a random number in the complex
+  // unit circle
+
+  Ctxt c1(publicKey);
+  p1.encrypt(c1);
+
+  //===========================================================================
+
+  // We can perform homomorphic computations in the same way as we did before:
+
+  Ctxt c2 = c0;
+  c2 *= 2.5;
+  c2 += c1;
+
+  // Note that there is no direct support for combining a ciphertext with a
+  // complex scalar. This can be achieved, however, by first converting the
+  // complex scaler to a PtxtArray.  For example:
+
+  PtxtArray I(context, std::complex<double>(0.0, 1.0));
+  // I has the imaginary unit in each slot
+
+  c2 *= I;
+
+  cout << "c2.capacity=" << c2.capacity() << " ";
+  cout << "c2.errorBound=" << c2.errorBound() << "\n";
+
+  // Data movement operations, like rotate and shift, work exactly as before.
+
+  // There is also support for multiplying a ciphertext by a plaintext matrix
+  // of complex numbers.  In 04_ckks_matmul.cpp, we showed how you could
+  // specify an n x n matrix of real numbers using the class MatMul_CKKS. One
+  // can specify an n x n matrix of complex numbers as follows:
+
+  MatMul_CKKS_Complex mat(context, [n](long i, long j) {
+    return std::complex<double>(i, j) / double(n);
+  });
+
+  c2 *= mat;
+
+  cout << "c2.capacity=" << c2.capacity() << " ";
+  cout << "c2.errorBound=" << c2.errorBound() << "\n";
+
+  //===========================================================================
+
+  // One can homomorphically compute the complex conjugate of each slot
+  // of a ciphertext as follows:
+
+  conjugate(c2);
+
+  cout << "c2.capacity=" << c2.capacity() << " ";
+  cout << "c2.errorBound=" << c2.errorBound() << "\n";
+
+  //===========================================================================
+
+  // Let's decrypt the results:
+
+  PtxtArray pp2(context);
+  pp2.decryptComplex(c2, secretKey);
+
+  // Note that if one just writes pp2.decrypt(c2, secretKey) instead of
+  // pp2.decryptComplex(c2, secretKey), the imaginary part will be discarded.
+
+  // We can store pp2 in a standard vector, as usual:
+
+  std::vector<std::complex<double>> v2;
+  pp2.store(v2);
+
+  //===========================================================================
+
+  // We can also perform the computation on plaintexts and compare:
+
+  PtxtArray p2 = p0;
+  p2 *= 2.5;
+  p2 += p1;
+  p2 *= I;
+  p2 *= mat;
+  conjugate(p2);
+
+  double distance = Distance(p2, pp2);
+  cout << "distance=" << distance << "\n";
+}