Straight from the source: NEURON’s incredible backwards compatibility

NEURON is a neural simulator, but it’s not just another neural network application. NEURON has been around much longer than your fancy deep learning software. It was first released in 1994, although some of it’s early code and concepts seem to stem from the 70’s and 80’s. In fact, NEURON is not a machine learning library at all. It simulates real neurons. It uses real morphologies and ion channel densities to reproduce experiments. Some labs even use machine learning algorithms to fit the parameters of their NEURON models. NEURON is one of the workhorses of the computational branch of the Human Brain Project and the core engine in the Blue Brain Project.

But the age of NEURON is starting to show in its source code. Because some things are a bit awkward when working with this simulator I decided to peek at its sources. Just to see what this old engine looks like on the inside. And it turned out to be an interesting journey. Deep inside NEURON’s plotting library, I found this:

#if VT125
case VT:
vtplot(mode, x, y);
break;
#endif

Now, I didn’t know what VT125 was when I first saw this, but a quick search on the web reminded me that I’m still a young software developer. I present to you, the VT100:

VT100 terminal
I couldn’t find a good picture of the VT125. I apologize if it looks way more modern than its older cousin.

Now that’s what I call backwards compatibility!

Some of you may want to lecture me about how modern terminals actually emulate VT100s and that this code might be in there to allow some fancy plotting inside xterm or its siblings. But I would argue that there are other parts of this code that give away its impressive attempt at supporting older platforms. Such as the rest of the above switch statement:

		switch (graphdev)
		{
		case SSUN:
#if SUNCORE
			hoc_sunplot(&text, mode, x, y);
			break;
#else
#if NRNOC_X11
			hoc_x11plot(mode,x,y);
			break;
#else
#if NeXTstep
			break;
		case NX:
			hoc_NeXTplot(mode,x,y);
			break;
#endif
#endif
#endif
#if TEK
		case ADM:
		case SEL:
		case TEK4014:
			tplot(mode, x, y);
			break;
#endif
#if VT125
		case VT:
			vtplot(mode, x, y);
			break;
#endif
		}
#endif

Now, we all love nested preprocessor if-statements inside switch blocks, but let’s look aside from that and at what’s supported here.

There’s the NRNOC_X11, which I believe introduces the only part of this block that might actually be executed nowadays. In addition we have SUNCORE, which might be Solaris, but I’d bet this supports something that existed long before Oracle acquired Sun back in 2010. There’s TEK, which may refer to something like the Tektronix 4010:

Tektronix_4014
This baby was made in 1972, but it still runs NEURON’s plotting functions. Just download the 5 MB zip-file of NEURON’s source code and … oh, wait.

And then there’s NeXTstep, which Apple acquired in 1997 and used to replace its own Mac OS with Mac OS X. Considering that NeXTstep made its last official release in 1995, I think its fair to say that this piece of code was written in the previous century. It could, of course, just be that no one has deared to search-replace NeXTstep with OS X, but I doubt it.

I should finish this with a final caveat: It could be that this code isn’t at all in use by NEURON anymore. After all, I found all of the above in the plot.c file in the src/oc folder of NEURON’s source code. The above could be remainders of NEURON’s interpreter language, hoc, which was originally made as a demonstration of how to use the parser generator Yacc in the The Unix Programming Environment book. As far as I know, NEURON is the only software out there that’s still using hoc, but that’s a story for another day.

Image Credits: Wikipedia User:ClickRick, Wikipedia User:Rees11.

Choosing the right license for your code

I was pointed to John Hunter’s Why we should be using BSD and came to think about how I rather tend to advocate using the GPL license. Richard Stallman makes some very convincing arguments for why GPL is the better choice, but even though I like this reasoning, I do see why choosing a different license may be the right choice.

In this post, I will explain some of the differences between BSD and GPL and hopefully help you to choose for yourself. The target audience for this post are people in the scientific community, but it may also be useful to others.

So how do BSD and GPL differ? Below I have listed what I think is most important, but please remember that I am not a lawyer, and that there are other effects of licensing that may apply to you:

  • BSD is a free-for-all license that only requires attribution. Anyone using your code must give credit to you as the original author. Apart from that, they can do pretty much everything. They can change the code and sell programs based on it without asking you.
  • GPL too requires attribution. However, it also requires anyone distributing software based on your source code to make available any changes they make to it. They can still sell programs based on your code to others without asking, but if they were to do something really smart with your code, you can demand that they share the changes with you. And you too can sell software based on their changes.

Before moving on, I would like to clarify one important thing: Even though you are licensing your code as BSD or GPL, you can still sell software based on your code. You can even sell the rights to use your code with a different license. The licenses only apply to what other people can do with your code. You still keep all other rights.

In the below table, I have summarized the differences between the licenses by listing a few scenarios. “They” is referring to someone using your code in their own software projects:

BSD GPL
You can sell software based on your own code. ✔   ✔  
They can sell software based on your code. ✔   ✔  
They can make changes to your code. ✔  
They have to give you credit for writing the original code. ✔  
They have to use the same license as you.
You can demand access to the changes they made to your code.
They can sell software based on your code without sharing their changes with you.
You can sell software based on the changes they made to your code. *

*Except if they also use a BSD license for their changes.

Some people call GPL “viral” because it “infects” any software using GPL licensed code. Any project using code with a GPL license will basically have to be GPL licensed too. This may be a showstopper for some companies that want to keep their own changes proprietary (secret/hidden) while still using your code. Note that this only applies if they distribute the software to others: If someone downloads your code and plays around with it on their own computer, they don’t have to care about the GPL license.

The viral effect is why Richard Stallman advocates the GPL license. He thinks that it benefits the open source community (and perhaps also the scientific community) that software using GPL code must be GPL too. In his opinion, companies have money to spend on developing new products or to buy access to other people’s source code. The open source community, on the other hand, does not necessarily have the same monetary resources, but has access to all the open source code out there. If an open source project is fine with the adhering to the GPL license, they can also use all other GPL licensed code .

Further, I think you should choose GPL for any code you think might be commercially viable for yourself in the future. Some people think the best option is to keep source code proprietary if you want to make money of it in the future. I think the exact opposite. If you are working on a project that you believe has some commercial value, why not let others find that commercial value for you? If someone starts selling software based on an improved version of your code, you can demand that they share the changes with you and start selling the software yourself.

However, there are many good arguments for using the BSD license too. Many open source projects are working with companies that require code not to be GPL licensed. One such project is Matplotlib, for which John Hunter is the original author. They have received contributions from companies like Enthought, which want to make sure they don’t have to license all their software as GPL because some code they use is from GPL projects. Such contributions are often significant for open source projects, and I can see why choosing BSD is a good middle way for them to keep the project open while still getting as much benefit from cooperation with companies.

Some also argue that BSD attracts more developers than GPL because some developers may be put off by a GPL license. However, I believe this works both ways. Some developers are also put off by non-GPL projects. I don’t think your licensing choice will change much in the number of developers that are attracted to your project. If anything, I would do some research and contact relevant companies and developers and ask if they would be willing to contribute to your project. You can always change the license as you go, but you should know that all code that has already been licensed as GPL or BSD will forever be licensed that way. It is non-retractable. Any future changes you make to your own code, however, can be put under a different license. You may even choose not to license your new code any more if you want to.

To conclude, when choosing between BSD and GPL, you should consider whether your main goal is to contribute to the open source community or to everyone in general. If you target only the open source community, GPL may be your best choice. If you want to contribute to everyone without further restrictions to the usage of your code, BSD may be your best bet.

Personally, I will continue using GPL as long as I think my code may turn into a commercially viable project or if I just don’t have a long-term plan yet. However, I will happily use BSD if I think the code can be contributed into a BSD licensed project such as Matplotlib.

There are also many other licenses out there. Have a look at the list made by the Open Source Initiative if you want to know more about other licenses.

Installing Sumatra 0.6-dev in Ubuntu 13.10

Sumatra is a great tool for reproducibility and provenance when you are running numerical simulations. Keeping your work reproducible ensures that you and others will be able to check your results at a later time, while provenance is to keep track of where your results came from in the first place.

I won’t get into details about using Sumatra in this post, as its documentation is quite good at describing that already.

Computational Physics members

If you are a member of the Computational Physics group and have access to the computing cluster, Smaug, you don’t have to install anything. Just ssh into our dedicated Sumatra machine, named bender, and run your jobs from there. In the future, all machines will support Sumatra, but for now, we only have one dedicated machine for this task:

ssh bender

On your own machine

Otherwise, or if you want it on your own machine, you will have to install it manually. This is done by cloning the repository and running the setup.py file. This will install Sumatra with all dependencies:

hg clone https://bitbucket.org/apdavison/sumatra
cd sumatra
python setup.py install --user

Adding –user to the final command ensures that all packages are installed to your home directory, under .local/lib, so that  you don’t have to install with sudo privileges, and it makes it a bit easier to remove the package if you don’t want to keep it.

We also need the GitPython and PyYAML modules, which you may install using apt-get:

sudo apt-get install python-git python-yaml

And that’s it! You should now be able to run your projects with Sumatra.

Recent commit causes Qt3D to fail compilation

A recent commit pushed to the Qt3D repository breaks building Qt3D against Qt version 5.2 and older with the following error message:

painting\qglpainter.cpp:2348:29: error: 'class QOpenGLFunctions' has no member named 'glReadPixels'

Thankfully, rolling back to an older commit still works. Just supply the following command after pulling the Qt3D repository:

git checkout d3338a9 -b older_version

This should enable you to compile Qt3D for Qt5.2 and earlier.

New project structure for projects in Qt Creator with unit tests

Note: This is a new version of an earlier post, with a revised project structure.

Note 2: See this post for the same project structure using the even better Catch testing framework.

This post assumes that you are using a C++ testing framework such as UnitTest++. See this earlier post for some information on installing UnitTest++ on Ubuntu.

To get the most out UnitTest++ it is a good idea to integrate its output into the Qt Creator IDE. The way I have set this up in Qt Creator is with subprojects. One for the main project, which again is split into the app itself and a library, and one for the tests. In addition, I have a helper project file, named defaults.pri. The structure of the project is like this:

MyProject
├─ MyProject.pro
├─ defaults.pri
├─ app/
│  ├─ app.pro
│  └─ main.cpp
├─ src/
│  ├─ src.pro
│  └─ myclass.cpp
└─ tests/
   ├─ tests.pro
   └─ main.cpp

An example project using this code structure has been posted on Github by Filip Sund. (Thanks to Filip for doing this!)

The main project file, MyProject.pro will now be based on a subdirs template, and may look like this:

TEMPLATE = subdirs
CONFIG+=ordered
SUBDIRS = \
    src \
    app \
    tests
app.depends = src
tests.depends = src

The app.depends and tests.depends statements makes sure that the src project is compiled before the application and tests, because the src directory contains the library that will be used by both the app and the tests.

(Thanks to Will for noting that this works better for parallel builds with make -j 8 than my previous version only using CONFIG+=ordered. We should keep CONFIG+=ordered in there still, though, because depends doesn’t affect the order when using make install).

defaults.pri

Each of the other .pro files will include defaults.pri to have all the headers available. defaults.pri contains the following:

INCLUDEPATH += $$PWD/src
SRC_DIR = $$PWD

If the library, main program and tests use common libraries, it is very useful to have the defaults.pri define these dependencies too.

./src

In the src folder, I have myclass.cpp, which is the class that I want to use and test. The src.pro needs to compile to a library, so that it may be used both by app and tests, and could look something like this:

include(../defaults.pri)
CONFIG -= qt

TARGET = myapp
TEMPLATE = lib

SOURCES += myclass.cpp
HEADERS += myclass.h

What this class does is not so interesting, it could be anything. A simple example could be this header file:

#ifndef MYCLASS_H
#define MYCLASS_H

class MyClass {
public:
    double addition(double a, double b);
};

#endif // MYCLASS_H

With this accompaning source file:

#include "myclass.h"

double MyClass::addition(double a, double b) {
    return a * b;
}

./app

I only have a main.cpp file in app, because the app is basically just something that uses everything in the src folder. It will depend on the shared compiled library from src, and app.pro would look something like this:

include(../defaults.pri)

TEMPLATE = app
CONFIG += console
CONFIG -= app_bundle
CONFIG -= qt

SOURCES += main.cpp

LIBS += -L../src -lmyapp

The main.cpp file could be a simple program that uses MyClass:

#include <myclass.h>
#include <iostream>

using namespace std;

int main()
{
    MyClass adder;
    cout << adder.addition(10, 20) << endl;
    return 0;
}

./tests

In the tests folder I have simply added a main.cpp which will run the tests. Then tests.pro has the following contents:

include(../defaults.pri)
TEMPLATE = app

CONFIG   += console
CONFIG   -= app_bundle
CONFIG   -= qt

SOURCES += main.cpp

LIBS += -lunittest++ -L../src -lmyapp

Which now links to the myapp library in addition to the unit tests.

The main.cpp in tests file which could contain the following, if we were to use UnitTest++ as our testing library:

#include <unittest++/UnitTest++.h>
#include <myclass.h>

TEST(MyMath) {
    MyClass my;
    CHECK(my.addition(3,4) == 7);
}

int main()
{
    return UnitTest::RunAllTests();
}

This test will fail because my implementation of MyClass::addition is completely wrong:

class MyClass {
public:
    double addition(double a, double b) {
        return a * b;
    }
};

Note that I’m including MyClass by through <myclass.h> which is possible because of the INCLUDEPATH variable in defaults.pri.

This is hopefully all you’ll need to define a project that compiles a library, as well as tests and an application using the library.

Faster loading of Qt apps on Android

Edit: In QtCreator 3.1, the method used here (using resource files) will become the default way to perform deployment on all platforms. I.e., this guide is only useful if you have created your project using QtCreator < 3.1.

If your Qt application is taking too long to load on Android, it is likely because accessing asset-files is really slow on some devices. I just tested an application with about 12 QML-files and it took 40(!) seconds to load. This appears to have been an issue for quite some time, and although efforts have been made to reduce the problem, my app still loads too slow on my Asus Transformer TF300T. In Qt and Android’s defence, this device is known for its extremely slow eMMC storage.

The cure in my case was to use a Qt Resource Collection file for all my QML assets. In Qt Creator, this is as simple as clicking  File > New File or Project > Qt > Qt Resource file and then add a prefix “/” before adding all files from each QML folder. After creating and setting up the .qrc-file, I changed the URL in my main-function to “qrc:/qml/myproject/main.qml”.

This worked flawlessly, and the load time dropped from 40 seconds to less than a second!

You should of course be careful with what you add to your resource file. All listed files will be compiled into your executable, so if there are files you don’t want loaded right away, you might want to keep them outside your .qrc file.

The only downside with this approach is adding all new QML files to the resource file. This  is a bit tedious in the long run, so I suppose I will automate it with a script.

 

Focusrite Scarlett 2i2 working flawlessly on Ubuntu with JACK

I needed a new sound card for Ubuntu that would allow me to do some recording and playback easily. After a bit of searching and testing, I figured I would go with the Focusrite Scarlett 2i2, which is a USB sound card with 2 XLR + jack inputs, stereo monitor output and a headphone jack. It also supports +48V phantom power if you need to connect a condenser microphone.

In addition it appears to be well-tested on Linux, with several user reporting that the device just works.

Popping trouble

However, the device seemed to have some trouble with PulseAudio, which is the default audio library used in Ubuntu. Everything works, meaning that any audio application was able to output sound, and recording in Audacity gave good sound quality, but whenever I started playback or recording after switching between applications, the sound card would hang for 2 seconds and make 4 popping sounds before returning to normal operation.

The solution: JACK + PulseAudio JACK Sink

If you are going to do any serious recording in Ubuntu, or Linux in general, you should get to know JACK. It is an awesome audio library for Ubuntu that aims to make life easy for musicians, audio engineers or the occasional amateur that wants to do recordings. It runs on top of ALSA, meaning it will support almost any sound card you can think of, but does so in a way that gives you extremely low latency and doesn’t mess with sound quality. The downside? JACK doesn’t allow PulseAudio to play side-by-side with it. And every Ubuntu application tries to play through PulseAudio by default.

The solution is to install the pulseaudio-module-jack package, which will allow applications to connect to JACK, even when they have no support for JACK:

sudo apt-get install pulseaudio-module-jack

In addition, you should install a nice GUI that will allow you to control JACK easily. This is named QjackCtl:

sudo apt-get install qjackctl

After installing, just run QjackCtl from the command line or the Dash and start + connect to the JACK server.

qjackctlAfter this is done, you may check the Connect window to see if PulseAudio JACK Sink is also running, which it should do by default.

pulseaudiojacksinkThen you may open Ubuntu’s Sound Settings and set PulseAudio JACK Sink to be your Output device. From now on, all applications should work even though JACK is running.

ubuntu-soundIf you wish to, you may change QjackCtl’s settings to make JACK start whenever QjackCtl is started, and afterwards add QjackCtl to your Startup Applications in Ubuntu. This way JACK will start whenever you start your computer.

No more popping

After installing PulseAudio JACK Sink and QjackCtl, I no longer experience any popping, and the FocusRite Scarlett 2i2 works flawlessly. The sound quality is great and the latency minimal, so I would definitely recommend this sound card to any Linux user wanting to do some recording at home or on the go.

Even though I wish it would work right out of the box, installing two packages to get everything perfect is that much work, and I assume that someone figures out a good solution to merge PulseAudio and JACK in a way similar to the one I use by default sometime in the future.