+------------------------------------------------------------------------------+
|                                                                     3/17/88  |
|                             C L - P R O T O S                                |
|  --------------------------------------------------------------------------  |
|                                                                              |
|  CL-PROTOS is a Common Lisp reconstruction of the research version of the    |
|  Protos exemplar-based learning apprentice conceived by E. Ray Bareiss and   |
|  Bruce W. Porter of the Artificial Intelligence Laboratory at The University |
|  of Texas at Austin.  Protos was originally developed as an experiment in    |
|  knowledge acquisition for heuristic classification tasks.                   |
|                                                                              |
|  The original research version of Protos was written in Prolog.  This        |
|  Common Lisp implementation is a reconstruction, not a Prolog-to-Lisp        |
|  rewrite.  Thus, CL-Protos differs from the original Protos in several       |
|  places, but mostly by intention.  Ray Bareiss had a consulting role in      |
|  this reconstruction and suggested many of the changes.                      |
|                                                                              |
|  CL-Protos is a research tool, not a product, so no warranties are given     |
|  about the absence of bugs.  CL-Protos is distributed as a courtesy among    |
|  researchers; all commercial rights are reserved.                            |
+------------------------------------------------------------------------------+


DOCUMENTATION:
     The main description of Protos' design upon which CL-Protos is based is
     chapter 3 of Ray Bareiss's doctoral dissertation (1988, Department of
     Computer Sciences, The University of Texas at Austin).  This should be
     read by anyone who wishes to examine and/or modify CL-Protos.  Other
     useful papers include:

     -- "Concept Learning and Heuristic Classification in Weak-Theory Domains",
         by Porter, B., Bareiss, R., and Holte, R. (to appear in the AI Journal
         Fall 1990. Until then, ask Porter@cs.utexas.edu to send a copy.)

     -- "CL-Protos Users Guide" and "CL-Protos Software Guide" by
	 Dan Dvorak.  These documents are normally distributed along
	 with the CL-Protos tape, and they exist in LaTeX format on
	 the tape.


COMPILATION & LOADING:
     The completely portable way to load CL-Protos (prior to interpretive
     execution) is to issue the Lisp form (load "load-protos.lisp").
     If you do this, please change the *hostname*, *dirname*, and 
     *bintype* variables in the load-protos.lisp file to reflect you system
     configuration before loading the file.  *bintype* is the extention
     that is given to lisp files after they have been compiled.
     If you are using Symbolics Genera 7, then you may take advantage of
     the fact that the file "protos-sys.lisp" defines the Protos "system".
     Installed as a system, you can then issue the Genera commands
     "Compile System PROTOS" and "Load System PROTOS".
     If you have .o, .bin, or .xld files in the directory, then these
     are the executables generated respecitivly by AKCL, Symbolics
     Common-Lisp, and TI Common-Lisp.  These files should be deleted
     and then the source files should be recompiled.

EXECUTION:
     All of the Protos software resides in a package named PROTOS.
     To start execution of CL-Protos, enter these Lisp forms:
          (in-package 'protos)
          (protos)

     The program will then display a top-level menu from which you can
     choose a specific action such as displaying "help" information, loading
     an example knowledge base, entering a new case for classification, etc.


EXAMPLE KNOWLEDGE BASE:
     CL-Protos includes a simple example knowledge base for classifying
     chairs (the example published in "Protos: An Exemplar-Based Learning
     Apprentice").  This example helps illustrate how knowledge is stored
     in Protos' category network and, if you choose to enter a new type of
     chair, it can help illustrate how Protos uses that knowledge to
     classify the chair (and learn from failures).


AUDIOLOGY KNOWLEDGE BASES:
     There is a knowledge base that was made in the Prolog version
     of Protos and subsequently transferred to the Common-Lisp version.
     This knowledge bases is about audiology and is called first_base.lisp.
     There is another knowledge base, first_base_inv.lisp,
     which is the same as the first except that the relations are all 
     inverted.  For example, if you have the relation (A requires B) in
     inverted KB, then the correct relation that appears in the normal
     KB will be (B requires A).  The inverted KB's were created during
     the first translations of the Prolog KB's and may provide some small 
     interest.

     Note:  the *good* KB is first_base.lisp, while the erroneous KB is
           first_base_inv.lisp.

SYSTEM REQUIREMENTS:
     We currently run PROTOS on Sun-3's that use 64 Meg of swap space.  One
     user that had 16 Meg of swap and 15 Meg of real memory would run out
     of memory when loading Protos.  So, your system will need to have more
     than 16 Meg of swap space.


SOURCE CODE:
     CL-Protos consists of about 13,000 lines of source code (see file
     "load-protos.lisp" for the names of the source files).  Although
     CL-Protos was developed on Symbolics Genera 7, the implementation
     should be completely portable, using only functions of Common Lisp.
     To date, CL-Protos has been run on Symbolics, TI Explorer, and
     HP 9000.

     We have attempted to make this implementation readable and well-commented.
     You are welcome to build upon and modify CL-Protos for your own research.
     If you find and/or fix any bugs, please let us know.  Also, if you enhance
     CL-Protos in a way that might be of general interest, please let us know -
     we might want to put those enhancements into the "official" version.



CREDITS:
     CL-Protos was implemented by (in alphabetical order): Rita Duran,
     Dan Dvorak, Jim Kroger, Hilel Swerdlin, and Ben Tso.  Their specific
     contributions were as follows:
     -- Rita Duran programmed the knowledge-based pattern matcher (kbpm.lisp)
        and associated heuristics (heuristic.lisp).
     -- Ben Tso developed the parser (parse.lisp).
     -- Jim Kroger developed the functions for saving and loading knowledge
	bases from files (save-kb.lisp). 
     -- Hilel Swerdlin developed the functions for merging a case with an
        exemplar (merging.lisp) and the enhancement to build-hypotheses to
        control the number of exemplars chosen based on the strength of the
        combined reminding.
     -- Agnar Aamodt developed the code for transformation of parameter
	values, such as for quantitative-to-qualitative transformation.
     -- Dan Dvorak organized the reconstruction effort, architected the
	overall design in Common Lisp, and programmed everything else not
	specifically credited above.
     -- Erik Eilerts primarialy debugged the Common-Lisp version and 
        translated the audiology KB's from Prolog to Lisp.


CONTACT PERSON:
     For questions, comments, bug reports, or enhancements, please contact
     either of:

                 Dan Dvorak                   Ray Bareiss
     Internet:   dvorak@cs.utexas.edu         bareiss@vuse.vanderbilt.edu
     UUCP:       ...!cs.utexas.edu!dvorak     
     phone:      512-471-9576                 615-322-3233

                                              Erik Eilerts
                                              eilerts@cs.utexas.edu

LEGALITIES:
     Unfortunately, we live in an increasingly litigious society.  The
     following legalisms apply to this CL-Protos software:

                  Copyright 1988, by Daniel L. Dvorak

     Permission to use this software is granted subject to the following
     restrictions and understandings:

     1.  This material is for educational and research purposes only,
	 and should not be re-distributed in any form without prior
	 written consent of Daniel L. Dvorak.

     2.  Daniel L. Dvorak has provided this software AS IS.  Daniel L. Dvorak
	 has made no warranty or representation that the operation of this
	 software will be error-free, and he is under no obligation to provide
	 any services, by way of maintenance, update, or otherwise.

     3.  Any user of such software agrees to indemnify and hold harmless
	 Daniel L. Dvorak, The University of Texas, and AT&T Bell Laboratories
	 from all claims arising out of the use or misuse of this software,
	 or arising out of any accident, injury, or damage whatsoever, and from
	 all costs, counsel fees and liabilities incurred in or about any such
	 claim, action, or proceeding brought thereon.

     4.  Users are requested, but not required, to inform Daniel L. Dvorak
	 of any noteworthy uses of this software.

     5.  All materials and reports developed as a consequence of the use
	 of this software shall duly acknowledge such use, in accordance
	 with the usual standards of acknowledging credit in academic
	 research.

     6.  In conjunction with products arising from the use of this material,
	 there shall be no use of the name of Daniel L. Dvorak, The University
	 of Texas, AT&T Bell Laboratories, nor of any adaptation thereof in any
	 advertising, promotional, or sales literature without the prior
	 written consent from Daniel L. Dvorak, The University of Texas, or
	 AT&T Bell Laboratories, in each case as appropriate.

