## `GUAVA`

A &GAP;4 Package for computing with error-correcting codes
Version 2
Jasper Cramwinckel
Erik Roijackers
Reinald Baart
Eric Minkes
Lea Ruscio
David Joyner

    	 Mathematics Department,

    	 U. S. Naval Academy,

    	 Annapolis, MD,

             21402 USA.

wdj@usna.edu http://cadigweb.ew.usna.edu/~wdj/gap/GUAVA/
December 27, 2004
GUAVA
is released under the GNU General Public License (GPL). This file is part of `GUAVA`, though as documentation it is released under the GNU Free Documentation License (see http://www.gnu.org/licenses/licenses.html#FDL).

GUAVA
is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

GUAVA
is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with `GUAVA`; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details, see http://www.fsf.org/licenses/gpl.html.

GUAVA
was originally written by Jasper Cramwinckel, Erik Roijackers, and Reinald Baart in the early-to-mid 1990's as a final project during their study of Mathematics at the Delft University of Technology, Department of Pure Mathematics, under the direction of Professor Juriaan Simonis. This work was continued in Aachen, at Lehrstuhl D fur Mathematik. In version 1.3, new functions were added by Eric Minkes, also from Delft University of Technology.

JC, ER and RB would like to thank the &GAP; people at the RWTH Aachen for their support, A.E. Brouwer for his advice and J. Simonis for his supervision.

The &GAP; 4 version of `GUAVA` (versions 1.4 and 1.5) was created by Lea Ruscio and (since 2001, starting with version 1.6) is currently maintained by David Joyner, who (with the help of several students) has added several new functions. For further details, see the CHANGES file in the `GUAVA` directory, also available at http://cadigweb.ew.usna.edu/~wdj/gap/GUAVA/CHANGES.guava.

This documentation was prepared with the `GAPDoc` package of Frank L\"ubeck and Max Neunh\"offer. The conversion from TeX to `GAPDoc`'s XML was done by David Joyner in 2004.

Please send bug reports, suggestions and other comments about `GUAVA` to support@gap-system.org. Currently known bugs and suggested `GUAVA` projects are listed on the bugs and projects web page http://cadigweb.ew.usna.edu/~wdj/gap/GUAVA/guava2do.html. Older releases and further history can be found on the `GUAVA` web page http://cadigweb.ew.usna.edu/~wdj/gap/GUAVA/.

Contributors
: Other than the authors listed on the title page, the following people have contributed code to the `GUAVA` project: Alexander Hulpke, Steve Linton, Frank L\"ubeck, Aron Foster, Wayne Irons, Clifton (``Clipper") Lennon, Jason McGowan, Shuhong Gao, and, indirectly, Jeffrey Leon, Joe Nicely.

Introduction
Introduction to the `GUAVA` package

This is the manual of the &GAP; package `GUAVA` that provides implementations of some routines designed for the construction and analysis of in the theory of error-correcting codes.

The functions can be divided into three subcategories:

Construction of codes: `GUAVA` can construct unrestricted, linear and cyclic codes. Information about the code, such as operations applicable to the code, is stored in a record-like data structure called a &GAP; object.
Manipulations of codes: Manipulation transforms one code into another, or constructs a new code from two codes. The new code can profit from the data in the record of the old code(s), so in these cases calculation time decreases.
Computations of information about codes: `GUAVA` can calculate important parameters of codes quickly. The results are stored in the codes' object components.

Except for the automorphism group and isomorphism testing functions, which make use of J.S. Leon's programs (see and the documentation in the 'src' subdirectory of the 'guava' directory for some details), `GUAVA` is written in the &GAP; language, and runs on any system supporting &GAP;4.3 and above. Several algorithms that need the speed were integrated in the &GAP; kernel.

Good general references for error-correcting codes and the technical terms in this manual are MacWilliams and Sloane Huffman and Pless .

Installing `GUAVA`

To install `GUAVA` (as a &GAP; 4 Package) unpack the archive file in a directory in the `pkg' hierarchy of your version of &GAP; 4.

After unpacking `GUAVA` the &GAP;-only part of `GUAVA` is installed. The parts of `GUAVA` depending on J. Leon's backtrack programs package (for computing automorphism groups) are only available in a UNIX environment, where you should proceed as follows: Go to the newly created `guava' directory and call `./configure /gappath' where /gappath is the path to the &GAP; home directory. So for example, if you install the package in the main `pkg' directory call

./configure ../..
This will fetch the architecture type for which &GAP; has been compiled last and create a `Makefile'. Now call

make

to compile the binary and to install it in the appropriate place. (For a windows machine with CYGWIN installed - see http://www.cygwin.com/ - instructions for compiling Leon's binaries are likely to be similar to those above. On a 64-bit SUSE linux computer, instead of the configure command above - which will only compile the 32-bit binary - type ./configure ../.. --enable-libsuffix=64 make to compile Leon's program as a 64 bit native binary. This may also work for other 64-bit linux distributions as well.)

This completes the installation of `GUAVA` for a single architecture. If you use this installation of `GUAVA` on different hardware platforms you will have to compile the binary for each platform separately.

Loading `GUAVA`

After starting up &GAP;, the `GUAVA` package needs to be loaded. Load `GUAVA` by typing at the &GAP; prompt:

gap> LoadPackage( "guava", "2.0", false );

If `GUAVA` isn't already in memory, it is loaded and the author information is displayed. If you are a frequent user of `GUAVA`, you might consider putting this line in your `.gaprc' file.

Codewords

Let GF(q) denote a finite field with q (a prime power) elements. A code is a subset C of some finite-dimensional vector space V over GF(q). The length of C is the dimension of V. Usually, V=GF(q)^n and the length is the number of coordinate entries. When C is itself a vector space over GF(q) then it is called a linear code linear code and the dimension of C is its dimension as a vector space over GF(q).

In `GUAVA`, a `codeword' is a &GAP; record, with one of its components being an element in V. Likewise, a `code' is a &GAP; record, with one of its components being a subset (or subspace with given basis, if C is linear) of V.

gap> C:=RandomLinearCode(20,10,GF(4)); a [20,10,?] randomly generated code over GF(4) gap> c:=Random(C); [ 1 a 0 0 0 1 1 a^2 0 0 a 1 1 1 a 1 1 a a 0 ] gap> NamesOfComponents(C); [ "LeftActingDomain", "GeneratorsOfLeftOperatorAdditiveGroup", "WordLength", "GeneratorMat", "name", "Basis", "NiceFreeLeftModule", "Dimension", "Representative", "ZeroImmutable" ] gap> NamesOfComponents(c); [ "VectorCodeword", "WordLength", "treatAsPoly" ] gap> c!.VectorCodeword; [ immutable compressed vector length 20 over GF(4) ] gap> Display(last); [ Z(2^2), Z(2^2), Z(2^2), Z(2)^0, Z(2^2), Z(2^2)^2, 0*Z(2), Z(2^2), Z(2^2), Z(2)^0, Z(2^2)^2, 0*Z(2), 0*Z(2), Z(2^2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2^2)^2, Z(2)^0, 0*Z(2) ] gap> C!.Dimension; 10

Mathematically, a `codeword' is an element of a code C, but in `GUAVA` the Codeword and VectorCodeword commands have implementations which do not check if the codeword belongs to C (i.e., are independent of the code itself). They exist primarily to make it easier for the user to construct a the associated &GAP; record. Using these commands, one can enter into a &GAP; both a codeword c (belonging to C) and a received word r (not belonging to C) using the same command. The user can input codewords in different formats (as strings, vectors, and polynomials), and output information is formatted in a readable way.

A codeword c in a linear code C arises in practice by an initial encoding of a 'block' message m, adding enough redundancy to recover m after c is transmitted via a 'noisy' communication medium. In `GUAVA`, for linear codes, the map m\longmapsto c is computed using the command c:=m*C and recovering m from c is obtained by the command InformationWord(c,C). These commands are explained more below.

Many operations are available on codewords themselves, although codewords also work together with codes (see chapter on Codes).

The first section describes how codewords are constructed (see and ). Sections and describe the arithmetic operations applicable to codewords. Section describe functions that convert codewords back to vectors or polynomials (see and ). Section describe functions that change the way a codeword is displayed (see and ). Finally, Section describes a function to generate a null word (see ) and some functions for extracting properties of codewords (see , and ).

Construction of Codewords
Codeword
returns a codeword or a list of codewords constructed from obj. The object obj can be a vector, a string, a polynomial or a codeword. It may also be a list of those (even a mixed list).

If a number n is specified, all constructed codewords have length n. This is the only way to make sure that all elements of obj are converted to codewords of the same length. Elements of obj that are longer than n are reduced in length by cutting of the last positions. Elements of obj that are shorter than n are lengthened by adding zeros at the end. If no n is specified, each constructed codeword is handled individually.

If a Galois field F is specified, all codewords are constructed over this field. This is the only way to make sure that all elements of obj are converted to the same field F (otherwise they are converted one by one). Note that all elements of obj must have elements over F or over `Integers'. Converting from one Galois field to another is not allowed. If no F is specified, vectors or strings with integer elements will be converted to the smallest Galois field possible.

Note that a significant speed increase is achieved if F is specified, even when all elements of obj already have elements over F.

Every vector in obj can be a finite field vector over F or a vector over `Integers'. In the last case, it is converted to F or, if omitted, to the smallest Galois field possible.

Every string in obj must be a string of numbers, without spaces, commas or any other characters. These numbers must be from 0 to 9. The string is converted to a codeword over F or, if F is omitted, over the smallest Galois field possible. Note that since all numbers in the string are interpreted as one-digit numbers, Galois fields of size larger than 10 are not properly represented when using strings. In fact, no finite field of size larger than 11 arises in this fashion at all.

Every polynomial in obj is converted to a codeword of length n or, if omitted, of a length dictated by the degree of the polynomial. If F is specified, a polynomial in obj must be over F.

Every element of obj that is already a codeword is changed to a codeword of length n. If no n was specified, the codeword doesn't change. If F is specified, the codeword must have base field F.

gap> c := Codeword([0,1,1,1,0]); [ 0 1 1 1 0 ] gap> VectorCodeword( c ); [ 0*Z(2), Z(2)^0, Z(2)^0, Z(2)^0, 0*Z(2) ] gap> c2 := Codeword([0,1,1,1,0], GF(3)); [ 0 1 1 1 0 ] gap> VectorCodeword( c2 ); [ 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, 0*Z(3) ] gap> Codeword([c, c2, "0110"]); [ [ 0 1 1 1 0 ], [ 0 1 1 1 0 ], [ 0 1 1 0 ] ] gap> p := UnivariatePolynomial(GF(2), [Z(2)^0, 0*Z(2), Z(2)^0]); Z(2)^0+x_1^2 gap> Codeword(p); x^2 + 1

This command can also be called using the syntax Codeword(obj,C). In this format, the elements of obj are converted to elements of the same ambient vector space as the elements of a code C. The command Codeword(c,C) is the same as calling Codeword(c,n,F), where n is the word length of C and the F is the ground field of C.
gap> C := WholeSpaceCode(7,GF(5)); a cyclic [7,7,1]0 whole space code over GF(5) gap> Codeword(["0220110", [1,1,1]], C); [ [ 0 2 2 0 1 1 0 ], [ 1 1 1 0 0 0 0 ] ] gap> Codeword(["0220110", [1,1,1]], 7, GF(5)); [ [ 0 2 2 0 1 1 0 ], [ 1 1 1 0 0 0 0 ] ] gap> C:=RandomLinearCode(10,5,GF(3)); a linear [10,5,1..3]3..5 random linear code over GF(3) gap> Codeword("1000000000",C); [ 1 0 0 0 0 0 0 0 0 0 ] gap> Codeword("1000000000",10,GF(3)); [ 1 0 0 0 0 0 0 0 0 0 ]
CodewordNr
returns a list of codewords of C. list may be a list of integers or a single integer. For each integer of list, the corresponding codeword of C is returned. The correspondence of a number i with a codeword is determined as follows: if a list of elements of C is available, the i^{th} element is taken. Otherwise, it is calculated by multiplication of the i^{th} information vector by the generator matrix or generator polynomial, where the information vectors are ordered lexicographically. In particular, the returned codeword(s) could be a vector or a polynomial.

So CodewordNr(C, i) is equal to AsSSortedList(C)[i], described in the next chapter. The latter function first calculates the set of all the elements of C and then returns the i^{th} element of that set, whereas the former only calculates the i^{th} codeword.
gap> B := BinaryGolayCode(); a cyclic [23,12,7]3 binary Golay code over GF(2) gap> c := CodewordNr(B, 4); x^22 + x^20 + x^17 + x^14 + x^13 + x^12 + x^11 + x^10 gap> R := ReedSolomonCode(2,2); a cyclic [2,1,2]1 Reed-Solomon code over GF(3) gap> AsSSortedList(R); [ [ 0 0 ], [ 1 1 ], [ 2 2 ] ] gap> CodewordNr(R, [1,3]); [ [ 0 0 ], [ 2 2 ] ]
IsCodeword
returns `true' if obj, which can be an object of arbitrary type, is of the codeword type and `false' otherwise. The function will signal an error if obj is an unbound variable.
gap> IsCodeword(1); false gap> IsCodeword(ReedMullerCode(2,3)); false gap> IsCodeword("11111"); false gap> IsCodeword(Codeword("11111")); true
Comparisons of Codewords
The equality operator c1 = c2 evaluates to `true' if the codewords c1 and c2 are equal, and to `false' otherwise. Note that codewords are equal if and only if their base vectors are equal. Whether they are represented as a vector or polynomial has nothing to do with the comparison.

Comparing codewords with objects of other types is not recommended, although it is possible. If c2 is the codeword, the other object c1 is first converted to a codeword, after which comparison is possible. This way, a codeword can be compared with a vector, polynomial, or string. If c1 is the codeword, then problems may arise if c2 is a polynomial. In that case, the comparison always yields a `false', because the polynomial comparison is called.

The equality operator is also denoted EQ, and EQ(c1,c2) is the same as c1 = c2. There is also an inequality operator, &tlt; &tgt;, or not EQ.

not =
&tlt; &tgt;
gap> P := UnivariatePolynomial(GF(2), Z(2)*[1,0,0,1]); Z(2)^0+x_1^3 gap> c := Codeword(P, GF(2)); x^3 + 1 gap> P = c; # codeword operation true gap> c2 := Codeword("1001", GF(2)); [ 1 0 0 1 ] gap> c = c2; true gap> C:=HammingCode(3); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> c1:=Random(C); [ 1 0 0 1 1 0 0 ] gap> c2:=Random(C); [ 0 1 0 0 1 0 1 ] gap> EQ(c1,c2); false gap> not EQ(c1,c2); true
Arithmetic Operations for Codewords
The following operations are always available for codewords. The operands must have a common base field, and must have the same length. No implicit conversions are performed. codewords, addition

The operator + evaluates to the sum of the codewords c1 and c2.
gap> C:=RandomLinearCode(10,5,GF(3)); a linear [10,5,1..3]3..5 random linear code over GF(3) gap> c:=Random(C); [ 1 0 2 2 2 2 1 0 2 0 ] gap> Codeword(c+"2000000000"); [ 0 0 2 2 2 2 1 0 2 0 ] gap> Codeword(c+"1000000000");
The last command return a &GAP; ERROR since the `codeword' which `GUAVA` associates to "1000000000" belongs to GF(2) and not GF(3).

Similar to addition: the operator - evaluates to the difference of the codewords c1 and c2. codewords, subtraction
The operator v+C evaluates to the coset code of code C after adding a `codeword' v to all codewords in C. Note that if c \in C then mathematically c+C=C but `GUAVA` only sees them equal as sets. See .

Note that the command C+v returns the same output as the command v+C.

codewords, cosets
coset
gap> C:=RandomLinearCode(10,5); a [10,5,?] randomly generated code over GF(2) gap> c:=Random(C); [ 0 0 0 0 0 0 0 0 0 0 ] gap> c+C; [ add. coset of a [10,5,?] randomly generated code over GF(2) ] gap> c+C=C; true gap> IsLinearCode(c+C); false gap> v:=Codeword("100000000"); [ 1 0 0 0 0 0 0 0 0 ] gap> v+C; [ add. coset of a [10,5,?] randomly generated code over GF(2) ] gap> C=v+C; false gap> C := GeneratorMatCode( [ [1, 0,0,0], [0, 1,0,0] ], GF(2) ); a linear [4,2,1]1 code defined by generator matrix over GF(2) gap> Elements(C); [ [ 0 0 0 0 ], [ 0 1 0 0 ], [ 1 0 0 0 ], [ 1 1 0 0 ] ] gap> v:=Codeword("0011"); [ 0 0 1 1 ] gap> C+v; [ add. coset of a linear [4,2,4]1 code defined by generator matrix over GF(2) ] gap> Elements(C+v); [ [ 0 0 1 1 ], [ 0 1 1 1 ], [ 1 0 1 1 ], [ 1 1 1 1 ] ]

In general, the operations just described can also be performed on codewords expressed as vectors, strings or polynomials, although this is not recommended. The vector, string or polynomial is first converted to a codeword, after which the normal operation is performed. For this to go right, make sure that at least one of the operands is a codeword. Further more, it will not work when the right operand is a polynomial. In that case, the polynomial operations (FiniteFieldPolynomialOps) are called, instead of the codeword operations (CodewordOps).

Some other code-oriented operations with codewords are described in .

Functions that Convert Codewords to Vectors or Polynomials
Here obj can be a code word or a list of code words. This function returns the corresponding vectors over a finite field.
gap> a := Codeword("011011");; gap> VectorCodeword(a); [ 0*Z(2), Z(2)^0, Z(2)^0, 0*Z(2), Z(2)^0, Z(2)^0 ]
PolyCodeword
returns a polynomial or a list of polynomials over a Galois field, converted from obj. The object obj can be a codeword, or a list of codewords.
gap> a := Codeword("011011");; gap> PolyCodeword(a); x_1+x_1^2+x_1^4+x_1^5
Functions that Change the Display Form of a Codeword
TreatAsVector
adapts the codewords in obj to make sure they are printed as vectors. obj may be a codeword or a list of codewords. Elements of obj that are not codewords are ignored. After this function is called, the codewords will be treated as vectors. The vector representation is obtained by using the coefficient list of the polynomial.

Note that this only changes the way a codeword is printed. TreatAsVector returns nothing, it is called only for its side effect. The function VectorCodeword converts codewords to vectors (see ).
gap> B := BinaryGolayCode(); a cyclic [23,12,7]3 binary Golay code over GF(2) gap> c := CodewordNr(B, 4); x^22 + x^20 + x^17 + x^14 + x^13 + x^12 + x^11 + x^10 gap> TreatAsVector(c); gap> c; [ 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 0 0 1 0 0 1 0 1 ]
TreatAsPoly
adapts the codewords in obj to make sure they are printed as polynomials. obj may be a codeword or a list of codewords. Elements of obj that are not codewords are ignored. After this function is called, the codewords will be treated as polynomials. The finite field vector that defines the codeword is used as a coefficient list of the polynomial representation, where the first element of the vector is the coefficient of degree zero, the second element is the coefficient of degree one, etc, until the last element, which is the coefficient of highest degree.

Note that this only changes the way a codeword is printed. TreatAsPoly returns nothing, it is called only for its side effect. The function PolyCodeword converts codewords to polynomials (see ).
gap> a := Codeword("00001",GF(2)); [ 0 0 0 0 1 ] gap> TreatAsPoly(a); a; x^4 gap> b := NullWord(6,GF(4)); [ 0 0 0 0 0 0 ] gap> TreatAsPoly(b); b; 0
Other Codeword Functions
Other uses: NullWord( n ) (default F=GF(2)) and NullWord( C ).

NullWord
returns a codeword of length n over the field F of only zeros. The integer n must be greater then zero. If only a code C is specified, NullWord will return a null word with both the word length and the Galois field of C.
gap> NullWord(8); [ 0 0 0 0 0 0 0 0 ] gap> Codeword("0000") = NullWord(4); true gap> NullWord(5,GF(16)); [ 0 0 0 0 0 ] gap> NullWord(ExtendedTernaryGolayCode()); [ 0 0 0 0 0 0 0 0 0 0 0 0 ]
DistanceCodeword
returns the Hamming distance from c1 to c2. Both variables must be codewords with equal word length over the same Galois field. The Hamming distance between two words is the number of places in which they differ. As a result, DistanceCodeword always returns an integer between zero and the word length of the codewords.
gap> a := Codeword([0, 1, 2, 0, 1, 2]);; b := NullWord(6, GF(3));; gap> DistanceCodeword(a, b); 4 gap> DistanceCodeword(b, a); 4 gap> DistanceCodeword(a, a); 0
Support
returns a set of integers indicating the positions of the non-zero entries in a codeword c.
gap> a := Codeword("012320023002");; Support(a); [ 2, 3, 4, 5, 8, 9, 12 ] gap> Support(NullWord(7)); [ ]

The support of a list with codewords can be calculated by taking the union of the individual supports. The weight of the support is the length of the set.

gap> L := Codeword(["000000", "101010", "222000"], GF(3));; gap> S := Union(List(L, i -> Support(i))); [ 1, 2, 3, 5 ] gap> Length(S); 4
WeightCodeword
returns the weight of a codeword c, the number of non-zero entries in c. As a result, WeightCodeword always returns an integer between zero and the word length of the codeword.
gap> WeightCodeword(Codeword("22222")); 5 gap> WeightCodeword(NullWord(3)); 0 gap> C := HammingCode(3); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> Minimum(List(AsSSortedList(C){[2..Size(C)]}, WeightCodeword ) ); 3
Codes

A code is a set of codewords (recall a code code, elements of codeword in `GUAVA` is simply a sequence of elements of a finite field GF(q), where q is a prime power). We call these the elements of the code. Depending on the type of code, a codeword can be interpreted as a vector or as a polynomial. This is explained in more detail in Chapter .

In `GUAVA`, codes can be a set specified by its elements (this will be called an unrestricted code), code, unrestricted by a generator matrix listing a set of basis elements (for a linear code) or by a generator polynomial (for a cyclic code).

Any code can be defined by its elements. If you like, you can give the code a name.

gap> C := ElementsCode(["1100", "1010", "0001"], "example code", GF(2) ); a (4,3,1..4)2..4 example code over GF(2)

An (n,M,d) code is a code with word length n, size M and minimum distance d. code, (n,M,d) minimum distance length size If the minimum distance has not yet been calculated, the lower bound and upper bound are printed (except in the case where the code is a random linear codes, where these are not printed for efficiency reasons). So

a (4,3,1..4)2..4 code over GF(2)
means a binary unrestricted code of length 4, with 3 elements and the minimum distance is greater than or equal to 1 and less than or equal to 4 and the covering radius is greater than or equal to 2 and less than or equal to 4.

gap> C := ElementsCode(["1100", "1010", "0001"], "example code", GF(2) ); a (4,3,1..4)2..4 example code over GF(2) gap> MinimumDistance(C); 2 gap> C; a (4,3,2)2..4 example code over GF(2)

If the set of elements is a linear subspace of GF(q)^n, the code is called linear. If a code is linear, it can be defined by its generator matrix or parity check matrix. code, linear parity check matrix By definition, the rows of the generator matrix is a basis for the code (as a vector space over GF(q)). By definition, the rows of the parity check matrix is a basis for the dual space of the code,

C^* = \{ v \in GF(q)^n\ |\ v\cdot c = 0,\ for \ all\ c \in C \}.
gap> G := GeneratorMatCode([[1,0,1],[0,1,2]], "demo code", GF(3) ); a linear [3,2,1..2]1 demo code over GF(3)

So a linear [n, k, d]r code code, [n, k, d]r is a code with word length n, dimension k, minimum distance d and covering radius r.

If the code is linear and all cyclic shifts of its codewords (regarded as n-tuples) are again codewords, the code is called cyclic. code, cyclic All elements of a cyclic code are multiples of the monic polynomial modulo a polynomial x^n -1, where n is the word length of the code. Such a polynomial is called a generator polynomial generator polynomial The generator polynomial must divide x^n-1 and its quotient is called a check polynomial. check polynomial Multiplying a codeword in a cyclic code by the check polynomial yields zero (modulo the polynomial x^n -1). In `GUAVA`, a cyclic code can be defined by either its generator polynomial or check polynomial.

gap> G := GeneratorPolCode(Indeterminate(GF(2))+Z(2)^0, 7, GF(2) ); a cyclic [7,6,1..2]1 code defined by generator polynomial over GF(2)

It is possible that `GUAVA` does not know that an unrestricted code is in fact linear. This situation occurs for example when a code is generated from a list of elements with the function ElementsCode (see ). By calling the function IsLinearCode (see ), `GUAVA` tests if the code can be represented by a generator matrix. If so, the code record and the operations are converted accordingly.

gap> L := Z(2)*[ [0,0,0], [1,0,0], [0,1,1], [1,1,1] ];; gap> C := ElementsCode( L, GF(2) ); a (3,4,1..3)1 user defined unrestricted code over GF(2) # so far, GUAVA does not know what kind of code this is gap> IsLinearCode( C ); true # it is linear gap> C; a linear [3,2,1]1 user defined unrestricted code over GF(2)

Of course the same holds for unrestricted codes that in fact are cyclic, or codes, defined by a generator matrix, that actually are cyclic.

Codes are printed simply by giving a small description of their parameters, the word length, size or dimension and perhaps the minimum distance, followed by a short description and the base field of the code. The function Display gives a more detailed description, showing the construction history of the code.

GUAVA
doesn't place much emphasis on the actual encoding and decoding processes; some algorithms have been included though. Encoding works simply by multiplying an information vector with a code, decoding is done by the functions Decode or Decodeword. For more information about encoding and decoding, see sections and .

gap> R := ReedMullerCode( 1, 3 ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2) gap> w := [ 1, 0, 1, 1 ] * R; [ 1 0 0 1 1 0 0 1 ] gap> Decode( R, w ); [ 1 0 1 1 ] gap> Decode( R, w + "10000000" ); # One error at the first position [ 1 0 1 1 ] # Corrected by Guava

Sections and describe the operations that are available for codes.

Section describe the functions that tests whether an object is a code and what kind of code it is (see IsCode, and IsCyclicCode) and various other boolean functions for codes.

Section describe functions about equivalence and isomorphism of codes (see , and ).

Section describes functions that work on domains (see Chapter "Domains and their Elements" in the &GAP; Reference Manual).

Section describes functions for printing and displaying codes.

Section describes functions that return the matrices and polynomials that define a code (see , , , , ).

Section describes functions that return the basic parameters of codes (see , and ).

Section describes functions that return distance and weight distributions (see , , and ).

Section describes functions that are related to decoding (see , , , and ).

In Chapters and which follow, we describe functions that generate and manipulate codes.

Comparisons of Codes
The equality operator C1 = C2 evaluates to `true' if the codes C1 and C2 are equal, and to `false' otherwise.

The equality operator is also denoted EQ, and Eq(C1,C2) is the same as C1 = C2. There is also an inequality operator, &tlt; &tgt;, or not EQ.

Note that codes are equal if and only if their set of elements are equal. Codes can also be compared with objects of other types. Of course they are never equal.
not =
&tlt; &tgt;
gap> M := [ [0, 0], [1, 0], [0, 1], [1, 1] ];; gap> C1 := ElementsCode( M, GF(2) ); a (2,4,1..2)0 user defined unrestricted code over GF(2) gap> M = C1; false gap> C2 := GeneratorMatCode( [ [1, 0], [0, 1] ], GF(2) ); a linear [2,2,1]0 code defined by generator matrix over GF(2) gap> C1 = C2; true gap> ReedMullerCode( 1, 3 ) = HadamardCode( 8 ); true gap> WholeSpaceCode( 5, GF(4) ) = WholeSpaceCode( 5, GF(2) ); false

Another way of comparing codes is IsEquivalent, which checks if two codes are equivalent (see ). By the way, this called CodeIsomorphism. For the current version of `GUAVA`, unless one of the codes is unrestricted, this calls Leon's C program (which only works for binary linear codes and only on a unix/linux computer).

Operations for Codes
codes, addition
codes, direct sum

The operator `+' evaluates to the direct sum of the codes C1 and C2. See .

gap> C1:=RandomLinearCode(10,5); a [10,5,?] randomly generated code over GF(2) gap> C2:=RandomLinearCode(9,4); a [9,4,?] randomly generated code over GF(2) gap> C1+C2; a linear [10,9,1]0..10 unknown linear code over GF(2)
codes, product

The operator `*' evaluates to the direct product of the codes C1 and C2. See .
gap> C1 := GeneratorMatCode( [ [1, 0,0,0], [0, 1,0,0] ], GF(2) ); a linear [4,2,1]1 code defined by generator matrix over GF(2) gap> C2 := GeneratorMatCode( [ [0,0,1, 1], [0,0,0, 1] ], GF(2) ); a linear [4,2,1]1 code defined by generator matrix over GF(2) gap> C1*C2; a linear [16,4,1]4..12 direct product code
codes, encoding
encoder map
The operator m*C evaluates to the element of C belonging to information word ('message') m. Here m may be a vector, polynomial, string or codeword or a list of those. This is the way to do encoding in `GUAVA`. C must be linear, because in `GUAVA`, encoding by multiplication is only defined for linear codes. If C is a cyclic code, this multiplication is the same as multiplying an information polynomial m by the generator polynomial of C. If C is a linear code, it is equal to the multiplication of an information vector m by a generator matrix of C.

To invert this, use the function InformationWord (see , which simply calls the function Decode).

gap> C := GeneratorMatCode( [ [1, 0,0,0], [0, 1,0,0] ], GF(2) ); a linear [4,2,1]1 code defined by generator matrix over GF(2) gap> m:=Codeword("11"); [ 1 1 ] gap> m*C; [ 1 1 0 0 ]
codes, decoding
information bits
Here C is a linear code and c is a codeword in it. The command InformationWord returns the message word (or 'information digits') m satisfying c=m*C. This command simply calls Decode, provided c in C is true. Otherwise, it returns an error.

To invert this, use the encoding function * (see ).

gap> C:=HammingCode(3); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> c:=Random(C); [ 0 0 0 1 1 1 1 ] gap> InformationWord(C,c); [ 0 1 1 1 ] gap> c:=Codeword("1111100"); [ 1 1 1 1 1 0 0 ] gap> InformationWord(C,c); "ERROR: codeword must belong to code" gap> C:=NordstromRobinsonCode(); a (16,256,6)4 Nordstrom-Robinson code over GF(2) gap> c:=Random(C); [ 0 0 0 1 0 0 0 1 0 0 1 0 1 1 0 1 ] gap> InformationWord(C,c); "ERROR: code must be linear"
Boolean Functions for Codes
code, element test
The command c in C evaluates to `true' if C contains the codeword or list of codewords specified by c. Of course, c and C must have the same word lengths and base fields.
gap> C:= HammingCode( 2 );; eC:= AsSSortedList( C ); [ [ 0 0 0 ], [ 1 1 1 ] ] gap> eC[2] in C; true gap> [ 0 ] in C; false
code, subcode
The command IsSubset(C1,C2) returns `true' if C2 is a subcode of C1, i.e. if C1 contains all the elements of C2.

gap> IsSubset( HammingCode(3), RepetitionCode( 7 ) ); true gap> IsSubset( RepetitionCode( 7 ), HammingCode( 3 ) ); false gap> IsSubset( WholeSpaceCode( 7 ), HammingCode( 3 ) ); true
IsCode
returns `true' if obj, which can be an object of arbitrary type, is a code and `false' otherwise. Will cause an error if obj is an unbound variable.
gap> IsCode( 1 ); false gap> IsCode( ReedMullerCode( 2,3 ) ); true
IsLinearCode
checks if object obj (not necessarily a code) is a linear code. If a code has already been marked as linear or cyclic, the function automatically returns `true'. Otherwise, the function checks if a basis G of the elements of obj exists that generates the elements of obj. If so, G is recorded as a generator matrix of obj and the function returns `true'. If not, the function returns `false'.
gap> C := ElementsCode( [ [0,0,0],[1,1,1] ], GF(2) ); a (3,2,1..3)1 user defined unrestricted code over GF(2) gap> IsLinearCode( C ); true gap> IsLinearCode( ElementsCode( [ [1,1,1] ], GF(2) ) ); false gap> IsLinearCode( 1 ); false
IsCyclicCode
checks if the object obj is a cyclic code. If a code has already been marked as cyclic, the function automatically returns `true'. Otherwise, the function checks if a polynomial g exists that generates the elements of obj. If so, g is recorded as a generator polynomial of obj and the function returns `true'. If not, the function returns `false'.
gap> C := ElementsCode( [ [0,0,0], [1,1,1] ], GF(2) ); a (3,2,1..3)1 user defined unrestricted code over GF(2) gap> # GUAVA does not know the code is cyclic gap> IsCyclicCode( C ); # this command tells GUAVA to find out true gap> IsCyclicCode( HammingCode( 4, GF(2) ) ); false gap> IsCyclicCode( 1 ); false
IsPerfectCode(C)
returns `true' if C is a perfect code. If C\subset GF(q)^n then, by definition, this means that for some positive integer t, the space GF(q)^n is covered by non-overlapping spheres of (Hamming) radius t centered at the codewords in C. For a code with odd minimum distance d = 2t+1, this is the case when every word of the vector space of C is at distance at most t from exactly one element of C. Codes with even minimum distance are never perfect.

In fact, a code that is not "trivially perfect" (the binary repetition codes of odd length, the codes consisting of one word, and the codes consisting of the whole vector space), and does not have the parameters of a Hamming or Golay code, cannot be perfect (see section 1.12 in ).
code, perfect
gap> H := HammingCode(2); a linear [3,1,3]1 Hamming (2,2) code over GF(2) gap> IsPerfectCode( H ); true gap> IsPerfectCode( ElementsCode([[1,1,0],[0,0,1]],GF(2)) ); true gap> IsPerfectCode( ReedSolomonCode( 6, 3 ) ); false gap> IsPerfectCode( BinaryGolayCode() ); true
IsMDSCode(C)
returns true if C is a maximum distance separable (MDS) code. A linear [n, k, d]-code of length n, dimension k and minimum distance d is an MDS code if k=n-d+1, in other words if C meets the Singleton bound (see ). An unrestricted (n, M, d) code is called MDS if k=n-d+1, with k equal to the largest integer less than or equal to the logarithm of M with base q, the size of the base field of C.

Well-known MDS codes include the repetition codes, the whole space codes, the even weight codes (these are the only binary MDS codes) and the Reed-Solomon codes.
code, maximum distance separable
MDS
gap> C1 := ReedSolomonCode( 6, 3 ); a cyclic [6,4,3]2 Reed-Solomon code over GF(7) gap> IsMDSCode( C1 ); true # 6-3+1 = 4 gap> IsMDSCode( QRCode( 23, GF(2) ) ); false
IsSelfDualCode(C)
returns `true' if C is self-dual, i.e. when C is equal to its dual code (see also ). A code is self-dual if it contains all vectors that its elements are orthogonal to. If a code is self-dual, it automatically is self-orthogonal (see ).

If C is a non-linear code, it cannot be self-dual (the dual code is always linear), so `false' is returned. A linear code can only be self-dual when its dimension k is equal to the redundancy r.
code, self-dual
gap> IsSelfDualCode( ExtendedBinaryGolayCode() ); true gap> C := ReedMullerCode( 1, 3 ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2) gap> DualCode( C ) = C; true
self-orthogonal
IsSelfOrthogonalCode(C)
returns `true' if C is self-orthogonal. A code is self-orthogonal if every element of C is orthogonal to all elements of C, including itself. (In the linear case, this simply means that the generator matrix of C multiplied with its transpose yields a null matrix.)
code, self-orthogonal
gap> R := ReedMullerCode(1,4); a linear [16,5,8]6 Reed-Muller (1,4) code over GF(2) gap> IsSelfOrthogonalCode(R); true gap> IsSelfDualCode(R); false
Equivalence and Isomorphism of Codes
permutation equivalent codes
equivalent codes
We say that C1 is permutation equivalent to C2 if C1 can be obtained from C2 by carrying out column permutations. IsEquivalent returns true if C1 and C2 are equivalent codes. At this time, IsEquivalent only handles binary codes. (The external unix/linux program desauto from J. S. Leon is called by IsEquivalent.) Of course, if C1 and C2 are equal, they are also equivalent.

Note that the algorithm is very slow for non-linear codes.

More generally, we say that C1 is equivalent to C2 if C1 can be obtained from C2 by carrying out column permutations and a permutation of the alphabet.
gap> x:= Indeterminate( GF(2) );; pol:= x^3+x+1; Z(2)^0+x_1+x_1^3 gap> H := GeneratorPolCode( pol, 7, GF(2)); a cyclic [7,4,1..3]1 code defined by generator polynomial over GF(2) gap> H = HammingCode(3, GF(2)); false gap> IsEquivalent(H, HammingCode(3, GF(2))); true # H is equivalent to a Hamming code gap> CodeIsomorphism(H, HammingCode(3, GF(2))); (3,4)(5,6,7)
If the two codes C1 and C2 are permutation equivalent codes (see ), CodeIsomorphism returns the permutation that transforms C1 into C2. If the codes are not equivalent, it returns `false'.

At this time, IsEquivalent only computes isomorphisms between binary codes on a linux/unix computer (since it calls Leon's C program desauto).
gap> x:= Indeterminate( GF(2) );; pol:= x^3+x+1; Z(2)^0+x_1+x_1^3 gap> H := GeneratorPolCode( pol, 7, GF(2)); a cyclic [7,4,1..3]1 code defined by generator polynomial over GF(2) gap> CodeIsomorphism(H, HammingCode(3, GF(2))); (3,4)(5,6,7) gap> PermutedCode(H, (3,4)(5,6,7)) = HammingCode(3, GF(2)); true
AutomorphismGroup
returns the automorphism group of a linear code C. For a binary code, the automorphism group is the largest permutation group of degree n such that each permutation applied to the columns of C again yields C. `GUAVA` calls the external program desauto written by J. S. Leon, if it exists, to compute the automorphism group. If Leon's program is not compiled on the system (and in the default directory) then it calls instead the much slower program PermutationAutomorphismGroup.

See Leon for a more precise description of the method, and the guava/src/leon/doc subdirectory for for details about Leon's C programs.

The function PermutedCode permutes the columns of a code (see ).
gap> R := RepetitionCode(7,GF(2)); a cyclic [7,1,7]3 repetition code over GF(2) gap> AutomorphismGroup(R); Sym( [ 1 .. 7 ] ) # every permutation keeps R identical gap> C := CordaroWagnerCode(7); a linear [7,2,4]3 Cordaro-Wagner code over GF(2) gap> AsSSortedList(C); [ [ 0 0 0 0 0 0 0 ], [ 0 0 1 1 1 1 1 ], [ 1 1 0 0 0 1 1 ], [ 1 1 1 1 1 0 0 ] ] gap> AutomorphismGroup(C); Group([ (3,4), (4,5), (1,6)(2,7), (1,2), (6,7) ]) gap> C2 := PermutedCode(C, (1,6)(2,7)); a linear [7,2,4]3 permuted code gap> AsSSortedList(C2); [ [ 0 0 0 0 0 0 0 ], [ 0 0 1 1 1 1 1 ], [ 1 1 0 0 0 1 1 ], [ 1 1 1 1 1 0 0 ] ] gap> C2 = C; true
PermutationGroup
PermutationAutomorphismGroup
returns the permutation automorphism group of a linear code C. This is the largest permutation group of degree n such that each permutation applied to the columns of C again yields C. It is written in GAP, so is much slower than AutomorphismGroup.

When C is binary PermutationAutomorphismGroup does not call AutomorphismGroup, even though they agree mathematically in that case. This way PermutationAutomorphismGroup can be called on any platform which runs GAP.

The older name for this command, PermutationGroup, will become obsolete in the next version of GAP.

gap> R := RepetitionCode(3,GF(3)); a cyclic [3,1,3]2 repetition code over GF(3) gap> G:=PermutationAutomorphismGroup(R); Group([ (), (1,3), (1,2,3), (2,3), (1,3,2), (1,2) ]) gap> G=SymmetricGroup(3); true
Domain Functions for Codes

These are some &GAP; functions that work on `Domains' in general. Their specific effect on `Codes' is explained here.

IsFinite
is an implementation of the &GAP; domain function IsFinite. It returns true for a code C.
gap> IsFinite( RepetitionCode( 1000, GF(11) ) ); true
Size
returns the size of C, the number of elements of the code. If the code is linear, the size of the code is equal to q^k, where q is the size of the base field of C and k is the dimension.
gap> Size( RepetitionCode( 1000, GF(11) ) ); 11 gap> Size( NordstromRobinsonCode() ); 256
LeftActingDomain
returns the base field of a code C. Each element of C consists of elements of this base field. If the base field is F, and the word length of the code is n, then the codewords are elements of F^n. If C is a cyclic code, its elements are interpreted as polynomials with coefficients over F.
gap> C1 := ElementsCode([[0,0,0], [1,0,1], [0,1,0]], GF(4)); a (3,3,1..3)2..3 user defined unrestricted code over GF(4) gap> LeftActingDomain( C1 ); GF(2^2) gap> LeftActingDomain( HammingCode( 3, GF(9) ) ); GF(3^2)
Dimension
returns the parameter k of C, the dimension of the code, or the number of information symbols in each codeword. The dimension is not defined for non-linear codes; Dimension then returns an error.
gap> Dimension( NullCode( 5, GF(5) ) ); 0 gap> C := BCHCode( 15, 4, GF(4) ); a cyclic [15,9,5]3..4 BCH code, delta=5, b=1 over GF(4) gap> Dimension( C ); 9 gap> Size( C ) = Size( LeftActingDomain( C ) ) ^ Dimension( C ); true
AsSSortedList
(as strictly sorted list) returns an immutable, duplicate free list of the elements of C. For a finite field GF(q) generated by powers of Z(q), the ordering on GF(q)=\{ 0 , Z(q)^0, Z(q), Z(q)^2, ...Z(q)^{q-2} \} is that determined by the exponents i. These elements are of the type codeword (see ). Note that for large codes, generating the elements may be very time- and memory-consuming. For generating a specific element or a subset of the elements, use CodewordNr (see ).
gap> C := ConferenceCode( 5 ); a (5,12,2)1..4 conference code over GF(2) gap> AsSSortedList( C ); [ [ 0 0 0 0 0 ], [ 0 0 1 1 1 ], [ 0 1 0 1 1 ], [ 0 1 1 0 1 ], [ 0 1 1 1 0 ], [ 1 0 0 1 1 ], [ 1 0 1 0 1 ], [ 1 0 1 1 0 ], [ 1 1 0 0 1 ], [ 1 1 0 1 0 ], [ 1 1 1 0 0 ], [ 1 1 1 1 1 ] ] gap> CodewordNr( C, [ 1, 2 ] ); [ [ 0 0 0 0 0 ], [ 0 0 1 1 1 ] ]
Printing and Displaying Codes
Print
prints information about C. This is the same as typing the identifier C at the &GAP;-prompt.

If the argument is an unrestricted code, information in the form

a (n,M,d)r ... code over GF(q)
is printed, where n is the word length, M the number of elements of the code, d the minimum distance and r the covering radius.

If the argument is a linear code, information in the form

a linear [n,k,d]r ... code over GF(q)
is printed, where n is the word length, k the dimension of the code, d the minimum distance and r the covering radius.

Except for codes produced by RandomLinearCode, if d is not yet known, it is displayed in the form

lowerbound..upperbound
and if r is not yet known, it is displayed in the same way. For certain ranges of n, the values of lowerbound and upperbound are obtained from tables.

The function Display gives more information. See .
gap> C1 := ExtendedCode( HammingCode( 3, GF(2) ) ); a linear [8,4,4]2 extended code gap> Print( "This is ", NordstromRobinsonCode(), ". \n"); This is a (16,256,6)4 Nordstrom-Robinson code over GF(2).
String
returns information about C in a string. This function is used by Print.
gap> x:= Indeterminate( GF(3) );; pol:= x^2+1; x_1^2+Z(3)^0 gap> Factors(pol); [ x_1^2+Z(3)^0 ] gap> H := GeneratorPolCode( pol, 8, GF(3)); a cyclic [8,6,1..2]1..2 code defined by generator polynomial over GF(3) gap> String(H); "a cyclic [8,6,1..2]1..2 code defined by generator polynomial over GF(3)"
Display
prints the method of construction of code C. With this history, in most cases an equal or equivalent code can be reconstructed. If C is an unmanipulated code, the result is equal to output of the function Print (see ).
gap> Display( RepetitionCode( 6, GF(3) ) ); a cyclic [6,1,6]4 repetition code over GF(3) gap> C1 := ExtendedCode( HammingCode(2) );; gap> C2 := PuncturedCode( ReedMullerCode( 2, 3 ) );; gap> Display( LengthenedCode( UUVCode( C1, C2 ) ) ); a linear [12,8,2]2..4 code, lengthened with 1 column(s) of a linear [11,8,1]1..2 U U+V construction code of U: a linear [4,1,4]2 extended code of a linear [3,1,3]1 Hamming (2,2) code over GF(2) V: a linear [7,7,1]0 punctured code of a cyclic [8,7,2]1 Reed-Muller (2,3) code over GF(2)
Generating (Check) Matrices and Polynomials
GeneratorMat
returns a generator matrix of C. The code consists of all linear combinations of the rows of this matrix.

If until now no generator matrix of C was determined, it is computed from either the parity check matrix, the generator polynomial, the check polynomial or the elements (if possible), whichever is available.

If C is a non-linear code, the function returns an error.
gap> GeneratorMat( HammingCode( 3, GF(2) ) ); [ [ an immutable GF2 vector of length 7], [ an immutable GF2 vector of length 7], [ an immutable GF2 vector of length 7], [ an immutable GF2 vector of length 7] ] gap> Display(last); 1 1 1 . . . . 1 . . 1 1 . . . 1 . 1 . 1 . 1 1 . 1 . . 1 gap> GeneratorMat( RepetitionCode( 5, GF(25) ) ); [ [ Z(5)^0, Z(5)^0, Z(5)^0, Z(5)^0, Z(5)^0 ] ] gap> GeneratorMat( NullCode( 14, GF(4) ) ); [ ]
CheckMat
returns a parity check matrix of C. The code consists of all words orthogonal to each of the rows of this matrix. The transpose of the matrix is a right inverse of the generator matrix. The parity check matrix is computed from either the generator matrix, the generator polynomial, the check polynomial or the elements of C (if possible), whichever is available.

If C is a non-linear code, the function returns an error.
gap> CheckMat( HammingCode(3, GF(2) ) ); [ [ 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ], [ 0*Z(2), Z(2)^0, Z(2)^0, 0*Z(2), 0*Z(2), Z(2)^0, Z(2)^0 ], [ Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0 ] ] gap> Display(last); . . . 1 1 1 1 . 1 1 . . 1 1 1 . 1 . 1 . 1 gap> CheckMat( RepetitionCode( 5, GF(25) ) ); [ [ Z(5)^0, Z(5)^2, 0*Z(5), 0*Z(5), 0*Z(5) ], [ 0*Z(5), Z(5)^0, Z(5)^2, 0*Z(5), 0*Z(5) ], [ 0*Z(5), 0*Z(5), Z(5)^0, Z(5)^2, 0*Z(5) ], [ 0*Z(5), 0*Z(5), 0*Z(5), Z(5)^0, Z(5)^2 ] ] gap> CheckMat( WholeSpaceCode( 12, GF(4) ) ); [ ]
GeneratorPol
returns the generator polynomial of C. The code consists of all multiples of the generator polynomial modulo x^{n}-1, where n is the word length of C. The generator polynomial is determined from either the check polynomial, the generator or check matrix or the elements of C (if possible), whichever is available.

If C is not a cyclic code, the function returns `false'.
gap> GeneratorPol(GeneratorMatCode([[1, 1, 0], [0, 1, 1]], GF(2))); Z(2)^0+x_1 gap> GeneratorPol( WholeSpaceCode( 4, GF(2) ) ); Z(2)^0 gap> GeneratorPol( NullCode( 7, GF(3) ) ); -Z(3)^0+x_1^7
CheckPol
returns the check polynomial of C. The code consists of all polynomials f with f\cdot h \equiv 0 \ ({\rm mod}\ x^n-1), where h is the check polynomial, and n is the word length of C. The check polynomial is computed from the generator polynomial, the generator or parity check matrix or the elements of C (if possible), whichever is available.

If C if not a cyclic code, the function returns an error.
gap> CheckPol(GeneratorMatCode([[1, 1, 0], [0, 1, 1]], GF(2))); Z(2)^0+x_1+x_1^2 gap> CheckPol(WholeSpaceCode(4, GF(2))); Z(2)^0+x_1^4 gap> CheckPol(NullCode(7,GF(3))); Z(3)^0
RootsOfCode
returns a list of all zeros of the generator polynomial of a cyclic code C. These are finite field elements in the splitting field of the generator polynomial, GF(q^m), m is the multiplicative order of the size of the base field of the code, modulo the word length.

The reverse process, constructing a code from a set of roots, can be carried out by the function RootsCode (see ).
gap> C1 := ReedSolomonCode( 16, 5 ); a cyclic [16,12,5]3..4 Reed-Solomon code over GF(17) gap> RootsOfCode( C1 ); [ Z(17), Z(17)^2, Z(17)^3, Z(17)^4 ] gap> C2 := RootsCode( 16, last ); a cyclic [16,12,5]3..4 code defined by roots over GF(17) gap> C1 = C2; true
Parameters of Codes
WordLength
returns the parameter n of C, the word length of the elements. Elements of cyclic codes are polynomials of maximum degree n-1, as calculations are carried out modulo x^{n}-1.

gap> WordLength( NordstromRobinsonCode() ); 16 gap> WordLength( PuncturedCode( WholeSpaceCode(7) ) ); 6 gap> WordLength( UUVCode( WholeSpaceCode(7), RepetitionCode(7) ) ); 14
Redundancy
returns the redundancy r of C, which is equal to the number of check symbols in each element. If C is not a linear code the redundancy is not defined and Redundancy returns an error.

If a linear code C has dimension k and word length n, it has redundancy r=n-k.

gap> C := TernaryGolayCode(); a cyclic [11,6,5]2 ternary Golay code over GF(3) gap> Redundancy(C); 5 gap> Redundancy( DualCode(C) ); 6
MinimumDistance
returns the minimum distance of C, the largest integer d with the property that every element of C has at least a Hamming distance d (see ) to any other element of C. For linear codes, the minimum distance is equal to the minimum weight. This means that d is also the smallest positive value with w[d+1] \neq 0, where w=(w[1],w[2],...,w[n]) is the weight distribution of C (see ). For unrestricted codes, d is the smallest positive value with w[d+1] \neq 0, where w is the inner distribution of C (see ).

For codes with only one element, the minimum distance is defined to be equal to the word length.

For linear codes C, the algorithm used is the following: After replacing C by a permutation equivalent C', one may assume the generator matrix has the following form G=(I_{k} \, | \, A), for some k\times (n-k) matrix A. If A=0 then return d(C)=1. Next, find the minimum distance of the code spanned by the rows of A. Call this distance d(A). Note that d(A) is equal to the the Hamming distance d(v,0) where v is some proper linear combination of i distinct rows of A. Return d(C)=d(A)+i, where i is as in the previous step.

This command may also be called using the syntax MinimumDistance(C, w). In this form, MinimumDistance returns the minimum distance of a codeword w to the code C, also called the distance from w to C. This is the smallest value d for which there is an element c of the code C which is at distance d from w. So d is also the minimum value for which D[d+1] \neq 0, where D is the distance distribution of w to C (see ).

Note that w must be an element of the same vector space as the elements of C. w does not necessarily belong to the code (if it does, the minimum distance is zero).
gap> C := MOLSCode(7);; MinimumDistance(C); 3 gap> WeightDistribution(C); [ 1, 0, 0, 24, 24 ] gap> MinimumDistance( WholeSpaceCode( 5, GF(3) ) ); 1 gap> MinimumDistance( NullCode( 4, GF(2) ) ); 4 gap> C := ConferenceCode(9);; MinimumDistance(C); 4 gap> InnerDistribution(C); [ 1, 0, 0, 0, 63/5, 9/5, 18/5, 0, 9/10, 1/10 ] gap> C := MOLSCode(7);; w := CodewordNr( C, 17 ); [ 3 3 6 2 ] gap> MinimumDistance( C, w ); 0 gap> C := RemovedElementsCode( C, w );; MinimumDistance( C, w ); 3 # so w no longer belongs to C

See also the `GUAVA` commands relating to bounds on the minimum distance in section .

MinimumDistanceLeon
returns the ``probable'' minimum distance d_{Leon} of a linear binary code C, using an implementation of Leon's probabilistic polynomial time algorithm. Briefly: Let C be a linear code of dimension k over GF(q) as above. The algorithm has input parameters s and \rho, where s is an integer between 2 and n-k, and \rho is an integer between 2 and k.

Find a generator matrix G of C.
Randomly permute the columns of G.
Perform Gaussian elimination on the permuted matrix to obtain a new matrix of the following form: G=(I_{k} \, | \, Z \, | \, B) with Z a k\times s matrix. If (Z,B) is the zero matrix then return 1 for the minimum distance. If Z=0 but not B then either choose another permutation of the rows of C or return `method fails'.
Search Z for at most \rho rows that lead to codewords of weight less than \rho.
For these codewords, compute the weight of the whole word in C. Return this weight.
(See for example J. S. Leon, for more details.) Sometimes (as is the case in `GUAVA`) this probabilistic algorithm is repeated several times and the most commonly occurring value is taken.
gap> C:=RandomLinearCode(50,22,GF(2)); a [50,22,?] randomly generated code over GF(2) gap> MinimumDistanceLeon(C); time; 6 211 gap> MinimumDistance(C); time; 6 1204
DecreaseMinimumDistanceUpperBound
is an implementation of the algorithm for the minimum distance of a linear binary code C by Leon . This algorithm tries to find codewords with small minimum weights. The parameter t is at least 1 and less than the dimension of C. The best results are obtained if it is close to the dimension of the code. The parameter m gives the number of runs that the algorithm will perform.

The result returned is a record with two fields; the first, mindist, gives the lowest weight found, and word gives the corresponding codeword. (This was implemented before MinimumDistanceLeon but independently. The older manual had given the command incorrectly, so the command was only found after reading all the *.gi files in the `GUAVA` library. Though both MinimumDistance and MinimumDistanceLeon often run much faster than DecreaseMinimumDistanceUpperBound, DecreaseMinimumDistanceUpperBound appears to be more accurate than MinimumDistanceLeon.)
gap> C:=RandomLinearCode(5,2,GF(2)); a [5,2,?] randomly generated code over GF(2) gap> DecreaseMinimumDistanceUpperBound(C,1,4); rec( mindist := 3, word := [ 0*Z(2), Z(2)^0, Z(2)^0, 0*Z(2), Z(2)^0 ] ) gap> MinimumDistance(C); 3 gap> C:=RandomLinearCode(8,4,GF(2)); a [8,4,?] randomly generated code over GF(2) gap> DecreaseMinimumDistanceUpperBound(C,3,4); rec( mindist := 2, word := [ Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0 ] ) gap> MinimumDistance(C); 2
MinimumDistanceRandom
returns an upper bound for the minimum distance d_{random} of a linear binary code C, using a probabilistic polynomial time algorithm. Briefly: Let C be a linear code of dimension k over GF(q) as above. The algorithm has input parameters num and s, where s is an integer between 2 and n-1, and num is an integer greater than or equal to 1.

Find a generator matrix G of C.
Randomly permute the columns of G, written G_p..
G=(A, B)
with A a k\times s matrix. If A is the zero matrix then return `method fails'.
Search A for at most 5 rows that lead to codewords, in the code C_A with generator matrix A, of minimum weight.
For these codewords, use the associated linear combination to compute the weight of the whole word in C. Return this weight and codeword.
This probabilistic algorithm is repeated num times (with different random permutations of the rows of G each time) and the weight and codeword of the lowest occurring weight is taken.
gap> C:=RandomLinearCode(60,20,GF(2)); a [60,20,?] randomly generated code over GF(2) gap> #mindist(C);time; gap> #mindistleon(C,10,30);time; #doesn't work well gap> a:=MinimumDistanceRandom(C,10,30);time; # done 10 times -with fastest time!!

This is a probabilistic algorithm which may return the wrong answer. [ 12, [ 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 1 1 0 0 1 0 0 0 1 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 1 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 ] ] 130 gap> a[2] in C; true gap> b:=DecreaseMinimumDistanceUpperBound(C,10,1); time; #only done once! rec( mindist := 12, word := [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, Z(2)^0, 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2) ] ) 649 gap> Codeword(b!.word) in C; true gap> MinimumDistance(C);time; 12 196 gap> c:=MinimumDistanceLeon(C);time; 12 66 gap> C:=RandomLinearCode(30,10,GF(3)); a [30,10,?] randomly generated code over GF(3) gap> a:=MinimumDistanceRandom(C,10,10);time;

This is a probabilistic algorithm which may return the wrong answer. [ 13, [ 0 0 0 1 0 0 0 0 0 0 1 0 2 2 1 1 0 2 2 0 1 0 2 1 0 0 0 1 0 2 ] ] 229 gap> a[2] in C; true gap> MinimumDistance(C);time; 9 45 gap> c:=MinimumDistanceLeon(C); Code must be binary. Quitting. 0 gap> a:=MinimumDistanceRandom(C,1,29);time;

This is a probabilistic algorithm which may return the wrong answer. [ 10, [ 0 0 1 0 2 0 2 0 1 0 0 0 0 0 0 1 0 1 0 0 1 0 0 0 0 0 2 2 2 0 ] ] 53
t(n,k)
covering code
CoveringRadius
returns the covering radius of a linear code C. This is the smallest number r with the property that each element v of the ambient vector space of C has at most a distance r to the code C. So for each vector v there must be an element c of C with d(v,c) \leq r. The smallest covering radius of any [n,k] binary linear code is denoted t(n,k). A binary linear code with reasonable small covering radius is called a covering code.

If C is a perfect code (see ), the covering radius is equal to t, the number of errors the code can correct, where d = 2t+1, with d the minimum distance of C (see ).

If there exists a function called SpecialCoveringRadius in the `operations' field of the code, then this function will be called to compute the covering radius of the code. At the moment, no code-specific functions are implemented.

If the length of BoundsCoveringRadius (see ), is 1, then the value in

C.boundsCoveringRadius

is returned. Otherwise, the function

C.operations.CoveringRadius

is executed, unless the redundancy of C is too large. In the last case, a warning is issued.

The algorithm used to compute the covering radius is the following. First, CosetLeadersMatFFE is used to compute the list of coset leaders (which returns a codeword in each coset of GF(q)^n/C of minimum weight). Then WeightVecFFE is used to compute the weight of each of these coset leaders. The program returns the maximum of these weights.

gap> H := RandomLinearCode(10, 5, GF(2)); a [10,5,?] randomly generated code over GF(2) gap> CoveringRadius(H); 3 gap> H := HammingCode(4, GF(2));; IsPerfectCode(H); true gap> CoveringRadius(H); 1 # Hamming codes have minimum distance 3 gap> CoveringRadius(ReedSolomonCode(7,4)); 3 gap> CoveringRadius( BCHCode( 17, 3, GF(2) ) ); 3 gap> CoveringRadius( HammingCode( 5, GF(2) ) ); 1 gap> C := ReedMullerCode( 1, 9 );; gap> CoveringRadius( C ); CoveringRadius: warning, the covering radius of this code cannot be computed straightforward. Try to use IncreaseCoveringRadiusLowerBound( code ). (see the manual for more details). The covering radius of code lies in the interval: [ 240 .. 248 ]

See also the `GUAVA` commands relating to bounds on the minimum distance in section .

SetCoveringRadius
enables the user to set the covering radius herself, instead of letting `GUAVA` compute it. If intlist is an integer, `GUAVA` will simply put it in the `boundsCoveringRadius' field. If it is a list of integers, however, it will intersect this list with the `boundsCoveringRadius' field, thus taking the best of both lists. If this would leave an empty list, the field is set to intlist. Because some other computations use the covering radius of the code, it is important that the entered value is not wrong, otherwise new results may be invalid.
gap> C := BCHCode( 17, 3, GF(2) );; gap> BoundsCoveringRadius( C ); [ 3 .. 4 ] gap> SetCoveringRadius( C, [ 2 .. 3 ] ); gap> BoundsCoveringRadius( C ); [ [ 2 .. 3 ] ]
Distributions
WeightDistribution
returns the weight distribution of C, as a vector. The i^{th} element of this vector contains the number of elements of C with weight i-1. For linear codes, the weight distribution is equal to the inner distribution (see ). If w is the weight distribution of a linear code C, it must have the zero codeword, so w[1] = 1 (one word of weight 0).

Some codes, such as the Hamming codes, have precomputed weight distributions. For others, the program WeightDistribution calls the GAP program DistancesDistributionMatFFEVecFFE, which is written in C. See also CodeWeightEnumerator.
gap> WeightDistribution( ConferenceCode(9) ); [ 1, 0, 0, 0, 0, 18, 0, 0, 0, 1 ] gap> WeightDistribution( RepetitionCode( 7, GF(4) ) ); [ 1, 0, 0, 0, 0, 0, 0, 3 ] gap> WeightDistribution( WholeSpaceCode( 5, GF(2) ) ); [ 1, 5, 10, 10, 5, 1 ]
InnerDistribution
returns the inner distribution of C. The i^{th} element of the vector contains the average number of elements of C at distance i-1 to an element of C. For linear codes, the inner distribution is equal to the weight distribution (see ).

Suppose w is the inner distribution of C. Then w[1] = 1, because each element of C has exactly one element at distance zero (the element itself). The minimum distance of C is the smallest value d > 0 with w[d+1] \neq 0, because a distance between zero and d never occurs. See .
gap> InnerDistribution( ConferenceCode(9) ); [ 1, 0, 0, 0, 63/5, 9/5, 18/5, 0, 9/10, 1/10 ] gap> InnerDistribution( RepetitionCode( 7, GF(4) ) ); [ 1, 0, 0, 0, 0, 0, 0, 3 ]
distance
DistancesDistribution
returns the distribution of the distances of all elements of C to a codeword w in the same vector space. The i^{th} element of the distance distribution is the number of codewords of C that have distance i-1 to w. The smallest value d with w[d+1] \neq 0, is defined as the distance to C (see ).
gap> H := HadamardCode(20); a (20,40,10)6..8 Hadamard code of order 20 over GF(2) gap> c := Codeword("10110101101010010101", H); [ 1 0 1 1 0 1 0 1 1 0 1 0 1 0 0 1 0 1 0 1 ] gap> DistancesDistribution(H, c); [ 0, 0, 0, 0, 0, 1, 0, 7, 0, 12, 0, 12, 0, 7, 0, 1, 0, 0, 0, 0, 0 ] gap> MinimumDistance(H, c); 5 # distance to H
The function OuterDistribution returns a list of length q^n, where q is the size of the base field of C and n is the word length. The elements of the list consist of pairs, the first coordinate being an element of GF(q)^n (this is a codeword type) and the second coordinate being a distribution of distances to the code (a list of integers). This table is very large, and for n > 20 it will not fit in the memory of most computers. The function DistancesDistribution (see ) can be used to calculate one entry of the list.
gap> C := RepetitionCode( 3, GF(2) ); a cyclic [3,1,3]1 repetition code over GF(2) gap> OD := OuterDistribution(C); [ [ [ 0 0 0 ], [ 1, 0, 0, 1 ] ], [ [ 1 1 1 ], [ 1, 0, 0, 1 ] ], [ [ 0 0 1 ], [ 0, 1, 1, 0 ] ], [ [ 1 1 0 ], [ 0, 1, 1, 0 ] ], [ [ 1 0 0 ], [ 0, 1, 1, 0 ] ], [ [ 0 1 1 ], [ 0, 1, 1, 0 ] ], [ [ 0 1 0 ], [ 0, 1, 1, 0 ] ], [ [ 1 0 1 ], [ 0, 1, 1, 0 ] ] ] gap> WeightDistribution(C) = OD[1][2]; true gap> DistancesDistribution( C, Codeword("110") ) = OD[4][2]; true
Decoding Functions
Decode
decodes r (a 'received word') with respect to code C and returns the `message word' (i.e., the information digits associated to the codeword c \in C closest to r). Here r can be a `GUAVA` codeword or a list of codewords. First, possible errors in r are corrected, then the codeword is decoded to an information codeword m (and not an element of C). If the code record has a field `specialDecoder', this special algorithm is used to decode the vector. Hamming codes and BCH codes have such a special algorithm. (The algorithm used for BCH codes is the Sugiyama algorithm described, for example, in section 5.4.3 of . Work in progress: special decoders are now being written for the generalized Reed-Solomon code.) If C is linear and no special decoder field has been set then syndrome decoding is used. Otherwise (when C is non-linear), no decoding algorithms have been implemented and an error is returned.

A special decoder can be created by defining a function

C!.SpecialDecoder := function(C, r) ... end;

The function uses the arguments C (the code record itself) and r (a vector of the codeword type) to decode r to an information vector. A normal decoder would take a codeword r of the same word length and field as C, and would return an information vector of length k, the dimension of C. The user is not restricted to these normal demands though, and can for instance define a decoder for non-linear codes.

Encoding is done by multiplying the information vector with the code (see ).

gap> C := HammingCode(3); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> c := "1010"*C; # encoding [ 1 0 1 1 0 1 0 ] gap> Decode(C, c); # decoding [ 1 0 1 0 ] gap> Decode(C, Codeword("0010101")); [ 1 1 0 1 ] # one error corrected gap> C!.SpecialDecoder := function(C, c) > return NullWord(Dimension(C)); > end; function ( C, c ) ... end gap> Decode(C, c); [ 0 0 0 0 ] # new decoder always returns null word
Decodeword
decodes r (a 'received word') with respect to code C and returns the codeword c \in C closest to r. Here r can be a `GUAVA` codeword or a list of codewords. If the code record has a field `specialDecoder', this special algorithm is used to decode the vector. Hamming codes, generalized Reed-Solomon codes, and BCH codes have such a special algorithm. (The algorithm used for BCH codes is the Sugiyama algorithm described, for example, in section 5.4.3 of . The algorithm used for generalized Reed-Solomon codes is the ``interpolation algorithm'' described for example in chapter 5 of .) If C is linear and no special decoder field has been set then syndrome decoding is used. Otherwise, when C is non-linear, the nearest neighbor algorithm has been implemented (which should only be used for small-sized codes).
gap> C := HammingCode(3); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> c := "1010"*C; # encoding [ 1 0 1 1 0 1 0 ] gap> Decodeword(C, c); # decoding [ 1 0 1 1 0 1 0 ] gap> gap> R:=PolynomialRing(GF(11),["t"]); GF(11)[t] gap> P:=List([1,3,4,5,7],i->Z(11)^i); [ Z(11), Z(11)^3, Z(11)^4, Z(11)^5, Z(11)^7 ] gap> C:=GeneralizedReedSolomonCode(P,3,R); a linear [5,3,1..3]2 generalized Reed-Solomon code over GF(11) gap> MinimumDistance(C); 3 gap> c:=Random(C); [ 0 9 6 2 1 ] gap> v:=Codeword("09620"); [ 0 9 6 2 0 ] gap> GeneralizedReedSolomonDecoderGao(C,v); [ 0 9 6 2 1 ] gap> Decodeword(C,v); # calls the special interpolation decoder [ 0 9 6 2 1 ] gap> G:=GeneratorMat(C); [ [ Z(11)^0, 0*Z(11), 0*Z(11), Z(11)^8, Z(11)^9 ], [ 0*Z(11), Z(11)^0, 0*Z(11), Z(11)^0, Z(11)^8 ], [ 0*Z(11), 0*Z(11), Z(11)^0, Z(11)^3, Z(11)^8 ] ] gap> C1:=GeneratorMatCode(G,GF(11)); a linear [5,3,1..3]2 code defined by generator matrix over GF(11) gap> Decodeword(C,v); # calls syndrome decoding [ 0 9 6 2 1 ]
GeneralizedReedSolomonDecoderGao
decodes r (a 'received word') to a codeword c \in C in a generalized Reed-Solomon code C (see ), closest to r. Here r must be a `GUAVA` codeword. If the code record does not have name `generalized Reed-Solomon code' then an error is returned. Otherwise, the Gao decoder is used to compute c.

For long codes, this method is faster in practice than the interpolation method used in Decodeword.
gap> R:=PolynomialRing(GF(11),["t"]); GF(11)[t] gap> P:=List([1,3,4,5,7],i->Z(11)^i); [ Z(11), Z(11)^3, Z(11)^4, Z(11)^5, Z(11)^7 ] gap> C:=GeneralizedReedSolomonCode(P,3,R); a linear [5,3,1..3]2 generalized Reed-Solomon code over GF(11) gap> MinimumDistance(C); 3 gap> c:=Random(C); [ 0 9 6 2 1 ] gap> v:=Codeword("09620"); [ 0 9 6 2 0 ] gap> GeneralizedReedSolomonDecoderGao(C,v); [ 0 9 6 2 1 ]
GeneralizedReedSolomonListDecoder
implements Sudans list-decoding algorithm (see section 12.1 of ) for ``low rate'' Reed-Solomon codes. It returns the list of all codewords in C which are a distance of at most tau from r (a 'received word'). C must be a generalized Reed-Solomon code C (see ) and r must be a `GUAVA` codeword.

gap> F:=GF(16); GF(2^4) gap> gap> a:=PrimitiveRoot(F);; b:=a^7;; b^4+b^3+1; 0*Z(2) gap> Pts:=List([0..14],i->b^i); [ Z(2)^0, Z(2^4)^7, Z(2^4)^14, Z(2^4)^6, Z(2^4)^13, Z(2^2), Z(2^4)^12, Z(2^4)^4, Z(2^4)^11, Z(2^4)^3, Z(2^2)^2, Z(2^4)^2, Z(2^4)^9, Z(2^4), Z(2^4)^8 ] gap> x:=X(F);; gap> R1:=PolynomialRing(F,[x]);; gap> vars:=IndeterminatesOfPolynomialRing(R1);; gap> y:=X(F,vars);; gap> R2:=PolynomialRing(F,[x,y]);; gap> C:=GeneralizedReedSolomonCode(Pts,3,R1); a linear [15,3,1..13]10..12 generalized Reed-Solomon code over GF(16) gap> MinimumDistance(C); ## 6 error correcting 13 gap> z:=Zero(F);; gap> r:=[z,z,z,z,z,z,z,z,b^6,b^2,b^5,b^14,b,b^7,b^11];; gap> r:=Codeword(r); [ 0 0 0 0 0 0 0 0 a^12 a^14 a^5 a^8 a^7 a^4 a^2 ] gap> cs:=GeneralizedReedSolomonListDecoder(C,r,2); time; [ [ 0 a^9 a^3 a^13 a^6 a^10 a^11 a a^12 a^14 a^5 a^8 a^7 a^4 a^2 ], [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ] ] 250 gap> c1:=cs[1]; c1 in C; [ 0 a^9 a^3 a^13 a^6 a^10 a^11 a a^12 a^14 a^5 a^8 a^7 a^4 a^2 ] true gap> c2:=cs[2]; c2 in C; [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ] true gap> WeightCodeword(c1-r); 7 gap> WeightCodeword(c2-r); 7
NearestNeighborGRSDecodewords
finds all generalized Reed-Solomon codewords within distance dist from v and the associated polynomial, using ``brute force''. Input: v is a received vector (a `GUAVA` codeword), C is a GRS code, dist > 0 is the distance from v to search in C. Output: a list of pairs [c,f(x)], where wt(c-v)\leq dist-1 and c = (f(x_1),...,f(x_n)).
gap> F:=GF(16); GF(2^4) gap> a:=PrimitiveRoot(F);; b:=a^7; b^4+b^3+1; Z(2^4)^7 0*Z(2) gap> Pts:=List([0..14],i->b^i); [ Z(2)^0, Z(2^4)^7, Z(2^4)^14, Z(2^4)^6, Z(2^4)^13, Z(2^2), Z(2^4)^12, Z(2^4)^4, Z(2^4)^11, Z(2^4)^3, Z(2^2)^2, Z(2^4)^2, Z(2^4)^9, Z(2^4), Z(2^4)^8 ] gap> x:=X(F);; gap> R1:=PolynomialRing(F,[x]);; gap> vars:=IndeterminatesOfPolynomialRing(R1);; gap> y:=X(F,vars);; gap> R2:=PolynomialRing(F,[x,y]);; gap> C:=GeneralizedReedSolomonCode(Pts,3,R1); a linear [15,3,1..13]10..12 generalized Reed-Solomon code over GF(16) gap> MinimumDistance(C); # 6 error correcting 13 gap> z:=Zero(F); 0*Z(2) gap> r:=[z,z,z,z,z,z,z,z,b^6,b^2,b^5,b^14,b,b^7,b^11];; # 7 errors gap> r:=Codeword(r); [ 0 0 0 0 0 0 0 0 a^12 a^14 a^5 a^8 a^7 a^4 a^2 ] gap> cs:=NearestNeighborGRSDecodewords(C,r,7); [ [ [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ], 0*Z(2) ], [ [ 0 a^9 a^3 a^13 a^6 a^10 a^11 a a^12 a^14 a^5 a^8 a^7 a^4 a^2 ], x_1+Z(2)^0 ] ]
NearestNeighborDecodewords
finds all codewords in a linear code C within distance dist from v, using ``brute force''. Input: v is a received vector (a `GUAVA` codeword), C is a linear code, dist > 0 is the distance from v to search in C. Output: a list of c \in C, where wt(c-v)\leq dist-1.
gap> F:=GF(16); GF(2^4) gap> a:=PrimitiveRoot(F);; b:=a^7; b^4+b^3+1; Z(2^4)^7 0*Z(2) gap> Pts:=List([0..14],i->b^i); [ Z(2)^0, Z(2^4)^7, Z(2^4)^14, Z(2^4)^6, Z(2^4)^13, Z(2^2), Z(2^4)^12, Z(2^4)^4, Z(2^4)^11, Z(2^4)^3, Z(2^2)^2, Z(2^4)^2, Z(2^4)^9, Z(2^4), Z(2^4)^8 ] gap> x:=X(F);; gap> R1:=PolynomialRing(F,[x]);; gap> vars:=IndeterminatesOfPolynomialRing(R1);; gap> y:=X(F,vars);; gap> R2:=PolynomialRing(F,[x,y]);; gap> C:=GeneralizedReedSolomonCode(Pts,3,R1); a linear [15,3,1..13]10..12 generalized Reed-Solomon code over GF(16) gap> MinimumDistance(C); 13 gap> z:=Zero(F); 0*Z(2) gap> r:=[z,z,z,z,z,z,z,z,b^6,b^2,b^5,b^14,b,b^7,b^11];; gap> r:=Codeword(r); [ 0 0 0 0 0 0 0 0 a^12 a^14 a^5 a^8 a^7 a^4 a^2 ] gap> cs:=NearestNeighborDecodewords(C,r,7); [ [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ], [ 0 a^9 a^3 a^13 a^6 a^10 a^11 a a^12 a^14 a^5 a^8 a^7 a^4 a^2 ] ]

Syndrome
returns the syndrome of word v with respect to a linear code C. v is a codeword in the ambient vector space of C. If v is an element of C, the syndrome is a zero vector. The syndrome can be used for looking up an error vector in the syndrome table (see ) that is needed to correct an error in v.

A syndrome is not defined for non-linear codes. Syndrome then returns an error.
gap> C := HammingCode(4); a linear [15,11,3]1 Hamming (4,2) code over GF(2) gap> v := CodewordNr( C, 7 ); [ 1 1 0 0 0 0 0 0 0 0 0 0 1 1 0 ] gap> Syndrome( C, v ); [ 0 0 0 0 ] gap> Syndrome( C, Codeword( "000000001100111" ) ); [ 1 1 1 1 ] gap> Syndrome( C, Codeword( "000000000000001" ) ); [ 1 1 1 1 ] # the same syndrome: both codewords are in the same # coset of C
SyndromeTable
returns a syndrome table of a linear code C, consisting of two columns. The first column consists of the error vectors that correspond to the syndrome vectors in the second column. These vectors both are of the codeword type. After calculating the syndrome of a word v with Syndrome (see ), the error vector needed to correct v can be found in the syndrome table. Subtracting this vector from v yields an element of C. To make the search for the syndrome as fast as possible, the syndrome table is sorted according to the syndrome vectors.
syndrome table
gap> H := HammingCode(2); a linear [3,1,3]1 Hamming (2,2) code over GF(2) gap> SyndromeTable(H); [ [ [ 0 0 0 ], [ 0 0 ] ], [ [ 1 0 0 ], [ 0 1 ] ], [ [ 0 1 0 ], [ 1 0 ] ], [ [ 0 0 1 ], [ 1 1 ] ] ] gap> c := Codeword("101"); [ 1 0 1 ] gap> c in H; false # c is not an element of H gap> Syndrome(H,c); [ 1 0 ] # according to the syndrome table, # the error vector [ 0 1 0 ] belongs to this syndrome gap> c - Codeword("010") in H; true # so the corrected codeword is # [ 1 0 1 ] - [ 0 1 0 ] = [ 1 1 1 ], # this is an element of H
StandardArray
returns the standard array of a code C. This is a matrix with elements of the codeword type. It has q^r rows and q^k columns, where q is the size of the base field of C, r=n-k is the redundancy of C, and k is the dimension of C. The first row contains all the elements of C. Each other row contains words that do not belong to the code, with in the first column their syndrome vector (see ).

A non-linear code does not have a standard array. StandardArray then returns an error.

Note that calculating a standard array can be very time- and memory- consuming.
gap> StandardArray(RepetitionCode(3)); [ [ [ 0 0 0 ], [ 1 1 1 ] ], [ [ 0 0 1 ], [ 1 1 0 ] ], [ [ 0 1 0 ], [ 1 0 1 ] ], [ [ 1 0 0 ], [ 0 1 1 ] ] ]
PermutationDecode
performs permutation decoding when possible and returns original vector and prints 'fail' when not possible.

This uses AutomorphismGroup in the binary case, and (the slower) PermutationAutomorphismGroup otherwise, to compute the permutation automorphism group P of C. The algorithm runs through the elements p of P checking if the weight of H(p\cdot v) is less than (d-1)/2. If it is then the vector p\cdot v is used to decode v: assuming C is in standard form then c=p^{-1}Em is the decoded word, where m is the information digits part of p\cdot v. If no such p exists then ``fail'' is returned. See, for example, section 10.2 of Huffman and Pless for more details.
gap> C0:=HammingCode(3,GF(2)); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> G0:=GeneratorMat(C0);; gap> G := List(G0, ShallowCopy);; gap> PutStandardForm(G); () gap> Display(G); 1 . . . . 1 1 . 1 . . 1 . 1 . . 1 . 1 1 . . . . 1 1 1 1 gap> H0:=CheckMat(C0);; gap> Display(H0); . . . 1 1 1 1 . 1 1 . . 1 1 1 . 1 . 1 . 1 gap> c0:=Random(C0); [ 0 0 0 1 1 1 1 ] gap> v01:=c0[1]+Z(2)^2;; gap> v1:=List(c0, ShallowCopy);; gap> v1[1]:=v01;; gap> v1:=Codeword(v1); [ 1 0 0 1 1 1 1 ] gap> c1:=PermutationDecode(C0,v1); [ 0 0 0 1 1 1 1 ] gap> c1=c0; true
Coding theory functions in the GAP kernel

This chapter will recall from the GAP manual the GAP coding theory functions, some of which are partially written in C. The main functions are AClosestVectorCombinationsMatFFEVecFFE, AClosestVectorCombinationsMatFFEVecFFECoords, CosetLeadersMatFFE, DistancesDistributionMatFFEVecFFE, DistancesDistributionVecFFEsVecFFE, DistanceVecFFE, and WeightVecFFE. These are declared in the GAP library file 'listcoef.gd' and implemented in 'listcoef.gi'.

Distance functions
This command runs through the F-linear combinations of the vectors in the rows of the matrix mat that can be written as linear combinations of exactly r rows (that is without using zero as a coefficient) and returns a vector from these that is closest to the vector vec. The length of the rows of mat and the length of vec must be equal, and all elements must lie in F. The rows of mat must be linearly independent. If it finds a vector of distance at most st, which must be a nonnegative integer, then it stops immediately and returns this vector.

gap> F:=GF(3);; gap> x:= Indeterminate( F );; pol:= x^2+1; x_1^2+Z(3)^0 gap> C := GeneratorPolCode(pol,8,F); a cyclic [8,6,1..2]1..2 code defined by generator polynomial over GF(3) gap> v:=Codeword("12101111"); [ 1 2 1 0 1 1 1 1 ] gap> v:=VectorCodeword(v); [ Z(3)^0, Z(3), Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ] gap> G:=GeneratorMat(C); [ [ Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], [ 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3) ], [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ] ] gap> AClosestVectorCombinationsMatFFEVecFFE(G,F,v,1,1); [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ]
AClosestVectorCombinationsMatFFEVecFFECoords
returns a two element list containing (a) the same closest vector as in AClosestVectorCombinationsMatFFEVecFFE, and (b) a vector v with exactly r non-zero entries, such that v*mat is the closest vector.
gap> F:=GF(3);; gap> x:= Indeterminate( F );; pol:= x^2+1; x_1^2+Z(3)^0 gap> C := GeneratorPolCode(pol,8,F); a cyclic [8,6,1..2]1..2 code defined by generator polynomial over GF(3) gap> v:=Codeword("12101111"); v:=VectorCodeword(v);; [ 1 2 1 0 1 1 1 1 ] gap> G:=GeneratorMat(C);; gap> AClosestVectorCombinationsMatFFEVecFFECoords(G,F,v,1,1); [ [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ], [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0 ] ]
DistancesDistributionMatFFEVecFFE
returns the distances distribution of the vector vec to the vectors in the list vecs. All vectors must have the same length, and all elements must lie in a common field. The distances distribution is a list d of length Length(vec)+1, such that the value d[i] is the number of vectors in vecs that have distance i+1 to vec.
gap> v:=[ Z(3)^0, Z(3), Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ];; gap> vecs:=[ [ Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ] ];; gap> DistancesDistributionMatFFEVecFFE(vecs,GF(3),v); [ 0, 4, 6, 60, 109, 216, 192, 112, 30 ]
DistancesDistributionVecFFEsVecFFE
returns the distances distribution of the vector vec to the vectors in the list vecs. All vectors must have the same length, and all elements must lie in a common field. The distances distribution is a list d of length Length(vec)+1, such that the value d[i] is the number of vectors in vecs that have distance i+1 to vec.

gap> v:=[ Z(3)^0, Z(3), Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ];; gap> vecs:=[ [ Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0, 0*Z(3) ], > [ 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ] ];; gap> DistancesDistributionVecFFEsVecFFE(vecs,v); [ 0, 0, 0, 0, 0, 4, 0, 1, 1 ]
Other functions
WeightVecFFE
returns the weight of the finite field vector vec, i.e. the number of nonzero entries.
gap> v:=[ Z(3)^0, Z(3), Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ];; gap> WeightVecFFE(v); 7
Hamming metric
The Hamming metric on GF(q)^n is the function dist((v_1,...,v_n),(w_1,...,w_n)) =|\{i\in [1..n]\ |\ v_i\not= w_i\}|. This is also called the (Hamming) distance between v=(v_1,...,v_n) and w=(w_1,...,w_n). DistanceVecFFE returns the distance between the two vectors vec1 and vec2, which must have the same length and whose elements must lie in a common field. The distance is the number of places where vec1 and vec2 differ.
gap> v1:=[ Z(3)^0, Z(3), Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ];; gap> v2:=[ Z(3), Z(3)^0, Z(3)^0, 0*Z(3), Z(3)^0, Z(3)^0, Z(3)^0, Z(3)^0 ];; gap> DistanceVecFFE(v1,v2); 2
Generating Codes

In this chapter we describe functions for generating codes.

Section describes functions for generating unrestricted codes.

Section describes functions for generating linear codes.

Section describes functions for constructing certain covering codes, such as the Gabidulin codes.

Section describes functions for constructing the Golay codes.

Section describes functions for generating cyclic codes.

Section describes functions for generating codes as the image of an evaluation map applied to a space of functions. For example, generalized Reed-Solomon codes and toric codes are described there.

Generating Unrestricted Codes

In this section we start with functions that creating code from user defined matrices or special matrices (see , , and ). These codes are unrestricted codes; they may later be discovered to be linear or cyclic.

The next functions generate random codes (see ) and the Nordstrom-Robinson code (see ), respectively.

Finally, we describe two functions for generating Greedy codes. These are codes that contructed by gathering codewords from a space (see and ).

ElementsCode
creates an unrestricted code of the list of elements L, in the field F. L must be a list of vectors, strings, polynomials or codewords. name can contain a short description of the code.

If L contains a codeword more than once, it is removed from the list and a &GAP; set is returned.
gap> M := Z(3)^0 * [ [1, 0, 1, 1], [2, 2, 0, 0], [0, 1, 2, 2] ];; gap> C := ElementsCode( M, "example code", GF(3) ); a (4,3,1..4)2 example code over GF(3) gap> MinimumDistance( C ); 4 gap> AsSSortedList( C ); [ [ 0 1 2 2 ], [ 1 0 1 1 ], [ 2 2 0 0 ] ]
code, Hadamard
The four forms this command can take are HadamardCode(H,t), HadamardCode(H), HadamardCode(n,t), and HadamardCode(n).

In the case when the arguments H and t are both given, HadamardCode returns a Hadamard code of the t^{th} kind from the Hadamard matrix H In case only H is given, t = 3 is used.

By definition, a Hadamard matrix is a square matrix H with H\cdot H^T = -n\cdot I_n, where n is the size of H. The entries of H are either 1 or -1. Hadamard matrix

The matrix H is first transformed into a binary matrix A_n by replacing the 1's by 0's and the -1's by 1s).

The Hadamard matrix of the first kind (t=1) is created by using the rows of A_n as elements, after deleting the first column. This is a (n-1, n, n/2) code. We use this code for creating the Hadamard code of the second kind (t=2), by adding all the complements of the already existing codewords. This results in a (n-1, 2n, n/2 -1) code. The third kind (t=3) is created by using the rows of A_n (without cutting a column) and their complements as elements. This way, we have an (n, 2n, n/2)-code. The returned code is generally an unrestricted code, but for n = 2^r, the code is linear.

The command HadamardCode(n,t) returns a Hadamard code with parameter n of the t^{th} kind. For the command HadamardCode(n), t=3 is used.

When called in these forms, HadamardCode first creates a Hadamard matrix (see ), of size n and then follows the same procedure as described above. Therefore the same restrictions with respect to n as for Hadamard matrices hold.
gap> H4 := [[1,1,1,1],[1,-1,1,-1],[1,1,-1,-1],[1,-1,-1,1]];; gap> HadamardCode( H4, 1 ); a (3,4,2)1 Hadamard code of order 4 over GF(2) gap> HadamardCode( H4, 2 ); a (3,8,1)0 Hadamard code of order 4 over GF(2) gap> HadamardCode( H4 ); a (4,8,2)1 Hadamard code of order 4 over GF(2) gap> H4 := [[1,1,1,1],[1,-1,1,-1],[1,1,-1,-1],[1,-1,-1,1]];; gap> C := HadamardCode( 4 ); a (4,8,2)1 Hadamard code of order 4 over GF(2) gap> C = HadamardCode( H4 ); true
code, conference
ConferenceCode
returns a code of length n-1 constructed from a symmetric 'conference matrix' H. A conference matrix H is a symmetric matrix of order n, which satisfies H\cdot H^T = ((n-1)\cdot I, with n \equiv 2 \pmod 4. The rows of \frac{1}{2}(H+I+J), \frac{1}{2}(-H+I+J), plus the zero and all-ones vectors form the elements of a binary non-linear (n-1, 2n, (n-2)/2) code. conference matrix

GUAVA
constructs a symmetric conference matrix of order n+1 (n\equiv 1 \pmod 4) and uses the rows of that matrix, plus the zero and all-ones vectors, to construct a binary non-linear (n, 2(n+1), (n-1)/2)-code.
gap> H6 := [[0,1,1,1,1,1],[1,0,1,-1,-1,1],[1,1,0,1,-1,-1], > [1,-1,1,0,1,-1],[1,-1,-1,1,0,1],[1,1,-1,-1,1,0]];; gap> C1 := ConferenceCode( H6 ); a (5,12,2)1..4 conference code over GF(2) gap> IsLinearCode( C1 ); false gap> C2 := ConferenceCode( 5 ); a (5,12,2)1..4 conference code over GF(2) gap> AsSSortedList( C2 ); [ [ 0 0 0 0 0 ], [ 0 0 1 1 1 ], [ 0 1 0 1 1 ], [ 0 1 1 0 1 ], [ 0 1 1 1 0 ], [ 1 0 0 1 1 ], [ 1 0 1 0 1 ], [ 1 0 1 1 0 ], [ 1 1 0 0 1 ], [ 1 1 0 1 0 ], [ 1 1 1 0 0 ], [ 1 1 1 1 1 ] ]
MOLSCode
returns an (n, q^2, n-1) code over GF(q). The code is created from n-2 'Mutually Orthogonal Latin Squares' (MOLS) of size q \times q. The default for n is 4. `GUAVA` can construct a MOLS code for n-2 \leq q. Here q must be a prime power, q > 2. If there are no n-2 MOLS, an error is signalled.

Since each of the n-2 MOLS is a q\times q matrix, we can create a code of size q^2 by listing in each code element the entries that are in the same position in each of the MOLS. We precede each of these lists with the two coordinates that specify this position, making the word length become n.

The MOLS codes are MDS codes (see ).
gap> C1 := MOLSCode( 6, 5 ); a (6,25,5)3..4 code generated by 4 MOLS of order 5 over GF(5) gap> mols := List( [1 .. WordLength(C1) - 2 ], function( nr ) > local ls, el; > ls := NullMat( Size(LeftActingDomain(C1)), Size(LeftActingDomain(C1)) ); > for el in VectorCodeword( AsSSortedList( C1 ) ) do > ls[IntFFE(el[1])+1][IntFFE(el[2])+1] := el[nr + 2]; > od; > return ls; > end );; gap> AreMOLS( mols ); true gap> C2 := MOLSCode( 11 ); a (4,121,3)2 code generated by 2 MOLS of order 11 over GF(11)
RandomCode
returns a random unrestricted code of size M with word length n over F. M must be less than or equal to the number of elements in the space GF(q)^n.

The function RandomLinearCode returns a random linear code (see ).
gap> C1 := RandomCode( 6, 10, GF(8) ); a (6,10,1..6)4..6 random unrestricted code over GF(8) gap> MinimumDistance(C1); 3 gap> C2 := RandomCode( 6, 10, GF(8) ); a (6,10,1..6)4..6 random unrestricted code over GF(8) gap> C1 = C2; false
code, Nordstrom-Robinson
NordstromRobinsonCode
returns a Nordstrom-Robinson code, the best code with word length n=16 and minimum distance d=6 over GF(2). This is a non-linear (16, 256, 6) code.
gap> C := NordstromRobinsonCode(); a (16,256,6)4 Nordstrom-Robinson code over GF(2) gap> OptimalityCode( C ); 0
code, greedy
GreedyCode
returns a Greedy code with design distance d over the finite field F. The code is constructed using the greedy algorithm on the list of vectors L. (The greedy algorithm checks each vector in L and adds it to the code if its distance to the current code is greater than or equal to d. It is obvious that the resulting code has a minimum distance of at least d.

Greedy codes are often linear codes.

The function LexiCode creates a greedy code from a basis instead of an enumerated list (see ).
gap> C1 := GreedyCode( Tuples( AsSSortedList( GF(2) ), 5 ), 3, GF(2) ); a (5,4,3..5)2 Greedy code, user defined basis over GF(2) gap> C2 := GreedyCode( Permuted( Tuples( AsSSortedList( GF(2) ), 5 ), > (1,4) ), 3, GF(2) ); a (5,4,3..5)2 Greedy code, user defined basis over GF(2) gap> C1 = C2; false
In this format, Lexicode returns a lexicode with word length n, design distance d over F. The code is constructed using the greedy algorithm on the lexicographically ordered list of all vectors of length n over F. Every time a vector is found that has a distance to the current code of at least d, it is added to the code. This results, obviously, in a code with minimum distance greater than or equal to d.

Another syntax which one can use is LexiCode( B, d, F ). When called in this format, LexiCode uses the basis B instead of the standard basis. B is a matrix of vectors over F. The code is constructed using the greedy algorithm on the list of vectors spanned by B, ordered lexicographically with respect to B.

Note that binary lexicodes are always linear.
gap> C := LexiCode( 4, 3, GF(5) ); a (4,17,3..4)2..4 lexicode over GF(5) gap> B := [ [Z(2)^0, 0*Z(2), 0*Z(2)], [Z(2)^0, Z(2)^0, 0*Z(2)] ];; gap> C := LexiCode( B, 2, GF(2) ); a linear [3,1,2]1..2 lexicode over GF(2)

The function GreedyCode creates a greedy code that is not restricted to a lexicographical order (see ).

Generating Linear Codes

In this section we describe functions for constructing linear codes. A linear code always has a generator or check matrix.

The first two functions generate linear codes from the generator matrix () or check matrix (). All linear codes can be constructed with these functions.

The next functions we describe generate some well-known codes, like Hamming codes (), Reed-Muller codes () and the extended Golay codes ( and ).

A large and powerful family of codes are alternant codes. They are obtained by a small modification of the parity check matrix of a BCH code (see , , and ).

Finally, we describe a function for generating random linear codes (see ).

GeneratorMatCode
returns a linear code with generator matrix G. G must be a matrix over finite field F. name can contain a short description of the code. The generator matrix is the basis of the elements of the code. The resulting code has word length n, dimension k if G is a k \times n-matrix. If GF(q) is the field of the code, the size of the code will be q^k. Before printing the information [n,k,d_1..d_2]r_1..r_2 about the code to the screen using ViewObj (an undocumented internal `GUAVA` command), upper and lower estimates for the minimum distance and covering radius are computed. These estimates are obtained as follows: first, if n and q are not too big, `GUAVA` searches though the tables in the `tbl' subdirectory for best-known upper bounds. This can be time-consuming. Otherwise, `GUAVA` simply calls BoundsMinimumDistance and BoundsCoveringRadius. ViewObj

If the generator matrix does not have full row rank, the linearly dependent rows are removed. This is done by the &GAP; function BaseMat and results in an equal code. The generator matrix can be retrieved with the function GeneratorMat (see ).
gap> G := Z(3)^0 * [[1,0,1,2,0],[0,1,2,1,1],[0,0,1,2,1]];; gap> C1 := GeneratorMatCode( G, GF(3) ); a linear [5,3,1..2]1..2 code defined by generator matrix over GF(3) gap> C2 := GeneratorMatCode( IdentityMat( 5, GF(2) ), GF(2) ); a linear [5,5,1]0 code defined by generator matrix over GF(2) gap> GeneratorMatCode( List( AsSSortedList( NordstromRobinsonCode() ), > x -> VectorCodeword( x ) ), GF( 2 ) ); a linear [16,11,1..4]2 code defined by generator matrix over GF(2) # This is the smallest linear code that contains the N-R code
GeneratorMatCodeNC
returns a linear code C with generator matrix G. This command is the same as GeneratorMatCode, except that (1) it does not compute upper and lower bounds for the minimum distance or covering radius for C, and (2) it does not allow for an optional argument name. This command is much faster than GeneratorMatCode in some cases.
CheckMatCode
returns a linear code with check matrix H. H must be a matrix over Galois field F. [name. can contain a short description of the code. The parity check matrix is the transposed of the nullmatrix of the generator matrix of the code. Therefore, c\cdot H^T = 0 where c is an element of the code. If H is a r\times n-matrix, the code has word length n, redundancy r and dimension n-r.

If the check matrix does not have full row rank, the linearly dependent rows are removed. This is done by the &GAP; function BaseMat. and results in an equal code. The check matrix can be retrieved with the function CheckMat (see ).
gap> G := Z(3)^0 * [[1,0,1,2,0],[0,1,2,1,1],[0,0,1,2,1]];; gap> C1 := CheckMatCode( G, GF(3) ); a linear [5,2,1..2]2..3 code defined by check matrix over GF(3) gap> CheckMat(C1); [ [ Z(3)^0, 0*Z(3), Z(3)^0, Z(3), 0*Z(3) ], [ 0*Z(3), Z(3)^0, Z(3), Z(3)^0, Z(3)^0 ], [ 0*Z(3), 0*Z(3), Z(3)^0, Z(3), Z(3)^0 ] ] gap> C2 := CheckMatCode( IdentityMat( 5, GF(2) ), GF(2) ); a cyclic [5,0,5]5 code defined by check matrix over GF(2)
code, Hamming
HammingCode
returns a Hamming code with redundancy r over F. A Hamming code is a single-error-correcting code. The parity check matrix of a Hamming code has all nonzero vectors of length r in its columns, except for a multiplication factor. The decoding algorithm of the Hamming code (see ) makes use of this property.

If q is the size of its field F, the returned Hamming code is a linear [(q^r-1)/(q-1), (q^r-1)/(q-1) - r, 3] code.
gap> C1 := HammingCode( 4, GF(2) ); a linear [15,11,3]1 Hamming (4,2) code over GF(2) gap> C2 := HammingCode( 3, GF(9) ); a linear [91,88,3]1 Hamming (3,9) code over GF(9)
code, Reed-Muller
ReedMullerCode
returns a binary 'Reed-Muller code' R(r, k) with dimension k and order r. This is a code with length 2^k and minimum distance 2^{k-r} (see for example, section 1.10 in ). By definition, the r^{th} order binary Reed-Muller code of length n=2^m, for 0 \leq r \leq m, is the set of all vectors f, where f is a Boolean function which is a polynomial of degree at most r.
gap> ReedMullerCode( 1, 3 ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2)

See for a more general construction.

code, alternant
AlternantCode
returns an 'alternant code', with parameters r, Y and alpha (optional). F denotes the (finite) base field. Here, r is the design redundancy of the code. Y and alpha are both vectors of length n from which the parity check matrix is constructed. The check matrix has the form H=([a_i^j y_i]), where 0 \leq j\leq r-1, 1 \leq i\leq n, and where [...] is as in ). If no alpha is specified, the vector [1, a, a^2, .., a^{n-1}] is used, where a is a primitive element of a Galois field F.
gap> Y := [ 1, 1, 1, 1, 1, 1, 1];; a := PrimitiveUnityRoot( 2, 7 );; gap> alpha := List( [0..6], i -> a^i );; gap> C := AlternantCode( 2, Y, alpha, GF(8) ); a linear [7,3,3..4]3..4 alternant code over GF(8)
code, Goppa (classical)
GoppaCode
returns a Goppa code C from Goppa polynomial g, having coefficients in a Galois Field GF(q). L must be a list of elements in GF(q), that are not roots of g. The word length of the code is equal to the length of L. The parity check matrix has the form H=([a_i^j / G(a_i)])_{0 \leq j \leq deg(g)-1,\ a_i \in L}, where a_i\in L and [...] is as in , so H has entries in GF(q), q=p^m. It is known that d(C)\geq deg(g)+1, with a better bound in the binary case provided g has no multiple roots. See Huffman and Pless section 13.2.2, and MacWilliams and Sloane section 12.3, for more details.

One can also call GoppaCode using the syntax GoppaCode(g,n). When called with parameter n, `GUAVA` constructs a list L of length n, such that no element of L is a root of g.

This is a special case of an alternant code.
gap> x:=Indeterminate(GF(8),"x"); x gap> L:=Elements(GF(8)); [ 0*Z(2), Z(2)^0, Z(2^3), Z(2^3)^2, Z(2^3)^3, Z(2^3)^4, Z(2^3)^5, Z(2^3)^6 ] gap> g:=x^2+x+1; x^2+x+Z(2)^0 gap> C:=GoppaCode(g,L); a linear [8,2,5]3 Goppa code over GF(2) gap> xx := Indeterminate( GF(2), "xx" );; gap> gg := xx^2 + xx + 1;; L := AsSSortedList( GF(8) );; gap> C1 := GoppaCode( gg, L ); a linear [8,2,5]3 Goppa code over GF(2) gap> y := Indeterminate( GF(2), "y" );; gap> h := y^2 + y + 1;; gap> C2 := GoppaCode( h, 8 ); a linear [8,2,5]3 Goppa code over GF(2) gap> C1=C2; true gap> C=C1; true
code, Srivastava
GeneralizedSrivastavaCode
returns a generalized Srivastava code with parameters a, w, z, t. a =\{ a_1, ..., a_n\} and w =\{ w_1, ..., w_s\} are lists of n+s distinct elements of F=GF(q^m), z is a list of length n of nonzero elements of GF(q^m). The parameter t determines the designed distance: d \geq st + 1. The check matrix of this code is the form H=([\frac{z_i}{(a_i - w_j)^k}]), 1\leq k\leq t, where [...] is as in . We use this definition of H to define the code. The default for t is 1. The original Srivastava codes (see ) are a special case t=1, z_i=a_i^\mu, for some \mu.

gap> a := Filtered( AsSSortedList( GF(2^6) ), e -> e in GF(2^3) );; gap> w := [ Z(2^6) ];; z := List( [1..8], e -> 1 );; gap> C := GeneralizedSrivastavaCode( a, w, z, 1, GF(64) ); a linear [8,2,2..5]3..4 generalized Srivastava code over GF(2)
SrivastavaCode
returns a Srivastava code with parameters a, w (and optionally mu). a =\{ a_1, ..., a_n\} and w =\{ w_1, ..., w_s\} are lists of n+s distinct elements of F=GF(q^m). The default for mu is 1. The Srivastava code is a generalized Srivastava code, in which z_i = a_i^{mu} for some mu and t=1.

J. N. Srivastava introduced this code in 1967, though his work was not published. See Helgert for more details on the properties of this code. Related reference: G. Roelofsen, On Goppa and Generalized Srivastava Codes PhD thesis, Dept. Math. and Comp. Sci., Eindhoven Univ. of Technology, the Netherlands, 1982.

gap> a := AsSSortedList( GF(11) ){[2..8]};; gap> w := AsSSortedList( GF(11) ){[9..10]};; gap> C := SrivastavaCode( a, w, 2, GF(11) ); a linear [7,5,3]2 Srivastava code over GF(11) gap> IsMDSCode( C ); true # Always true if F is a prime field
code, Cordaro-Wagner
CordaroWagnerCode
returns a binary Cordaro-Wagner code. This is a code of length n and dimension 2 having the best possible minimum distance d. This code is just a little bit less trivial than RepetitionCode (see ).

gap> C := CordaroWagnerCode( 11 ); a linear [11,2,7]5 Cordaro-Wagner code over GF(2) gap> AsSSortedList(C); [ [ 0 0 0 0 0 0 0 0 0 0 0 ], [ 0 0 0 0 1 1 1 1 1 1 1 ], [ 1 1 1 1 0 0 0 1 1 1 1 ], [ 1 1 1 1 1 1 1 0 0 0 0 ] ]
RandomLinearCode
returns a random linear code with word length n, dimension k over field F. The method used is to first construct a k\times n matrix of the block form (I,A), where I is a k\times k identity matrix and A is a k\times (n-k) matrix constructed using Random(F) repeatedly. Then the columns are permuted using a randomly selected element of SymmetricGroup(n).

To create a random unrestricted code, use RandomCode (see ).
gap> C := RandomLinearCode( 15, 4, GF(3) ); a [15,4,?] randomly generated code over GF(3) gap> Display(C); a linear [15,4,1..6]6..10 random linear code over GF(3)

The method `GUAVA` chooses to output the result of a RandomLinearCode command is different than other codes. For example, the bounds on the minimum distance is not displayed. Howeer, you can use the Display command to print this information. This new display method was added in version 1.9 to speed up the command (if n is about 80 and k about 40, for example, the time it took to look up and/or calculate the bounds on the minimum distance was too long).

In general this command is no longer accurate, since the tables have not been updated since 1998. See the web site http://www.win.tue.nl/~aeb/voorlincod.html for more recent data.

OptimalityCode
returns the difference between the smallest known upper bound and the actual size of the code. Note that the value of the function UpperBound is not always equal to the actual upper bound A(n,d) thus the result may not be equal to 0 even if the code is optimal!

OptimalityLinearCode
is similar but applies only to linear codes.
In general this command is no longer accurate, since the tables have not been updated since 1998. See the web site http://www.win.tue.nl/~aeb/voorlincod.html for more recent data.

BestKnownLinearCode
returns the best known (as of 1998) linear code of length n, dimension k over field F. The function uses the tables described in section to construct this code.

This command can also be called using the syntax BestKnownLinearCode( rec ), where rec must be a record containing the fields `lowerBound', `upperBound' and `construction'. It uses the information in this field to construct a code. This form is meant to be used together with the function BoundsMinimumDistance (see ), if the bounds are already calculated.
gap> C1 := BestKnownLinearCode( 23, 12, GF(2) ); a cyclic [23,12,7]3 binary Golay code over GF(2) gap> C1 = BinaryGolayCode(); true gap> Display( BestKnownLinearCode( 8, 4, GF(4) ) ); a linear [8,4,4]2..3 U U+V construction code of U: a cyclic [4,3,2]1 dual code of a cyclic [4,1,4]3 repetition code over GF(4) V: a cyclic [4,1,4]3 repetition code over GF(4) gap> C := BestKnownLinearCode(131,47); a linear [131,47,28..32]23..68 shortened code gap> bounds := BoundsMinimumDistance( 20, 17, GF(4) ); rec( n := 20, k := 17, q := 4, references := rec( HM := [ "%T this reference is unknown, for more info", "%T contact A.E. Brouwer (aeb@cwi.nl)" ] ), construction := [ [Operation "ShortenedCode"], [ [ [Operation "HammingCode"], [ 3, 4 ] ], [ 1 ] ] ], lowerBound := 3, lowerBoundExplanation := [ "Lb(20,17)=3, by shortening of:", "Lb(21,18)=3, reference: HM" ], upperBound := 3, upperBoundExplanation := [ "Ub(20,17)=3, otherwise construction B would contradict:", "Ub(3,1)=3, repetition code" ] ) gap> C := BestKnownLinearCode( bounds ); a linear [20,17,3]2 shortened code gap> C = BestKnownLinearCode( 20, 17, GF(4) ); true
Gabidulin Codes

These five binary, linear codes are derived from an article by Gabidulin, Davydov and Tombak . All these codes are defined by check matrices. Exact definitions can be found in the article. The Gabidulin code, the enlarged Gabidulin code, the Davydov code, the Tombak code, and the enlarged Tombak code, correspond with theorem 1, 2, 3, 4, and 5, respectively in the article.

Like the Hamming codes, these codes have fixed minimum distance and covering radius, but can be arbitrarily long.

code, Gabidulin
GabidulinCode
yields a code of length 5 . 2^{m-2}-1, redundancy 2m-1, minimum distance 3 and covering radius 2. w1 and w2 should be elements of GF(2^{m-2}).
EnlargedGabidulinCode
yields a code of length 7. 2^{m-2}-2, redundancy 2m, minimum distance 3 and covering radius 2. w1 and w2 are elements of GF(2^{m-2}). e is an element of GF(2^m).
code, Davydov
DavydovCode
yields a code of length 2^v + 2^{r-v} - 3, redundancy r, minimum distance 4 and covering radius 2. v is an integer between 2 and r-2. ei and ej are elements of GF(2^v) and GF(2^{r-v}), respectively.
code, Tombak
TombakCode
yields a code of length 15 \cdot 2^{m-3} - 3, redundancy 2m, minimum distance 4 and covering radius 2. e is an element of GF(2^m). beta and gamma are elements of GF(2^{m-1}). w1 and w2 are elements of GF(2^{m-3}).
EnlargedTombakCode
yields a code of length 23 \cdot 2^{m-4} - 3, redundancy 2m-1, minimum distance 4 and covering radius 2. The parameters m, e, beta, gamma, w1 and w2 are defined as in TombakCode. u is an element of GF(2^{m-1}).
gap> GabidulinCode( 4, Z(4)^0, Z(4)^1 ); a linear [19,12,3]2 Gabidulin code (m=4) over GF(2) gap> EnlargedGabidulinCode( 4, Z(4)^0, Z(4)^1, Z(16)^11 ); a linear [26,18,3]2 enlarged Gabidulin code (m=4) over GF(2) gap> DavydovCode( 6, 3, Z(8)^1, Z(8)^5 ); a linear [13,7,4]2 Davydov code (r=6, v=3) over GF(2) gap> TombakCode( 5, Z(32)^6, Z(16)^14, Z(16)^10, Z(4)^0, Z(4)^1 ); a linear [57,47,4]2 Tombak code (m=5) over GF(2) gap> EnlargedTombakCode( 6, Z(32)^6, Z(16)^14, Z(16)^10, > Z(4)^0, Z(4)^0, Z(32)^23 ); a linear [89,78,4]2 enlarged Tombak code (m=6) over GF(2)
Golay Codes
The Golay code is probably the most important of all codes for both practical and theoretical reasons.
(, pg. 64). Though born in Switzerland, M. J. E. Golay (1902-1989) worked for the US Army Labs for most of his career. For more information on his life, see his obit in the June 1990 IEEE Information Society Newsletter.

code, Golay (binary)
BinaryGolayCode
returns a binary Golay code. This is a perfect [23,12,7] code. It is also cyclic, and has generator polynomial g(x)=1+x^2+x^4+x^5+x^6+x^{10}+x^{11}. Extending it results in an extended Golay code (see ). There's also the ternary Golay code (see ).
gap> C:=BinaryGolayCode(); a cyclic [23,12,7]3 binary Golay code over GF(2) gap> ExtendedBinaryGolayCode() = ExtendedCode(BinaryGolayCode()); true gap> IsPerfectCode(C); true gap> IsCyclicCode(C); true
ExtendedBinaryGolayCode
returns an extended binary Golay code. This is a [24,12,8] code. Puncturing in the last position results in a perfect binary Golay code (see ). The code is self-dual.
gap> C := ExtendedBinaryGolayCode(); a linear [24,12,8]4 extended binary Golay code over GF(2) gap> IsSelfDualCode(C); true gap> P := PuncturedCode(C); a linear [23,12,7]3 punctured code gap> P = BinaryGolayCode(); true gap> IsCyclicCode(C); false

code, Golay (ternary)
TernaryGolayCode
returns a ternary Golay code. This is a perfect [11,6,5] code. It is also cyclic, and has generator polynomial g(x)=2+x^2+2x^3+x^4+x^5. Extending it results in an extended Golay code (see ). There's also the binary Golay code (see ).
gap> C:=TernaryGolayCode(); a cyclic [11,6,5]2 ternary Golay code over GF(3) gap> ExtendedTernaryGolayCode() = ExtendedCode(TernaryGolayCode()); true gap> IsCyclicCode(C); true
ExtendedTernaryGolayCode
returns an extended ternary Golay code. This is a [12,6,6] code. Puncturing this code results in a perfect ternary Golay code (see ). The code is self-dual.
gap> C := ExtendedTernaryGolayCode(); a linear [12,6,6]3 extended ternary Golay code over GF(3) gap> IsSelfDualCode(C); true gap> P := PuncturedCode(C); a linear [11,6,5]2 punctured code gap> P = TernaryGolayCode(); true gap> IsCyclicCode(C); false
Generating Cyclic Codes

The elements of a cyclic code C are all multiples of a ('generator') polynomial g(x), where calculations are carried out modulo x^n-1. Therefore, as polynomials in x, the elements always have degree less than n. A cyclic code is an ideal in the ring F[x]/(x^n-1) of polynomials modulo x^n - 1. The unique monic polynomial of least degree that generates C is called the generator polynomial of C. It is a divisor of the polynomial x^n-1. generator polynomial check polynomial

The check polynomial is the polynomial h(x) with g(x)h(x)=x^n-1. Therefore it is also a divisor of x^n-1. The check polynomial has the property that c(x)h(x) \equiv 0 \pmod{x^n-1}, for every codeword c(x)\in C.

The first two functions described below generate cyclic codes from a given generator or check polynomial. All cyclic codes can be constructed using these functions.

Two of the Golay codes already described are cyclic (see and ). For example, the `GUAVA` record for a binary Golay code contains the generator polynomial:

gap> C := BinaryGolayCode(); a cyclic [23,12,7]3 binary Golay code over GF(2) gap> NamesOfComponents(C); [ "LeftActingDomain", "GeneratorsOfLeftOperatorAdditiveGroup", "WordLength", "GeneratorMat", "GeneratorPol", "Dimension", "Redundancy", "Size", "name", "lowerBoundMinimumDistance", "upperBoundMinimumDistance", "WeightDistribution", "boundsCoveringRadius", "MinimumWeightOfGenerators", "UpperBoundOptimalMinimumDistance" ] gap> C!.GeneratorPol; x_1^11+x_1^10+x_1^6+x_1^5+x_1^4+x_1^2+Z(2)^0

Then functions that generate cyclic codes from a prescribed set of roots of the generator polynomial are described, including the BCH codes (see , , and ).

Finally we describe the trivial codes (see , , ), and the command CyclicCodes which lists all cyclic codes ().

GeneratorPolCode
creates a cyclic code with a generator polynomial g, word length n, over F. name can contain a short description of the code.

If g is not a divisor of x^n-1, it cannot be a generator polynomial. In that case, a code is created with generator polynomial gcd( g, x^n-1 ), i.e. the greatest common divisor of g and x^n-1. This is a valid generator polynomial that generates the ideal (g). See .
gap> x:= Indeterminate( GF(2) );; P:= x^2+1; Z(2)^0+x^2 gap> C1 := GeneratorPolCode(P, 7, GF(2)); a cyclic [7,6,1..2]1 code defined by generator polynomial over GF(2) gap> GeneratorPol( C1 ); Z(2)^0+x gap> C2 := GeneratorPolCode( x+1, 7, GF(2)); a cyclic [7,6,1..2]1 code defined by generator polynomial over GF(2) gap> GeneratorPol( C2 ); Z(2)^0+x
CheckPolCode
creates a cyclic code with a check polynomial h, word length n, over F. name can contain a short description of the code (as a string).

If h is not a divisor of x^n-1, it cannot be a check polynomial. In that case, a code is created with check polynomial gcd( h, x^n-1 ), i.e. the greatest common divisor of h and x^n-1. This is a valid check polynomial that yields the same elements as the ideal (h). See .

gap> x:= Indeterminate( GF(3) );; P:= x^2+2; -Z(3)^0+x_1^2 gap> H := CheckPolCode(P, 7, GF(3)); a cyclic [7,1,7]4 code defined by check polynomial over GF(3) gap> CheckPol(H); -Z(3)^0+x_1 gap> Gcd(P, X(GF(3))^7-1); -Z(3)^0+x_1
This is the generalization of the BCH, Reed-Solomon and quadratic residue codes (see , and ). The user can give a length of the code n and a prescribed set of zeros. The argument list must be a valid list of primitive n^{th} roots of unity in a splitting field GF(q^m). The resulting code will be over the field GF(q). The function will return the largest possible cyclic code for which the list list is a subset of the roots of the code. From this list, `GUAVA` calculates the entire set of roots.

This command can also be called with the syntax RootsCode( n, list, q ). In this second form, the second argument is a list of integers, ranging from 0 to n-1. The resulting code will be over a field GF(q). `GUAVA` calculates a primitive n^{th} root of unity, \alpha, in the extension field of GF(q). It uses the set of the powers of \alpha in the list as a prescribed set of zeros.
gap> a := PrimitiveUnityRoot( 3, 14 ); Z(3^6)^52 gap> C1 := RootsCode( 14, [ a^0, a, a^3 ] ); a cyclic [14,7,3..6]3..7 code defined by roots over GF(3) gap> MinimumDistance( C1 ); 4 gap> b := PrimitiveUnityRoot( 2, 15 ); Z(2^4) gap> C2 := RootsCode( 15, [ b, b^2, b^3, b^4 ] ); a cyclic [15,7,5]3..5 code defined by roots over GF(2) gap> C2 = BCHCode( 15, 5, GF(2) ); true

code, Bose-Chaudhuri-Hockenghem
The function BCHCode returns a 'Bose-Chaudhuri-Hockenghem code' (or BCH code for short). This is the largest possible cyclic code of length n over field F, whose generator polynomial has zeros a^{b},a^{b+1}, ..., a^{b+delta-2}, where a is a primitive n^{th} root of unity in the splitting field GF(q^m), b is an integer 0\leq b\leq n-delta+1 and m is the multiplicative order of q modulo n. (The integers \{b,...,b+delta-2\} typically lie in the range \{1,...,n-1\}.) Default value for b is 1, though the algorithm allows b=0. The length n of the code and the size q of the field must be relatively prime. The generator polynomial is equal to the least common multiple of the minimal polynomials of a^{b}, a^{b+1}, ..., a^{b+delta-2}. The set of zeroes of the generator polynomial is equal to the union of the sets \{a^x\ |\ x \in C_k\}, where C_k is the k^{th} cyclotomic coset of q modulo n and b\leq k\leq b+delta-2 (see ).

Special cases are b=1 (resulting codes are called 'narrow-sense' BCH codes), and n=q^m-1 (known as 'primitive' BCH codes). `GUAVA` calculates the largest value of d for which the BCH code with designed distance d coincides with the BCH code with designed distance delta. This distance d is called the Bose distance of the code. The true minimum distance of the code is greater than or equal to the Bose distance. Bose distance

Printed are the designed distance (to be precise, the Bose distance) d, and the starting power b.

The Sugiyama decoding algorithm has been implemented for this code (see ).
gap> C1 := BCHCode( 15, 3, 5, GF(2) ); a cyclic [15,5,7]5 BCH code, delta=7, b=1 over GF(2) gap> DesignedDistance( C1 ); 7 gap> C2 := BCHCode( 23, 2, GF(2) ); a cyclic [23,12,5..7]3 BCH code, delta=5, b=1 over GF(2) gap> DesignedDistance( C2 ); 5 gap> MinimumDistance(C2); 7

See for a more general construction.

code, Reed-Solomon
ReedSolomonCode
returns a 'Reed-Solomon code' of length n, designed distance d. This code is a primitive narrow-sense BCH code over the field GF(q), where q=n+1. The dimension of an RS code is n-d+1. According to the Singleton bound (see ) the dimension cannot be greater than this, so the true minimum distance of an RS code is equal to d and the code is maximum distance separable (see ).
gap> C1 := ReedSolomonCode( 3, 2 ); a cyclic [3,2,2]1 Reed-Solomon code over GF(4) gap> IsCyclicCode(C1); true gap> C2 := ReedSolomonCode( 4, 3 ); a cyclic [4,2,3]2 Reed-Solomon code over GF(5) gap> RootsOfCode( C2 ); [ Z(5), Z(5)^2 ] gap> IsMDSCode(C2); true

See for a more general construction.

QRCode
returns a quadratic residue code. If F is a field GF(q), then q must be a quadratic residue modulo n. That is, an x exists with x^2 \equiv q \pmod n. Both n and q must be primes. Its generator polynomial is the product of the polynomials x-a^i. a is a primitive n^{th} root of unity, and i is an integer in the set of quadratic residues modulo n.
gap> C1 := QRCode( 7, GF(2) ); a cyclic [7,4,3]1 quadratic residue code over GF(2) gap> IsEquivalent( C1, HammingCode( 3, GF(2) ) ); true gap> IsCyclicCode(C1); true gap> IsCyclicCode(HammingCode( 3, GF(2) )); false gap> C2 := QRCode( 11, GF(3) ); a cyclic [11,6,4..5]2 quadratic residue code over GF(3) gap> C2 = TernaryGolayCode(); true
code, Fire
FireCode
constructs a (binary) Fire code. g is a primitive polynomial of degree m, and a factor of x^r-1. b an integer 0 \leq b \leq m not divisible by r, that determines the burst length of a single error burst that can be corrected. The argument g can be a polynomial with base ring GF(2), or a list of coefficients in GF(2). The generator polynomial of the code is defined as the product of g and x^{2b-1}+1.

Here is the general definition of 'Fire code', named after P. Fire, who introduced these codes in 1959 in order to correct burst errors. First, a definition. If F=GF(q) and f\in F[x] then we say f has order e if f(x)|(x^e-1). order of polynomial A Fire code is a cyclic code over F with generator polynomial g(x)= (x^{2t-1}-1)p(x), where p(x) does not divide x^{2t-1}-1 and satisfies deg(p(x))\geq t. The length of such a code is the order of g(x). Non-binary Fire codes have not been implemented.
.

gap> x:= Indeterminate( GF(2) );; G:= x^3+x^2+1; Z(2)^0+x^2+x^3 gap> Factors( G ); [ Z(2)^0+x^2+x^3 ] gap> C := FireCode( G, 3 ); a cyclic [35,27,1..4]2..6 3 burst error correcting fire code over GF(2) gap> MinimumDistance( C ); 4 # Still it can correct bursts of length 3
WholeSpaceCode
returns the cyclic whole space code of length n over F. This code consists of all polynomials of degree less than n and coefficients in F.
gap> C := WholeSpaceCode( 5, GF(3) ); a cyclic [5,5,1]0 whole space code over GF(3)
NullCode
returns the zero-dimensional nullcode with length n over F. This code has only one word: the all zero word. It is cyclic though!
gap> C := NullCode( 5, GF(3) ); a cyclic [5,0,5]5 nullcode over GF(3) gap> AsSSortedList( C ); [ [ 0 0 0 0 0 ] ]
RepetitionCode
returns the cyclic repetition code of length n over F. The code has as many elements as F, because each codeword consists of a repetition of one of these elements.
gap> C := RepetitionCode( 3, GF(5) ); a cyclic [3,1,3]2 repetition code over GF(5) gap> AsSSortedList( C ); [ [ 0 0 0 ], [ 1 1 1 ], [ 2 2 2 ], [ 4 4 4 ], [ 3 3 3 ] ] gap> IsPerfectCode( C ); false gap> IsMDSCode( C ); true
CyclicCodes
returns a list of all cyclic codes of length n over F. It constructs all possible generator polynomials from the factors of x^n-1. Each combination of these factors yields a generator polynomial after multiplication.
gap> CyclicCodes(3,GF(3)); [ a cyclic [3,3,1]0 enumerated code over GF(3), a cyclic [3,2,1..2]1 enumerated code over GF(3), a cyclic [3,1,3]2 enumerated code over GF(3), a cyclic [3,0,3]3 enumerated code over GF(3) ]
The function NrCyclicCodes calculates the number of cyclic codes of length n over field F.
gap> NrCyclicCodes( 23, GF(2) ); 8 gap> codelist := CyclicCodes( 23, GF(2) ); [ a cyclic [23,23,1]0 enumerated code over GF(2), a cyclic [23,22,1..2]1 enumerated code over GF(2), a cyclic [23,11,1..8]4..7 enumerated code over GF(2), a cyclic [23,0,23]23 enumerated code over GF(2), a cyclic [23,11,1..8]4..7 enumerated code over GF(2), a cyclic [23,12,1..7]3 enumerated code over GF(2), a cyclic [23,1,23]11 enumerated code over GF(2), a cyclic [23,12,1..7]3 enumerated code over GF(2) ] gap> BinaryGolayCode() in codelist; true gap> RepetitionCode( 23, GF(2) ) in codelist; true gap> CordaroWagnerCode( 23 ) in codelist; false # This code is not cyclic
Evaluation Codes
code, evaluation
Input: F is a finite field, L is a list of rational functions in R=F[x_1,...,x_r], P is a list of n points in F^r at which all of the functions in L are defined.
Output: The 'evaluation code' C, which is the image of the evalation map Eval_P:span(L)\rightarrow F^n, given by f\longmapsto (f(p_1),...,f(p_n)), where P=\{p_1,...,p_n\} and f \in L. The generator matrix of C is G=(f_i(p_j))_{f_i\in L,p_j\in P}.

This command returns a "record" object C with several extra components (type NamesOfComponents(C) to see them all): C!.points (namely P), C!.basis (namely L), and C!.ring (namely R).
gap> F:=GF(11); GF(11) gap> R := PolynomialRing(F,["x","y"]); PolynomialRing(..., [ x, y ]) gap> indets := IndeterminatesOfPolynomialRing(R);; gap> x:=indets[1];; y:=indets[2];; gap> L:=[x^2*y,x*y,x^5,x^4,x^3,x^2,x,x^0];; gap> Pts:=[ [ Z(11)^9, Z(11) ], [ Z(11)^8, Z(11) ], [ Z(11)^7, 0*Z(11) ], [ Z(11)^6, 0*Z(11) ], [ Z(11)^5, 0*Z(11) ], [ Z(11)^4, 0*Z(11) ], [ Z(11)^3, Z(11) ], [ Z(11)^2, 0*Z(11) ], [ Z(11), 0*Z(11) ], [ Z(11)^0, 0*Z(11) ], [ 0*Z(11), Z(11) ] ];; gap> C:=EvaluationCode(Pts,L,R); a linear [11,8,1..3]2..3 evaluation code over GF(11) gap> MinimumDistance(C); 3

Input: R=F[x], where F is a finite field, k is a positive integer, P is a list of n points in F.
Output: The C which is the image of the evaluation map Eval_P:F[x]_k\rightarrow F^n, given by f\longmapsto (f(p_1),...,f(p_n)), where P=\{p_1,...,p_n\}\subset F and f ranges over the space F[x]_k of all polynomials of degree less than k.

This command returns a "record" object C with several extra components (type NamesOfComponents(C) to see them all): C!.points (namely P), C!.degree (namely k), and C!.ring (namely R).

This code can be decoded using Decodeword, which applies the special decoder method (the interpolation method), or using GeneralizedReedSolomonDecoderGao which applies an algorithm of S. Gao (see ). This code has a special decoder record which implements the interpolation algorithm described in section 5.2 of Justesen and Hoholdt . See and for more details.

The weighted version has implemented with the option GeneralizedReedSolomonCode(P,k,R,wts), where wts = [v_1, ..., v_n] is a sequence of n non-zero elements from the base field F of R. See also the generalized Reed--Solomon code GRS_k(P, V) described in , p.303.

Work in progress
: The list-decoding algorithm of Sudan-Guraswami (described in section 12.1 of ) should be implemented. See .

gap> R:=PolynomialRing(GF(11),["t"]); GF(11)[t] gap> P:=List([1,3,4,5,7],i->Z(11)^i); [ Z(11), Z(11)^3, Z(11)^4, Z(11)^5, Z(11)^7 ] gap> C:=GeneralizedReedSolomonCode(P,3,R); a linear [5,3,1..3]2 generalized Reed-Solomon code over GF(11) gap> MinimumDistance(C); 3 gap> V:=[Z(11)^0,Z(11)^0,Z(11)^0,Z(11)^0,Z(11)]; [ Z(11)^0, Z(11)^0, Z(11)^0, Z(11)^0, Z(11) ] gap> C:=GeneralizedReedSolomonCode(P,3,R,V); a linear [5,3,1..3]2 weighted generalized Reed-Solomon code over GF(11) gap> MinimumDistance(C); 3

See for a more general construction.

GeneralizedReedMullerCode
returns a 'Reed-Muller code' C with length |Pts| and order r. One considers (a) a basis of monomials for the vector space over F=GF(q) of all polynomials in F[x_1,...,x_d] of degree at most r, and (b) a set Pts of points in F^d. The generator matrix of the associated Reed-Muller code C is G=(f(p))_{f\in B,p \in Pts}. This code C is constructed using the command GeneralizedReedMullerCode(Pts,r,F). When Pts is the set of all q^d points in F^d then the command GeneralizedReedMuller(d,r,F) yields the code. When Pts is the set of all (q-1)^d points with no coordinate equal to 0 then this is can be constructed using the ToricCode command (as a special case).

This command returns a "record" object C with several extra components (type NamesOfComponents(C) to see them all): C!.points (namely Pts) and C!.degree (namely r).
gap> Pts:=ToricPoints(2,GF(5)); [ [ Z(5)^0, Z(5)^0 ], [ Z(5)^0, Z(5) ], [ Z(5)^0, Z(5)^2 ], [ Z(5)^0, Z(5)^3 ], [ Z(5), Z(5)^0 ], [ Z(5), Z(5) ], [ Z(5), Z(5)^2 ], [ Z(5), Z(5)^3 ], [ Z(5)^2, Z(5)^0 ], [ Z(5)^2, Z(5) ], [ Z(5)^2, Z(5)^2 ], [ Z(5)^2, Z(5)^3 ], [ Z(5)^3, Z(5)^0 ], [ Z(5)^3, Z(5) ], [ Z(5)^3, Z(5)^2 ], [ Z(5)^3, Z(5)^3 ] ] gap> C:=GeneralizedReedMullerCode(Pts,2,GF(5)); a linear [16,6,1..11]6..10 generalized Reed-Muller code over GF(5)

See for a more general construction.

AffinePointsOnCurve(f,R,E)
returns the points (x,y) \in E^2 satisying f(x,y)=0, where f is an element of R=F[x,y].
gap> F:=GF(11);; gap> R := PolynomialRing(F,["x","y"]); PolynomialRing(..., [ x, y ]) gap> indets := IndeterminatesOfPolynomialRing(R);; gap> x:=indets[1];; y:=indets[2];; gap> P:=AffinePointsOnCurve(y^2-x^11+x,R,F); [ [ Z(11)^9, 0*Z(11) ], [ Z(11)^8, 0*Z(11) ], [ Z(11)^7, 0*Z(11) ], [ Z(11)^6, 0*Z(11) ], [ Z(11)^5, 0*Z(11) ], [ Z(11)^4, 0*Z(11) ], [ Z(11)^3, 0*Z(11) ], [ Z(11)^2, 0*Z(11) ], [ Z(11), 0*Z(11) ], [ Z(11)^0, 0*Z(11) ], [ 0*Z(11), 0*Z(11) ] ]
Input: f is a polynomial in R=F[x,y], where F is a finite field, m is a positive integer (the multiplicity of the `point at infinity' \infty on the curve f(x,y)=0), P is a list of n points on the curve over F.
Output: The C which is the image of the evaluation map Eval_P:L(m \cdot \infty)\rightarrow F^n, given by f\longmapsto (f(p_1),...,f(p_n)), where p_i \in P. Here L(m \cdot \infty) denotes the Riemann-Roch space of the divisor m \cdot \infty on the curve. This has a basis consisting of monomials x^iy^j, where (i,j) range over a polygon depending on m and f(x,y). For more details on the Riemann-Roch space of the divisor m \cdot \infty see Proposition III.10.5 in Stichtenoth .

This command returns a "record" object C with several extra components (type NamesOfComponents(C) to see them all): C!.points (namely P), C!.multiplicity (namely m), C!.curve (namely f) and C!.ring (namely R).
gap> F:=GF(11); GF(11) gap> R := PolynomialRing(F,["x","y"]); PolynomialRing(..., [ x, y ]) gap> indets := IndeterminatesOfPolynomialRing(R); [ x, y ] gap> x:=indets[1]; y:=indets[2]; x y gap> P:=AffinePointsOnCurve(y^2-x^11+x,R,F);; gap> C:=OnePointAGCode(y^2-x^11+x,P,15,R); a linear [11,8,1..0]2..3 one-point AG code over GF(11) gap> MinimumDistance(C); 4 gap> Pts:=List([1,2,4,6,7,8,9,10,11],i->P[i]);; gap> C:=OnePointAGCode(y^2-x^11+x,PT,10,R); a linear [9,6,1..4]2..3 one-point AG code over GF(11) gap> MinimumDistance(C); 4

See for a more general construction.

ToricPoints(n,F)
returns the points in (F^{\times})^n.
gap> ToricPoints(2,GF(5)); [ [ Z(5)^0, Z(5)^0 ], [ Z(5)^0, Z(5) ], [ Z(5)^0, Z(5)^2 ], [ Z(5)^0, Z(5)^3 ], [ Z(5), Z(5)^0 ], [ Z(5), Z(5) ], [ Z(5), Z(5)^2 ], [ Z(5), Z(5)^3 ], [ Z(5)^2, Z(5)^0 ], [ Z(5)^2, Z(5) ], [ Z(5)^2, Z(5)^2 ], [ Z(5)^2, Z(5)^3 ], [ Z(5)^3, Z(5)^0 ], [ Z(5)^3, Z(5) ], [ Z(5)^3, Z(5)^2 ], [ Z(5)^3, Z(5)^3 ] ]
code, toric
This function returns the toric codes as in D. Joyner (see also J. P. Hansen ). This is a truncated (generalized) Reed-Muller code. Here L is a list of integral vectors and F is the finite field. The size of F must be different from 2.

This command returns a record object C with an extra component (type NamesOfComponents(C) to see them all): C!.exponents (namely L).
gap> C:=ToricCode([[1,0],[3,4]],GF(3)); a linear [4,1,4]2 toric code over GF(3) gap> Display(GeneratorMat(C)); 1 1 2 2 gap> Elements(C); [ [ 0 0 0 0 ], [ 1 1 2 2 ], [ 2 2 1 1 ] ]

See for a more general construction.

Manipulating Codes

In this chapter we describe several functions `GUAVA` uses to manipulate codes. Some of the best codes are obtained by starting with for example a BCH code, and manipulating it.

In some cases, it is faster to perform calculations with a manipulated code than to use the original code. For example, if the dimension of the code is larger than half the word length, it is generally faster to compute the weight distribution by first calculating the weight distribution of the dual code than by directly calculating the weight distribution of the original code. The size of the dual code is smaller in these cases.

Because `GUAVA` keeps all information in a code record, in some cases the information can be preserved after manipulations. Therefore, computations do not always have to start from scratch.

In Section , we describe functions that take a code with certain parameters, modify it in some way and return a different code (see , , , , , , , , , , , , , , , and ).

In Section , we describe functions that generate a new code out of two codes (see , , , and ).

Functions that Generate a New Code from a Given Code
Parity check
ExtendedCode
extends the code C i times and returns the result. i is equal to 1 by default. Extending is done by adding a parity check bit after the last coordinate. The coordinates of all codewords now add up to zero. In the binary case, each codeword has even weight.

The word length increases by i. The size of the code remains the same. In the binary case, the minimum distance increases by one if it was odd. In other cases, that is not always true.

A cyclic code in general is no longer cyclic after extending.
gap> C1 := HammingCode( 3, GF(2) ); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> C2 := ExtendedCode( C1 ); a linear [8,4,4]2 extended code gap> IsEquivalent( C2, ReedMullerCode( 1, 3 ) ); true gap> List( AsSSortedList( C2 ), WeightCodeword ); [ 0, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 8 ] gap> C3 := EvenWeightSubcode( C1 ); a linear [7,3,4]2..3 even weight subcode

To undo extending, call PuncturedCode (see ). The function EvenWeightSubcode (see ) also returns a related code with only even weights, but without changing its word length.

PuncturedCode
punctures C in the last column, and returns the result. Puncturing is done simply by cutting off the last column from each codeword. This means the word length decreases by one. The minimum distance in general also decrease by one.

This command can also be called with the syntax PuncturedCode( C, L ). In this case, PuncturedCode punctures C in the columns specified by L, a list of integers. All columns specified by L are omitted from each codeword. If l is the length of L (so the number of removed columns), the word length decreases by l. The minimum distance can also decrease by l or less.

Puncturing a cyclic code in general results in a non-cyclic code. If the code is punctured in all the columns where a word of minimal weight is unequal to zero, the dimension of the resulting code decreases.
gap> C1 := BCHCode( 15, 5, GF(2) ); a cyclic [15,7,5]3..5 BCH code, delta=5, b=1 over GF(2) gap> C2 := PuncturedCode( C1 ); a linear [14,7,4]3..5 punctured code gap> ExtendedCode( C2 ) = C1; false gap> PuncturedCode( C1, [1,2,3,4,5,6,7] ); a linear [8,7,1]1 punctured code gap> PuncturedCode( WholeSpaceCode( 4, GF(5) ) ); a linear [3,3,1]0 punctured code # The dimension decreased from 4 to 3
ExtendedCode
extends the code again (see ), although in general this does not result in the old code.

EvenWeightSubcode
returns the even weight subcode of C, consisting of all codewords of C with even weight. If C is a linear code and contains words of odd weight, the resulting code has a dimension of one less. The minimum distance always increases with one if it was odd. If C is a binary cyclic code, and g(x) is its generator polynomial, the even weight subcode either has generator polynomial g(x) (if g(x) is divisible by x-1) or g(x)\cdot (x-1) (if no factor x-1 was present in g(x)). So the even weight subcode is again cyclic.

Of course, if all codewords of C are already of even weight, the returned code is equal to C.
gap> C1 := EvenWeightSubcode( BCHCode( 8, 4, GF(3) ) ); an (8,33,4..8)3..8 even weight subcode gap> List( AsSSortedList( C1 ), WeightCodeword ); [ 0, 4, 4, 4, 4, 4, 4, 6, 4, 4, 4, 4, 6, 4, 4, 6, 4, 4, 8, 6, 4, 6, 8, 4, 4, 4, 6, 4, 6, 8, 4, 6, 8 ] gap> EvenWeightSubcode( ReedMullerCode( 1, 3 ) ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2)
ExtendedCode
also returns a related code of only even weights, but without reducing its dimension (see ).

PermutedCode
returns C after column permutations. L (in &GAP; disjoint cycle notation) is the permutation to be executed on the columns of C. If C is cyclic, the result in general is no longer cyclic. If a permutation results in the same code as C, this permutation belongs to the automorphism group of C (see ). In any case, the returned code is equivalent to C (see ).
gap> C1 := PuncturedCode( ReedMullerCode( 1, 4 ) ); a linear [15,5,7]5 punctured code gap> C2 := BCHCode( 15, 7, GF(2) ); a cyclic [15,5,7]5 BCH code, delta=7, b=1 over GF(2) gap> C2 = C1; false gap> p := CodeIsomorphism( C1, C2 ); ( 2, 4,14, 9,13, 7,11,10, 6, 8,12, 5) gap> C3 := PermutedCode( C1, p ); a linear [15,5,7]5 permuted code gap> C2 = C3; true
ExpurgatedCode
expurgates the code C> by throwing away codewords in list L. C must be a linear code. L must be a list of codeword input. The generator matrix of the new code no longer is a basis for the codewords specified by L. Since the returned code is still linear, it is very likely that, besides the words of L, more codewords of C are no longer in the new code.
gap> C1 := HammingCode( 4 );; WeightDistribution( C1 ); [ 1, 0, 0, 35, 105, 168, 280, 435, 435, 280, 168, 105, 35, 0, 0, 1 ] gap> L := Filtered( AsSSortedList(C1), i -> WeightCodeword(i) = 3 );; gap> C2 := ExpurgatedCode( C1, L ); a linear [15,4,3..4]5..11 code, expurgated with 7 word(s) gap> WeightDistribution( C2 ); [ 1, 0, 0, 0, 14, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0 ]

This function does not work on non-linear codes. For removing words from a non-linear code, use RemovedElementsCode (see ). For expurgating a code of all words of odd weight, use `EvenWeightSubcode' (see ).

AugmentedCode
returns C after augmenting. C must be a linear code, L must be a list of codeword inputs. The generator matrix of the new code is a basis for the codewords specified by L as well as the words that were already in code C. Note that the new code in general will consist of more words than only the codewords of C and the words L. The returned code is also a linear code.

This command can also be called with the syntax AugmentedCode(C).

When called without a list of codewords, AugmentedCode returns C after adding the all-ones vector to the generator matrix. C must be a linear code. If the all-ones vector was already in the code, nothing happens and a copy of the argument is returned. If C is a binary code which does not contain the all-ones vector, the complement of all codewords is added.
gap> C31 := ReedMullerCode( 1, 3 ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2) gap> C32 := AugmentedCode(C31,["00000011","00000101","00010001"]); a linear [8,7,1..2]1 code, augmented with 3 word(s) gap> C32 = ReedMullerCode( 2, 3 ); true gap> C1 := CordaroWagnerCode(6); a linear [6,2,4]2..3 Cordaro-Wagner code over GF(2) gap> Codeword( [0,0,1,1,1,1] ) in C1; true gap> C2 := AugmentedCode( C1 ); a linear [6,3,1..2]2..3 code, augmented with 1 word(s) gap> Codeword( [1,1,0,0,0,0] ) in C2; true

The function AddedElementsCode adds elements to the codewords instead of adding them to the basis (see ).

RemovedElementsCode
returns code C after removing a list of codewords L from its elements. L must be a list of codeword input. The result is an unrestricted code.
gap> C1 := HammingCode( 4 );; WeightDistribution( C1 ); [ 1, 0, 0, 35, 105, 168, 280, 435, 435, 280, 168, 105, 35, 0, 0, 1 ] gap> L := Filtered( AsSSortedList(C1), i -> WeightCodeword(i) = 3 );; gap> C2 := RemovedElementsCode( C1, L ); a (15,2013,3..15)2..15 code with 35 word(s) removed gap> WeightDistribution( C2 ); [ 1, 0, 0, 0, 105, 168, 280, 435, 435, 280, 168, 105, 35, 0, 0, 1 ] gap> MinimumDistance( C2 ); 3 # C2 is not linear, so the minimum weight does not have to # be equal to the minimum distance

Adding elements to a code is done by the function AddedElementsCode (see ). To remove codewords from the base of a linear code, use ExpurgatedCode (see ).

AddedElementsCode
returns code C after adding a list of codewords L to its elements. L must be a list of codeword input. The result is an unrestricted code.
gap> C1 := NullCode( 6, GF(2) ); a cyclic [6,0,6]6 nullcode over GF(2) gap> C2 := AddedElementsCode( C1, [ "111111" ] ); a (6,2,1..6)3 code with 1 word(s) added gap> IsCyclicCode( C2 ); true gap> C3 := AddedElementsCode( C2, [ "101010", "010101" ] ); a (6,4,1..6)2 code with 2 word(s) added gap> IsCyclicCode( C3 ); true

To remove elements from a code, use RemovedElementsCode (see ). To add elements to the base of a linear code, use AugmentedCode (see ).

ShortenedCode( C )
returns the code C shortened by taking a cross section. If C is a linear code, this is done by removing all codewords that start with a non-zero entry, after which the first column is cut off. If C was a [n,k,d] code, the shortened code generally is a [n-1,k-1,d] code. It is possible that the dimension remains the same; it is also possible that the minimum distance increases.

If C is a non-linear code, ShortenedCode first checks which finite field element occurs most often in the first column of the codewords. The codewords not starting with this element are removed from the code, after which the first column is cut off. The resulting shortened code has at least the same minimum distance as C.

This command can also be called using the syntax ShortenedCode(C,L). When called in this format, ShortenedCode repeats the shortening process on each of the columns specified by L. L therefore is a list of integers. The column numbers in L are the numbers as they are before the shortening process. If L has l entries, the returned code has a word length of l positions shorter than C.
gap> C1 := HammingCode( 4 ); a linear [15,11,3]1 Hamming (4,2) code over GF(2) gap> C2 := ShortenedCode( C1 ); a linear [14,10,3]2 shortened code gap> C3 := ElementsCode( ["1000", "1101", "0011" ], GF(2) ); a (4,3,1..4)2 user defined unrestricted code over GF(2) gap> MinimumDistance( C3 ); 2 gap> C4 := ShortenedCode( C3 ); a (3,2,2..3)1..2 shortened code gap> AsSSortedList( C4 ); [ [ 0 0 0 ], [ 1 0 1 ] ] gap> C5 := HammingCode( 5, GF(2) ); a linear [31,26,3]1 Hamming (5,2) code over GF(2) gap> C6 := ShortenedCode( C5, [ 1, 2, 3 ] ); a linear [28,23,3]2 shortened code gap> OptimalityLinearCode( C6 ); 0

The function LengthenedCode lengthens the code again (only for linear codes), see . In general, this is not exactly the inverse function.

LengthenedCode( C )
returns the code C lengthened. C must be a linear code. First, the all-ones vector is added to the generator matrix (see ). If the all-ones vector was already a codeword, nothing happens to the code. Then, the code is extended i times (see ). i is equal to 1 by default. If C was an [n,k] code, the new code generally is a [n+i,k+1] code.
gap> C1 := CordaroWagnerCode( 5 ); a linear [5,2,3]2 Cordaro-Wagner code over GF(2) gap> C2 := LengthenedCode( C1 ); a linear [6,3,2]2..3 code, lengthened with 1 column(s)
ShortenedCode
' shortens the code, see . In general, this is not exactly the inverse function.

The function ResidueCode takes a codeword c of C (if c is omitted, a codeword of minimal weight is used). It removes this word and all its linear combinations from the code and then punctures the code in the coordinates where c is unequal to zero. The resulting code is an [n-w, k-1, d-\lfloor w*(q-1)/q \rfloor ] code. C must be a linear code and c must be non-zero. If c is not in then no change is made to C.
gap> C1 := BCHCode( 15, 7 ); a cyclic [15,5,7]5 BCH code, delta=7, b=1 over GF(2) gap> C2 := ResidueCode( C1 ); a linear [8,4,4]2 residue code gap> c := Codeword( [ 0,0,0,1,0,0,1,1,0,1,0,1,1,1,1 ], C1);; gap> C3 := ResidueCode( C1, c ); a linear [7,4,3]1 residue code
The function ConstructionBCode takes a binary linear code C and calculates the minimum distance of the dual of C (see ). It then removes the columns of the parity check matrix of C where a codeword of the dual code of minimal weight has coordinates unequal to zero. The resulting matrix is a parity check matrix for an [n-dd, k-dd+1, \geq d] code, where dd is the minimum distance of the dual of C.
gap> C1 := ReedMullerCode( 2, 5 ); a linear [32,16,8]6 Reed-Muller (2,5) code over GF(2) gap> C2 := ConstructionBCode( C1 ); a linear [24,9,8]5..10 Construction B (8 coordinates) gap> BoundsMinimumDistance( 24, 9, GF(2) ); rec( n := 24, k := 9, q := 2, references := rec( ), construction := [ [ Operation "UUVCode" ], [ [ [ Operation "UUVCode" ], [ [ [ Operation "DualCode" ], [ [ [ Operation "RepetitionCode" ], [ 6, 2 ] ] ] ], [ [ Operation "CordaroWagnerCode" ], [ 6 ] ] ] ], [ [ Operation "CordaroWagnerCode" ], [ 12 ] ] ] ], lowerBound := 8, lowerBoundExplanation := [ "Lb(24,9)=8, u u+v construction of C1 and C2:", "Lb(12,7)=4, u u+v construction of C1 and C2:", "Lb(6,5)=2, dual of the repetition code", "Lb(6,2)=4, Cordaro-Wagner code", "Lb(12,2)=8, Cordaro-Wagner code" ], upperBound := 8, upperBoundExplanation := [ "Ub(24,9)=8, otherwise construction B would contradict:", "Ub(18,4)=8, Griesmer bound" ] ) # so C2 is optimal
DualCode
returns the dual code of C. The dual code consists of all codewords that are orthogonal to the codewords of C. If C is a linear code with generator matrix G, the dual code has parity check matrix G (or if C has parity check matrix H, the dual code has generator matrix H). So if C is a linear [n, k] code, the dual code of C is a linear [n, n-k] code. If C is a cyclic code with generator polynomial g(x), the dual code has the reciprocal polynomial of g(x) as check polynomial.

The dual code is always a linear code, even if C is non-linear.

If a code C is equal to its dual code, it is called self-dual.
gap> R := ReedMullerCode( 1, 3 ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2) gap> RD := DualCode( R ); a linear [8,4,4]2 Reed-Muller (1,3) code over GF(2) gap> R = RD; true gap> N := WholeSpaceCode( 7, GF(4) ); a cyclic [7,7,1]0 whole space code over GF(4) gap> DualCode( N ) = NullCode( 7, GF(4) ); true
self-dual
ConversionFieldCode
returns code C after converting its field. If the field of C is GF(q^m), the returned code has field GF(q). Each symbol of every codeword is replaced by a concatenation of m symbols from GF(q). If C is an (n, M, d_1) code, the returned code is a (n\cdot m, M, d_2) code, where d_2 > d_1.

See also .
gap> R := RepetitionCode( 4, GF(4) ); a cyclic [4,1,4]3 repetition code over GF(4) gap> R2 := ConversionFieldCode( R ); a linear [8,2,4]3..4 code, converted to basefield GF(2) gap> Size( R ) = Size( R2 ); true gap> GeneratorMat( R ); [ [ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ] ] gap> GeneratorMat( R2 ); [ [ Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2) ], [ 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0 ] ]
CosetCode
returns the coset of a code C with respect to word w. w must be of the codeword type. Then, w is added to each codeword of C, yielding the elements of the new code. If C is linear and w is an element of C, the new code is equal to C, otherwise the new code is an unrestricted code.

Generating a coset is also possible by simply adding the word w to C. See .
gap> H := HammingCode(3, GF(2)); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> c := Codeword("1011011");; c in H; false gap> C := CosetCode(H, c); a (7,16,3)1 coset code gap> List(AsSSortedList(C), el-> Syndrome(H, el)); [ [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ], [ 1 1 1 ] ] # All elements of the coset have the same syndrome in H
ConstantWeightSubcode
returns the subcode of C that only has codewords of weight w. The resulting code is a non-linear code, because it does not contain the all-zero vector.

This command also can be called with the syntax ConstantWeightSubcode(C) In this format, ConstantWeightSubcode returns the subcode of C consisting of all minimum weight codewords of C.

ConstantWeightSubcode
first checks if Leon's binary wtdist exists on your computer (in the default directory). If it does, then this program is called. Otherwise, the constant weight subcode is computed using a GAP program which checks each codeword in C to see if it is of the desired weight.

gap> N := NordstromRobinsonCode();; WeightDistribution(N); [ 1, 0, 0, 0, 0, 0, 112, 0, 30, 0, 112, 0, 0, 0, 0, 0, 1 ] gap> C := ConstantWeightSubcode(N, 8); a (16,30,6..16)5..8 code with codewords of weight 8 gap> WeightDistribution(C); [ 0, 0, 0, 0, 0, 0, 0, 0, 30, 0, 0, 0, 0, 0, 0, 0, 0 ] gap> eg := ExtendedTernaryGolayCode();; WeightDistribution(eg); [ 1, 0, 0, 0, 0, 0, 264, 0, 0, 440, 0, 0, 24 ] gap> C := ConstantWeightSubcode(eg); a (12,264,6..12)3..6 code with codewords of weight 6 gap> WeightDistribution(C); [ 0, 0, 0, 0, 0, 0, 264, 0, 0, 0, 0, 0, 0 ]
StandardFormCode
returns C after putting it in standard form. If C is a non-linear code, this means the elements are organized using lexicographical order. This means they form a legal &GAP; `Set'.

If C is a linear code, the generator matrix and parity check matrix are put in standard form. The generator matrix then has an identity matrix in its left part, the parity check matrix has an identity matrix in its right part. Although `GUAVA` always puts both matrices in a standard form using BaseMat, this never alters the code. StandardFormCode even applies column permutations if unavoidable, and thereby changes the code. The column permutations are recorded in the construction history of the new code (see ). C and the new code are of course equivalent.

If C is a cyclic code, its generator matrix cannot be put in the usual upper triangular form, because then it would be inconsistent with the generator polynomial. The reason is that generating the elements from the generator matrix would result in a different order than generating the elements from the generator polynomial. This is an unwanted effect, and therefore StandardFormCode just returns a copy of C for cyclic codes.
gap> G := GeneratorMatCode( Z(2) * [ [0,1,1,0], [0,1,0,1], [0,0,1,1] ], > "random form code", GF(2) ); a linear [4,2,1..2]1..2 random form code over GF(2) gap> Codeword( GeneratorMat( G ) ); [ [ 0 1 0 1 ], [ 0 0 1 1 ] ] gap> Codeword( GeneratorMat( StandardFormCode( G ) ) ); [ [ 1 0 0 1 ], [ 0 1 0 1 ] ]
PiecewiseConstantCode
returns a code with length n = \sum n_i, where part=[ n_1, \dots, n_k ]. wts is a list of constraints w=(w_1,...,w_k), each of length k, where 0 \leq w_i \leq n_i. The default field is GF(2).

A constraint is a list of integers, and a word c = ( c_1, \dots, c_k ) (according to part, i.e., each c_i is a subword of length n_i) is in the resulting code if and only if, for some constraint w \in wts, \|c_i\| = w_i$ for all $1 \leq i \leq k, where \| ...\| denotes the Hamming weight.

An example might make things clearer:
gap> PiecewiseConstantCode( [ 2, 3 ], > [ [ 0, 0 ], [ 0, 3 ], [ 1, 0 ], [ 2, 2 ] ], > GF(2) ); a (5,7,1..5)1..5 piecewise constant code over GF(2) gap> AsSSortedList(last); [ [ 0 0 0 0 0 ], [ 0 0 1 1 1 ], [ 0 1 0 0 0 ], [ 1 0 0 0 0 ], [ 1 1 0 1 1 ], [ 1 1 1 0 1 ], [ 1 1 1 1 0 ] ]

The first constraint is satisfied by codeword 1, the second by codeword 2, the third by codewords 3 and 4, and the fourth by codewords 5, 6 and 7.

Functions that Generate a New Code from Two Given Codes
DirectSumCode
returns the direct sum of codes C1 and C2. The direct sum code consists of every codeword of C1 concatenated by every codeword of C2. Therefore, if Ci was a (n_i,M_i,d_i) code, the result is a (n_1+n_2,M_1*M_2,min(d_1,d_2)) code.

If both C1 and C2 are linear codes, the result is also a linear code. If one of them is non-linear, the direct sum is non-linear too. In general, a direct sum code is not cyclic.

Performing a direct sum can also be done by adding two codes (see Section ). Another often used method is the `u, u+v'-construction, described in .
gap> C1 := ElementsCode( [ [1,0], [4,5] ], GF(7) );; gap> C2 := ElementsCode( [ [0,0,0], [3,3,3] ], GF(7) );; gap> D := DirectSumCode(C1, C2);; gap> AsSSortedList(D); [ [ 1 0 0 0 0 ], [ 1 0 3 3 3 ], [ 4 5 0 0 0 ], [ 4 5 3 3 3 ] ] gap> D = C1 + C2; # addition = direct sum true
UUVCode
returns the so-called (u\|u+v) construction applied to C1 and C2. The resulting code consists of every codeword u of C1 concatenated by the sum of u and every codeword v of C2. If C1 and C2 have different word lengths, sufficient zeros are added to the shorter code to make this sum possible. If Ci is a (n_i,M_i,d_i) code, the result is an (n_1+max(n_1,n_2),M_1\cdot M_2,min(2\cdot d_1,d_2)) code.

If both C1 and C2 are linear codes, the result is also a linear code. If one of them is non-linear, the UUV sum is non-linear too. In general, a UUV sum code is not cyclic.

The function DirectSumCode returns another sum of codes (see ).
gap> C1 := EvenWeightSubcode(WholeSpaceCode(4, GF(2))); a cyclic [4,3,2]1 even weight subcode gap> C2 := RepetitionCode(4, GF(2)); a cyclic [4,1,4]2 repetition code over GF(2) gap> R := UUVCode(C1, C2); a linear [8,4,4]2 U U+V construction code gap> R = ReedMullerCode(1,3); true
DirectProductCode
returns the direct product of codes C1 and C2. Both must be linear codes. Suppose Ci has generator matrix G_i. The direct product of C1 and C2 then has the Kronecker product of G_1 and G_2 as the generator matrix (see the &GAP; command KroneckerProduct).

If Ci is a [n_i, k_i, d_i] code, the direct product then is an [n_1\cdot n_2,k_1\cdot k_2,d_1\cdot d_2] code.
gap> L1 := LexiCode(10, 4, GF(2)); a linear [10,5,4]2..4 lexicode over GF(2) gap> L2 := LexiCode(8, 3, GF(2)); a linear [8,4,3]2..3 lexicode over GF(2) gap> D := DirectProductCode(L1, L2); a linear [80,20,12]20..45 direct product code
IntersectionCode
returns the intersection of codes C1 and C2. This code consists of all codewords that are both in C1 and C2. If both codes are linear, the result is also linear. If both are cyclic, the result is also cyclic.

gap> C := CyclicCodes(7, GF(2)); [ a cyclic [7,7,1]0 enumerated code over GF(2), a cyclic [7,6,1..2]1 enumerated code over GF(2), a cyclic [7,3,1..4]2..3 enumerated code over GF(2), a cyclic [7,0,7]7 enumerated code over GF(2), a cyclic [7,3,1..4]2..3 enumerated code over GF(2), a cyclic [7,4,1..3]1 enumerated code over GF(2), a cyclic [7,1,7]3 enumerated code over GF(2), a cyclic [7,4,1..3]1 enumerated code over GF(2) ] gap> IntersectionCode(C[6], C[8]) = C[7]; true
hull
The hull of a linear code is the intersection of the code with its dual code. In other words, the hull of C is IntersectionCode(C, DualCode(C)).

UnionCode
returns the union of codes C1 and C2. This code consists of the union of all codewords of C1 and C2 and all linear combinations. Therefore this function works only for linear codes. The function AddedElementsCode can be used for non-linear codes, or if the resulting code should not include linear combinations. See . If both arguments are cyclic, the result is also cyclic.
gap> G := GeneratorMatCode([[1,0,1],[0,1,1]]*Z(2)^0, GF(2)); a linear [3,2,1..2]1 code defined by generator matrix over GF(2) gap> H := GeneratorMatCode([[1,1,1]]*Z(2)^0, GF(2)); a linear [3,1,3]1 code defined by generator matrix over GF(2) gap> U := UnionCode(G, H); a linear [3,3,1]0 union code gap> c := Codeword("010");; c in G; false gap> c in H; false gap> c in U; true
The extended direct sum construction is described in section V of Graham and Sloane . The resulting code consists of m copies of L, extended by repeating the codewords of B m times.

Suppose L is an [n_L, k_L]r_L code, and B is an [n_L, k_B]r_B code (non-linear codes are also permitted). The length of B must be equal to the length of L. The length of the new code is n = m n_L, the dimension (in the case of linear codes) is k \leq m k_L + k_B, and the covering radius is r \leq \lfloor m \Psi( L, B ) \rfloor, with

\Psi( L, B ) = \max_{u \in F_2^{n_L}} \frac{1}{2^{k_B}} \sum_{v \in B} {\rm d}( L, v + u ).
However, this computation will not be executed, because it may be too time consuming for large codes.

If L \subseteq B, and L and B are linear codes, the last copy of L is omitted. In this case the dimension is k = m k_L + (k_B - k_L).
gap> c := HammingCode( 3, GF(2) ); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> d := WholeSpaceCode( 7, GF(2) ); a cyclic [7,7,1]0 whole space code over GF(2) gap> e := ExtendedDirectSumCode( c, d, 3 ); a linear [21,15,1..3]2 3-fold extended direct sum code
AmalgamatedDirectSumCode
returns the amalgamated direct sum of the codes c1 and c2. The amalgamated direct sum code consists of all codewords of the form (u \, \| \,0 \, \| \, v) if (u \, \| \, 0) \in c_1 and (0 \, \| \, v) \in c_2 and all codewords of the form (u \, \| \, 1 \, \| \, v) if (u \, \| \, 1) \in c_1 and (1 \, \| \, v) \in c_2. The result is a code with length n = n_1 + n_2 - 1 and size M \leq M_1 \cdot M_2 / 2 .

If both codes are linear, they will first be standardized, with information symbols in the last and first coordinates of the first and second code, respectively.

If c1 is a normal code (see ) with the last coordinate acceptable (see ), and c2 is a normal code with the first coordinate acceptable, then the covering radius of the new code is r \leq r_1 + r_2 . However, checking whether a code is normal or not is a lot of work, and almost all codes seem to be normal. Therefore, an option check can be supplied. If check is true, then the codes will be checked for normality. If check is false or omitted, then the codes will not be checked. In this case it is assumed that they are normal. Acceptability of the last and first coordinate of the first and second code, respectively, is in the last case also assumed to be done by the user.
gap> c := HammingCode( 3, GF(2) ); a linear [7,4,3]1 Hamming (3,2) code over GF(2) gap> d := ReedMullerCode( 1, 4 ); a linear [16,5,8]6 Reed-Muller (1,4) code over GF(2) gap> e := DirectSumCode( c, d ); a linear [23,9,3]7 direct sum code gap> f := AmalgamatedDirectSumCode( c, d );; gap> MinimumDistance( f );; gap> CoveringRadius( f );; gap> f; a linear [22,8,3]7 amalgamated direct sum code
BlockwiseDirectSumCode
returns a subcode of the direct sum of C1 and C2. The fields of C1 and C2 must be same. The lists L1 and L2 are two equally long with elements from the ambient vector spaces of C1 and C2, respectively, or L1 and L2 are two equally long lists containing codes. The union of the codes in L1 and L2 must be C1 and C2, respectively.

In the first case, the blockwise direct sum code is defined as

bds = \bigcup_{1 \leq i \leq \ell} ( C_1 + (L_1)_i ) \oplus ( C_2 + (L_2)_i ),
where \ell is the length of L1 and L2, and \oplus is the direct sum.

In the second case, it is defined as

bds = \bigcup_{1 \leq i \leq \ell} ( (L_1)_i \oplus (L_2)_i ).
The length of the new code is n = n_1 + n_2.
gap> C1 := HammingCode( 3, GF(2) );; gap> C2 := EvenWeightSubcode( WholeSpaceCode( 6, GF(2) ) );; gap> BlockwiseDirectSumCode( C1, [[ 0,0,0,0,0,0,0 ],[ 1,0,1,0,1,0,0 ]], > C2, [[ 0,0,0,0,0,0 ],[ 1,0,1,0,1,0 ]] ); a (13,1024,1..13)1..2 blockwise direct sum code
Bounds on codes, special matrices and miscellaneous functions

In this chapter we describe functions that determine bounds on the size and minimum distance of codes (Section ), functions that determine bounds on the size and covering radius of codes (Section ), functions that work with special matrices `GUAVA` needs for several codes (see Section ), and constructing codes or performing calculations with codes (see Section ).

Distance bounds on codes

This section describes the functions that calculate estimates for upper bounds on the size and minimum distance of codes. Several algorithms are known to compute a largest number of words a code can have with given length and minimum distance. It is important however to understand that in some cases the true upper bound is unknown. A code which has a size equalto the calculated upper bound may not have been found. However, codes that have a larger size do not exist.

A second way to obtain bounds is a table. In `GUAVA`, an extensive table is implemented for linear codes over GF(2), GF(3) and GF(4). It contains bounds on the minimum distance for given word length and dimension. For binary codes, it contains entries for word length less than or equal to 257. For codes over GF(3) and GF(4), it contains entries for word length less than or equal to 130.

Firstly, we describe functions that compute specific upper bounds on the code size (see , , , , and ).

Next we describe a function that computes `GUAVA`'s best upper bound on the code size (see ).

Then we describe two functions that compute a lower and upper bound on the minimum distance of a code (see and ).

Finally, we describe a function that returns a lower and upper bound on the minimum distance with given parameters and a description of how the bounds were obtained (see ).

bounds, Singleton
UpperBoundSingleton
returns the Singleton bound for a code of length n, minimum distance d over a field of size q. This bound is based on the shortening of codes. By shortening an (n, M, d) code d-1 times, an (n-d+1,M,1) code results, with M \leq q^{n-d+1} (see ). Thus

M \leq q^{n-d+1}.
maximum distance separable
Codes that meet this bound are called maximum distance separable (see ).
gap> UpperBoundSingleton(4, 3, 5); 25 gap> C := ReedSolomonCode(4,3);; Size(C); 25 gap> IsMDSCode(C); true
bounds, Hamming
bounds, sphere packing bound
perfect
The Hamming bound (also known as the sphere packing bound) returns an upper bound on the size of a code of length n, minimum distance d, over a field of size q. The Hamming bound is obtained by dividing the contents of the entire space GF(q)^n by the contents of a ball with radius \lfloor(d-1) / 2\rfloor. As all these balls are disjoint, they can never contain more than the whole vector space. M \leq {q^n \over V(n,e)}, where M is the maxmimum number of codewords and V(n,e) is equal to the contents of a ball of radius e (see ). This bound is useful for small values of d. Codes for which equality holds are called perfect (see ).
gap> UpperBoundHamming( 15, 3, 2 ); 2048 gap> C := HammingCode( 4, GF(2) ); a linear [15,11,3]1 Hamming (4,2) code over GF(2) gap> Size( C ); 2048
bounds, Johnson
The Johnson bound is an improved version of the Hamming bound (see ). In addition to the Hamming bound, it takes into account the elements of the space outside the balls of radius e around the elements of the code. The Johnson bound only works for binary codes.
gap> UpperBoundJohnson( 13, 5 ); 77 gap> UpperBoundHamming( 13, 5, 2); 89 # in this case the Johnson bound is better
bounds, Plotkin
The function UpperBoundPlotkin calculates the sum of the distances of all ordered pairs of different codewords. It is based on the fact that the minimum distance is at most equal to the average distance. It is a good bound if the weights of the codewords do not differ much. It results in:

M \leq {d \over {d-(1-1/q)n}},
where M is the maximum number of codewords. In this case, d must be larger than (1-1/q)n, but by shortening the code, the case d \langle (1-1/q)n is covered.
gap> UpperBoundPlotkin( 15, 7, 2 ); 32 gap> C := BCHCode( 15, 7, GF(2) ); a cyclic [15,5,7]5 BCH code, delta=7, b=1 over GF(2) gap> Size(C); 32 gap> WeightDistribution(C); [ 1, 0, 0, 0, 0, 0, 0, 15, 15, 0, 0, 0, 0, 0, 0, 1 ]
bounds, Elias
The Elias bound is an improvement of the Plotkin bound (see ) for large codes. Subcodes are used to decrease the size of the code, in this case the subcode of all codewords within a certain ball. This bound is useful for large codes with relatively small minimum distances.
gap> UpperBoundPlotkin( 16, 3, 2 ); 12288 gap> UpperBoundElias( 16, 3, 2 ); 10280 gap> UpperBoundElias( 20, 10, 3 ); 16255
bounds, Griesmer
The Griesmer bound is valid only for linear codes. It is obtained by counting the number of equal symbols in each row of the generator matrix of the code. By omitting the coordinates in which all rows have a zero, a smaller code results. The Griesmer bound is obtained by repeating this proces until a trivial code is left in the end.
gap> UpperBoundGriesmer( 13, 5, 2 ); 64 gap> UpperBoundGriesmer( 18, 9, 2 ); 8 # the maximum number of words for a linear code is 8 gap> Size( PuncturedCode( HadamardCode( 20, 1 ) ) ); 20 # this non-linear code has 20 elements
A(n,d)
UpperBound
returns the best known upper bound A(n,d) for the size of a code of length n, minimum distance d over a field of size q. The function UpperBound first checks for trivial cases (like d=1 or n=d), and if the value is in the built-in table. Then it calculates the minimum value of the upper bound using the methods of Singleton (see ), Hamming (see ), Johnson (see ), Plotkin (see ) and Elias (see ). If the code is binary, A(n, 2\cdot \ell-1) = A(n+1,2\cdot \ell), so the UpperBound takes the minimum of the values obtained from all methods for the parameters (n, 2\cdot\ell-1) and (n+1, 2\cdot \ell).
gap> UpperBound( 10, 3, 2 ); 85 gap> UpperBound( 25, 9, 8 ); 1211778792827540
In this form, LowerBoundMinimumDistance returns a lower bound for the minimum distance of code C.

This command can also be called using the syntax LowerBoundMinimumDistance( n, k, F ). In this form, LowerBoundMinimumDistance returns a lower bound for the minimum distance of the best known linear code of length n, dimension k over field F. It uses the mechanism explained in section .
gap> C := BCHCode( 45, 7 ); a cyclic [45,23,7..9]6..16 BCH code, delta=7, b=1 over GF(2) gap> LowerBoundMinimumDistance( C ); 7 # designed distance is lower bound for minimum distance gap> LowerBoundMinimumDistance( 45, 23, GF(2) ); 10
bound, Gilbert-Varshamov lower
This is the lower bound due (independently) to Gilbert and Varshamov. It says that for each n and d, there exists a linear code having length n and minimum distance d at least of size q^{n-1}/ SphereContent(n-1,d-2,GF(q)).
gap> LowerBoundGilbertVarshamov(3,2,2); 4 gap> LowerBoundGilbertVarshamov(3,3,2); 1 gap> LowerBoundMinimumDistance(3,3,2); 1 gap> LowerBoundMinimumDistance(3,2,2); 2
bound, sphere packing lower
This is the lower bound due (independently) to Gilbert and Varshamov. It says that for each n and r, there exists an unrestricted code at least of size q^n/ SphereContent(n,d,GF(q)) minimum distance d.
gap> LowerBoundSpherePacking(3,2,2); 2 gap> LowerBoundSpherePacking(3,3,2); 1
In this form, UpperBoundMinimumDistance returns an upper bound for the minimum distance of code C. For unrestricted codes, it just returns the word length. For linear codes, it takes the minimum of the possibly known value from the method of construction, the weight of the generators, and the value from the table (see ).

This command can also be called using the syntax UpperBoundMinimumDistance( n, k, F ). In this form, UpperBoundMinimumDistance returns an upper bound for the minimum distance of the best known linear code of length n, dimension k over field F. It uses the mechanism explained in section .
gap> C := BCHCode( 45, 7 );; gap> UpperBoundMinimumDistance( C ); 9 gap> UpperBoundMinimumDistance( 45, 23, GF(2) ); 11
The function BoundsMinimumDistance calculates a lower and upper bound for the minimum distance of an optimal linear code with word length n, dimension k over field F. The function returns a record with the two bounds and an explenation for each bound. The function Display can be used to show the explanations.

The values for the lower and upper bound are obtained from a table. `GUAVA` has tables containing lower and upper bounds for q=2 (n \leq 257), 3, 4 (n \leq 130). (Current as of 1998.) These tables were derived from the table of Brouwer and Verhoeff. (See http://www.win.tue.nl/~aeb/voorlincod.html.) For codes over other fields and for larger word lengths, trivial bounds are used.

The resulting record can be used in the function BestKnownLinearCode (see ) to construct a code with minimum distance equal to the lower bound.
gap> bounds := BoundsMinimumDistance( 7, 3 );; DisplayBoundsInfo( bounds ); an optimal linear [7,3,d] code over GF(2) has d=4 ------------------------------------------------------------------------------ Lb(7,3)=4, by shortening of: Lb(8,4)=4, u u+v construction of C1 and C2: Lb(4,3)=2, dual of the repetition code Lb(4,1)=4, repetition code ------------------------------------------------------------------------------ Ub(7,3)=4, Griesmer bound # The lower bound is equal to the upper bound, so a code with # these parameters is optimal. gap> C := BestKnownLinearCode( bounds );; Display( C ); a linear [7,3,4]2..3 shortened code of a linear [8,4,4]2 U U+V construction code of U: a cyclic [4,3,2]1 dual code of a cyclic [4,1,4]2 repetition code over GF(2) V: a cyclic [4,1,4]2 repetition code over GF(2)
Covering radius bounds on codes
BoundsCoveringRadius
returns a list of integers. The first entry of this list is the maximum of some lower bounds for the covering radius of C, the last entry the minimum of some upper bounds of C.

If the covering radius of C is known, a list of length 1 is returned. BoundsCoveringRadius makes use of the functions GeneralLowerBoundCoveringRadius and GeneralUpperBoundCoveringRadius.
gap> BoundsCoveringRadius( BCHCode( 17, 3, GF(2) ) ); [ 3 .. 4 ] gap> BoundsCoveringRadius( HammingCode( 5, GF(2) ) ); [ 1 ]
IncreaseCoveringRadiusLowerBound
tries to increase the lower bound of the covering radius of C. It does this by means of a probabilistic algorithm. This algorithm takes a random word in GF(q)^n (or startword if it is specified), and, by changing random coordinates, tries to get as far from C as possible. If changing a coordinate finds a word that has a larger distance to the code than the previous one, the change is made permanent, and the algorithm starts all over again. If changing a coordinate does not find a coset leader that is further away from the code, then the change is made permanent with a chance of 1 in 100, if it gets the word closer to the code, or with a chance of 1 in 10, if the word stays at the same distance. Otherwise, the algorithm starts again with the same word as before.

If the algorithm did not allow changes that decrease the distance to the code, it might get stuck in a sub-optimal situation (the coset leader corresponding to such a situation - i.e. no coordinate of this coset leader can be changed in such a way that we get at a larger distance from the code - is called an orphan).

If the algorithm finds a word that has distance stopdist to the code, it ends and returns that word, which can be used for further investigations.

The variable InfoCoveringRadius can be set to Print to print the maximum distance reached so far every 1000 runs. The algorithm can be interrupted with ctrl-C, allowing the user to look at the word that is currently being examined (called `current'), or to change the chances that the new word is made permanent (these are called `staychance' and `downchance'). If one of these variables is i, then it corresponds with a i in 100 chance.

At the moment, the algorithm is only useful for codes with small dimension, where small means that the elements of the code fit in the memory. It works with larger codes, however, but when you use it for codes with large dimension, you should be very patient. If running the algorithm quits &GAP; (due to memory problems), you can change the global variable CRMemSize to a lower value. This might cause the algorithm to run slower, but without quitting &GAP;. The only way to find out the best value of CRMemSize is by experimenting.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> IncreaseCoveringRadiusLowerBound(C,10); Number of runs: 1000 best distance so far: 3 Number of runs: 2000 best distance so far: 3 Number of changes: 100 Number of runs: 3000 best distance so far: 3 Number of runs: 4000 best distance so far: 3 Number of runs: 5000 best distance so far: 3 Number of runs: 6000 best distance so far: 3 Number of runs: 7000 best distance so far: 3 Number of changes: 200 Number of runs: 8000 best distance so far: 3 Number of runs: 9000 best distance so far: 3 Number of runs: 10000 best distance so far: 3 Number of changes: 300 Number of runs: 11000 best distance so far: 3 Number of runs: 12000 best distance so far: 3 Number of runs: 13000 best distance so far: 3 Number of changes: 400 Number of runs: 14000 best distance so far: 3 user interrupt at... # # used ctrl-c to break out of execution # ... called from IncreaseCoveringRadiusLowerBound( code, -1, current ) called from function( arguments ) called from read-eval-loop Entering break read-eval-print loop ... you can 'quit;' to quit to outer loop, or you can 'return;' to continue brk> current; [ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0, 0*Z(2), Z(2)^0 ] brk> gap> CoveringRadius(C); 3

ExhaustiveSearchCoveringRadius
does an exhaustive search to find the covering radius of C. Every time a coset leader of a coset with weight w is found, the function tries to find a coset leader of a coset with weight w+1. It does this by enumerating all words of weight w+1, and checking whether a word is a coset leader. The start weight is the current known lower bound on the covering radius.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> ExhaustiveSearchCoveringRadius(C); Trying 3 ... [ 3 .. 5 ] gap> CoveringRadius(C); 3

GeneralLowerBoundCoveringRadius
returns a lower bound on the covering radius of C. It uses as many functions which names start with LowerBoundCoveringRadius as possible to find the best known lower bound (at least that `GUAVA` knows of) together with tables for the covering radius of binary linear codes with length not greater than $64$.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> GeneralLowerBoundCoveringRadius(C); 2 gap> CoveringRadius(C); 3

GeneralUpperBoundCoveringRadius
returns an upper bound on the covering radius of C. It uses as many functions which names start with UpperBoundCoveringRadius as possible to find the best known upper bound (at least that `GUAVA` knows of).
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> GeneralUpperBoundCoveringRadius(C); 4 gap> CoveringRadius(C); 3

This command can also be called using the syntax LowerBoundCoveringRadiusSphereCovering( n, r, [F,] true ). If the last argument of LowerBoundCoveringRadiusSphereCovering is false, then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

F is the field over which the code is defined. If F is omitted, it is assumed that the code is over GF(2). The bound is computed according to the sphere covering bound: M \cdot V_q(n,r) \geq q^n where V_q(n,r) is the size of a sphere of radius r in GF(q)^n.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 3 gap> LowerBoundCoveringRadiusSphereCovering(10,32,GF(2),false); 2 gap> LowerBoundCoveringRadiusSphereCovering(10,3,GF(2),true); 6

This command can also be called using the syntax LowerBoundCoveringRadiusVanWee1( n, r, [F,] true ). If the last argument of LowerBoundCoveringRadiusVanWee1 is false, then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

F is the field over which the code is defined. If F is omitted, it is assumed that the code is over GF(2).

The Van Wee bound is an improvement of the sphere covering bound: M \cdot \left\{ V_q(n,r) - \frac{{n \choose r}}{\lceil\frac{n-r}{r+1}\rceil} \left(\left\lceil\frac{n+1}{r+1}\right\rceil - \frac{n+1}{r+1}\right) \right\} \geq q^n
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 3 gap> LowerBoundCoveringRadiusVanWee1(10,32,GF(2),false); 2 gap> LowerBoundCoveringRadiusVanWee1(10,3,GF(2),true); 6

This command can also be called using the syntax LowerBoundCoveringRadiusVanWee2( n, r [,true] ). If the last argument of LowerBoundCoveringRadiusVanWee2 is false, then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

This bound only works for binary codes. It is based on the following inequality: M \cdot \frac{\left( \left( V_2(n,2) - \frac{1}{2}(r+2)(r-1) \right) V_2(n,r) + \varepsilon V_2(n,r-2) \right)} {(V_2(n,2) - \frac{1}{2}(r+2)(r-1) + \varepsilon)} \geq 2^n, where

\varepsilon = {r+2 \choose 2} \left\lceil {n-r+1 \choose 2} / {r+2 \choose 2} \right\rceil - {n-r+1 \choose 2}.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 3 gap> LowerBoundCoveringRadiusVanWee2(10,32,false); 2 gap> LowerBoundCoveringRadiusVanWee2(10,3,true); 7

This command can also be called with LowerBoundCoveringRadiusCountingExcess( n, r [,true] ). If the last argument of LowerBoundCoveringRadiusCountingExcess is false, then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

This bound only works for binary codes. It is based on the following inequality: M \cdot \left( \rho V_2(n,r) + \varepsilon V_2(n,r-1) \right) \geq (\rho + \varepsilon) 2^n, where

\varepsilon = (r+1) \left\lceil\frac{n+1}{r+1}\right\rceil - (n+1)
and

\rho = \left\{ \begin{array}{l} n-3+\frac{2}{n}, \ \ \ \ \ \ {\rm if}\ r = 2\\ n-r-1 , \ \ \ \ \ \ {\rm if}\ r \geq 3 . \end{array} \right.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 3 gap> LowerBoundCoveringRadiusCountingExcess(10,32,false); 0 gap> LowerBoundCoveringRadiusCountingExcess(10,3,true); 7

This command can also be called with LowerBoundCoveringRadiusEmbedded1( n, r [,true] ). If the last argument of LowerBoundCoveringRadiusEmbedded1 is 'false', then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

This bound only works for binary codes. It is based on the following inequality:

M \cdot \left( V_2(n,r) - {2r \choose r} \right) \geq 2^n - A( n, 2r+1 ) {2r \choose r},
where A(n,d) denotes the maximal cardinality of a (binary) code of length n and minimum distance d. The function UpperBound is used to compute this value.

Sometimes LowerBoundCoveringRadiusEmbedded1 is better than LowerBoundCoveringRadiusEmbedded2, sometimes it is the other way around.
gap> C:=RandomLinearCode(10,5,GF(2)); a [10,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 3 gap> LowerBoundCoveringRadiusEmbedded1(10,32,false); 2 gap> LowerBoundCoveringRadiusEmbedded1(10,3,true); 7

This command can also be called with LowerBoundCoveringRadiusEmbedded2( n, r [,true] ). If the last argument of LowerBoundCoveringRadiusEmbedded2 is 'false', then it returns a lower bound for the covering radius of a code of size M and length n. Otherwise, it returns a lower bound for the size of a code of length n and covering radius r.

This bound only works for binary codes. It is based on the following inequality:

M \cdot \left( V_2(n,r) - \frac{3}{2} {2r \choose r} \right) \geq 2^n - 2A( n, 2r+1 ) {2r \choose r},
where A(n,d) denotes the maximal cardinality of a (binary) code of length n and minimum distance d. The function UpperBound is used to compute this value.

Sometimes LowerBoundCoveringRadiusEmbedded1 is better than LowerBoundCoveringRadiusEmbedded2, sometimes it is the other way around.
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> Size(C); 32 gap> CoveringRadius(C); 6 gap> LowerBoundCoveringRadiusEmbedded2(10,32,false); 2 gap> LowerBoundCoveringRadiusEmbedded2(10,3,true); 7

LowerBoundCoveringRadiusInduction
returns a lower bound for the size of a code with length n and covering radius r.

If n = 2r+2 and r \geq 1, the returned value is 4.

If n = 2r+3 and r \geq 1, the returned value is 7.

If n = 2r+4 and r \geq 4, the returned value is 8.

Otherwise, 0 is returned.
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> CoveringRadius(C); 5 gap> LowerBoundCoveringRadiusInduction(15,6); 7

UpperBoundCoveringRadiusRedundancy
returns the redundancy of C as an upper bound for the covering radius of C. C must be a linear code.
external distance
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> CoveringRadius(C); 5 gap> UpperBoundCoveringRadiusRedundancy(C); 10

UpperBoundCoveringRadiusDelsarte
returns an upper bound for the covering radius of C. This upper bound is equal to the external distance of C, this is the minimum distance of the dual code, if C is a linear code.

This is described in Theorem 11.3.3 of .
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> CoveringRadius(C); 5 gap> UpperBoundCoveringRadiusDelsarte(C); 13
UpperBoundCoveringRadiusStrength
returns an upper bound for the covering radius of C.

First the code is punctured at the zero coordinates (i.e. the coordinates where all codewords have a zero). If the remaining code has strength 1 (i.e. each coordinate contains each element of the field an equal number of times), then it returns \frac{q-1}{q}m + (n-m) (where q is the size of the field and m is the length of punctured code), otherwise it returns n. This bound works for all codes.
strength
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> CoveringRadius(C); 5 gap> UpperBoundCoveringRadiusStrength(C); 7
This function returns an upper bound for the covering radius of C, which must be linear, in a Griesmer-like fashion. It returns

n - \sum_{i=1}^k \left\lceil \frac{d}{q^i} \right\rceil
gap> C:=RandomLinearCode(15,5,GF(2)); a [15,5,?] randomly generated code over GF(2) gap> CoveringRadius(C); 5 gap> UpperBoundCoveringRadiusGriesmerLike(C); 9

This function returns an upper bound for the covering radius of C, which must be a cyclic code. It returns

n - k + 1 - \left\lceil \frac{w(g(x))}{2} \right\rceil,
where g(x) is the generator polynomial of C.
gap> C:=CyclicCodes(15,GF(2))[3]; a cyclic [15,12,1..2]1..3 enumerated code over GF(2) gap> CoveringRadius(C); 3 gap> UpperBoundCoveringRadiusCyclicCode(C); 3

Special matrices in `GUAVA`

This section explains functions that work with special matrices `GUAVA` needs for several codes.

Firstly, we describe some matrix generating functions (see , , , and ).

Next we describe two functions regarding a standard form of matrices (see and ).

Then we describe functions that return a matrix after a manipulation (see , and ).

Finally, we describe functions that do some tests on matrices (see and ).

KrawtchoukMat
returns the n+1 by n+1 matrix K=(k_{ij}) defined by k_{ij}=K_i(j) for i,j=0,...,n. K_i(j) is the Krawtchouk number (see ). n must be a positive integer and q a prime power. The Krawtchouk matrix is used in the MacWilliams identities, defining the relation between the weight distribution of a code of length n over a field of size q, and its dual code. Each call to KrawtchoukMat returns a new matrix, so it is safe to modify the result.
gap> PrintArray( KrawtchoukMat( 3, 2 ) ); [ [ 1, 1, 1, 1 ], [ 3, 1, -1, -3 ], [ 3, -1, -1, 3 ], [ 1, -1, 1, -1 ] ] gap> C := HammingCode( 3 );; a := WeightDistribution( C ); [ 1, 0, 0, 7, 7, 0, 0, 1 ] gap> n := WordLength( C );; q := Size( LeftActingDomain( C ) );; gap> k := Dimension( C );; gap> q^( -k ) * KrawtchoukMat( n, q ) * a; [ 1, 0, 0, 0, 7, 0, 0, 0 ] gap> WeightDistribution( DualCode( C ) ); [ 1, 0, 0, 0, 7, 0, 0, 0 ]
Gary code
GrayMat
returns a list of all different vectors (see &GAP;'s Vectors command) of length n over the field F, using Gray ordering. n must be a positive integer. This order has the property that subsequent vectors differ in exactly one coordinate. The first vector is always the null vector. Each call to GrayMat returns a new matrix, so it is safe to modify the result.
gap> GrayMat(3); [ [ 0*Z(2), 0*Z(2), 0*Z(2) ], [ 0*Z(2), 0*Z(2), Z(2)^0 ], [ 0*Z(2), Z(2)^0, Z(2)^0 ], [ 0*Z(2), Z(2)^0, 0*Z(2) ], [ Z(2)^0, Z(2)^0, 0*Z(2) ], [ Z(2)^0, Z(2)^0, Z(2)^0 ], [ Z(2)^0, 0*Z(2), Z(2)^0 ], [ Z(2)^0, 0*Z(2), 0*Z(2) ] ] gap> G := GrayMat( 4, GF(4) );; Length(G); 256 # the length of a GrayMat is always $q^n$ gap> G[101] - G[100]; [ 0*Z(2), 0*Z(2), Z(2)^0, 0*Z(2) ]
SylvesterMat
returns the n\times n Sylvester matrix of order n. This is a special case of the Hadamard matrices (see ). For this construction, n must be a power of 2. Each call to SylvesterMat returns a new matrix, so it is safe to modify the result.
gap> PrintArray(SylvesterMat(2)); [ [ 1, 1 ], [ 1, -1 ] ] gap> PrintArray( SylvesterMat(4) ); [ [ 1, 1, 1, 1 ], [ 1, -1, 1, -1 ], [ 1, 1, -1, -1 ], [ 1, -1, -1, 1 ] ]
Hadamard matrix
HadamardMat
returns a Hadamard matrix of order n. This is an n\times n matrix with the property that the matrix multiplied by its transpose returns n times the identity matrix. This is only possible for n=1, n=2 or in cases where n is a multiple of 4. If the matrix does not exist or is not known (as of 1998), HadamardMat returns an error. A large number of construction methods is known to create these matrices for different orders. HadamardMat makes use of two construction methods (among which the Sylvester construction -- see ). These methods cover most of the possible Hadamard matrices, although some special algorithms have not been implemented yet. The following orders less than 100 do not yet have an implementation for a Hadamard matrix in `GUAVA`: 28, 36, 52, 76, 92.
gap> C := HadamardMat(8);; PrintArray(C); [ [ 1, 1, 1, 1, 1, 1, 1, 1 ], [ 1, -1, 1, -1, 1, -1, 1, -1 ], [ 1, 1, -1, -1, 1, 1, -1, -1 ], [ 1, -1, -1, 1, 1, -1, -1, 1 ], [ 1, 1, 1, 1, -1, -1, -1, -1 ], [ 1, -1, 1, -1, -1, 1, -1, 1 ], [ 1, 1, -1, -1, -1, -1, 1, 1 ], [ 1, -1, -1, 1, -1, 1, 1, -1 ] ] gap> C * TransposedMat(C) = 8 * IdentityMat( 8, 8 ); true
The function VandermondeMat returns the (a+1)\times n matrix of powers x_i^j where X is a list of elements of a field, X=\{ x_1,...,x_n\}, and a is a non-negative integer.
gap> M:=VandermondeMat([Z(5),Z(5)^2,Z(5)^0,Z(5)^3],2); [ [ Z(5)^0, Z(5), Z(5)^2 ], [ Z(5)^0, Z(5)^2, Z(5)^0 ], [ Z(5)^0, Z(5)^0, Z(5)^0 ], [ Z(5)^0, Z(5)^3, Z(5)^2 ] ] gap> Display(M); 1 2 4 1 4 1 1 1 1 1 3 4
standard form
We say that a k\times n matrix is in standard form if it is equal to the block matrix (I\ |\ A), for some k\times (n-k) matrix A and where I is the k\times k identity matrix. It follows from a basis result in linear algebra that, after a possible permutation of the columns, using elementary row operations, every matrix can be reduced to standard form. PutStandardForm puts a matrix M in standard form, and returns the permutation needed to do so. idleft is a boolean that sets the position of the identity matrix in M. (The default for idleft is `true'.) If idleft is set to `true', the identity matrix is put on the left side of M. Otherwise, it is put at the right side. (This option is useful when putting a check matrix of a code into standard form.) The function BaseMat also returns a similar standard form, but does not apply column permutations. The rows of the matrix still span the same vector space after BaseMat, but after calling PutStandardForm, this is not necessarily true.
gap> M := Z(2)*[[1,0,0,1],[0,0,1,1]];; PrintArray(M); [ [ Z(2), 0*Z(2), 0*Z(2), Z(2) ], [ 0*Z(2), 0*Z(2), Z(2), Z(2) ] ] gap> PutStandardForm(M); # identity at the left side (2,3) gap> PrintArray(M); [ [ Z(2), 0*Z(2), 0*Z(2), Z(2) ], [ 0*Z(2), Z(2), 0*Z(2), Z(2) ] ] gap> PutStandardForm(M, false); # identity at the right side (1,4,3) gap> PrintArray(M); [ [ 0*Z(2), Z(2), Z(2), 0*Z(2) ], [ 0*Z(2), Z(2), 0*Z(2), Z(2) ] ]
IsInStandardForm
determines if M is in standard form. idleft is a boolean that indicates the position of the identity matrix in M, as in PutStandardForm (see ). IsInStandardForm checks if the identity matrix is at the left side of M, otherwise if it is at the right side. The elements of M may be elements of any field.
gap> IsInStandardForm(IdentityMat(7, GF(2))); true gap> IsInStandardForm([[1, 1, 0], [1, 0, 1]], false); true gap> IsInStandardForm([[1, 3, 2, 7]]); true gap> IsInStandardForm(HadamardMat(4)); false
PermutedCols
returns a matrix M with a permutation P applied to its columns.
gap> M := [[1,2,3,4],[1,2,3,4]];; PrintArray(M); [ [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ] ] gap> PrintArray(PermutedCols(M, (1,2,3))); [ [ 3, 1, 2, 4 ], [ 3, 1, 2, 4 ] ]
VerticalConversionFieldMat
returns the matrix M with its elements converted from a field F=GF(q^m), q prime, to a field GF(q). Each element is replaced by its representation over the latter field, placed vertically in the matrix, using the GF(p)-vector space isomorphism

[...] : GF(q)\rightarrow GF(p)^m,
with q=p^m.

If M is a k by n matrix, the result is a k\cdot m \times n matrix, since each element of GF(q^m) can be represented in GF(q) using m elements.
gap> M := Z(9)*[[1,2],[2,1]];; PrintArray(M); [ [ Z(3^2), Z(3^2)^5 ], [ Z(3^2)^5, Z(3^2) ] ] gap> DefaultField( Flat(M) ); GF(3^2) gap> VCFM := VerticalConversionFieldMat( M, GF(9) );; PrintArray(VCFM); [ [ 0*Z(3), 0*Z(3) ], [ Z(3)^0, Z(3) ], [ 0*Z(3), 0*Z(3) ], [ Z(3), Z(3)^0 ] ] gap> DefaultField( Flat(VCFM) ); GF(3)

A similar function is HorizontalConversionFieldMat (see ).

HorizontalConversionFieldMat
returns the matrix M with its elements converted from a field F=GF(q^m), q prime, to a field GF(q). Each element is replaced by its representation over the latter field, placed horizontally in the matrix.

If M is a k \times n matrix, the result is a k\times m\times n\cdot m matrix. The new word length of the resulting code is equal to n\cdot m, because each element of GF(q^m) can be represented in GF(q) using m elements. The new dimension is equal to k\times m because the new matrix should be a basis for the same number of vectors as the old one.

ConversionFieldCode
uses horizontal conversion to convert a code (see ).
gap> M := Z(9)*[[1,2],[2,1]];; PrintArray(M); [ [ Z(3^2), Z(3^2)^5 ], [ Z(3^2)^5, Z(3^2) ] ] gap> DefaultField( Flat(M) ); GF(3^2) gap> HCFM := HorizontalConversionFieldMat(M, GF(9));; PrintArray(HCFM); [ [ 0*Z(3), Z(3)^0, 0*Z(3), Z(3) ], [ Z(3)^0, Z(3)^0, Z(3), Z(3) ], [ 0*Z(3), Z(3), 0*Z(3), Z(3)^0 ], [ Z(3), Z(3), Z(3)^0, Z(3)^0 ] ] gap> DefaultField( Flat(HCFM) ); GF(3)

A similar function is VerticalConversionFieldMat (see ).

mutually orthogonal Latin squares
Latin square
MOLS
returns a list of n Mutually Orthogonal Latin Squares (MOLS). A Latin square of order q is a q\times q matrix whose entries are from a set F_{q} of q distinct symbols (`GUAVA` uses the integers from 0 to q) such that each row and each column of the matrix contains each symbol exactly once.

A set of Latin squares is a set of MOLS if and only if for each pair of Latin squares in this set, every ordered pair of elements that are in the same position in these matrices occurs exactly once.

n must be less than q. If n is omitted, two MOLS are returned. If q is not a prime power, at most 2 MOLS can be created. For all values of q with q > 2 and q \neq 6, a list of MOLS can be constructed. However, `GUAVA` does not yet construct MOLS for q\equiv 2 \pmod 4. If it is not possible to construct n MOLS, the function returns `false'.

MOLS are used to create q-ary codes (see ).
gap> M := MOLS( 4, 3 );;PrintArray( M[1] ); [ [ 0, 1, 2, 3 ], [ 1, 0, 3, 2 ], [ 2, 3, 0, 1 ], [ 3, 2, 1, 0 ] ] gap> PrintArray( M[2] ); [ [ 0, 2, 3, 1 ], [ 1, 3, 2, 0 ], [ 2, 0, 1, 3 ], [ 3, 1, 0, 2 ] ] gap> PrintArray( M[3] ); [ [ 0, 3, 1, 2 ], [ 1, 2, 0, 3 ], [ 2, 1, 3, 0 ], [ 3, 0, 2, 1 ] ] gap> MOLS( 12, 3 ); false
IsLatinSquare
determines if a matrix M is a Latin square. For a Latin square of size n\times n, each row and each column contains all the integers 1,\dots,n exactly once.
gap> IsLatinSquare([[1,2],[2,1]]); true gap> IsLatinSquare([[1,2,3],[2,3,1],[1,3,2]]); false
AreMOLS
determines if L is a list of mutually orthogonal Latin squares (MOLS). For each pair of Latin squares in this list, the function checks if each ordered pair of elements that are in the same position in these matrices occurs exactly once. The function MOLS creates MOLS (see ).
gap> M := MOLS(4,2); [ [ [ 0, 1, 2, 3 ], [ 1, 0, 3, 2 ], [ 2, 3, 0, 1 ], [ 3, 2, 1, 0 ] ], [ [ 0, 2, 3, 1 ], [ 1, 3, 2, 0 ], [ 2, 0, 1, 3 ], [ 3, 1, 0, 2 ] ] ] gap> AreMOLS(M); true
Some functions related to the norm of a code

In this section, some functions that can be used to compute the norm of a code and to decide upon its normality are discussed. Typically, these are applied to binary linear codes. The definitions of this section were introduced in Graham and Sloane .

CoordinateNorm
returns the norm of C with respect to coordinate coord. If C_a = \{ c \in C \ |\ c_{coord} = a \}, then the norm of C with respect to coord is defined as

\max_{v \in GF(q)^n} \sum_{a=1}^q d(x,C_a),
with the convention that d(x,C_a) = n if C_a is empty.
gap> CoordinateNorm( HammingCode( 3, GF(2) ), 3 ); 3
norm of a code
CodeNorm
returns the norm of C. The norm of a code is defined as the minimum of the norms for the respective coordinates of the code. In effect, for each coordinate CoordinateNorm is called, and the minimum of the calculated numbers is returned.
gap> CodeNorm( HammingCode( 3, GF(2) ) ); 3
acceptable coordinate
IsCoordinateAcceptable
returns `true' if coordinate coord of C is acceptable. A coordinate is called acceptable if the norm of the code with respect to that coordinate is not more than two times the covering radius of the code plus one.
gap> IsCoordinateAcceptable( HammingCode( 3, GF(2) ), 3 ); true
acceptable coordinate
GeneralizedCodeNorm
returns the k-norm of C with respect to k subcodes.
gap> c := RepetitionCode( 7, GF(2) );; gap> ham := HammingCode( 3, GF(2) );; gap> d := EvenWeightSubcode( ham );; gap> e := ConstantWeightSubcode( ham, 3 );; gap> GeneralizedCodeNorm( ham, c, d, e ); 4
normal code
IsNormalCode
returns `true' if C is normal. A code is called normal if the norm of the code is not more than two times the covering radius of the code plus one. Almost all codes are normal, however some (non-linear) abnormal codes have been found.

Often, it is difficult to find out whether a code is normal, because it involves computing the covering radius. However, IsNormalCode uses much information from the literature (in particular, ) about normality for certain code parameters.
gap> IsNormalCode( HammingCode( 3, GF(2) ) ); true
Miscellaneous functions

In this section we describe several functions `GUAVA` uses for constructing codes or performing calculations with codes.

In this section, some new miscellaneous functions are described, including weight enumerators, the MacWilliams-transform and affinity and almost affinity of codes.

weight enumerator polynomial
CodeWeightEnumerator
returns a polynomial of the following form:

f(x) = \sum_{i=0}^{n} A_i x^i,
where A_i is the number of codewords in C with weight i.
gap> CodeWeightEnumerator( ElementsCode( [ [ 0,0,0 ], [ 0,0,1 ], > [ 0,1,1 ], [ 1,1,1 ] ], GF(2) ) ); x^3 + x^2 + x + 1 gap> CodeWeightEnumerator( HammingCode( 3, GF(2) ) ); x^7 + 7*x^4 + 7*x^3 + 1
CodeDistanceEnumerator
returns a polynomial of the following form:

f(x) = \sum_{i=0}^{n} B_i x^i,
where B_i is the number of codewords with distance i to w.

If w is a codeword, then CodeDistanceEnumerator returns the same polynomial as CodeWeightEnumerator.
gap> CodeDistanceEnumerator( HammingCode( 3, GF(2) ),[0,0,0,0,0,0,1] ); x^6 + 3*x^5 + 4*x^4 + 4*x^3 + 3*x^2 + x gap> CodeDistanceEnumerator( HammingCode( 3, GF(2) ),[1,1,1,1,1,1,1] ); x^7 + 7*x^4 + 7*x^3 + 1 # `[1,1,1,1,1,1,1]' $\in$ `HammingCode( 3, GF(2 ) )'
MacWilliams transform
CodeMacWilliamsTransform
returns a polynomial of the following form:

f(x) = \sum_{i=0}^{n} C_i x^i,
where C_i is the number of codewords with weight i in the dual code of C.
gap> CodeMacWilliamsTransform( HammingCode( 3, GF(2) ) ); 7*x^4 + 1
IsSelfComplementaryCode
returns `true' if

v \in code \Rightarrow 1 - v \in code,
where 1 is the all-one word of length n.
gap> IsSelfComplementaryCode( HammingCode( 3, GF(2) ) ); true gap> IsSelfComplementaryCode( EvenWeightSubcode( > HammingCode( 3, GF(2) ) ) ); false
affine code
IsAffineCode
returns `true' if C is an affine code. A code is called affine if it is an affine space. In other words, a code is affine if it is a coset of a linear code.
gap> IsAffineCode( HammingCode( 3, GF(2) ) ); true gap> IsAffineCode( CosetCode( HammingCode( 3, GF(2) ), > [ 1, 0, 0, 0, 0, 0, 0 ] ) ); true gap> IsAffineCode( NordstromRobinsonCode() ); false
IsAlmostAffineCode
returns `true' if C is an almost affine code. A code is called almost affine if the size of any punctured code of C is q^r for some r, where q is the size of the alphabet of the code. Every affine code is also almost affine, and every code over GF(2) and GF(3) that is almost affine is also affine.
gap> code := ElementsCode( [ [0,0,0], [0,1,1], [0,2,2], [0,3,3], > [1,0,1], [1,1,0], [1,2,3], [1,3,2], > [2,0,2], [2,1,3], [2,2,0], [2,3,1], > [3,0,3], [3,1,2], [3,2,1], [3,3,0] ], > GF(4) );; gap> IsAlmostAffineCode( code ); true gap> IsAlmostAffineCode( NordstromRobinsonCode() ); false
Griesmer code
IsGriesmerCode
returns `true' if C, which must be a linear code, is Griesmer code, and `false' otherwise. A code is called Griesmer if its length satisfies

n = g[k,d] = \sum_{i=0}^{k-1} \lceil \frac{d}{q^i} \rceil.
gap> IsGriesmerCode( HammingCode( 3, GF(2) ) ); true gap> IsGriesmerCode( BCHCode( 17, 2, GF(2) ) ); false
density of a code
CodeDensity
returns the density of C. The density of a code is defined as

\frac{M \cdot V_q(n,t)}{q^n},
where M is the size of the code, V_q(n,t) is the size of a sphere of radius t in GF(q^n) (which may be computed using SphereContent), t is the covering radius of the code and n is the length of the code.
gap> CodeDensity( HammingCode( 3, GF(2) ) ); 1 gap> CodeDensity( ReedMullerCode( 1, 4 ) ); 14893/2048
perfect
SphereContent
returns the content of a ball of radius t around an arbitrary element of the vectorspace F^n. This is the cardinality of the set of all elements of F^n that are at distance (see less than or equal to t from an element of F^n.

In the context of codes, the function is used to determine if a code is perfect. A code is perfect if spheres of radius t around all codewords contain exactly the whole vectorspace, where t is the number of errors the code can correct.
gap> SphereContent( 15, 0, GF(2) ); 1 # Only one word with distance 0, which is the word itself gap> SphereContent( 11, 3, GF(4) ); 4984 gap> C := HammingCode(5); a linear [31,26,3]1 Hamming (5,2) code over GF(2) #the minimum distance is 3, so the code can correct one error gap> ( SphereContent( 31, 1, GF(2) ) * Size(C) ) = 2 ^ 31; true
Krawtchouk
returns the Krawtchouk number K_{k}(i). q must be a prime power, n must be a positive integer, k must be a non-negative integer less then or equal to n and i can be any integer. (See ). This number is the value at x=i of the polynomial

K_k^{n,q}(x) =\sum_{j=0}^n (-1)^j(q-1)^{k-j}b(x,j)b(n-x,k-j),
where $b(v,u)=u!/(v!(v-u)!)$ is the binomial coefficient if $u,v$ are integers. For more properties of these polynomials, see .
gap> Krawtchouk( 2, 0, 3, 2); 3
PrimitiveUnityRoot
returns a primitive n-th root of unity in an extension field of F. This is a finite field element a with the property a^n=1 in F, and n is the smallest integer such that this equality holds.
gap> PrimitiveUnityRoot( GF(2), 15 ); Z(2^4) gap> last^15; Z(2)^0 gap> PrimitiveUnityRoot( GF(8), 21 ); Z(2^6)^3
reciprocal polynomial
ReciprocalPolynomial
returns the reciprocal of polynomial P. This is a polynomial with coefficients of P in the reverse order. So if P=a_0 + a_1 X + ... + a_{n} X^{n}, the reciprocal polynomial is P'=a_{n} + a_{n-1} X + ... + a_0 X^{n}.

This command can also be called using the syntax ReciprocalPolynomial( P , n ). In this form, the number of coefficients of P is assumed to be less than or equal to n+1 (with zero coefficients added in the highest degrees, if necessary). Therefore, the reciprocal polynomial also has degree n+1.
gap> P := UnivariatePolynomial( GF(3), Z(3)^0 * [1,0,1,2] ); Z(3)^0+x_1^2-x_1^3 gap> RecP := ReciprocalPolynomial( P ); -Z(3)^0+x_1+x_1^3 gap> ReciprocalPolynomial( RecP ) = P; true gap> P := UnivariatePolynomial( GF(3), Z(3)^0 * [1,0,1,2] ); Z(3)^0+x_1^2-x_1^3 gap> ReciprocalPolynomial( P, 6 ); -x_1^3+x_1^4+x_1^6
CyclotomicCosets
returns the cyclotomic cosets of q \pmod n. q and n must be relatively prime. Each of the elements of the returned list is a list of integers that belong to one cyclotomic coset. A q-cyclotomic coset of s \pmod n is a set of the form \{s,sq,sq^2,...,sq^{r-1}\}, where r is the smallest positive integer such that sq^r-s is 0 \pmod n. In other words, each coset contains all multiplications of the coset representative by q \pmod n. The coset representative is the smallest integer that isn't in the previous cosets.
gap> CyclotomicCosets( 2, 15 ); [ [ 0 ], [ 1, 2, 4, 8 ], [ 3, 6, 12, 9 ], [ 5, 10 ], [ 7, 14, 13, 11 ] ] gap> CyclotomicCosets( 7, 6 ); [ [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ] ]
The function WeightHistogram plots a histogram of weights in code C. The maximum length of a column is h. Default value for h is 1/3 of the size of the screen. The number that appears at the top of the histogram is the maximum value of the list of weights.
gap> H := HammingCode(2, GF(5)); a linear [6,4,3]1 Hamming (2,5) code over GF(5) gap> WeightDistribution(H); [ 1, 0, 0, 80, 120, 264, 160 ] gap> WeightHistogram(H); 264---------------- * * * * * * * * * * * * * * * * * +--------+--+--+--+-- 0 1 2 3 4 5 6
The function CoefficientToPolynomial returns the degree d-1 polynomial c_0+c_1x+...+c_{d-1}x^{d-1}, where coeffs is a list of elements of a field, coeffs=\{ c_0,...,c_{d-1}\}, and R is a univariate polynomial ring.
gap> F:=GF(11); GF(11) gap> R1:=PolynomialRing(F,["a"]);; gap> var1:=IndeterminatesOfPolynomialRing(R1);; a:=var1[1];; gap> coeffs:=Z(11)^0*[1,2,3,4]; [ Z(11)^0, Z(11), Z(11)^8, Z(11)^2 ] gap> CoefficientToPolynomial(coeffs,R1); Z(11)^2*a^3+Z(11)^8*a^2+Z(11)*a+Z(11)^0
The function DegreesMonomialTerm returns the list of degrees to which each variable in the multivariate polynomial ring R occurs in the monomial m, where coeffs is a list of elements of a field.
gap> F:=GF(11); GF(11) gap> R1:=PolynomialRing(F,["a"]);; gap> var1:=IndeterminatesOfPolynomialRing(R1);; a:=var1[1];; gap> b:=X(F,"b",var1); b gap> var2:=Concatenation(var1,[b]); [ a, b ] gap> R2:=PolynomialRing(F,var2); PolynomialRing(..., [ a, b ]) gap> c:=X(F,"c",var2); c gap> var3:=Concatenation(var2,[c]); [ a, b, c ] gap> R3:=PolynomialRing(F,var3); PolynomialRing(..., [ a, b, c ]) gap> m:=b^3*c^7; b^3*c^7 gap> DegreesMonomialTerm(m,R3); [ 0, 3, 7 ]
The function DivisorsMultivariatePolynomial returns the list of polynomial divisors of f in the multivariate polynomial ring R with coefficients in a field. This program uses a simple but slow algorithm (see Joachim von zur Gathen, J\"urgen Gerhard, , exercise 16.10) which first converts the multivariate polynomial f to an associated univariate polynomial f^*, then Factors f^*, and finally converts these univariate factors back into the multivariate polynomial factors of f. Since Factors is non-deterministic, DivisorsMultivariatePolynomial is non-deterministic as well.
gap> R2:=PolynomialRing(GF(3),["x1","x2"]); PolynomialRing(..., [ x1, x2 ]) gap> vars:=IndeterminatesOfPolynomialRing(R2); [ x1, x2 ] gap> x2:=vars[2]; x2 gap> x1:=vars[1]; x1 gap> f:=x1^3+x2^3;; gap> DivisorsMultivariatePolynomial(f,R2); [ x1+x2, x1+x2, x1+x2 ]