Developer Manual

This manual gives guidelines for developers working on the source code for the Topographica simulator. Users will not usually need to refer to this material, unless they plan to submit significant blocks of code to the project (which is, of course, strongly encouraged!).

By default, all the text in this manual refers to program code written in the Python language. There are also some bits of C/C++ code in the simulator, which use different conventions.

Note that Topographica’s documentation may change between releases, so developers should usually be reading either their locally built copy of the documentation, or the online nightly documentation build. The documentation at applies to the previous release, so may be out of date with respect to the current version of Topographica in Git.

Installation instructions
Before starting, you will need a version-controlled copy of Topographica.
Revision control
How we keep track of changes to the code and other files
General guidelines
General info on writing Python, plus Topographica-specific conventions such as guidelines for naming, comments, documentation, parameters, units, and external imports.
Object-oriented design
How to design well-structured code
Importing files and packages
How to import Topographica and external code
How to flag incorrect or confusing code or documentation
GUI programming
How to add functionality to the GUI
Performance optimization
When (and when not!) to optimize for performance, and how to do it
Memory usage
How to measure memory usage and reduce it
Refactoring/testing tips
Tips for improving existing code by refactoring
Test suite
Rationale behind unit tests; should eventually include information about how to set up tests
How to make a new public release of Topographica


Anyone interested in Topographica is welcome to join as a Topographica developer to get read/write access, so that your changes can become part of the main distribution. Just sign up for a free account at, then email Jim your username and what you want to do, and he’ll tell you how to proceed from there. Alternatively, you can start immediately by cloning Topographica, developing your feature, and submitting it as a public pull request only once it’s done.