Guidelines

The basic principles of developing Brian are:

  1. For the user, the emphasis is on making the package flexible, readable and easy to use. See the paper “The Brian simulator” in Frontiers in Neuroscience for more details.
  2. For the developer, the emphasis is on keeping the package maintainable by a small number of people. To this end, we use stable, well maintained, existing open source packages whenever possible, rather than writing our own code.

Coding conventions. We use the PEP-8 coding conventions for our code. Syntax is chosen as much as possible from the user point of view, to reflect the concepts as directly as possible. Ideally, a Brian script should be readable by someone who doesn’t know Python or Brian, although this isn’t always possible. Function and class names should be explicit rather than abbreviated.

Documentation. It is very important to maintain documentation. We use the Sphinx documentation generator tools. The documentation is all hand written. Sphinx source files are stored in the docs_sphinx folder in the repository, and compiled HTML files are stored in the docs folder. Most of the documentation is stored directly in the Sphinx source text files, but reference documentation for important Brian classes and functions are kept in the documentation strings of those classes themselves. This is automatically pulled from these classes for the reference manual section of the documentation. The idea is to keep the definitive reference documentation near the code that it documents, serving as both a comment for the code itself, and to keep the documentation up to date with the code.

In the code, every class or function should start with an explanation of what it does, unless it is trivial. A good idea is to use explicit names rather than abbreviations, so that you instantly understand what it is about. Inside a function, important chunks should also be commented.

Testing. Brian uses the nose package for its testing framework. Tests are stored in the brian/tests directory. Tests associated to a Brian module are stored in brian/tests/testinterface and tests of the mathematical correctness of Brian’s algorithms are stored in brian/tests/testcorrectness.

Errors. It is a good idea to start an important function (e.g. object initialisation) with a check of the arguments, and possibly issue errors. This way errors are more understandable by the user.

Enhancements. Brian uses a system parallel to the Python Enhancement Proposals (PEPs) system for Python, called Brian Enhancement Proposals (BEPs). These are stored in dev/BEPs. Ideas for new functionality for Brian are put in here for comment and discussion. A BEP typically includes:

  • How the feature will look from user point of view, with example scripts.
  • Detailed implementation ideas and options.

We also use the Brian development mailing list.

Contributing code

First of all, you should register to the developers mailing list. If you want to modify existing modules, you should make sure that you work on the latest SVN version. We use the Eclipse IDE because it has a nice Python plugin (Pydev) and SVN plugin, but of course you can use your preferred IDE. The next step is to carefully read the guidelines in this guide.

Now that you wrote your code:

  • Write a test for it in brian/tests/testinterface. If it is a new module, create a new file test_mymodule.py;
  • Write documentation, both in the file (see how it’s done in existing modules) and, if appropriate, in the relevant file in docs_sphinx. We use the Sphinx documentation generator tools. If you want to see how it looks, generate the html docs by executing dev/tools/docs/build_html.py. The html files will then be in docs.
  • If it is a significant feature, write an example script in examples and insert a line in examples/examples_guide.txt.
  • Create a patch file. For example with Eclipse, right-click on the Brian project, then Team > Create Patch > Save in filesystem, then Next > Project.
  • Send your patch as an attachment to the developers mailing list and make sure the subject of your message starts with [PATCH]. Then describe your patch in your message.

From that point, your patch will either be directly included in the svn or (more likely) will be first discussed in the mailing list.

New modules. New Brian modules typically start in the dev/ideas folder, then go to brian/experimental when they starting looking like modules. They move to the main folder when they are stable (especially the user syntax).

Project Versions

Table Of Contents

Previous topic

Developer’s guide

Next topic

Simulation principles

This Page