python-sat 1.8.dev25__cp310-cp310-macosx_11_0_arm64.whl

pysat/__init__.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## __init__.py
+##
+##  Created on: Mar 4, 2017
+##      Author: Alexey S. Ignatiev
+##      E-mail: aignatiev@ciencias.ulisboa.pt
+##
+
+# current version
+#==============================================================================
+VERSION = (1, 8, 'dev', 25)
+
+
+# PEP440 Format
+#==============================================================================
+__version__ = '%d.%d.%s%d' % VERSION if len(VERSION) == 4 else \
+              '%d.%d.%d' % VERSION
+
+
+# all submodules
+#==============================================================================
+__all__ = ['card', 'engines', 'formula', 'pb', 'process', 'solvers']

pysat/_fileio.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## _fileio.py
+##
+##  Created on: Aug 18, 2018
+##      Author: Alexey S. Ignatiev
+##      E-mail: aignatiev@ciencias.ulisboa.pt
+##
+
+"""
+    ===============
+    List of classes
+    ===============
+
+    .. autosummary::
+        :nosignatures:
+
+        FileObject
+
+    ==================
+    Module description
+    ==================
+
+    This simple module provides a basic interface to input/output operations
+    on files. Its key design feature is the ability to work with both
+    uncompressed and compressed files through a unified interface, thus,
+    making it easier for a user to deal with various types of compressed
+    files. The compression types supported include gzip, bzip2, lzma (xz), and
+    zstandard (zstd).
+
+    The module is supposed to be mainly used by :mod:`pysat.formula`.
+
+    A simple usage example is the following:
+
+    .. code-block:: python
+
+        >>> from pysat._fileio import FileObject
+        >>>
+        >>> with FileObject(name='formula.cnf', mode='r') as fp1:
+        ...     contents1 = fp1.readlines()
+        >>>
+        >>> with FileObject(name='filename.txt.gz', compression='use_ext') as fp2:
+        ...     contents2 = fp2.readlines()
+        >>>
+        >>> with FileObject(name='f.txt.bz2', mode='w', compression='bzip2') as fp3:
+        ...     fp3.write('hello, world!\n')
+
+    ==============
+    Module details
+    ==============
+"""
+
+#
+#==============================================================================
+import bz2
+import codecs
+import gzip
+import os
+
+lzma_present = True
+try:  # for Python3
+    import lzma
+except ImportError:
+    try:  # for Python2 + backports.lzma installed
+        from backports import lzma
+    except ImportError:  # for Python2 without lzma
+        lzma_present = False
+
+zstd_present = True
+try:
+    from compression import zstd
+except ImportError:  # zstandard is introduced in Python 3.14
+    zstd_present = False
+
+
+
+#
+#==============================================================================
+class FileObject(object):
+    """
+        Auxiliary class for convenient and uniform file manipulation, e.g. to
+        open files creating standard file pointers and closing them. The class
+        is used when opening DIMACS files for reading and writing. Supports
+        both uncompressed and compressed files. Compression algorithms
+        supported are ``gzip``, ``bzip2``, ``lzma``, and ``zstd``. Algorithm
+        ``lzma`` can be used in Python 3 by default and also in Python 2 if
+        the ``backports.lzma`` package is installed. Algorithm ``zstandard``
+        can be used in Python 3.14 and later.
+
+        Note that the class opens a file in text mode.
+
+        :param name: a file name to open
+        :param mode: opening mode
+        :param compression: compression type
+
+        :type name: str
+        :type mode: str
+        :type compression: str
+
+        Compression type can be ``None``, ``'gzip'``, ``'bzip2'``, ``'lzma'``,
+        ``'zstd'``, as well as ``'use_ext'``. If ``'use_ext'`` is specified,
+        compression algorithm is defined by the extension of the given file
+        name.
+    """
+
+    def __init__(self, name, mode='r', compression=None):
+        """
+            Constructor.
+        """
+
+        self.fp = None  # file pointer to give access to
+        self.ctype = None  # compression type
+
+        # in some cases an additional file pointer is needed
+        self.fp_extra = None
+
+        self.open(name, mode=mode, compression=compression)
+
+    def open(self, name, mode='r', compression=None):
+        """
+            Open a file pointer. Note that a file is *always* opened in
+            text mode. The method inherits its input parameters from the
+            constructor of :class:`FileObject`.
+        """
+
+        if compression == 'use_ext':
+            self.get_compression_type(name)
+        else:
+            self.ctype = compression
+
+        if not self.ctype:
+            self.fp = open(name, mode)
+        elif self.ctype == 'gzip':
+            self.fp = gzip.open(name, mode + 't')
+        elif self.ctype == 'bzip2':
+            try:
+                # Python 3 supports opening bzip2 files in text mode
+                # therefore, we prefer to open them this way
+                self.fp = bz2.open(name, mode + 't')
+            except:
+                # BZ2File opens a file in binary mode
+                # thus, we have to use codecs.getreader()
+                # to be able to use it in text mode
+                self.fp_extra = bz2.BZ2File(name, mode)
+
+                if mode == 'r':
+                    self.fp = codecs.getreader('ascii')(self.fp_extra)
+                else:  # mode == 'w'
+                    self.fp = codecs.getwriter('ascii')(self.fp_extra)
+        elif self.ctype == 'lzma':
+            # LZMA is available in Python 2 only if backports.lzma is installed
+            # Python 3 supports it by default
+            assert lzma_present, 'LZMA compression is unavailable.'
+            self.fp = lzma.open(name, mode=mode + 't')
+        else:  # self.ctype == 'zstd'
+            # Zstandard is available only in Python 3.14 and later
+            assert zstd_present, 'Zstandard compression is unavailable.'
+            self.fp = zstd.open(name, mode=mode + 't')
+
+    def close(self):
+        """
+            Close a file pointer.
+        """
+
+        if self.fp:
+            self.fp.close()
+            self.fp = None
+
+        if self.fp_extra:
+            self.fp_extra.close()
+            self.fp_extra = None
+
+        self.ctype = None
+
+    def get_compression_type(self, file_name):
+        """
+            Determine compression type for a given file using its extension.
+
+            :param file_name: a given file name
+            :type file_name: str
+        """
+
+        ext = os.path.splitext(file_name)[1]
+
+        if ext == '.gz':
+            self.ctype = 'gzip'
+        elif ext == '.bz2':
+            self.ctype = 'bzip2'
+        elif ext in ('.xz', '.lzma'):
+            self.ctype = 'lzma'
+        elif ext == '.zst':
+            self.ctype = 'zstd'
+        else:
+            self.ctype = None
+
+    def __enter__(self):
+        """
+            'with' constructor.
+        """
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """
+            'with' destructor.
+        """
+
+        self.close()

pysat/_utils.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## _utils.py
+##
+##  Created on: Nov 27, 2019
+##      Author: Alexey S. Ignatiev
+##      E-mail: aignatiev@ciencias.ulisboa.pt
+##
+
+"""
+    ===============
+    List of classes
+    ===============
+
+    .. autosummary::
+        :nosignatures:
+
+        MainThread
+
+    ==================
+    Module description
+    ==================
+
+    This simple module is supposed to implement auxiliary classes and routines
+    that are used by the other (main) modules of PySAT.
+
+    ==============
+    Module details
+    ==============
+"""
+
+#
+#==============================================================================
+import threading
+
+
+#
+#==============================================================================
+class MainThread(object):
+    """
+        A dummy class for checking whether the current thread is the main one.
+        This is currently necessary for proper signal handling when making
+        oracle calls and creating cardinality encodings.
+    """
+
+    @staticmethod
+    def check():
+        """
+            The actual checker.
+        """
+
+        try:  # for Python > 3.4
+            res = threading.current_thread() is threading.main_thread()
+        except AttributeError:
+            res = isinstance(threading.current_thread(), threading._MainThread)
+
+        return res

pysat/allies/approxmc.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python
+#-*- coding:utf-8 -*-
+##
+## approxmc.py
+##
+##  Created on: Apr 14, 2023
+##      Author: Mate Soos
+##      E-mail: soos.mate@gmail.com
+##
+
+"""
+    ===============
+    List of classes
+    ===============
+
+    .. autosummary::
+        :nosignatures:
+
+        Counter
+
+    ==================
+    Module description
+    ==================
+
+    This module provides interface to `ApproxMCv4
+    <https://github.com/meelgroup/approxmc/>`_, a state-of-the-art
+    *approximate* model counter utilising an improved version of CryptoMiniSat
+    to give approximate model counts to problems of size and complexity that
+    are out of reach for earlier approximate model counters. The original work
+    on ApproxMCv4 has been published in [1]_ and [2]_.
+
+    .. [1] Mate Soos, Kuldeep S. Meel. *BIRD: Engineering an Efficient CNF-XOR
+        SAT Solver and Its Applications to Approximate Model Counting*. AAAI
+        2019. pp. 1592-1599
+
+    .. [2] Mate Soos, Stephan Gocht, Kuldeep S. Meel. *Tinted, Detached, and
+        Lazy CNF-XOR Solving and Its Applications to Counting and Sampling*.
+        CAV 2020. pp. 463-484
+
+    Note that to be functional, the module requires package ``pyapproxmc`` to
+    be installed:
+
+    ::
+
+        $ pip install pyapproxmc
+
+    The interface gives access to :class:`Counter`, which expects a formula in
+    :class:`.CNF` as input. Given a few additional (optional) arguments,
+    including a random seed, *tolerance factor* :math:`\\varepsilon`, and
+    *confidence* :math:`\\delta`, the class can be used to get an approximate
+    number of models of the formula, subject to the given tolerance factor and
+    confidence parameter.
+
+    Namely, given a CNF formula :math:`\\mathcal{F}` with
+    :math:`\\#\\mathcal{F}` as the exact number of models, and parameters
+    :math:`\\varepsilon\\in(0,1]` and :math:`\\delta\\in[0,1)`, the counter
+    computes and reports a value :math:`C`, which is an approximate number of
+    models of :math:`\\mathcal{F}`, such that
+    :math:`\\textrm{Pr}\\left[\\frac{1}{1+\\varepsilon}\\#\\mathcal{F}\\leq
+    C\\leq (1+\\varepsilon)\\#\\mathcal{F}\\right]\\geq 1-\\delta`.
+
+    The implementation can be used as an executable (the list of available
+    command-line options can be shown using ``approxmc.py -h``) in the
+    following way:
+
+    ::
+
+        $ xzcat formula.cnf.xz
+        p cnf 20 2
+        1 2 3 0
+        3 20 0
+
+        $ approxmc.py -p 1,2,3-9 formula.cnf.xz
+        s mc 448
+
+    Alternatively, the algorithm can be accessed and invoked through the
+    standard ``import`` interface of Python, e.g.
+
+    .. code-block:: python
+
+        >>> from pysat.allies.approxmc import Counter
+        >>> from pysat.formula import CNF
+        >>>
+        >>> cnf = CNF(from_file='formula.cnf.xz')
+        >>>
+        >>> with Counter(cnf) as counter:
+        ...     print(counter.counter(projection=range(1, 10))
+        448
+
+    As can be seen in the above example, besides model counting across all the
+    variables in a given input formula, the counter supports *projected* model
+    counting, i.e. when one needs to approximate the number of models with
+    respect to a given list of variables rather than with respect to all
+    variables appearing in the formula. This feature comes in handy when the
+    formula is obtained, for example, through Tseitin transformation [3]_ with
+    a number of auxiliary variables introduced.
+
+    .. [3] G. S. Tseitin. *On the complexity of derivations in the
+        propositional calculus*. Studies in Mathematics and Mathematical
+        Logic, Part II. pp. 115–125, 1968
+
+    ==============
+    Module details
+    ==============
+"""
+
+#
+#==============================================================================
+from __future__ import print_function
+import getopt
+import os
+from pysat.formula import CNF
+import re
+import sys
+
+# we need pyapproxmc to be installed:
+pyapproxmc_present = True
+try:
+    import pyapproxmc
+except ImportError:
+    pyapproxmc_present = False
+
+
+#
+#==============================================================================
+class Counter(object):
+    """
+        A wrapper for `ApproxMC <https://github.com/meelgroup/approxmc/>`_, a
+        state-of-the-art *approximate* model counter. Given a formula in
+        :class:`.CNF`, this class can be used to get an approximate number of
+        models of the formula, subject to *tolerance factor* ``epsilon`` and
+        *confidence parameter* ``delta``.
+
+        Namely, given a CNF formula :math:`\\mathcal{F}` and parameters
+        :math:`\\varepsilon\\in(0,1]` and :math:`\\delta\\in[0,1)`, the
+        counter computes and reports a value :math:`C` such that
+        :math:`\\textrm{Pr}\\left[\\frac{1}{1+\\varepsilon}\\#\\mathcal{F}\\leq
+        C\\leq (1+\\varepsilon)\\#\\mathcal{F}\\right]\\geq 1-\\delta`. Here,
+        :math:`\\#\\mathcal{F}` denotes the exact model count for formula
+        :math:`\\mathcal{F}`.
+
+        The ``formula`` argument can be left unspecified at this stage. In
+        this case, a user is expected to add all the relevant clauses using
+        :meth:`add_clause`.
+
+        An additional parameter a user may want to specify is integer ``seed``
+        used by ApproxMC. The value of ``seed`` is set to ``1`` by default.
+
+        :param formula: CNF formula
+        :param seed: integer seed value
+        :param epsilon: tolerance factor
+        :param delta: confidence parameter
+        :param verbose: verbosity level
+
+        :type formula: :class:`.CNF`
+        :type seed: int
+        :type epsilon: float
+        :type delta: float
+        :type verbose: int
+
+        .. code-block:: python
+
+            >>> from pysat.allies.approxmc import Counter
+            >>> from pysat.formula import CNF
+            >>>
+            >>> cnf = CNF(from_file='some-formula.cnf')
+            >>> with Counter(formula=cnf, epsilon=0.1, delta=0.9) as counter:
+            ...     num = counter.count() # an approximate number of models
+    """
+
+    def __init__(self, formula=None, seed=1, epsilon=0.8, delta=0.2, verbose=0):
+        """
+            Constructor.
+        """
+
+        assert pyapproxmc_present, 'Package \'pyapproxmc\' is unavailable. Check your installation.'
+
+        # there are no initial counts
+        self.cellc, self.hashc = None, None
+
+        # creating the Counter object
+        self.counter = pyapproxmc.Counter(verbosity=verbose, seed=seed,
+                                          epsilon=epsilon, delta=delta)
+
+        # adding clauses to the counter
+        if formula:
+            for clause in formula:
+                self.add_clause(clause)
+
+    def __del__(self):
+        """
+            Destructor.
+        """
+
+        self.delete()
+
+    def __enter__(self):
+        """
+            'with' constructor.
+        """
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """
+            'with' destructor.
+        """
+
+        self.delete()
+
+    def add_clause(self, clause):
+        """
+            The method for adding a clause to the problem formula. Although
+            the input formula can be specified as an argument of the
+            constructor of :class:`Counter`, adding clauses may also be
+            helpful afterwards, *on the fly*.
+
+            The clause to add can be any iterable over integer literals.
+
+            :param clause: a clause to add
+            :type clause: iterable(int)
+
+            .. code-block:: python
+
+                >>> from pysat.allies.approxmc import Counter
+                >>>
+                >>> with Counter() as counter:
+                ...     counter.add_clause(range(1, 4))
+                ...     counter.add_clause([3, 20])
+                ...
+                ...     print(counter.count())
+                720896
+        """
+
+        self.counter.add_clause(clause)
+
+    def count(self, projection=None):
+        """
+
+            Given the formula provided by the user either in the constructor
+            of :class:`Counter` or through a series of calls to
+            :meth:`add_clause`, this method runs the ApproxMC counter with the
+            specified values of tolerance :math:`\\varepsilon` and confidence
+            :math:`\\delta` parameters, as well as the random ``seed`` value,
+            and returns the number of models estimated.
+
+            A user may specify an argument ``projection``, which is a list of
+            integers specifying the variables with respect to which projected
+            model counting should be performed. If ``projection`` is left as
+            ``None``, approximate model counting is performed wrt. all the
+            variables of the input formula.
+
+            :param projection: variables to project on
+            :type projection: list(int)
+
+            .. code-block:: python
+
+                >>> from pysat.allies.approxmc import Counter
+                >>> from pysat.card import CardEnc, EncType
+                >>>
+                >>> # cardinality constraint with auxiliary variables
+                >>> # there are exactly 70 models for the constraint
+                >>> # over the 8 original variables
+                >>> cnf = CardEnc.equals(lits=range(1, 9), bound=4, encoding=EncType.cardnetwrk)
+                >>>
+                >>> with Counter(formula=cnf, epsilon=0.05, delta=0.95) as counter:
+                ...     print(counter.count())
+                123840
+                >>>
+                >>> with Counter(formula=cnf, epsilon=0.05, delta=0.95) as counter:
+                ...     print(counter.count(projection=range(1, 8)))
+                70
+        """
+
+        if projection is not None:
+            self.cellc, self.hashc = self.counter.count(projection=projection)
+        else:
+            self.cellc, self.hashc = self.counter.count()
+
+        return self.cellc * (2 ** self.hashc)
+
+    def delete(self):
+        """
+            Explicit destructor of the internal Counter oracle.
+            Delete the actual counter object and sets it to ``None``.
+        """
+
+        if self.counter:
+            del self.counter
+            self.counter = None
+
+
+#
+#==============================================================================
+def parse_options():
+    """
+        Parses command-line option
+    """
+
+    try:
+        opts, args = getopt.getopt(sys.argv[1:], 'd:e:hp:s:v:',
+                ['delta=', 'epsilon=', 'help', 'projection=', 'seed=', 'verbose='])
+    except getopt.GetoptError as err:
+        sys.stderr.write(str(err).capitalize())
+        usage()
+        sys.exit(1)
+
+    delta = 0.2
+    epsilon = 0.8
+    projection = None
+    seed = 1
+    verbose = 0
+
+    for opt, arg in opts:
+        if opt in ('-d', '--delta'):
+            delta = float(arg)
+        elif opt in ('-e', '--epsilon'):
+            epsilon = float(arg)
+        elif opt in ('-h', '--help'):
+            usage()
+            sys.exit(0)
+        elif opt in ('-p', '--projection'):
+            # parsing the list of variables
+            projection, values = [], str(arg).split(',')
+
+            # checking if there are intervals
+            for value in values:
+                if value.isnumeric():
+                    projection.append(int(value))
+                elif '-' in value:
+                    lb, ub = value.split('-')
+                    assert int(lb) < int(ub)
+                    projection.extend(list(range(int(lb), int(ub) + 1)))
+
+            # removing duplicates, if any
+            projection = sorted(set(projection))
+        elif opt in ('-s', '--seed'):
+            seed = int(arg)
+        elif opt in ('-v', '--verbose'):
+            verbose = int(arg)
+        else:
+            assert False, 'Unhandled option: {0} {1}'.format(opt, arg)
+
+    return delta, epsilon, projection, seed, verbose, args
+
+
+#
+#==============================================================================
+def usage():
+    """
+        Prints usage message.
+        """
+
+    print('Usage:', os.path.basename(sys.argv[0]), '[options] dimacs-file')
+    print('Options:')
+    print('        -d, --delta=<float>        Confidence parameter as per PAC guarantees')
+    print('                                   Available values: [0, 1) (default = 0.2)')
+    print('        -e, --epsilon=<float>      Tolerance factor as per PAC guarantees')
+    print('                                   Available values: (0 .. 1], all (default = 0.8)')
+    print('        -p, --projection=<list>    Do model counting projected on this set of variables')
+    print('                                   Available values: comma-separated-list, none (default = none)')
+    print('        -s, --seed=<int>           Random seed')
+    print('                                   Available values: [0 .. INT_MAX] (default = 1)')
+    print('        -v, --verbose=<int>        Verbosity level')
+    print('                                   Available values: [0 .. 15] (default = 0)')
+
+
+#
+#==============================================================================
+if __name__ == '__main__':
+    delta, epsilon, projection, seed, verbose, files = parse_options()
+
+    # parsing the input formula
+    if files and re.search(r'\.cnf(\.(gz|bz2|lzma|xz))?$', files[0]):
+        formula = CNF(from_file=files[0])
+
+        # creating the counter object
+        with Counter(formula, seed=seed, epsilon=epsilon, delta=delta,
+                        verbose=verbose) as counter:
+
+            # approximate model counting
+            count = counter.count(projection=projection)
+
+            # printing the result
+            print('s mc', count)