|
| 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.
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-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)
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.
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:
- 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.
For full use of the features of these packages, see their
documentation.
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 scipy if 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 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.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).
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
cython from 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.py as usual, being sure to use whichever copy of
Python that you use for Topographica
topographica/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 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.
|