Base class for Encoders

Representation of a bijection between a message space and a code.

class sage.coding.encoder.Encoder(code)

Bases: sage.structure.sage_object.SageObject

Abstract top-class for Encoder objects.

Every encoder class should inherit from this abstract class.

To implement an encoder, you need to:

  • inherit from Encoder,
  • call Encoder.__init__ in the subclass constructor. Example: super(SubclassName, self).__init__(code). By doing that, your subclass will have its code parameter initialized.
  • Then, if the message space is a vector space, default implementations of encode() and unencode_nocheck() methods are provided. These implementations rely on generator_matrix() which you need to override to use the default implementations.
  • If the message space is not of the form \(F^k\), where \(F\) is a finite field, you cannot have a generator matrix. In that case, you need to override encode(), unencode_nocheck() and message_space().
  • By default, comparison of Encoder (using methods __eq__ and __ne__ ) are by memory reference: if you build the same encoder twice, they will be different. If you need something more clever, override __eq__ and __ne__ in your subclass.
  • As Encoder is not designed to be instantiated, it does not have any representation methods. You should implement _repr_ and _latex_ methods in the subclass.

REFERENCES:

code()

Returns the code for this Encoder.

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: C = LinearCode(G)
sage: E = C.encoder()
sage: E.code() == C
True
encode(word)

Transforms an element of the message space into a codeword.

This is a default implementation which assumes that the message space of the encoder is \(F^{k}\), where \(F\) is sage.coding.linear_code.AbstractLinearCode.base_field() and \(k\) is sage.coding.linear_code.AbstractLinearCode.dimension(). If this is not the case, this method should be overwritten by the subclass.

Note

encode() might be a partial function over self’s message_space(). One should use the exception EncodingError to catch attempts to encode words that are outside of the message space.

One can use the following shortcut to encode a word with an encoder E:

E(word)

INPUT:

  • word – a vector of the message space of the self.

OUTPUT:

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: C = LinearCode(G)
sage: word = vector(GF(2), (0, 1, 1, 0))
sage: E = codes.encoders.LinearCodeGeneratorMatrixEncoder(C)
sage: E.encode(word)
(1, 1, 0, 0, 1, 1, 0)

If word is not in the message space of self, it will return an exception:

sage: word = random_vector(GF(7), 4)
sage: E.encode(word)
Traceback (most recent call last):
...
ArithmeticError: reduction modulo 2 not defined
generator_matrix()

Returns a generator matrix of the associated code of self.

This is an abstract method and it should be implemented separately. Reimplementing this for each subclass of Encoder is not mandatory (as a generator matrix only makes sense when the message space is of the \(F^k\), where \(F\) is the base field of code().)

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: C = LinearCode(G)
sage: E = C.encoder()
sage: E.generator_matrix()
[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]
message_space()

Returns the ambient space of allowed input to encode(). Note that encode() is possibly a partial function over the ambient space.

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: C = LinearCode(G)
sage: E = C.encoder()
sage: E.message_space()
Vector space of dimension 4 over Finite Field of size 2
unencode(c, nocheck=False)

Return the message corresponding to the codeword c.

This is the inverse of encode().

INPUT:

  • c – a codeword of code().
  • nocheck – (default: False) checks if c is in 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 unencode() is not defined (except that it will be in the message space of self).

OUTPUT:

  • an element of the message space of 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: C = LinearCode(G)
sage: c = vector(GF(2), (1, 1, 0, 0, 1, 1, 0))
sage: c in C
True
sage: E = codes.encoders.LinearCodeGeneratorMatrixEncoder(C)
sage: E.unencode(c)
(0, 1, 1, 0)
unencode_nocheck(c)

Returns the message corresponding to c.

When c is not a codeword, the output is unspecified.

AUTHORS:

This function is taken from codinglib [Nie]

INPUT:

OUTPUT:

  • an element of the message space of 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: C = LinearCode(G)
sage: c = vector(GF(2), (1, 1, 0, 0, 1, 1, 0))
sage: c in C
True
sage: E = codes.encoders.LinearCodeGeneratorMatrixEncoder(C)
sage: E.unencode_nocheck(c)
(0, 1, 1, 0)

Taking a vector that does not belong to C will not raise an error but probably just give a non-sensical result:

sage: c = vector(GF(2), (1, 1, 0, 0, 1, 1, 1))
sage: c in C
False
sage: E = codes.encoders.LinearCodeGeneratorMatrixEncoder(C)
sage: E.unencode_nocheck(c)
(0, 1, 1, 0)
sage: m = vector(GF(2), (0, 1, 1, 0))
sage: c1 = E.encode(m)
sage: c == c1
False
exception sage.coding.encoder.EncodingError

Bases: exceptions.Exception

Special exception class to indicate an error during encoding or unencoding.