komm.TabooCode

Taboo code. It is an integer code with domain the positive integers. Let $M \geq 1$ be the base. The codeword for an integer $n$ is a sequence of blocks, each one a truncated binary codeword with cardinality $M + 1$: the blocks of the digits of $n - 1$ in bijective base $M$, which range from $1$ to $M$, most significant first, followed by the block of $0$, called the taboo.

This is a variation of the block taboo codes of SM10, Sec. 3.16, which have blocks of $b$ bits (that is, $M = 2^b - 1$) and do not use the taboo alone as a codeword. Here, the taboo alone is the codeword for $n = 1$, which makes the code complete; the codewords for $n \geq 2$ are those of SM10, in the same order. The codes $C_3$, $C_7$, and $C_{15}$ of MacK03, Ch. 7 are similar, but write $n$ in the usual base $M$, without leading zeros, and are therefore not complete.

The table below shows the codewords for the first integers, with a space between the blocks.

$n$	$M = 1$	$M = 2$	$M = 3$	$M = 4$
$1$	0	0	00	00
$2$	1 0	10 0	01 00	01 00
$3$	1 1 0	11 0	10 00	10 00
$4$	1 1 1 0	10 10 0	11 00	110 00
$5$	1 1 1 1 0	10 11 0	01 01 00	111 00
$6$	1 1 1 1 1 0	11 10 0	01 10 00	01 01 00
$7$	1 1 1 1 1 1 0	11 11 0	01 11 00	01 10 00
$8$	1 1 1 1 1 1 1 0	10 10 10 0	10 01 00	01 110 00

Notes

• For $M = 1$ it reduces to the unary code with stop bit $0$.
• For $M = 2$ it has the same codeword lengths as the Elias gamma code.
• The escape code uses the same blocks, but reserves the block of $M$ to extend the codeword, instead of the block of $0$ to end it.

Parameters:

• base (int) –

  The base $M$. Must satisfy $M \geq 1$.

encode_single()

Encodes a single integer into its codeword.

Parameters:

• integer (SupportsIndex) –

  The integer to be encoded. Must be in the domain of the code.

Returns:

• codeword (Word) –

  The codeword of the integer. It is a tuple of bits.

Examples:

>>> code = komm.TabooCode(3)
>>> code.encode_single(4)
(1, 1, 0, 0)

decode_single()

Decodes a single codeword from a bit iterator. This method consumes exactly the bits of one codeword, leaving the iterator at the boundary with the next one; any remaining bits are left untouched.

Parameters:

• bits (Iterator[SupportsIndex]) –

  An iterator of bits starting with a complete codeword. It must be an iterator (as returned by iter), not a general iterable, since advancing it is part of the contract.

Returns:

• integer (int) –

  The decoded integer.

Notes

A ValueError is raised if the iterator is exhausted mid-codeword or if an invalid bit is found.

Examples:

>>> code = komm.TabooCode(3)
>>> bits = iter([1, 1, 0, 0, 0, 0])
>>> code.decode_single(bits)
4
>>> list(bits)  # Iterator is left at codeword boundary
[0, 0]

length()

Returns the codeword length $\ell(n)$ for a given integer $n$ in the domain of the code.

Examples:

>>> code = komm.TabooCode(3)
>>> code.length(4)
4

encode()

Encodes a sequence of integers.

Parameters:

• input (ArrayLike) –

  The sequence of integers to be encoded. Must be a 1D-array of positive integers.

Returns:

• output (Array1D[integer]) –

  The concatenation of the codewords. It is a 1D-array of bits.

Examples:

>>> code = komm.TabooCode(3)
>>> code.encode([4, 1, 3])
array([1, 1, 0, 0, 0, 0, 1, 0, 0, 0])

decode()

Decodes a sequence of bits.

Parameters:

• input (ArrayLike) –

  The sequence of bits to be decoded. Must be a 1D-array of bits. Also, the sequence must be a concatenation of codewords (i.e., the output of the encode method).

Returns:

• output (Array1D[integer]) –

  The sequence of decoded integers. It is a 1D-array of positive integers.

Examples:

>>> code = komm.TabooCode(3)
>>> code.decode([1, 1, 0, 0, 0, 0, 1, 0, 0, 0])
array([4, 1, 3])