GENESIS 2.3 Binary Distribution README
CONTENTS
1 QUICK START
2 INTRODUCTION
3 INSTALLATION
3.1 Unpacking
3.2 Site-specific Setup
3.3 Environment Variables
3.4 Running GENESIS
3.5 The GENESIS Neural Modeling Tutorials
4 OPERATING SYSTEM SPECIFIC NOTES
4.1 Cygwin
4.2 Linux
4.3 OSX Darwin
5 PROBLEMS RUNNING GENESIS
5.1 Floating Point Variation
1 QUICK START
cd <install_directory>
tar xzf genesis-2.3-<os>-bin.tar.gz
cd genesis-2.3/genesis
./binsetup
cp .simrc ~
export PATH=$PATH:/usr/local/genesis-2.3/genesis # use 'set' for csh
If it didn't work, you'll have to read on...
2 INTRODUCTION
This distribution includes precompiled versions of both genesis (with XODUS, dependent on X11 installation) and nxgenesis (non-X genesis, without the XODUS GUI, hence no X11 dependence).
If you have a pre-2.0 version of GENESIS and some custom scripts you'd like to keep, you can use the 'convert' utility in the bin directory to update your scripts.
The genesis executables have been linked with certain versions of dynamic libraries. These libraries must be available at run time. See the Operating System Specific Notes below. If have problems running this distribution or want to compile your own version of GENESIS, please get the source distribution from http://sourceforge.net/projects/genesis-sim.
3 INSTALLATION
3.1 Unpacking
Pick the place where you want to install the "genesis" directory tree. If you are making a system-wide installation as "root" user, /usr/local is a good choice. For a personal installation, without root privileges, you can use your home directory ("~"). Change to this directory and extract the genesis directory from the archive file, e.g. genesis-2.3-linux-bin.tar.gz. For example,
cd /usr/local
tar xvzf /mnt/cdrom/genesis-2.3-linux-bin.tar.gz
or from wherever you have it (e.g.~/downloads/genesis-2.3-linux-bin.tar.gz)
3.2 Site-specific Setup
A small setup script should be run to create a GENESIS initialization file (.simrc) which is modified to reflect your installation directory.
cd genesis-2.3/genesis
./binsetup
Then copy the resulting .simrc to your home directory.
cp .simrc ~
3.3 Environment Variables
Finally, add the genesis directory to your search path, so that "genesis" can be found from any directory. If your login shell is bash, do this by editing the .bashrc file in your home directory. For example, if you have installed genesis in /usr/local, add this line:
PATH=$PATH:/usr/local/genesis-2.3/genesis
If you are using tcsh or csh as your command shell, add
set path=($path /usr/local/genesis-2.3/genesis)
to your .tcsh or .csh file.
3.4 Running GENESIS
At this point, you are ready to try running GENESIS. Change into the directory genesis/Scripts and try some of the tutorials suggested in the README file.
If you have any trouble with the installation or execution of GENESIS, read the OS-specific notes below. If you still can't get it to work, please try downloading and installing the source distribution.
3.5 The GENESIS Neural Modeling Tutorials
The genesis/Tutorials directory in the GENESIS distribution is provided as a "place holder" for supplemental hypertext GENESIS modeling tutorials and documentation, including the GENESIS Neural Modeling Tutorials package. These are an evolving set of HTML tutorials intended to teach the process of constructing biologically realistic neural models with the GENESIS simulator. The latest version of this package is offered as a separate download from the GENESIS web site, http://www.genesis-sim.org/GENESIS. The downloaded file (Tutorials.tar.gz or Tutorials.zip) should be unpacked in the genesis directory in order to augment the files that are provided there. The "bare bones" version that is provided with the GENESIS distribution includes a beginner's guide to UNIX/Linux commands that may be useful for those who are new to the command line environment used by GENESIS.
4 OPERATING SYSTEM SPECIFIC NOTES
Statically linked binaries are no longer provided for GENESIS. The main reason for this is that many modern systems can be configured in ways that make it impossible or impractical to provide static executables. In particular, system libraries may have different dependencies based on the flavor or version of the installed operating system.
So, the GENESIS executables have been linked against dynamic libraries creating runtime dependencies as described below.
4.1 Cygwin
Cygwin provides a UNIX-like environment for Windows that will let you run GENESIS and other UNIX programs that have been compiled to run under Cygwin. Go to http://cygwin.com, and look for the "Install Cygwin now" link. This will download a small setup.exe, which will let you choose what to install and then download it. For more information about selecting packages to install, use the link for "Help on setup.exe". For more information on Cygwin, see the Cygwin users guide at http://cygwin.com/cygwin-ug-net/
More information on installing and using X windows with Cygwin can be found in the Cygwin/X User's Guide at http://x.cygwin.com/docs/ug/cygwin-x-ug.html
GENESIS can be run under Windows with the Cygwin software installed. If you want to run GENESIS with GUI capabilities, the X windows package must be installed under Cygwin. The instructions below assume you want GUI capabilities. You should be able to run non-graphical GENESIS (nxgenesis.exe) with a standard Cygwin installation.
Graphical GENESIS requires the following packages (and all their dependencies):
Package Cygwin Category
------- ---------------
coreutils Base*
sed Base
X-startup-scripts X11
xorg-x11-base X11
*Recent versions of Cygwin roll textutils and fileutils into coreutils. If you have an older Cygwin, you may need to install these packages; they are in the Base category.
Go to the Cygwin site (http://www.cygwin.com) and use the "Install or update now!" link to install the setup.exe program. Running setup.exe will lead you through several dialogs and eventually to a list of packages. If there is a version number displayed next to the package under the 'Current' column, that package is already installed. Please see the Cygwin website for further instructions on using the setup.exe program.
More information on installing and using X windows with Cygwin can be found in the Cygwin/X User's Guide at http://x.cygwin.com/docs/ug/cygwin-x-ug.html
You will probably want to install a text editor for editing GENESIS simulation scripts or modifying configuration files. These are found in the Editors category. Text files that are created by UNIX have a different End-Of-Line terminator than Windows text files. For that reason, it is best to use a UNIX editor instead of Windows Notepad for editing GENESIS files. If you are more familiar with Windows than UNIX, choose "nedit". This is an easy-to-use editor with built-in help that will be familiar to users of Windows Notepad. If you are a UNIX user, you may prefer to install emacs or vi (Vim).
4.2 Linux
The linux executables have been linked against gnu libc6 (aka glibc2). Certain libraries will need to be available at run time. Non-graphical GENESIS (nxgenesis) depends on:
libm.so.6
libncurses.so.5
libc.so.6
libgpm.so.1
Graphical GENESIS (genesis) needs these additional libraries:
libXt.so.6
libX11.so.6
libdl.so.2
and possibly:
libSM.so.6
libICE.so.6
Given the variety of Linuces available each with it's own package management system, there's no standard process for installing these libraries. Try to get packages from your OS vendor's web site. You'll need libc6 and X11R6.
4.3 OSX Darwin
The OSX executables were built using Xcode 2.2 tools, based on GCC 4.0.
The binary distribution of GENESIS will only work with OSX 10.2 and higher, on the PowerPC architectures. You'll have to compile the package from source to run on earlier versions or on the Intel architecture.
The non-graphical version of GENESIS (nxgenesis) should run on any standard
OSX installation. Graphical GENESIS (genesis) relies on the X11 libraries for
it's graphical user interface (GUI). An X11 server needs to be started before
graphical GENESIS can be run. If you can't locate the X11 application (usually
Applications->Utilities->X11), see:
http://developer.apple.com/darwin/runningX11.html
for further information.
Starting the X11 application should bring up an 'xterm' window. Graphical GENESIS must be started from the xterm window; it will not work from a window started by the 'Terminal' application.
5 PROBLEMS RUNNING GENESIS
You must be running X11R5 or X11R6 in order to successfully run the graphical GENESIS. Earlier versions will not work.
SGI users: if your X11 server is set up to default to a TrueColor visual and you get X protocol errors running GENESIS, try using the -defaultcolor option on the GENESIS command line.
SGI and HP users: the default font used by some Irix and HPUX X windows implementations is too large for the widgets in many of the simulations. You may modify this by setting X resources, as described in <installdir>/startup/Xdefaults.example.
Problems with XODUS colors: By default, XODUS widgets should have a LightSteelBlue background, with black foreground (text and graphics). If you are getting something else (or want to change these defaults), you can use the Xdefaults.example file described above.
FreeBSD users: Some versions of FreeBSD (ver. 4.3) will run GENESIS simulations and accept input from XODUS dialog boxes, but will not accept input at the genesis prompt in the terminal window. At present, we do not have a solution for this problem.
5.1 Floating Point Variation
Floating point computation may vary based on hardware, operating system, and compiler versions/options. While similar system configurations should reliably produce identical results, systems with different processors, operating systems, and/or compiler options can be expected to show some variation in floating point results. For the Rallpack benchmarks, this will be after the sixth decimal place -- any larger variation should be reported as a bug. Simulations with chaotic behavior and/or long runtimes may potentially have much larger variations.