Python bindings

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - Samples - Models - Education - Contributed Code - Papers

Overview

The goal of Python bindings for NS-3 are two fold:

1. Allow the programmer to write complete simulation scripts in Python;
2. Prototype new models (e.g. routing protocols).

For the time being, the primary focus of the bindings is the first goal, but the second goal will eventually be supported as well. Python bindings for NS-3 are being developed using a new tool called PyBindGen.

The process by which Python bindings are handled is the following:

1. Periodically a developer uses a GCC-XML based API scanning script, which saves the scanned API definition as bindings/python/ns3_module_*.py files. These files are kept under version control in the main NS-3 repository;
2. Other developers clone the repository and use the already scanned API definitions;
3. When configuring NS-3, pybindgen will be automatically downloaded if not already installed. Released NS-3 tarballs will ship a copy of pybindgen.

Build instructions

Just make sure Python development headers are installed (e.g., in debian/ubuntu: sudo apt-get install python-dev), then waf configure and waf build ns-3 as usual. If you are building a ns-3 repository version (rather than official release), you will also need the program bazaar in order to automatically donwload pybindgen (e.g., in debian/ubuntu: sudo apt-get install bzr).

If something goes wrong with compiling Python bindings and you just want to ignore them and move on with C++, you can disable Python with:

./waf --python-disable

Testing

"./waf check" now also runs some Python unit tests, at the end.

To run example programs:

./waf --shell
python examples/mixed-wireless.py

or:

./waf --pyrun examples/mixed-wireless.py

Instructions for wrapping new or changed APIs

The manual way

You will need to read some PyBindGen documentation.

API of existing module changed or added

So you have been changing existing NS-3 APIs and Python bindings no longer compile? Do not despair, you can manually edit the bindings API definitions to make them reflect the new changed API.

The API definitions are organized as follows. For each ns-3 module <name>, the file bindings/python/ns3_module_<name>.py describes its API. Each of those files have 3 toplevel functions:

1. def register_types(module): this function takes care of registering new types (e.g. C++ classes, enums) that are defined in tha module;
2. def register_methods(module): this function calls, for each class <name>, another function register_methods_Ns3<name>(module). These latter functions add method definitions for each class;
3. def register_functions(module): this function registers ns-3 functions that belong to that module.

New module

If you are adding a new module, Python bindings will continue to compile but will not cover the new module. To cover a new module, you have to create a bindings/python/ns3_module_<name>.py file, similar to the what is described in the previous section, and register it in the variable LOCAL_MODULES in bindings/python/ns3modulegen.py

The semi-automatic way

It is possible to use GCC-XML and PyGccXml to scan API definitions automatically. The API scanner is not perfect, but it gets most of the job done.

First you need to install the necessary tools:

1. Get CMake (can either build from source or download binaries for windows, linux i386);
2. Get GCC-XML (must download from CVS). Instructions are to be found here. Not, as with all CVS versions, stability may vary. This CVS snapshot is known to work: cvs up -D "2008-04-20".
3. Download and install pygccxml, version 0.9.5; (To install: python setup.py install --prefix /usr/local);

Next step, run "./waf" just for a while to make sure the 'everything.h' file is generated (this file will be scanned). You can interrupt the build as soon as all 'blue' tasks are finished and compilation starts.

Finally, run "./waf --python-scan". If all goes well, the files in bindings/python/* should have been updated with new API definitions. Now you can build ns-3 as usual, and new Python bindings are compiled.

Caveats

Python bindings for NS-3 is a work in progress, and some limitations are know by developers. Some of these limitations (not all) are listed here.

Conversion Constructors

Conversion constructors are not fully supported yet by PyBindGen, and they always act as explicit constructors when translating an API into Python. For example, in C++ you can do this:

Ipv4AddressHelper ipAddrs;
ipAddrs.SetBase ("192.168.0.0", "255.255.255.0");
ipAddrs.Assign (backboneDevices);

In Python, for the time being you have to do:

ipAddrs = ns3.Ipv4AddressHelper()
ipAddrs.SetBase(ns3.Ipv4Address("192.168.0.0"), ns3.Ipv4Mask("255.255.255.0"))
ipAddrs.Assign(backboneDevices)

CommandLine

CommandLine::AddValue is template based and does not work in Python.

Tracing

Callback based tracing is not yet properly supported for Python, as new NS-3 API needs to be provided for this to be supported. Bug #127 for details.

Cygwin limitation

Python bindings do not work on Cygwin. This is due to a gccxml bug: http://www.gccxml.org/Bug/view.php?id=7572

You might get away with it by re-scanning API definitions from within the cygwin environment (./waf --python-scan). However the most likely solution will probably have to be that we disable python bindings in CygWin.

If you really care about Python bindings on Windows, try building with mingw and native python instead. Or else, to build without python bindings, disable python bindings in the configuration stage:

 ./waf configure --python-disable