Home

Introduction

About this Document

The goal of this document is to enable the users of the COSIVINA toolbox to quickly build DNF architectures, design GUIs for them, and run their models in the way that is most appropriate for their requirements. This document does not provide a general introduction to Dynamic Neural Field Theory, its applications or the underlying mathematics (see http://www.robotics-school.org/ for introductory lectures and materials).

The document is structured into four major parts: The first describes the key components of the framework. The second one provides a reference of the available classes, specifically the elements that can be used to construct an architecture and the controls and visualizations for the design of a custom GUI. The third part describes how to expand the framework by adding new classes. The fourth part provides tutorials and examples for using this framework, including the construction of architectures and GUIs and different ways to run simulations for testing and tuning neurodynamic models. You may jump directly to this last part to get a quick idea of how to use this framework.

Overview of the Framework

The COSIVINA toolbox is intended as a tool to quickly create Dynamic Neural Field (DNF) architectures in Matlab and simulate their activation time course either in an interactive mode with a GUI, or in an offline mode. The software was developed at the Institut für Neuroinformatik at the Ruhr-Universität Bochum, where it is used both in teaching the concepts of DNFs and in research. It is published under the Simplified BSD License.

The basic idea for the framework is to divide a DNF architecture into individual elements that can be implemented as objects of different classes. Assume for example we have a simple one-dimensional dynamic neural field, which has lateral interactions (typically local excitiation and surround inhibition) and receives several inputs, often modeled as Gaussian functions. We can then divide this architecture up into the following elements: The dynamic neural field itself (the distribution of activation that changes according to a dynamic field equation); the lateral interaction kernel that is convolved with the field; and several Gaussian stimuli. These elements are connected to each other: The stimuli feed into the neural field, the element for the lateral interactions receives input from the field and feeds back to it. Larger architectures containing many neural fields that interact with each other through mutual projections or other operations can be segmented in the same way.

The dynamics of the architecture (the change of its state over time) is simulated using the Euler method: The rate of change for each dynamic element is determined for equidistant time steps and assumed fixed for the duration of the step. The segmentation into elements is done in such a way that the operation to be performed in each step can be computed for each element separately, based only on the element’s own state, its direct inputs and the element’s parameters.

In the framework, an architecture is constructed by adding elements and specifying their parameters and their connections to each other. The architecture can be run (i.e. the change of its state over time be simulated) either in individual steps or for a fixed duration. The states of of all element can then be accessed, analyzed or plotted, their parameters or states changed, and the simulation continued thereafter. Moreover, the framework offers tools to create graphical user interfaces (GUIs) that can be used to run the architecture while visualizing the states (like activation patterns or outputs) of some or all of its elements online. These GUIs allow online changes of parameters via control elements (sliders, buttons, and edit fields). The settings of an architecture (its elements, their parameters and the connections between them) can be stored in a parameter file, and the architecture can be created again by loading from this file. The framework uses the JSON format (see www.json.org) to store parameter files, and utilizes the Open Source toolbox JSONlab for saving and loading these files.

As a typical usage of this framework for research in the field of behavioral/neural modeling, we envision something like the following: You start with an idea for a DNF model that performs a certain task. You implement that model in the DNF framework, e.g. by writing a script that creates the required elements and their connectivity, using the provided classes. Then you create a GUI for this architecture, which shows you the activations of all fields and maybe the results of some other operations that go on in each step of the simulation. Add some controls to change inputs to the system and key parameters, and try it out. You may have to do some debugging of the connectivity before the simulation actually runs; the framework provides some tools to assist you here. Then find out whether the architecture behaves the way you expected, at least qualitatively. You may have to change or add some elements or connections before it looks good. In the next step, to get the actual behavior that you want out of the system, tuning of the parameters will almost certainly be necessary. The standard GUI allows you to access all parameters of the elements in your architecture, so that you can change their behavior while the simulation is running. You may also add more controls to have a more direct way to change some key properties. Store the parameter settings that are promising in parameter files as you work on the model. At some point you may want to start running standardized trials with the model, perhaps with some fixed sequence of inputs. You can then move to running the model in an offline mode (without the GUI, though perhaps still with some visualization or analysis as the simulation runs). Just load the architecture from the parameter files and write a script that sets up the desired time course and the necessary analysis of the results. And from here, you can switch between GUI and the offline mode to test the model, analyze its behavior, improve and expand it.

Object-Oriented Programming and Terminology

Working with the DNF framework does not require detailed knowledge of object-oriented programming, and providing such knowledge would be beyond the scope of this document (see the Matlab help for this). We will, however, give a very brief overview of the concepts and terminology of object-oriented programming in Matlab to facilitate understanding of our framework. The central idea of object-oriented programming is to structure the program code (or parts of it) into classes, which combine data structures and functions that act on them. A class in Matlab can be written as a single m-file that contains a class definition, which specifies the name of the class and its relationship to other classes. This class definition is typically followed by a list of persistent variables of this class, called properties. A class can furthermore define functions, which typically act on these properties. These functions are called methods of the class.

To use the class and its methods in scripts or other functions, it is typically necessary to instantiate it – that is, to create an object of that class. This can be done by calling a constructor function for the class, which has the same name as the class itself. The constructor call returns a concrete variable, which contains all the properties of the class (analogous to the fields in a struct). One can access these properties and call the methods of the class via the dot-notation (in the form objectName.propertyName or objectName.methodName(…)). Some properties may not be accessible (or not accessible for writing) except via methods of the class. It is possible and common to instantiate multiple objects of the same class. These objects then have the same structure and offer the same methods, but the content of their internal variables may be entirely different.

The DNF framework strongly relies on so called handle classes: When an object of a handle class is created, it is instantiated in memory and a handle to it is returned as variable in the workspace. This handle allows access to the class’s properties and methods via the dot-notation in the same way as in non-handle classes. However, when copying this variable, only the handle to the existing object is copied, not the object itself. This is similar to graphics handles in Matlab, which can be copied without multiplying the graphics object. The handle class object itself is destroyed when all handles referring to it are removed from the workspace.

We will furthermore use some fixed terms below that are specific to our framework (and not to be confused with general object-oriented programming terminology). In particular, we will refer to the parameters and components of an element. These two terms refer to different types of properties of the element classes, that are distinguished by their role for the behavior of the element, not by their implementation.

Preparing the Framework for Use

To use the framework, clone the repository or download the compressed Matlab sources and unpack them in a folder of your choice. Then add the subfolders base, controls, elements, examples (optional), mathTools, and visualizations to your Matlab path. You can do so manually via the entry Set Path ... in the Matlab File menu (choose Add with subfolders, then save the settings for future Matlab sessions), or call the function setpath in the COSIVINA base directory.

The full functionality of COSIVINA is supported by Matlab R2011a and later. The framework can also be used with earlier versions (back to at least R2009a), but then requires a small adjustment to run: In the file base/Element.m, replace the class definition

classdef Element < matlab.mixin.Copyable

with

classdef Element < handle

(both forms are prepared in the file, just comment/uncomment the appropriate line). With this change, the copy functions of the Element and Simulator classes are no longer functional. Except for this, the framework remains fully functional, including the creation and use of GUIs for interactive simulations.

In order to save and load architecture settings to/from configuration files, you additionally need the Open Source toolbox JSONlab. You can obtain it from https://github.com/fangq/jsonlab The current version of COSIVINA has been tested with JSONlab versions 0.9.1 to 1.0. The location of this toolbox also needs to be added to the Matlab path. The setpath function will do so if a folder jsonlab exists either as a subfolder in the COSIVINA base folder or on the same level as the COSIVINA base folder itself.

To test the toolbox, call one of the scripts from the examples folder. For instance, call launcherOneLayerField.m from the Matlab command line (the launcher... files create a DNF architecture and accompanying GUI and then run that GUI). This should open a GUI window with a running DNF model, in which you can change field parameters and input settings via sliders. Press the Quit button to close the simulation. You can also run the example scripts, which are explained in detail in the last part of this document.