|
|
Topographica is developed under Linux, and is also supported for
Windows and Mac OS X. It should work on non-Linux versions of UNIX as
well, as long as standard GNU tools like make and GCC are installed.
You will need a writable directory with a large amount of space
available, about 500 megabytes as of 10/2007.
There are two ways to obtain Topographica: as downloadable
installation packages, or via Subversion (SVN). Most users
should download the installation packages at our Sourceforge downloads
page. Linux, Unix, and Mac OS X users can download either the
.zip or .tar.gz archive package, unpack it,
and then follow the Building
Topographica instructions below. Depending on your setup, Mac
users may find that you need to install some of the programs specified
in the Mac SVN instructions. Windows users
can download and run the self-installing .exe
file, and can then skip to the 'Running Topographica' instructions
below. Users who want more frequent updates, or who need to modify
the source code, should obtain Topographica using
SVN instead.
Once you have obtained the topographica directory, you
are ready to build Topographica. This directory contains the files
making up Topographica itself, plus source code versions of the
various external libraries needed by Topographica. At present, the
libraries are included in source code form to minimize
platform-specific modifications needed for different systems, although
this approach does increase the disk space and compile time
requirements.
On Windows, no build step is necessary if you downloaded the
self-installing .exe file. Windows SVN users should just double click
on setup.bat in the
topographica\topographica-win\setup_cvs_copy\
directory after checking out the code.
On Mac OS X, you first need to type make osx-patch
(which removes LDFLAGS=-Wl,-rpath,${PREFIX}/lib from the
python build step; the -rpath option is required
on Linux but is not supported on the Mac). Following this, type
make as usual (see below). Note that the lack of
-rpath appears to mean that system Tcl/Tk libraries will
be used if those are present; we are looking into whether the ones in
the Topographica distribution can be used instead.
On other Unix-based systems like Linux, just type make
(which may be called gmake on some systems) from within
the topographica/ directory. It is best to do this as a
regular user in the user's own directory, not as a root user with
special privileges, because Topographica does not need any special
access to your system. You will currently (10/2007)
need to do this on a machine with a functioning DISPLAY, not on a
remote text-only windowless session, because of build requirements for
the MatPlotLib library. (Note that many systems provide xfvb for this
very purpose, and in such cases you can simply do "xvfb-run make" to
build using a virtual display instead.) The build process will take a
while to complete (e.g. about 5-10 minutes on a 1.5GHz Pentium IV
machine with a local disk).
On some Linux distributions that start with a minimal set of
packages included, such as Ubuntu or the various "live CD" systems,
you may need to specify explicitly that some standard libraries be
installed in your system, such as
libfreetype,
libfreetype-dev,
libpng,
libpng-dev,
libx11-dev, and
zlib,
before make will succeed. On some systems the
-dev packages are called -devel, and
sometimes specific versions must be specified (e.g.
libpng12-dev,
libfreetype6-dev). Example for Ubuntu 7.10:
"sudo apt-get install libfreetype6 libfreetype6-dev libpng12-0 libpng12-dev libx11-dev zlib1g".
If you have the php, m4, bibtex, convert,
and fig2dev commands installed, you can also make local copies of the
HTML documentation from the web site; to do so, type make
all instead of (or after) make. (If you don't
have those commands, in most distributions you can get them by
installing the php, m4, tetex, imagemagick, and transfig packages).
make all will also run the regression tests and
example files, to ensure that everything is functioning properly on
your system. If you do the tests on a machine without a functioning
DISPLAY, such as a remote text-only session, there will be some
warnings about GUI tests being skipped.
If all goes well, a script named topographica or
topographica.bat will be created in the
topographica/ directory; you can use this to start
Topographica as described in the 'Running
Topographica' section below. If you have problems,
try adding -k to the make command, which
will allow the make process to skip any components that do not build
properly on your machine. Topographica is highly modular, and most
functionality should be accessible even without some of those
components.
Once you have the program installed and built, you can run
Topographica on the example models. On most systems (including Linux,
Unix, and Mac), just open a terminal window, go to your topographica/
directory, and type e.g.:
./topographica -g examples/cfsom_or.ty
or
./topographica -g examples/hierarchical.ty
or
./topographica -g examples/som_retinotopy.ty
or
./topographica -g examples/lissom_oo_or.ty
(Windows users can type similar commands at a Windows command prompt:
hold your mouse over a command above to see the Windows equivalent, or
see our note about translating Unix shell
commands to Windows. Alternatively, Windows users can double
click on one of the .ty scripts in the examples
directory; .ty files are associated with Topographica.)
Note that the first time Topographica is run on a given example,
there may be a short pause while the program compiles some of the
optimized components used in that example. (Some components,
generally those with _opt in their names, use code
written in C++ internally for speed, and this code must be compiled.)
The compiled versions are stored in ~/.python25_compiled/
on most systems (or in the temporary directory
%TEMP%\%USERNAME% on Windows), and they will be reused on
the next run unless the source files have changed. Thus you should
only notice such pauses the first time you use a particular component,
at which time you may also notice various inscrutable messages from
the compiler (which may generally be ignored).
In any case, a good way to get started with these examples is to
work through
the SOM or
LISSOM tutorials.
Have fun with Topographica, and be sure to subscribe to the
topographica-announce
mailing list to hear about future updates!
|