Trac #21226: An Abstract Class for Rank Metric Codes

We propose to implement `AbstractRankMetricCode`, an abstract class for
rank metric codes which will initialize the basic parameters that every
rank metric code possesses. This will inherit from `AbstractCode` class.
Further, we propose to add rank-metric based methods to compute
distance, weight and allow for matrix to vector (and reverse)
conversions between representations. Finally, we create a generic
representative class `LinearRankMetricCode` as well as encoding
(generator matrix, systematic) and decoding (nearest neighbour) methods.

URL: https://trac.sagemath.org/21226
Reported by: arpitdm
Ticket author(s): Arpit Merchant, Marketa Slukova, Johan Rosenkilde
Reviewer(s): Dima Pasechnik, Johan Rosenkilde, Xavier Caruso

Author: Release Manager

src/sage/coding/linear_code.py

@@ -1158,60 +1158,6 @@ def construction_x(self, other, aux):
         G = left.augment(right)
         return LinearCode(G)
 
-    def __eq__(self, right):
-        """
-        Checks if ``self`` is equal to ``right``.
-
-        EXAMPLES::
-
-            sage: C1 = codes.HammingCode(GF(2), 3)
-            sage: C2 = codes.HammingCode(GF(2), 3)
-            sage: C1 == C2
-            True
-
-        TESTS:
-
-        We check that :trac:`16644` is fixed::
-
-            sage: C = codes.HammingCode(GF(2), 3)
-            sage: C == ZZ
-            False
-        """
-        if not (isinstance(right, LinearCode)\
-                and self.length() == right.length()\
-                and self.dimension() == right.dimension()\
-                and self.base_ring() == right.base_ring()):
-            return False
-        Ks = self.parity_check_matrix().right_kernel()
-        rbas = right.gens()
-        if not all(c in Ks for c in rbas):
-            return False
-        Kr = right.parity_check_matrix().right_kernel()
-        sbas = self.gens()
-        if not all(c in Kr for c in sbas):
-            return False
-        return True
-
-    def __ne__(self, other):
-        r"""
-        Tests inequality of ``self`` and ``other``.
-
-        This is a generic implementation, which returns the inverse of ``__eq__`` for self.
-
-        EXAMPLES::
-
-            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,0,1]])
-            sage: C1 = LinearCode(G)
-            sage: C2 = LinearCode(G)
-            sage: C1 != C2
-            False
-            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,1,1]])
-            sage: C2 = LinearCode(G)
-            sage: C1 != C2
-            True
-        """
-        return not self == other
-
     def extended_code(self):
         r"""
         Returns `self` as an extended code.

src/sage/coding/linear_code_no_metric.py

@@ -157,6 +157,22 @@ def __init__(self, base_field, length, default_encoder_name, default_decoder_nam
         - ``default_decoder_name`` -- the name of the default decoder of ``self``
 
         - ``metric`` -- (default: ``Hamming``) the metric of ``self``
+
+        EXAMPLES:
+
+            sage: from sage.coding.linear_code_no_metric import AbstractLinearCodeNoMetric
+            sage: from sage.coding.linear_code import LinearCodeSyndromeDecoder
+            sage: class MyLinearCode(AbstractLinearCodeNoMetric):
+            ....:   def __init__(self, field, length, dimension, generator_matrix):
+            ....:       self._registered_decoders['Syndrome'] = LinearCodeSyndromeDecoder
+            ....:       AbstractLinearCodeNoMetric.__init__(self, field, length, "Systematic", "Syndrome")
+            ....:       self._dimension = dimension
+            ....:       self._generator_matrix = generator_matrix
+            ....:   def generator_matrix(self):
+            ....:       return self._generator_matrix
+            ....:   def _repr_(self):
+            ....:       return "[%d, %d] dummy code over GF(%s)" % (self.length(), self.dimension(), self.base_field().cardinality())
+            sage: C = MyLinearCode(GF(2), 1, 1, matrix(GF(2), [1]))
         """
 
         self._registered_encoders['Systematic'] = LinearCodeSystematicEncoder
@@ -227,7 +243,63 @@ def generator_matrix(self, encoder_name=None, **kwargs):
         return E.generator_matrix()
 
     def __eq__(self, other):
-        return self.generator_matrix() == other.generator_matrix()
+        r"""
+        Tests equality between two linear codes.
+
+        EXAMPLES::
+
+            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,0,1]])
+            sage: C1 = LinearCode(G)
+            sage: C1 == 5
+            False
+            sage: C2 = LinearCode(G)
+            sage: C1 == C2
+            True
+            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,1,1]])
+            sage: C2 = LinearCode(G)
+            sage: C1 == C2
+            False
+            sage: G = Matrix(GF(3), [[1,2,1,0,0,0,0]])
+            sage: C3 = LinearCode(G)
+            sage: C1 == C3
+            False
+        """
+        # Fail without computing the generator matrix if possible:
+        if not (isinstance(other, AbstractLinearCodeNoMetric)\
+                and self.length() == other.length()\
+                and self.dimension() == other.dimension()\
+                and self.base_ring() == other.base_ring()):
+            return False
+        # Check that basis elements of `other` are all in `self.`
+        # Since we're over a field and since the dimensions match, the codes
+        # must be equal.
+        # This implementation may avoid linear algebra altogether, if `self`
+        # implements an efficient way to obtain a parity check matrix, and in
+        # the worst case does only one system solving.
+        for c in other.gens():
+            if not (c in self):
+                return False
+        return True
+
+    def __ne__(self, other):
+        r"""
+        Tests inequality of ``self`` and ``other``.
+
+        This is a generic implementation, which returns the inverse of ``__eq__`` for self.
+
+        EXAMPLES::
+
+            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,0,1]])
+            sage: C1 = LinearCode(G)
+            sage: C2 = LinearCode(G)
+            sage: C1 != C2
+            False
+            sage: G = Matrix(GF(2), [[1,1,1,0,0,0,0],[1,0,0,1,1,0,0],[0,1,0,1,0,1,0],[1,1,0,1,0,1,1]])
+            sage: C2 = LinearCode(G)
+            sage: C1 != C2
+            True
+        """
+        return not self == other
 
     def dimension(self):
         r"""

src/sage/coding/linear_rank_metric.py

@@ -153,8 +153,8 @@ def to_matrix_representation(v, sub_field=None, basis=None):
 
     - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
       ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+      `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+      represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
     EXAMPLES::
 
@@ -204,8 +204,8 @@ def from_matrix_representation(w, base_field=None, basis=None):
 
     - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
       ``F_q``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+      `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+      represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
     EXAMPLES::
 
@@ -247,8 +247,8 @@ def rank_weight(c, sub_field=None, basis=None):
 
     - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
       ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+      `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+      represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
     EXAMPLES::
 
@@ -284,8 +284,8 @@ def rank_distance(a, b, sub_field=None, basis=None):
 
     - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
       ``sub_field``. If not specified, given that `q = p^s`, let
-      `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-      represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+      `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+      represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
     EXAMPLES::
 
@@ -386,8 +386,8 @@ def __init__(self, base_field, sub_field, length, default_encoder_name,
 
         - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
           ``sub_field``. If not specified, given that `q = p^s`, let
-          `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-          represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+          `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+          represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
         EXAMPLES:
 
@@ -558,10 +558,11 @@ def minimum_distance(self):
 
         EXAMPLES::
 
-            sage: G = Matrix(GF(64), [[1,1,0], [0,0,1]])
-            sage: C = codes.LinearRankMetricCode(G, GF(4))
+            sage: F.<a> = GF(8)
+            sage: G = Matrix(F, [[1,a,a^2,0]])
+            sage: C = codes.LinearRankMetricCode(G, GF(2))
             sage: C.minimum_distance()
-            1
+            3
         """
         d = Infinity
         for c in self:
@@ -681,8 +682,8 @@ def __init__(self, generator, sub_field=None, basis=None):
 
         - ``basis`` -- (default: ``None``) a basis of `F_{q^m}` as a vector space over
           ``sub_field``. If not specified, given that `q = p^s`, let
-          `1,\beta,\ldots,\beta^{sm}` be the power basis that SageMath uses to
-          represent `F_{q^m}`. The default basis is then `1,\beta,\ldots,beta^{m-1}`.
+          `1,β,\ldots,β^{sm}` be the power basis that SageMath uses to
+          represent `F_{q^m}`. The default basis is then `1,β,\ldots,β^{m-1}`.
 
         EXAMPLES::
 
@@ -860,6 +861,15 @@ def decode_to_code(self, r):
         OUTPUT:
 
         - a vector of ``self``'s message space
+
+        EXAMPLES::
+
+            sage: F.<a> = GF(4)
+            sage: G = Matrix(F, [[1,1,0]])
+            sage: C = codes.LinearRankMetricCode(G, GF(2))
+            sage: D = codes.decoders.LinearRankMetricCodeNearestNeighborDecoder(C)
+            sage: D.decode_to_code(vector(F, [a, a, 1]))
+            (a, a, 0)
         """
         C = self.code()
         c_min = C.zero()
@@ -877,11 +887,12 @@ def decoding_radius(self):
 
         EXAMPLES::
 
-            sage: G = Matrix(GF(64), [[1,1,0], [0,0,1]])
-            sage: C = codes.LinearRankMetricCode(G, GF(4))
+            sage: F.<a> = GF(8)
+            sage: G = Matrix(F, [[1,a,a^2,0]])
+            sage: C = codes.LinearRankMetricCode(G, GF(2))
             sage: D = codes.decoders.LinearRankMetricCodeNearestNeighborDecoder(C)
             sage: D.decoding_radius()
-            0
+            1
         """
         return (self.code().minimum_distance()-1) // 2