# xclingo
A tool for explaining and debugging Answer Set Programs.
***IMPORTANT:*** This is a new version of [xclingo](https://github.com/bramucas/xclingo). This version is intended to replace the previous one in the future.
**xclingo** is a clingo-based tool which produces text explanations for the solutions of ASP programs. The original program must be annotated with clingo-friendly annotations and then provided to xclingo.
All the directives start with a ```%``` character, so they are recognized by clingo as comments and therefore they don't modify the meaning of the original program. In other words: a xclingo-annotated ASP program will still produce the original output when called with clingo.
## Installation
*Install with python3*
```bash
python3 -m pip install xclingo
```
## Short usage
xclingo must be provided with a maximum number of solutions to be computed for the original program and with the maximum number of explanations to be printed for each solution.
An example (all the solutions and 2 explanations):
```
xclingo -n 0 2 examples/drive.lp
```
Defaults are 1 solution and 1 explanation.
## Example
We have any ASP program:
```
% examples/dont_drive_drunk.lp
person(gabriel;clare).
drive(gabriel).
alcohol(gabriel, 40).
resist(gabriel).
drive(clare).
alcohol(clare, 5).
punish(P) :- drive(P), alcohol(P,A), A>30, person(P).
punish(P) :- resist(P), person(P).
sentence(P, prison) :- punish(P).
sentence(P, innocent) :- person(P), not punish(P).
```
And we write some special comments:
```
% examples/dont_drive_drunk.lp
person(gabriel;clare).
drive(gabriel).
alcohol(gabriel, 40).
resist(gabriel).
drive(clare).
alcohol(clare, 5).
%!trace_rule {"% drove drunk", P}
punish(P) :- drive(P), alcohol(P,A), A>30, person(P).
%!trace_rule {"% resisted to authority", P}
punish(P) :- resist(P), person(P).
%!trace_rule {"% goes to prison",P}
sentence(P, prison) :- punish(P).
%!trace_rule {"% is innocent by default",P}
sentence(P, innocent) :- person(P), not punish(P).
%!trace {"% alcohol's level is %",P,A} alcohol(P,A).
%!trace {"% was drunk",P} alcohol(P,A).
%!show_trace sentence(P,S).
```
We will call those comments *annotations* from now on.
Now we can obtain the answer sets of the (annotated) program with clingo (```clingo -n 0 examples/dont_drive_drunk.lp```):
```
Answer: 1
person(gabriel) person(clare) alcohol(gabriel,40) alcohol(clare,5) drive(gabriel) drive(clare) punish(gabriel) resist(gabriel) sentence(clare,innocent) sentence(gabriel,prison)
SATISFIABLE
```
But also very fashion natural language explanations of with xclingo (```xclingo -n 0 0 examples/dont_drive_drunk.lp```):
```
Answer 1
*
|__clare is innocent by default
*
|__gabriel goes to prison
| |__gabriel drove drunk
| | |__gabriel alcohol's level is 40;gabriel was drunk
*
|__gabriel goes to prison
| |__gabriel resisted to authority
```
*Note:* for this small example almost all the rules and facts of the program have its own text label (this is, they have been *labelled*). Actually, only labelled rules are used to build the explanations so you can still obtain clear, short explanations even for most complex ASP programs.
## Annotations
### %!trace_rule
Assigns a text to the atom in the head of a rule.
```
%!trace_rule {"% resisted to authority", P}
punish(P) :- resist(P), person(P).
```
### %!trace
Assigns a text to the set of atoms produced by a conditional atom.
```
%!trace {"% alcohol's level is above permitted (%)",P,A} alcohol(P,A) : A>40.
```
### %!show_trace
Selects which atoms should be explained via conditional atoms.
```
%!show_trace sentence(P,S).
```
### %!mute
Mark some atoms as *untraceable*. Therefore, explanations will not include them, nor will atoms cause them.
```
%!mute punish(P) : vip_person(P).
```
## Usage
```
usage: xclingo [-h] [--version] [--only-translate | --only-translate-annotations | --only-explanation-atoms] [--auto-tracing {none,facts,all}] [-n N N] infiles [infiles ...]
Tool for explaining (and debugging) ASP programs
positional arguments:
infiles ASP program
optional arguments:
-h, --help show this help message and exit
--version Prints the version and exists.
--only-translate Prints the internal translation and exits.
--only-translate-annotations
Prints the internal translation and exits.
--only-explanation-atoms
Prints the atoms used by the explainer to build the explanations.
--auto-tracing {none,facts,all}
Automatically creates traces for the rules of the program. Default: none.
-n N N Number of answer sets and number of desired explanations.
```
## Differences with respect to the previous version
### Choice rules and pooling
They are now supported.
```
n(1..20).
switch(s1;s2;s3;s4).
2{num(N):n(N)}4 :- n(N), N>15.
```
Then can be traced with ```%!trace_rule``` annotations.
### Multiple labels for the same atom
In the [previous version](https://github.com/bramucas/xclingo), multiple labels for the same atom lead to alternative explanations. In this version a single explanation is be produced in which labels are concatenated.
As an example, the following situation:
```
%!trace {"% alcohol's level is above permitted (%)",P,A} alcohol(P,A) : A>40.
%!trace {"% was drunk",P} alcohol(P,A) : A>40.
```
would lead to the following result in the previous version:
```
*
|__gabriel goes to prison
| |__gabriel drove drunk
| | |__gabriel alcohol's level is 40
*
|__gabriel goes to prison
| |__gabriel drove drunk
| | |__gabriel was drunk
```
while the new version will produce:
```
*
|__gabriel goes to prison
| |__gabriel drove drunk
| | |__gabriel alcohol's level is 40;gabriel was drunk
```
###
Raw data
{
"_id": null,
"home_page": "https://github.com/bramucas/xclingo2",
"name": "xclingo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "logic programming, answer set programming",
"author": "Brais Mu\u00f1iz",
"author_email": "mc.brais@gmail.com",
"download_url": null,
"platform": null,
"description": "# xclingo\n\nA tool for explaining and debugging Answer Set Programs.\n\n***IMPORTANT:*** This is a new version of [xclingo](https://github.com/bramucas/xclingo). This version is intended to replace the previous one in the future.\n\n**xclingo** is a clingo-based tool which produces text explanations for the solutions of ASP programs. The original program must be annotated with clingo-friendly annotations and then provided to xclingo. \n\nAll the directives start with a ```%``` character, so they are recognized by clingo as comments and therefore they don't modify the meaning of the original program. In other words: a xclingo-annotated ASP program will still produce the original output when called with clingo. \n\n## Installation\n*Install with python3*\n\n```bash\npython3 -m pip install xclingo\n```\n\n## Short usage\nxclingo must be provided with a maximum number of solutions to be computed for the original program and with the maximum number of explanations to be printed for each solution.\n\nAn example (all the solutions and 2 explanations):\n```\nxclingo -n 0 2 examples/drive.lp\n```\n\nDefaults are 1 solution and 1 explanation.\n\n## Example\n\nWe have any ASP program:\n```\n% examples/dont_drive_drunk.lp\n\nperson(gabriel;clare).\n\ndrive(gabriel).\nalcohol(gabriel, 40).\nresist(gabriel).\n\ndrive(clare).\nalcohol(clare, 5).\n\npunish(P) :- drive(P), alcohol(P,A), A>30, person(P).\npunish(P) :- resist(P), person(P).\n\nsentence(P, prison) :- punish(P).\nsentence(P, innocent) :- person(P), not punish(P).\n```\n\nAnd we write some special comments:\n```\n% examples/dont_drive_drunk.lp\n\nperson(gabriel;clare).\n\ndrive(gabriel).\nalcohol(gabriel, 40).\nresist(gabriel).\n\ndrive(clare).\nalcohol(clare, 5).\n\n%!trace_rule {\"% drove drunk\", P}\npunish(P) :- drive(P), alcohol(P,A), A>30, person(P).\n\n%!trace_rule {\"% resisted to authority\", P}\npunish(P) :- resist(P), person(P).\n\n%!trace_rule {\"% goes to prison\",P}\nsentence(P, prison) :- punish(P).\n\n%!trace_rule {\"% is innocent by default\",P}\nsentence(P, innocent) :- person(P), not punish(P).\n\n%!trace {\"% alcohol's level is %\",P,A} alcohol(P,A).\n%!trace {\"% was drunk\",P} alcohol(P,A).\n\n%!show_trace sentence(P,S).\n```\nWe will call those comments *annotations* from now on.\n\nNow we can obtain the answer sets of the (annotated) program with clingo (```clingo -n 0 examples/dont_drive_drunk.lp```):\n```\nAnswer: 1\nperson(gabriel) person(clare) alcohol(gabriel,40) alcohol(clare,5) drive(gabriel) drive(clare) punish(gabriel) resist(gabriel) sentence(clare,innocent) sentence(gabriel,prison)\nSATISFIABLE\n```\n\nBut also very fashion natural language explanations of with xclingo (```xclingo -n 0 0 examples/dont_drive_drunk.lp```):\n```\nAnswer 1\n *\n |__clare is innocent by default\n\n *\n |__gabriel goes to prison\n | |__gabriel drove drunk\n | | |__gabriel alcohol's level is 40;gabriel was drunk\n\n *\n |__gabriel goes to prison\n | |__gabriel resisted to authority\n```\n\n*Note:* for this small example almost all the rules and facts of the program have its own text label (this is, they have been *labelled*). Actually, only labelled rules are used to build the explanations so you can still obtain clear, short explanations even for most complex ASP programs.\n\n## Annotations\n\n### %!trace_rule\nAssigns a text to the atom in the head of a rule.\n```\n%!trace_rule {\"% resisted to authority\", P}\npunish(P) :- resist(P), person(P).\n```\n\n### %!trace\nAssigns a text to the set of atoms produced by a conditional atom.\n```\n%!trace {\"% alcohol's level is above permitted (%)\",P,A} alcohol(P,A) : A>40.\n```\n\n### %!show_trace\nSelects which atoms should be explained via conditional atoms.\n```\n%!show_trace sentence(P,S).\n```\n\n### %!mute\nMark some atoms as *untraceable*. Therefore, explanations will not include them, nor will atoms cause them.\n```\n%!mute punish(P) : vip_person(P).\n```\n\n## Usage\n\n```\nusage: xclingo [-h] [--version] [--only-translate | --only-translate-annotations | --only-explanation-atoms] [--auto-tracing {none,facts,all}] [-n N N] infiles [infiles ...]\n\nTool for explaining (and debugging) ASP programs\n\npositional arguments:\n infiles ASP program\n\noptional arguments:\n -h, --help show this help message and exit\n --version Prints the version and exists.\n --only-translate Prints the internal translation and exits.\n --only-translate-annotations\n Prints the internal translation and exits.\n --only-explanation-atoms\n Prints the atoms used by the explainer to build the explanations.\n --auto-tracing {none,facts,all}\n Automatically creates traces for the rules of the program. Default: none.\n -n N N Number of answer sets and number of desired explanations.\n```\n\n## Differences with respect to the previous version\n\n### Choice rules and pooling\nThey are now supported.\n```\nn(1..20).\nswitch(s1;s2;s3;s4).\n2{num(N):n(N)}4 :- n(N), N>15.\n```\nThen can be traced with ```%!trace_rule``` annotations.\n\n### Multiple labels for the same atom\n\nIn the [previous version](https://github.com/bramucas/xclingo), multiple labels for the same atom lead to alternative explanations. In this version a single explanation is be produced in which labels are concatenated.\n\nAs an example, the following situation:\n```\n%!trace {\"% alcohol's level is above permitted (%)\",P,A} alcohol(P,A) : A>40.\n%!trace {\"% was drunk\",P} alcohol(P,A) : A>40.\n```\n\nwould lead to the following result in the previous version:\n```\n*\n |__gabriel goes to prison\n | |__gabriel drove drunk\n | | |__gabriel alcohol's level is 40\n\n*\n |__gabriel goes to prison\n | |__gabriel drove drunk\n | | |__gabriel was drunk\n```\n\nwhile the new version will produce:\n\n```\n*\n |__gabriel goes to prison\n | |__gabriel drove drunk\n | | |__gabriel alcohol's level is 40;gabriel was drunk\n```\n\n###\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Tool for explaining and debugging Answer Set Programs.",
"version": "2.0b19",
"project_urls": {
"Homepage": "https://github.com/bramucas/xclingo2"
},
"split_keywords": [
"logic programming",
" answer set programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ed71c7e7a2f91c367fb7b5426075f7179aa492080b8e310f3e2d4c62ff54632",
"md5": "c93371903290483aa4a607a0fc7f9463",
"sha256": "07f66a32db4f66c115ff7e893f7074bd9709532e45696fc05164ca5cea24cb00"
},
"downloads": -1,
"filename": "xclingo-2.0b19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c93371903290483aa4a607a0fc7f9463",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 27797,
"upload_time": "2024-09-30T14:33:26",
"upload_time_iso_8601": "2024-09-30T14:33:26.942255Z",
"url": "https://files.pythonhosted.org/packages/0e/d7/1c7e7a2f91c367fb7b5426075f7179aa492080b8e310f3e2d4c62ff54632/xclingo-2.0b19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 14:33:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bramucas",
"github_project": "xclingo2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xclingo"
}
JSON
