Walnut  >  Documentation  >  README  >  README

README

$Id: README,v 1.1 2002/07/11 12:58:38 maryniak Exp $


README text file for Walnut/Nutshell - a simulator for neural network paradigms

    Copyright (C) 2000-2002  University of Amsterdam
    Author: Eric Maryniak <e.maryniak@pobox.com>

    The NeuroMod Group on the Web:

        http://static/


Contents
--------

    1. Introduction
    2. Copyright and License
    3. Installation
    4. Documentation
    5. Reporting a bug


1. Introduction
===============
This is the Walnut/Nutshell Neurosimulator, version 1.0.255, based on
the Walnut library, version 1.0.1.
The Walnut Neurosimulation system consists of the following parts:

    o a neural network markup language (NNML), which is to be enhanced
      to a full-fledged XML standard with DTD and Schema definition.

    o a set of libraries (in C++).

    o a development shell, Nutshell. which is a scriptable application
      that runs under Microsoft Windows and allows creation, manipulation
      and visualization of neural network architectures and simulations.

    o a number of neural network paradigms (e.g. Backpropagation,
      Hopfield and MacGregor) that have already been programmed, but
      new user-developed paradigms can easily be added.

The research team includes members from psychology, neuroscience and
mathematics and is led by Prof. Dr. Jaap Murre.

Currently, Nutshell (programmed in Microsoft Visual C++), only runs
on Microsoft Windows. The source is Microsoft Windows dependent.
Nutshell has been tested on:

    o Windows 95, requirement:
      - Internet Explorer 5.5 (Service Pack 1) or higher

    o Windows 98 (all editions)
      - no special requirements

    o Windows Me (Millenium Edition)
      - no special requirements

    o Windows NT (4.0), requirements:
      - Service Pack 6a or higher
      - Internet Explorer 5.5 (Service Pack 1) or higher
      - Install as Administrator, then use as any user

    o Windows 2000, requirements:
      - Install as Administrator or Standard User (=default user)
      - Use as any user except a Restricted User

Notes on specific Microsoft Windows versions and
notes on other operating systems:

- Windows 95
Nutshell runs on 'standard' Windows 95, but often gives problems with
system dll's (dynamic link libraries) and HTMLHelp files, if you are
running the first release of Windows 95 and/or have an old version of
Internet Explorer.
To avoid all these problems, download the latest Internet Explorer from
Microsoft, available at the Microsoft web site at this url:
    http://www.microsoft.com/windows/ie/
On 2001-03-20, it was at version 5.5 (Service Pack 1) and Nutshell works
ok on Windows 95 when this version of Internet Explorer is installed.
You may need to install the so-called 'Plus!' package first in order to
get connected to the Internet and be able to upgrade Internet Explorer.
You should also use Internet Explorer 5.5 (Service Pack 1) if you are
using Windows NT.

- Windows NT 3.5x
Nutshell has not been tested at all on Windows NT 3.5x, but you should
probably follow the same guidelines as for Windows NT 4.0.

- Windows NT 4 and Windows 2000
Because the Nutshell installation program (in the binary release) wants
to install three dll's (MFC42.dll, MSVCP60.dll and MSVCRT.dll) in the
Windows system directory, you need sufficient user priviliges under
Windows NT 4 (Administrator) and Windows 2000 (Administrator or Standard
User) when installing. After installation, you can use it as any user,
except as a Restricted User under Windows 2000.

- Windows XP
Walnut/Nutshell has been tested successfully under Microsoft 'Whistler'
(as Administrator), albeit not exhaustively, so it will probably also
run under Microsoft Windows XP.

- Windows CE
Nutshell has not been tested under Windows CE (for handhelds), but it
can be safely assumed that it will not run on that operating system
without serious modifications.

- OS/2, Linux
Furthermore, Nutshell has not been tested under OS/2 and under Linux
with Wine (a Windows 'emulator', http://www.winehq.com/). It may well
run on those operating systems, because they are capable of running
Windows 9x programs (with varying degrees of success).

Future directions: conversion from C++ to Python.

The Walnut library (directories 'WalnutCore', 'Components/Base' and
'Paradigms/Base'), which is the foundation of Nutshell, is also programmed
in C++, but is platform independent. 
It has been succesfully compiled on Linux with the gcc compiler and also
on Windows NT with the Cygwin port of the gcc compiler (http://cygwin.com/).
Functionally, it will also be the foundation library for a future version
of Nutshell, programmed in Python and called 'NutshellPy'.
NutshellPy will be platform independent and probably use the Tk (Toolkit)
as a platform indenpendant GUI (Graphical User Interface) library
(wxWindows/wxPython is another option).

NutshellPy will use a native version of Walnut programmed in Python,
called WalnutPy.
An attempt to use the C++ Walnut library and wrap it with SWIG
(http://www.swig.org/) failed, due to too many C++ dependencies of the
code that SWIG could not handle directly (although it has the means to
"work around" those, but it was felt that this would take too much time).
WalnutPy makes extensive use of NumPy (Numerical Python) for performance
and also uses DBC (Design By Contract), also programmed in Python.
WalnutPy is functionally equivalent to the original Walnut library in C++
but has more options, has a better design en is easier to use (thanks,
in part, to Python).
A pre-alfa version of WalnutPy is already finished and is being tested,
mainly on performance. So far, the results are very encouraging. Using
paradigms in Python with WalnutPy also drastically simplifies the paradigm
creation process.


2. Copyright and License
========================
See file 'COPYRIGHT' in the top level directory for authoritative
details, but basically it says that all source is free software,
mostly distributed under the GNU General Public License (GPL) -- with
the Walnut libraries under the GNU Lesser General Public License (LGPL) --
and with special exception clauses for some external libraries and source
not developed by us.


3. Installation
===============
For the latest (source) code releases, please visit the Nutshell
home page:

    http://static/nutshell

Walnut/Nutshell is not yet available under Unix, so there is no
configure script. Portable Makefiles are also missing -- the *.mak
files are Microsoft nmake specific.

To install Walnut/Nutshell, you have three options:

    (1) Install a binary-only release.

        This is the easiest way if you want to be up and running quickly.
        Installation is straightforward, because Nutshell is packaged as
        a self-extracting archive that runs a Setup Installation Wizard
        after unpacking automatically like Windows users are used to.

    (2) Build from the Microsoft Visual C++ project files.

        This is also easy, but you will need Microsoft Visual C++ with
        Service Packs (1, 2 and 3) and STLPort installed.
        Download a source code release: a stable, unstable or development
        version, at your option.
        Please refer to 'Doc/internal/QuickStart.txt', which also includes
        a reference to detailed MSVC++ installation instructions, on how
        to proceed next.

    (3) Build from scratch.
        This is the most elaborate way, but may be the only option if you
        are experiencing strange problems or, for whatever reason, you
        want to tinker with the Walnut/Nutshell system itself.
        Please note that if you just want to add a new neural network
        paradigm, it is not necessary to rebuild either Nutshell or Walnut.
        Nutshell automatically detects new paradigms if they have been
        compiled successfully.
        Download a source code release: a stable, unstable or development
        version, at your option.
        You will need Microsoft Visual C++ with Service Packs (1, 2 and 3)
        and STLPort installed.
        Please refer to 'Doc/internal/master-ground-buildup.txt', which
        also includes a reference to detailed MSVC++ installation
        instructions, on how to proceed next.


4. Documentation
================
Please visit the Walnut and Nutshell home page for up to date documentation:

    http://static/walnut
    http://static/nutshell

Unfortunately, documentation is largely missing at the moment.
However, Nutshell has built-in help and tutorials that should at least
answer some basic questions.
We are working hard on a number of manuals targeted at various users:
prospective, beginner, model, research, paradigm developer and general
programmer (porting issues).

Directory 'Doc/internal' contains mostly internal documentation, but
they are of good use, e.g., to build Walnut, Nutshell and paradigms
from source.
For an overview of the documents, refer to 'Doc/README.txt'.


5. Reporting a bug
==================
Please visit the Walnut and Nutshell home page for support questions:

    http://static/nutshell

You will find a FAQ there, online documentation, mailing lists and a
web form to report bugs. Use of this web form is preferred, because
this provides us information in a structured and uniform way, that
we can easily insert in our bug tracking system (based on Bugzilla).

If you want to report a bug by e-mail, send it to:

    memory-bugs@psy.uva.nl


Good luck and have fun with Nutshell!

On behalf of the NeuroMod Software Development Team:

    Eric Maryniak  <e.maryniak@pobox.com>
    Jaap Murre     <murre@psy.uva.nl>


End of README.

$Source: /home/cvsroot/Walnut/C++/README,v $