LOGIC2CNF(1)

NAME
logic2cnf(1) is an extension of the popular minisat(1) SAT solver.

SYNOPSIS

logic2cnf [-c] [-d] [-g] [-h] [-jnum] [-l] [-m] [-p] [-r] [-s] [-x] [sourcefile]

DESCRIPTION

logic2cnf(1) is able to find all satisfiable results for any propositional logic formula. logic2cnf(1) was designed with ease of use in mind, therefore the user does not have to worry about the task of converting the formula into conjunctive normal form (CNF) or encoding into DIMACS.

By default logic2cnf(1) reads a program from standard input and processes it upon reading end-of-file. A number of resulting (satisfiable) variable assignments (if any) are then printed onto standard output. The default behaviour may be altered using command line options.

OPTIONS

-c
     Just print the DIMACS notation of the formula converted to CNF. This is useful if you want to use the formula with a different SAT solver.

-d
     Enable debugging information on standard error.

-g
     Dump parse/converted logic trees. The trees are dumped in graphviz dot(1) format to pt.dot and ast.dot.

-h
     Show help text.

-j num
     Find only up to `num' SAT results (to save time when prototyping).

-l
     Just print a textual logic notation of the formula once converted to CNF.

-m
     Enable the m4 pre-processing engine.

-p
     Disable the progress report on standard error.

-r
     Enable experimental optimiser. This will resolve away internal compiler variables, remove trivially true clauses, remove duplicate clauses/literals and remove superset clauses. Currently this process can be slow on large formulas.

-s
     Just print statistics and exit.

-x
     Leave intermediate m4 file behind after compilation.

INPUT LANGUAGE DESCRIPTION

The logic2cnf(1) input language is split into several sections which must appear in the following order:

Literal Definitions
    Each literal must be defined here before it is used.

Report Definitions
    Optionally the user may define a series of reporting

Universal Quantifier Elimination
    Apply universal quantification upon a number of literals.

Resolution Elimination
    Apply logic resolution to a number of variables.

Maximum/Minimum Specifications
    . It is possible to solve the upper or lower bound of a bit vector.

Formula Specification
    The logical formula itself. There may only be one logical formula per program.

The formula specification must appear last and variables must be defined first.

Lines beginning with a hash are ignored as comments.

  LITERAL DEFINITIONS

In the interest of typographic error detection, logic2cnf(1) uses a strict define-before-use scheme for literals. The def statement is used to define a list of space separated literals terminated by a semicolon.

The following example defines 3 literals for use in a logical formula:

def a b c;

  REPORT DEFINITIONS

By default logic2cnf(1) will emit literal assignments for every literal in the input formula. Often this is too much information and sometimes a series of literals will need to be interpreted as a number. For these reasons the following reporting statements were included:

report
    Takes a list of space separated literals (terminated by a semi-colon), causing these literals to be printed on a line for each satisfiable result found.

report_dec
    Takes a list of space separated literals(terminated by a semi-colon), interprets them as an unsigned number and prints the result on a line for each satisfiable result found. The first literal is the least significant bit in the binary representation.

Optionally, report or report_dec may be followed by a string enclosed in minus signs, for example:

report -hello- literal1;

Using a minus-encapsulated string on a report assigns it a comment which is printed alongside the report. This feature can be useful to identify the meaning of each report line in situations where reporting is used extensively.

If the user chooses to use a reporting statement, logic2cnf(1) no longer emits every literal; Instead it prints one line for each report statement, for each result onto standard output.

The following example prints the literals `a' and `b' on one line and the literals `a', `b' and `c' interpreted as an unsigned number on the next line for each result determined to be satisfiable by the SAT solver:

report a b;
report_dec a b c;

  UNIVERSAL QUANTIFIER ELIMINATION

Literals may be eliminated via universal quantifier elimination with the `uq_elim' keyword, which takes a space separated list of literals terminated by a colon. For example:

uq_elim a b c;

Please note that this feature is experimental.

  RESOLUTION ELIMINATION

Literals may be eliminated via logic resolution with the `resolve' keyword, which takes a space separated list of literals terminated by a colon.

resolve a b c;

Due to the nature of logic resolution, this feature may cause non-termination for formulae with many variables/clauses.

  MAXIMUM/MINIMUM SPECIFICATION

The 'find_min' and 'find_max' keywords may be used to find an minimum/maximum value of a bit vector as constrained by the formula. 'find_*' accepts a space separated list of literals (LSB first) and returns the uppermost/lowermost unsigned integer representation possible given the logical formula posed.

For example:

def a b c d;
find_max a b c d;
report_dec a b c d;
~(a.b.c.d) .  (a+b+c+d);

Gives the answer:
0: 14

The technique used to achieve this is described in detail in the paper: "Range and Set Abstraction using SAT" by Edd Barrett and Andy King.

  FORMULA SPECIFICATION

The logical formula itself is an ASCII representation of a logical formula terminated by a semi-colon, using any of the following tokens:

LITERAL
    Named (defined) literal.

.   And.

+   Or.

~ Not.

<=> IFF (Bi-implication).

<=  Left implication.

=>  Right implication.

@   Exclusive or.

(   Left Bracket.

)   Right Bracket.

  EXAMPLE INPUT AND OUTPUT

The following program:

# an example
def a b c;
report a b c;
report_dec a b c;
c . ((a.~b) + (b . ~a));

Gives the following output:

0: ~a  b  c
0: 6
1:  a ~b  c
1: 5

PRE-PROCESSOR SUPPORT (M4)

logic2cnf(1) supports m4 for preprocessing. If enabled, m4 is executed over the input stream and dumped into a temporary file, which is then fed to the parser.

m4 will look in the following path in the following order:

*   `pwd`/share/l2cstd/

*   `pwd`/

*   /usr/local/share/l2cstd/

*   share/l2cstd/ in the build directory.

A standard library of macros is being built in the /usr/local/share/l2cstd/ directory in your install. These macros will be documented at a later date, when they are considered stable.

FILES

No config files (yet).

SEE ALSO

minisat(1)

VERSION

This is Logic2CNF-0.7.2.

LICENSE AND COPYRIGHT

The majority of Logic2CNF is distributed under an ISC license. The integrated MiniSAT code is distributed under a MIT license.

BUGS

Likely. You may raise bug tickets at the Logic2CNF WWW page:
http://projects.cs.kent.ac.uk/projects/logic2cnf/trac

AUTHOR

Edd Barrett <e.barrett@kent.ac.uk>