The lpdec package: Structure and General Utilities¶

The lpdec package is organized as follows:

The main package directory contains several utility classes and functions used across the package
The lpdec.codes subpackage contains implementations of various classes of codes
The lpdec.decoders subpackage contains decoder implementations
The lpdec.database packages is responsible for storing and retrieving simulation results in relational databases.
The lpdec.cli package contains the command-line tools that provide e.g. database browsing or code analysis.

subclasses(base)¶: Return all subclasses of base as dictionary mapping class names to class objects.

exactVersion()¶

Returns the version of the lpdec package.

If this __init__ file is located inside a git repository (identified b a ».git« subdirectory of the parent directory), then the output of git describe --dirty is returned. Otherwise, the value of the above variable __version__ is returned.

Channels¶

class Channel(seed=None, q=2)¶

Bases: lpdec.persistence.JSONDecodable

Abstract parent class for a communication channel; in fact, instances model the combination of modulator and noisy channel. This means that the inputs are unmodulated codewords, while the output consists of zero-based log-likelihood ratio (LLR) values, defined as $\log\frac{ P(y|x=0)}{P(y|x=s)}$ for the non-zero input symbol $s$ and channel observation $y$ .

Channel noise can be generated by calling the Channel object with a codeword as parameter.

Parameters:	seed (int, optional) – Optional initial random seed value for noise generation. q (int, optional) – The arity of the used code. Defaults to 2 for binary codes.
Variables:	snr (float) – A numerical parameter corresponding to the signal-to-noise ratio of the channel. It is not necessarily the “real” SNR, but be chosen such that an increase indicates decreasing error probability. This is used for plots and statistics.

resetSeed()¶: Reset the random seed of the channel to its initial value.

simulate(codeword)¶

Afflict the given input codeword with channel noise.

Parameters:	codeword (numpy array (1-dim)) – The codeword for which the channel transmission is to be simulated.
Returns:	Channel output as double array.
Return type:	numpy array (1-dim)

skip(word, num)¶

Skip a given number of simulated transmissions of a given codeword.

Use this method to resume computations with a given random number seed.

Parameters:	num (int) – Number of transmissions to skip. word – The codeword to use.

signalGenerator(code, **kwargs)¶

Convenience function returning a SignalGenerator for this channel and the given code.

Additional keyword args are passed to the SignalGenerator constructor.

class AWGNC(snr, coderate, q=2, round=None, seed=None)¶

Bases: lpdec.channels.Channel

The additive white Gaussian noise channel with q-PSK modulation.

Parameters:	snr (float) – Signal-to-noise ratio $\frac{E_b}{N_0}$ in dB. coderate (float) – Coding rate (needed to calculate $E_c$ from $E_b$ ). round (int, optional) – Number of decimals to which the resulting LLR values are rounded.

class BSC(p, seed=None)¶

Bases: lpdec.channels.Channel

The binary symmetric channel: Indepentently flips each bit with a fixed probability.

Parameters:	p (float) – Crossover probability ( $0 \leq p \leq \frac 1 2$ )

class SignalGenerator(code, channel, wordSeed=None)¶

Bases: object

An iterator class for generating noisy channel output of transmitted codewords.

Codewords are sent through a channel which adds noise. A random seed may be provided that is used for generating codewords.

The SignalGenerator can be used as an iterator; every call to next() will yield another noisy signal. Afterwards, the attributes codeword and llrOutput are available.

Parameters:	code (`BinaryLinearBlockCode`) – The code to use for generating codewords and deducing block length. channel (`Channel`) – The channel model. wordSeed (int, optional) – Random seed for generating codewords. The default value of `None` uses a random seed, i.e. non-deterministic behavior. The special value `-1` causes the zero codeword to be used instead of random ones.
Variables:	llrOutput (np.ndarray[np.double]) – Log-likelihood vector of channel outputs resulting from the most recent simulation. codeword (np.ndarray[int]) – The codeword used for the most recent simulation.

next()¶: Generate and return the next noisy signal.

skip(num)¶: Skip the next num signals. When resuming a seeded computation, this is much more efficient than calling next() num times for simulation with random codewords, as the generation of random words is not actually performed.

correctObjectiveValue()¶: Returns the objective value (scalar product of llrOutput and codeword) of the codeword that was actually sent.

Matrix Input and Output¶

alistToNumpy(lines)¶

Converts a parity-check matrix in AList format to a 0/1 numpy array. The argument is a list-of-lists corresponding to the lines of the AList format, already parsed to integers if read from a text file.

The AList format is introduced on http://www.inference.phy.cam.ac.uk/mackay/codes/alist.html.

This method supports a “reduced” AList format where lines 3 and 4 (containing column and row weights, respectively) and the row-based information (last part of the Alist file) are omitted.

Example

>>> alistToNumpy([[3,2], [2, 2], [1,1,2], [2,2], [1], [2], [1,2], [1,2,3,4]])
array([[1, 0, 1],
       [0, 1, 1]])

getBinaryMatrix(source)¶

Creates a binary matrix of type np.ndarray from either a file or a two-dimensional python list.

If source is a file path, the file must either contain an explicit representation of the matrix (by means of whitespace-separated ‘0’ and ‘1’ characters) or be in the AList format (see alistToNumpy docstring).

The file may be bzip2’ed, in which case it will be decompressed automatically.

Returns:	Numpy ndarray representation of the given matrix.
Return type:	np.ndarray[dtype=int]

numpyToAlist(matrix)¶: Converts a 2-dimensional 0/1 numpy array into MacKay’s AList format, in form of a list of lists of integers.

numpyToString(array, width=2)¶: Formats a numpy matrix as string, using width columns per entry.

formatMatrix(matrix, format='plain', width=2, filename=None)¶

Converts a matrix to a string in the requested format.

Parameters:	matrix (np.ndarray[int]) – The matrix to be formatted. format ({‘plain’, ‘alist’}, optional) – The output format. `'plain'` (the default) means the “canonical” representation (entries separated by spaces and newlines), while `'alist'` leads to MacKay’s Alist format. width (int, optional) – In `plain` output format, each entry of the matrix will be left-padded with blanks to match the given width. filename (str, optional) – If provided, write formatted matrix string to the given file.
Returns:	String representation of the given matrix.
Return type:	str

numpyToReducedAlist(matrix)¶

Convert the matrix to reduced AList format in form of a list of lists.

The first entry is a pair containing number of columns and rows, respectively. The second entry is an empty list (in MacKay’s Alist format, this contains the max number of entries per column and row, respectively). Then, for each column, a list of nonzero positions follows.

getNonbinaryMatrix(source)¶: Reads a nonbinary matrix (no AList support).

Handling of Binary ( $\mathbb{F}_2$ ) Matrices¶

This module contains linear algebra functions in $GF(q)$ arithmetics, i.e. vector spaces defined over finite fields.

gaussianElimination(__Pyx_memviewslice matrix, __Pyx_memviewslice columns=None, bool diagonalize=True, __Pyx_memviewslice successfulCols=None, int q=2)¶

gaussianElimination(matrix, columns=None, diagonalize=True, successfulCols=None, q=2)

The Gaussian elimination algorithm in $\mathbb F_q$ arithmetics, turning a given matrix into reduced row echelon form by elementary row operations.

Warning

This algorithm operates in-place!

Parameters:	matrix (np.int_t[:,::1]) – The matrix to operate on. columns (np.intp_t[:], optional) – A sequence of column indices, giving the the order in which columns of the matrix are visited. Defaults to `range(matrix.shape[1])`. diagonalize (bool, True) – If `True`, matrix elements above the pivots will be turned to zeros, leading to a diagonal submatrix. Otherwise, the result contains an upper triangular submatrix. successfulCols (np.intp_t[::1], optinonal) – Numpy array in which successfully diagonalized column indices are stored. If supplied, this array will be used for the return value. Otherwise, a new array will be created, resulting in a slight performance drain. q (int, optional) – Field size in which operations should be performed. Defaults to `2`.
Returns:	np.intp_t[ – Indices of successfully diagonalized columns.
Return type:	:1]

inKernel(__Pyx_memviewslice matrix, __Pyx_memviewslice vector, int q=2)¶

inKernel(matrix, vector, q=2)

Return True iff matrix $\times$ vector = 0 in $\mathbb F_q$ .

inv(int a, int q)¶: Computes the multiplicative inverse of a in $\mathbb F_q$ .

orthogonalComplement(matrix, columns=None, q=2)¶: Computes an orthogonal complement (in GF(q)) to the given matrix.

rank(matrix, q=2)¶: Return the rank (in GF(q)) of a matrix.

Various Utilities¶

class Timer¶

Bases: object

Class for time measurement that can be used as a context manager (see example below).

Variables:	startTime (float) – Time (CPU clock time) the timer was started. endTime (float) – Time (CPU clock time) the timer was ended. duration (float) – Duration (in seconds) the timer was running.

Examples

>>> with Timer() as timer:
...     x = sum(range(100000))
>>> cpuTime = timer.duration

utcnow()¶: Returns a timezone-aware datetime object representing the current date and time in UTC.

frange(start, end, step=1)¶: Generalization of the built-in range() function that supports fractional step sizes.

splitRanges(rangesString)¶: Split a string of type ‘1-3 9 12’ into a list of ints [1,2,3,9,12].

machineString()¶: A string identifying the current machine, composed of the host name and platform information.

isStr(arg)¶: Python version-agnostic test whether arg is of a string type (str in python 3, basestring in python 2).