Trac #20787: A class to manage Golay Codes

There are four types of Golay Codes, Extended Binary, Binary, Extended
Ternary and Ternary. The aim of this ticket is to refactor the current
methods for constructing these codes into one single Golay Code class
(based on the new API) that provides for combinatorial properties as
well as encoding and decoding algorithms for each type of Golay code.

URL: https://trac.sagemath.org/20787
Reported by: arpitdm
Ticket author(s): Arpit Merchant, David Lucas, Dima Pasechnik, Daniel
Augot
Reviewer(s): Dima Pasechnik, Daniel Augot

src/doc/en/constructions/linear_codes.rst

@@ -46,9 +46,9 @@ the four Golay codes
 
 ::
 
-    sage: C = codes.ExtendedTernaryGolayCode()
+    sage: C = codes.GolayCode(GF(3))
     sage: C
-    [12, 6] linear code over GF(3)
+    [12, 6, 6] Extended Golay code over Finite Field of size 3
     sage: C.minimum_distance()
     6
     sage: C.generator_matrix()

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

@@ -3,90 +3,114 @@
 Coding Theory
 =============
 
-Abstract classes, catalogs and databases
-----------------------------------------
+Basic Coding Theory objects
+---------------------------
+
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   sage/coding/linear_code
+   sage/coding/channel_constructions
    sage/coding/decoder
    sage/coding/encoder
-   sage/coding/bounds_catalog
+
+Catalogs
+--------
+
+.. toctree::
+   :maxdepth: 2
+
    sage/coding/channels_catalog
    sage/coding/codes_catalog
    sage/coding/decoders_catalog
    sage/coding/encoders_catalog
+   sage/coding/bounds_catalog
    sage/coding/databases
    sage/coding/two_weight_db
 
-Linear codes and related constructions
----------------------------------------
+Code constructions
+------------------
 
 .. toctree::
    :maxdepth: 1
 
-   sage/coding/binary_code
-   sage/coding/cyclic_code
    sage/coding/linear_code
+
+The named code families below are represented in Sage by their own classes,
+allowing specialised implementations of e.g. decoding or computation of properties:
+
+.. toctree::
+   :maxdepth: 2
+
    sage/coding/grs
    sage/coding/hamming_code
-   sage/coding/guruswami_sudan/gs_decoder
-   sage/coding/guruswami_sudan/interpolation
-   sage/coding/guruswami_sudan/utils
-   sage/coding/subfield_subcode
-   sage/coding/code_constructions
-   sage/coding/punctured_code
-   sage/coding/extended_code
-   sage/coding/self_dual_codes
-   sage/coding/guava
-   sage/coding/binary_code
-   sage/coding/reed_muller_code
+   sage/coding/golay_code
    sage/coding/parity_check_code
+   sage/coding/reed_muller_code
+   sage/coding/cyclic_code
 
-Bounds on codes
----------------
+In contrast, for some code families Sage can only construct their generator
+matrix and has no other a priori knowledge on them:
 
 .. toctree::
    :maxdepth: 1
 
-   sage/coding/code_bounds
-   sage/coding/delsarte_bounds
+   sage/coding/code_constructions
+   sage/coding/guava
+   sage/coding/self_dual_codes
+   sage/coding/binary_code
 
-Channels and related constructions
-----------------------------------
+Derived Code Constructions
+--------------------------
+
+Sage supports the following derived code constructions. If the constituent code
+is from a special code family, the derived codes inherit e.g. decoding or
+minimum distance capabilities:
 
 .. toctree::
    :maxdepth: 2
 
-   sage/coding/channel_constructions
+   sage/coding/subfield_subcode
+   sage/coding/punctured_code
+   sage/coding/extended_code
+
+Other derived constructions that simply produce the modified generator matrix
+can be found among the methods of a constructed code.
+
+Methods and Operations related to Linear Codes
+----------------------------------------------
 
-Source coding
--------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   sage/coding/source_coding/huffman
+   sage/coding/codecan/codecan
+   sage/coding/codecan/autgroup_can_label
 
-Canonical forms
----------------
+Source coding
+-------------
 
 .. toctree::
    :maxdepth: 1
 
-   sage/coding/codecan/codecan
-   sage/coding/codecan/autgroup_can_label
+   sage/coding/source_coding/huffman
 
-Other tools
------------
+Other modules
+-------------
 
 .. toctree::
    :maxdepth: 1
 
    sage/coding/relative_finite_field_extension
+   sage/coding/guruswami_sudan/gs_decoder
+   sage/coding/guruswami_sudan/interpolation
+   sage/coding/guruswami_sudan/utils
+   sage/coding/code_bounds
+   sage/coding/delsarte_bounds
 
 Deprecated modules
-------------------
+----------------------------
 
 .. toctree::
    :maxdepth: 1

src/sage/coding/all.py

@@ -1,13 +1,15 @@
 from __future__ import absolute_import
 
-from sage.misc.lazy_import import lazy_import
+from sage.misc.lazy_import import lazy_import as _lazy_import
 
-lazy_import("sage.coding.code_constructions", ["permutation_action",
+_lazy_import("sage.coding.code_constructions", ["permutation_action",
             "walsh_matrix"])
 
-from sage.misc.superseded import deprecated_callable_import
+from sage.misc.superseded import \
+    deprecated_callable_import as _deprecated_callable_import, \
+    deprecated_function_alias as _deprecated_function_alias
 
-deprecated_callable_import(19315,
+_deprecated_callable_import(19315,
             "sage.coding.code_bounds",
             globals(),
             locals(),
@@ -31,28 +33,38 @@
             ("This method soon will not be available in that way."
             "Please call codes.bounds.%(name)s instead"))
 
-lazy_import("sage.coding.linear_code", [
+_lazy_import("sage.coding.linear_code", [
             "LinearCode",
             "LinearCodeFromVectorSpace",
             "self_orthogonal_binary_codes"])
 
 # Functions removed from the global namespace
-lazy_import('sage.coding.databases','best_linear_code_in_guava', "best_known_linear_code",
+_lazy_import('sage.coding.databases','best_linear_code_in_guava', "best_known_linear_code",
     deprecation=(21165, "best_known_linear_code has moved to sage.coding.databases.best_linear_code_in_guava"))
-lazy_import('sage.coding.databases','best_linear_code_in_guava', "best_known_linear_code_www",
+_lazy_import('sage.coding.databases','best_linear_code_in_guava', "best_known_linear_code_www",
     deprecation=(21165, "best_known_linear_code_www has moved to sage.coding.databases.best_linear_code_in_guava"))
-lazy_import('sage.coding.databases','bounds_on_minimum_distance_in_guava', "bounds_minimum_distance",
+_lazy_import('sage.coding.databases','bounds_on_minimum_distance_in_guava', "bounds_minimum_distance",
     deprecation=(21165, "bounds_minimum_distance has moved to sage.coding.databases.bounds_on_minimum_distance_in_guava"))
-lazy_import('sage.coding.databases','self_orthogonal_binary_codes', "self_orthogonal_binary_codes",
+_lazy_import('sage.coding.databases','self_orthogonal_binary_codes', "self_orthogonal_binary_codes",
     deprecation=(21165, "self_orthogonal_binary_codes has moved to sage.coding.databases.self_orthogonal_binary_codes"))
-lazy_import('sage.coding.databases','self_dual_binary_codes', "self_dual_codes_binary",
+_lazy_import('sage.coding.databases','self_dual_binary_codes', "self_dual_codes_binary",
     deprecation=(21165, "self_dual_codes_binary has moved to sage.coding.databases.self_dual_binary_codes"))
 
-lazy_import("sage.coding.delsarte_bounds", [
-            "Krawtchouk",
-            "Kravchuk",
-            "delsarte_bound_hamming_space",
-            "delsarte_bound_additive_hamming_space"])
+_lazy_import('sage.coding.delsarte_bounds','krawtchouk', "Krawtchouk",
+    deprecation=(20908, "Krawtchouk will be removed from the global namespace. Please use codes.bounds.krawtchouk instead."))
+_lazy_import('sage.coding.delsarte_bounds','krawtchouk', "Kravchuk",
+    deprecation=(20908, "Kravchuk will be removed from the global namespace. Please use codes.bounds.krawtchouk instead."))
 
-lazy_import('sage.coding', 'codes_catalog', 'codes')
-lazy_import('sage.coding', 'channels_catalog', 'channels')
+_deprecated_callable_import(20908,
+            "sage.coding.delsarte_bounds",
+            globals(),
+            locals(),
+            ["delsarte_bound_hamming_space",
+             "delsarte_bound_additive_hamming_space"],
+            ("This function will soon be removed from the global namespace. "
+            "Please call it using codes.bounds.%(name)s instead"))
+
+
+
+_lazy_import('sage.coding', 'codes_catalog', 'codes')
+_lazy_import('sage.coding', 'channels_catalog', 'channels')

src/sage/coding/binary_code.pyx

@@ -1,5 +1,5 @@
 r"""
-Fast binary code routines
+Optimized low-level binary code representation
 
 Some computations with linear binary codes. Fix a basis for $GF(2)^n$.
 A linear binary code is a linear subspace of $GF(2)^n$, together with
@@ -1123,7 +1123,7 @@ cdef class BinaryCode:
         EXAMPLE::
 
             sage: from sage.coding.binary_code import *
-            sage: B = BinaryCode(codes.ExtendedBinaryGolayCode().generator_matrix())
+            sage: B = BinaryCode(codes.GolayCode(GF(2)).generator_matrix())
             sage: B
             Binary [24,12] linear code, generator matrix
             [100000000000101011100011]
@@ -3807,8 +3807,8 @@ cdef class BinaryCodeClassifier:
 
             sage: from sage.coding.binary_code import *
             sage: BC = BinaryCodeClassifier()
-            sage: B = BinaryCode(codes.ExtendedBinaryGolayCode().generator_matrix())
-            sage: B.apply_permutation(list(range(24,-1,-1)))
+            sage: B = BinaryCode(codes.GolayCode(GF(2)).generator_matrix())
+            sage: B.apply_permutation(range(24,-1,-1))
             sage: B
             Binary [24,12] linear code, generator matrix
             [011000111010100000000000]

src/sage/coding/bounds_catalog.py

@@ -1,5 +1,5 @@
 r"""
-Index of bounds
+Index of bounds on the parameters of codes
 
 The ``codes.bounds`` object may be used to access the bounds that Sage can compute.
 
@@ -30,6 +30,12 @@
             "elias_bound_asymp",
             "mrrw1_bound_asymp"])
 
+_lazy_import("sage.coding.delsarte_bounds",
+            ["krawtchouk",
+             "delsarte_bound_hamming_space",
+             "delsarte_bound_additive_hamming_space"])
+
+
 from sage.misc.rest_index_of_methods import gen_rest_table_index as _gen_rest_table_index
 import sys as _sys
 __doc__ = __doc__.format(INDEX_OF_FUNCTIONS=_gen_rest_table_index(_sys.modules[__name__], only_local_functions=False))

src/sage/coding/channel_constructions.py

@@ -1,5 +1,5 @@
 r"""
-Channels
+Base class for Channels and commonly used channels
 
 Given an input space and an output space, a channel takes element from
 the input space (the message) and transforms it into an element of the output space

src/sage/coding/channels_catalog.py

@@ -1,12 +1,11 @@
 r"""
-Index of channels
+Index of Channels: the information theoretic notion of transmission
 
 The ``channels`` object may be used to access the codes that Sage can build.
 
-- :func:`channel_constructions.ErrorErasureChannel <sage.coding.channel_constructions.ErrorErasureChannel>`
-- :func:`channel_constructions.StaticErrorRateChannel <sage.coding.channel_constructions.StaticErrorRateChannel>`
-
-- :func:`channel_constructions.QarySymmetricChannel <sage.coding.channel_constructions.QarySymmetricChannel>`
+- :class:`channel_constructions.ErrorErasureChannel <sage.coding.channel_constructions.ErrorErasureChannel>`
+- :class:`channel_constructions.QarySymmetricChannel <sage.coding.channel_constructions.QarySymmetricChannel>`
+- :class:`channel_constructions.StaticErrorRateChannel <sage.coding.channel_constructions.StaticErrorRateChannel>`
 
 .. NOTE::
 
@@ -15,6 +14,17 @@
         sage: from sage.coding.channels_catalog import *
 
 """
+#*****************************************************************************
+#       Copyright (C) 2015 David Lucas <david.lucas@inria.fr>
+#
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or later (at your preference).
+#
+#                  http://www.gnu.org/licenses/
+#*****************************************************************************
 from __future__ import absolute_import
 
-from .channel_constructions import (ErrorErasureChannel, StaticErrorRateChannel, QarySymmetricChannel)
+from sage.misc.lazy_import import lazy_import as _lazy_import
+_lazy_import('sage.coding.channel_constructions', ['ErrorErasureChannel',
+                                                   'QarySymmetricChannel',
+                                                   'StaticErrorRateChannel'])