komm.Labeling

General binary labeling. It is defined by a bijective mapping from $[0:2^m)$ to $\mathbb{B}^m$ or, equivalently, by an ordered set $\{ \mathbf{q}_i : i \in [0:2^m) \}$ of $2^m$ distinct binary vectors in $\mathbb{B}^m$. In this class, a labeling is represented by a matrix $\mathbf{Q} \in \mathbb{B}^{2^m \times m}$, where the $i$-th row of $\mathbf{Q}$ corresponds to the binary vector $\mathbf{q}_i$. For more details, see SA15, Sec. 2.5.2.

Parameters:

• matrix (ArrayLike) –

  The labeling matrix $\mathbf{Q}$. Must be a $2^m \times m$ binary matrix whose rows are all distinct.

matrix NDArray[integer] property

The labeling matrix $\mathbf{Q}$.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.matrix
array([[1, 0],
       [1, 1],
       [0, 1],
       [0, 0]])

num_bits int property

The number $m$ of bits per index of the labeling.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.num_bits
2

cardinality int property

The cardinality $2^m$ of the labeling.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.cardinality
4

inverse_mapping dict[tuple[int, ...], int] property

The inverse mapping of the labeling. It is a dictionary that maps each binary tuple to the corresponding index.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.inverse_mapping
{(1, 0): 0, (1, 1): 1, (0, 1): 2, (0, 0): 3}

indices_to_bits()

Returns the binary representation of the given indices.

Parameters:

• indices (ArrayLike) –

  The indices to be converted to bits. Must be an array of integers in $[0:2^m)$.

Returns:

• bits (NDArray[integer]) –

  The binary representations of the given indices. Has the same shape as indices, but with the last dimension expanded by a factor of $m$.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.indices_to_bits([2, 0])
array([0, 1, 1, 0])
>>> labeling.indices_to_bits([[2, 0], [3, 3]])
array([[0, 1, 1, 0],
       [0, 0, 0, 0]])

bits_to_indices()

Returns the indices corresponding to a given sequence of bits.

Parameters:

• bits (ArrayLike) –

  The bits to be converted to indices. Must be an array with elements in $\mathbb{B}$ whose last dimension is a multiple $m$.

Returns:

• indices (NDArray[integer]) –

  The indices corresponding to the given bits. Has the same shape as bits, but with the last dimension contracted by a factor of $m$.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.bits_to_indices([0, 1, 1, 0])
array([2, 0])
>>> labeling.bits_to_indices([[0, 1, 1, 0], [0, 0, 0, 0]])
array([[2, 0],
       [3, 3]])

marginalize()

Marginalize metrics over the bits of the labeling. The metrics may represent likelihoods or probabilities, for example. The marginalization is done by computing the L-values of the bits, which are defined as $$ L(\mathtt{b}_i) = \log \frac{\Pr[\mathtt{b}_i = 0]}{\Pr[\mathtt{b}_i = 1]}. $$

Parameters:

• metrics (ArrayLike) –

  The metrics for each index of the labeling. Must be an array whose last dimension is a multiple of $2^m$.

Returns:

• lvalues (NDArray[floating]) –

  The marginalized metrics over the bits of the labeling. Has the same shape as metrics, but with the last dimension changed by a factor of $m / 2^m$.

Examples:

>>> labeling = komm.Labeling([[1, 0], [1, 1], [0, 1], [0, 0]])
>>> labeling.marginalize([0.1, 0.2, 0.3, 0.4, 0.25, 0.25, 0.25, 0.25])
array([0.84729786, 0.        , 0.        , 0.        ])
>>> labeling.marginalize([[0.1, 0.2, 0.3, 0.4], [0.25, 0.25, 0.25, 0.25]])
array([[0.84729786, 0.        ],
       [0.        , 0.        ]])