Trac #18928: A new structure for Reed-Solomon codes in Sage

This ticket proposes a new implementation for Generalized Reed-Solomon
codes in Sage.
It contains:

- a new code class, `GeneralizedReedSolomonCode`, which wraps Reed-
Solomon code in the object-oriented structure introduced in #18099,
- a first new encoder, `GRSEvaluationVectorEncoder`, which can encode
words from a message space which is a vector space, and
- a second new encoder, `GRSEvaluationPolynomialEncoder`, which can
encode words from a message space which is a polynomial ring.

This new implementation properly sets GRS codes in the object-oriented
structure, which allows the user to use specific methods and algorithms
to encode (and later decode) words. It also introduces the notion of
generalized Reed-Solomon codes, which means that the user can now set a
list of column multipliers for the code.

It also allows to compute parity-check matrix and generator matrix from
the parameters of the code, through dedicated methods. It allows super-
fast computation of certain - usually exponential - properties, such as
weight distribution.

As GRS codes are now objects in Sage, it is also possible to ask a GRS
code for its specific parameters (like the list of its evaluation
points, or its column multipliers).

The two provided encoders follow the structure introduced in #18376.

This ticket also removes the old `ReedSolomonCode` method from the
global namespace as it was deprecated more than a year ago (see #15445).

More details about GRS codes can be found in the docstring of the
provided code.

URL: http://trac.sagemath.org/18928
Reported by: dlucas
Ticket author(s): David Lucas, Johan Sebastian Rosenkilde Nielsen
Reviewer(s): Johan Sebastian Rosenkilde Nielsen, David Lucas

Author: Release Manager

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

@@ -13,6 +13,7 @@ Coding Theory
    sage/coding/channel_constructions
    sage/coding/channels_catalog
    sage/coding/codes_catalog
+   sage/coding/grs
    sage/coding/linear_code
    sage/coding/code_constructions
    sage/coding/guava

src/doc/en/thematic_tutorials/coding_theory.rst

@@ -577,10 +577,8 @@ Python:
    applied to the ambient ``MatrixSpace`` of the generator matrix until a
    full rank matrix is found.
 
--  ``ReedSolomonCode`` - Also called a "generalized Reed-Solomon code" (the
-   "narrow" RS codes codes are also cyclic codes; they are part of GUAVA
-   but have not been ported over to natice Python/Sage yet). Given a
-   finite field :math:`\mathbb{F}` of order :math:`q`, let :math:`n` and
+-  ``GeneralizedReedSolomonCode`` - Given a finite field :math:`\mathbb{F}`
+   of order :math:`q`, let :math:`n` and
    :math:`k` be chosen such that :math:`1 \leq k \leq n \leq q`. Pick
    :math:`n` distinct elements of :math:`\mathbb{F}`, denoted
    :math:`\{ x_1, x_2, ... , x_n \}`. Then, the codewords are obtained
@@ -597,31 +595,28 @@ Python:
 
    INPUT:
 
-   -  ``n`` : the length
+    - ``evaluation_points`` -- A list of evaluation points in a finite field F
 
-   -  ``k`` : the dimension
+    - ``dimension`` -- The dimension of the code
 
-   -  ``F`` : the base ring
-
-   -  ``pts`` : (optional) list of :math:`n` points in :math:`\mathbb{F}` (if
-      omitted then Sage  picks :math:`n` of them in the order given to
-      the elements of :math:`\mathbb{F}`)
+    - ``column_multipliers`` -- (default: ``None``) List of column multipliers in F for this code.
+      All column multipliers are set to 1 if default value is kept.
 
    EXAMPLES:
 
    ::
 
 
-         sage: C = codes.ReedSolomonCode(6,4,GF(7)); C
-         Linear code of length 6, dimension 4 over Finite Field of size 7
+         sage: C = codes.GeneralizedReedSolomonCode(GF(7).list()[:6], 4); C
+         [6, 4, 3] Generalized Reed-Solomon Code over Finite Field of size 7
          sage: C.minimum_distance()
          3
          sage: F.<a> = GF(3^2,"a")
          sage: pts = [0,1,a,a^2,2*a,2*a+1]
          sage: len(Set(pts)) == 6 # to make sure there are no duplicates
          True
-         sage: C = codes.ReedSolomonCode(6,4,F,pts); C
-         Linear code of length 6, dimension 4 over Finite Field in a of size 3^2
+         sage: C = codes.GeneralizedReedSolomonCode(pts, 4); C
+         [6, 4, 3] Generalized Reed-Solomon Code over Finite Field in a of size 3^2
          sage: C.minimum_distance()
          3
 

src/sage/coding/all.py

@@ -4,6 +4,7 @@
             "walsh_matrix"])
 
 from sage.misc.superseded import deprecated_callable_import
+
 deprecated_callable_import(19315,
             "sage.coding.code_bounds",
             globals(),

src/sage/coding/code_constructions.py

@@ -1202,54 +1202,10 @@ def RandomLinearCode(n,k,F):
 
 
 def ReedSolomonCode(n,k,F,pts = None):
-    r"""
-    Given a finite field `F` of order `q`, let
-    `n` and `k` be chosen such that
-    `1 \leq k \leq n \leq q`. Pick `n` distinct
-    elements of `F`, denoted
-    `\{ x_1, x_2, ... , x_n \}`. Then, the codewords are
-    obtained by evaluating every polynomial in `F[x]` of degree
-    less than `k` at each `x_i`:
-
-    .. math::
-
-       C = \left\{ \left( f(x_1), f(x_2), ..., f(x_n) \right), f \in F[x],
-       {\rm deg}(f)<k \right\}.
-
-
-    `C` is a `[n, k, n-k+1]` code. (In particular, `C` is MDS.)
-
-    INPUT: n : the length k : the dimension F : the base ring pts :
-    (optional) list of n points in F (if None then Sage picks n of them
-    in the order given to the elements of F)
-
-    EXAMPLES::
-
-        sage: C = codes.ReedSolomonCode(6,4,GF(7)); C
-        Linear code of length 6, dimension 4 over Finite Field of size 7
-        sage: C.minimum_distance()
-        3
-        sage: C = codes.ReedSolomonCode(6,4,GF(8,"a")); C
-        Linear code of length 6, dimension 4 over Finite Field in a of size 2^3
-        sage: C.minimum_distance()
-        3
-        sage: C.minimum_distance(algorithm='gap') # long time, check d=n-k+1
-        3
-        sage: F.<a> = GF(3^2,"a")
-        sage: pts = [0,1,a,a^2,2*a,2*a+1]
-        sage: len(Set(pts)) == 6 # to make sure there are no duplicates
-        True
-        sage: C = codes.ReedSolomonCode(6,4,F,pts); C
-        Linear code of length 6, dimension 4 over Finite Field in a of size 3^2
-        sage: C.minimum_distance()
-        3
-
-    REFERENCES:
-
-    - [W] http://en.wikipedia.org/wiki/Reed-Solomon
-    """
+    from sage.misc.superseded import deprecation
+    from sage.coding.grs import GeneralizedReedSolomonCode
+    deprecation(18928, "codes.ReedSolomonCode is now deprecated. Please use codes.GeneralizedReedSolomonCode instead.")
     q = F.order()
-    power = lambda x,n,F: (x==0 and n==0) and F(1) or F(x**n) # since 0^0 is undefined
     if n>q or k>n or k>q:
         raise ValueError("RS codes does not exist with the given input.")
     if pts is not None and len(pts) != n:
@@ -1261,11 +1217,7 @@ def ReedSolomonCode(n,k,F,pts = None):
             if i<n:
                 pts.append(x)
                 i = i+1
-    MS = MatrixSpace(F, k, n)
-    rowsG = []
-    rowsG = [[power(x,j,F) for x in pts] for j in range(k)]
-    G = MS(rowsG)
-    return LinearCode(G, d=n-k+1)
+    return GeneralizedReedSolomonCode(pts, k)
 
 
 def TernaryGolayCode():

src/sage/coding/codes_catalog.py

@@ -28,6 +28,8 @@
                                 ReedSolomonCode, TernaryGolayCode,
                                 ToricCode, TrivialCode, WalshCode)
 
+from grs import GeneralizedReedSolomonCode
+
 from guava import BinaryReedMullerCode, QuasiQuadraticResidueCode, RandomLinearCodeGuava
 
 import decoders_catalog as decoders

src/sage/coding/encoder.py

@@ -142,12 +142,11 @@ def unencode(self, c, nocheck=False):
 
         INPUT:
 
-        - ``c`` -- a vector of the same length as :meth:`code` over the
-          base field of :meth:`code`.
+        - ``c`` -- a codeword of :meth:`code`.
 
-        - ``nocheck`` -- (default: ``False``) checks if ``c`` is in ``self``. You might set
+        - ``nocheck`` -- (default: ``False``) checks if ``c`` is in :meth:`code`. You might set
           this to ``True`` to disable the check for saving computation. Note that if ``c`` is
-          not in ``self`` and ``nocheck = True``, then the output of :meth:`unencode` is
+          not in :meth:`self` and ``nocheck = True``, then the output of :meth:`unencode` is
           not defined (except that it will be in the message space of ``self``).
 
         OUTPUT:
@@ -231,12 +230,12 @@ def unencode_nocheck(self, c):
 
         INPUT:
 
-        - ``c`` -- a vector of the same length as ``self`` over the
-          base field of ``self``
+
+        - ``c`` -- a codeword of :meth:`code`.
 
         OUTPUT:
 
-        - a vector
+        - an element of the message space of ``self``.
 
         EXAMPLES::
 

src/sage/coding/encoders_catalog.py

@@ -3,8 +3,15 @@
 
 The ``codes.encoders`` object may be used to access the encoders that Sage can build.
 
+**Generic encoders**
+
 :class:`linear_code.LinearCodeGeneratorMatrixEncoder <sage.coding.linear_code.LinearCodeGeneratorMatrixEncoder>`
 
+**Generalized Reed-Solomon code encoders**
+
+- :class:`grs.GRSEvaluationVectorEncoder <sage.coding.grs.GRSEvaluationVectorEncoder>`
+- :class:`grs.GRSEvaluationPolynomialEncoder <sage.coding.grs.GRSEvaluationPolynomialEncoder>`
+
 .. NOTE::
 
     To import these names into the global namespace, use:
@@ -23,3 +30,4 @@
 
 from sage.misc.lazy_import import lazy_import as _lazy_import
 _lazy_import('sage.coding.linear_code', 'LinearCodeGeneratorMatrixEncoder')
+_lazy_import('sage.coding.grs', ['GRSEvaluationVectorEncoder', 'GRSEvaluationPolynomialEncoder'])