GENESIS - README

This directory contains the August 1997 distribution of GENESIS, version 2.1 in the compressed tar file genesis.tar.Z (a link to genesis2.1.tar.Z). If you have the gnu utility gunzip, you my download the smaller, more highly compressed version, genesis.tar.gz (a link to genesis2.1.tar.gz).

If you experience any trouble compiling or running GENESIS, be sure to see the README file in the Bug-fixes directory. The LATEST.NEWS file also contains information on recent developments and changes.

Versions 2.0 and later represent a major revision of GENESIS from the earlier GENESIS 1 version (1.4.2). If you have used a previous version of GENESIS, please read the file genesis/Doc/Changes.doc in the GENESIS distribution.

Parallel GENESIS

This directory also contains a much improved release of Parallel GENESIS (PGENESIS 2.1), designed for networks of workstations (NOW), symmetric multiprocessors (SMP) and massively parallel processors (MPP). This release, which replaces the experimental version which was previously available on this site, can be run on any platform which supports GENESIS 2.1 and the PVM (Parallel Virtual Machine) software. PGENESIS 2.1 has been tested extensively on IRIX 5.3, Digital UNIX, Unicos/mk (Cray T3E). It has been run on SunOS, Solaris, Linux, HPUX and Intel Paragon.

Parallel GENESIS is expected to be of use for simulations which must be run many times independently e.g., parameter-search, monte-carlo. It will also be of use for large scale models that do not fit in the memory of a single workstation, especially network models. The primary user-level changes are the extension of the script language to include some parallel programming constructs, the provision of GENESIS messages to cross cpu boundaries, and the use of the PVM parallel software layer.

If you wish to compile the parallel libraries for GENESIS, you will need to download the following files, in addition to the GENESIS 2.1 distribution:

If you do not have the gnu gunzip utility, you may download the larger files with the ".Z" extension which werre produced with UNIX compress.

Please see Readme.pgenesis and the README file and hypertext documentation in the PGENESIS distribution for further information about PGENESIS.

GENESIS Description

GENESIS is a general purpose simulation platform which was developed to support the simulation of neural systems ranging from complex models of single neurons to simulations of large networks made up of more abstract neuronal components. GENESIS has provided the basis for laboratory courses in neural simulation at Caltech, the Marine Biological Laboratory in Woods Hole, MA, the Crete Course in Computational Neuroscience, and at least 34 universities of which we are aware. Most current GENESIS applications involve realistic simulations of biological neural systems. Although the software can also model more abstract networks, other simulators are more suitable for backpropagation and similar connectionist modeling.

Machine dependence

GENESIS and its graphical front-end XODUS are written in C and run under UNIX on Sun (SunOS 4.x or Solaris 2.x), DECstation (Ultrix), Silicon Graphics (Irix 4.0.1 and up) or x86 PC (Linux or FreeBSD) machines with X-windows (versions X11R4, X11R5, and X11R6). DEC Alphas (OSF v2 and v3) IBM RS6000s (AIX) and HPs (HPUX) have been successful in compiling and running, though our experience is limited. We have received reports of use of GENESIS on the Power Macintosh with the current (ver. 2.1) developers release of Mac Linux, but have not tested it ourselves. We welcome feedback on experiences with these platforms.

Other platforms may be capable of running GENESIS, but the software has not been tested by Caltech outside of these environments.

GENESIS Tutorials

In addition to demonstrations which illustrate GENESIS features and techniques for programming simulations, the genesis/Scripts direcctory contains a number of interactive tutorials for teaching concepts in neurobiology and neural modeling. As their use requires no knowldge of GENESIS programming, they are suitable for use in a computer simulation laboratory which would accompany upper division undergraduate and graduate neuroscience courses. Each of these has on-line help and a number of suggested exercises or "experiments" which may be either assigned as homework or used for self-study. These tutorials may also be taken apart and modified to create your own simulations, as they are reasonably well commented. Several of them are derived from existing research simulations.

These tutorial simulations form the basis of Part I of "The Book of GENESIS" by James M. Bower and David Beeman, published by TELOS/Springer-Verlag. Part II is intended to teach the use of the GENESIS script language for the construction of one's own simulations. This part will be useful for self-study by researchers who wish to do neural modeling, as well as by students.

Improvements and New Features in GENESIS 2.1

In addition to many bug fixes, these are the most significant new features of GENESIS version 2.1:

There are now two-dimensional versions of the tabchannel and table objects (tab2Dchannel and table2D) which will be useful for modeling voltage and concentration dependent channels. The tabcurrent object, along with the setupNaCa and setupghk commands, may be used to model non-ohmic currents, and can also be used to compute the solution to the Goldman-Hodgkin-Katz equation.
The kinetics library for modeling biochemical kinetics reactions has been integrated with GENESIS 2.1, allowing use of the Kinetikit graphical toolkit, which is also included.
The diskio, variable, and metadata objects may be used to provide the features of the existing disk_in and disk_out objects to read and write data in the portable binary NETCDF format. This will ease the interfacing of GENESIS simulations with popular analysis and signalprocessing tools such as MATLAB, and make it possible to use binary files produced by GENESIS on multiple platforms.
There is a new version of the library (``genesis/src/concen'') of objects which are used to model the effects of the diffusion of ions (e.g., calcium).
There have been substantial improvements in the hsolve object, which is used to maximize the speed and accuracy of computations for compartmental models. The chanmodes have been reorganized to present a progression from most general/least restrictive/slowest to most restrictive/fastest. The default mode of use (chanmode 0) has been revised so that it is possible to easily add and delete outgoing messages to other elements, and to use it with any elements whether or not they are handled by hsolve. There is a new mode (chanmode 4), and some changes in the restrictions of the other modes. These are explained in detail in the revised documentation for hsolve. A new command findsolvefield has been provided to make it easy to accesss fields of the hsolve element when using these faster chanmodes, thus avoiding their restrictions on input and output of field values. The useconcen and usenernst fields of the hsolve object have been removed, as they are no longer needed. A new restriction is that, for chanmodes 2-4, the element tree of your cell (or other element tree to be taken over by hsolve) must not contain any non-hsolvable elements other than neutral elements. For existing simulations which violate this restriction, it will be easiest to switch to chanmode 0 or 1.
The readcell command and the hsolve object recognize the new concentration and channel objects. Both readcell and hsolve may be used to create an hsolve element instead of a neutral element at the root of the cell hierarchy.
Compartments now have both start and end coordinates, making it easier to determine the orientation of cylindrical compartments. This change does not require any changes to scripts or cell parameter files.
XODUS forms can now be nested, allowing for grouping of widgets within a form using a nested form.
Several changes have been made to allow parallel GENESIS 2.1 (PGENESIS) to be built on top of GENESIS 2.1.
The randomspike object now gives the average firing rate which is specified by the "rate" field, when the "abs_refract" field is greater than zero. Previously, the effective firing rate was not adjusted to make up for the prohibited spike events which would have occurred during the absolute refractory period. Thus, earlier versions of randomspike would produce a lower average firing rate than the requested one, if the "abs_refract" field was greater than zero. (A non-zero value of "abs_refract", would be used if a randomspike element were used to represent the random background firing of a single cell, rather than the converging input of many cells.) Further details are given in genesis/src/CHANGES.
The spikehistory object outputs the times of spike events to a text file.
Postscript output now compresses long sequences of horizontal and vertical lines into a single output line. This can significantly compress the size of postscript files produced for spiking output.
The main Makefile has been simplified considerably.
The GENESIS Reference Manual has been updated. As before, it exists in three versions: GENESIS on-line help (Doc/*.doc), Hypertext help (in Hyperdoc), and postscript files (in Doc/Manual.tar.Z). The file Doc/README.changes lists the documentation files which have been added or revised.

GENESIS Users Group (BABEL)

Due to the large number of requests for GENESIS, we only able to provide minimal help or support for those who acquire GENESIS through the ftp site described above. Therefore, we strongly encourage serious users of GENESIS to join the GENESIS Users Group, BABEL. Members of BABEL are entitled to access the BABEL directories and email newsgroup. These are used as a repository for the latest contributions by GENESIS users and developers. These include new simulations, libraries of cells and channels, additional simulator components, new documentation and tutorials, bug reports and fixes, and the posting of questions and hints for setting up GENESIS simulations. As the results of GENESIS research simulations are published, many of these simulations are being made available through BABEL. New developments are announced in a newsletter which is sent by email to all members. BABEL operates from an Internet accessable SUN SPARCstation 2 at Caltech. Members are able to access the BABEL directories and transfer files to and from their host machines using ftp.

We have recently discontinued the requirement of a registration fee for BABEL membership. Now, all that we require is some assurance that you have a serious interest in using the GENESIS simulator. If you have not yet tried GENESIS, please try some of the demonstration simulations and tutorials, in order to determine if GENESIS is suitable for your purposes. If you then feel that membership in BABEL will be useful to you, you may apply for membership by sending the following information to babel@bbb.caltech.edu:

Your name, institution, mailing address and phone number (optional), the email address at which you would like to receive communications from BABEL, and a description of your present or intended uses of GENESIS. Although this description need not be lengthy, please try to be as specific as possible in your statement of what types of models you intend to construct with GENESIS. If you have used GENESIS in teaching or research in the past, we would like to hear about it, with references for any publications or conference papers related to your use of GENESIS.

NOTE: If more than one person in your group is using GENESIS, you may wish to set up a local mail alias to a list of people who would like to receive BABEL news mailings. This will allow us to have a single email address on our mailing list, yet assure that everyone who uses GENESIS will get the mailings.

After your registration has been accepted, we will add you to the BABEL mailing list, and send you information on accessing the BABEL archives and posting to the BABEL newsgroup.

Installation

The first step is to download the file 'genesis.tar.Z', or if you have the gunzip utility, the smaller file 'genesis.tar.gz'. This may be done via the GENESIS WWW page (http://www.bbb.caltech.edu/GENESIS) or by anonymous ftp to genesis.bbb.caltech.edu.

When using ftp, give the username "anonymous" and your email address as the passwoed. Then, give the ftp command "binary". Then, give the command "get genesis.tar.Z". The file may take a while to transfer if you do this at a time when networks are busy. If you have the gnu "gunzip" utility, you may get the smaller file "genesis.tar.gz", instead. You may download the parallel library files in a similar manner. Finally, give the "quit" command.

Next, change to the directory in which you wish the GENESIS directory tree to reside and give the unix command "zcat genesis.tar.Z | tar xvf -". This will create the directory 'genesis' and a number of subdirectories. Begin by reading the README file in the 'genesis' directory.

If you have downloaded the file genesis.tar.gz instead, it should be uncompressed with the gnu "gunzip" utility, then extracted with tar. This can be done with:

Note that genesis.tar.gz *cannot* be uncompressed with the UNIX compress utility. If you do not have gunzip, use the genesis.tar.Z file, instead.

Directions for compiling and installing the software may be found in the README file contained in the 'src' subdirectory. Also, be sure to carefully read the comments in src/Makefile. Directions for printing and using the documentation may be found in 'Doc/README'. The 'Scripts/README' file describes the demonstration and tutorial simulations which are included with this distribution.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the California Institute of Technology not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. The California Institute of Technology makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Some components are copyright by the originating institution and are used with the permission of the authors. The conditions of these copyrights (none of which restrict the free distribution of GENESIS) appear with these modules.