File: SUMMARY
Author: Heinz Schmidt (hws@ICSI.Berkeley.EDU)
Copyright (C) International Computer Science Institute, 1991
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 


        IIIII   CCCC   CCCC  IIIII  MM  MM        The ICSI ARTIFICIAL
          I    C      C        I    M MM M        
          I    C       CCC     I    M    M        NET SIMULATOR
          I    C          C    I    M    M
        IIIII   CCCC  CCCC   IIIII  M    M          


Designed by    Heinz Schmidt / Jerome Feldman / Ben Gomes
Implemented by Heinz Schmidt / Ben Gomes

State of Doc: 9/7/91

----------------------------------------------------------------------
                               OVERVIEW
----------------------------------------------------------------------
Goal: 
        Support some novel AN concepts, especially, 
              * modular architectures
              * shared structures (e.g. shared weights)
              * unsupervised learning

        Provide simple means to extend/add
              * types of neural networks
              * types of neuron models

        Permit interactive and non-interactive
              * construction of networks
              * change of size and restructuring of networks
        
Means:
        Shift (conceptual) focus 
              * from units to nets
              * from global & sequential execution to
                local & asynchronous execution

        Combine flexibility of object-oriented design 
              with efficiency by              
              * virtualization of structures (e.g. virtual connections)
              * parallel execution (granularity: nets)
              * dedicated processing (e.g. downloading nets to RAP)

Target group: 
        AN scientific community, teaching AN
              * from (almost) non-programmer expert connectionist
                (moderate extensions, no user-interface programming)                
              * through programming expert connectionist 
                (all classes accessible and changeable)
        
Programming language:
        The Sather language, the ICSI public domain OO language

Programming environment:
        The Sather language environment.

----------------------------------------------------------------------
                           MORE ABOUT ICSIM
----------------------------------------------------------------------


For an overview of existing directories read on.

The current ICSIM design is documented in:

   Heinz W. Schmidt and Ben Gomes: "ICSIM -- An Object-Oriented 
        Connectionist Simulator", ICSI TR 91 048 1991

If your not familiar with Sather you may consult:

   Stephen M. Omohundro: "The Sather Language." ICSI 1990
   Heinz W. Schmidt and Stephen M. Omohundro: "CLOS, Eiffel and Sather: 
          A Comparison.", ICSI TR 91 047 1991
 
   Postscript versions of the above reports are available by anon ftp
   from icsi-ftp.berkeley.edu  /pub/techreports.

   To setup your Sather environment follow the instructions in the 
   <SATHER>/doc/GETTING_STARTED file. (Consult your system administrator
   for the location of the <SATHER> directory.)

If you are familiar with Sather and the Sather programming
environment, the best way to 'look' at the design is to browse the
corresponding Eiffel libraries using the Sather programming
environemnt based on GNU Emacs. You can see the class hierarchies
and get a quick class and feature reference documentations. You can
move between classes and from calls to definitions and vice versa.


 
----------------------------------------------------------------------
                          WHERE TO FIND WHAT
----------------------------------------------------------------------

Here is a short map of the file system tree to the extent that an
ICSIM user may ask 'where is ..' or may want to know more about 'what
is ..' when s/he's browsing through the system.



.sather                 -- sample .sather file

.sather_debug           -- independent debug options included by .sather

.sa_uicsim              -- independent ui source file listing optionally included by .sather

README                  -- this file

TAGS,TAGS.compl         -- if present, Emacs sather-tags browser xref files

bkup                    -- various backup versions of simulator classes

doc                     -- more docuemntation on ICSIM        

examples                -- various examples nets, see the README file there for
	                   how to compile examples.

icsim                   -- a link to this directory to make the relocatable
                           .sather work here, so we can run Emacs sather-tags
                           on this directory and get browser xref for all ICSIM

io                      -- I/O classes

models                  -- the model classes

test                    -- test executables

ui                      -- user interface classes


----------------------------------------------------------------------
                          MAINTENANCE HINTS
----------------------------------------------------------------------

Backup versions (bkup) are not group writable.

All current simulator files are group writable. The current group at ICSI is
"labusers". 

The top-level .sather file is relocatable by refering to ./icsim
When it is copied a symbolic link to the <ICSIM> directory named icsim
will make the currenct directory (whereever the link is placed)
work with that .sather file. 

Alternative you can suggest users to write a small .sather file
that (include)s the top-level .sather file and contains only user
(source_file)s. The (include) files called upon by the top-level
.sather file do not refer to the ./icsim directory. So they
can be redefined in the current user directory. Since most of the 
time only the debug keys change while one is developing a single
system, this is the only include file mentioned by .sather.

Testing after changes should include compiling all tests (all_tests)
and then compiling and running some of the tests. Compilation should
include the conservative debug_key setting in .sather_debug that
includes various type checks and should also use the -chk option.

[The following hint may be obsolete now that -chk produces a trace
back.  However the sdb story is still a good programming trick to
start poking for where and why the error occurs. Most likely you will
know this.]

When cs -chk tells about an error, it often does not refer to the
"right" place. For instance an erroneous use of a library routine may
be trapped at the point where a precondition is checked.  The error
may be far up in the recursion where some parameter originates.  Until
exception handling is available in Sather, one may use sdb to run into
the error and then type "where" to get a traceback. Some of the
runtime system exits do not signal an error but terminate the
program with a return code. If sdb does not allow to look at the stack
after this exit, one may redefine the corresponding runtime check
routine that prints out the error by a (c_macro) in the .sather file
that essentially copies the current C function for error reporting
on runtime check violations (err_quit_ currently) and have it
signal an error instead of using exit.

