Linux	Windows	Test Coverage	SonarSource	Codacy

JamSAT

JamSAT is a fast, clean incremental SAT solver implementing the IPASIR interface. Though not being a descendant of Minisat, this solver is heavily influenced by Minisat, Glucose and the Candy Kingdom. Hence the marmalade-themed name.

Being a relatively young SAT solver as well as a side project, JamSAT is yet missing some important features. The implementation status section contains a summary of its capabilities.

JamSAT is free software distributed under the MIT license (X11 variant).

Table of contents:

Scope
Supported Platforms and Ecosystems
Building JamSAT
Using JamSAT
Implementation Status
Developer Documentation

Scope

While JamSAT can be used as a generic SAT solver, its focus lies on solving problem instances arising from industrial applications such as model checking, artificial intelligence, circuit equivalence checking and SMT solving. More specifically, it is optimized for agile SAT solving: it is designed to efficiently solve vast numbers of SAT problem instances that are not very hard individually.

Supported Platforms and Ecosystems

JamSAT is regularly built and tested using the following configurations:

Operating System	Compilers
GNU/Linux	clang 7, gcc 8
Apple macOS	clang (XCode 10.1 / Apple Clang 10)
Microsoft Windows	Visual C++ 2017

A compiler supporting C++17 is required to build JamSAT.

JamSAT integrates nicely with CMake projects. The repository contains an example showing how to use JamSAT in client applications. Support for pkg-config is planned, but not yet implemented.

Building JamSAT

The following prerequisites must be present on your system:

CMake (at least version 3.12)
a C++ compiler with C++17 support
Boost (at least version 1.59)
zlib
(optionally) GSL (at least version 3.1.0; see the option JAMSAT_USE_VENDORED_GSL)

Building without tests

To build JamSAT, execute the following commands, with <I> being the directory where JamSAT shall be installed:

git clone https://github.com/fkutzner/JamSAT
cd JamSAT
git submodule init
git submodule update
cd ..
mkdir JamSAT-build
cd JamSAT-build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<I> ../jamsat
cmake --build . --target install

Note for Windows builds: You'll need to pass the path to Boost and the zlib installation to the first cmake invocation as well. See the AppVeyor configuration for a build recipe.

Building with tests

Building the JamSAT test suite can be enabled by additionally passing the argument -DJAMSAT_ENABLE_TESTING=ON to the first cmake invocation.

To run the test suite, navigate to JamSAT's build directory (e.g. the JamSAT-build created in the script above) and run ctest. JamSAT supports fuzz testing with afl-fuzz. To enable fuzzing, pass -DJAMSAT_ENABLE_AFL_FUZZER=ON to the first cmake invocation. You can then fuzz-test JamSAT by building the target barecdclsolver_fuzzer-run. Fuzzing results will be placed in the directory bin/barecdclsolver_fuzzer-fuzzer-findings.

See the Travis CI build script or AppVeyor configuration for a more detailed description of building with testing enabled.

Build Options

Set options by passing -D<OPTION>=ON|OFF to cmake, e.g. -DJAMSAT_ENABLE_TESTING=ON. Unless otherwise noted, options are set to OFF by default. The list of JamSAT build options is given below.

Controlling the scope of the build

JAMSAT_ENABLE_TESTING - Enable building the JamSAT test suite.

3rd party libraries

JAMSAT_USE_SYSTEM_GSL - Search for the Microsoft GSL in the CMake module search path. If OFF (which is the default), the GSL included in deps/GSL is used for building JamSAT.

General compiler and linker settings

JAMSAT_BUILD_STATIC_LIB - Build the JamSAT library as a static library
JAMSAT_DISABLE_BOOST_LINKING_SETUP - Don't override linker settings for Boost

Logging

JAMSAT_ENABLE_LOGGING - Enable logging.
JAMSAT_LOGGING_DEFAULT_START_EPOCH - The first logging epoch in which logging is performed. Currently, a new logging epoch starts at every CDCL conflict. After this logging epoch, logging remains enabled. The default value is 0. This option only has an effect if JAMSAT_ENABLE_LOGGING is set to ON.

When logging is enabled, JamSAT emits very fine-grained logging information. This can slow down the solver and produce masses of extraneous data, making it infeasible to use full logging for large SAT problem instances. For effective logging, either

use fuzz testing to find a small input example for the bug you're trying to fix and use full logging to understand it,
or use the JAMSAT_LOGGING_DEFAULT_START_EPOCH option to restrict logging to the last few (1000 to 10000) conflicts before observing the behaviour you are investigating.

Debugging

JAMSAT_ENABLE_AFL_FUZZER - Use afl-clang rsp. afl-gcc for compilation and build the fuzzing targets for AFL
JAMSAT_DISABLE_OPTIMIZATIONS - Disable compiler optimimzations
JAMSAT_ENABLE_ASAN - Enable the address sanitizer if the compiler supports address sanitizing
JAMSAT_ENABLE_UBSAN - Enable the undefined-behaviour sanitizer if the compiler supports undefined-behaviour sanitizing
JAMSAT_ENABLE_RELEASE_ASSERTIONS Enable release-mode assertions
JAMSAT_ENABLE_EXPENSIVE_ASSERTIONS - Enable more thorough, but expensive assertions
JAMSAT_ENABLE_COVERAGE - Enable code coverage measurements. Currently only works on Linux and macOS and produces lcov-readable coverage data.

Using JamSAT

See Using JamSAT

Implementation Status

Capability	Status
Incremental SAT solving	Supported
IPASIR interface	Mostly supported
Problem simplification	Partially supported
UNSAT Certificates	TODO

Problem Simplification

JamSAT employs inprocessing techniques to simplify the problem-instance during the solving process, leveraging lemmas derived from the instance. Currently, JamSAT implements the following techniques:

Clause subsumption with hyper-binary resolution
Self-subsuming resolution with hyper-binary resolution
Failed Literal Elimination

IPASIR Implementation Status

Function	Status
ipasir_signature	Supported
ipasir_init	Supported
ipasir_release	Supported
ipasir_add	Supported
ipasir_assume	Supported
ipasir_solve	Supported
ipasir_val	Supported
ipasir_failed	Supported
ipasir_set_terminate	Supported
ipasir_set_learn	TODO

Developer Documentation

Reference manual: Build the target doxygen to generate JamSAT's developer documentation, which can then be browsed at <JamSAT-Build-Dir>/doc/html/index.html. The Doxygen documentation system is required to build the documentation.
Repository description

fkutzner / JamSAT