clingexplaid 1.0.9__py3-none-any.whl

clingexplaid/__init__.py

@@ -0,0 +1,3 @@
+"""
+The clingexplaid project.
+"""

clingexplaid/__main__.py

@@ -0,0 +1,21 @@
+"""
+The main entry point for the application.
+"""
+
+import sys
+
+from clingo.application import clingo_main
+
+from .cli.clingo_app import ClingoExplaidApp
+
+
+def main() -> None:
+    """
+    Run the main function.
+    """
+
+    clingo_main(ClingoExplaidApp(sys.argv[0]), sys.argv[1:] + ["-V0"])
+
+
+if __name__ == "__main__":
+    main()

clingexplaid/cli/clingo_app.py

@@ -0,0 +1,352 @@
+"""
+App Module: clingexplaid CLI clingo app
+"""
+
+import re
+import sys
+from importlib.metadata import version
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Sequence, Set, Tuple
+from warnings import warn
+
+import clingo
+from clingo.application import Application, Flag
+
+from ..muc import CoreComputer
+from ..propagators import DecisionOrderPropagator
+from ..transformers import AssumptionTransformer, OptimizationRemover
+from ..unsat_constraints import UnsatConstraintComputer
+from ..utils import get_constants_from_arguments
+from ..utils.logging import BACKGROUND_COLORS, COLORS
+
+HYPERLINK_MASK = "\033]8;{};{}\033\\{}\033]8;;\033\\"
+
+
+class ClingoExplaidApp(Application):
+    """
+    Application class for executing clingo-explaid functionality on the command line
+    """
+
+    # pylint: disable = too-many-instance-attributes
+
+    CLINGEXPLAID_METHODS = {
+        "muc": "Description for MUC method",
+        "unsat-constraints": "Description for unsat-constraints method",
+        "show-decisions": "Visualize the decision process of clingo during solving",
+    }
+
+    def __init__(self, name: str) -> None:
+        # pylint: disable = unused-argument
+        self.methods: Set[str] = set()
+        self.method_functions: Dict[str, Callable] = {  # type: ignore
+            m: getattr(self, f'_method_{m.replace("-", "_")}') for m in self.CLINGEXPLAID_METHODS
+        }
+        self.method_flags: Dict[str, Flag] = {m: Flag() for m in self.CLINGEXPLAID_METHODS}
+        self.argument_constants: Dict[str, str] = {}
+
+        # SHOW DECISIONS
+        self._show_decisions_decision_signatures: Dict[str, int] = {}
+        self._show_decisions_model_id: int = 1
+
+        # MUC
+        self._muc_assumption_signatures: Dict[str, int] = {}
+        self._muc_id: int = 1
+
+    def _initialize(self) -> None:
+        # add enabled methods to self.methods
+        for method, flag in self.method_flags.items():
+            if flag.flag:
+                self.methods.add(method)
+
+        if len(self.methods) == 0:
+            raise ValueError(
+                f"Clingexplaid was called without any method, please select at least one of the following methods: "
+                f"[{', '.join(['--' + str(m) for m in self.CLINGEXPLAID_METHODS])}]"
+            )
+
+    @staticmethod
+    def _parse_signature(signature_string: str) -> Tuple[str, int]:
+        match_result = re.match(r"^([a-zA-Z]+)/([0-9]+)$", signature_string)
+        if match_result is None:
+            raise ValueError("Wrong signature Format")
+        return match_result.group(1), int(match_result.group(2))
+
+    def _parse_assumption_signature(self, assumption_signature: str) -> bool:
+        if not self.method_flags["muc"]:
+            print("PARSE ERROR: The assumption signature option is only available if the flag --muc is enabled")
+            return False
+        assumption_signature_string = assumption_signature.replace("=", "").strip()
+        try:
+            signature, arity = self._parse_signature(assumption_signature_string)
+        except ValueError:
+            print(
+                "PARSE ERROR: Wrong signature format. The assumption signatures have to follow the format "
+                "<assumption-name>/<arity>"
+            )
+            return False
+        self._muc_assumption_signatures[signature] = arity
+        return True
+
+    def _parse_decision_signature(self, decision_signature: str) -> bool:
+        if not self.method_flags["show-decisions"]:
+            print(
+                "PARSE ERROR: The decision signature option is only available if the flag --show-decisions is enabled"
+            )
+            return False
+        decision_signature_string = decision_signature.replace("=", "").strip()
+        try:
+            signature, arity = self._parse_signature(decision_signature_string)
+        except ValueError:
+            print(
+                "PARSE ERROR: Wrong signature format. The decision signatures have to follow the format "
+                "<assumption-name>/<arity>"
+            )
+            return False
+        self._show_decisions_decision_signatures[signature] = arity
+        return True
+
+    def register_options(self, options: clingo.ApplicationOptions) -> None:
+        group = "Clingo-Explaid Methods"
+
+        for method, description in self.CLINGEXPLAID_METHODS.items():
+            options.add_flag(
+                group=group,
+                option=method,
+                description=description,
+                target=self.method_flags[method],
+            )
+
+        group = "MUC Options"
+
+        options.add(
+            group,
+            "assumption-signature,a",
+            "Facts matching with this signature will be converted to assumptions for finding a MUC "
+            "(default: all facts)",
+            self._parse_assumption_signature,
+            multi=True,
+        )
+
+        group = "Show Decisions Options"
+
+        options.add(
+            group,
+            "decision-signature",
+            "When --show-decisions is enabled, show only decisions matching with this signature "
+            "(default: show all decisions)",
+            self._parse_decision_signature,
+            multi=True,
+        )
+
+        # group = "General Options"
+
+    def _apply_assumption_transformer(
+        self, signatures: Dict[str, int], files: List[str]
+    ) -> Tuple[str, AssumptionTransformer]:
+        signature_set = set(self._muc_assumption_signatures.items()) if signatures else None
+        at = AssumptionTransformer(signatures=signature_set)
+        if not files:
+            program_transformed = at.parse_files("-")
+        else:
+            program_transformed = at.parse_files(files)
+        return program_transformed, at
+
+    def _print_muc(self, muc_string: str) -> None:
+        print(f"{BACKGROUND_COLORS['BLUE']} MUC {BACKGROUND_COLORS['LIGHT_BLUE']} {self._muc_id} {COLORS['NORMAL']}")
+        print(f"{COLORS['BLUE']}{muc_string}{COLORS['NORMAL']}")
+        self._muc_id += 1
+
+    def _method_muc(
+        self,
+        control: clingo.Control,
+        files: List[str],
+        compute_unsat_constraints: bool = False,
+    ) -> None:
+        program_transformed, at = self._apply_assumption_transformer(
+            signatures=self._muc_assumption_signatures, files=files
+        )
+
+        # remove optimization statements
+        optr = OptimizationRemover()
+        program_transformed = optr.parse_string(program_transformed)
+
+        control.add("base", [], program_transformed)
+        control.ground([("base", [])])
+
+        assumptions = at.get_assumptions(control, constants=self.argument_constants)
+        cc = CoreComputer(control, assumptions)
+
+        max_models = int(control.configuration.solve.models)  # type: ignore
+        print("Solving...")
+
+        # Case: Finding a single MUC
+        if max_models == -1:
+            control.solve(assumptions=list(assumptions), on_core=cc.shrink)
+
+            if cc.minimal is None:
+                print("SATISFIABLE: Instance has no MUCs")
+                return
+            if len(list(cc.minimal)) == 0:
+                print(
+                    "NO MUCS CONTAINED: The unsatisfiability of this program is not induced by the provided assumptions"
+                )
+                return
+
+            muc_string = " ".join(cc.muc_to_string(cc.minimal))
+            self._print_muc(muc_string)
+
+            if compute_unsat_constraints:
+                self._method_unsat_constraints(
+                    control=clingo.Control(),
+                    files=files,
+                    assumption_string=muc_string,
+                    output_prefix_active=f"{COLORS['RED']}├──{COLORS['NORMAL']}",
+                    output_prefix_passive=f"{COLORS['RED']}│  {COLORS['NORMAL']}",
+                )
+
+        # Case: Finding multiple MUCs
+        if max_models >= 0:
+            program_unsat = False
+            with control.solve(assumptions=list(assumptions), yield_=True) as solve_handle:
+                if not solve_handle.get().satisfiable:
+                    program_unsat = True
+
+            if program_unsat:
+                mucs = 0
+                for muc in cc.get_multiple_minimal(max_mucs=max_models):
+                    mucs += 1
+                    muc_string = " ".join(cc.muc_to_string(muc))
+                    self._print_muc(muc_string)
+
+                    if compute_unsat_constraints:
+                        self._method_unsat_constraints(
+                            control=clingo.Control(),
+                            files=files,
+                            assumption_string=muc_string,
+                            output_prefix_active=f"{COLORS['RED']}├──{COLORS['NORMAL']}",
+                            output_prefix_passive=f"{COLORS['RED']}│  {COLORS['NORMAL']}",
+                        )
+                if not mucs:
+                    print(
+                        "NO MUCS CONTAINED: The unsatisfiability of this program is not induced by the provided "
+                        "assumptions"
+                    )
+                    return
+
+    def _print_unsat_constraints(
+        self,
+        unsat_constraints: Dict[int, str],
+        ucc: UnsatConstraintComputer,
+        prefix: Optional[str] = None,
+    ) -> None:
+        if prefix is None:
+            prefix = ""
+        print(f"{prefix}{BACKGROUND_COLORS['RED']} Unsat Constraints {COLORS['NORMAL']}")
+        for cid, constraint in unsat_constraints.items():
+            location = ucc.get_constraint_location(cid)
+            if location is None:
+                warn(f"Couldn't find a corresponding file for constraint with id {cid}")
+                continue
+            relative_file_path = location.begin.filename
+            absolute_file_path = str(Path(relative_file_path).absolute().resolve())
+            line_beginning = location.begin.line
+            line_end = location.end.line
+            line_string = (
+                f"Line {line_beginning}" if line_beginning == line_end else f"Lines {line_beginning}-{line_end}"
+            )
+            file_link = "file://" + absolute_file_path
+            if " " in absolute_file_path:
+                # If there's a space in the filename use a hyperlink
+                file_link = HYPERLINK_MASK.format("", file_link, file_link)
+
+            if location is not None:
+                print(
+                    f"{prefix}{COLORS['RED']}{constraint}"
+                    f"{COLORS['GREY']} [ {file_link} ]({line_string}){COLORS['NORMAL']}"
+                )
+            else:
+                print(f"{prefix}{COLORS['RED']}{constraint}{COLORS['NORMAL']}")
+
+    def _method_unsat_constraints(
+        self,
+        control: clingo.Control,
+        files: List[str],
+        assumption_string: Optional[str] = None,
+        output_prefix_active: str = "",
+        output_prefix_passive: str = "",
+    ) -> None:
+        # register DecisionOrderPropagator if flag is enabled
+        if self.method_flags["show-decisions"]:
+            decision_signatures = set(self._show_decisions_decision_signatures.items())
+            dop = DecisionOrderPropagator(signatures=decision_signatures, prefix=output_prefix_passive)
+            control.register_propagator(dop)  # type: ignore
+
+        ucc = UnsatConstraintComputer(control=control)
+        ucc.parse_files(files)
+        unsat_constraints = ucc.get_unsat_constraints(assumption_string=assumption_string)
+        self._print_unsat_constraints(unsat_constraints, ucc=ucc, prefix=output_prefix_active)
+
+    def _print_model(
+        self,
+        model: clingo.Model,
+        prefix_active: str = "",
+        prefix_passive: str = "",
+    ) -> None:
+        print(prefix_passive)
+        print(
+            f"{prefix_active}"
+            f"{BACKGROUND_COLORS['LIGHT-GREY']}{COLORS['BLACK']} Model {COLORS['NORMAL']}{BACKGROUND_COLORS['GREY']} "
+            f"{self._show_decisions_model_id} {COLORS['NORMAL']} "
+            f"{model}"
+        )
+        # print(f"{COLORS['BLUE']}{model}{COLORS['NORMAL']}")
+        print(prefix_passive)
+        self._show_decisions_model_id += 1
+
+    def _method_show_decisions(
+        self,
+        control: clingo.Control,
+        files: List[str],
+    ) -> None:
+        decision_signatures = set(self._show_decisions_decision_signatures.items())
+        dop = DecisionOrderPropagator(signatures=decision_signatures)
+        control.register_propagator(dop)  # type: ignore
+        for f in files:
+            control.load(f)
+        if not files:
+            control.load("-")
+        control.ground()
+        control.solve(on_model=lambda model: self._print_model(model, "├", "│"))
+
+    def print_model(self, model: clingo.Model, _) -> None:  # type: ignore
+        return
+
+    def main(self, control: clingo.Control, files: Sequence[str]) -> None:
+        print("clingexplaid", "version", version("clingexplaid"))
+        self._initialize()
+
+        # printing the input files
+        if not files:
+            print("Reading from -")
+        else:
+            print(f"Reading from {files[0]} {'...' if len(files) > 1 else ''}")
+
+        self.argument_constants = get_constants_from_arguments(sys.argv)
+
+        # standard case: only one method
+        if len(self.methods) == 1:
+            method = list(self.methods)[0]
+            method_function = self.method_functions[method]
+            method_function(control, files)
+        # special cases where specific pipelines have to be configured
+        elif self.methods == {"muc", "unsat-constraints"}:
+            self.method_functions["muc"](control, files, compute_unsat_constraints=True)
+        elif self.methods == {"muc", "unsat-constraints", "show-decisions"}:
+            self.method_functions["muc"](control, files, compute_unsat_constraints=True)
+        elif self.methods == {"unsat-constraints", "show-decisions"}:
+            self.method_functions["unsat-constraints"](control, files)
+        else:
+            print(
+                f"METHOD ERROR: the combination of the methods {[f'--{m}' for m in self.methods]} is invalid. "
+                f"Please remove the conflicting method flags"
+            )

clingexplaid/muc/__init__.py

@@ -0,0 +1,9 @@
+"""
+Minimal Unsatisfiable Core Utilities
+"""
+
+from .core_computer import CoreComputer
+
+__all__ = [
+    "CoreComputer",
+]

clingexplaid/muc/core_computer.py

@@ -0,0 +1,140 @@
+"""
+MUC Module: Core Computer to get Minimal Unsatisfiable Cores
+"""
+
+from itertools import chain, combinations
+from typing import Dict, Generator, List, Optional, Set, Tuple
+
+import clingo
+
+from ..utils import get_solver_literal_lookup
+from ..utils.types import Assumption, AssumptionSet, SymbolSet
+
+
+class CoreComputer:
+    """
+    A container class that allows for a passed program_string and assumption_set to compute a minimal unsatisfiable
+    core.
+    """
+
+    def __init__(self, control: clingo.Control, assumption_set: AssumptionSet):
+        self.control = control
+        self.assumption_set = assumption_set
+        self.literal_lookup = get_solver_literal_lookup(control=self.control)
+        self.minimal: Optional[AssumptionSet] = None
+
+    def _solve(self, assumptions: Optional[AssumptionSet] = None) -> Tuple[bool, SymbolSet, SymbolSet]:
+        """
+        Internal function that is used to make the single solver calls for finding the minimal unsatisfiable core.
+        """
+        if assumptions is None:
+            assumptions = self.assumption_set
+
+        with self.control.solve(assumptions=list(assumptions), yield_=True) as solve_handle:
+            satisfiable = bool(solve_handle.get().satisfiable)
+            model = solve_handle.model().symbols(atoms=True) if solve_handle.model() is not None else []
+            core = {self.literal_lookup[literal_id] for literal_id in solve_handle.core()}
+
+        return satisfiable, set(model), core
+
+    def _compute_single_minimal(self, assumptions: Optional[AssumptionSet] = None) -> AssumptionSet:
+        """
+        Function to compute a single minimal unsatisfiable core from the passed set of assumptions and the program of
+        the CoreComputer. If there is no minimal unsatisfiable core, since for example the program with assumptions
+        assumed is satisfiable, an empty set is returned. The algorithm that is used to compute this minimal
+        unsatisfiable core is the iterative deletion algorithm.
+        """
+        if assumptions is None:
+            assumptions = self.assumption_set
+
+        # check that the assumption set isn't empty
+        if not assumptions:
+            raise ValueError("A minimal unsatisfiable core cannot be computed on an empty assumption set")
+
+        # check if the problem with the full assumption set is unsatisfiable in the first place, and if not skip the
+        # rest of the algorithm and return an empty set.
+        satisfiable, _, _ = self._solve(assumptions=assumptions)
+        if satisfiable:
+            return set()
+
+        muc_members: Set[Assumption] = set()
+        working_set = set(assumptions)
+
+        for assumption in assumptions:
+            # remove the current assumption from the working set
+            working_set.remove(assumption)
+
+            satisfiable, _, _ = self._solve(assumptions=working_set.union(muc_members))
+            # if the working set now becomes satisfiable without the assumption it is added to the muc_members
+            if satisfiable:
+                muc_members.add(assumption)
+                # every time we discover a new muc member we also check if all currently found muc members already
+                # suffice to make the instance unsatisfiable. If so we can stop the search sice we fund our muc.
+                if not self._solve(assumptions=muc_members)[0]:
+                    break
+
+        return muc_members
+
+    def shrink(self, assumptions: Optional[AssumptionSet] = None) -> None:
+        """
+        This function applies the unsatisfiable core minimization (`self._compute_single_minimal`) on the assumptions
+        set `assumptions` and stores the resulting MUC inside `self.minimal`.
+        """
+        self.minimal = self._compute_single_minimal(assumptions=assumptions)
+
+    def get_multiple_minimal(self, max_mucs: Optional[int] = None) -> Generator[AssumptionSet, None, None]:
+        """
+        This function generates all minimal unsatisfiable cores of the provided assumption set. It implements the
+        generator pattern since finding all mucs of an assumption set is exponential in nature and the search might not
+        fully complete in reasonable time. The parameter `max_mucs` can be used to specify the maximum number of
+        mucs that are found before stopping the search.
+        """
+        assumptions = self.assumption_set
+        assumption_powerset = chain.from_iterable(
+            combinations(assumptions, r) for r in reversed(range(len(list(assumptions)) + 1))
+        )
+
+        found_sat: List[AssumptionSet] = []
+        found_mucs: List[AssumptionSet] = []
+
+        for current_subset in (set(s) for s in assumption_powerset):
+            # skip if empty subset
+            if len(current_subset) == 0:
+                continue
+            # skip if an already found satisfiable subset is superset
+            if any(set(sat).issuperset(current_subset) for sat in found_sat):
+                continue
+            # skip if an already found muc is a subset
+            if any(set(muc).issubset(current_subset) for muc in found_mucs):
+                continue
+
+            muc = self._compute_single_minimal(assumptions=current_subset)
+
+            # if the current subset wasn't unsatisfiable store this info and continue
+            if len(list(muc)) == 0:
+                found_sat.append(current_subset)
+                continue
+
+            # if iterative deletion finds a muc that wasn't discovered before update sets and yield
+            if muc not in found_mucs:
+                found_mucs.append(muc)
+                yield muc
+                # if the maximum muc amount is found stop search
+                if max_mucs is not None and len(found_mucs) == max_mucs:
+                    break
+
+    def muc_to_string(self, muc: AssumptionSet, literal_lookup: Optional[Dict[int, clingo.Symbol]] = None) -> Set[str]:
+        """
+        Converts a MUC into a set containing the string representations of the contained assumptions
+        """
+        # take class literal_lookup as default if no other is provided
+        if literal_lookup is None:
+            literal_lookup = self.literal_lookup
+
+        muc_string = set()
+        for a in muc:
+            if isinstance(a, int):
+                muc_string.add(str(literal_lookup[a]))
+            else:
+                muc_string.add(str(a[0]))
+        return muc_string

clingexplaid/propagators/__init__.py

@@ -0,0 +1,16 @@
+"""
+Propagators for Explanation
+"""
+
+# pragma: no cover
+
+from typing import List
+
+from .propagator_decision_order import DecisionOrderPropagator
+
+DecisionLevel = List[int]
+DecisionLevelList = List[DecisionLevel]
+
+__all__ = [
+    "DecisionOrderPropagator",
+]

clingexplaid/propagators/constants.py

@@ -0,0 +1,11 @@
+"""
+Constant definitions for the propagators package
+"""
+
+from ..utils.logging import COLORS
+
+UNKNOWN_SYMBOL_TOKEN = "INTERNAL"
+
+INDENT_START = "├─"
+INDENT_STEP = f"─{COLORS['GREY']}┼{COLORS['NORMAL']}──"
+INDENT_END = f"─{COLORS['GREY']}┤{COLORS['NORMAL']}  "