(This file describe a previous version of Sammy, but may be of interest.)

---

SAMMY XML-RPC API:

(Please keep in mind that this document is subject to change.)

INSTALLATION:

Obtain and install the following modules:

CVCL: Install the current "unstable" build of CVCL.
(http://verify.stanford.edu/CVCL/)  Configure this with the 
"--with-build=optimized" option.

Ocaml: The system seems to be more stable under the Ocaml 3.07-2 (3.07,
patch level 2) build than the current Ocaml 3.08.0 build.  Specifically we
have been experiencing out of memory errors with respect to the Ocaml
garbage collector in 3.08.0 that do not occur in 3.07-2.  Ocaml sources and
precompiled RPMs can be found at http://www.ocaml.org.

Installing ocaml to the /usr directory (the RPMs should default to 
here; the source installation defaults to /usr/local) and cvcl to its 
default directory will simplify a later step.

Ocaml packages:

The XML-RPC support of sammy requires the following Ocaml packages be 
installed (in the following suggested order):

* findlib-1.0.4 (http://www.ocaml-programming.de/packages/)
* OCamlMakefile 1.64
    (http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html)
* xstr-0.2.1 (http://www.ocaml-programming.de/packages/)
* equeue-2.0.1 (http://www.ocaml-programming.de/packages/)
* pcre-ocaml-5.08.1 
    (http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html)
* ocamlnet-0.97.1 (http://www.ocaml-programming.de/packages/)
* pxp-1.1.6 (http://www.ocaml-programming.de/packages/)
* netclient-0.90.4 (http://www.ocaml-programming.de/packages/)
* ocaml-http-0.0.9 (http://www.bononia.it/~zack/ocaml-http.en.html)
* annexlib-0.13.0 (http://raevnos.pennmush.org/code/annexlib/)
* ocaml-xml-rpc-0.2.3 (http://raevnos.pennmush.org/code/ocaml.html)

In general it is necessary to run "./configure" (if present), then "make 
all", "make opt", and "make install" for each library.

If you need to update the PCRE C libraries (http://www.pcre.org/, 
pcre-ocaml requires version 4.5+), make sure all of the pcre libraries 
are actually updated.  A simple "make install" may fail to install, for 
example, the library file libpcre.so.0.0.1.

The ocaml-XML-RPC library needs to use annexlib, not extlib as is written 
in its META file (edit its META file prior to compiling/installing).  
Additionally sammy requires the use of the ocaml-xml-rpc httpd code, 
which is not installed with the rest of the package by default.  It is 
necessary to manually enter the ocaml-xml-rpc's httpd directory and 
"make" and "make install".

The supplied Java client, located in dpllt/client/, is an extremely naive 
example, and uses a slightly modified version of the Apache Java XML-RPC 
library xmlrpc-1.2-b1, which has been altered to follow the API behavior 
mentioned in the notes section, below.

Installing sammy:

The sammy code can be extracted via a cvs archive on goedel.cs.uiowa.edu
(account information to be provided).  The appropriate command to 
retrieve the code is
	cvs checkout -d /usr/local/dpllt-cvs dpllt
which will create and populate a dpllt directory.  The SMT-LIB server for 
sammy is located in dpllt/cvcl/smt/ (the example client code is in 
dpllt/client/).

Configuration:
This currently requires some information generated by cvcl's installation.
Given the cvcl source directory is called "cvcl/", first copy the file
cvcl/config.h to dpllt/cvcl/interface/ (or someplace visible to your 
library search path).  Next it may be necessary to modify the makefile
dpllt/cvcl/interface/Makefile.

Find the line containing the string CPPFLAGS in cvcl/config.status.
The flags in the line of the interface/Makefile reading
-DDEBUG -D__DEPRECATED -DHAVE___GNU_CXX__EXT_HASH_MAP -DHAVE___GNU_CXX__EXT_HASH_SET \
should correspond to the flags present in the CPPFLAGS line of the 
config.status file.  Additionally the Makefile's -I flags should 
correspond to your actual ocaml and cvcl include directories (if they are 
different from the assumed ones, mentioned above).

Once this is done, cd to dpllt/cvcl/smt/ and run make.  This will produce 
a server executable (which may be freely moved elsewhere on the machine) 
called "sammy" and a shell script dpllt/client/samc to call the example 
client application.

Hypertext code documentation can be automatically generated by executing 
	make -htdoc
from dpllt/cvcl/smt/ after the code has been compiled.  The documentation 
will be placed in dpllt/cvcl/smt/doc/.

=====

GENERAL SYSTEM BEHAVIOR:

The sammy system is run as a server process, which is then accessed through 
a client via XML-RPC.  A naive example client is provided, which may be used 
as a reference.  Details on its use are in the dpllt/client/README.txt
file.

The server is invoked simply by ./sammy, with -port n as an optional 
command line flag to specify a port number to listen on (default is 8000).

Returns to procedure calls will always be integer values, with negative values
indicating some error state.

Unless otherwise specified, these error codes are as follows:

-1 : Incorrect state.  The system currently only supports certain orders
of procedure calls.  This error is raised if an out-of-order call is
attempted. The call is not completed and does not need to be backtracked.

-2 : Parsing error.  The string passed to the procedure cannot be parsed
successfully.  If any declarations were made as part of the call
(including local variables), these may have been successfully completed.
Altering the type of a previously declared token will result in a system
error.

-3 : Backtrack error.  The system attempted to backtrack more
assertion/declaration calls then were made.  No backtracking is done.

-32 : Other error.  Some other error was caught. 
(32 is an arbitrary, high enough value for non-specifi errors.)

=====

SUPPORTED PROCEDURE CALLS:

The following assumes a knowledge of how to make XML remote procedure calls
from Java.  In order to keep the interface as simple as possible for now, 
all parameters to calls are currently either single strings, or (in one case) 
a single integer.  All return values will be integers, with negative 
numbers indicating a detected error.  This differs from the proposed 
interface documentation by Joe.

The procedure descriptions are in the following format:

label (param)
description

Where label is the XML-RPC identification label for the procedure, (param) is
the parameter accepted (may be empty), and description is more detailed
description of the procedure.

Many procedures expect parameters to be in SMT-LIB format, which can be 
found detailed in the "SMT-LIB Standard: Version 1.0" document, located at 
http://goedel.cs.uiowa.edu/smtlib/.

sammy.start_solver ()
Initializes the solver.  Once this procedure has been called, the system
will be ready to accept any of the following commands.  The system must
be re-initialized following any calls to stop_solver (below).
Returns 1 on success.

sammy.set_flags (flags:string)
Allows the optional setting of various system flags.  This call may only 
be made after a call to start_solver (above) and before any calls to 
procedures following, or after they have all been backtracked.
Returns 1 on success.

set_flags reads the flags string as if they were part of a command line,
so any number of flags may be set at once.  For more information, see
the parameters section of the dpllt/cvcl/global.ml file.
Among the flags supported are:

-max_lemmas n
  Maximum total number of learned lemmas stored in memory.

-active_lemmas n
  Number of "active" learned lemmas ( active_lemmas =< max_lemmas )

-activity_cycle n
  Predicate selection scoring decay parameter.

-max_instances n
  Limit on the number of instances the system will create at once
  (internal behavior).

-exhaustive
  Instantiate quantifiers exhaustively.

-inst_time n
  Instantiation cycle timeout (in seconds).  Queries should restart with
  a new instantiation pattern after this time is exceeded.  inst_time <=
  timeout, below.

-timeout n
  System timeout (in seconds).  Queries will always return "don't know"
  after this time is exceeded.  Note that the timeouts are not strict:
  they should be considered lower limits on when the system will give up.

-restart_cycle n
  Search restarts after n conflicts.  Defaults to max_int, which
  essentially turns off this feature.

sammy.type_declaration (type_ids:string)
Declare uninterpreted types.  The type_id string should be in SMT-LIB
format: a list of sort names.
Returns 1 on success.

Example type_ids:
(not_real unreal sort_of_real really)

sammy.func_declaration (function_ids:string)
Declare function symbols (these may not be predicates).  The
function_ids string must be in SMT-LIB format,
according to the <fun_symb_decl> entry of the concrete syntax 
(fig. 10 of the SMT-LIB document).  
In SMT-LIB constants are represented by 0-ary functions (only their return
type). Each function must be contained within parentheses, and must 
have a function name followed by the types involved (minimum one type).
Returns 1 on success.

Example function_ids:
(exp real real real)
(pc real)
(hash_value real real)
(x unreal)

sammy.pred_declaration (predicate_ids:string)
Declare predicate symbols.  The predicate_ids string should be in 
SMT-LIB format, 
according to the <pred_symb_decl> entry of the concrete syntax
(fig 10 of the SMT-LIB document).
Returns 1 on success.

Example predicate_ids:
(p)
(greater_than real real)
(is_integer real)

sammy.add_assertion (formula:string)
Assert a formula by adding it to the current context. 
The formula string should be in SMT-LIB format, according to 
the <an_formula> entry of the concrete syntax 
(fig 9 of the SMT-LIB document).  
Returns 1 on success if the new formula is not detected to be inconsistent
with the context, or 0 if sammy detects that adding the assertion would 
cause the context to become unsatisfiable.  (This consistency check is not 
exhaustive, so an inconsistent context may return a 1 -- it has just not 
been detected yet.)   When 0 is returned, the assertion is also
automatically retracted.

Example formulas:
(or (not true) (= (+ 1 1) 2))
(and (> 5 y) (= (+ y 1) z))    [note that y and z must have been previously declared as constant symbols]
(= 5 1)
(forall (?y real) (?z real) (implies (> 5 ?y) (= (+ ?y 1) ?z)))

sammy.query (formula:string)
Query a formula.  The formula string should be in SMT-LIB format, 
according to the <an_formula> entry of the concrete syntax
(fig 9 of the SMT-LIB document).  
The query is not added to the current context and does *not* need to be
retracted with a call to sammy.backtrack (see below).
Returns 1 if the formula is VALID in the current context, 
0 if the formula is not VALID, and 
2 if the formula may be either (don't know).
Note: in the current version of sammy, 2 is returned on quantifier 
 
Example formulas:
(as above)


sammy.backtrack (n:int)
Retracts context the n most recents assertions and restabishes the context
existing right before those assertions.
See the error conditions (above) and notes (below) for further information.
Returns 1 on success.

sammy.stop_solver ()
Stops and re-sets the solver in preparation of calling start_solver again.
Returns 1 on success.

=====

NOTES:

* The system currently keeps track of 3 general classes of states: START,
FLAG, and STEP.  Flags can only be set in the FLAG state, and STEP
includes the declaration/assertion stack, which must be completely
backtracked to return to the FLAGS state.  stop_solver returns the system
to the START state.  The ability to freely interleave declarations and
assertions (and still backtrack all assertions) may change in the future
(assume all declarations must be made prior to any assertions).

The expected order of procedure calls is something like:

1. start_solver (START->FLAG)
2. set_flags (optional) (FLAG)
3. perform declarations (FLAG->STEP, STEP->STEP)
4. add_assertions, perform queries, and backtrack assertions, as necessary
   (FLAG->STEP, STEP->STEP, STEP->FLAG)
5. stop_solver (?->START)
6. goto 1 (optional)

* The XML-RPC specification states that the <string> tags for string
parameters are optional.  They are required by this API.

* Similarly, the API expects at least one parameter for each procedure
call. In the case of unit parameters, (), the system should ignore (and
work successfully with) any single parameter, such as an empty string.

* It is currently not possible to "undeclare" tokens such as those 
declared by type_declaration, func_declaration, or pred_declaration.  
In other words, declarations are not backtrackable. Once a type is
associated with a particular symbol, it may not be changed without
restarting the system (either as a process or through
stop_solver/start_solver).  One may still backtrack _through_
declarations to retract previous assertions, but these declarations are 
not actually forgotten.  Redeclaring an already declared symbol in exacly
the same way is currently accepted, but redeclaring it differently will 
generate an error.

* We currently do not allow function and predicate symbol overloading --
each symbol must be either a function or predicate symbol and must have 
a single asociated type.

* There is currently an occasional problem with system restarts, 
specifically with the (stop_solver command). (More on this later.)


* The interface is case sensitive.

====

The current version of Sammy supports as built in theories:
- real linear arithmetic, 
- a theory of arrays with real indexes and real elements, and 
- the theory of equality over uninterpreted symbols
  and the sorts real and real_real_array.
We can easily modify Sammy to also provide as built-in:
- more uninterpreted sorts,
- other instances of the theory of arrays over these sorts,
- the theory of tuples (over some given sorts)
- theory of records (over some given sorts),
- the theory of the booleans 
- mixed integer linear arithmetic
- (forthcoming) a rich theory of bitvectors
 

Reserved keywords that are currently interpreted by our theory:

real, real_real_array, +, -, /, *, real_real_select, real_real_store, 
true, false, >, <, <=, >=, distinct, =, and, or, not, xor, implies, 
ite, if_then_else, forall, exists

Integer numerals are also interpreted by the theory as real constants.

Definitions of usage / syntax:

predefined types:
	real
	real_real_array
                                                                                
built-in function symbols

type						usage
------------------------------------------------------------
(+ real real real)				(+ x y)
(- real real)					(- x)
(- real real real)				(- x y)
(/ real real real)				(/ x y)
(* real real real)				(* x y)
(real_real_select real_real_array real real)	(real_real_select a i)
(real_real_store 
    real_real_array real real real_real_array)	(real_real_store a i x)
                                                                                
built-in predicate symbols

type						usage
------------------------------------------------------------
(true)						true
(false)						false
(> real real)					(> x y)
(< real real)					(< x y)
(>= real real)					(>= x y)
(<= real real)					(<= x y)
(distinct 'a 'a 'a ...)				(distinct x y z ...)
(= 'a 'a 'a ...)				(= x y z ...)

'a above stands for any sort.


special term constructor

	(ite p x y) 
        [where p is a formula and x y are terms of the same sort]


formula constructors

	(and p q)
	(or p q)
	(not p)
	(xor p q)
	(implies p q)
	(if_then_else p q r)
	(iff p q)
	(forall (?x1 s1) ... (?yn sn) p)	
	(exists (?x1 s1) ... (?yn sn) p)	
	(flet ($f p) q)

Where p,q, ?xi, ?si and $f are as specified in the SMT-LIB standard.


strings
	"string"

other reserved words:
notes, sorts, funs, preds, extensions, definitions, axioms, theory, :, (, ),
sat, unsat, unknown, assumption, formula, status, bencmark, benchmarks,
extrasorts, extrafuns, extrapreds, language, benchset, ;

