# Codeword Operations

## Construction

### `C ! [a₁, ..., aₙ]: Code, [ RngElt ] -> ModTupRngElt`

### `elt< C | a₁, ..., aₙ>: Code, List -> ModTupRngElt`

Given a code $C$ which is defined as a subset of the $R$-space $R^{(n)}$, and elements $a_1, \ldots, a_n$ belonging to $R$, construct the codeword $(a_1, \ldots, a_n)$ of $C$. It is checked that the vector ($a_1, \ldots, a_n$) is an element of $C$.

### `C ! u: Code, ModTupRngElt -> ModTupRngElt`

Given a code $C$ which is defined as a subset of the $R$-space $V = R^{(n)}$, and an element $u$ belonging to $V$, create the codeword of $C$ corresponding to $u$. The function will fail if $u$ does not belong to $C$.

### `C ! 0: Code, RngIntElt -> ModTupRngElt`

The zero word of the code $C$.

### `Example: Code Elts (ex-c7f5f7)`

We create some elements of a code over a finite ring.

```magma
> R<w> := GR(16,2);
> P<x> := PolynomialRing(R);
> L := CyclotomicFactors(R, 7);
> C := CyclicCode(7, L[2]);
> C ! [1, 2*w, 0, w+3, 7*w, 12*w+3, w+3];
(       1      2*w        0    w + 3      7*w 12*w + 3    w + 3)
> elt< C | 0, 3, 0, 2*w + 5, 6*w + 9, 4*w + 5, 14*w + 14 >;
(        0         3         0   2*w + 5   6*w + 9   4*w + 5 14*w + 14)

```

If the given vector does not lie in the given code then an error will result.

```magma
> C ! [0,0,0,0,0,0,1];

>> C ! [0,0,0,0,0,0,1];
     ^
Runtime error in '!': Result is not in the given structure
> elt< C | 1, 0, 1, 0, 1, 0, 1>;

>> elt< C | 1, 0, 1, 0, 1, 0, 1>;
      ^
Runtime error in elt< ... >: Result is not in the lhs of the constructor

```

## Operations

### `u + v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

Sum of the codewords $u$ and $v$, where $u$ and $v$ belong to the same linear code $C$.

### `- u: ModTupRngElt -> ModTupRngElt`

Additive inverse of the codeword $u$ belonging to the linear code $C$.

### `u - v: ModTupRngElt, ModTupRngElt -> ModTupRngElt`

Difference of the codewords $u$ and $v$, where $u$ and $v$ belong to the same linear code $C$.

### `a * u: RngElt, ModTupRngElt -> ModTupRngElt`

Given an element $a$ belonging to the ring $R$, and a codeword $u$ belonging to the linear code $C$, return the codeword $a*u$.

### `Weight(v): ModTupRngElt -> RngIntElt`

The Hamming weight of the codeword $v$, i.e., the number of non-zero components of $v$.

### `Distance(u, v): ModTupRngElt, ModTupRngElt -> RngIntElt`

The Hamming distance between the codewords $u$ and $v$, where $u$ and $v$ belong to the same code $C$.

### `Support(w): ModTupRngElt -> { RngIntElt }`

Given a word $w$ belonging to the length $n$ code $C$, return its support as a subset of the integer set $\{ 1 .. n \}$. The support of $w$ consists of the coordinates at which $w$ has non-zero entries.

### `(u, v): ModTupRngElt, ModTupRngElt -> RngElt`

### `InnerProduct(u, v): ModTupRngElt, ModTupRngElt -> RngElt`

Inner product of the vectors $u$ and $v$ with respect to the Euclidean norm, where $u$ and $v$ belong to the parent vector space of the code $C$.

### `Coordinates(C, u): Code, ModTupRngElt -> [ RngFinElt ]`

Given a length $n$ linear code $C$ and a codeword $u$ of $C$ return the coordinates of $u$ with respect to $C$. The coordinates of $u$ are returned as a sequence $Q = [a_1, \ldots, a_k]$ of elements from the alphabet of $C$ so that $u = a_1 * C.1 + \ldots + a_k * C.k$.

### `Normalize(u): ModTupRngElt -> ModTupRngElt`

Given an element $u$ of a code defined over the ring $R$, return the normalization of $u$, which is the unique vector $v$ such that $v = a\cdot u$ for some scalar $a\in R$ such that the first non-zero entry of $v$ is the canonical associate in $R$ of the first non-zero entry of $u$ ($v$ is zero if $u$ is zero).

### `Rotate(u, k): ModTupRngElt, RngIntElt -> ModTupRngElt`

Given a vector $u$, return the vector obtained from $u$ by cyclically shifting its components to the right by $k$ coordinate positions.

### `Rotate(~u, k): ModTupRngElt, RngIntElt`

Given a vector $u$, destructively rotate $u$ by $k$ coordinate positions.

### `Parent(w): ModTupRngElt -> ModTupRng`

Given a word $w$ belonging to the code $C$, return the ambient space $V$ of $C$.

### `Example: Codeword Ops (ex-38a7a5)`

Given a code over a finite ring, we explore various operations on its code words.

```magma
> R<w> := GR(4, 4);
> P<x> := PolynomialRing(R);
> g := x + 2*w^3 + 3*w^2 + w + 2;
> C := CyclicCode(3, g);
> C;
(3, 1048576) Cyclic Code over GaloisRing(2, 2, 4)
Generator matrix:
[          1           0     w^2 + w]
[          0           1 w^2 + w + 1]
[          0           0           2]
> u := C.1;
> v := C.2;
> u;
(      1       0 w^2 + w)
> v;
(          0           1 w^2 + w + 1)
> u + v;
(              1               1 2*w^2 + 2*w + 1)
> 2*u;
(          2           0 2*w^2 + 2*w)
> 4*u;
(0 0 0)
> Weight(u);
2
> Support(u);
{ 1, 3 }

```

## Accessing Components of a Codeword

### `u[i]: ModTupRngElt, RngIntElt -> RngElt`

Given a codeword $u$ belonging to the code $C$ defined over the ring $R$, return the $i$-th component of $u$ (as an element of $R$).

### `u[i] := x;`

Given an element $u$ belonging to a subcode $C$ of the full $R$-space $V = R^n$, a positive integer $i$, $1 \leq i\leq n$, and an element $x$ of $R$, this function returns a vector in $V$ which is $u$ with its $i$-th component redefined to be $x$.