libwireless and wireless-python

Added 2013-07-03: libwireless Class documentation, and “Code documentation” section below.

The wireless package contains components for physical- and link-layer simulation of wireless systems, with an emphasis on error correction codes. It was developed as part of spinal code research. Components include:

  • Error correcting codes: spinal codes, raptor, LT, LDPC, strider, turbo.
  • Mappers/Demappers: linear mapping, gray mapping.
  • Channels: AWGN, BSC, MIMO, model of Rayleigh channel.
  • Packet generators: random, random+CRC.
  • Statistics collection: BER (Bit Error Rate), PER (Packet Error Rate).
  • Simulation loop ready for parallel execution, supports rateless codes.
  • Efficient database (based on Berkeley DB) to collect experiment results.

Package dependencies

The package has the following dependencies: SWIG, git, python header files, GNU autotools, libtool, a C++ compiler (e.g., g++), Boost (for strider linear algebra), numpy, and IT++. On Ubuntu 12.04 these can be installed via:

sudo apt-get install swig git python-dev autoconf libtool g++ libboost-dev python-numpy-dev libitpp-dev

Note that on Ubuntu, IT++ is in the universe software repository, so they might require enabling universe repositories. Note that SWIG version 2.0.7 and up are required. Earlier versions have bugs that prevent swig from successfully compiling the binding code. If downloading latest swig source code, note that libpcre is required, e.g.:

sudo apt-get install libpcre3-dev

Obtaining the code

The code is hosted on github: To get a copy:

git clone git://


Enter the directory

cd wireless

Deploy the autotools build system

autoreconf --install

Configure the package. The build requires CPPFLAGS with the location of IT++ include files (in Ubuntu 12.04 for example, /usr/include). To separate build objects from the source tree, the package is configured from within a different directory (called release, below). The package could be installed to the default system paths (by omitting –prefix), but the example below installs to the user’s home directory.

mkdir release cd release CPPFLAGS="-I/usr/include -DNDEBUG" CXXFLAGS="-O3" ../configure --prefix=$HOME -C

Or, make a debug release

mkdir debug cd debug CPPFLAGS="-I/usr/include -DDEBUG" CXXFLAGS="-O1 -g" ../configure --prefix=$HOME -C

Make the package and install:

make -j8 make -j8 install

Setting up the environment

In case the library was installed into a custom directory (like the user’s home directory), the following paths enable the package to be found.


By adding these to ~/.bashrc or the like, these paths can be configured automatically.

Checking installation

The sanity test runs simulation with many of the package’s components:

    python     >>> import wireless.simulator.SanityTest

Code documentation

See the code documentation online, organized by the function of components. The following list is organized by the sequence of operations to simulate a packet:

  • Packet generators produce test messages
  • A link layer protocol tells the simulator how many symbols to transmit
  • Error correction codes encode the message into integers
  • Mapper transform the integers to symbols. Symbols can be represented as complex numbers, floating point numbers, or fixed point numbers.
  • Channels add noise to symbols and simulate fading.
  • (optional) A demapper takes in noisy symbols and infers the likelihood of individual mapped bits
  • A decoder infers the original message. The decoder can be a subclass of ILLRDecoder (if its input is likelihoods) or IDecoder (if its input is raw symbols).
  • A detector decides whether the decode was successful. On decode failure, the link layer protocol can decide to transmit more symbols and try decoding again.
  • Statistics objects collect information about the decode: whether it succeeded, how many bit errors it had, etc.
  • The Simulator class orchestrates packet simulation from start to end. Factories make different components, to make the simulator modular.

These might also help:

  • The file python/simulator/ contains multiple experiment specifications.
  • For spinal codes, a python implementation (without puncturing) is in python/codes/spinal/reference. The file test/codes/spinal/ doesn’t work out of the box, but contains the basic recipe to make spinal encoders/decoders (to complement information in

More Information

For more information, please leave a comment or contact the author (yonch at mit dot edu). This guide will be expanded according to user requests as time allows. — Jonathan


  1. Hi,

    I followed your instructions to install wireless package but I’m getting the following error:
    make[3]: Entering directory `/home/zhouwei/project/wirelesstool/wireless/release/bindings/itpp’
    /home/zhouwei/developer/swigtool/bin/swig -c++ -python -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o base_sparse.cpp ../../../bindings/itpp/base_sparse.i
    /home/zhouwei/developer/swigtool/bin/swig -c++ -python -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o base_vec.cpp ../../../bindings/itpp/base_vec.i
    /home/zhouwei/developer/swigtool/bin/swig -c++ -python -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o ldpc.cpp ../../../bindings/itpp/ldpc.i
    /home/zhouwei/developer/swigtool/bin/swig -c++ -python -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o llr.cpp ../../../bindings/itpp/llr.i
    /home/zhouwei/developer/swigtool/bin/swig -c++ -python -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o modulator.cpp ../../../bindings/itpp/modulator.i
    ../../../bindings/itpp/base_vec.i:36: Error: Unable to find ‘itpp/base/binary.h’
    ../../../bindings/itpp/base_sparse.i:135: Error: Unable to find ‘itpp/base/gf2mat.h’
    Do you have any idea how to solve this?
    I’m running Ubuntu12.04 – x86_64


    • Hi,
      I got the same error and solved it by adjusting the CPPFLAGS include path (cf. installation instructions) to -I/usr/local/include (inserted the local), because IT++ is installed there:
      mkdir release cd release CPPFLAGS="-I/usr/local/include -DNDEBUG" CXXFLAGS="-O3" ../configure --prefix=$HOME -C

  2. Dear Jonathan,

    The wireless tool is awesome, and thank you for open source, it will be a big help on my research.

    There is a question, what is the difference between python spinal code and c++ spinal code, did they achieve the same function?

    Thank you!

    • Yes, the python and C++ implementations compute the same code. The C++ code has faster runtime but more is involved.

  3. While computing the branch cost of spinal codes,is there a collision between the branches who share the same spine value?I mean two or more output symbols among the 2^k may be the same.

    • Collision is when spine values are the same, i.e., two codewords have the same s_i, which is 2^\nu bits.

      If two different spine values output the same symbol (k bits long), then the decoder receives no information from that symbol to distinguish between these two specific branches. However subsequent symbols are unlikely to be the same, so with more output symbols the decoder will be able to distinguish between the branches.

  4. hello,yonch:
    When I run the command “make -j8″,it will report the error that” Making all in python
    make[2]: 正在进入目录 `/home/lian/wireless/debug/python’
    make[2]: *** 没有规则可以创建目标“all”。 停止。”

    Do you have any idea how to solve this?

    I’m running Ubuntu14.04 – 64


  5. Hi, I followed the installation instructions word by word (IT++ cloned from git/master, libwireless from git/master). When calling make I obtain the following error:
    make[3]: entering „/home/aex1lab/src/libwireless-git/build_release/bindings/itpp“
    /usr/bin/swig -c++ -python -I/usr/local/include -DNDEBUG -I/usr/include/python2.7 -I../../../include -I../../../bindings/itpp -I../../../bindings/itpp/.. -DHAVE_CONFIG_H -o base_sparse.cpp ../../../bindings/itpp/base_sparse.i
    /usr/local/include/itpp/base/binary.h:162: Error: Syntax error – possibly a missing semicolon.

    The corresponding line 162 is:
    ITPP_EXPORT std::ostream &operator<<(std::ostream &output, const bin &inbin);

    Any ideas?

    • Hi, I found the answer by myself: Some %includes where missing.
      1) in file bindings/itpp/binary.i replace


      and in file bindings/itpp/llr.i replace



      • Sorry code problem:
        in file `bindings/itpp/binary.i` replace
        %include <itpp/base/binary.h>

        %include <itpp/itexports.h>
        %include <itpp/base/itassert.h>
        %include <itpp/base/binary.h>

        and in file `bindings/itpp/llr.i` replace

        %include <itpp/comm/llr.h>


        %include <base_vec.i>
        %include <itpp/comm/llr.h>

  6. Hi,

    I’m getting the same error as Wei Zhou: “Unable to find itpp/base/binary.h” etc.

    I’m using Ubuntu 12.04 and have followed the instructions as provided. I do not have to adjust the CPPFLAGS include path as mentioned by Stephan as the header files are located under /usr/include as originally described.

    Any help would be much appreciated.


Leave a Reply

Your email address will not be published. Required fields are marked *