MuDDy - SML interface to BuDDy
==============================

Homepage:
    http://www.itu.dk/research/muddy

Authors:
    Ken Friis Larsen  <kfl@itu.dk> and Jakob Lichtenberg <jl@itu.dk>

Copyright (C) 1997-2000 by Ken Friis Larsen and Jakob Lichtenberg.



WHAT
----------------

MuDDy is a SML interface to the Binary Decision Diagrams package BuDDy
written in C.  BuDDy is written by Jrn Lind-Nielsen <jln@itu.dk> and
is available at the homepage:
    http://www.itu.dk/research/buddy

MuDDy is used by a small set of people, and the functionality and
design of the interface corresponds to these people's need.  Please
comment on the design of the interface to the authors.

We use Moscow ML's foreign function interface to call the C functions
in BuDDy.  Therefore, MuDDy can only be used with Moscow ML (version
1.43 or newer).  However, we are very interested if somebody wants to
port MuDDy to other SML systems and are willing to provide information
and help.



REQUIREMENTS
----------------

Moscow ML: Version 1.43 (or newer) compiled with dynlib support.  
       Moscow ML is available from:
	      http://www.dina.kvl.dk/~sestoft/mosml.html

Make:  MuDDy needs a non-broken make to install.  We recommend GNU make
       from Free Software Foundation. GNU make is included in most
       Linux distributions, and is furthermore available from:
	      http://www.gnu.org/software/make/make.html

Linux: MuDDy is developed under Linux and is only tested under Linux,
       but it should work without problems on other UNIX-like systems
       with Moscow ML dynlib support.  Please report back if you are
       able to compile MuDDy on other systems.



INSTALLATION
----------------

To install the package:
    tar xzf muddy.tgz
    cd muddy

The directory you are in now will be refered to as MuDDy home dir.

Edit MOSMLHOME in the Makefile to point to your Moscow ML installation

Compile BuDDy and MuDDy with:
    make



STARTUP
----------------

To use the MuDDy package, the Moscow ML runtime system must have
access to: 
       * The shared library muddy.so 
       * The compiled ML modules.

These files are all available in the MuDDy home dir after installation.

If the MUDDYHOME environment variable points to the MuDDy home dir, MuDDy
will be able to find the shared library.

Therefore, assuming MuDDy home dir is the current directory, and you
use the bash shell:
    export MUDDYHOME=`pwd`

Or, if you use tcsh shell:
    setenv MUDDYHOME `pwd`

Now, when you use Moscow ML you must remember to tell it where the
compiled SML modules can found.  For example, to invoke the
interactive environment do: 
    mosml -I $MUDDYHOME
  
(If the MUDDYHOME environment variable is not set, the shared library
must be placed in the dynamic library load path, controlled by the
LD_LIBRARY_PATH environment variable, and you must still provide the
path to the SML modules when invoking Moscow ML.  For more information
on these matters refer to the Moscow ML documentation.)



DOCUMENTATION
----------------

Since MuDDy is just an interface to BuDDy, the documentation is based
on the documentation for BuDDy, available in $MUDDYHOME/buddy17/doc/buddy.ps

MuDDy consists of three modules:
    * bdd implementing the functionality of the BuDDy bdd.h header
    * fdd implementing the functionality of the BuDDy fdd.h header
    * bvec implementing the functionality of the BuDDy bvec.h header

Each module has a sig file.  In this file you can find:
    * Short documentation of the types and values.
    * A comparison to the BuDDy C types and function declarations.

You should be aware, that there is the general difference between
MuDDy and BuDDy that when you use MuDDy, reference counting of BDD
nodes are managed automatically.


Some tutorial material is includes in 

 University of Cambridge Computer Laboratory Technical Report No. 481
    Combining the Hol98 Proof Assistant with the BuDDy BDD package

by Mike Gordon and Ken Friis Larsen.  The report is available at
	http://www.cl.cam.ac.uk/~mjcg/BDD/#TR


EXAMPLES
----------------

Surprisingly, the examples are in the examples directory!

For now, we only provide one example: test.sml.

To test MuDDy, start Moscow ML in the examples dir, and write:
    use "test.sml";

Remember to follow the instructions in the STARTUP section regarding
the MUDDYHOME variable, and the -I directive.
  


ACKNOWLEDGEMENTS
----------------

The first version of MuDDy was written by Ken Friis Larsen while
visiting Mike Gordon at Computer Lab. at University of Cambridge (UK),
in autumn 1997 and spring 1998.  Jakob Lichtenberg then extended MuDDy
to cope with the new BuDDy features: Finite Domain Diagrams (fdds) and
Boolean Vectors (bvecs).

It should be stressed that MuDDy is only a type safe SML wrapping
around Jrn Lind-Nielsen's <jln@itu.dk> great BuDDy package, and that
all the "hard work" is done by the BuDDy package.  Jrn Lind-Nielsen
has answered lots of BuDDy questions (and BDD questions), and have
been very willing to change the BuDDy package to make the SML wrapping
more easy.

A special thanks should also go to Peter Sestoft who have answered
tons of questions about the Moscow ML/Caml Light runtime system, and
he even audited the C code at one point to help finding a bug.

The wrapping of C functions caused surprisingly few problems, this is
mainly due to the magnificent designed Caml Light runtime system that
Moscow ML is based upon.  Caml Light is created by Xavier Leroy and
Damien Doligez and is available from:
    http://pauillac.inria.fr/caml/overview-caml-light-eng.html

The first usage of MuDDy was in the Hol98 theorem prover.  This usage
has influenced lots of decisions about how the interface should be.

We would also like to thanks the following people who have provided
lots of good feedback and encouragement (listed in alphabetic order):
    
    Henrik Reif Andersen (IT University in Copenhagen)
    Mike Gordon          (Computer Lab. Univerity of Cambridge (UK))
    Jesper Mller        (IT University in Copenhagen)
    Michael Norris       (Computer Lab. Univerity of Cambridge (UK))
    Konrad Slind         (Computer Lab. Univerity of Cambridge (UK))



COPYRIGHT NOTICE for MuDDy
--------------------------

MuDDy - a SML interface to the Binary Decision Diagrams package BuDDy
Copyright (C) 1997, 1998, 1999, 2000 Ken Friis Larsen and Jakob Lichtenberg

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA

