README

   1 This version of Screamer is based on released version 3.20.
   2
   3 See file LICENSE for licensing details.
   4
   5 This directory contains the following files:
   6
   7 screamer.lisp - The source code for Screamer.
   8
   9 primordial.lisp - A sort of torture test to determine whether Screamer is
  10 working. To run, first compile and load Screamer and Iterate, compile and load
  11 this file, type (IN-PACKAGE :PRIMORDIAL), and then type (PRIME-ORDEAL). If no
  12 errors result then Screamer is probably working correctly.
  13
  14 screams.lisp - A file containing all of the examples from the Screamer manual
  15 and the two papers ircs-93-03 and aaai93. To use, first compile and load
  16 Screamer and Iterate, compile and load this file, and then type
  17 (IN-PACKAGE :SCREAMS).
  18
  19 equations.lisp - A file containing some equations for testing Screamer's
  20 numeric constraint satisfaction procedures. To use, first compile and load
  21 Screamer, compile and load this file, and then type (IN-PACKAGE :SCREAMS).
  22
  23 iscream.el - If you run Lisp on Unix under GNUEmacs using ILisp you can load
  24 this Emacs Lisp file (preferably byte compiled first). You must also then
  25 set the variable SCREAMER:*ISCREAM?* to T. This will enable the Screamer
  26 macro LOCAL-OUTPUT and improve the behavior of Y-OR-N-P and PRINT-VALUES
  27 under ILisp.
  28
  29 screamer.dvi
  30 screamer.ps - DVI and Postscript versions of an outdated manual for Screamer.
  31 The code in this manual has some bugs but corrected versions are included in
  32 screams.lisp.
  33
  34 ircs-93-03.dvi
  35 ircs-93-03.ps - DVI and Postscript versions of a paper describing the
  36 fundamentals of nondeterministic CommonLisp. This paper is available at
  37 Technical Report 93-03 of the University of Pennsylvania Institute for
  38 Research in Cognitive Science. The appropriate BibTeX entry is:
  39 \newcommand{\Screamer}{{\mbox{\sc Screamer}}}
  40 \newcommand{\CommonLisp}{{\mbox{\sc Common Lisp}}}
  41 @string{IRCS = {University of Pennsylvania Institute for Research in Cognitive
  42         Science}}
  43 @techreport{SiskindM93,
  44         author = {Jeffrey Mark Siskind and David Allen McAllester},
  45         title = {{\Screamer:} A Portable Efficient Implementation of
  46                 Nondeterministic {\CommonLisp}},
  47         institution = IRCS,
  48         year = 1993,
  49         number = {IRCS--93--03}}
  50 The code in this paper is included in screams.lisp.
  51
  52 aaai93.dvi
  53 aaai93.ps - DVI and Postscript versions of a paper describing the constraint
  54 package included with Screamer. This paper will appear in the Proceedings of
  55 AAAI-93. The appropriate BibTeX entry is:
  56 The code in this paper is also included in screams.lisp.
  57 \newcommand{\Lisp}{{\mbox{\sc Lisp}}}
  58 @string{AAAI93 = {Proceedings of the Eleventh National Conference on
  59         Artifical Intelligence}}
  60 @inproceedings{SiskindM93a,
  61         author = {Jeffrey Mark Siskind and David Allen McAllester},
  62         title = {Nondeterministic {\Lisp} as a Substrate for Constraint Logic
  63                 Programming},
  64         booktitle = AAAI93,
  65         year = 1993,
  66         month = jul}
  67
  68 Incompatibilities between Screamer 3.20 and Screamer 2.4:
  69
  70 Screamer 3.20 contains numerous bug fixes, performance enhancements and novel
  71 features over Screamer 2.4, the prior widely released version. I do not have
  72 the time to describe all such improvements. Until the completion of a new
  73 Screamer manual you must resort to looking at the source code. At the beginning
  74 of the file there is a fairly extensive change log.
  75
  76 A small number of incompatibilities have been introduced in the transition
  77 from Screamer 2.4 to Screamer 3.20. These are summarized below. Those already
  78 familiar with Screamer should have no difficulty modifying their code modulo
  79 these changes.
  80
  81 1. All Screamer code must be recompiled. The Screamer 3.20 runtime is
  82 incompatibile with the Screamer 2.4 compiler.
  83
  84 2. The function MAP-VALUES has been removed. An expression such as:
  85 (MAP-VALUES function expression)
  86 can be rewritten using the new FOR-EFFECTS macro as follows:
  87 (FOR-EFFECTS (FUNCALL function expression))
  88 The new syntax is every bit as powerful as the old syntax. In fact it is more
  89 powerfull. MAP-VALUES used to require that the function argument be a
  90 deterministic expression while the new syntax makes no such requirement. (Note
  91 that FUNCALL still requires that its first argument evaluate to a deterministic
  92 function.)
  93
  94 3. You no longer need to reload Screamer after doing an UNWEDGE-SCREAMER since
  95 Screamer keeps track of which functions are intrinsic and UNWEDGE-SCREAMER
  96 does not purge those functions.
  97
  98 4. The following functions have been renamed:
  99 NUMBERV  -> NUMBERPV
 100 REALV    -> REALPV
 101 INTEGERV -> INTEGERPV
 102 BOOLEANV -> BOOLEANPV
 103 The original names were inconsistent with the naming convention that every
 104 function ending in V names a lifted version of the function name without the V.
 105 I.e. NUMBERV would have been a lifted version of a function NUMBER but there
 106 is no ground function. NUMBERV was really a lifted version of NUMBERP and thus
 107 should have been named NUMBERPV.
 108
 109 5. A new naming convention has been introduced. All nondeterministic
 110 `generators' now begin with the prefix A- or AN-. This results in the
 111 following name changes:
 112 INTEGER-BETWEEN -> AN-INTEGER-BETWEEN
 113 MEMBER-OF       -> A-MEMBER-OF
 114 FLIP            -> A-BOOLEAN
 115 Furthermore, `lifted generators' both begin with A- or AN- and end with V.
 116 This results in the following name changes:
 117 REAL-ABOVEV      -> A-REAL-ABOVEV
 118 REAL-BELOWV      -> A-REAL-BELOWV
 119 REAL-BETWEENV    -> A-REAL-BETWEENV
 120 INTEGER-ABOVEV   -> AN-INTEGER-ABOVEV
 121 INTEGER-BELOWV   -> AN-INTEGER-BELOWV
 122 INTEGER-BETWEENV -> AN-INTEGER-BETWEENV
 123
 124 6. The variable *FUZZ* has been eliminated. The functionality of this variable
 125 has been replaced by additional arguments to the REORDER function.
 126
 127 7. REORDER now takes four arguments:
 128 (COST-FUNCTION TERMINATE? ORDER FORCE-FUNCTION)
 129 instead of one. The FORCE-FUNCTION is the same as the prior lone argument.
 130 The COST-FUNCTION is a function to be applied to each VARIABLE at each
 131 reordering step to return its cost. Typical values for COST-FUNCTION are
 132 #'DOMAIN-SIZE or #'RANGE-SIZE. The COST-FUNCTION can return NIL which causes
 133 REORDER to not consider that variable for further forcing. ORDER is a two
 134 argument predicate applied to the non-NIL cost functions computed for the
 135 variables at each reordering step. Typical values are #'<, to choose the least
 136 cost, and #'>, to choose the greatest cost variable to force next. TERMINATE?
 137 is a one argument predicate applied to the (non-NIL) cost function computed
 138 for the variable chosen to force next. If TERMINATE? returns T then the
 139 variable reordering and forcing terminates. The following is a typical call
 140 to REORDER used to solve numerical constraints:
 141
 142 (REORDER #'RANGE-SIZE
 143          #'(LAMBDA (X) (< X 1E-6))
 144          #'>
 145          #'DIVIDE-AND-CONQUER-FORCE)
 146
 147 The following is a typical call to REORDER used to solve symbolic constraints:
 148
 149 (REORDER #'DOMAIN-SIZE
 150          #'(LAMBDA (X) (DECLARE (IGNORE X)) NIL)
 151          #'<
 152          #'LINEAR-FORCE)
 153
 154 8. Instead of the standard Screamer file preamble which used to be:
 155
 156 (IN-PACKAGE :<my-package>)
 157 (USE-PACKAGE '(:LISP :SCREAMER))
 158 (SHADOWING-IMPORT '(SCREAMER::DEFUN))
 159
 160 there is now a different standard preamble. Loading Screamer creates a
 161 predefined package SCREAMER-USER which is useful for small student and
 162 demonstration programs. If you wish your file to be in the SCREAMER-USER
 163 package the single line:
 164
 165 (IN-PACKAGE :SCREAMER-USER)
 166
 167 should be placed at the top of the file. In addition:
 168
 169 (IN-PACKAGE :SCREAMER-USER)
 170
 171 should be typed to the Listener after loading Screamer. More complex programs
 172 typically reside in their own package. You can place a program in its own
 173 package by using the following preamble to your file:
 174
 175 (IN-PACKAGE :CL-USER)
 176 (SCREAMER:DEFINE-SCREAMER-PACKAGE :<my-package>
 177  <optional defpackage arguments>)
 178 (IN-PACKAGE :MY-PACKAGE)
 179
 180 Note that DEFINE-SCREAMER-PACKAGE doesn't work under AKCL or Poplog so on
 181 these systems you must either use the SCREAMER-USER package or figure out on
 182 your own how to appropriately define a Screamer package.