Transformers

Transformers for Explanation.

__all__ = ['ConstraintTransformer', 'FactTransformer', 'OptimizationRemover', 'RuleIDTransformer', 'RuleSplitter'] module-attribute

ConstraintTransformer(constraint_head_symbol: str, include_id: bool = False)

Bases: Transformer

A Transformer that takes all constraint rules and adds an atom to their head to avoid deriving false through them.

Construct a ConstraintTransformer with the given head symbol and option to include an id per constraint.

PARAMETER	DESCRIPTION
constraint_head_symbol	The symbol to use for the constraint head atom. TYPE: str
include_id	Whether to include the constraint ID is included in the head atom. TYPE: bool DEFAULT: False

parse_files(paths: Sequence[str | Path]) -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Add a constraint_head_symbol atom to the head of every constraint.

FactTransformer(signatures: set[tuple[str, int]] | None = None)

Bases: Transformer

Transformer removes all facts from a program that match provided signatures.

Construct a FactTransformer for the given fact signatures.

PARAMETER	DESCRIPTION
signatures	The set of signatures to match facts against. TYPE: set[tuple[str, int]] | None DEFAULT: None

parse_files(paths: Sequence[str | Path]) -> str

Transform the provided list of files and return a concatination of their transformations.

parse_string(string: str) -> str

Transform the provided string and return its transformation.

post_transform(program_string: str) -> str staticmethod

Return a cleaned-up version after the transformation.

visit_Rule(node: AST) -> AST

Remove all facts from a program that match the given signatures (if none are given all facts are removed).

OptimizationRemover

Bases: Transformer

Transformer that removes all optimization statements.

parse_files(paths: Sequence[str | Path]) -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

post_transform(program_string: str) -> str staticmethod

Cleanup after the transformation.

visit_Minimize(node: ast.AST) -> ast.AST

Remove all facts from a program that match the given signatures (if none are given all facts are removed).

RuleIDTransformer(rule_id_signature: str = RULE_ID_SIGNATURE)

Bases: Transformer

Transformer that takes all the rules of a program and adds an atom with self.rule_id_signature in their bodys.

This is to make the original rule the generated them identifiable even after grounding. Additionally, a choice rule containing all generated self.rule_id_signature atoms is added, which allows us to add assumptions that assume them. This is done in order to not modify the original program's reasoning by assuming all self.rule_id_signature atoms as True.

Construct a RuleIDTransformer with the given rule ID signature.

PARAMETER	DESCRIPTION
rule_id_signature	The signature to use for the rule ID atom. TYPE: str DEFAULT: RULE_ID_SIGNATURE

get_assumptions(n_rules: int | None = None) -> set[tuple[clingo.Symbol, bool]]

Get the rule_id_signature assumptions.

This can be modified, depending on the number of rules contained in the transformed program. Can only be called after parse_file has been executed before.

parse_file(path: str | Path, encoding: str = 'utf-8') -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Add a rule_id_signature(id) atom to the body of every rule that is visited.

RuleSplitter()

Bases: Transformer

A transformer that is used to split rules into two.

This is done using an intermediate predicate called _body, which contains a base64 representation of the original rule and all body variable assignments for explanation purposes. This intermediate predicate replaces the head of the original rule and a new rule with the old head and the newly generated _body predicate as the body is also inserted. Use the parse_string method to apply this transformer.

Construct a RuleSplitter.

parse_file(path: str | Path, encoding: str = 'utf-8') -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Replace the head of every rule with a _body predicate and stores all new head rules in self.head_rules.

constants

Constant definitions for the transformers package.

transformer_constraint

Transformer adding atoms to constraint heads to retrace the ones firing in the case of an unsatisfiable program.

ConstraintTransformer(constraint_head_symbol: str, include_id: bool = False)

Bases: Transformer

A Transformer that takes all constraint rules and adds an atom to their head to avoid deriving false through them.

Construct a ConstraintTransformer with the given head symbol and option to include an id per constraint.

PARAMETER	DESCRIPTION
constraint_head_symbol	The symbol to use for the constraint head atom. TYPE: str
include_id	Whether to include the constraint ID is included in the head atom. TYPE: bool DEFAULT: False

parse_files(paths: Sequence[str | Path]) -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Add a constraint_head_symbol atom to the head of every constraint.

transformer_fact

Transformer to remove facts for a program.

FactTransformer(signatures: set[tuple[str, int]] | None = None)

Bases: Transformer

Transformer removes all facts from a program that match provided signatures.

Construct a FactTransformer for the given fact signatures.

PARAMETER	DESCRIPTION
signatures	The set of signatures to match facts against. TYPE: set[tuple[str, int]] | None DEFAULT: None

parse_files(paths: Sequence[str | Path]) -> str

Transform the provided list of files and return a concatination of their transformations.

parse_string(string: str) -> str

Transform the provided string and return its transformation.

post_transform(program_string: str) -> str staticmethod

Return a cleaned-up version after the transformation.

visit_Rule(node: AST) -> AST

Remove all facts from a program that match the given signatures (if none are given all facts are removed).

transformer_optimization_remover

Transformer Module: Removing all optimization statements.

OptimizationRemover

Bases: Transformer

Transformer that removes all optimization statements.

parse_files(paths: Sequence[str | Path]) -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

post_transform(program_string: str) -> str staticmethod

Cleanup after the transformation.

visit_Minimize(node: ast.AST) -> ast.AST

Remove all facts from a program that match the given signatures (if none are given all facts are removed).

transformer_rule_id

Transformer Module: Adding unique rule identifiers to the body of rules.

RuleIDTransformer(rule_id_signature: str = RULE_ID_SIGNATURE)

Bases: Transformer

Transformer that takes all the rules of a program and adds an atom with self.rule_id_signature in their bodys.

This is to make the original rule the generated them identifiable even after grounding. Additionally, a choice rule containing all generated self.rule_id_signature atoms is added, which allows us to add assumptions that assume them. This is done in order to not modify the original program's reasoning by assuming all self.rule_id_signature atoms as True.

Construct a RuleIDTransformer with the given rule ID signature.

PARAMETER	DESCRIPTION
rule_id_signature	The signature to use for the rule ID atom. TYPE: str DEFAULT: RULE_ID_SIGNATURE

get_assumptions(n_rules: int | None = None) -> set[tuple[clingo.Symbol, bool]]

Get the rule_id_signature assumptions.

This can be modified, depending on the number of rules contained in the transformed program. Can only be called after parse_file has been executed before.

parse_file(path: str | Path, encoding: str = 'utf-8') -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Add a rule_id_signature(id) atom to the body of every rule that is visited.

transformer_rule_splitter

Transformer Module: Split Rules into dedicated body and head parts.

RuleSplitter()

Bases: Transformer

A transformer that is used to split rules into two.

This is done using an intermediate predicate called _body, which contains a base64 representation of the original rule and all body variable assignments for explanation purposes. This intermediate predicate replaces the head of the original rule and a new rule with the old head and the newly generated _body predicate as the body is also inserted. Use the parse_string method to apply this transformer.

Construct a RuleSplitter.

parse_file(path: str | Path, encoding: str = 'utf-8') -> str

Apply the transformer to the provided file.

parse_string(string: str) -> str

Apply the transformer to the provided string.

visit_Rule(node: clingo.ast.AST) -> clingo.ast.AST

Replace the head of every rule with a _body predicate and stores all new head rules in self.head_rules.