clingexplaid 1.2.2__tar.gz → 1.3.0__tar.gz

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clingexplaid
-Version: 1.2.2
+Version: 1.3.0
 Summary: Tools to aid the development of explanation systems using clingo
 Author-email: Hannes Weichelt <hweichelt@uni-potsdam.de>, Susana Hahn <susuhahnml@yahoo.com.mx>
 Maintainer-email: Hannes Weichelt <hweichelt@uni-potsdam.de>
@@ -96,12 +96,37 @@ Here are two example for using `clingexplaid`'s API.
 
 ### Minimal Unsatisfiable Subsets (MUS)
 
+Transforming facts to Assumptions (necessary pre-processing step):
+
+```python
+from clingexplaid.preprocessors import AssumptionPreprocessor
+from clingexplaid.preprocessors import (
+    FilterSignature,
+    FilterPattern,
+)
+
+PROGRAM = """
+a(book;magazine;video).
+b(test).
+c(1..10).
+d(1..3).
+"""
+
+ap = AssumptionPreprocessor(filters=[
+    FilterSignature("a", 1),
+    FilterPattern("d(2)")
+])
+result = ap.process(PROGRAM)
+# You can either use the return value of `ap.process`
+print(result)
+# Or use `ap.control` with your transformed program already added
+print(ap.control)
+```
+
 Getting a single MUS:
 
 ```python
-import clingo
-from clingexplaid.transformers import AssumptionTransformer
-from clingexplaid.transformers.transformer_assumption import FilterSignature
+from clingexplaid.preprocessors import AssumptionPreprocessor, FilterSignature
 from clingexplaid.mus import CoreComputer
 
 PROGRAM = """
@@ -113,25 +138,19 @@ a(X) :- b(X).
 :- a(X), X>=3.
 """
 
-control = clingo.Control()
-at = AssumptionTransformer(filters={FilterSignature("a", 1)})
-
-transformed_program = at.parse_string(PROGRAM)
-
-control.add("base", [], transformed_program)
-control.ground([("base", [])])
-
-assumptions = at.get_assumption_literals(control)
-
-cc = CoreComputer(control, assumptions)
-
+ap = AssumptionPreprocessor(filters={FilterSignature("a", 1)})
+ap.process(PROGRAM)
+ap.control.ground([("base", [])])
+cc = CoreComputer(ap.control, ap.assumptions)
 
 def shrink_on_core(core) -> None:
     mus_literals = cc.shrink(core)
     print("MUS:", cc.mus_to_string(mus_literals))
 
-
-control.solve(assumptions=list(assumptions), on_core=shrink_on_core)
+ap.control.solve(
+    assumptions=list(ap.assumptions),
+    on_core=shrink_on_core
+)
 ```
 
 Getting multiple MUS:

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/README.md

@@ -27,12 +27,37 @@ Here are two example for using `clingexplaid`'s API.
 
 ### Minimal Unsatisfiable Subsets (MUS)
 
+Transforming facts to Assumptions (necessary pre-processing step):
+
+```python
+from clingexplaid.preprocessors import AssumptionPreprocessor
+from clingexplaid.preprocessors import (
+    FilterSignature,
+    FilterPattern,
+)
+
+PROGRAM = """
+a(book;magazine;video).
+b(test).
+c(1..10).
+d(1..3).
+"""
+
+ap = AssumptionPreprocessor(filters=[
+    FilterSignature("a", 1),
+    FilterPattern("d(2)")
+])
+result = ap.process(PROGRAM)
+# You can either use the return value of `ap.process`
+print(result)
+# Or use `ap.control` with your transformed program already added
+print(ap.control)
+```
+
 Getting a single MUS:
 
 ```python
-import clingo
-from clingexplaid.transformers import AssumptionTransformer
-from clingexplaid.transformers.transformer_assumption import FilterSignature
+from clingexplaid.preprocessors import AssumptionPreprocessor, FilterSignature
 from clingexplaid.mus import CoreComputer
 
 PROGRAM = """
@@ -44,25 +69,19 @@ a(X) :- b(X).
 :- a(X), X>=3.
 """
 
-control = clingo.Control()
-at = AssumptionTransformer(filters={FilterSignature("a", 1)})
-
-transformed_program = at.parse_string(PROGRAM)
-
-control.add("base", [], transformed_program)
-control.ground([("base", [])])
-
-assumptions = at.get_assumption_literals(control)
-
-cc = CoreComputer(control, assumptions)
-
+ap = AssumptionPreprocessor(filters={FilterSignature("a", 1)})
+ap.process(PROGRAM)
+ap.control.ground([("base", [])])
+cc = CoreComputer(ap.control, ap.assumptions)
 
 def shrink_on_core(core) -> None:
     mus_literals = cc.shrink(core)
     print("MUS:", cc.mus_to_string(mus_literals))
 
-
-control.solve(assumptions=list(assumptions), on_core=shrink_on_core)
+ap.control.solve(
+    assumptions=list(ap.assumptions),
+    on_core=shrink_on_core
+)
 ```
 
 Getting multiple MUS:

clingexplaid-1.3.0/src/clingexplaid/cli/style/mus.py

@@ -0,0 +1,5 @@
+MODE_MUS_STYLE = """
+#content.mode-mus{
+
+}
+"""

clingexplaid-1.3.0/src/clingexplaid/exceptions/__init__.py

@@ -0,0 +1,8 @@
+"""Exceptions for ClingExplaid"""
+
+
+class UnprocessedException(Exception):
+    """
+    Exception raised if the assumptions property of an AssumptionPreprocessor is called before it is used to
+    preprocess a program.
+    """

clingexplaid-1.3.0/src/clingexplaid/preprocessors/__init__.py

@@ -0,0 +1,5 @@
+"""Preprocessors for Clingexplaid"""
+
+from .preprocessor_assumption import AssumptionPreprocessor, FilterPattern, FilterSignature
+
+__all__ = ["AssumptionPreprocessor", "FilterPattern", "FilterSignature"]

clingexplaid-1.3.0/src/clingexplaid/preprocessors/preprocessor_assumption.py

@@ -0,0 +1,210 @@
+"""
+Transformer Module: Assumption Transformer for converting facts to choices that can be assumed
+"""
+
+import warnings
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, Set, Tuple, Union
+
+import clingo
+from clingo.ast import ProgramBuilder, parse_string
+
+from ..exceptions import UnprocessedException
+from ..utils.match import match
+
+
+@dataclass
+class FilterSignature:
+    """Filters the facts converted to assumptions by signature"""
+
+    name: str
+    arity: int
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.arity))
+
+
+@dataclass
+class FilterPattern:
+    """Filters the facts converted to assumptions by pattern"""
+
+    pattern: str
+
+    def __hash__(self) -> int:
+        return hash(self.pattern)
+
+
+class AssumptionPreprocessor:
+    """
+    A transformer that transforms facts that match with one of the signatures provided (no signatures means all facts)
+    into choice rules and also provides the according assumptions for them.
+    """
+
+    # pylint: disable=too-many-instance-attributes
+
+    def __init__(
+        self,
+        filters: Optional[Iterable[Union[FilterPattern, FilterSignature]]] = None,
+        control: Optional[clingo.Control] = None,
+        fail_on_unprocessed: bool = True,
+    ):
+        self.control = control if control is not None else clingo.Control()
+        self.filters: Set[Union[FilterPattern, FilterSignature]] = set(filters) if filters is not None else set()
+        self._filters_convert_nothing = bool(filters is not None and len(list(filters)) == 0)
+        self._processed = False
+        self._fail_on_unprocessed = fail_on_unprocessed
+        self._parsed_rules: List[str] = []
+        self._constants: Dict[str, clingo.Symbol] = {}
+        self._assumptions: Set[Tuple[clingo.Symbol, bool]] = set()
+
+        if self._filters_convert_nothing:
+            warnings.warn("When an empty list of filters is provided, no facts will be transformed to assumptions")
+
+    @staticmethod
+    def _to_ast(symbol: Union[str, clingo.Symbol]) -> clingo.ast.AST:
+        parsed_ast: List[clingo.ast.AST] = []
+        parse_string(f"{symbol}.", parsed_ast.append)
+        ast_symbol = parsed_ast[1]  # return AST symbol (parsed_ast[0] = '#program base.')
+        return ast_symbol
+
+    def _add_assumption(self, symbol: clingo.Symbol, positive: bool) -> None:
+        self._assumptions.add((symbol, positive))
+
+    def _add_assumption_string(self, string: str, positive: bool) -> None:
+        self._add_assumption(clingo.parse_term(string), positive)
+
+    def _add_constant(self, name: str, symbol: clingo.Symbol) -> None:
+        self._constants[name] = symbol
+
+    def _any_filters_apply(self, symbol: clingo.Symbol) -> bool:
+        if self._filters_convert_nothing:
+            # Convert nothing
+            return False
+        if not self._filters_convert_nothing and len(self.filters) == 0:
+            # Convert everything
+            return True
+        applies = False
+        for symbol_filter in self.filters:
+            match symbol_filter:
+                case FilterPattern(pattern=pattern):
+                    applies |= bool(match(pattern, symbol))
+                case FilterSignature(name=name, arity=arity):
+                    applies |= len(symbol.arguments) == arity and symbol.name == name
+        return applies
+
+    @staticmethod
+    def _unpool(ast_symbol: clingo.ast.ASTType.SymbolicAtom) -> Set[clingo.Symbol]:
+        if ".." in str(ast_symbol):
+            # Case range in ast symbol (i.e. 1..10)
+            # Solved using grounding, but if possible, I'd rather avoid this if possible
+            unpool_control = clingo.Control()
+            unpool_control.add(f"{ast_symbol}.")
+            unpool_control.ground([("base", [])])
+            with unpool_control.solve(yield_=True) as solve_handle:
+                result = solve_handle.get()
+                if result.satisfiable:
+                    model = solve_handle.model()
+                    return set(model.symbols(atoms=True))
+                raise ValueError("Provided AST symbol does not follow valid ASP syntax")  # nocoverage
+        # Case default
+        atoms_unpooled = ast_symbol.unpool()
+        return {clingo.parse_term(str(a)) for a in atoms_unpooled}
+
+    def _transform_rule(self, rule: clingo.ast.ASTType.Rule) -> List[clingo.ast.ASTType.Rule]:
+        if rule.head.ast_type != clingo.ast.ASTType.Literal:
+            return [rule]
+        if rule.body:
+            return [rule]
+
+        atoms_unpooled = AssumptionPreprocessor._unpool(rule.head)
+        atoms_choice: Set[clingo.ast.AST] = set()
+        atoms_retained: Set[clingo.Symbol] = set()
+        for atom in atoms_unpooled:
+            filters_apply = self._any_filters_apply(atom)
+            # if filters are defined, only transform facts that match them, else transform all facts
+            if not filters_apply:
+                atoms_retained.add(atom)
+                continue
+            ast = AssumptionPreprocessor._to_ast(atom)
+            ast_choice_literal = clingo.ast.ConditionalLiteral(location=rule.location, literal=ast.head, condition=[])
+            atoms_choice.add(ast_choice_literal)
+        atoms_retained_ast: Set[clingo.ast.AST] = set()
+        for atom in atoms_retained:
+            atoms_retained_ast.add(AssumptionPreprocessor._to_ast(atom))
+
+        if len(atoms_choice) > 0:
+            # Add all choice atoms to the assumption list
+            for a_choice in atoms_choice:
+                self._add_assumption_string(str(a_choice), True)
+
+            choice_rule = clingo.ast.Rule(
+                location=rule.location,
+                head=clingo.ast.Aggregate(
+                    location=rule.location,
+                    left_guard=None,
+                    elements=list(sorted(atoms_choice, key=str)),
+                    right_guard=None,
+                ),
+                body=[],
+            )
+            return [choice_rule, *sorted(atoms_retained_ast, key=str)]
+        return list(sorted(atoms_retained_ast, key=str))
+
+    def register_ast(self, ast: clingo.ast.AST, builder: clingo.ast.ProgramBuilder) -> None:
+        """Registers the provided AST to the builder and the parsed rules list"""
+        if ast.ast_type == clingo.ast.ASTType.Definition:
+            self._add_constant(str(ast.name), ast.value.symbol)
+        self._parsed_rules.append(str(ast))
+        warnings.warn(
+            "Currently the ProgramBuilder does not fill the control. Please add the processed programm manually."
+        )
+        builder.add(ast)
+
+    def process(self, program_string: str) -> str:
+        """Processes the provided program string and returns the transformed program string (control is also updated)"""
+        control = clingo.Control("0")
+        ast_list: List[clingo.ast.AST] = []
+        with ProgramBuilder(control) as builder:
+            parse_string(program_string, ast_list.append)
+            for ast in ast_list:
+                if ast.ast_type == clingo.ast.ASTType.Rule:
+                    for new_ast in self._transform_rule(ast):
+                        if new_ast.ast_type != clingo.ast.ASTType.Rule:  # nocoverage
+                            new_rule = clingo.ast.Rule(location=ast.location, head=new_ast, body=[])
+                            self.register_ast(new_rule, builder)
+                        else:
+                            self.register_ast(new_ast, builder)
+                elif ast.ast_type == clingo.ast.ASTType.Definition:
+                    self.register_ast(ast, builder)
+                else:
+                    self.register_ast(ast, builder)
+        self._processed = True
+        return "\n".join(self._parsed_rules)
+
+    @property
+    def assumptions(self) -> Set[Tuple[clingo.Symbol, bool]]:
+        """Property that returns the assumptions generated by the preprocessor after calling `process`"""
+        if not self._processed:
+            if self._fail_on_unprocessed:
+                raise UnprocessedException(
+                    "It is impossible to retrieve assumptions without invoking the `process` function first"
+                )
+            warnings.warn(
+                "Unprocessed Error: It is impossible to retrieve assumptions without invoking the "
+                "`process` function first"
+            )  # nocoverage
+        return set(self._assumptions)
+
+    @property
+    def constants(self) -> Dict[str, clingo.Symbol]:
+        """Property that returns the constants generated by the preprocessor after calling `process`"""
+        if not self._processed:  # nocoverage
+            if self._fail_on_unprocessed:
+                raise UnprocessedException(
+                    "It is impossible to retrieve constants without invoking the `process` function first"
+                )
+            warnings.warn(
+                "Unprocessed Error: It is impossible to retrieve constants without invoking the "
+                "`process function first`"
+            )
+        return self._constants

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/src/clingexplaid/transformers/__init__.py

@@ -2,7 +2,6 @@
 Transformers for Explanation
 """
 
-from .transformer_assumption import AssumptionTransformer
 from .transformer_constraint import ConstraintTransformer
 from .transformer_fact import FactTransformer
 from .transformer_optimization_remover import OptimizationRemover
@@ -10,7 +9,6 @@ from .transformer_rule_id import RuleIDTransformer
 from .transformer_rule_splitter import RuleSplitter
 
 __all__ = [
-    "AssumptionTransformer",
     "ConstraintTransformer",
     "FactTransformer",
     "OptimizationRemover",

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/src/clingexplaid.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clingexplaid
-Version: 1.2.2
+Version: 1.3.0
 Summary: Tools to aid the development of explanation systems using clingo
 Author-email: Hannes Weichelt <hweichelt@uni-potsdam.de>, Susana Hahn <susuhahnml@yahoo.com.mx>
 Maintainer-email: Hannes Weichelt <hweichelt@uni-potsdam.de>
@@ -96,12 +96,37 @@ Here are two example for using `clingexplaid`'s API.
 
 ### Minimal Unsatisfiable Subsets (MUS)
 
+Transforming facts to Assumptions (necessary pre-processing step):
+
+```python
+from clingexplaid.preprocessors import AssumptionPreprocessor
+from clingexplaid.preprocessors import (
+    FilterSignature,
+    FilterPattern,
+)
+
+PROGRAM = """
+a(book;magazine;video).
+b(test).
+c(1..10).
+d(1..3).
+"""
+
+ap = AssumptionPreprocessor(filters=[
+    FilterSignature("a", 1),
+    FilterPattern("d(2)")
+])
+result = ap.process(PROGRAM)
+# You can either use the return value of `ap.process`
+print(result)
+# Or use `ap.control` with your transformed program already added
+print(ap.control)
+```
+
 Getting a single MUS:
 
 ```python
-import clingo
-from clingexplaid.transformers import AssumptionTransformer
-from clingexplaid.transformers.transformer_assumption import FilterSignature
+from clingexplaid.preprocessors import AssumptionPreprocessor, FilterSignature
 from clingexplaid.mus import CoreComputer
 
 PROGRAM = """
@@ -113,25 +138,19 @@ a(X) :- b(X).
 :- a(X), X>=3.
 """
 
-control = clingo.Control()
-at = AssumptionTransformer(filters={FilterSignature("a", 1)})
-
-transformed_program = at.parse_string(PROGRAM)
-
-control.add("base", [], transformed_program)
-control.ground([("base", [])])
-
-assumptions = at.get_assumption_literals(control)
-
-cc = CoreComputer(control, assumptions)
-
+ap = AssumptionPreprocessor(filters={FilterSignature("a", 1)})
+ap.process(PROGRAM)
+ap.control.ground([("base", [])])
+cc = CoreComputer(ap.control, ap.assumptions)
 
 def shrink_on_core(core) -> None:
     mus_literals = cc.shrink(core)
     print("MUS:", cc.mus_to_string(mus_literals))
 
-
-control.solve(assumptions=list(assumptions), on_core=shrink_on_core)
+ap.control.solve(
+    assumptions=list(ap.assumptions),
+    on_core=shrink_on_core
+)
 ```
 
 Getting multiple MUS:

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/src/clingexplaid.egg-info/SOURCES.txt

@@ -59,15 +59,17 @@ src/clingexplaid.egg-info/SOURCES.txt
 src/clingexplaid.egg-info/dependency_links.txt
 src/clingexplaid.egg-info/requires.txt
 src/clingexplaid.egg-info/top_level.txt
+src/clingexplaid/cli/style/mus.py
+src/clingexplaid/exceptions/__init__.py
 src/clingexplaid/mus/__init__.py
 src/clingexplaid/mus/core_computer.py
+src/clingexplaid/preprocessors/__init__.py
+src/clingexplaid/preprocessors/preprocessor_assumption.py
 src/clingexplaid/propagators/__init__.py
 src/clingexplaid/propagators/constants.py
 src/clingexplaid/propagators/propagator_solver_decisions.py
 src/clingexplaid/transformers/__init__.py
 src/clingexplaid/transformers/constants.py
-src/clingexplaid/transformers/exceptions.py
-src/clingexplaid/transformers/transformer_assumption.py
 src/clingexplaid/transformers/transformer_constraint.py
 src/clingexplaid/transformers/transformer_fact.py
 src/clingexplaid/transformers/transformer_optimization_remover.py
@@ -88,6 +90,7 @@ tests/test_main.py
 tests/clingexplaid/__init__.py
 tests/clingexplaid/test_main.py
 tests/clingexplaid/test_muc.py
+tests/clingexplaid/test_preprocessors.py
 tests/clingexplaid/test_transformers.py
 tests/clingexplaid/test_unsat_constraints.py
 tests/clingexplaid/test_utils.py
@@ -105,6 +108,7 @@ tests/clingexplaid/res/transformed_program_assumptions_certain_signatures.lp
 tests/clingexplaid/res/transformed_program_constraints.lp
 tests/clingexplaid/res/transformed_program_constraints_id.lp
 tests/clingexplaid/res/transformed_program_facts.lp
+tests/clingexplaid/res/transformed_program_nothing_transformed.lp
 tests/clingexplaid/res/transformed_program_optimization.lp
 tests/clingexplaid/res/transformed_program_pattern.lp
 tests/clingexplaid/res/transformed_program_rule_ids.lp

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/tests/clingexplaid/res/transformed_program_assumptions_all.lp

@@ -2,7 +2,7 @@
 { a(1) }.
 b(2) :- x.
 c(3); c(4) :- x.
-{ d((10..15)) }.
+{ d(10); d(11); d(12); d(13); d(14); d(15) }.
 { e(16) }.
 f(17); f(18) :- e(16).
 { x(19) }.

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/tests/clingexplaid/res/transformed_program_assumptions_certain_signatures.lp

@@ -2,7 +2,7 @@
 { a(1) }.
 b(2) :- x.
 c(3); c(4) :- x.
-{ d((10..15)) }.
+{ d(10); d(11); d(12); d(13); d(14); d(15) }.
 { e(16) }.
 f(17); f(18) :- e(16).
 x(19).

clingexplaid-1.3.0/tests/clingexplaid/res/transformed_program_nothing_transformed.lp

@@ -0,0 +1,13 @@
+#program base.
+a(1).
+b(2) :- x.
+c(3); c(4) :- x.
+d(10).
+d(11).
+d(12).
+d(13).
+d(14).
+d(15).
+e(16).
+f(17); f(18) :- e(16).
+x(19).

{clingexplaid-1.2.2 → clingexplaid-1.3.0}/tests/clingexplaid/test_muc.py

@@ -11,8 +11,7 @@ import clingo
 
 from clingexplaid.mus import CoreComputer
 from clingexplaid.mus.core_computer import UnsatisfiableSubset
-from clingexplaid.transformers import AssumptionTransformer
-from clingexplaid.transformers.transformer_assumption import FilterPattern, FilterSignature
+from clingexplaid.preprocessors import AssumptionPreprocessor, FilterPattern, FilterSignature
 
 from .test_main import TEST_DIR
 
@@ -34,20 +33,18 @@ def get_mus_of_program(
 
     ctl = control if control is not None else clingo.Control()
 
-    at = AssumptionTransformer(filters=assumption_filters)
-    transformed_program = at.parse_string(program_string)
+    ap = AssumptionPreprocessor(filters=assumption_filters)
+    transformed_program = ap.process(program_string)
 
     ctl.add("base", [], transformed_program)
     ctl.ground([("base", [])])
 
-    assumptions = at.get_assumption_literals(ctl)
-
-    cc = CoreComputer(ctl, assumptions)
+    cc = CoreComputer(ctl, ap.assumptions)
 
     def shrink_on_model(core: Sequence[int]) -> None:
         _ = cc.shrink(core, timeout=timeout)
 
-    ctl.solve(assumptions=list(assumptions), on_core=shrink_on_model)
+    ctl.solve(assumptions=list(ap.assumptions), on_core=shrink_on_model)
 
     # if the instance was satisfiable and the on_core function wasn't called an empty set is returned, else the mus.
     result = cc.minimal if cc.minimal is not None else UnsatisfiableSubset(set())
@@ -223,11 +220,12 @@ class TestMUS(TestCase):
         ctl = clingo.Control()
 
         program_path = TEST_DIR.joinpath("res/test_program_multi_mus.lp")
-        at = AssumptionTransformer(filters={FilterSignature("a", 1)})
-        parsed = at.parse_files([program_path])
+        ap = AssumptionPreprocessor(filters={FilterSignature("a", 1)})
+        with open(program_path, "r", encoding="utf-8") as file:
+            parsed = ap.process(file.read())
         ctl.add("base", [], parsed)
         ctl.ground([("base", [])])
-        cc = CoreComputer(ctl, at.get_assumption_literals(ctl))
+        cc = CoreComputer(ctl, ap.assumptions)
 
         mus_generator = cc.get_multiple_minimal()
 
@@ -246,11 +244,12 @@ class TestMUS(TestCase):
         ctl = clingo.Control()
 
         program_path = TEST_DIR.joinpath("res/test_program_multi_mus.lp")
-        at = AssumptionTransformer(filters={FilterSignature("a", 1)})
-        parsed = at.parse_files([program_path])
+        ap = AssumptionPreprocessor(filters={FilterSignature("a", 1)})
+        with open(program_path, "r", encoding="utf-8") as file:
+            parsed = ap.process(file.read())
         ctl.add("base", [], parsed)
         ctl.ground([("base", [])])
-        cc = CoreComputer(ctl, at.get_assumption_literals(ctl))
+        cc = CoreComputer(ctl, ap.assumptions)
 
         mus_generator = cc.get_multiple_minimal(max_mus=2)