Clean up coding section

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

@@ -3,20 +3,23 @@
 Coding Theory
 =============
 
-Basic Coding Theory objects
----------------------------
+Coding theory is the mathematical theory for algebraic and combinatorial codes
+used for forward error correction in communications theory. Sage provides an
+extensive library of objects and algorithms in coding theory.
 
+Basic objects in coding theory are channels, linear codes, encoders, and
+decoders. The following modules provide the base classes defining them.
 
 .. toctree::
    :maxdepth: 1
 
    sage/coding/linear_code
    sage/coding/channel_constructions
-   sage/coding/decoder
    sage/coding/encoder
+   sage/coding/decoder
 
-Catalogs
---------
+Catalogs for available constructions of the basic objects and for bounds on
+the parameters of linear codes are provided.
 
 .. toctree::
    :maxdepth: 2
@@ -26,30 +29,24 @@ Catalogs
    sage/coding/decoders_catalog
    sage/coding/encoders_catalog
    sage/coding/bounds_catalog
-   sage/coding/databases
-   sage/coding/two_weight_db
-
-Code constructions
-------------------
 
-.. toctree::
-   :maxdepth: 1
-
-   sage/coding/linear_code
+Families of Codes
+-----------------
 
-The named code families below are represented in Sage by their own classes,
-allowing specialised implementations of e.g. decoding or computation of properties:
+Famous families of codes, listed below, are represented in Sage by their own
+classes. For some of them, implementations of special decoding algorithms or
+computations for structural invariants are available.
 
 .. toctree::
    :maxdepth: 2
 
-   sage/coding/grs
+   sage/coding/parity_check_code
    sage/coding/hamming_code
+   sage/coding/cyclic_code
+   sage/coding/bch_code
    sage/coding/golay_code
-   sage/coding/parity_check_code
    sage/coding/reed_muller_code
-   sage/coding/cyclic_code
-   sage/coding/bch
+   sage/coding/grs_code
 
 In contrast, for some code families Sage can only construct their generator
 matrix and has no other a priori knowledge on them:
@@ -62,12 +59,12 @@ matrix and has no other a priori knowledge on them:
    sage/coding/self_dual_codes
    sage/coding/binary_code
 
-Derived Code Constructions
+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:
+is from a special code family, the derived codes inherit structural properties
+like decoding radius or minimum distance:
 
 .. toctree::
    :maxdepth: 2
@@ -79,37 +76,67 @@ minimum distance capabilities:
 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
-----------------------------------------------
+Decoding
+--------
 
+Information-set decoding for linear codes:
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/coding/information_set_decoder
+
+Guruswami-Sudan interpolation-based list decoding for Reed-Solomon codes:
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/coding/guruswami_sudan/gs_decoder
+   sage/coding/guruswami_sudan/interpolation
+   sage/coding/guruswami_sudan/utils
+
+Automorphism Groups of Linear Codes
+-----------------------------------
 
 .. toctree::
    :maxdepth: 2
 
    sage/coding/codecan/codecan
    sage/coding/codecan/autgroup_can_label
 
-Source coding
--------------
+Bounds for Parameters of Linear Codes
+-------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   sage/coding/code_bounds
+   sage/coding/delsarte_bounds
+
+Databases for Coding Theory
+---------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   sage/coding/databases
+   sage/coding/two_weight_db
+
+Miscellaneous Modules
+---------------------
+
+There is at least one module in Sage for source coding in communications theory:
 
 .. toctree::
    :maxdepth: 1
 
    sage/coding/source_coding/huffman
 
-Other modules
--------------
+Finally an experimental module used for code constructions:
 
 .. 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/information_set_decoder
-   sage/coding/code_bounds
-   sage/coding/delsarte_bounds
-
 
 .. include:: ../footer.txt

src/doc/en/thematic_tutorials/coding_theory.rst

@@ -316,7 +316,7 @@ we can now ask for specific encoder and decoder::
     sage: Evect
     Evaluation vector-style encoder for [40, 12, 29] Generalized Reed-Solomon Code over GF(59)
     sage: type(Evect)
-    <class 'sage.coding.grs.GRSEvaluationVectorEncoder'>
+    <class 'sage.coding.grs_code.GRSEvaluationVectorEncoder'>
     sage: msg = random_vector(GF(59), C.dimension()) #random
     sage: c = Evect.encode(msg)
     sage: NN = C.decoder("NearestNeighbor")

src/sage/coding/bch.py → src/sage/coding/bch_code.py

@@ -1,16 +1,16 @@
 r"""
-BCH Code
+BCH code
 
-Let `F = GF(q)` and `\Phi` be the splitting field of `x^{n} - 1` over `F`,
-with `n` a positive integer. Let also `\alpha` be an element of multiplicative
-order `n` in `\Phi`. Finally, let `b, \delta, \ell` be integers such that
-`0 \le b \le n`, `1 \le \delta \le n` and `\alpha^\ell` generates the
-multiplicative group `\Phi^{\times}`.
+Let `F = GF(q)` and `\Phi` be the splitting field of `x^{n} - 1` over `F`, with
+`n` a positive integer. Let also `\alpha` be an element of multiplicative order
+`n` in `\Phi`. Finally, let `b, \delta, \ell` be integers such that `0 \le b
+\le n`, `1 \le \delta \le n` and `\alpha^\ell` generates the multiplicative
+group `\Phi^{\times}`.
 
 A BCH code over `F` with designed distance `\delta` is a cyclic code whose
 codewords `c(x) \in F[x]` satisfy `c(\alpha^{a}) = 0`, for all integers `a` in
-the arithmetic sequence
-`b, b + \ell, b + 2 \times \ell, \dots, b + (\delta - 2) \times \ell`.
+the arithmetic sequence `b, b + \ell, b + 2 \times \ell, \dots, b + (\delta -
+2) \times \ell`.
 
 TESTS:
 
@@ -23,11 +23,13 @@
     sage: Fqm.<aa> = GF(16)
     sage: Fq.<a> = GF(4)
     sage: RelativeFiniteFieldExtension(Fqm, Fq)
-    doctest:...: FutureWarning: This class/method/function is marked as experimental. It, its functionality or its interface might change without a formal deprecation.
+    doctest:...: FutureWarning: This class/method/function is marked as
+    experimental. It, its functionality or its interface might change without a
+    formal deprecation.
     See http://trac.sagemath.org/20284 for details.
-    Relative field extension between Finite Field in aa of size 2^4 and Finite Field in a of size 2^2
+    Relative field extension between Finite Field in aa of size 2^4 and Finite
+    Field in a of size 2^2
 """
-
 # *****************************************************************************
 #       Copyright (C) 2016 David Lucas <david.lucas@inria.fr>
 #                     2017 Julien Lavauzelle <julien.lavauzelle@inria.fr>
@@ -38,17 +40,17 @@
 # (at your option) any later version.
 #                  https://www.gnu.org/licenses/
 # *****************************************************************************
+from copy import copy
 
-from .cyclic_code import CyclicCode
-from .grs import GeneralizedReedSolomonCode
-from .decoder import Decoder
 from sage.modules.free_module_element import vector
 from sage.misc.misc_c import prod
 from sage.categories.fields import Fields
 from sage.arith.all import gcd
 from sage.rings.all import Zmod
-from copy import copy
 
+from .cyclic_code import CyclicCode
+from .grs_code import GeneralizedReedSolomonCode
+from .decoder import Decoder
 
 class BCHCode(CyclicCode):
     r"""
@@ -272,7 +274,7 @@ def bch_to_grs(self):
 class BCHUnderlyingGRSDecoder(Decoder):
     r"""
     A decoder which decodes through the underlying
-    :class:`sage.coding.grs.GeneralizedReedSolomonCode` code of the provided
+    :class:`sage.coding.grs_code.GeneralizedReedSolomonCode` code of the provided
     BCH code.
 
     INPUT:
@@ -448,7 +450,7 @@ def decode_to_code(self, y):
             (a, a + 1, 1, a + 1, 1, a, a + 1, a + 1, 0, 1, a + 1, 1, 1, 1, a)
             sage: D.decode_to_code(y) in C
             True
-        
+
         We check that it still works when, while list-decoding, the GRS decoder
         output some words which do not lie in the BCH code::
 

src/sage/coding/binary_code.pyx

@@ -736,6 +736,17 @@ cdef class BinaryCode:
 
     """
     def __cinit__(self, arg1, arg2=None):
+        """
+        Initialize.
+
+        TESTS::
+
+            sage: import sage.coding.binary_code
+            sage: from sage.coding.binary_code import *
+            sage: M = Matrix(GF(2), [[1,1,1,1]])
+            sage: B = BinaryCode(M)
+            sage: TestSuite(B).run()
+        """
         cdef int nrows, i, j, size
         cdef int nwords, other_nwords, parity, combination
         cdef codeword word, glue_word
@@ -1259,6 +1270,16 @@ cdef class OrbitPartition:
 
     """
     def __cinit__(self, int nrows, int ncols):
+        """
+        Initialize.
+
+        TESTS::
+
+            sage: import sage.coding.binary_code
+            sage: from sage.coding.binary_code import *
+            sage: O = OrbitPartition(4, 8)
+            sage: TestSuite(O).run(skip='_test_pickling')
+        """
         cdef int col
         cdef int nwords, word
         nwords = (1 << nrows)
@@ -1558,6 +1579,16 @@ cdef class PartitionStack:
     group computation.
     """
     def __cinit__(self, arg1, arg2=None):
+        """
+        Initialize.
+
+        TESTS::
+
+            sage: import sage.coding.binary_code
+            sage: from sage.coding.binary_code import *
+            sage: P = PartitionStack(2, 6)
+            sage: TestSuite(P).run(skip='_test_pickling')
+        """
         cdef int k, nwords, ncols, sizeof_int
         cdef PartitionStack other = None
         cdef int *wd_ents
@@ -3047,6 +3078,16 @@ cdef class PartitionStack:
 cdef class BinaryCodeClassifier:
 
     def __cinit__(self):
+        """
+        Initialize.
+
+        TESTS::
+
+            sage: import sage.coding.binary_code
+            sage: from sage.coding.binary_code import *
+            sage: BC = BinaryCodeClassifier()
+            sage: TestSuite(BC).run(skip='_test_pickling')
+        """
         self.radix = sizeof(codeword) << 3
         self.ham_wts = hamming_weights()
         self.L = 100 # memory limit for Phi and Omega- multiply by 8KB

src/sage/coding/channel_constructions.py

@@ -1,8 +1,8 @@
 r"""
-Base class for Channels and commonly used channels
+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
+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
 (the transmitted message).
 
 In Sage, Channels simulate error-prone transmission over communication
@@ -273,22 +273,22 @@ def output_space(self):
     @abstract_method
     def transmit_unsafe(self, message):
         r"""
-        Returns ``message``, modified accordingly with the algorithm of the channel it was
+        Return ``message``, modified accordingly with the algorithm of the channel it was
         transmitted through.
 
         This method does not check if ``message`` belongs to the input space of``self``.
 
         This is an abstract method which should be reimplemented in all the subclasses of
         Channel.
-        """
-
-
-
-
-
-
 
+        EXAMPLES::
 
+            sage: n_err = 2
+            sage: Chan = channels.StaticErrorRateChannel(GF(59)^6, n_err)
+            sage: v = Chan.input_space().random_element()
+            sage: Chan.transmit_unsafe(v)  # random
+            (1, 33, 46, 18, 20, 49)
+        """
 
 
 class StaticErrorRateChannel(Channel):
@@ -649,14 +649,6 @@ def number_erasures(self):
         return self._number_erasures
 
 
-
-
-
-
-
-
-
-
 class QarySymmetricChannel(Channel):
     r"""
     The q-ary symmetric, memoryless communication channel.
@@ -670,9 +662,9 @@ class QarySymmetricChannel(Channel):
 
     Though `\Sigma` is usually taken to be a finite field, this implementation
     allows any structure for which Sage can represent `\Sigma^n` and for which
-    `\Sigma` has a `random_element()` method. However, beware that if `\Sigma`
+    `\Sigma` has a ``random_element()`` method. However, beware that if `\Sigma`
     is infinite, errors will not be uniformly distributed (since
-    `random_element()` does not draw uniformly at random).
+    ``random_element()`` does not draw uniformly at random).
 
     The input space and the output space of this channel are the same:
     `\Sigma^n`.