Pymote documentation¶

This document refers to the Pymote version 0.2.2

Date:	November 25, 2015

Installation¶

This document assumes you are familiar with using command prompt or shell. It should outline the necessary steps to install software needed for using Pymote.

Requirements¶

If you don’t have all required packages already installed and/or want them installed in an isolated environment (see note below) please follow the instructions for your OS in the following sections.

Note

Since there can be only one version of any package installed systemwide in some cases this can result in situation where two programs need different versions of the same package. This is resolved by using isolated virtual environments.

Virtual environments live in a separate directories and they are independent form systemwide Python installation.

Alternatively, if none of the above is your concern, although not recommended, all required packages can be installed systemwide using their respective instructions for appropriate OS and then Pymote can be installed by using:

> pip install pymote

Windows¶

Windows version can be installed in an isolated environment very easy:

Install WinPython 2.7. WinPython has included python and all required packages inside simple exe installer and they are all installed one relocatable [*] directory.

[*]
After directory reloacation change links in headers of Scripts/ipymote and Scripts/pymote-simgui and paths in Lib/site-packages/easy_install.pth and Lib/site-packages/Pymote.egg-link.
Run WinPython Command Prompt.exe located in WinPython installation dir and install latest official version of Pymote with pip install pymote

Note

For latest development version instead of pip intall pymote use pip install -e git+https://github.com/darbula/pymote.git#egg=Pymote and for upgrade after git pull use run python setup.py develop inside pymote dir.

For starting Pymote interactive console just run ipymote from the WinPython Command Prompt, and for simulation GUI run pymote-simgui. For more details refer to Starting Pymote.

Alternatively, installation can be done using Windows virtualenv installation but it is much more involved and not recommended.

Linux (Ubuntu)¶

Python 2.7 should already be installed on all new releases of Linux.

Install packages required for getting and compiling the source:

$ sudo apt-get install git libatlas-dev libpng12-dev libfreetype6 libfreetype6-dev g++ libzmq-dev liblapack-dev gfortran python-dev build-essential

Virtualenv¶

Install pip and virtualenv:

$ sudo apt-get install python-pip python-virtualenv

Create virtual environment:

$ virtualenv pymote_env --system-site-packages

Warning

If you want to avoid using –system-site-packages then PySide package has to be installed in virtualenv which is slightly involved or time and disk-space consuming. Both procedures are described below in PySide section.

Activate virtual environment:

$ source pymote_env/bin/activate

Required packages¶

Install required python packages into virtual environment:

(pymote_env)$ pip install numpy scipy ipython matplotlib networkx pypng distribute

IPython notebook¶

Optionally for IPython notebook install these:

(pymote_env)$ pip install tornado pyzmq pygments jinja2

PySide¶

Installing PySide into virtual environment can take some skill or time and disk space. To avoid this, it can be installed systemwide (if –system-site-packages option is used when creating virtualenv, as noted above) using these instructions or simply like this:

$ sudo add-apt-repository ppa:pyside
$ sudo apt-get update
$ sudo apt-get install python-pyside

If you really want to install PySide into virtual environment quick option is to follow this solution or simmilar and even better solution

More time consuming option is to use pip. In this case you’ll have to install packages needed for compilation using following commands:

$ sudo apt-get install cmake qt4-qmake qt-sdk
(pymote_env)$ pip install pyside

Pymote¶

Finally, in order to download and install Pymote and all other required packages there are two aviliable options, use one of them:

Stable: for latest stable version use package from PyPI:
```
(pymote_env)> pip install pymote
```
Development: to install latest development version of the Pymote use source from github repo:
```
(pymote_env)> pip install -e git+https://github.com/darbula/pymote.git#egg=Pymote
```

Starting Pymote¶

Before starting, make sure that virtual environment is activated and run ipymote for interactive console or pymote-simgui for simulation GUI. For more details refer to Starting Pymote.

Starting Pymote¶

Pymote features interactive console based on IPython and simulation GUI.

Pymote console and GUI

Interactive console (IPython)¶

To use Pymote from the interactive console (IPython) start provided program ipymote with previously activated virtual environment:

> ipymote

Note

If virtualenv is used make sure that virtual environment is activated (linux, windows) and if WinPython is used then run ipymote from WinPython Command Prompt.

Pymote can also be started by starting IPython directly and using dedicated pymote profile:

> ipython --profile=pymote

Note

Pymote profile files should be present inside pymote_env/.ipython/profile_pymote/ipython_config.py or ~/.ipython/profile_pymote/ipython_config.py file created during Pymote installation.

Simulation GUI¶

Pymote features simulation GUI which can be started as standalone application using pymote-simgui (in Windows pymote-simgui.exe).

Note

If pymote is installed in virtual environment then pymote-simgui starts inside this environment. When network pickle is opened in simulator all algorithms this network is referencing must be importable from virtual environment. The easy and proper way to ensure that the algorithms are importable is to use bootstrap algorithms package that can be found in pymote-algorithms-bootstrap and follow the instructions found there.

Simulation GUI running from the interactive console¶

Very convenient way of starting and working with the GUI is from the interactive console by running simulationgui.py like this:

In [1]: %run path/to/pymote/gui/simulationgui.py

The gui event loop is separated from the console. Simulation window can be accessed by using simgui and network in the simulator window by using simgui.net so all simulation objects (network, nodes, messages...) are fully inspectable and usable via console.

Tutorials¶

Tutorials assume that the Pymote and all required packages are installed. If not, please refer to the Installation section of this documentation.

Hello distributed world¶

This tutorial demonstrates a distributed version of the classic Hello world example. Tutorial is currently available in form of IPython notebook which can be viewed and downloaded.

Reference¶

Release: 0.2.2

Date: November 25, 2015

Sensors¶

Real world sensors¶

`AoASensor`
`DistSensor`

Knowledge sensors¶

`NeighborsSensor`
`TruePosSensor`

Composite sensor¶

Network Generator¶

Implementation of different methods for automated network creation. It defines parameters (conditions) that generated network must satisfy.

Methods¶

Default procedure¶

For any generator method network attributes take default priorities which are defined like this:

first network is created in given environment with n_count number of nodes and comm_range communication range
if connected is True it must be satisfied, if not satisfied initially:
- gradually increase number of nodes up to n_max
- if comm_range is None gradually increase nodes commRange
- if still not connected raise an exception
if degree condition is defined and current network degree is
- lower - repeat measures from the last step to increase current network degree
- higher one degree or more - try countermeasures i.e. decrease number of nodes and commRange but without influencing other defined and already satisfied parameters (connected)

Pymote configuration¶

Pymote initial configuration is defined by its global settings

Implementation of different methods for automated network creation.

Configuration module¶

Global settings¶

Below is list of current Pymote global settings.

Developer Guide¶

Distributing to PyPI¶

http://docs.python.org/2/distutils/index.html#distutils-index https://python-packaging-user-guide.readthedocs.org/en/latest/current/

Windows¶

Install required packages:

> pip install twine wheel

Create C:\Users\<user>\.pypirc file:

[distutils]
index-servers =
    pypi

[pypi]
repository: http://pypi.python.org/pypi
username: <username>
password: <password>

[server-login]
repository: http://pypi.python.org/pypi
username: <username>
password: <password>

Issue these commands:

> setx HOME C:\Users\<user>
> python setup.py sdist bdist_wheel
> twine upload dist/*

Running tests¶

To execute tests install nose pip install nose and run it inside pymote directory. All tests should be found recursively scanning directories. To run all tests run this from root pymote directory:

nosetests -v

To run selected test module:

nosetests -v pymote.tests.test_algorithm

Tests coverage¶

For tests coverage install Coverage package and run it:

pip install coverage
coverage run --source=pymote setup.py nosetests

Configuration file is in .coveragerc.

Make report in console or html:

coverage report -m
coverage html

For integration with coveralls refer to coverall readme.

Writing documentation¶

This section describes certain not obvious details in writing documentation for Pymote in sphinx.

Intersphinx¶

To auto-reference external document in with intersphinx:

set intersphinx_mapping in conf.py:

intersphinx_mapping = {
    'python': ('http://docs.python.org/', None),
    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
    'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
}

reference in docs with `:py:<type>:`<ref>` i.e. :py:class:`numpy.poly1d`. For finding reference manually read on.

Finding reference¶

If <type> is not explicitly known it can be found out from objects.inv files found in URLs in intersphinx_mapping above.

To get and decode objects.inv for numpy:

$ wget http://docs.scipy.org/doc/numpy/
$ ipython

In python:

import zlib
with open("objects.inv","r") as f:
    inv_lines = f.readlines()
lista = zlib.decompress(''.join(inv_lines[4:])).split('\n')
with open('objects_numpy.inv','w') as f:
    for line in lista:
        f.write(line+'\n')

To find reference for numpy.poly1d serach for it in decoded file objects_numpy.inv.

The line should include word class

In documentation include :py:class:`numpy.poly1d`

For scipy.stats.norm:

find scipy.stats.norm -> data -> :py:data:`scipy.stats.norm`

Readthedocs.org¶

In order for readthedocs.org to make documentation it needs to have certain packages accessible.

On readthedocs.org admin page check option Use virtualenv And Use system packages and in Requirements file put the name to the requirements file in repo (i.e. requirements.txt).
Make readthedocs.py module and put it in docs folder with Mock class found here

In documentation conf.py put the following lines to import mock class for certain modules that are not present in virtual environment.

if os.environ.get('READTHEDOCS', None) == 'True':
    sys.path.insert(0,'.')
    from readthedocs import *
    sys.path.pop(0)

Pymote documentation¶

Installation¶

Requirements¶

Windows¶

Linux (Ubuntu)¶

Virtualenv¶

Required packages¶

IPython notebook¶

PySide¶

Pymote¶

Starting Pymote¶

Starting Pymote¶

Interactive console (IPython)¶

Simulation GUI¶

Simulation GUI running from the interactive console¶

Tutorials¶

Hello distributed world¶

Reference¶

Sensors¶

Real world sensors¶

Knowledge sensors¶

Composite sensor¶

Network Generator¶

Methods¶

Default procedure¶

Pymote configuration¶

Configuration module¶

Global settings¶

Developer Guide¶

Distributing to PyPI¶

Windows¶

Running tests¶

Tests coverage¶

Writing documentation¶

Intersphinx¶

Finding reference¶

Readthedocs.org¶

Indices and tables¶

Table Of Contents