more doc

README.md

 
+Cocks--Pinch curves with embedding degree 5 to 8 and optimal ate pairing
+========================================================================
+
+This repository holds companion code for the paper.
+
+We provide code for the following tasks.
+ * Search for pairing-friendly curves with our Cocks-Pinch variant; see
+   "Using the search program")
+ * Generate formulas for efficient computation of final exponentiations
+   when k is either 5 or 7 (see file `final_expo_k57.py`) or 6 or 8
+   (`final_expo_k68.sage`). For all four cases, see also the section
+   "Formulas for final exponentiation" in this file.
+ * Generate tables with estimated costs of pairing computations for
+   various embedding degrees. See "Computing pairing costs"
+
+
 Using the search program
 ========================
 
@@ -563,3 +579,50 @@ respectively):
 
 Note that the former is naturally preferred because hy has 2-naf weight
 only 4.
+
+
+Formulas for final exponentiation
+=================================
+
+This corresponds to §5.2 of the paper.
+
+For the cases `k=5` and `k=7`, the file `final_expo_k57.py` contains
+explicit formulas that reach the upper bound claimed in §5.2 in the
+paper.
+
+To reproduce this, one does as follows. Notice that the number of
+inversions depends on the parameter `i`.
+    sage: load("final_expo_k57.py")
+    sage: print_final_expo_k57()
+    cost for k=5 i=1: 3p + 1c + 7M + 3T
+    cost for k=5 i=2: 1I + 3p + 1c + 7M + 3T
+    cost for k=5 i=3: 2I + 3p + 1c + 7M + 3T
+    cost for k=5 i=4: 1I + 3p + 1c + 7M + 3T
+    cost for k=7 i=1: 5p + 1c + 11M + 5T
+    cost for k=7 i=2: 1I + 5p + 1c + 11M + 5T
+    cost for k=7 i=3: 1I + 5p + 1c + 11M + 5T
+    cost for k=7 i=4: 2I + 5p + 1c + 11M + 5T
+    cost for k=7 i=5: 2I + 5p + 1c + 11M + 5T
+    cost for k=7 i=6: 1I + 5p + 1c + 11M + 5T
+
+For the cases `k=6` and `k=8`, the exact formulas depend on the chosen
+CM discriminant, and employ further optimizations. Formulas as well as
+costs, matching those found in §5.2 in the paper, can be obtained as
+follows:
+    sage: load("final_expo_k68.sage")
+    sage: formulas(6)
+    [lots of output]
+    sage: formulas(8)
+    [lots of output]
+
+Computing pairing costs
+=======================
+
+Tables 5 and 9 in the paper are also generated automatically. The
+following code can be used.
+
+    sage: load("cost_pairing.py")
+    sage: table_costFpk([1,2,3,5,6,7,8,12,16])
+
+    sage: table_cost_pairing()
+

cost_pairing.py

@@ -2,9 +2,9 @@ from sage.all_cmdline import *
 from CocksPinchVariant import *
 import sage.rings.integer
 from BLS12 import *
-from BLS24 import *
+# from BLS24 import *
 from KSS16 import *
-from KSS18 import *
+# from KSS18 import *
 from BN import *
 from MNT6 import *
 from final_expo_k57 import *
@@ -171,7 +171,7 @@ def table_costFpk(k_list):
         r"\end{array}$$",
     ]
     print "% This table is generated by:"
-    print "%% PYTHONPATH=code/ sage -c 'load(\"code/cost_pairing.py\"); table_costFpk(%s)'" % (k_list)
+    print "%% PYTHONPATH=cocks-pinch-variant/ sage -c 'load(\"cocks-pinch-variant/cost_pairing.py\"); table_costFpk(%s)'" % (k_list)
 
     for s in contents:
         print s
@@ -229,11 +229,11 @@ def finite_field_cost(logp):
 def is_one_of_our_known_pairing_friendly_curves(C):
     return isinstance(C, BN) or \
             isinstance(C, BLS12) or \
-            isinstance(C, BLS24) or \
             isinstance(C, KSS16) or \
-            isinstance(C, KSS18) or \
             isinstance(C, MNT6) or \
             False;
+    # isinstance(C, BLS24) or \
+    # isinstance(C, KSS18) or \
 
 def polymorphic_get_logp(C):
     if is_one_of_our_known_pairing_friendly_curves(C):
@@ -264,12 +264,12 @@ def polymorphic_get_name(C):
         return 'MNT6'
     elif isinstance(C, BLS12):
         return 'BLS12'
-    elif isinstance(C, BLS24):
-        return 'BLS24'
+    # elif isinstance(C, BLS24):
+    #     return 'BLS24'
     elif isinstance(C, KSS16):
         return 'KSS16'
-    elif isinstance(C, KSS18):
-        return 'KSS18'
+    # elif isinstance(C, KSS18):
+    #    return 'KSS18'
     elif isinstance(C, Integer):
         return '$k=1$'
     else:
@@ -280,9 +280,9 @@ def polymorphic_get_miller_loop_length(C):
         return C.T
     elif isinstance(C, BN):
         return 6*C.u()+2
-    elif isinstance(C, BLS12) or isinstance(C, BLS24):
+    elif isinstance(C, BLS12): # or isinstance(C, BLS24):
         return C.tr() - 1
-    elif isinstance(C, KSS16) or isinstance(C, KSS18):
+    elif isinstance(C, KSS16): # or isinstance(C, KSS18):
         return C.u()
     elif isinstance(C, MNT6):
         # lazy me
@@ -679,7 +679,7 @@ def table_cost_pairing() :
     #timing recap is generated
 
     print "% This table is generated by:"
-    print "% PYTHONPATH=code sage -c 'load(\"code/cost_pairing.py\"); table_cost_pairing()"
+    print "% PYTHONPATH=cocks-pinch-variant sage -c 'load(\"cocks-pinch-variant/cost_pairing.py\"); table_cost_pairing()"
 
     def wrap_cell(cell):
         return "\\begin{tabular}{@{}c@{}} %s \\end{tabular}" % cell