Dependencies

This page gives information about the external packages that are required or useful for Topographica; installation of these packages is described on the main Downloads page.

Required External Packages

Topographica makes extensive use of the following external packages that must be installed to use Topographica.

Python

Topographica command and scripting language (essential!). Topographica is written in Python, so anything that Python can do is also valid for Topographica. For a good basic introduction, check out the Python tutorial. Those already familiar with programming might find Python for Programmers or Idiomatic Python useful.

NumPy

Topographica makes heavy use of NumPy arrays and math functions; these provide high-level operations for dealing with matrix data. The interface and options are similar to Matlab and other high-level array languages. These operations are generally much higher performance than explicitly manipulating each matrix element, as well as being simpler, and so they should be used whenever possible. See the NumPy documentation list (especially the Guide to Numpy, NumPy Example List, and NumPy Functions by Category) to learn about the full range of available functions.

PIL

Topographica uses the Python Imaging Library for reading and writing bitmap images of various types. PIL also provides a variety of image processing and graphics routines, which are available for use in Topographica components and scripts.

Required IOAM Packages

Some of the modules developed for Topographica are maintained and released separately, so that they can be used in other projects, but are also required for Topographica:

Param and ParamTk

General-purpose support for full-featured Parameters, extending Python attributes to have documentation, bounds, types, etc. The Tk interface ParamTk is optional, and only used for Topographica’s optional tkgui interface.

ImaGen

General-purpose support for generating 0D (scalar), 1D (vector), and 2D (image) patterns, starting from mathematical functions, geometric shapes, random distributions, images, etc. Useful for any program that uses such patterns, e.g. any sensory modelling software, not just Topographica.

Again, installation of these packages is described on the main Downloads page.

Typical External Packages

Most Topographica users will also want these additional packages:

MatPlotLib

Matplotlib is used for generating 1D (line) and 2D (plane) plots, such as topographic grid plots. It provides PyLab, a very general Matlab-like interface for creating plots of any quantities one might wish to visualize, including any array or vector in the program.

IPython

IPython provides Topographica with an enhanced Python shell, allowing efficient interactive work. The IPython tutorial explains the most immediately useful features; see IPython’s documentation for more detailed information.

Weave

Topographica uses weave (shipped with SciPy) to allow snippets of C or C++ code to be included within Python functions, usually for a specific speed optimization. This functionality is available for any user-defined library function, for cases when speed is crucial.

gmpy

A C-coded Python extension module that wraps the GMP library to provide Python with fast multiprecision arithmetic. Topographica uses gmpy’s rational type as its default simulation time, to avoid precision issues inherent in floating-point arithmetic. Since gmpy requires GMP to be built, Topographica will fall back to a slower, purely Python implementation of fixed-point numbers (fixedpoint) if gmpy is not available.

Lancet

Support for running large numbers of simulation jobs and collating the results to produce figures and analyses, especially for publication.

Optional External Packages

A number of other packages are also useful with Topographica, but are not necessarily required. Packages listed below are therefore not part of the default Topographica installation, but many are in use by Topographica users and/or developers.

In most cases, these packages are included in Python distributions such as EPD/Python(x,y), or are available via package managers such as apt-get/MacPorts. Alternatively, the packages are available for easy_install/pip install/standard Python installation via PyPI. Many of these packages can also be installed using the external directory of Topographica; see the github installation instructions. Note that, however you choose to install any of these packages, if your system has more than one copy of Python you must install the package using the same copy of Python that you are using for Topographica.

If you encounter problems using these packages, feel free to ask the Topographica community for help.

SciPy

SciPy includes many, many functions useful in scientific research, such as statistics, linear algebra, integration and differential equation solvers, etc.

mlabwrap

mlabwrap is a high-level Python-to-Matlab bridge, allowing Matlab to look like a normal Python library:

from mlabwrap import mlab  # start a Matlab session
mlab.plot([1,2,3],'-o')

mlabwrap is transitioning to SciKits (see below), but installation can be tricky so we describe it further here. First, check you can run matlab -nodesktop -nosplash successfully, then build from source (e.g. from Topographica’s fat distribution with make -C external mlabwrap, or download and build the source yourself). If the matlab libraries are not in your LD_LIBRARY_PATH, there will be a note during the build telling you to add the libraries to your path. For example:

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/opt/matlab-7.5/bin/glnx86

You can either add that permanently to your path, or add it each time before using mlabwrap.

pyaudiolab

pyaudiolab provides an easy way to read from and write to sound files (it wraps libsndfile). In the fat distribtion, building should be simple: make -C external pyaudiolab.

scikits-image

A collection of algorithms for image processing.

Player/Stage/Gazebo

The Player/Stage/Gazebo project provides interfaces for a large variety of external hardware and simulation software, such as cameras, digitizers, and robots. The Gazebo and Stage simulators that support the Player interface can also be used, as described on the Player site. Note that a connection to Player is provided in topo/misc/robotics.py (last tested with player-2.0.4.tar.bz2 from playerstage.sf.net).

Processing

Because of the “global interpreter lock” it is not possible to do true multiprocessing in Python using the language’s built-in threads. The processing module provides support for multiprocessing using an API similar to that of Python’s threading module. (Although, unlike threads, processes don’t share memory.) The module also provides a number of other useful features including process-safe queues, worker pools, and factories (“managers”) that allow the creation of python objects in other processes that communicate through proxies.

Cython

Cython is a language that is very similar to Python, but supports calling C functions and declaring C types, and will produce and compile C code. Therefore, the performance benefit of C is available from a much simpler language. Because Cython can compile almost any Python code to C, one can start with a component written entirely in Python and then optimize it step by step (by adding types, for example). See the Cython documentation for more information.

Quantities

Quantities allows you to use real-world units in your .ty scripts, such as mm or degrees of visual field, converting them to Topographica’s units.

SciKits

SciKits provide many useful extensions to SciPy, e.g. for machine learning and numerical optimization.

RPy

The language R (a free implementation of the S statistical language) has a nice interface to Python that allows any R function to be called from Python. Nearly any statistical function you might ever need is in R.

Topographica runs on an unmodified version of the Python language, and so it can be used with any other Python package that you install yourself. A good list of potentially useful software is located at SciPy.org.

As above, note that if your system has more than one copy of Python, you must install the package using the same copy of Python that you are using for Topographica.