Python bindings

From Nsnam
Revision as of 17:14, 18 February 2009 by GustavoCarneiro (Talk | contribs) (Tracing)

Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - 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 --disable-python

Testing

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

Running programs

waf contains some options that automatically update the python path to find the ns3 module. To run example programs, there are two ways to use waf to take care of this. One is to run a waf shell; e.g.:

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

and the other is to use the --pyrun option to waf:

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

To run a python script under the C debugger:

./waf --shell
gdb --args python 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. Note that, as with all CVS versions, stability may vary. This CVS snapshot is known to work: cvs up -D "2008-07-01".
  3. Download and install pygccxml, version 0.9.5; (To install: python setup.py install --prefix /usr/local);
  4. Run ./waf configure, to let ns-3 detect the python scanning tools. You should see something along these lines; if not, something is wrong:
[...]
Checking for Python module pygccxml                                      : ok  
Checking for pygccxml version                                            : ok 0.9.5 
Checking for program gccxml                                              : ok /usr/local/bin/gccxml 
Checking for gccxml version                                              : ok 0.9.0 
[...]
Python Bindings               : enabled
Python API Scanning Support   : enabled

Now you are ready to scan; 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 does not work in Python. This will be fixed in NS-3.3.

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.

Pcap file writing is supported via the normal API.

Ascii tracing is supported since NS-3.4 via the normal C++ API translated to Python. However, ascii tracing requires the creation of an ostream object to pass into the ascii tracing methods. In Python, the C++ std::ofstream has been minimally wrapped to allow this. For example:

   ascii = ns3.ofstream("wifi-ap.tr") # create the file
   ns3.YansWifiPhyHelper.EnableAsciiAll(ascii)
   ns3.Simulator.Run()
   ns3.Simulator.Destroy()
   ascii.close() # close the file

There is one caveat: you must not allow the file object to be garbage collected while NS-3 is still using it. That means that the 'ascii' variable above must not be allowed to go out of scope or else the program will crash.

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 --disable-python