# 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.

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()
{
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;
}

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.

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

Then 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.

If 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.

# Writing molecular dynamics data to binary LAMMPS format

In this post I will explain  how to write to the binary LAMMPS file format from C++, using data stored in Armadillo vectors and matrices. After running the example in this post you should be able to open the resulting file in Ovito or any other program capable of reading binary LAMMPS files. The example should also be fairly easy to port to other data structure type, if needed.

For the impatient: You’ll find a working main.cpp file and a qmake project file on GitHub.

The result, if rendered in Ovito, is two silicon atoms (in red) and one oxygen atom:

## About the LAMMPS format

LAMMPS is a molecular dynamics simulation package that is extremely versatile with plenty of interaction potentials and features implemented. However, you may have written some other code involving atoms and found yourself in the position of considering using a standard file format to write atom data to file. In this case, the XYZ-format has likely passed your mind, but because this is a ASCII-based text format, it is slow to read and write. This format also lacks standardized headers for information such as the system boundaries – causing visualizers like Ovito to have to guess for the right boundaries in your system.

# Playing around with Sculpt Mode in Blender

While preparing for a presentation I’m giving on Python scripting in Blender, I figured I’d  also try out some new features . One such feature is in Sculpt Mode, where dynamic topology is now allowing fine-grained control over the level of detail while sculpting. This turned out to be a lot of fun, so I decided to sculpt a human face while at it:

Dynamic topology is such an amazing addition to Blender and exactly what lacked in previous versions. The feature has been around for a while and has truly matured the whole Sculpt Mode since last time I tried it in Blender.

There’s a long list of things I would like to fix in this rendering, but with so much going on in other projects, I will be putting this away for now. Should I pick it up again later, I might even start from scratch and make better use of Blender’s multiresolution features too.

If you want to start learning how to sculpt human faces in Blender (in much greater detail than what I have achieved here), you should take a look at this great video course.

# Copying data files to the build directory with qmake

Sometimes you want to copy some data files to the same folder as your final executable when you are building with qmake in a different directory than your source code. This is what Qt Creator does by default, so this is quite often needed.

Just add the following to your .pro file to copy the folder “data” from the source directory to the build directory whenever you build the source code:

copydata.commands = $(COPY_DIR) $$PWD/data$$OUT_PWD first.depends =$(first) copydata
export(first.depends)
export(copydata.commands)
QMAKE_EXTRA_TARGETS += first copydata

The meaning of the different names in the above are as follows:

• \$(COPY_DIR) – Holds a platform-dependent copy-command that makes sure to copy recursively.
• $$PWD – Holds the name of the source code directory, where your .pro file resides. •$$OUT_PWD – Holds the name of the build directory. Note that this may not work if you are running qmake and make in the same directory as your source code, as you will be copying into the same folder as you copy from.
• copydata – Just a name we choose. You can replace this with whatever you want.
• first - This is a build step that already exists in the Makefile generated by qmake. We attach the copy build step to this build step.
• export – Makes the variable in the argument of the function available in a global scope.
• QMAKE_EXTRA_TARGETS - Tells qmake that you want to build more targets than the ones it adds by default to the Makefile.

This method is a bit messy, and I wish the Qt developers would make it easier to do this, but it works. It also ensures that the data is always copied, ensuring that any changes in the data folder are pushed to the build folder.

# Multiple billboards in Qt3D

While Qt3D has a transform for drawing billboards, it is not very useful if you are drawing thousands of particles. This is because the transform can only be applied to one object at the time, and using thousands of objects is never a good idea in neither OpenGL or Qt. This is simply because the overhead of each object is very large, both in terms of memory and performance.

The solution I found was to write my own custom class that inherits QQuickItem3D and is capable of drawing a list of 3D points as billboards by directly turning each sprite towards the camera at every draw call. This is not very efficient, but it works and is way faster than the options: Drawing spheres or creating one billboard per particle. The ideal option is of course to use geometry shaders, but they are not easily available in Qt3D yet. Most likely because its a new feature in OpenGL 3.2.

The class is available on GitHub and the resulting output is shown in this screenshot:

# Using Qt3D today

Qt3D is an amazing library for Qt that gives you the ability to render your own 3D stuff together with your existing widget or QML based GUI. The library was started by the Qt developers a few years back, but has not yet been released with the official Qt SDK. It was announced that it would be bundled with Qt5.0, but because of the state of the library at the time, its release was postponed. Even so, the library is still very mature and appears to work very well in my opinion. So I would urge you to test it out.

## Simple install on Ubuntu

To use the library you have a couple of different choices. If you are running Ubuntu, you may just run the following commands:

sudo apt-get install qt3d5-dev qtdeclarative5-qt3d-plugin

And you should be good to go. Look for examples in the Qt3D documentation.

Note that Ubuntu currently doesn’t have QtQuick.Controls available, so you will have to follow the instructions below to combine Qt3D with QtQuick.Controls.

## Install Qt3D into the newest Qt release

Currently Qt5.1.1 is the newest stable release of Qt and is the version I’d recommend that you use with Qt3D.

git clone git://gitorious.org/qt/qt3d.git qt3d
make install