Originally written by : Matt Wilson
Tutorial #1
A Basic Tutorial on GENESIS - Constructing a Simple Compartment
This document will guide you through a brief session under GENESIS in whichyou will use the basic features of the simulator to create and run a simplesimulation.
Some Notation
In this guide you will be instructed, at various points, to enterGENESIS commands through the keyboard. This will be indicatedby showing the text that you should enter in a monospaced "typewriter" font.For example:
type this
Getting Started
To run the simulator, first make sure that you are at the UNIX shellcommand prompt. At the prompt type genesis. If your path isproperly configured this should start up the simulator and display the openingcredits. If you get a message such as genesis: Command not found,check your path (echo $PATH) to be sure that it contains thegenesis directory (often /usr/genesis).
Interpreter Basics
After the simulator has completed its startup procedure you should see theGENESIS command prompt "genesis #0 >" indicating that you are nowin the GENESIS interpreter (SLI). In the interpreter you can execute bothUNIX shell and GENESIS commands. Try this by typing
ls
This should invoke the UNIX ls command displaying files in the currentdirectory. Typing
listcommands
should produce a list of available GENESIS commands.Note that while there are a large number of available commands, youwill typically use a much smaller subset of these.It is also possible to combine GENESIS and UNIX shell commands. Typing
listcommands | more
will "pipe" the output of the GENESIS command listcommands through the UNIX command more, thus allowing you to page through the listing.
listcommands | lpr
will "pipe" the output to the printer and
listcommands > myfile
will redirect the output into a file called "myfile".
Basic Objects
The building blocks used to create simulations under GENESIS are referredto as elements. Elements are created from templates called "objects". Thesimulator comes with a number of basic objects. To list the available objectstype
listobjects
To get more information on a particular objects type
showobject name
where "name" is replaced by any name from the object list.
The compartment object is commonly used in GENESIS simulations toconstruct parts of neurons. As we will be using this object, try thecommand showobject compartment at this time. There are a few commonlyused objects which are documented more thoroughly with the GENESIS helpcommand. In order to obtain a detailed description of the equivalentcircuit for the compartment object, type
help compartment
(HINT: You may pipe these commands into more to prevent the output fromscrolling off the top of the screen.) For example.
help compartment | more
Creating Elements
To create an Element from an Object description you use the createcommand. Try typing the create command without arguments
create
This gives a usage statement which gives the proper syntax for using thiscommand. Most commands will produce a usage statement if invoked withoutarguments, or if followed with the option -usage or -help.In the case of the create command the usage statement looks like
usage: create object name -autoindex [object-specific-options]
In this exercise we will create a simple passive compartment. In order to keep track of the many elements that go into a simulation, eachelement must be given a name. To create a compartment with the namesoma type
create compartment /soma
Elements are maintained in a hierarchy much like that used to maintain filesin the UNIX operating system. In this case, /soma is a pathname whichindicates that the soma is to be placed at the root or top of the hierarchy.
We will eventually build a fairly realistic neuron called /cell witha soma, dendrites, channels and an axon. It would be a good idea to organizethese components into a hierarchy of elements such as /cell/soma,/cell/dend, /cell/dend/Ex_channel, and so on. If we dothis, we need to create the appropriate type of element for /cell.GENESIS has a neutral object for this sort of use. An element of thistype is an empty element that performs no actions and is used chiefly as aparent element for a hierarchy of child elements.
To start the construction of our cell, give the commands
create neutral /cell create compartment /cell/soma
As we no longer need our original element /soma, we maydelete it with the command delete.
delete /soma
Examining Elements
The commands for maintaining elements within their hierarchy arevery much like those used to maintainfiles in the UNIX operating system. In that spirit, the commands formoving about within the GENESIS element hierarchy are similar to their UNIX counterparts. For example, to list the elements in thecurrent level of the hierarchy use the le (list elements) command
le
You should see several items listed including the newly created cell.
Each element contains data fields which contain the values of parametersand state variables used by the element. To show the contents of thesedata fields use the showfield command.
showfield /cell *
This will display the names and contents of the data fields of the "cell".The "*" indicates that you wish to display all the data fields associatedwith the element.To display the contents of a particular field, type
showfield /cell/soma Rm
To display an extended listing of the element contents including a description of the object associated with the element, type
showfield /cell/soma **
Moving About in the Hierarchy
When working in GENESIS you are always located at a particular elementwithin the hierarchy which is referred to as the "working element".This location is used as a default for many commands which requirepath specifications. For example, the le command used abovenormally takes a path argument. When the path argument is omittedthe working element is used and thus all elements located under theworking element are listed. To move about in the hierarchy use the ce (change element) command.To change the current working element to the newly create soma, type
ce /cell/soma
Now you can repeat the show command used above omitting the explicitreference to the /cell/soma pathname.
showfield *
This should display the contents of the /cell/soma data fields.You may find the current working element by using the pwe (print workingelement) command. Try giving the command:
pwe
Note the analogy between these commands and the UNIX commandsls, cd, and pwd. By analogy with UNIX, GENESIS usesthe symbols "." to refer to the working element, and ".."to refer to the element above it in the hierarchy. Try using these withthe le, ce, and showfield commands. Likewise, GENESIShas pushe and pope commandsto correspond to the UNIX pushd and popd commands. Theseprovide a convenient method of changing to a new working element andreturning to the previous one. Try the sequence of commands
pushe /cell pwe pope pwe
Modifying Elements
The contents of the element data fields can be changed using thesetfield command. To set the transmembrane resistance of your cell type
setfield /cell/soma Rm 10
You can set multiple fields in a single command as in
setfield /cell/soma Cm 2 Em 25 inject 5
Now if you do a showfield command on the element you should see the newvalues appearing in the data fields.
showfield /cell/soma *
State variables are automatically updated by the elements when they are"run" during a simulation. For instance the Vm field is a state variablewhich, while you can change it, will be updated by the element automatically,replacing your value.
Running a Simulation
Before running a simulation the elements must be placed in a known initialstate. This is done using the reset command, which should be performedprior to all simulation runs.
reset
If you now show the value of the compartment voltage Vm you will seethat it has been reset to the value given by the parameter Em.
showfield /cell/soma *
To run a simulation use the step command, which causes the simulatorto advance a given number of simulation steps.
step 10
Displaying the Vm field now shows that the simulator actually didsomething and the value has changed from its initial value due to thecurrent injection.
showfield /cell/soma Vm
Adding Graphics
Some people find that graphics are more effective than endless columns ofnumbers in monitoring the course of a simulation. With that in mind wewill attempt to add a graph to the simulation which will display thevoltage trajectory of your cell.Graphics are implemented using graphical objects from the XODUS library which are manipulated using the same techniques described above.The "form" is the graphical object which is used as a container forall other graphical items. Thus, before making a graph we need to make a form to put it in which we will arbitrarily name /data.
create xform /data
You may have noticed that nothing much seemed to happen. By default, formsare hidden when first created. To reveal the newly created form use thecommand
xshow /data
An empty box should appear somewhere on your screen. To create a graph in this form with the name voltage use the command
create xgraph /data/voltage
Note that the graph was created beneath the form in the element hierarchy.This is quite important, as the hierarchy is used to define the nesting of the displayed graphical elements.
Linking Elements
Now you have a cell with a soma, and a graph, but you need some way ofpassing information from one to the other.
Inter-element communication within GENESIS is achieved through a system oflinks called messages. Messages allow one element to access the datafields of another element. For example to cause the graph to display thevoltage of the cell you must first pass a message from the cell to the graphindicating that you would like a particular data field to be plotted. Thisis done using the command
addmsg /cell/soma /data/voltage PLOT Vm *volts *red
The first two arguments give it the source and destination elements. Thethird argument tells it what type of message you are sending. In this casethe message is a request to plot the contents of the fourth argument whichis the name of the data field in the cell which you wish to be plotted.The last two arguments give the label and color to be used in plotting thisfield. You can now run the simulation and view the results in the graph.
reset step 100
Note that to plot another field in the same graph, just send anothermessage
addmsg /cell/soma /data/voltage PLOT inject *current *blue reset step 100
and you are displaying current and voltage.
Adding Buttons to a Form
The xbutton graphical element is often used to invoke a function when amouse button is clicked. Give the command
create xbutton /data/RESET -script reset
This should cause a bar labeled RESET to appear within the "data"form below the "voltage" graph. When the mouse is moved so that the cursoris within the bar and the left mouse button is clicked, the functionfollowing the argument -script is invoked. Now add another buttonto the form with the command
create xbutton /data/RUN -script "step 100"
In this case, the function to be executed has a parameter (the number ofsteps), so "step 100" must be enclosed in quotes so that theargument of -script will be treated as a single string.
At this stage, you have a complete GENESIS simulation which may be run byclicking the left mouse button on the bar labeled RESET and thenon the one labeled RUN. To terminate the simulation and leaveGENESIS, type either quit or exit. If you like, you mayimplement one of these commands with a button also.
At this time, you should use an editor to create a script containing theGENESIS commands which were used to construct this simulation. The scriptshould begin with
//genesis
and the filename should have the extension ".g". For example, if thescript were named tutorial1.g, you could create the objects and setup the messages with the GENESIS command
tutorial1
If you have exited GENESIS and are back at the unix prompt, you may runGENESIS and bring up the simulation with the single command
genesis tutorial1Next: Making realistic neural compartmentsPrevious: Getting started with GENESIS programmingUp: Table of Contents
