python-sat 1.9.dev20__cp314-cp314t-win_amd64.whl

python_sat-1.9.dev20.data/scripts/optux.py

@@ -0,0 +1,750 @@
+#!python
+#-*- coding:utf-8 -*-
+##
+## optux.py
+##
+##  Created on: Mar 22, 2021
+##      Author: Alexey Ignatiev
+##      E-mail: alexey.ignatiev@monash.edu
+##
+
+"""
+    ===============
+    List of classes
+    ===============
+
+    .. autosummary::
+        :nosignatures:
+
+        OptUx
+
+    ==================
+    Module description
+    ==================
+
+    An implementation of an extractor of a smallest size minimal unsatisfiable
+    subset (smallest MUS, or SMUS) [1]_ [2]_ [3]_ [4]_ and enumerator of
+    SMUSes based on *implicit hitting set enumeration* [1]_. This
+    implementation tries to replicate the well-known SMUS extractor Forqes
+    [1]_. In contrast to Forqes, this implementation supports not only plain
+    DIMACS :class:`.CNF` formulas but also weighted :class:`.WCNF` formulas.
+    As a result, the tool is able to compute and enumerate *optimal* MUSes in
+    case of weighted formulas. On the other hand, this prototype lacks a
+    number of command-line options used in Forqes and so it may be less
+    efficient compared to Forqes but the performance difference should not be
+    significant.
+
+    .. [1] Alexey Ignatiev, Alessandro Previti, Mark H. Liffiton, Joao
+        Marques-Silva. *Smallest MUS Extraction with Minimal Hitting Set
+        Dualization*. CP 2015. pp. 173-182
+
+    .. [2] Mark H. Liffiton, Maher N. Mneimneh, Ines Lynce, Zaher S. Andraus,
+        Joao Marques-Silva, Karem A. Sakallah. *A branch and bound algorithm
+        for extracting smallest minimal unsatisfiable subformulas*.
+        Constraints An Int. J. 14(4). 2009. pp. 415-442
+
+    .. [3] Alexey Ignatiev, Mikolas Janota, Joao Marques-Silva. *Quantified
+        Maximum Satisfiability: A Core-Guided Approach*. SAT 2013.
+        pp. 250-266
+
+    .. [4] Alexey Ignatiev, Mikolas Janota, Joao Marques-Silva. *Quantified
+        maximum satisfiability*. Constraints An Int. J. 21(2). 2016.
+        pp. 277-302
+
+    The file provides a class :class:`OptUx`, which is the basic
+    implementation of the algorithm. It can be applied to any formula in the
+    :class:`.CNF` or :class:`.WCNF` format.
+
+    The implementation can be used as an executable (the list of available
+    command-line options can be shown using ``optux.py -h``) in the following
+    way:
+
+    ::
+
+        $ xzcat formula.wcnf.xz
+        p wcnf 3 6 4
+        1 1 0
+        1 2 0
+        1 3 0
+        4 -1 -2 0
+        4 -1 -3 0
+        4 -2 -3 0
+
+        $ optux.py -vvv formula.wcnf.xz
+        c mcs: 1 2 0
+        c mcses: 0 unit, 1 disj
+        c mus: 1 2 0
+        c cost: 2
+        c oracle time: 0.0001
+
+    Alternatively, the algorithm can be accessed and invoked through the
+    standard ``import`` interface of Python, e.g.
+
+    .. code-block:: python
+
+        >>> from pysat.examples.optux import OptUx
+        >>> from pysat.formula import WCNF
+        >>>
+        >>> wcnf = WCNF(from_file='formula.wcnf.xz')
+        >>>
+        >>> with OptUx(wcnf) as optux:
+        ...     for mus in optux.enumerate():
+        ...         print('mus {0} has cost {1}'.format(mus, optux.cost))
+        mus [1, 2] has cost 2
+        mus [1, 3] has cost 2
+        mus [2, 3] has cost 2
+
+    As can be seen in the example above, the solver can be instructed either
+    to compute one optimal MUS of an input formula, or to enumerate a given
+    number (or *all*) of its top optimal MUSes.
+
+    ==============
+    Module details
+    ==============
+"""
+
+#
+#==============================================================================
+from __future__ import print_function
+import getopt
+import os
+from pysat.examples.hitman import Atom, Hitman
+from pysat.examples.rc2 import RC2
+from pysat.formula import CNFPlus, WCNFPlus
+from pysat.process import Processor
+from pysat.solvers import Solver, SolverNames
+import re
+import sys
+
+
+#
+#==============================================================================
+class OptUx(object):
+    """
+        A simple Python version of the implicit hitting set based optimal MUS
+        extractor and enumerator. Given a (weighted) (partial) CNF formula,
+        i.e. formula in the :class:`.WCNF` format, this class can be used to
+        compute a given number of optimal MUS (starting from the *best* one)
+        of the input formula. :class:`OptUx` roughly follows the
+        implementation of Forqes [1]_ but lacks a few additional heuristics,
+        which however aren't applied in Forqes by default.
+
+        As a result, OptUx applies exhaustive *disjoint* minimal correction
+        subset (MCS) enumeration [1]_, [2]_, [3]_, [4]_ with the incremental
+        use of RC2 [5]_ as an underlying MaxSAT solver. Disjoint MCS
+        enumeration is run only if the corresponding input parameter
+        ``nodisj`` is set to ``False``. Once disjoint MCSes are enumerated,
+        they are used to bootstrap a hitting set solver. This implementation
+        uses :class:`.Hitman` as a hitting set solver, which is again based on
+        RC2.
+
+        Note that in the main implicit hitting enumeration loop of the
+        algorithm, OptUx follows Forqes in that it does not reduce correction
+        subsets detected to minimal correction subsets. As a result,
+        correction subsets computed in the main loop are added to
+        :class:`Hitman` *unreduced*.
+
+        :class:`OptUx` can use any SAT solver available in PySAT. The default
+        SAT solver to use is ``g3``, which stands for Glucose 3 [6]_ (see
+        :class:`.SolverNames`). Boolean parameters ``adapt``, ``exhaust``, and
+        ``minz`` control whether or not the underlying :class:`.RC2` oracles
+        should apply detection and adaptation of intrinsic AtMost1
+        constraints, core exhaustion, and core reduction. Also, unsatisfiable
+        cores can be trimmed if the ``trim`` parameter is set to a non-zero
+        integer. Finally, verbosity level can be set using the ``verbose``
+        parameter.
+
+        Two additional optional parameters ``unsorted`` and ``dcalls`` can be
+        used to instruct the tool to enumerate MUSes in the unsorted fashion,
+        i.e. optimal MUSes are not guaranteed to go first. For this,
+        :class:`OptUx` applies LBX-like MCS enumeration (it uses :class:`.LBX`
+        directly). Parameter ``dcalls`` can be applied to instruct the
+        underlying MCS enumerator to apply clause D oracle calls.
+
+        Another optional paramater ``puresat`` can be used to instruct OptUx
+        to run a purely SAT-based minimal hitting set enumerator, following
+        the ideas of [7]_. The value of ``puresat`` can be either ``False``,
+        meaning that no pure SAT enumeration is to be done or be equal to
+        ``'mgh'``, ``'cd15'``, or ``'lgl'`` - these are the solvers that
+        support *hard* phase setting, i.e. user preferences will not be
+        overwritten by the *phase saving* heuristic [8]_.
+
+        Additionally, the input formula can be preprocessed before running MUS
+        enumeration. This is controlled by the input parameter ``process``
+        whose integer value signifies the number of processing rounds to be
+        applied. The number of rounds is set to 0 by default.
+
+        Since the algorithm builds on implicit hitting set dualization,
+        correction sets computed along the way can be minimized
+        *heuristically*, by limiting the budget on the number of conflicts a
+        SAT solver can collect during the minimization process. Parameter
+        ``reduce`` is responsible for this behaviour. By default, the budget
+        is set to ``0``, meaning that no reduction of correction sets is
+        performed. Setting it to ``-1`` forces the solver to compute an exact
+        MCS. Otherwise, any positive value of this parameter will indicate the
+        upper bound on the number of conflicts.
+
+        Finally, one more optional input parameter ``cover`` is to be used
+        when exhaustive enumeration of MUSes is not necessary and the tool can
+        stop as soon as a given formula is covered by the set of currently
+        computed MUSes. This can be made to work if the soft clauses of
+        ``formula`` are of size 1.
+
+        .. [5] Alexey Ignatiev, Antonio Morgado, Joao Marques-Silva. *RC2: an
+            Efficient MaxSAT Solver*. J. Satisf. Boolean Model. Comput. 11(1).
+            2019. pp. 53-64
+
+        .. [6] Gilles Audemard, Jean-Marie Lagniez, Laurent Simon.
+            *Improving Glucose for Incremental SAT Solving with
+            Assumptions: Application to MUS Extraction*. SAT 2013.
+            pp. 309-317
+
+        .. [7] Enrico Giunchiglia, Marco Maratea. *Solving Optimization
+            Problems with DLL*. ECAI 2006. pp. 377-381
+
+        .. [8] Knot Pipatsrisawat, Adnan Darwiche. *A Lightweight Component
+            Caching Scheme for Satisfiability Solvers*. SAT 2007. pp. 294-299
+
+
+        :param formula: (weighted) (partial) CNFPlus formula
+        :param solver: SAT oracle name
+        :param adapt: detect and adapt intrinsic AtMost1 constraints
+        :param cover: CNFPlus formula to cover when doing MUS enumeration
+        :param dcalls: apply clause D oracle calls (for unsorted enumeration only)
+        :param exhaust: do core exhaustion
+        :param minz: do heuristic core reduction
+        :param nodisj: do not enumerate disjoint MCSes
+        :param process: apply formula preprocessing this many times
+        :param puresat: use pure SAT-based hitting set enumeration
+        :param reduce: minimize correction sets using this budget on the number of conflicts
+        :param unsorted: apply unsorted MUS enumeration
+        :param trim: do core trimming at most this number of times
+        :param verbose: verbosity level
+
+        :type formula: :class:`.WCNFPlus`
+        :type solver: str
+        :type adapt: bool
+        :type cover: :class:`.CNFPlus`
+        :type dcalls: bool
+        :type exhaust: bool
+        :type minz: bool
+        :type nodisj: bool
+        :type process: int
+        :type puresat: str
+        :type reduce: int
+        :type unsorted: bool
+        :type trim: int
+        :type verbose: int
+    """
+
+    def __init__(self, formula, solver='g3', adapt=False, cover=None,
+            dcalls=False, exhaust=False, minz=False, nodisj=False, process=0,
+            puresat=False, reduce=0, unsorted=False, trim=False, verbose=0):
+        """
+            Constructor.
+        """
+
+        assert not puresat or unsorted, '\'unsorted\' needs to be True for pure SAT mode'
+
+        # verbosity level
+        self.verbose = verbose
+
+        # budget on the number of conflicts when reducing corrections sets
+        self.reduce_budget = reduce
+
+        # constructing a local copy of the formula
+        self.formula = WCNFPlus()
+        self.formula.hard = formula.hard[:]
+        self.formula.wght = formula.wght[:]
+        self.formula.topw = formula.topw
+        self.formula.nv = formula.nv
+
+        # copying atmost constraints, if any
+        if isinstance(formula, WCNFPlus) and formula.atms:
+            self.formula.atms = formula.atms[:]
+
+        # top variable identifier
+        self.topv = formula.nv
+
+        # processing soft clauses
+        self._process_soft(formula)
+        self.formula.nv = self.topv
+
+        # applying formula processing (if any)
+        if process:
+            # the processor is immediately destroyed,
+            # as we do not need to restore the models
+            with Processor(bootstrap_with=self.formula.hard) as processor:
+                proc = processor.process(rounds=process, freeze=self.sels)
+                self.formula.hard = proc.clauses
+                self.formula.nv = max(self.formula.nv, proc.nv)
+
+        # creating an unweighted copy
+        unweighted = self.formula.copy()
+        unweighted.wght = [1 for w in unweighted.wght]
+
+        if not nodisj:
+            # enumerating disjoint MCSes (including unit-size MCSes)
+            to_hit, self.units = self._disjoint(unweighted, solver, adapt, exhaust,
+                    minz, trim)
+        else:
+            to_hit, self.units, self.disj_time = [], [], 0.
+
+        if self.verbose > 2:
+            print('c mcses: {0} unit, {1} disj'.format(len(self.units),
+                len(to_hit) + len(self.units)))
+
+        if not unsorted:
+            # MaxSAT-based hitting set enumerator
+            self.hitman = Hitman(bootstrap_with=to_hit, weights=self.weights,
+                    solver=solver, htype='sorted', mxs_adapt=adapt,
+                    mxs_exhaust=exhaust, mxs_minz=minz, mxs_trim=trim)
+        elif not puresat:
+            # MCS-based hitting set enumerator
+            self.hitman = Hitman(bootstrap_with=to_hit, weights=self.weights,
+                    solver=solver, htype='lbx', mcs_usecld=dcalls)
+        else:
+            # pure SAT-based hitting set enumerator with preferred phases
+            self.hitman = Hitman(bootstrap_with=to_hit, weights=self.weights,
+                    solver=puresat, htype='sat')
+
+        # adding the formula to cover to the hitting set enumerator
+        self.cover = cover is not None
+        if cover:
+            # mapping literals to Hitman's atoms
+            m = lambda l: Atom(l, sign=True) if -l not in self.weights else Atom(-l, sign=False)
+
+            for cl in cover:
+                if len(cl) != 2 or not type(cl[0]) in (list, tuple, set):
+                    cl = [m(l) for l in cl]
+                else:
+                    cl = [[m(l) for l in cl[0]], cl[1]]
+
+                self.hitman.add_hard(cl, weights=self.weights)
+
+        # SAT oracle bootstrapped with the hard clauses; note that
+        # clauses of the unit-size MCSes are enforced to be enabled
+        self.oracle = Solver(name=solver, bootstrap_with=unweighted.hard +
+                [[mcs] for mcs in self.units], use_timer=True)
+
+        if unweighted.atms:
+            if solver in SolverNames.cadical195:
+                # we are using CaDiCaL195 and it can use external linear engine
+                self.oracle.activate_atmost()
+
+            assert self.oracle.supports_atmost(), \
+                    '{0} does not support native cardinality constraints. Make sure you use the right type of formula.'.format(self.solver)
+
+            for atm in unweighted.atms:
+                self.oracle.add_atmost(*atm)
+
+    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 delete(self):
+        """
+            Explicit destructor of the internal hitting set and SAT oracles.
+        """
+
+        if self.hitman:
+            self.hitman.delete()
+            self.hitman = None
+
+        if self.oracle:
+            self.oracle.delete()
+            self.oracle = None
+
+    def _process_soft(self, formula):
+        """
+            The method is for processing the soft clauses of the input
+            formula. Concretely, it checks which soft clauses must be relaxed
+            by a unique selector literal and applies the relaxation.
+
+            :param formula: input formula
+            :type formula: :class:`.WCNF`
+        """
+
+        # list of selectors
+        self.sels = []
+
+        # mapping from selectors to clause ids
+        self.smap = {}
+
+        # duplicate unit clauses
+        processed_dups = set()
+
+        # processing the soft clauses
+        for cl in formula.soft:
+            # if the clause is unit-size, its sole literal acts a selector
+            selv = cl[0]
+
+            # if clause is not unit, we relax it
+            if len(cl) > 1:
+                self.topv += 1
+                selv = self.topv
+                self.formula.hard.append(cl + [-selv])
+            elif selv in self.smap:
+                # the clause is unit but a there is a previously seen
+                # duplicate of this clause; this means we have to
+                # reprocess the previous clause again and relax it
+                if selv not in processed_dups:
+                    self.topv += 1
+                    nsel = self.topv
+                    self.sels[self.smap[selv] - 1] = nsel
+                    self.formula.hard.append(self.formula.soft[self.smap[selv] - 1] + [-nsel])
+                    self.formula.soft[self.smap[selv] - 1] = [nsel]
+                    self.smap[nsel] = self.smap[selv]
+                    processed_dups.add(selv)
+
+                # processing the current clause
+                self.topv += 1
+                selv = self.topv
+                self.formula.hard.append(cl + [-selv])
+
+            self.sels.append(selv)
+            self.formula.soft.append([selv])
+            self.smap[selv] = len(self.sels)
+
+        # garbage-collecting the duplicates
+        for selv in processed_dups:
+            del self.smap[selv]
+
+        # these numbers should be equal after the processing
+        assert len(self.sels) == len(self.smap) == len(self.formula.wght)
+
+        # creating a dictionary of weights
+        self.weights = {l: w for l, w in zip(self.sels, self.formula.wght)}
+
+    def _disjoint(self, formula, solver, adapt, exhaust, minz, trim):
+        """
+            This method constitutes the preliminary step of the implicit
+            hitting set paradigm of Forqes. Namely, it enumerates all the
+            disjoint *minimal correction subsets* (MCSes) of the formula,
+            which will be later used to bootstrap the hitting set solver.
+
+            Note that the MaxSAT solver in use is :class:`.RC2`. As a result,
+            all the input parameters of the method, namely, ``formula``,
+            ``solver``, ``adapt``, `exhaust``, ``minz``, and ``trim`` -
+            represent the input and the options for the RC2 solver.
+
+            :param formula: input formula
+            :param solver: SAT solver name
+            :param adapt: detect and adapt AtMost1 constraints
+            :param exhaust: exhaust unsatisfiable cores
+            :param minz: apply heuristic core minimization
+            :param trim: trim unsatisfiable cores at most this number of times
+
+            :type formula: :class:`.WCNF`
+            :type solver: str
+            :type adapt: bool
+            :type exhaust: bool
+            :type minz: bool
+            :type trim: int
+        """
+
+        # these will store disjoint MCSes
+        # (unit-size MCSes are stored separately)
+        to_hit, units = [], []
+
+        with RC2(formula, solver=solver, adapt=adapt, exhaust=exhaust,
+                minz=minz, trim=trim, verbose=0) as oracle:
+
+            # iterating over MaxSAT solutions
+            while True:
+                # a new MaxSAT model
+                model = oracle.compute()
+
+                if model is None:
+                    # no model => no more disjoint MCSes
+                    break
+
+                # extracting the MCS corresponding to the model
+                falsified = [l for l in self.sels if model[abs(l) - 1] == -l]
+
+                # unit size or not?
+                if len(falsified) > 1:
+                    to_hit.append(falsified)
+                else:
+                    units.append(falsified[0])
+
+                # blocking the MCS;
+                # next time, all these clauses will be satisfied
+                for l in falsified:
+                    oracle.add_clause([l])
+
+                # reporting the MCS
+                if self.verbose > 3:
+                    print('c mcs: {0} 0'.format(' '.join([str(self.smap[s]) for s in falsified])))
+
+            # RC2 will be destroyed next; let's keep the oracle time
+            self.disj_time = oracle.oracle_time()
+
+        return to_hit, units
+
+    def compute(self):
+        """
+            This method implements the main look of the implicit hitting set
+            paradigm of Forqes to compute a best-cost MUS. The result MUS is
+            returned as a list of integers, each representing a soft clause
+            index.
+
+            :rtype: list(int)
+        """
+
+        # correctly computed cost of the unit-mcs component
+        units_cost = sum(map(lambda l: self.weights[l], self.units))
+
+        it = 0
+        while True:
+            # computing a new optimal hitting set
+            hs = self.hitman.get()
+            if self.verbose > 3:
+                self.cost = sum(map(lambda l: self.weights[l], hs)) + units_cost
+
+            if hs is None:
+                # no more hitting sets exist
+                break
+
+            # setting all the selector polarities to true
+            self.oracle.set_phases(self.sels)
+
+            # testing satisfiability of the {self.units + hs} subset
+            res = self.oracle.solve(assumptions=hs)
+
+            if res == False:
+                # the candidate subset of clauses is unsatisfiable,
+                # i.e. it is an optimal MUS we are searching for;
+                # therefore, blocking it and returning
+                self.hitman.block(hs)
+                self.cost = sum(map(lambda l: self.weights[l], hs)) + units_cost
+
+                if self.units and self.cover:
+                    # due to additional constraints to cover and unit mcses,
+                    # there may be duplicate clauses in self.units + hs
+                    return sorted(map(lambda s: self.smap[s], sorted(set(self.units + hs))))
+                else:
+                    return sorted(map(lambda s: self.smap[s], self.units + hs))
+            else:
+                # the candidate subset is satisfiable,
+                # thus extracting a correction subset
+                model = self.oracle.get_model()
+                cs = [l for l in self.sels if model[abs(l) - 1] == -l]
+
+                # naive MCS extraction with a budget on the conflict count
+                if self.reduce_budget:
+                    ss = [l for l in self.sels if model[abs(l) - 1] == +l]
+                    self.oracle.conf_budget(self.reduce_budget)
+
+                    # probing all the literals of the correction set
+                    for l in cs:
+                        if self.oracle.solve_limited(assumptions=[l] + ss) is True:
+                            ss.append(l)
+
+                    cs = sorted(set(cs) - set(ss))
+                    self.oracle.conf_budget(budget=-1)
+
+                # hitting the new correction subset
+                self.hitman.hit(cs, weights=self.weights)
+
+            it += 1
+            if self.verbose > 3:
+                print(f'c iter: {it}, cost: {self.cost}; cs sz: {len(cs)}')
+
+    def enumerate(self):
+        """
+            This is generator method iterating through MUSes and enumerating
+            them until the formula has no more MUSes, or a user decides to
+            stop the process.
+
+            :rtype: list(int)
+        """
+
+        done = False
+
+        while not done:
+            mus = self.compute()
+
+            if mus != None:
+                yield mus
+            else:
+                done = True
+
+    def oracle_time(self):
+        """
+            This method computes and returns the total SAT solving time
+            involved.
+
+            :rtype: float
+        """
+
+        return self.disj_time + self.hitman.oracle_time() + self.oracle.time_accum()
+
+
+#
+#==============================================================================
+def parse_options():
+    """
+        Parses command-line options.
+    """
+
+    try:
+        opts, args = getopt.getopt(sys.argv[1:], 'ac:de:hmnp:P:r:s:t:uvx',
+                                   ['adapt', 'cover=', 'dcalls', 'enum=',
+                                    'exhaust', 'help', 'minimize', 'no-disj',
+                                    'solver=', 'puresat=', 'process=',
+                                    'reduce=', 'unsorted', 'trim=', 'verbose'])
+    except getopt.GetoptError as err:
+        sys.stderr.write(str(err).capitalize() + '\n')
+        usage()
+        sys.exit(1)
+
+    adapt = False
+    cover = None
+    dcalls = False
+    exhaust = False
+    minz = False
+    no_disj = False
+    to_enum = 1
+    solver = 'g3'
+    process = 0
+    puresat = False
+    reduce = 0
+    unsorted = False
+    trim = 0
+    verbose = 1
+
+    for opt, arg in opts:
+        if opt in ('-a', '--adapt'):
+            adapt = True
+        elif opt in ('-c', '--cover'):
+            cover = str(arg)
+            if cover.lower() == 'none':
+                cover = None
+        elif opt in ('-d', '--dcalls'):
+            dcalls = True
+        elif opt in ('-e', '--enum'):
+            to_enum = str(arg)
+            if to_enum != 'all':
+                to_enum = int(to_enum)
+        elif opt in ('-h', '--help'):
+            usage()
+            sys.exit(0)
+        elif opt in ('-m', '--minimize'):
+            minz = True
+        elif opt in ('-n', '--no-disj'):
+            no_disj = True
+        elif opt in ('-p', '--puresat'):
+            puresat = str(arg)
+        elif opt in ('-P', '--process'):
+            process = int(arg)
+        elif opt in ('-r', '--reduce'):
+            reduce = int(arg)
+        elif opt in ('-s', '--solver'):
+            solver = str(arg)
+        elif opt in ('-u', '--unsorted'):
+            unsorted = True
+        elif opt in ('-t', '--trim'):
+            trim = int(arg)
+        elif opt in ('-v', '--verbose'):
+            verbose += 1
+        elif opt in ('-x', '--exhaust'):
+            exhaust = True
+        else:
+            assert False, 'Unhandled option: {0} {1}'.format(opt, arg)
+
+    return adapt, cover, dcalls, exhaust, minz, no_disj, trim, to_enum, \
+            solver, process, puresat, reduce, unsorted, verbose, args
+
+
+#
+#==============================================================================
+def usage():
+    """
+        Prints help message.
+    """
+
+    print('Usage:', os.path.basename(sys.argv[0]), '[options] file')
+    print('Options:')
+    print('        -a, --adapt               Try to adapt (simplify) input formula')
+    print('        -c, --cover=<string>      Stop MUS enumeration as soon as this formula is covered')
+    print('                                  Available values: any valid file path, none (default = none)')
+    print('        -d, --dcalls              Apply clause D calls (in unsorted enumeration only)')
+    print('        -e, --enum=<string>       Enumerate top-k solutions')
+    print('                                  Available values: [1 .. INT_MAX], all (default: 1)')
+    print('        -h, --help                Show this message')
+    print('        -m, --minimize            Use a heuristic unsatisfiable core minimizer')
+    print('        -n, --no-disj             Do not enumerate disjoint MCSes')
+    print('        -p, --puresat=<string>    Use a pure SAT-based hitting set enumerator')
+    print('                                  Available values: cd15, cd19, lgl, mgh (default = mgh)')
+    print('                                  Requires: unsorted mode, i.e. \'-u\'')
+    print('        -P, --process=<int>       Number of processing rounds')
+    print('                                  Available values: [0 .. INT_MAX] (default = 0)')
+    print('        -r, --reduce=<int>        Conflict budget when reducing correction sets')
+    print('                                  Available values: [0 .. INT_MAX], -1 (default = 0, meaning no reduction)')
+    print('        -s, --solver              SAT solver to use')
+    print('                                  Available values: cd15, cd19, g3, g4, lgl, mcb, mcm, mpl, m22, mc, mgh (default = g3)')
+    print('        -t, --trim=<int>          How many times to trim unsatisfiable cores')
+    print('                                  Available values: [0 .. INT_MAX] (default = 0)')
+    print('        -u, --unsorted            Enumerate MUSes in an unsorted way')
+    print('        -v, --verbose             Be verbose')
+    print('        -x, --exhaust             Exhaust new unsatisfiable cores')
+
+
+#
+#==============================================================================
+if __name__ == '__main__':
+    adapt, cover, dcalls, exhaust, minz, no_disj, trim, to_enum, solver, \
+            process, puresat, reduce, unsorted, verbose, files = parse_options()
+
+    if files:
+        # reading standard CNF, WCNF, or (W)CNF+
+        assert re.search(r'cnf[p|+]?(\.(gz|bz2|lzma|xz|zst))?$', files[0]), 'Unknown input file extension'
+        if re.search(r'\.wcnf[p|+]?(\.(gz|bz2|lzma|xz|zst))?$', files[0]):
+            formula = WCNFPlus(from_file=files[0])
+        else:  # expecting '*.cnf[,p,+].*'
+            formula = CNFPlus(from_file=files[0]).weighted()
+
+        if cover:  # expecting  '*.cnf[,p,+].*' only!
+            assert re.search(r'cnf[p|+]?(\.(gz|bz2|lzma|xz|zst))?$', cover), 'Wrong file for formula to cover'
+            cover = CNFPlus(from_file=cover)
+
+        # creating an object of OptUx
+        with OptUx(formula, solver=solver, adapt=adapt, cover=cover,
+                   dcalls=dcalls, exhaust=exhaust, minz=minz, nodisj=no_disj,
+                   process=process, puresat=puresat, reduce=reduce,
+                   unsorted=unsorted, trim=trim, verbose=verbose) as optux:
+
+            # iterating over the necessary number of optimal MUSes
+            for i, mus in enumerate(optux.enumerate()):
+                # reporting the current solution
+                if verbose:
+                    print('c mus:', ' '.join([str(cl_id) for cl_id in mus]), '0')
+
+                    if verbose > 1:
+                        print('c cost:', optux.cost)
+
+                # checking if we are done
+                if to_enum and i + 1 == to_enum:
+                    break
+
+            # reporting the total oracle time
+            if verbose > 1:
+                print('c oracle time: {0:.4f}'.format(optux.oracle_time()))