Personal tools

SpineCreator - A Graphical Tool

From Spiking Neural Mark-up Language (SpineML)

(Redirected from Gui)
Jump to: navigation, search

Contents

Introduction

SpineCreator is a cross platform (OSX with retina support, Linux and (potentially) Windows) graphical editor for SpineML models with support for running model simulations. It features OpenGL visualisation of networks, simulator integration and graphical analysis tools.

Pre-built binaries can be downloaded below or you can check out the source from github.

One way to get SpineCreator running is by building it from source. This allows you to easily keep up to date with improvements to the software.

Although SpineCreator on its own can create and modify SpineML models, it is always installed along with the SpineML_PreFlight program, the SpineML_2_BRAHMS simulation engine and the BRAHMS program so that it can execute models as well as modify and edit them.

Full source code for all four programs is available from github. You will need to have the Graphviz library installed on your system and you may need to modify the main Qt Creator project file with its location.

Please report any issues on Github.

SpineCreator

Github SpineCreator source

SpineCreator is the SpineML Editor; the main graphical front end. It's built using Qt and depends on Graphviz.

SpineCreator calls SpineML_2_BRAHMS to run a model.

SpineML_2_BRAHMS

Github SpineML_2_BRAHMS source

A complex set of scripts which manage the execution of the SpineML model. The convert_script_s2b script is the top level script and is either called automatically by SpineCreator or manually by the user.

convert_script_s2b first "preflights" the SpineML model, then converts the model network into a BRAHMS-friendly "SystemML" format. It converts the SpineML components into C++ BRAHMS component code. The C++ BRAHMS components are then compiled into object-code. Finally, BRAHMS is called to execute the simulation.

SpineML_PreFlight

Github SpineML_PreFlight source

SpineML_PreFlight takes a SpineML model created by SpineCreator (or any other tool) and "preflights" it ready for simulation.

The program parses the SpineML model, updating any aspects of the model where parameters, weights or connectivity are specified in meta-form.

SpineML_PreFlight is called by SpineML_2_BRAHMS.

BRAHMS

Github BRAHMS source

BRAHMS is execution middleware. It is the program which actually executes the model, generating output data into log files which can then be analysed in SpineCreator or any external data viewer.

BRAHMS is called by SpineML_2_BRAHMS.

Download/Install

The latest binary release of the SpineML toolchain was made in January 2016. We provide packages for Mac, Debian and Ubuntu.

Mac

The Mac installation package is available here: spinecreator-0.9.6.dmg

Note: This is stored on a non-commercial web server which does not have a commercially signed SSL certificate; you will have to Okay some security warnings to access the file!

Debian

Debian packages are available for Jessie (Debian 8) and unstable (a.k.a. Debian Sid). Download the 4 .deb files for your architecture (amd64 for 64 bit; i386 for 32 bit).

Debian Jessie debs are here: https://sebjames.zapto.org/owncloud/index.php/s/SKp02hTaoLy7rRh

Unstable/sid debs are here: https://sebjames.zapto.org/owncloud/index.php/s/grJuQkLUKZiUIWJ

Now install the 4 .deb files:

sudo dpkg -i brahms_0.8.0-1_amd64.deb spineml-preflight_0.1.0-1_amd64.deb \
             spineml-2-brahms_1.1.0-1_amd64.deb spinecreator_0.9.6-1_amd64.deb

Ubuntu

Ubuntu packages for Ubuntu versions 14.04 (trusty) and above are available from the following Personal Package Archive: https://launchpad.net/~sebjames/+archive/ubuntu/spineml

To install, open a terminal and do the following:

sudo add-apt-repository ppa:sebjames/spineml
sudo apt-get update
sudo apt-get install spinecreator

A note about Windows

Unfortunately, we don't have the resources to prepare Windows builds of SpineCreator and SpineML-2-BRAHMS, although some work has been carried out towards this goal. If you're interested in making Windows builds, please contact Seb James.

Building on a Mac

Note that these instructions for building on Mac have not recently been verified (Seb, 20151126).

Mac prerequisites

Xcode

You will need to install Xcode. This is used to compile popt, graphviz-devel, as well as SpineCreator and its components.

Install Xcode from the App Store, assuming you have the latest Mac OS. If you're using an older Mac OS, you'll have to find the matching version of Xcode from: https://developer.apple.com/downloads/

CMake

CMake is a build-coordinating system. We use it to build BRAHMS, SpineML_PreFlight and the SpineML_2_BRAHMS tools.

Download and install from: https://cmake.org/download/

Mac Ports

You will probably want to install Mac Ports. This is used to install popt and graphviz-devel. It's not the only way; if you prefer an alternative, use that.

Install Mac Ports from: https://www.macports.org/install.php

You can verify your installation by opening a terminal on your Mac and typing

port

A program should run. Type "quit" to exit.

Libraries

Once Xcode and Mac Ports is installed, you can install the prerequisite libraries popt and graphviz like this (in a terminal):

sudo port install popt
sudo port install graphviz-devel

Qt

One more prerequisite is Qt, which is required by SpineCreator. You can install this with the Qt online installer from https://www.qt.io/download/

SpineML_PreFlight

First make sure you installed popt, as described above.

Clone a copy of SpineML_PreFlight:

git clone https://github.com/SpineML/SpineML_PreFlight.git

Build and install SpineML_PreFlight using cmake:

cd SpineML_PreFlight
mkdir build

Now open CMake. In the CMake window, navigate to the SpineML_PreFlight directory as the "source" and for "where to build" navigate to SpineML_PreFlight/build. Press "configure" then "generate". Now go back to your terminal:

make -j4
sudo make install

BRAHMS

Clone the SpineML-group-maintained version of BRAHMS (which sports a nice cmake compile and install scheme):

git clone https://github.com/sebjameswml/brahms.git

Build brahms in "standalone" mode and have it installed in your home directory with cmake:

cd brahms
mkdir build
cd build
cmake -DSTANDALONE_INSTALL=ON -DCOMPILE_WITH_X11=OFF \
      -DLICENCE_INSTALL=OFF -DCMAKE_INSTALL_PREFIX=/Users/yourname ..
make -j4
make install

If you're using the GUI version of CMake (which is usual on a Mac) then make sure to check "STANDALONE_INSTALL", uncheck the LICENCE_INSTALL and COMPILE_WITH_X11 and set CMAKE_INSTALL_PREFIX to /Users/yourname.

SpineML_2_BRAHMS

Clone a copy of SpineML_2_BRAHMS into your home directory:

cd $HOME
git clone https://github.com/SpineML/SpineML_2_BRAHMS.git

We'll build the tools in SpineML_2_BRAHMS in-place (they don't have to be installed).

Open CMake. For both "source" and "where to build" select the SpineML_2_BRAHMS directory. Press "configure" and "generate".

(Ignore any Policy CMP0042 error you see).

In the terminal:

cd SpineML_2_BRAHMS
make

And that's it for SpineML_2_BRAHMS.

SpineCreator

Python requisite

SpineCreator requires python. On a Mac, this is available by default, so there's nothing to do to get it.

Qt prerequisite

Qt is a prerequisite of SpineCreator - SpineCreator is built with the Qt toolkit.

Obtain the Qt online installer from https://www.qt.io/download/

This will install both the library and the QtCreator build tool.

Graphviz prerequisite

If you completed the initial prerequisites section and installed graphviz-devel, then you're good to go.

We recommend using MacPorts to install Graphviz. Follow the guide here: https://guide.macports.org/ to install MacPorts. Once installed, you should only need the following command to install Graphviz:

sudo port install graphviz-devel

This will install graphviz libraries to /opt/local/lib/graphviz and header files to /opt/local/include.

The QtCreator project file which is part of SpineCreator should contain these paths, so you can now go ahead and build SpineCreator.

Obtain and compile SpineCreator

You can get a copy of the latest SpineCreator using this command in a terminal window:

git clone https://github.com/SpineML/SpineCreator.git

Open QtCreator, and then open the SpineCreator project. The file to open is called spinecreator.pro (on older branches it was neuralNetworks.pro). You'll find the QtCreator application in the Qt directory, wherever you installed it (and not necessarily directly in Launchpad).

On opening spinecreator.pro, you'll be asked to select a "kit" to use to build the project - that means a particular version of the Qt library aimed at a particular target. You should be able to compile with Qt version 5.x (Qt 4.x no longer supported). Choose the "clang" kit which builds for desktop Mac OS (by default you'll also have installed Android and iOS targetted kits).

Compiling and running SpineCreator

Compiling should be as simple as pressing the "run" or "build" button in QtCreator.

Finishing up: Configuring SpineCreator on Mac

We have to tell SpineCreator where to find SpineML_2_BRAHMS, BRAHMS etc.

Launch SpineCreator from the Qt Creator window, by pressing the "run" button, then, in SpineCreator, go to the menu "Edit -> Settings". This brings up a window with three tabs. Choose "Simulators".

Change the value for "Convert script" to "/Users/[you]/SpineML_2_BRAHMS/convert_script_s2b". Replace [you] with your username, so that the path points to the SpineML_2_BRAHMS which you cloned in your home directory.

Change the value for "Working directory" to "/Users/[you]/SpineML_2_BRAHMS"

On Linux, I set the settings like this for my home directory (/home/seb):

SpineCreator Settings window

Set a value in SYSTEMML_INSTALL_PATH to be "/Users/[you]/SystemML". That allows the component build scripts to find the BRAHMS include files.

On Mac, you'll also need to add "/usr/local/bin" to the PATH environment variable. Add it with a ':' to separate it. This allows the spineml_preflight program to be found.

Last gotchas:

In SpineML_2_BRAHMS, you should:

echo "OSX" > current_os

That will ensure that SpineCreator doesn't try (and fail) to re-compile the tools that you compiled in the SpineML_2_BRAHMS section earlier.

Click "Apply" then "Close".

Your installed version of SpineCreator can now find SpineML_2_BRAHMS. SpineML_2_BRAHMS can find SpineML_PreFlight and BRAHMS, because these were installed system-wide into /usr/local/bin/spineml_preflight and /usr/local/bin/brahms.

You should now be able to test your installation by running the GPR Basal Ganglia model.

Building on Linux

These build instructions have been verified on Ubuntu 14.04. Other Linux flavours should work just fine, but there may be slight differences in the names of some of the prerequisites. If your distro does not provide Qt 5.x, then you will need to install that separately from http://www.qt.io/download-open-source/. If your distro provides a version of Graphviz older than 2.32, then you'll have to install a more recent version of that (which is outside the scope of these instructions). If I recall correctly, Ubuntu 13.04+ will provide an out-of-the-box working platform for SpineCreator, as will Debian 7+.

If the build process for any of the four components fails, please let us know by creating an issue on Github. For example, if you can't build SpineML_PreFlight, then create an issue here: https://github.com/SpineML/SpineML_PreFlight/issues

Linux Prerequisites

You will need the following programs installed on your system:

sudo apt-get install build-essential qtcreator libqt5svg5-dev libgvc6 python git gitk \
  python-dev libgraphviz-dev libpopt-dev doxygen xsltproc cmake libxaw7-dev libxv-dev

Note that the Qt version needs to be 5.x; Qt 4.x is no longer supported.

Let's create a directory to keep the source code in one place:

cd ~
mkdir scsrc

Menus in Qt

On current versions of Ubuntu, the window menus in a Qt program are rendered along the top of the screen when using the default Unity desktop. If you're not using Unity, these menus can become hidden. If you have trouble accessing the window menus ("File", "Edit", "Help" etc) in Qt Creator or SpineCreator, then you can apply this workaround:

sudo apt-get install appmenu-qt

This configures all Qt programs to display their window menus in the window, rather than at the top of the desktop screen.

Compile BRAHMS on Linux

Clone the SpineML-group-maintained version of BRAHMS (which sports a nice cmake compile and install scheme):

cd ~/scsrc
git clone https://github.com/sebjameswml/brahms.git

Build brahms with cmake:

cd brahms
mkdir build
cd build
cmake -DSTANDALONE_INSTALL=OFF -DCMAKE_INSTALL_PREFIX=/usr/local ..
make -j4
sudo make install

Compile SpineML_PreFlight on Linux

Clone a copy of SpineML_PreFlight:

cd ~/scsrc
git clone https://github.com/SpineML/SpineML_PreFlight.git

Build and install SpineML_PreFlight using cmake:

mkdir SpineML_PreFight-build && cd SpineML_PreFlight-build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ../SpineML_PreFlight
make -j4
sudo make install

Clone SpineML_2_BRAHMS on Linux

Clone a copy of SpineML_2_BRAHMS into your home directory:

cd ~
git clone https://github.com/SpineML/SpineML_2_BRAHMS.git

There is no need to build SpineML_2_BRAHMS, which is a set of scripts.

Build SpineCreator on Linux

Clone SpineCreator:

cd ~/scsrc
git clone https://github.com/SpineML/SpineCreator.git

Open QtCreator:

Open QtCreator

Now open the SpineCreator project. The file to open is called spinecreator.pro (in older branches it was neuralNetworks.pro):

Open spinecreator.pro

On opening spinecreator.pro, you'll be asked to "configure" the project. On Ubuntu you should be able to simply press the "Configure Project" button:

Press Configure Project

Compiling should now be as simple as pressing the "run" or "build" button in QtCreator:

Press the green play button

Finishing up: Configuring SpineCreator on Linux

There's just one last job to do. We have to tell SpineCreator where to find SpineML_2_BRAHMS.

Launch SpineCreator from the Qt Creator window, by pressing the "run" button, then, in SpineCreator, go to the menu "Edit -> Settings". This brings up a window with three tabs. Choose "Simulators".

Change the value for "Convert script" to "/home/[you]/SpineML_2_BRAHMS/convert_script_s2b". Replace [you] with your username, so that the path points to the SpineML_2_BRAHMS which you cloned in your home directory.

Change the value for "Working directory" to "/home/[you]/SpineML_2_BRAHMS"

I set the settings like this for my home directory (/home/seb):

SpineCreator Settings window

Click "Apply" then "Close".

Your installed version of SpineCreator can now find SpineML_2_BRAHMS. SpineML_2_BRAHMS can find SpineML_PreFlight and BRAHMS, because these were installed system-wide into /usr/local/bin/spineml_preflight and /usr/local/bin/brahms.

You should now be able to test your installation by running the GPR Basal Ganglia model.

Testing your SpineCreator installation

Whether you installed on Mac or Linux, you should be able to test your installation by running the GPR Basal Ganaglia model. This model is available from the ABRG-Models github account. You can either fork the model, or simply clone it:

cd ~
git clone https://github.com/ABRG-Models/GPR-BasalGanglia.git

Open SpineCreator, select "File -> Load project" and navigate to GPR-BasalGanglia/SpineML/GPR_BG.proj

You should see the Network for the model looking like this:

Network diagram for GPR Basal Ganglia model

Click on the "Expts" button to get to the Experiment interface. Choose the "Step Input" experiment and press the "Run experiment" button:

Experiment Layer

The system should first compile the components, then run the model. Compiling the components will take much longer than running this particular model. If you get the "Simulator Complete" message, then you can nagivate to the "Graphs" interface. The "Loaded Logs" list should be populated with several logs. Click on "SNr_out_log.bin". In "Select log indices to plot" highlight all six - hold the Ctrl key down and drag across them. Finally, click on "Line plot" for "Plot type" and then press the "Add plot" button. Your output should look like this:

Output of the model's Substantia Nigra pars Reticulata population

If your output matches the above, then congratulations, you have a working SpineCreator!

Gallery

Activity Visualisation

video here

Tutorials (under development)

Creating a component

Creating a network

Creating an experiment and graphing

Creating a new connectivity using a Python Script

Python scripts for generating connectivity are added to SpineCreator through the Settings/Preferences dialog, and once added appear in the list of connection types.

To allow non-programmers to use and configure extended connectivity types a set of formatted comments is added to the top of the Python script: these specify parameters to pass to the script, and define how SpineCreator should provide a graphical interface for these parameters. For example:

#PARNAME=sigma #LOC=1,1 
#PARNAME=minimum_weight #LOC=2,1 
#HASWEIGHT
 
def connectionFunc(srclocs,dstlocs,sigma,min_w):
  import math 
  normterm = 1/(sigma*math.sqrt(2*math.pi))
  i = 0
  out = []
  for srcloc in srclocs:
    j = 0
    for dstloc in dstlocs:
      dist = math.sqrt(math.pow((srcloc[0] - dstloc[0]),2) + \
        math.pow((srcloc[1] - dstloc[1]),2) + \
        math.pow((srcloc[2] - dstloc[2]),2))
      gauss = normterm*math.exp(-0.5*math.pow(dist/sigma,2))
      if gauss > min_w:
        conn = (i,j,0,gauss)
        out.append(conn)
      j = j + 1
    i = i + 1
  return out

Adding parameters to the SpineCreator GUI is performed using the #PARNAME comment, which gives a name used as a label for the parameter, and a #LOC which describes the row and column where the parameter should be added in a grid for laying out the parameters. The order of the parameters in the code denotes the order they have in the corresponding Python function call, and allows the label to have a more descriptive name than the variable used in the function. In addition there are two more comments that are parsed; #HASWEIGHT and #HASDELAY, which inform SpineCreator if the script needs to generate a weight and/or a delay. If a weight is generated SpineCreator will provide a drop-down list of the corresponding Properties in the WeightUpdate Component, and the selected Property will have the weight values inserted when the connectivity is generated. The function itself has arguments srclocs and dstlocs, which are Lists of Tuples, each Tuple containing the x, y, and z co-ordinates of the neuron at that index in the List.

Old Binary Releases

Windows 32bit (works on 64bit machines) Alpha 0.9.2 (Qt 4.8.1) download

Spinecreator 0.9.3: 32 bit | 64 bit

Everything - a zip of Debian packages for spinecreator 0.9.3, BRAHMS simulator and code generation for BRAHMS: 32 bit | 64 bit

Linux 32bit Alpha 0.9.2 Debian Package (with BRAHMS) download

Developer Information: SpineCreator Annotations and Project file

SpineCreator Annotations

SpineCreator stores information about the 2D layout of networks, the 3D layout of neurons, the 2D routing of inputs and projections, and python scripts used to generate some ConnectionList data, as Annotations using the new SpineML Annotations tags. Annotations about an object (population/projection etc...) are stored inside that tag, and SpineCreator will respect existing Annotations in the tags it modifies. In order for other software to be built that can utilise the SpineCreator information we present a guide to the tags and information that can be stored in Annotations through SpineCreator.

Population

An annotations tag within a Population stores the following information.

       <LL:Annotation>
           <SpineCreator>
               <xPos value="-11.2353"/>
               <yPos value="12.5792"/>
               <animSpeed value="0.2"/>
               <aspectRatio value="1.66667"/>
               <colour red="0" green="0" blue="0"/>
               <size value="1"/>
               <tag value="2"/>
               <x3D value="0"/>
               <y3D value="0"/>
               <z3D value="0"/>
               <is_visualised value="0"/>
           </SpineCreator>
       </LL:Annotation>

xPos

xPos
Contains Description
@value::float The 2D X position of the Population

yPos

yPos
Contains Description
@value::float The 2D Y position of the Population

animSpeed

animSpeed
Contains Description
@value::float The speed that a moved Population follows the mouse cursor

aspectRatio

aspectRatio
Contains Description
@value::float The ratio of the width to the height of the Population icon

colour

colour
Contains Description
@red::unit The red component of the Population icon colour (0:255)
@green::unit The green component of the Population icon colour (0:255)
@blue::unit The blue component of the Population icon colour (0:255)

size

size
Contains Description
@value::float The size of the Population icon

tag

tag
Contains Description
@value::int Not currently used by SpineCreator

x3D

x3D
Contains Description
@value::int The initial 3D X offset for drawing the neurons in the Population in 3D space

y3D

y3D
Contains Description
@value::int The initial 3D Y offset for drawing the neurons in the Population in 3D space

z3D

z3D
Contains Description
@value::int The initial 3D Z offset for drawing the neurons in the Population in 3D space

Projection

An annotations tag within a Projection stores the following information.

           <LL:Annotation>
               <SpineCreator>
                   <DrawOptions style="0" showlabel="0"/>
                   <start x="9.27878" y="7.23497"/>
                   <curves>
                       <curve>
                           <C1 xpos="9.4914" ypos="7.23497"/>
                           <C2 xpos="9.4914" ypos="7.22533"/>
                           <end xpos="9.56297" ypos="7.22533"/>
                       </curve>
                   </curves>
               </SpineCreator>
           </LL:Annotation>

DrawOptions

DrawOptions
Contains Description
@style::int Identifies the style used to draw the Projection in SpineCreator
@showlabel::bool Used to indicate if a label describing the Projection type should be displayed

start

start
Contains Description
@x::float The X start point of the bezier curves used to describe the 2D form of the Projection
@y::float The Y start point of the bezier curves used to describe the 2D form of the Projection

curves

curves
Contains Description
curve [1:...] Container for the bezier curve points used to describe the 2D form of the Projection

curve

curves
Contains Description
C1 [1] Bezier cubic curve C1 control point (See Qt documentation for QPainterPath::cubicTo for more details)
C2 [1] Bezier cubic curve C2 control point (See Qt documentation for QPainterPath::cubicTo for more details)
end [1] Bezier cubic curve end point (See Qt documentation for QPainterPath::cubicTo for more details)

C1

C1
Contains Description
@xpos::float X location of C1 bezier point
@ypos::float Y location of C1 bezier point

C2

C2
Contains Description
@xpos::float X location of C2 bezier point
@ypos::float Y location of C2 bezier point

end

end
Contains Description
@xpos::float X location of end bezier point
@ypos::float Y location of end bezier point

Input

An annotations tag within a Input stores the following information.

               <LL:Annotation>
                   <SpineCreator>
                       <start x="9.21702" y="5.48872"/>
                       <curves>
                           <curve>
                               <C1 xpos="8.94197" ypos="6.10971"/>
                               <C2 xpos="8.94197" ypos="6.10971"/>
                               <end xpos="8.66691" ypos="6.7307"/>
                           </curve>
                       </curves>
                   </SpineCreator>
               </LL:Annotation>

For descriptions of these tags please refer to the Projection section

ConnectionList

An annotations tag within a ConnectionList stores the following information.

                       <SpineCreator>
                           <Script text="#!/usr/bin/python

#PARNAME=size #LOC=1,1
#PARNAME=scale #LOC=2,1
#PARNAME=inhib #LOC=3,1
#HASWEIGHT

def connectionFunc( srclocs, dstlocs, size, scale, inhib ): 
...>
                           <Config weightProperty="w"/>
                       </SpineCreator>

Script

Script
Contains Description
@text:string The text describing a script for generating a ConnectionList of connectivity

Config

Config
Contains Description
@weightProperty:string A reference to the WeightUpdate Property name where an ExplictList is created by the Python script

SpineCreator Project file

SpineCreator stores the details of the xml files that compose the current Project in a file with the .proj extension. The format of this files is as follows:

<SpineCreatorProject>
 <Network>
  <File name="model.xml"/>
 </Network>
 <Components>
  <File name="LIN_adap.xml"/>
  <File name="LIF_det.xml"/>
  <File name="LIF_det1.xml"/>
  <File name="LIFposneg.xml"/>
  <File name="LIF1.xml"/>
 </Components>
 <Layouts>
  <File name="none.xml"/>
  <File name="hexagonal.xml"/>
 </Layouts>
 <Experiments>
  <File name="experiment0.xml"/>
  <File name="experiment1.xml"/>
 </Experiments>
</SpineCreatorProject>

SpineCreatorProject

SpineCreatorProject
Contains Description
Network [1] Contains the SpineML Network for the project
Conponents [1] Contains the SpineML Components for the project
Layouts [1] Contains the SpineML Layouts for the project
Experiments [1] Contains the SpineML Experiments for the project

Network

Network
Contains Description
File [1] The network file name

Components

Components
Contains Description
File [1:...] The component file names

Layouts

Layouts
Contains Description
File [1:...] The layout file names

Experiments

Experiments
Contains Description
File [1:...] The experiment file names

File

File
Contains Description
@name:string The name of a file