Trac #19930: A proper class for Hamming codes

`codes.HammingCode` is not a constructor for a class, but a method which
builds a generic linear code.

This ticket proposes a class implementation of Hamming codes, using the
API introduced in #18099 which properly sets Hamming codes as a class.
It also comes with a new generic encoder for codes built from a parity
check matrix.

URL: http://trac.sagemath.org/19930
Reported by: dlucas
Ticket author(s): David Lucas
Reviewer(s): Clément Pernet

Author: Release Manager

src/doc/en/constructions/linear_codes.rst

@@ -22,9 +22,9 @@ Sage can compute Hamming codes
 
 ::
 
-    sage: C = codes.HammingCode(3,GF(3))
+    sage: C = codes.HammingCode(GF(3), 3)
     sage: C
-    Linear code of length 13, dimension 10 over Finite Field of size 3
+    [13, 10] Hamming Code over Finite Field of size 3
     sage: C.minimum_distance()
     3
     sage: C.generator_matrix()
@@ -74,10 +74,10 @@ a check matrix, and the dual code:
 
 ::
 
-    sage: C = codes.HammingCode(3,GF(2))
+    sage: C = codes.HammingCode(GF(2), 3)
     sage: Cperp = C.dual_code()
     sage: C; Cperp
-    Linear code of length 7, dimension 4 over Finite Field of size 2
+    [7, 4] Hamming Code over Finite Field of size 2
     Linear code of length 7, dimension 3 over Finite Field of size 2
     sage: C.generator_matrix()
       [1 0 0 0 0 1 1]
@@ -90,7 +90,7 @@ a check matrix, and the dual code:
       [0 0 0 1 1 1 1]
     sage: C.dual_code()
     Linear code of length 7, dimension 3 over Finite Field of size 2
-    sage: C = codes.HammingCode(3,GF(4,'a'))
+    sage: C = codes.HammingCode(GF(4,'a'), 3)
     sage: C.dual_code()
     Linear code of length 21, dimension 3 over Finite Field in a of size 2^2
 
@@ -102,7 +102,7 @@ implemented.
 
 ::
 
-    sage: C = codes.HammingCode(3,GF(2))
+    sage: C = codes.HammingCode(GF(2), 3)
     sage: MS = MatrixSpace(GF(2),1,7)
     sage: F = GF(2); a = F.gen()
     sage: v = vector([a,a,F(0),a,a,F(0),a])
@@ -116,9 +116,9 @@ can use the matplotlib package included with Sage:
 
 ::
 
-    sage: C = codes.HammingCode(4,GF(2))
+    sage: C = codes.HammingCode(GF(2), 4)
     sage: C
-     Linear code of length 15, dimension 11 over Finite Field of size 2
+    [15, 11] Hamming Code over Finite Field of size 2
     sage: w = C.weight_distribution(); w
      [1, 0, 0, 35, 105, 168, 280, 435, 435, 280, 168, 105, 35, 0, 0, 1]
     sage: J = range(len(w))

src/doc/en/reference/coding/index.rst

@@ -26,6 +26,7 @@ Linear codes and related constructions
 
    sage/coding/binary_code
    sage/coding/grs
+   sage/coding/hamming_code
    sage/coding/guruswami_sudan/gs_decoder
    sage/coding/guruswami_sudan/interpolation
    sage/coding/guruswami_sudan/rootfinding

src/sage/coding/binary_code.pyx

@@ -861,7 +861,7 @@ cdef class BinaryCode:
         """
         cdef int i, j
         from sage.matrix.constructor import matrix
-        from sage.rings.all import GF
+        from sage.rings.finite_rings.finite_field_constructor import GF
         rows = []
         for i from 0 <= i < self.nrows:
             row = [0]*self.ncols
@@ -4226,7 +4226,7 @@ cdef class BinaryCodeClassifier:
                                 break
                         if bingo2:
                             from sage.matrix.constructor import Matrix
-                            from sage.rings.all import GF
+                            from sage.rings.finite_rings.finite_field_constructor import GF
                             M = Matrix(GF(2), B_aug.nrows, B_aug.ncols)
                             for i from 0 <= i < B_aug.ncols:
                                 for j from 0 <= j < B_aug.nrows:

src/sage/coding/code_constructions.py

@@ -7,8 +7,9 @@
 
 All codes available here can be accessed through the ``codes`` object::
 
-    sage: codes.HammingCode(3,GF(2))
-    Linear code of length 7, dimension 4 over Finite Field of size 2
+    sage: codes.HammingCode(GF(2), 3)
+    [7, 4] Hamming Code over Finite Field of size 2
+
 
 Let `F` be a finite field with `q` elements.
 Here's a constructive definition of a cyclic code of length
@@ -907,53 +908,6 @@ def ExtendedTernaryGolayCode():
     # C = TernaryGolayCode()
     # return C.extended_code()
 
-def HammingCode(r,F):
-    r"""
-    Implements the Hamming codes.
-
-    The `r^{th}` Hamming code over `F=GF(q)` is an
-    `[n,k,d]` code with length `n=(q^r-1)/(q-1)`,
-    dimension `k=(q^r-1)/(q-1) - r` and minimum distance
-    `d=3`. The parity check matrix of a Hamming code has rows
-    consisting of all nonzero vectors of length r in its columns,
-    modulo a scalar factor so no parallel columns arise. A Hamming code
-    is a single error-correcting code.
-
-    INPUT:
-
-
-    -  ``r`` - an integer 2
-
-    -  ``F`` - a finite field.
-
-
-    OUTPUT: Returns the r-th q-ary Hamming code.
-
-    EXAMPLES::
-
-        sage: codes.HammingCode(3,GF(2))
-        Linear code of length 7, dimension 4 over Finite Field of size 2
-        sage: C = codes.HammingCode(3,GF(3)); C
-        Linear code of length 13, dimension 10 over Finite Field of size 3
-        sage: C.minimum_distance()
-        3
-        sage: C.minimum_distance(algorithm='gap') # long time, check d=3
-        3
-        sage: C = codes.HammingCode(3,GF(4,'a')); C
-        Linear code of length 21, dimension 18 over Finite Field in a of size 2^2
-    """
-    q = F.order()
-    n =  (q**r-1)/(q-1)
-    k = n-r
-    MS = MatrixSpace(F,n,r)
-    X = ProjectiveSpace(r-1,F)
-    PFn = [list(p) for p in X.point_set(F).points(F)]
-    H = MS(PFn).transpose()
-    Cd = LinearCode(H)
-    # Hamming code always has distance 3, so we provide the distance.
-    return LinearCode(Cd.dual_code().generator_matrix(), d=3)
-
-
 def LinearCodeFromCheckMatrix(H):
     r"""
     A linear [n,k]-code C is uniquely determined by its generator
@@ -975,18 +929,22 @@ def LinearCodeFromCheckMatrix(H):
 
     EXAMPLES::
 
-        sage: C = codes.HammingCode(3,GF(2))
+        sage: C = codes.HammingCode(GF(2), 3)
         sage: H = C.parity_check_matrix(); H
         [1 0 1 0 1 0 1]
         [0 1 1 0 0 1 1]
         [0 0 0 1 1 1 1]
-        sage: codes.LinearCodeFromCheckMatrix(H) == C
+        sage: Gh = codes.LinearCodeFromCheckMatrix(H).generator_matrix()
+        sage: Gc = C.generator_matrix_systematic()
+        sage: Gh == Gc
         True
-        sage: C = codes.HammingCode(2,GF(3))
+        sage: C = codes.HammingCode(GF(3), 2)
         sage: H = C.parity_check_matrix(); H
         [1 0 1 1]
         [0 1 1 2]
-        sage: codes.LinearCodeFromCheckMatrix(H) == C
+        sage: Gh = codes.LinearCodeFromCheckMatrix(H).generator_matrix()
+        sage: Gc = C.generator_matrix_systematic()
+        sage: Gh == Gc
         True
         sage: C = codes.RandomLinearCode(10,5,GF(4,"a"))
         sage: H = C.parity_check_matrix()

src/sage/coding/codecan/autgroup_can_label.pyx

@@ -47,7 +47,7 @@ REFERENCES:
 EXAMPLES::
 
     sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-    sage: C = codes.HammingCode(3, GF(3)).dual_code()
+    sage: C = codes.HammingCode(GF(3), 3).dual_code()
     sage: P = LinearCodeAutGroupCanLabel(C)
     sage: P.get_canonical_form().generator_matrix()
     [1 0 0 0 0 1 1 1 1 1 1 1 1]
@@ -63,7 +63,7 @@ EXAMPLES::
 
 If the dimension of the dual code is smaller, we will work on this code::
 
-    sage: C2 = codes.HammingCode(3, GF(3))
+    sage: C2 = codes.HammingCode(GF(3), 3)
     sage: P2 = LinearCodeAutGroupCanLabel(C2)
     sage: P2.get_canonical_form().parity_check_matrix() == P.get_canonical_form().generator_matrix()
     True
@@ -72,7 +72,7 @@ There is a specialization of this algorithm to pass a coloring on the
 coordinates. This is just a list of lists, telling the algorithm which
 columns do share the same coloring::
 
-    sage: C = codes.HammingCode(3, GF(4, 'a')).dual_code()
+    sage: C = codes.HammingCode(GF(4, 'a'), 3).dual_code()
     sage: P = LinearCodeAutGroupCanLabel(C, P=[ [0], [1], range(2, C.length()) ])
     sage: P.get_autom_order()
     864
@@ -169,7 +169,7 @@ class LinearCodeAutGroupCanLabel:
     EXAMPLES::
 
         sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-        sage: C = codes.HammingCode(3, GF(3)).dual_code()
+        sage: C = codes.HammingCode(GF(3), 3).dual_code()
         sage: P = LinearCodeAutGroupCanLabel(C)
         sage: P.get_canonical_form().generator_matrix()
         [1 0 0 0 0 1 1 1 1 1 1 1 1]
@@ -206,7 +206,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(2)).dual_code()
+            sage: C = codes.HammingCode(GF(2), 3).dual_code()
             sage: P = LinearCodeAutGroupCanLabel(C)
             sage: P.get_canonical_form().generator_matrix()
             [1 0 0 0 1 1 1]
@@ -220,9 +220,9 @@ class LinearCodeAutGroupCanLabel:
             [0 0 1 0 1 1 1]
         """
         from sage.groups.semimonomial_transformations.semimonomial_transformation_group import SemimonomialTransformationGroup
-        from sage.coding.linear_code import LinearCode
+        from sage.coding.linear_code import LinearCode, AbstractLinearCode
 
-        if not isinstance(C, LinearCode):
+        if not isinstance(C, AbstractLinearCode):
             raise TypeError("%s is not a linear code"%C)
 
         self.C = C
@@ -531,7 +531,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(3)).dual_code()
+            sage: C = codes.HammingCode(GF(3), 3).dual_code()
             sage: CF1 = LinearCodeAutGroupCanLabel(C).get_canonical_form()
             sage: s = SemimonomialTransformationGroup(GF(3), C.length()).an_element()
             sage: C2 = LinearCode(s*C.generator_matrix())
@@ -548,7 +548,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(2)).dual_code()
+            sage: C = codes.HammingCode(GF(2), 3).dual_code()
             sage: P = LinearCodeAutGroupCanLabel(C)
             sage: g = P.get_transporter()
             sage: D = P.get_canonical_form()
@@ -564,7 +564,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(2)).dual_code()
+            sage: C = codes.HammingCode(GF(2), 3).dual_code()
             sage: A = LinearCodeAutGroupCanLabel(C).get_autom_gens()
             sage: Gamma = C.generator_matrix().echelon_form()
             sage: all([(g*Gamma).echelon_form() == Gamma for g in A])
@@ -579,7 +579,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(2)).dual_code()
+            sage: C = codes.HammingCode(GF(2), 3).dual_code()
             sage: LinearCodeAutGroupCanLabel(C).get_autom_order()
             168
         """
@@ -599,7 +599,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(4, 'a')).dual_code()
+            sage: C = codes.HammingCode(GF(4, 'a'), 3).dual_code()
             sage: A = LinearCodeAutGroupCanLabel(C).get_PGammaL_gens()
             sage: Gamma = C.generator_matrix()
             sage: N = [ x.monic() for x in Gamma.columns() ]
@@ -628,7 +628,7 @@ class LinearCodeAutGroupCanLabel:
         EXAMPLES::
 
             sage: from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel
-            sage: C = codes.HammingCode(3, GF(4, 'a')).dual_code()
+            sage: C = codes.HammingCode(GF(4, 'a'), 3).dual_code()
             sage: LinearCodeAutGroupCanLabel(C).get_PGammaL_order() == GL(3, GF(4, 'a')).order()*2/3
             True
         """

src/sage/coding/codecan/codecan.pyx

@@ -60,7 +60,7 @@ EXAMPLES:
 Get the canonical form of the Simplex code::
 
     sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-    sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+    sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
     sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
     sage: cf = P.get_canonical_form(); cf
     [1 0 0 0 0 1 1 1 1 1 1 1 1]
@@ -466,7 +466,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
     EXAMPLES::
 
         sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-        sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+        sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
         sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
         sage: cf = P.get_canonical_form(); cf
         [1 0 0 0 0 1 1 1 1 1 1 1 1]
@@ -493,7 +493,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
         """
         self._k = generator_matrix.nrows()
@@ -533,7 +533,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
         """
         self._run(P, algorithm_type)
@@ -559,7 +559,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: PartitionRefinementLinearCode(mat.ncols(), mat)
             Canonical form algorithm for linear code generated by
             [1 0 1 1 0 1 0 1 1 1 0 1 1]
@@ -577,7 +577,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat) #indirect doctest
             sage: P.get_canonical_form()
             [1 0 0 0 0 1 1 1 1 1 1 1 1]
@@ -663,7 +663,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P1 = PartitionRefinementLinearCode(mat.ncols(), mat)
             sage: CF1 = P1.get_canonical_form()
             sage: s = SemimonomialTransformationGroup(GF(3), mat.ncols()).an_element()
@@ -681,7 +681,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
             sage: CF = P.get_canonical_form()
             sage: t = P.get_transporter()
@@ -697,7 +697,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
             sage: A = P.get_autom_gens()
             sage: all( [(a*mat).echelon_form() == mat.echelon_form() for a in A])
@@ -713,7 +713,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic):
         EXAMPLES::
 
             sage: from sage.coding.codecan.codecan import PartitionRefinementLinearCode
-            sage: mat = codes.HammingCode(3, GF(3)).dual_code().generator_matrix()
+            sage: mat = codes.HammingCode(GF(3), 3).dual_code().generator_matrix()
             sage: P = PartitionRefinementLinearCode(mat.ncols(), mat)
             sage: P.get_autom_order_inner_stabilizer()
             2

src/sage/coding/codes_catalog.py

@@ -22,7 +22,7 @@
                                 CyclicCode, CyclicCodeFromCheckPolynomial, DuadicCodeEvenPair,
                                 DuadicCodeOddPair, ExtendedBinaryGolayCode,
                                 ExtendedQuadraticResidueCode, ExtendedTernaryGolayCode,
-                                HammingCode, LinearCode, LinearCodeFromCheckMatrix,
+                                LinearCode, LinearCodeFromCheckMatrix,
                                 QuadraticResidueCode, QuadraticResidueCodeEvenPair,
                                 QuadraticResidueCodeOddPair, RandomLinearCode,
                                 ReedSolomonCode, TernaryGolayCode,
@@ -31,6 +31,7 @@
 from grs import GeneralizedReedSolomonCode
 
 from guava import BinaryReedMullerCode, QuasiQuadraticResidueCode, RandomLinearCodeGuava
+from hamming_code import HammingCode
 
 import decoders_catalog as decoders
 import encoders_catalog as encoders