|
IEGENLIB
|
|
IEGENLIB
|
IEGenLib is a library with data structures and routines that can represent, parse, and visit integer tuple sets and relations with affine constraints and uninterpreted function symbol equality constraints. See src/parser/parser_test.cc for examples of strings that can be parsed.
The run_tests.cc driver will execute all tests identified with the TEST macro. In each of the src/ subdirectories, the *_test.cc files define regression tests.
The iegenlib_calc binary will execute tests that you input yourself and will return the interpreted version of the input along with a dotty file to the file set_relation.dot in the directory where the program is executed.
Copyright (c) 2009,2010,2011,2012 Colorado State University
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
=================================
README for IEGenLib
=================================
IEGenLib is a library that represents and manipulates integer sets and
relations that have affine and uninterpreted function constraints.
==== Unpacking the Distribution ===================
The distribution is shipped as a tar file. When you unpack the tar
file it creates a directory that is the root of the distribution.
tar xzvf iegenlib-1.0.0.tgz
==== Quick Start ===============
A. Running the IEGenLib Calculator
B. Using the IEGenLib Python Interface
This distribution is shipped with LINUX-64 bit and Mac OSX binaries in
addition to the sources and build system needed to compile and link on
unix-based machines.
In the below, assume the IEGEN_HOME environment variable is the path
to the top installation directory. Two installation directories come
with the package:
iegen-MACOSX/
and
iegen-LINUX64/.
---- A. Running the IEGenLib calculator ----------
The iegenlib_calc binary can be executed to enter sets and relations
and operations on them. When run, the iegenlib_calc suggests examples.
$IEGEN_HOME/bin/iegenlib_calc
The program will present a prompt for an input string. You may input
any valid string and it will return the interpreted string and a
formatted dot file to a file called set_relation.dot. The calculator
continues until a blank line is input or [CTRL][D] is entered.
---- B. Using the IEGenLib Python bindings ----------
Required to use Python bindings to IEGenLib:
* Python 2.7.2 known to work on linux and Mac
The Python bindings shipped in the distribution (iegen/bindings/..) can also
be used to interface to the library.
(1) Set the PYTHONPATH environment variable
export PYTHONPATH=$PYTHONPATH:$IEGEN_HOME/bindings
- OR -
setenv PYTHONPATH $IEGEN_HOME/bindings
(2) Run python
python
>>> import iegenlib
(3) Examples
The following Python statements are examples on how to create sets and
relations:
>>> S1 = iegenlib.Set("{[s,i]: 0<=s && s<T && 0<=i && i<N}")
>>> print S1
>>> R1 = iegenlib.Relation("{[s,i]->[0,s,1,i,0]}")
NOTE: Both the omega and ISL syntax are allowed for specifying sets and
relations. Some of the short cuts such as 0<=i<N are missing however.
The following Python statements are examples on how to apply operations
(such as Apply, Union, Inverse, and Compose) between sets/relations:
>>> S2 = R1.Apply(S1) # Apply operation #
>>> S3 = iegenlib.Set("{[i,j]: 0<=i and i<n and 5<=j and j<m}")
>>> S4 = iegenlib.Set("{[i,j]: 0<=i and i<n and m+5<=j and j<m+10}")
>>> S4 = S3.Union(S4) # Union operation #
>>> R2 = iegenlib.Relation("{[i,j]->[ip,jp]: ip=f(i) and jp=2j}")
>>> R3 = iegenlib.Relation("{[q,r]->[i,j]: i=q and j=r}")
>>> R3 = R3.Compose(R2) # Compose operation#
>>> R2 = R2.Inverse() # Inverse operation#
>>> print R2 # to print the resulting set/relation#
{ [ip, jp] -> [i, j] : ip - f(i) = 0 && 2 j - jp = 0 }
# The output of the print command #
Some examples that use function inverse declarations.
>>> iegenlib.appendCurrEnv("f() = inverse f_inv()");
>>> S5 = iegenlib.Set("{[i,j]:i=f(f_inv(j))}")
>>> print "S5 = ", S5
>>> R4 = iegenlib.Relation("{[i,j]->[ip,j]: ip=f(i)}")
>>> print "R4 = ", R4
>>> S6 = R4.Apply(S5)
>>> print "S6 = ", S6
The user can obtain dot files for SparseConstraints objects of
sets/relations from the IEGenlib Python Interface by using
toDotString() methods. Python methods open(filename, mode) and
write(item) can be used to open and write to the output file, as
in the following examples:
>>> S3 = iegenlib.Set("[n,m]->{[i,j]: 0<=i and i<n and 5<=j and j<m}")
>>> file = open("S3.dot", 'w')
>>> file.write(S3.toDotString())
>>> file.close()
==== Distribution Organization ===============
The distribution is shipped as a tar file. When you unpack the tar
file it creates a directory that is the root of the distribution.
tar xzvf iegenlib-#.#.#.tgz
This distribution is shipped with LINUX-64 bit (iegen-LINUX64/) and
Mac OSX (iegen-MACOSX/) binaries in addition to the sources and build
system needed to compile and link on unix-based machines.
iegen-LINUX64/ and iegen-MACOSX/
lib/
libiegenlib.a // C++ library
bin/
iegenlib_calc // interactive calculator
run_iegenlib_tests // regression tests
bindings/ // Python bindings
_iegenlib.so
iegenlib.py
Generated documentation can be found in the doc/refman.pdf file.
The refman.pdf file and a full set of html documentation can also be
found at the project downloads page website.
Sources for the project are found in the distribution root src/
sub-directory.
The library and demonstration driver create both string and dot
output; graphviz is needed to visualize the dot output.
==== Running the regression tests ===============
(1) Set the IEGEN_HOME environment variable :
On a Mac, from the distribution root directory:
export IEGEN_HOME=`pwd`/iegen-MACOSX
- OR -
setenv IEGEN_HOME `pwd`/iegen-MACOSX
On a Linux, from the distribution root directory:
export IEGEN_HOME=`pwd`/iegen-LINUX64
- OR -
setenv IEGEN_HOME `pwd`/iegen-LINUX64
(2) run the regression tests
$IEGEN_HOME/bin/run_iegenlib_tests
==== Building IEGenLib from Source =======================
Build Command Sequence
./configure
make install
Build and Test without creating an install directory
./configure
make test
Required to use Python bindings to IEGenLib:
* Python 2.7.2 known to work on linux and Mac
Requirements
* cmake 2.6 or newer
* C++ compiler, the below versions are known to work
Mac i686-apple-darwin10-g++-4.2.1,
GCC 4.6.3 20120306 (Red Hat 4.6.3-2)
* If re-generating parser files BISON 2.4 and FLEX 2.5 or newer
* If re-generating docs
* doxygen (http://www.stack.nl/~dimitri/doxygen/index.html,
known to work with 1.5.6 and 1.7.5)
* dot (http://www.graphviz.org)
* If rebuilding python bindings from source:
* swig version 2.0.4 for linux, version 1.3.40 for Mac known to work
** please note: if installing swig from macports 2 packages
are required: swig and swig-python
* If you plan to change the grammar for the sets or relations:
* Flex: version 2.5.35 known to work
* Bison: version 2.4.1 known to work
Please notify us if you find that other versions of these tools that
work or do not work for you.
Build files for the project are generated using cmake (except for the
distribution root-level Makefile that is included in the tar file).
Cmake version 2.6 or newer is required. Make files can be generated to
only build the binaries, to additionally generate the parser files,
and/or to additionally include Python bindings to the library. These
options are enabled through a configure script in the root of the
project. If the parser option is included, then additionally FLEX
version 2.5 or newer and BISON version 2.4 or newer are required. If
documentation is to be re-generated, then doxygen and dot are also
required to create it.
Run ./configure --help for more build configuration options.
The default install directory is ${IEGEN_DIR}/iegen/. This directory
may be changed using options to the configure script. Note that the
cmake system places binaries in an iegen/ directory, rather than an
iegen-LINUX64/ or iegen-MacOSX/ directory as are shipped in the
distribution.
===== Running Tests =====
The iegen/bin/run_iegenlib_tests binary can be executed to run the tests of
the various components of IEGenLib. Additionally, from the root of the
distribution you can run 'make test' to run these same tests.
The gtest framework is used for writing and running unit tests. Information
on gtest can be found at:
http://code.google.com/p/googletest/
and introductory documentation is at:
http://code.google.com/p/googletest/wiki/V1_6_Primer
===== Documentation =====
To create the doxygen documentation, run the following command:
make docs
An index.html file will be created in the distribution root directory, in
doc/html/. A latex pdf file, called refman.pdf will also be created, in the
doc/latex/ directory.
===== Debug and Release Builds =====
The default build is the debug build. It is set by cmake in the configure
script with -DCMAKE_BUILD_TYPE:STRING=Debug. The compiler options for the
debug build are '-O0 -g'.
To create a release version, use in the -build--release option to the
configure script. The compiler options for the release are '-O3 -DNDEBUG'.
To show actual build commands, you can run the verbose version of the build:
make install VERBOSE=1
===== Contact =====
For more information about the PIES project, please visit this URL:
http://www.cs.colostate.edu/hpc/PIES/
Or, please contact the PIES project director:
Dr. Michelle Strout, mstrout@cs.colostate.edu
1.7.5