-*- Mode:Text -*-

RCS: $Id: README,v 1.10 2002/07/02 20:23:35 snwiz Exp $

WHAT IS SNePS ?
===============
SNePS is the Semantic Network Processing System. Its first version was
designed by Stuart C. Shapiro in the early seventies, and it has been
developed since by Shapiro et al. (see the `bibliography.ps' file in the
distribution for a list of SNePS related publications). SNePS is the
implementation of a fully intensional theory of propositional knowledge
representation and reasoning.

Here is a short summary of the major features and components of the current
version of SNePS (aka SNePS-2.3 or SNeRE):

  + A module for creating and accessing propositional semantic networks
  + Path-based inference
  + Node-based inference based on SWM (a relevance logic with quantification)
    that uses natural deduction and can deal with recursive rules
  + forward, backward and bi-directional inference
  + Nonstandard logical connectives and quantifiers
  + An assumption based TMS for belief revision
  + A morphological analyzer and a generalized ATN (GATN) parser for parsing
    and generating natural language
  + SNePSLOG, a predicate-logic-style interface to SNePS
  + XGinseng, an X-based graphics interface for displaying, creating and
    editing SNePS networks
  + SNIP 2.2, a new implementation of the SNePS Inference Package that uses
    rule shadowing and knowledge migration to speed up inference [1].
  + SNeRE, the SNePS Rational Engine, which smoothly integrates
    acting and inference [2].

More information about SNePS, the SNePS Research Group (SNeRG), SNePS-related
papers and projects, etc., is available from our World-Wide-Web site at the
following URL: http://www.cs.buffalo.edu/pub/sneps/WWW/index.html


LICENSING INFORMATION:
======================
Since June 1993 SNePS is free software; you may redistribute it and/or modify
it under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later version.


MAILING LIST:
=============
If you use SNePS please send a short message to <shapiro@cs.buffalo.edu> and
<snwiz@cs.buffalo.edu> indicating that. Please also let us know whether you
want to be put on the SNUG (SNePS Users Group) mailing list. Notices about new
releases and other SNePS related information will be communicated on that
list.


SYSTEM REQUIREMENTS:
====================
COMMON-LISP: SNePS without the optional graphics stuff is written entirely in
Common-Lisp (as defined in Guy Steele's CLtL-I), hence, every proper
implementation of CLtL-I should be sufficient to run SNePS - in theory.
In practice, SNePS runs successfully in the following Common-Lisp
implementations (these Lisps are actually available to me for testing of the
current SNePS release):

  + Allegro CL 4.2      (on Sun SPARCs, SunOS 5.3)
  + Allegro CL 4.1      (on Sun SPARCs, SunOS 4.1.3)
  + CLISP April-95      (on Sun SPARCs, SunOS 5.3)
  + CLISP July-94       (on Sun SPARCs, SunOS 5.3)
  + Sun/Lucid CL 4.0    (on Sun SPARCs, SunOS 4.1.3)
  + CMU Common-Lisp 17b (on Sun SPARCs, SunOS 4.1.3)

Previous versions of SNePS ran successfully (or were reported to run) in the
following Common-Lisp implementations, hence, there is a significant chance
that the current version will run too (or will require only minor
modifications to make it run): 

  + Symbolics CL         (on a 3620, Genera 7.2 or 8.0)
  + TI Common-Lisp       (on TI-Explorers I/II, Rel.6.1)
  + AKCL 1.600 and higher
  + VAX Common-Lisp
  + Allegro CL running on a Macintosh

Visit the Lisp FAQ available on the World-Wide-Web at URL
http://www.cs.cmu.edu:8001/Web/Groups/AI/html/faqs/lang/lisp/top.html to find
out from where you can obtain free Common-Lisp implementations such as CLISP,
CMU Common-Lisp, AKCL, or GCL (GNU Common-Lisp).

OPERATING SYSTEM: Apart from the Lisp machines, all hardware platforms
available to me run some flavor of Unix, but there is no requirement to that
extent - again, in theory. SNePS uses an implementation of logical pathnames
(see below) that hides the underlying operating system pretty well (so far it
only supports Unix, VMS, Symbolics and Explorers, but extensions for DOS
(attractive with the advent of CLISP) or even Macs shouldn't be too hard to
write). The only requirement is the availability of a hierarchical file
system (leniency with regard to filename length will also help).

DISK SPACE: You will need about 10 Megabytes of disk space to install SNePS.
Once you have completed the installation you might be able to trim this to
about 5 Meg by compressing/deleting Lisp source files and/or documentation.

GRAPHICS: An optional X-based graphics interface called XGinseng is
available. XGinseng was written by Martin Zaidel and extended by John Lewocz.
It is built on top of the Garnet Toolkit developed at CMU.  Garnet is now in
the public domain and can be retrieved via anonymous ftp. For instructions on
how to get Garnet read the file `GARNET' in the `Doc' directory. The current
version of XGinseng is tested with Garnet 2.2 and 3.0.  It will not work with
earlier versions.


GETTING SNePS - FTP INSTRUCTIONS:
=================================
To retrieve SNePS via anonymous FTP connect to `ftp.cs.buffalo.edu', login as
user `anonymous' and supply your e-mail address as a password. Then cd to the
directory `/pub/sneps', change the transmission mode to binary and retrieve
the file `sneps-2.3.xx.tar.Z' (fill in the highest `xx' patch level according
to the directory listing). The `README' file and the bibliography and manual
files are all part of the distribution, they are just there separately so you
can get a hold of them without unpacking the complete distribution. See the
following script for more details (done on a UNIX host):

    > ftp ftp.cs.buffalo.edu
    Connected to talos.cs.buffalo.edu.
    220 talos.cs.Buffalo.EDU FTP server (SunOS 4.1) ready.
    Name (ftp.cs.buffalo.edu:snwiz): anonymous
    331 Guest login ok, send ident as password.
    Password:snwiz@cs.buffalo.edu

    230 Guest login ok, access restrictions apply.
    ftp> cd /pub/sneps
    250 CWD command successful.
    ftp> dir
    200 PORT command successful.
    150 ASCII data connection for /bin/ls (128.205.32.11,57490) (0 bytes).
    total 7600
    -rw-rw-r--   1 612      435        17982 Sep 16  1993 COPYING
    -rw-rw-r--   1 612      435         3999 Sep 17  1993 GARNET
    -rw-rw-r--   1 612      435          773 Sep 17  1993 INFO
    -rw-rw-r--   1 612      435        16791 Sep 16  1993 README
    drwxrwsr-x   4 110      436          512 Apr  7 17:28 WWW
    -rw-rw-r--   1 612      435         7863 Oct  8  1993 acl-4.0-patch67.fasl
    -rw-r--r--   1 110      100        25889 Dec  5 19:19 bibliography.bib.Z
    -rw-r--r--   1 110      100        31087 Dec  5 19:18 bibliography.dvi.Z
    -rw-r--r--   1 110      100        51888 Dec  5 19:19 bibliography.ps.Z
    drwxr-xr-x   2 root     ftp          512 Jun 18  1991 bin
    drwxr-xr-x   2 root     ftp          512 Jun 18  1991 etc
    -rw-rw-r--   1 110      100          873 Jul 19  1994 genbib.tex.Z
    -rw-r--r--   1 110      100       292174 Oct 20  1994 manual.ps.Z
    -rw-r-----   1 612      310      1732906 Jan 19  1993 rel-1-308.tar.Z
    -rw-rw-r--   1 612      435      1670798 Sep 17  1993 rel-1-400.tar.Z
    -rw-r--r--  1 612      3012      1923840 Apr 22 10:35 sneps-2.3.1.tar.Z
    
;; 201 ASCII Transfer complete.
    1010 bytes received in 0.97 seconds (1 Kbytes/s)
    ftp> get README
    200 PORT command successful.
    150 ASCII data connection for README (128.205.32.11,1544) (16791 bytes).
    
;; 201 ASCII Transfer complete.
    local: README remote: README
    17134 bytes received in 0.081 seconds (2.1e+02 Kbytes/s)
    ftp> binary
    200 Type set to I.
    ftp> get sneps-2.3.1.tar.Z
    200 PORT command successful.
    150 Binary data connection for sneps-2.3.1.tar.Z (128.205.32.11,1545) (1923840 bytes).
    
;; 201 Binary Transfer complete.
    local: sneps-2.3.1.tar.Z remote: sneps-2.3.1.tar.Z
    1923840 bytes received in 4.1 seconds (4.7e+02 Kbytes/s)
    ftp> bye
    221 Goodbye.
    >

Sorry, you can only retrieve SNePS via FTP, we do not have the manpower to
make tapes.


GENERAL RELEASE INFORMATION:
============================
The tar file you retrieved contains SNePS in its latest release. Details about
how SNePS can be used are contained in the corresponding manual.  SNePS is
written entirely in Common-Lisp, except for graphics packages such as Ginseng
and XGinseng.  The non-Common-Lisp packages are loaded conditionally,
depending on whether a particular Lisp implementation supports them or not.

The `Doc' directory contains LaTeX sources of the SNePS manual, and a
bibliography of SNePS-related papers. DVI and Postscript versions of these
documents are also available.

The `demo' directory tree contains files with various applications of SNePS.
If you type `(demo)' at the SNePS top level you get a menu of available and
working demos. The demos are supplied to give the novice SNePS user a flavor
of how SNePS code can be written. The extensions of the demo file names
correspond to the type of SNePS code of the demo, e.g., `.sneps' means that
this demo contains SNePS code written in SNePSUL, `.snlog' means that this is
a SNePSLOG demo.  Note that not all demos in the `demo' directory work with
the current release of SNePS (only the ones that are shown in the menu
mentioned above are save choices).


RESTORING THE SNePS SOURCES
===========================
Create a directory in which the SNePS installation is supposed to go (you will
need about 10 Meg of free disk space, see the section on system requirements
above), and copy the tar file into that directory.  Then do (assuming the
release is named `sneps-2.3.xx.tar.Z' and a Un*x operating system):

   zcat sneps-2.3.xx.tar.Z | tar xvf -

or

   uncompress sneps-2.3.xx.tar.Z
   tar xvf sneps-2.3.xx.tar.Z

This will install all the SNePS sources with the appropriate directory
structure. Under a non-Unix operating system you will probably need
different commands to unpack the tar file.


INSTALLING, COMPILING AND LOADING OF SNEPS:
===========================================
After you have successfully created the SNePS directory tree on your machine
either follow the quick installation guide in the file `load-sneps.lisp' at
the top level of the SNePS directory tree, or do the following:

Edit the value of the variable `*sneps-directory*' in the file
`load-sneps.lisp' such that it corresponds to the root pathname of the
directory into which SNePS has been copied. Use pathname syntax appropriate
for your machine or operating system.  Do not add a final directory delimiter
(e.g., a slash in Unix or a semicolon on Explorers).  If the Garnet Toolkit is
available on your machine and you want to use XGinseng also edit the value of
the variable `*sneps-garnet-directory*' so that it points to the directory in
which Garnet is installed. If your Garnet installation differs from ours it
might be necessary to add some translations to `*sneps-garnet-translations*'
to map the logical pathnames used in the file
`sneps:xginseng;load-xginseng.lisp' onto the correct physical pathnames.

All Lisp source files in this distribution have extension `.lisp'. If your
Common-Lisp uses a different extension by default you might want to rename all
files accordingly. Renaming is not mandatory, however, if you do choose to
rename the files you have to edit the value of the variable
`*sneps-lisp-extension*' to reflect that change.

Start up Common-Lisp and load the file `load-sneps.lisp'. You will be asked
whether you want to compile the system or just load it.  The first time you do
this select option `e' which will compile and load the whole system plus all
optional systems.

Once you have a compiled version of SNePS you can simply load it by loading
`load-sneps.lisp' and selecting option `a'. If you do not want any interaction
when you load SNePS you can change the value of `*sneps-noquery*' to T.  If
you do not want all the loading messages change the value of `*sneps-verbose*'
to NIL (all these variables are defined in `load-sneps.lisp', see that file
for more customization options).

After the system has been loaded successfully, just type `(sneps)' to start
interaction with SNePS. Type (lisp) to exit it. Type `(snepslog)' to start
SNePSLOG, type `lisp' to exit it.

To check whether your system works properly type `(demo)' at the SNePS prompt
(or `demo' at the SNEPSLOG prompt) and try the various demos. Here are some
approximate run times for the "Schubert's steamroller" SNePSLOG demo on
various Lisps and machines. These times are meant to give you a rough idea
whether your SNePS installation works efficiently or whether you spend 90% of
your time garbage collecting. All times are CPU times in seconds taken from
the value printed after the execution of a SNePS/LOG command. They were
achieved without any compiler optimization, i.e., just normal development mode
was used (where available):

                 SPARC-10/51(50MHz,64Meg) Sun-4/330(25MHz,64Meg) TI Explorer-II
Allegro CL 4.1           35 sec                   96 sec
Sun/Lucid CL 4.0.1       27 sec                   87 sec
Clisp                   110 sec
TI Explorer CL                                                       152
CMU CL                  173 sec (88)             554 sec (303)

The evaluator of CMU Common-Lisp seems to be very slow, hence, the parsing of
the Steamroller formulas which is done by an ATN parser that uses `eval' a
lot is very slow. The times in parentheses are the run times of the inference
alone without the parsing of the problem definition.


Logical Pathnames
=================
SNePS uses logical pathnames throughout in order to define its own system
structure as well as for its various demo files.  If your Common-Lisp already
comes with a native implementation of logical pathnames it tries to use that.
Otherwise, it will use an implementation written by Mark Kantrowitz at CMU.
That currently supports Unix, TI-Explorer, Symbolics and VAX/VMS pathname
syntax. It is a Common-Lisp portable implementation of logical pathnames. It
fulfills most of the X3J13 June 1989 specification for logical pathnames as
documented in Guy Steele's "Common Lisp: The Language" (2nd Edition), section
23.1.5 "Logical Pathnames".

Logical pathnames make SNePS almost completely independent of the particular
file system and location it is installed in. Only the directory variables
mentioned above have to be set to the appropriate pathnames.  For the machines
and operating systems mentioned above, and for popular Common-Lisps such as
Allegro-CL, Lucid(Sun)-CL, AKCL, CLISP, CMU-CL everything should work fine.
If you use some other Common-Lisp that uses special filename extensions for
Lisp or binary files, you might have to edit the values of the variables
`*sneps-lisp-extension*', `*sneps-default-lisp-extension*' or
`*sneps-binary-extension*' in `load-sneps.lisp' (see their documentation for
more details).

If SNePS has problems using the native logical pathname implementation of your
Common-Lisp, you can force it to use its own implementation by setting the
variable `*sneps-use-lpmk*' to T.  If that also fails you can try to modify
`sneps-parse-and-translate-namestring' and friends which are defined in the
file `system-utils.lisp'.  As a last resort, if you cannot get the logical
pathname system to work at all, you can replace all logical with physical
pathnames (most of them reside in the system definition file `system.lisp').


Known bugs, problems, caveats, restrictions:
============================================
- XGinseng requires Garnet 2.2 (or later)
- XGinseng does not work properly with CMU Common-Lisp
- SNePSLOG does not work in Symbolics-CL (Genera-7.2)
- Some of the operators available in SNePS-79 are not yet implemented, e.g.,
  the NON-DERIVABLE operator. Not yet implemented features are pointed out as
  such in the manual.
- Parts of the SNePS code are very ugly (to put it mildly), other parts are
  pretty clean. Keep in mind that this software has evolved over almost 20
  years now, from Franzlisp to Common-Lisp under the hands of many students
  (many of whom learned Common-Lisp while they developed/translated code).
- The SNePS prompt is the same as the CMU Common-Lisp prompt (we had it
  first :-). 


Development history:
====================
The current version of SNePS was mainly developed on a TI-Explorer 
under release 4.1 and release 6. Patches for release 1.0 were developed
under release 6.0, but also on various other Common-Lisp implementations
such as Allegro-CL (3.1.4 Sun 4), Sun(Lucid)-CL (3.0.0 Sun 4) and
Symbolics-CL (Genera 7.2). Since November 1990 the main development machines
are SPARC stations running Sun(Lucid)-CL 4.0 and Allegro-CL 4.1 and 4.2.


Consulting and Maintenance:
===========================
If you have any problems installing SNePS or find any bugs please send
e-mail to <snwiz@cs.buffalo.edu>. If you have to make adjustments to the
SNePS source to install it under your particular Common-Lisp installation
please report them to the above address so future users can also profit from
your adaptations.  Any other suggestions for improvements are also welcome.


Good luck,

Hans Chalupsky <hans@cs.buffalo.edu>

Department of Computer Science, 
;; 201 Bell Hall
State University of New York at Buffalo
Buffalo, NY 14260 USA


References and recommended reading:
===================================
[1] Joongmin Choi: "Experience-Based Learning in Deductive Reasoning Systems",
    Ph.D. Thesis, Technical Report #93-20, Department of Computer Science,
    State University of New York at Buffalo, 1993 (also available as Technical
    Report 93-20)

[2] Deepak Kumar: "From Beliefs and Goals to Intentions and Actions -- An
    Amalgamated Model of Acting and Inference",  Ph.D. Thesis, Department of
    Computer Science, State University of New York at Buffalo, 1994 (also
    available as Technical Report 94-04)

[3] Stuart C. Shapiro: "The SNePS semantic network processing system",
    in "Associative Networks: The Representation and Use of Knowledge by
    Computers", N. V. Findler, editor, Academic Press, New York, pages
    179-203, 1979

[4] Stuart C. Shapiro and William J. Rapaport: "SNePS considered as a fully
    intensional propositional semantic network", in "The Knowledge Frontier",
    N. Cercone and G. McCalla, editors, Springer Verlag, New York, pages
    263-315, 1987

[5] Stuart C. Shapiro and William J. Rapaport: "The SNePS Family", Computers
    & Mathematics with Applications, 23:2-5, pages 243-275, 1992

An up-to-date version of the bibliography of the SNePS Research Group (SNeRG)
can always be obtained from our World-Wide-Web site at the URL
http://www.cs.buffalo.edu/pub/sneps/WWW/index.html.  Otherwise, it can be
retrieved directly via anonymous ftp from `ftp.cs.buffalo.edu' in files
`pub/sneps/bibliography.{bib,ps}.Z' (refer to the SNePS ftp instructions
above). If you cannot retrieve the bibliography via ftp please send mail to
<snwiz@cs.buffalo.edu> or <shapiro@cs.buffalo.edu> and request a copy.



    
    




