Package: xclingo
xclingoA tool for explaining and debugging Answer Set Programs.IMPORTANT:This is a new version ofxclingo. This version is intended to replace the previous one in the future.xclingois 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.InstallationInstall with python3python3-mpipinstallxclingoShort usagexclingo 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.lpDefaults are 1 solution and 1 explanation.ExampleWe 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 commentsannotationsfrom 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)
SATISFIABLEBut 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 authorityNote:for this small example almost all the rules and facts of the program have its own text label (this is, they have beenlabelled). 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_ruleAssigns a text to the atom in the head of a rule.%!trace_rule {"% resisted to authority", P}
punish(P) :- resist(P), person(P).%!traceAssigns 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_traceSelects which atoms should be explained via conditional atoms.%!show_trace sentence(P,S).%!muteMark some atoms asuntraceable. Therefore, explanations will not include them, nor will atoms cause them.%!mute punish(P) : vip_person(P).Usageusage: 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 versionChoice rules and poolingThey 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_ruleannotations.Multiple labels for the same atomIn theprevious version, 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 drunkwhile the new version will produce:*
  |__gabriel goes to prison
  |  |__gabriel drove drunk
  |  |  |__gabriel alcohol's level is 40;gabriel was drunk