GENESIS: Tutorial 1

Related Documentation:

Using the GENESIS Shell for
Single Compartment Modeling and Simulation

In this first of two introductory tutorials you will be guided through a brief session under GENESIS. You will be shown how to use basic features of the GENESIS simulator to create, run, save, and explore the output of a simple single compartment model neuron. For example (Note: You can not cut and paste the following code and expect it to run as it is just code “snippets”, however if that is what you want to do, this script provides a working example with some documentation):

    create cell /n  
    create segment /n/soma  
    model_parameter_add /n/soma Vm_init -0.068  
    . . .  
    runtime_parameter_add /n/soma INJECT 2e-9  
    output_add /n/soma Vm  
    run /n 0.1  
    model_state_save /n /tmp/state  
    . . .  
    sh cat /tmp/output  
    . . .

The second introductory tutorial, which can be found here shows how to import, modify, and run a more complex multi-compartment model neuron. Both tutorials assume that you are familiar with the following topics:

Getting Started

To run the simulator, first make sure that you are at a UNIX shell command prompt. At the prompt type “genesis-g3” to start an interactive GENESIS session. If your path is properly configured this should start up the simulator, initiate a session, display the opening credits, and leave you at the GENESIS command line prompt, e.g.

    $ genesis-g3  
    Welcome to the GENESIS 3 shell  
    genesis >

If you get an error message such as Command not found, check your path (“echo $PATH”) to be sure that it contains the directory where the GENESIS shell program is located (often /usr/local/bin).

The remainder of this tutorial assumes that you are working within the GENESIS shell. If you have not done so already, you may wish to begin experimenting with some of the informative G-shell commands such as list commands or the various options for the help command.

Create Model

As the GENESIS User Workflow suggests, a simple single compartment cell model can be created within the GENESIS shell. In this exercise we will create and simulate a passive compartment. How to import an existing model into the GENESIS shell is described in Tutorial 2.

Creating and deleting elements

To keep track of the many elements that go into a simulation each element must be given a name. For example, we can use the create command to create a “cell” element within the model hierarchy and assign it a name

    create cell /n

If the “set_verbose information” flag has been set, the GENESIS shell will respond with

    create_cell: /n

to indicate the successful creation of the named element.

Elements are maintained in a hierarchy similar to that used to maintain files in the UNIX operating system. In the example above, /n is a pathname which indicates that the segment is to be placed at the root or top of the model element hierarchy.

Similarly, we could add a segment to the cell element we have just created

    genesis > create segment /n/soma  
        create_segment: /n/soma

Alternatively, we could delete the entire cell with

    genesis > delete /n  
        delete: /n

Note that the create command only operates on single elements, whereas, the delete command removes all elements in the hierarchy from the last element named in the path.

Setting element values

Once the element /n/soma exists, we can set (1) morphological parameters of the segment such as the diameter (DIA) and length (LENGTH), (2) passive parameters such as the dimensionless specific parameters of membrane resistance (RM), axial resistance (RA), and membrane capacitance (CM), and the leakage voltage (Eleak), and (3) initialize segment parameter values such as the initial membrane potential (V minit), e.g.

    genesis > model_parameter_add /n/soma DIA 2e-5  
    genesis > model_parameter_add /n/soma LENGTH 4.47e-5  
    genesis > model_parameter_add /n/soma CM 0.0164  
    genesis > model_parameter_add /n/soma RM 1.500  
    genesis > model_parameter_add /n/soma RA 2.50  
    genesis > model_parameter_add /n/soma ELEAK -0.080  
    genesis > model_parameter_add /n/soma Vm_init -0.0680

Importantly, remember that GENESIS assumes parameter values are in SI units, which in the case of CM are Farads/m2, for R M Ωtheyarem2, and R A has units of Ω m. GENESIS is able to convert model representations in other units to SI units, but it will be simplest and less error-prone to use SI units from the beginning. For an explanation of the units used in GENESIS, see the document Conversion From Physiological to SI Units in GENESIS 3.

Explore Model

In the case of our simple single compartment cell, the model is most easily explored by checking parameter values. It is particularly useful to check them at this stage in the work flow, to ensure that they have been correctly set. For example to check CM

    genesis > parameter_show /n/soma CM  
        value = 0.0164

We now also demonstrate a powerful new feature of GENESIS. That is, although we have set only the model parameters RM and CM, we can query our model for the membrane time constant TAU (from τ = RMCM). This is possible as, through the Model Container, the GENESIS shell is aware of neuronal morphology, membrane, and intracellular parameters. The Model Container can infer a number of properties about an element and it will calculate and provide derived parameter values when the GENESIS shell is queried. This is made possible by the hierarchical relations maintained by the Model Container between an element and its parents, children, and sibling’s parameters. For example,

    genesis > parameter_show /n/soma TAU  
        value = 0.0246

Save Model

Saving a model is as simple as issuing the “ndf_save” command with an associated model and file name, e.g. for our example

   genesis > ndf_save /n  myneuron.ndf

The model is then saved in the NDF format. The default location for ndf_save (as given in the above example) is the directory where you started GENESIS. However, the file can be saved at another location by giving the absolute path, e.g.

   genesis > ndf_save /n /tmp/myneuron.ndf

Alternatively, the current model could be saved to STDOUT (i.e. it will appear on the screen at the GENESIS prompt) with

   genesis > ndf_save /** STDOUT

Here, the construct /** is a wild card that expands to describe the current model. It is useful if the name of the model is not known.

Once a model has been saved, the next time GENESIS is run the file can be loaded into the G-Shell with, for example,

   genesis > ndf_load myneuron.ndf

Note that the name of the model (/n) is not given. It is contained within the NDF file.

Define Simulation Constants

The GENESIS shell distinguishes between model parameters such as those used to build our simple single compartment model, i.e. those generated above by the create command, and parameters that do not alter the model but only affect model behavior at run-time during a simulation. For example, the maximum conductance of the CaT channels located in the soma is specified as a model parameter because it is defined in the model. However, it and other model parameters may also be treated as run-time parameters. This allows them to be modified during a simulation run without changing the default values in the Model Container. However, as in this introductory tutorial we have constructed only a passive compartment, a description of how to define simulation constants is delayed until the corresponding section of Tutorial 2.

Define Simulation Inputs

Simulation inputs typically involve synaptic activation. However, as in this introductory tutorial we have constructed a passive compartment, a description of how to define synaptic activation is delayed until Tutorial 2.

Define Simulation Outputs

Having created a passive neuron, we can now define the output, typically the membrane potential (V m)

   genesis > output_add /n/soma Vm

By default, simulation output is placed in the file /tmp/output, where it can be viewed following termination of the simulation. Alternatively, the path (relative or absolute) and filename may be set using the output_filename command, e.g.:

   output_filename /tmp/myneuron_Vm.out

Check Simulation

After a simulation has been set up it is a good idea to check its integrity to ensure that the software modules required to run the simulation will be correctly recruited at run-time. For our simple passive neuron model this is done with

    genesis > check /n

Run Simulation

To run our single compartment model for 10 ms enter

    genesis > run /n 0.01

The simulation can then be continued by entering the run command again (this time for 1 s cf. the previous 10 ms)

    genesis > run /n 1.0

The default location and file name for simulation output is /tmp/output. To view simulation output from the G-Shell enter

    genesis > echo output follows:\n  
    genesis > sh cat /tmp/output

Note: With the exception of cd, the G-Shell recognizes many simple Unix commands when they are prefixed by sh.

Reset Simulation

At some stage during a GENESIS session you may want to return a simulation to the initial state that existed prior to any run command being issued. The “reset” command will set the time step of the simulation to zero and load the initial values for all solved variables, e.g.

    genesis > reset /n

Save Model State

There are several commands associated with the ability to start, stop, or continue a simulation. Importantly, the default state of the GENESIS shell is for the run command to continue a simulation using the state of a model at the end of a given simulation as the initialization state for the next run command. This allows multiple run commands to be issued within a single GENESIS session and makes it possible to change the state of a simulation between runs as the output of each simulation is appended to the file /tmp/output. It also means that a record is kept of the output of all simulations run within a single GENESIS session. This is useful if you want to change the run-time parameters of a simulation or check the output of a model during testing.

It may also be convenient to start a simulation from a predefined state. To do this, the state of the simulation is saved to a file name of your choosing. For example,

    genesis > model_state_save /n <file name>

saves the state of the model following the last update time step of a run to a file with the given name. A simulation can then be initiated from this saved state with the command

    genesis > model_state_load <file name>

The next run command will then start the simulation from this reinitialized state. Such functionality provides a convenient way to save different states of a simulation. In particular, it is useful for initiating a simulation following a startup period, thereby eliminating the continual rerunning of a simulation through startup calculations. Also, as a model only exists in memory for the duration of a GENESIS session, the simulation_state_save command is the only way that the state of a simulation can be saved between GENESIS sessions.

More generally, the GENESIS shell is not intended for creating anything but the simplest of models, such as the example given in this tutorial. As you can probably imagine, it would require considerable effort to create a realistic multi-compartment neuron model with comprehensive morphological, membrane, and channel descriptions if it had to be entered into the GENESIS shell one variable at a time. It is for this reason that the declarative model specification of the GENESIS .p cell descriptor file has been extended to cover biological levels other than just cellular morphology, e.g. intracellular mechanisms and network models.

Check Simulation Output

Simulation output (in the default location) can be checked with the following command:

   genesis > sh cat /tmp/output

This will print the values in /tmp/output to the screen. Alternatively, the values in the file may be plotted with a utility such as the G3Plot package.

Note: Most common UNIX shell commands can be run in the G-Shell if passed as arguments to the sh command.

The next and second of two introductory tutorials (Tutorial 2) deals with use of the GENESIS shell with a multi-compartment model neuron. It employs a pre-existing model, the De Schutter and Bower (1994) Purkinje cell.