Next: Making realistic neural compartments Previous: Getting started with GENESIS programming Up: Table of Contents

A basic tutorial on using GENESIS

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 which you will use the basic features of the simulator to create and run a simple simulation.

Some Notation

In this guide you will be instructed, at various points, to enter GENESIS commands through the keyboard. This will be indicated by 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 shell command prompt. At the prompt type genesis. If your path is properly configured this should start up the simulator and display the opening credits. If you get a message such as genesis: Command not found, check your path (echo $PATH) to be sure that it contains the genesis directory (often /usr/genesis).

Interpreter Basics

After the simulator has completed its startup procedure you should see the GENESIS command prompt "genesis #0 >" indicating that you are now in the GENESIS interpreter (SLI). In the interpreter you can execute both UNIX shell and GENESIS commands. Try this by typing

    ls

This should invoke the UNIX ls command displaying files in the current directory. Typing

    listcommands

should produce a list of available GENESIS commands. Note that while there are a large number of available commands, you will 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 referred to as elements. Elements are created from templates called "objects". The simulator comes with a number of basic objects. To list the available objects type

    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 to construct parts of neurons. As we will be using this object, try the command showobject compartment at this time. There are a few commonly used objects which are documented more thoroughly with the GENESIS help command. In order to obtain a detailed description of the equivalent circuit for the compartment object, type

    help compartment

(HINT: You may pipe these commands into more to prevent the output from scrolling off the top of the screen.) For example.

    help compartment | more

Creating Elements

To create an Element from an Object description you use the create command. Try typing the create command without arguments

    create

This gives a usage statement which gives the proper syntax for using this command. Most commands will produce a usage statement if invoked without arguments, 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, each element must be given a name. To create a compartment with the name soma type

    create compartment /soma

Elements are maintained in a hierarchy much like that used to maintain files in the UNIX operating system. In this case, /soma is a pathname which indicates 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 with a soma, dendrites, channels and an axon. It would be a good idea to organize these components into a hierarchy of elements such as /cell/soma, /cell/dend, /cell/dend/Ex_channel, and so on. If we do this, we need to create the appropriate type of element for /cell. GENESIS has a neutral object for this sort of use. An element of this type is an empty element that performs no actions and is used chiefly as a parent 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 may delete it with the command delete.

    delete /soma

Examining Elements

The commands for maintaining elements within their hierarchy are very much like those used to maintain files in the UNIX operating system. In that spirit, the commands for moving about within the GENESIS element hierarchy are similar to their UNIX counterparts. For example, to list the elements in the current 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 parameters and state variables used by the element. To show the contents of these data 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 associated with 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 element within the hierarchy which is referred to as the "working element". This location is used as a default for many commands which require path specifications. For example, the le command used above normally takes a path argument. When the path argument is omitted the working element is used and thus all elements located under the working 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 explicit reference 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 working element) command. Try giving the command:

    pwe

Note the analogy between these commands and the UNIX commands ls, cd, and pwd. By analogy with UNIX, GENESIS uses the symbols "." to refer to the working element, and ".." to refer to the element above it in the hierarchy. Try using these with the le, ce, and showfield commands. Likewise, GENESIS has pushe and pope commands to correspond to the UNIX pushd and popd commands. These provide a convenient method of changing to a new working element and returning 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 the setfield 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 new values 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 variable which, 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 initial state. This is done using the reset command, which should be performed prior to all simulation runs.

    reset

If you now show the value of the compartment voltage Vm you will see that 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 simulator to advance a given number of simulation steps.

    step 10

Displaying the Vm field now shows that the simulator actually did something and the value has changed from its initial value due to the current injection.

    showfield /cell/soma Vm

Adding Graphics

Some people find that graphics are more effective than endless columns of numbers in monitoring the course of a simulation. With that in mind we will attempt to add a graph to the simulation which will display the voltage 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 for all 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, forms are hidden when first created. To reveal the newly created form use the command

    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 and a graph but you need some way of passing information from one to the other.

Inter-element communication within GENESIS is achieved through a system of links called messages. Messages allow one element to access the data fields of another element. For example to cause the graph to display the voltage of the cell you must first pass a message from the cell to the graph indicating that you would like a particular data field to be plotted. This is done using the command

    addmsg /cell /data/voltage PLOT Vm *volts *red

The first two arguments give it the source and destination elements. The third argument tells it what type of message you are sending. In this case the message is a request to plot the contents of the fourth argument which is 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 this field. 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 another message

    addmsg /cell /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 a mouse 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 cursor is within the bar and the left mouse button is clicked, the function following the argument -script is invoked. Now add another button to 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 of steps), so "step 100" must be enclosed in quotes so that the argument of -script will be treated as a single string.

At this stage, you have a complete GENESIS simulation which may be run by clicking the left mouse button on the bar labeled RESET and then on the one labeled RUN. To terminate the simulation and leave GENESIS, type either quit or exit. If you like, you may implement one of these commands with a button also.

At this time, you should use an editor to create a script containing the GENESIS commands which were used to construct this simulation. The script should begin with

//genesis

and the filename should have the extension ".g". For example, if the script were named tutorial1.g, you could create the objects and set up the messages with the GENESIS command

    tutorial1

If you have exited GENESIS and are back at the unix prompt, you may run GENESIS and bring up the simulation with the single command

    genesis tutorial1

Next: Making realistic neural compartments Previous: Getting started with GENESIS programming Up: Table of Contents