NESim Help

Neural Engineering Simulator (NESim) Help
Simulation Syntax: How to define a system to simulate. This section describes the text file (.txt) format structure used to define circuits that can be compiled into a form that is used by the simulator. This section is divided into four parts. The first presents a simple example and describes the elements that must be present in any simulation definition. The second discusses the compiling procedure. The third describes what is needed to define transformations between populations. The fourth discusses the definition of complex transformations. A Simple Example The simplest possible circuit consists of an ensemble that represents a scalar that is driven by an external signal. The text file for creating this circuit is: %% Simplest possible circuit 1 Data File 1 X_N100D1 %% Connections Inputs to 1 External Signal 1 End The structure and meaning of each line in this file is given below Line 1: Optional: This is an example of an optional comment. Comment lines begin with the % sign. Line 2: Required: The number of neuronal ensembles in the circuit is read from the first integer that occurs in this line. Line3: Required: Following the ensemble number there has to be $N_{ens}$ lines that relate each ensemble number to a Matlab data file generated by the ensemble generator. The format for each line is: # Name_N##D# The line must start with an ensemble number followed by the file name (without the extension '.mat'). The ensemble numbers must be in sequential order. Optional parameters that define functional outputs are put in lines that follow each data file. This is described below. Line 5: Required: The inputs to each neuronal ensemble are defined by a line that states which ensemble gets the input. This line must start with the word "[In]puts'' followed by the ensemble number. The ensemble numbers must be in sequential order and all ensembles must get at least one input. There are 3 classes of inputs. "Ext[ernal] #" signal inputs followed by the signal input number. "Out[puts] #" from other ensembles to this ensemble, with output ensemble numbers given (including recurrent connections). "Fun[ction] #", functional output from other ensembles to this ensemble, with output ensemble numbers given. The outputs and functional connections must be accompanied by a coupling matrix as discussed below. No coupling matrix is allowed for external signals. Line 7: Required: The word "End", that terminates the file. Notes: Word case is ignored and blank lines are skipped. Words following key words are ignored as comments. In summary, all simulation txt files must have An integer on the first line that is not a comment. All the words on this line are ignored. A sequential list of the ensemble data files. All words after the data file are ignored. A sequential list of each ensemble and its inputs. The word 'End'. These are compiled into Matlab .mat files that are used by the main simulator. The program setupsim tries to catch syntax errors and provides hints as to the problem it occured. It also provides a description of the circuit. Compiling the Simple Example This text file is compiled by pressing the 'Setup Sim' button in the GUI. The program responds with this information in the main Matlab window: Ensemble 1: X_N100D1; N=100, D=1, Model Type 2 *****Connections***** Ensemble 1: gets input from external 1 *****Success***** Saved ..\NeuronData\simplest.mat The compiled file 'simplest.mat' is saved in the same directory as the .txt file. This directory must hold all the simulation data files, including: the ensemble data file 'X\_N100D1.mat', the text file 'simplest.txt', and the output file 'simplest.mat' Transformations Between Ensembles Following the list of data files and their numbering, the coupling between the ensembles is defined by listing, in sequential order, each ensemble followed by a list of the inputs. The following example demonstrates how this is done for adding two vectors. Number of Ensembles 3 1 X_N100D2 %% (X) 2 Y_N100D2 %% (Y) 3 Z_N100D2 %% (Z) %% Connections Inputs to 1 (X) External 1 Inputs to 2 (Y) External 2 Inputs to 3 (Z) Output from 1 Coupling Matrix 1.0 0.0 0.0 1.0 Output from 2 Coupling Matrix 0.0 -1.0 -1.0 0.0 End This example computes the following: The ensemble getting the inputs is specified by the keyword [In]puts followed by its index number. Any words after the word 'inputs' are ignored, as are words after the number. The numbers must appear in sequential order and all ensembles must get at least one input. As mentioned earlier, following each input line is a list of the inputs, which can be of three types: "Ext[ernal] #" signal inputs followed by the signal input number. "Out[puts] #" from other ensembles to this ensemble, with output ensemble numbers given (including recurrent connections). "Fun[ction] #", functional output from other ensembles to this ensemble, with output ensemble numbers given. The outputs and functional connections must be accompanied by a coupling matrix, while a coupling matrix is not allowed for the external signals. The word Mat[rix] must follow a line that starts with Out[puts] \#: or Fun[ction] \#:. Subsequent lines then specify the coupling matrix, where each row specifies the inputs to each component of the vector of the ensemble receiving these inputs. So if the input space is 1 dimensional and the output space is 3 dimensional, this matrix would consist of three numbers on a single line, Matrix 1.0 -0.5 0.1 while in the reverse case, the matrix would consist of 3 numbers on sequential lines. Matrix 1.0 -0.5 0.1 If the dimensions of the two spaces are the same, and if the coupling matrix is a constant times the identity matrix, then the matrix can specified by the constant value. Matrix 2.0 Defining More Complex Transformations Optional output functions are defined in the lines following each ensemble data file. Polynomials up to order 5 are supported for scalars, while only up to second order forms are supported for vector spaces. When the ensemble represents a scalar, the output functions are polynomials of up to order 5: An examble of a polynomial definition is 1 X_N100D50 Polynomial %% or Poly by itself 0.1 0.5 -1.0 -2.0 1.0 %% a0 a1 a2 etc. (Max of 6 terms) which computes the polynomial You can specify less than 6 terms, those you leave out will be assumed to be zero. It is possible output more than one polynomial: Ensemble 1 X_N100D50 Poly 0.1 0.5 -1.0 -2.0 1.0 0.0 0.0 1.0 0.0 0.0 In this case the second polynomial is x^2. The number of coefficients specified in each line must be less than or equal to 6, and the number given in each line must be the same. When connecting ensembles, the dimension of the functional output space must be taken into consideration. In the above example it is 2, even though the output of the ensemble is a scalar. Functional outputs for vector spaces are of the form: These are specified as: 3 Z_N100D3 %%% A 3 dimensional space Const %% Or Constant or Con 1.0 Linear %% Or Lin -0.1 0.3 3.0 Quad %% Or Quadratic or Bilinear, 1.0 0.5 0.1 0.0 2.0 0.3 0.0 0.0 3.0 which defines the function The default values of the 'Const', 'Linear', and 'Quad', terms are zero, so if all the values in any set are zero they do not need to be specified. For example, one can drop the 'Const' and 'Quad' terms if the output function is linear. The dimensions of the various coefficients must match the dimension of the vector space. Since the off diagonal elements of the quadratic matrix add to give , it is best to make the matrix triangular to prevent confusion. Multiple functions are defined in the following example: 1 W_N200D3 Const 1.0 -1.0 Linear 1.0 1.0 0.0 0.0 1.0 0.0 Quad 0.0 1.0 0.0 ; 0.0 0.0 0.0 0.0 0.0 0.0 ; 0.0 1.0 0.0 0.0 0.0 0.0 ; 0.0 0.0 0.0 The two functions in this case are The list of constant values are specified on a single line, the linear coefficients one line at a time, and the multiple quadratic matricies are separated by a semi-colon, colon or comma.