refactor, comments

gaknot/__init__.py

@@ -1,51 +1,67 @@
 #!/usr/bin/env python3
 
-r"""
+r"""calculations of signature function and sigma invariant of generalized algebraic knots (GA-knots)
-This package contains calculations of signature functions for knots (cable sums)
 
 
-A knot (cable sum) is encoded as a list where each element (also a list)
+The package was used to prove Lemma 3.2 from a paper
-corresponds to a cable knot, e.g. a list
+'On the slice genus of generalized algebraic knots' Maria Marchwicka and Wojciech Politarczyk).
-[[1, 3], [2], [-1, -2], [-3]] encodes
+It contains the following submodules.
-T(2, 3; 2, 7) # T(2, 5) # -T(2, 3; 2, 5) # -T(2, 7).
+    1) signature.sage - contains SignatureFunction class;
-
+       it encodes twisted and untwisted signature functions
-To calculate the number of characters for which signature function vanish use
+       of knots and allows to perform algebraic operations on them.
-the function .
+    2) cable_signature.sage - contains the following classes:
-
+        a) CableSummand - it represents a single cable knot,
-sage: eval_cable_for_null_signature([[1, 3], [2], [-1, -2], [-3]])
+        b) CableSum - it represents a cable sum, i. e. linear combination of single cable knots;
-
+           since the signature function and sigma invariant are additive under connected sum,
-T(2, 3; 2, 7) # T(2, 5) # -T(2, 3; 2, 5) # -T(2, 7)
+           the class use calculations from CableSummand objects,
-Zero cases: 1
+        c) CableTemplate - it represents schema for a cable sums.
-All cases: 1225
+    3) main.sage - module that encodes interesting schemas for cable and perform calculations,
-Zero theta combinations:
+       e.g. a proof for Lemma 3.2 from the paper.
-(0, 0, 0, 0)
-
-sage:
-
-The numbers given to the function eval_cable_for_null_signature are k-values
-for each component/cable in a direct sum.
-
-To calculate signature function for a knot and a theta value, use function
-get_signature_as_function_of_theta (see help/docstring for details).
-
-About notation:
-Cables that we work with follow a schema:
-    T(2, q_1; 2, q_2; 2, q_4) # -T(2, q_2; 2, q_4) #
-            # T(2, q_3; 2, q_4) # -T(2, q_1; 2, q_3; 2, q_4)
-In knot_formula each k[i] is related with some q_i value, where
-q_i = 2*k[i] + 1.
-So we can work in the following steps:
-1) choose a schema/formula by changing the value of knot_formula
-2) set each q_i all or choose range in which q_i should varry
-3) choose vector v / theata vector.
 """
 
+#
+# A knot (cable sum) is encoded as a list where each element (also a list) corresponds to a cable knot, e.g. a list
+# [[1, 3], [2], [-1, -2], [-3]] encodes
+# T(2, 3; 2, 7) # T(2, 5) # -T(2, 3; 2, 5) # -T(2, 7).
+#
+# To calculate the number of characters for which signature function vanish use
+# the function .
+#
+# EXAMPLES::
+#
+# sage: eval_cable_for_null_signature([[1, 3], [2], [-1, -2], [-3]])
+#
+# T(2, 3; 2, 7) # T(2, 5) # -T(2, 3; 2, 5) # -T(2, 7)
+# Zero cases: 1
+# All cases: 1225
+# Zero theta combinations:
+# (0, 0, 0, 0)
+#
+# sage:
+#
+# The numbers given to the function eval_cable_for_null_signature are k-values
+# for each component/cable in a direct sum.
+#
+# To calculate signature function for a knot and a theta value, use function
+# get_signature_as_function_of_theta (see help/docstring for details).
+#
+# About notation:
+# Cables that we work with follow a schema:
+#     T(2, q_1; 2, q_2; 2, q_4) # -T(2, q_2; 2, q_4) #
+#             # T(2, q_3; 2, q_4) # -T(2, q_1; 2, q_3; 2, q_4)
+# In knot_formula each k[i] is related with some q_i value, where
+# q_i = 2*k[i] + 1.
+# So we can work in the following steps:
+# 1) choose a schema/formula by changing the value of knot_formula
+# 2) set each q_i all or choose range in which q_i should varry
+# 3) choose vector v / theta vector.
+#
+
 from .utility import import_sage
 import os
 
-#
+package = __name__.split('.')[0]
-# package = __name__.split('.')[0]
+path = os.path.dirname(__file__)
-# path = os.path.dirname(__file__)
+import_sage('signature', package=package, path=path)
-# import_sage('signature', package=package, path=path)
+import_sage('cable_signature', package=package, path=path)
-# import_sage('cable_signature', package=package, path=path)
+import_sage('main', package=package, path=path)
-# import_sage('main', package=package, path=path)

gaknot/cable_signature.sage

@@ -22,8 +22,7 @@ else:  # called from package
     path = '../'
 sg = import_sage('signature', package=package, path=path)
 
-
+# constants - which invariants should be calculate
-
 SIGMA = 0
 SIGNATURE = 1
 
@@ -569,6 +568,7 @@ class CableSum:
             print("Satellite part = {}".format(sigma[1]))
             print("Sigma = {} ~ {}\n".format(sigma[2], int(sigma[2])))
 
+    # function that proves the main lemma
     def is_function_big_for_all_metabolizers(self, invariant=SIGMA):
         num_of_summands = len(self.knot_sum_as_k_valus)
         if num_of_summands % 4:
@@ -576,11 +576,17 @@ class CableSum:
             msg = "Function {}".format(f_name) + " is implemented only for " +\
                   "knots that are direct sums of 4n direct summands."
             raise ValueError(msg)
-
+        # check each p-primary part separately
         for shift in range(0, num_of_summands, 4):
+            # set character (twist) to be zero for all summands
             ranges_list = num_of_summands * [range(0, 1)]
+            # change ranges for all but one character for current p-primary part
             ranges_list[shift : shift + 3] = \
                 [range(0, i + 1) for i in self.patt_k_list[shift: shift + 3]]
+            # change range for last character in current p-primary part
+            # this one is consider to be 0 or 1
+            # For any characters combinations (vectors) [a_1, a_2, a_3, a_4] where a_4 != 0
+            # exists such as k < p that k * a_4 % p == 1.
             ranges_list[shift + 3] = range(0, 2)
             if not self.is_function_big_in_ranges(ranges_list, invariant):
                 return False

gaknot/signature.sage

@@ -1,8 +1,7 @@
 #!/usr/bin/env sage -python
 
 import sys
-import os
+# import os
-
 from collections import Counter
 import matplotlib.pyplot as plt
 import inspect
@@ -12,6 +11,7 @@ import warnings
 from .utility import mod_one
 
 
+# check if used in Jupyter Notebook to show plots in proper way
 JUPYTER = 'ipykernel'
 IPy_TERMINAL = 'IPython'
 
@@ -25,11 +25,12 @@ def get_ipython_info():
 global ipython_info
 ipython_info = get_ipython_info()
 
+#
+#
 # 9.11 (9.8)
 # 9.15 (9.9)
 
 
-
 class SignatureFunction:
 
     def __init__(self, values=None, counter=None, plot_title=''):