PyNuSMV is a Python binding for NuSMV. It is intended to provide a Python 
interface to NuSMV, allowing to use NuSMV as a library.

More details about PyNuSMV are provided in the documentation located in 
doc/html/index.html file.

-----
BUILD
-----

Dependencies
------------

In addition to tools needed by NuSMV to compile and run, PyNuSMV needs the 
following tools:

Python version 3.2 or higher -- http://python.org/
SWIG version 2.0.6 or higher -- http://www.swig.org/

Some tools provided with PyNuSMV in the tools/ directory also need the following 
libraries:

pyparsing version 1.5.6 or higher -- http://pyparsing.wikispaces.com/


SWIG and pyparsing are provided in this package in the dep/ directory.



Build
-----

With the pre-compiled version of PyNuSMV, PyNuSMV is already built and is 
located in src/pynumsv. Otherwise, read the following instructions.


To build PyNuSMV, you can just use the provided Makefiles:

make


These Makefiles accept arguments:
    - PYTHON defines the Python command. By default, `python3` is used.
    - SWIG defines the SWIG command. By default, if `swig` exists, it is used,
      otherwise, SWIG is compiled with the given sources; if this argument is 
      not empty, it is used as the `swig` command.
    - PYPARSING defines the PyParsing file. By default, PyParsing is searched, 
      if found it is used, otherwise it is extracted from the given sources; if 
      PYPARSING is set to something different from 0, the file is taken from the 
      given sources even if PyParsing is already installed.
      
For example, if you want to use `python3.2` instead of `python3` and to compile
SWIG from sources even if you have SWIG, you can use:

make PYTHON=python3.2 SWIG=


PyNuSMV is then located into src/pynusmv directory.


If you want more control on the different steps of the building, you can follow 
these instructions:

First compile NuSMV:

# Compile CUDD
cd src/cudd-2.4.1.1
make # use platform-specific makefile if needed e.g. make -f Makefile_os_x_64bit

# Compile NuSMV
cd ../nusmv
./configure
make
cd ..

Then, you can build PyNuSMV by running:
./build_libnusmv.sh
python setup.py build_ext --inplace


Problems
--------

On Mac OS X, an error can occur when compiling NuSMV sources when embedding no 
SAT solver:

/bin/sh ../../../libtool --tag=CC   --mode=link gcc -std=gnu99  -fno-strict-aliasing -g -O2   -o libsatsolvers.la -lm 
libtool: link: ar cru .libs/libsatsolvers.a 
ar: no archive members specified
usage:  ar -d [-TLsv] archive file ...
	ar -m [-TLsv] archive file ...
	ar -m [-abiTLsv] position archive file ...
	ar -p [-TLsv] archive [file ...]
	ar -q [-cTLsv] archive file ...
	ar -r [-cuTLsv] archive file ...
	ar -r [-abciuTLsv] position archive file ...
	ar -t [-TLsv] archive [file ...]
	ar -x [-ouTLsv] archive [file ...]


To avoid this error, modify
    src/nusmv/src/sat/Makefile:
        line 85: libsat_la_DEPENDENCIES = 
        line 343: libsat_la_LIBADD = 
    src/nusmv/src/sat/solvers/Makefile:
        line 322: noinst_LTLIBRARIES =


Using PyNuSMV
-------------

When PyNuSMV is built (with a pre-compiled version, or by following the instructions above), you can use it by going into the src/ directory, running a Python session and importing the pynusmv module.

If you to be able to access to PyNuSMV from anywhere, you have to set two different environment variables:

    - LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH under Mac OS) must contain the path to the src/lib/ directory of PyNuSMV package.
    - PYTHON_PATH must contain the path to the src/ directory of PyNuSMV package.
    
With this two environment variables set (and exported), you can import the pynusmv module, from any Python program or session, from anywhere on your computer (instead of just from the src/ directory).

Finally, you can also update the pynusmv.sh script in the PyNuSMV package to add the path to PyNuSMV package and then you can start a Python session with pynusmv already loaded with

    ./pynusmv.sh


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

The full API of (the upper interface of) PyNuSMV is provided
in the doc/html/index.html page. Other userful information like a presentation 
of the tool and a short tutorial are also given.


-------
CONTENT
-------

This package contains
- this README file;
- LGPL-2.1 : a copy of the LGPLv2 License;
- TOOLS : notes about the tools provided with PyNuSMV;
- dep/ : a directory containing some tools on which PyNuSMV depends;
- doc/ : a directory containing PyNuSMV documentation;
- src/ : PyNuSMV sources

    - build_libnusmv.sh : NuSMV shared library building script;
    - setup.py : PyNuSMV compilation file;

    - cudd-2.4.1.1/ : CUDD sources, needed by NuSMV;
    - nusmv/ : NuSMV sources;
    - MiniSat/ : MiniSat directory for NuSMV;
    - zchaff/ : zChaff directory for NuSMV;
    
    - pynusmv/ : PyNuSMV sources;
    - tools/ : PyNuSMV-based tools;
    - tests/ : PyNuSMV and PyNuSMV-based tools unit tests.
    
Note that pre-compiled versions have less content because only the minimal required files (i.e. PyNuSMV files and nusmv shared library) are included.

---------------------------
TESTING AND COVERAGE REPORT
---------------------------
Use the following two commands to run the unit tests and build the coverage report.

coverage run -m unittest
coverage html

or, if you want to only output the report relating to the SAT-BMC addition, 

coverage html --include "pynusmv/bmc/*,pynusmv/be/*,pynusmv/sexp/*,pynusmv/collections*,pynusmv/sat*,pynusmv/trace*,pynusmv/utils*,pynusmv/wff*,tools/bmcLTL/*,tools/diagnosability*"


---------
COPYRIGHT
---------

PyNuSMV is licensed under the GNU Lesser General Public License (LGPL in short). File LGPL-2.1 contains a copy of the License.


-------
CREDITS
-------

PyNuSMV is maintained and distributed by the LVL Group at Université catholique 
de Louvain.  Please contact <lvl at listes dot uclouvain dot be> for any 
question regarding this software distribution.

NuSMV is a symbolic model checker developed as a joint project between several 
partners and distributed under the GNU LGPL license. Please contact <nusmv at 
fbk dot eu> for getting in touch with the NuSMV development staff.