|
| 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 a 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.
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:
- base
- Core Topographica functions and classes
- 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)
The base directory contains the most fundamental
Topographica classes, implementing basic functionality such as
Parameters (user-controllable attributes), 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. All of 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.
The Topographica primitives library consists of an extensible
family of classes that can be used with the above functions and
classes:
- patterns
- PatternGenerator classes: 2D input or weight patterns
- sheets
- Sheet classes: 2D arrays of processing units
- projections
- Projection classes: connections between Sheets
- eps
- EventProcessor classes: other simulation objects
- outputfns
- Output functions: apply to matrices to do e.g. normalization or squashing
- responsefns
- Calculate the response of a unit or a Projection
- learningfns
- Adjust weights for a unit or a Projection
- commands
- 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 patterns/, 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 learningfns 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.
Many 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.
External Packages
Topographica makes extensive use of external packages included with the
distribution. For full use of the features of these packages, see their
documentation:
- Python
- Topographica command and scripting language (essential!). For a
good basic introduction, check out the Python tutorial. There
are also books and many websites available with more information.
Topographica is built on an unmodified copy of Python, so anything that
Python can do is also valid for Topographica.
- 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.
- MatPlotLib
- Matplotlib is used for generating 1D (line)
and 2D (plane) plots, such as topographic grid plots. It provides
a very general Matlab-like interface to creating plots of any quantities
one might wish to visualize, including any array or vector in the program.
- 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.
- Pmw
- Topographica uses Pmw for its graphical user interface (GUI)
classes, and those who want to add their own GUI windows can use any
widgets from Pmw.
- 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.
Optional External Packages
Several packages included with the Topographica distribution are
not built by default because their build processes are sometimes difficult.
Often, however, it is reasonably straightforward to build these
packages yourself. Individual packages can be built as described in their
own sections below, or you can attempt to build all the optional packages with
make -C external all (though this will stop at the first failure).
Alternatively, if you want to see which of these packages will build
without errors, just do make -k -C external all; any
packages with errors will then be skipped rather than stopping the
build process.
- 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 scipy.
- 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 run
matlab -nodesktop -nosplash successfully, then build with
make -C external mlabwrap.
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.2/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).
On Linux, building should require nothing more than
make -C external pyaudiolab.
- gnuplotpy
-
You can use the external
gnuplot command to generate plots on
some platforms (at least UNIX, and also probably Mac OS X). To build
it on Linux or Mac, first install Numeric (e.g. using
cvs update -D 2007-04-15 external/Makefile external/Numeric-24.0.tar.gz; make -C external numeric ; cvs update -d -P -A external/Makefile external/Numeric-24.0.tar.gz),
and then do make -C external gnuplotpy. At that point
you can e.g. use matrixplot3d_gnuplot() in place of
matrixplot3d()
or matrixplot(), or modify
matrixplot3d_gnuplot() to create any other gnuplot visualization.
- 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.
Additional extensions
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.py as usual, but using the copy of Python in
topographica/bin/python. For instance, if you are
currently in the main topographica directory and the new package has
been unpacked in your home directory /home/user/pkg, just type
bin/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.
|