Reference Manual
Home News Downloads Tutorials User Manual Reference Manual Developer Manual Forums Team Members Future Work FAQ Links This reference manual contains detailed documentation of each component making up Topographica, assuming that the user is already familiar with basic Topographica usage. See the User Manual and Tutorials for such an introduction. Note that the documentation of these components is gradually being improved, and not every component is properly documented yet. Moreover, the documentation is often much more verbose than necessary, because many little-used yet often duplicated methods are included for each class. Still, the reference for a given component does provide a comprehensive listing of all attributes and methods, inherited or otherwise, which is difficult to obtain from the source code. Core packages
Topographica is designed as a collection of packages from which elements can be selected to model specific neural systems. For more information, see the individual subpackages of the topo package. The most essential of these are:
The base directory contains the most fundamental Topographica classes, implementing basic functionality such as Sheets (arrays of units), Projections (large groups of connections between Sheets), ConnectionFields (spatially localized groups of connections to one unit), and the event-driven Simulation. It relies heavily on the generic support for Parameters (user-controllable attributes) from the param directory. Together these files are independent of the rest of the files in topo/, and act as the primary programming interface on which Topographica is built. The rest of the directories add components used in specific models, or add graphical interfaces.
- base
- Core Topographica-specific functions and classes
- param
- Support for objects with user-controllable attributes
- plotting
- Visualization functions and classes
- analysis
- Analysis functions and classes (besides plotting)
- misc
- Miscellaneous independent utility functions and classes
- tkgui
- Tk-based graphical user interface (GUI)
Library
The Topographica primitives library consists of an extensible family of classes that can be used with the above functions and classes:
- pattern
- PatternGenerator classes: 2D input or weight patterns
- numbergen
- NumberGenerator classes: scalars drawn from some distribution
- sheet
- Sheet classes: 2D arrays of processing units
- projection
- Projection classes: connections between Sheets
- ep
- EventProcessor classes: other simulation objects
- transferfn
- Output functions: apply to matrices to do e.g. normalization or squashing
- responsefn
- Calculate the response of a unit or a Projection
- learningfn
- Adjust weights for a unit or a Projection
- coordmapper
- Determine mapping from one Projection to another
- command
- High-level user commands
All of the library components are optional, in the sense that they can be deleted or ignored or replaced with custom versions without affecting the code in any of the main packages. (Of course, any specific model that depends on the component would not be able to function without it.)
Each of the library directories can be extended with new classes of the appropriate type, just by adding a new .py file to that directory. E.g. a file of new PatternGenerator classes can be copied into pattern/, and will then show up in the GUI menus as potential input patterns. The GUI will also show any class derived from those in the library directories, even if it is defined in your own files, as long as that file has been run or imported before the GUI window is opened.
Many of the components come in multiple varieties, to be used at different levels in a model. For instance, there are learning functions that operate on a single unit (type LearningFn), and ones that operate on an entire CFProjection (type CFPLearningFn). The lower level components can be used by providing them to a "Plugin" version of the higher level component, which will apply the lower level version to each unit. For instance, a LearningFn can be used with a CFPLearningFn of type CFPLF_Plugin, and will be applied the same to each unit individually.
Some components also come with an optimized version, usually written in C for speed. The fastest, but least flexible, components will be high-level components written in C, such as CFPLF_Hebbian_opt.
Required external Packages
Topographica makes extensive use of the following external packages that must be installed to use Topographica:
For full use of the features of these packages, see their documentation.
- Python
- Topographica command and scripting language (essential!). Topographica is built on an unmodified copy of 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.
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 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. Since gmpy requires GMP to be built, Topographica will fall back to a slower, purely Python implementation of fixed-point numbers (fixedpoint).
They are included in the source distribution, or can be installed via your regular package manager.
Optional External Packages
A number of other packages are also useful with Topographica, but can sometimes be difficult to install. They include:
- SciPy
- SciPy includes many, many functions useful in scientific research, such as statistics, linear algebra, image processing, integration and differential equation solvers, etc. However, because of all the external libraries that it uses, getting SciPy to work on a particular installation can be difficult. You can try with
make -C external scipyif you installed Topographica from source; otherwise install Scipy described in its documentation.- 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')To use this package, first check you can runmatlab -nodesktop -nosplashsuccessfully, then build withmake -C external mlabwrap. If the matlab libraries are not in yourLD_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/glnx86You 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). On Linux source installations, building should require nothing more than
make -C external pyaudiolab.- 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. A connection to Player is provided in topo/misc/robotics.py, but the Player software is not distributed directly with Topographica. To install it, just download player-2.0.4.tar.bz2 from playerstage.sf.net, put it in the externals/ subdirectory, and do
make -C external player. The Gazebo and Stage simulators that support the Player interface can also be used, as described on the Player site.- 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. To install Cython for Topographica, just enter
make -C external cythonfrom your Topographica directory.Topographica runs on an unmodified version of the Python language, and so it can be used with any Python package that you install yourself. To install such a package in Topographica, just run its
setup.pyas usual, being sure to use whichever copy of Python that you use for Topographicatopographica/bin/python. For instance, if you are currently in the main topographica source directory and the new package has been unpacked in your home directory/home/user/pkg, just typebin/python /home/user/pkg/setup.py. Running setup in this way ensures that the package will be installed in Topographica's copy of python, rather than any other copy of Python that might be present on your system.A good list of potentially useful software is located at SciPy.org. Some packages of note:
- 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.
Hosted by: ![]()
James A. Bednar (jbednar@inf.ed.ac.uk) Last update: Tue Nov 1 9:50:29 UTC 2011.