tiny-datalog 0.1.0__py3-none-any.whl

tiny_datalog/subsumption.py

@@ -0,0 +1,475 @@
+#!/usr/bin/env python3
+"""
+subsumption.py — KL-ONE-style concept subsumption, compiled to Datalog.
+(Lesson 12, which ends with a tour of this module.)
+
+KL-ONE (Brachman, late 1970s) organised knowledge as *concepts* with
+structured definitions, and its party trick was the classifier: state
+what a Father is, and the system *discovers* where Father belongs in the
+concept hierarchy.  The reasoning service underneath is **subsumption**:
+C is subsumed by D (written C ⊑ D) iff every possible instance of C must
+be an instance of D — a statement about definitions, not about any
+particular database.
+
+This module implements subsumption for the EL concept language —
+conjunction and existential restriction — by the standard
+completion-rule calculus.  EL is the tractable core that the
+SNOMED-scale reasoners (ELK, Snorocket) are built on; they implement
+its extensions (EL++/ELH: top, bottom, role hierarchies, right
+identities), which SNOMED CT actually requires and this module does
+not.  See "Where this stops", below.  The twist that earns it a place in this
+repository: after normalisation, the completion rules are *literally a
+positive Datalog program*, and this module simply compiles the ontology
+to facts + seven rules and hands them to the engine from datalog.py.
+Classification is a fixpoint; goal-directed subsumption checks even work
+under magic sets.  (`--emit` prints the compiled Datalog so you can run
+it yourself.)
+
+Ontology syntax (parsed with the repository's own parser — concept
+expressions are the compound terms Datalog itself forbids):
+
+    isa(man, person).                       % primitive: necessary only
+    define(parent, and(person, some(has_child, person))).
+                                            % defined: necessary AND
+                                            % sufficient — classifiable
+    role(has_child).                        % optional declaration
+    disjoint(cat, dog).                     % cat ⊓ dog ⊑ ⊥ (EL⊥)
+
+Expressions: atomic names, and(...) with two or more conjuncts, and
+some(role, expression).  The predicates subs, link, concept, isa1, isa2,
+isa_some, some_isa, the concept name bot (⊥) and concept names beginning
+gen_ are reserved.
+
+Normalisation introduces fresh names (gen_1, gen_2, ...) for nested
+complex expressions — one inclusion per fresh name, direction chosen by
+which side of ⊑ the expression sits on.  This is a conservative
+extension: subsumptions among the *named* concepts are unchanged.
+
+Where this stops
+----------------
+EL⊥: EL plus disjointness (`disjoint/2` = A ⊓ B ⊑ ⊥), enough to detect
+unsatisfiable definitions via two extra rules (⊥ is below everything;
+∃r.⊥ is ⊥).  No ⊤, no role hierarchies (`subrole/2` is rejected, not
+ignored), no role chains, nominals, datatypes, or ABox: definitions
+only, never individuals.  The completion-rule *method* extends to all of that —
+that is exactly how EL++ reasoners are built — but these seven rules
+are complete only for what is listed above.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from collections import defaultdict
+
+from tiny_datalog.datalog import (
+    Atom, Const, DatalogError, Engine, Literal, parse, Program, read_program,
+    Rule, Struct, Var)
+
+_RESERVED = {"subs", "link", "concept", "isa1", "isa2", "isa_some",
+             "some_isa", "bot"}
+
+class Ontology:
+    """An EL TBox, normalised on load into the four axiom forms:
+
+        isa1(A, B)         A ⊑ B
+        isa2(A1, A2, B)    A1 ⊓ A2 ⊑ B
+        isa_some(A, r, B)  A ⊑ ∃r.B
+        some_isa(r, A, B)  ∃r.A ⊑ B
+    """
+
+    def __init__(self):
+        self.isa1 = []
+        self.isa2 = []
+        self.isa_some = []
+        self.some_isa = []
+        self.disjoint = []      # (A, B) pairs: A ⊓ B ⊑ ⊥
+        self.concepts = set()   # every atomic name, fresh ones included
+        self.named = set()      # concepts the user actually named
+        self.roles = set()
+        self.told = set()       # (sub, super) pairs stated syntactically
+        self._memo = {}         # normalised expression -> fresh name
+        self._fresh = 0
+        self._supers = None     # classification cache
+
+    # -- loading ------------------------------------------------------------
+
+    @classmethod
+    def from_text(cls, text):
+        ont = cls()
+        for clause in parse(text):
+            if clause.body:
+                raise DatalogError(
+                    "an ontology contains only facts, not rules: %s" % clause)
+            pred, args = clause.head.pred, clause.head.args
+            if pred == "isa" and len(args) == 2:
+                ont._axiom(args[0], args[1], told=True)
+            elif pred == "define" and len(args) == 2:
+                if not isinstance(args[0], Const):
+                    raise DatalogError(
+                        "define/2 needs an atomic concept name: %s" % clause)
+                # A definition is an equivalence: both inclusions.
+                ont._axiom(args[0], args[1], told=True)
+                ont._axiom(args[1], args[0])
+            elif pred == "role" and len(args) == 1:
+                ont.roles.add(ont._role_name(args[0]))
+            elif pred == "primitive" and len(args) == 1:
+                ont._concept_name(args[0])
+            elif pred == "disjoint" and len(args) == 2:
+                ont.disjoint.append((ont._concept_name(args[0]),
+                                     ont._concept_name(args[1])))
+            else:
+                raise DatalogError(
+                    "unknown ontology statement %s/%d (expected isa/2, "
+                    "define/2, role/1, primitive/1 or disjoint/2): %s"
+                    % (pred, len(args), clause))
+        return ont
+
+    # -- names --------------------------------------------------------------
+
+    def _concept_name(self, term):
+        if not isinstance(term, Const) or not isinstance(term.value, str):
+            raise DatalogError("expected an atomic concept name, got %s" % (term,))
+        if term.value in _RESERVED or term.value.startswith("gen_"):
+            raise DatalogError("%r is reserved by the compilation%s" % (term.value,
+                "" if term.value in _RESERVED else  # gen_N would merge with a fresh name
+                " (gen_ names are the fresh concepts of normalisation)"))
+        self.concepts.add(term.value)
+        self.named.add(term.value)
+        return term.value
+
+    def _role_name(self, term):
+        if not isinstance(term, Const) or not isinstance(term.value, str):
+            raise DatalogError("expected an atomic role name, got %s" % (term,))
+        self.roles.add(term.value)
+        return term.value
+
+    def _gen(self):
+        self._fresh += 1
+        name = "gen_%d" % self._fresh
+        self.concepts.add(name)   # fresh names are concepts, but not named
+        return name
+
+    # -- normalisation ------------------------------------------------------
+    #
+    # The direction of each fresh-name inclusion follows the expression's
+    # side of ⊑.  On the right (A ⊑ ...expr...) the fresh name goes BELOW
+    # the expression; on the left (...expr... ⊑ B) it goes ABOVE.  Either
+    # way the extension is conservative — a model may always interpret the
+    # fresh name as exactly the expression.
+
+    @staticmethod
+    def _conjuncts(expr):
+        # flatten nested and(...)s into one list
+        if isinstance(expr, Struct) and expr.functor == "and":
+            out = []
+            for a in expr.args:
+                out.extend(Ontology._conjuncts(a))
+            return out
+        return [expr]
+
+    def _axiom(self, lhs, rhs, told=False):
+        """Assert lhs ⊑ rhs for arbitrary expressions."""
+        if isinstance(lhs, Const):
+            self._sub_atom_expr(self._concept_name(lhs), rhs, told=told)
+        elif isinstance(rhs, Const):
+            self._sub_expr_atom(lhs, self._concept_name(rhs))
+        else:
+            mid = self._gen()          # Ĉ ⊑ D̂  →  Ĉ ⊑ A, A ⊑ D̂
+            self._sub_expr_atom(lhs, mid)
+            self._sub_atom_expr(mid, rhs)
+
+    def _sub_atom_expr(self, a, expr, told=False):
+        """a ⊑ expr, a atomic."""
+        if isinstance(expr, Const):
+            b = self._concept_name(expr)
+            self.isa1.append((a, b))
+            if told:
+                self.told.add((a, b))
+        elif isinstance(expr, Struct) and expr.functor == "and":
+            for c in self._conjuncts(expr):
+                self._sub_atom_expr(a, c, told=told)
+        elif isinstance(expr, Struct) and expr.functor == "some" \
+                and len(expr.args) == 2:
+            r = self._role_name(expr.args[0])
+            self.isa_some.append((a, r, self._below(expr.args[1])))
+        else:
+            raise DatalogError("not an EL concept expression: %s" % (expr,))
+
+    def _sub_expr_atom(self, expr, b):
+        """expr ⊑ b, b atomic."""
+        if isinstance(expr, Const):
+            self.isa1.append((self._concept_name(expr), b))
+        elif isinstance(expr, Struct) and expr.functor == "and":
+            atoms = [self._above(c) for c in self._conjuncts(expr)]
+            # binarise a1 ⊓ a2 ⊓ a3 ⊑ b through fresh intermediates
+            while len(atoms) > 2:
+                t = self._gen()
+                self.isa2.append((atoms[0], atoms[1], t))
+                atoms = [t] + atoms[2:]
+            if len(atoms) == 1:
+                self.isa1.append((atoms[0], b))
+            else:
+                self.isa2.append((atoms[0], atoms[1], b))
+        elif isinstance(expr, Struct) and expr.functor == "some" \
+                and len(expr.args) == 2:
+            r = self._role_name(expr.args[0])
+            self.some_isa.append((r, self._above(expr.args[1]), b))
+        else:
+            raise DatalogError("not an EL concept expression: %s" % (expr,))
+
+    def _below(self, expr):
+        """Atomic name for expr in a right-hand position (name ⊑ expr)."""
+        if isinstance(expr, Const):
+            return self._concept_name(expr)
+        key = ("below", str(expr))
+        if key not in self._memo:
+            self._memo[key] = a = self._gen()
+            self._sub_atom_expr(a, expr)
+        return self._memo[key]
+
+    def _above(self, expr):
+        """Atomic name for expr in a left-hand position (expr ⊑ name)."""
+        if isinstance(expr, Const):
+            return self._concept_name(expr)
+        key = ("above", str(expr))
+        if key not in self._memo:
+            self._memo[key] = a = self._gen()
+            self._sub_expr_atom(expr, a)
+        return self._memo[key]
+
+    # -- compilation to Datalog ---------------------------------------------
+
+    def datalog(self):
+        """The completion calculus as a Datalog program (AST clauses).
+
+        Facts encode the normalised TBox; the rules are the EL⊥
+        completion rules (CR1–CR4 plus reflexivity).  subs(C, D) in the
+        fixpoint means C ⊑ D."""
+        def atom(pred, *names):
+            return Atom(pred, tuple(Const(n) for n in names))
+
+        names = sorted(self.concepts) + (["bot"] if self.disjoint else [])
+        clauses = [Rule(atom("concept", c), ()) for c in names]
+        clauses += [Rule(atom("isa2", a, b, "bot"), ()) for a, b in self.disjoint]
+        clauses += [Rule(atom("isa1", a, b), ()) for a, b in self.isa1]
+        clauses += [Rule(atom("isa2", a1, a2, b), ())
+                    for a1, a2, b in self.isa2]
+        clauses += [Rule(atom("isa_some", a, r, b), ())
+                    for a, r, b in self.isa_some]
+        clauses += [Rule(atom("some_isa", r, a, b), ())
+                    for r, a, b in self.some_isa]
+
+        C, D, D1, D2, Dp, E, R = (Var(n) for n in
+                                  ("C", "D", "D1", "D2", "Dp", "E", "R"))
+        lit = lambda pred, *args: Literal(Atom(pred, tuple(args)))
+        clauses += [
+            # every concept subsumes itself
+            Rule(Atom("subs", (C, C)), (lit("concept", C),)),
+            # CR1: climb told inclusions
+            Rule(Atom("subs", (C, E)),
+                 (lit("subs", C, D), lit("isa1", D, E))),
+            # CR2: two subsumers combine through a conjunction axiom
+            Rule(Atom("subs", (C, E)),
+                 (lit("subs", C, D1), lit("subs", C, D2),
+                  lit("isa2", D1, D2, E))),
+            # CR3: a subsumer with an existential creates a role link
+            Rule(Atom("link", (C, R, E)),
+                 (lit("subs", C, D), lit("isa_some", D, R, E))),
+            # CR4: a role link whose target is subsumed appropriately
+            Rule(Atom("subs", (C, E)),
+                 (lit("link", C, R, D), lit("subs", D, Dp),
+                  lit("some_isa", R, Dp, E))),
+            # CR5/CR6 (EL⊥): ⊥ is below everything; ∃r.⊥ is ⊥
+            Rule(Atom("subs", (C, E)),
+                 (lit("subs", C, Const("bot")), lit("concept", E))),
+            Rule(Atom("subs", (C, Const("bot"))),
+                 (lit("link", C, R, D), lit("subs", D, Const("bot")))),
+        ]
+        return clauses
+
+    def emit(self):
+        """The compiled program as Datalog text — runnable by datalog.py."""
+        return "\n".join(str(c) for c in self.datalog()) + "\n"
+
+    # -- classification -----------------------------------------------------
+
+    def saturate(self):
+        """CR1-CR6 as an indexed worklist saturation -- the same calculus
+        datalog() compiles, evaluated natively.  Returns {concept: set of
+        subsumers, itself included}; "bot" in S(C) marks C unsatisfiable.
+        classify(fast=True) uses this; the tests hold it equal to the
+        compiled-Datalog path on every ontology they touch."""
+        concepts = set(self.concepts) | ({"bot"} if self.disjoint else set())
+        by_sub = defaultdict(list)
+        for a, b in self.isa1:
+            by_sub[a].append(b)
+        conj = defaultdict(list)
+        for a1, a2, b in (self.isa2
+                          + [(a, b, "bot") for a, b in self.disjoint]):
+            conj[a1].append((a2, b))
+            conj[a2].append((a1, b))
+        exist = defaultdict(list)
+        for a, r, b in self.isa_some:
+            exist[a].append((r, b))
+        some_isa = defaultdict(list)
+        for r, a, b in self.some_isa:
+            some_isa[(r, a)].append(b)
+        S = {c: {c} for c in concepts}
+        links = defaultdict(set)
+        incoming = defaultdict(set)
+        work = [(c, c) for c in concepts]
+
+        def add(c, d):
+            if d not in S[c]:
+                S[c].add(d)
+                work.append((c, d))
+
+        while work:
+            c, d = work.pop()
+            for e in by_sub.get(d, ()):
+                add(c, e)
+            for d2, e in conj.get(d, ()):
+                if d2 in S[c]:
+                    add(c, e)
+            for r, e in exist.get(d, ()):
+                if (r, e) not in links[c]:
+                    links[c].add((r, e))
+                    incoming[e].add((c, r))
+                    for dp in list(S[e]):
+                        for f in some_isa.get((r, dp), ()):
+                            add(c, f)
+                    if "bot" in S[e]:
+                        add(c, "bot")
+            for c2, r in incoming.get(c, ()):
+                for f in some_isa.get((r, d), ()):
+                    add(c2, f)
+                if d == "bot":
+                    add(c2, "bot")
+            if d == "bot":
+                for e in concepts:
+                    add(c, e)
+        return S
+
+    def classify(self, fast=False):
+        """{named concept: set of named strict subsumers}."""
+        if self._supers is None and fast:
+            S = self.saturate()
+            self._unsat = {c for c in self.named if "bot" in S.get(c, ())}
+            self._supers = {c: {d for d in S[c]
+                                if d in self.named and d != c}
+                            for c in self.named if c not in self._unsat}
+            for c in self._unsat:
+                self._supers[c] = set()
+        if self._supers is None:
+            engine = Engine(Program(self.datalog()))
+            engine.run()
+            self._supers = {c: set() for c in self.named}
+            self._unsat = {c for c, d in engine.rels["subs"]
+                           if d == "bot" and c in self.named}
+            for sub, sup in engine.rels["subs"]:
+                if (sub in self.named and sup in self.named and sub != sup
+                        and sub not in self._unsat):   # ⊥ sits below all
+                    self._supers[sub].add(sup)
+        return self._supers
+
+    def unsatisfiable(self):
+        """Named concepts subsumed by ⊥ (only possible with disjoint/2)."""
+        self.classify()
+        return self._unsat
+
+    def direct_subsumers(self):
+        """The transitive reduction of classify(): for each concept, its
+        immediate parents in the discovered hierarchy."""
+        supers = self.classify()
+        out = {}
+        for c, sup in supers.items():
+            out[c] = {d for d in sup
+                      if not any(e != d and d in supers[e] and e not in supers[d]
+                                 for e in sup)}
+        return out
+
+    def equivalences(self):
+        supers = self.classify()
+        return sorted({tuple(sorted((c, d)))
+                       for c, sup in supers.items()
+                       for d in sup if c in supers[d]})
+
+def load(text):
+    return Ontology.from_text(text)
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Classify an EL ontology by compiling subsumption "
+                    "to Datalog.")
+    ap.add_argument("file", help="ontology file (isa/2, define/2 facts)")
+    ap.add_argument("-q", "--query", action="append", default=[],
+                    metavar="CONCEPT",
+                    help="print all subsumers of one concept (repeatable)")
+    ap.add_argument("--emit", action="store_true",
+                    help="print the compiled Datalog program and exit")
+    ap.add_argument("--fast", action="store_true",
+                    help="classify by native saturation instead of the "
+                         "compiled Datalog program (same result; the "
+                         "tests hold the two equal)")
+    args = ap.parse_args(argv)
+
+    try:
+        ont = load(read_program(args.file))
+        if args.emit:
+            sys.stdout.write(ont.emit())
+            return 0
+        t0 = time.perf_counter()
+        supers = ont.classify(fast=args.fast)
+        elapsed = time.perf_counter() - t0
+        print("(classified in %.3fs via %s)" % (
+            elapsed, "native saturation" if args.fast
+            else "the compiled Datalog program"))
+        direct = ont.direct_subsumers()
+    except DatalogError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+
+    if args.query:
+        for c in args.query:
+            if c not in supers:
+                print("error: unknown concept %r" % c, file=sys.stderr)
+                return 1
+            names = (["⊥   (unsatisfiable)"] if c in ont.unsatisfiable()
+                     else sorted(supers[c]) or ["(none)"])
+            print("%s  ⊑  %s" % (c, ", ".join(names)))
+        return 0
+
+    told = ont.told
+    inferred = 0
+    print("Classification (%d named concepts):" % len(supers))
+    for c in sorted(direct):
+        if c in ont.unsatisfiable():
+            print("  %-14s ⊑  ⊥   (unsatisfiable)" % c)
+            continue
+        if not direct[c]:
+            print("  %-14s (top of hierarchy)" % c)
+            continue
+        parts = []
+        for d in sorted(direct[c]):
+            if (c, d) in told:
+                parts.append(d)
+            else:
+                parts.append(d + "*")
+                inferred += 1
+        print("  %-14s ⊑  %s" % (c, ", ".join(parts)))
+    for c, d in ont.equivalences():
+        print("  %-14s ≡  %s" % (c, d))
+    if inferred:
+        print("  (* = inferred by the classifier, not stated)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tiny_datalog/tabling.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+tabling.py — tabled top-down evaluation: the third vertex of the
+evaluation triangle.  (Lesson 15, which ends with a tour of this module.)
+
+The course has shown three ways to answer a Datalog query:
+
+* bottom-up semi-naive (datalog.py) — compute everything, look up;
+* magic sets (magic.py) — compile the query's demand into the program,
+  then run bottom-up;
+* SLD resolution (prolog.py) — chase the goal top-down, tuple at a time,
+  repeating subgoals and looping on left recursion.
+
+Tabling is top-down done right: every subgoal (a predicate with a
+pattern of bound arguments — an adornment *with its values*) gets a
+**table** of answers, filled once and shared by every occurrence.  A
+subgoal that reaches itself — left recursion, which sends Prolog into
+the abyss — simply reads its own table and grows it to fixpoint.
+
+The implementation is the iterative QSQR formulation, chosen because it
+is honest and small: each round re-solves every tabled subgoal
+top-down, with recursive calls reading current table contents; new
+subgoals encountered get empty tables; repeat until no table grows.
+Termination is Datalog's usual gift — finitely many call patterns,
+finitely many answers.
+
+The punchline to check for yourself: run a bound query here and under
+`datalog.py --magic --trace`, and compare this module's *tables* with
+the magic predicates' contents.  They are the same sets — magic sets is
+tabling performed at compile time, tabling is magic sets performed at
+run time.
+
+Positive programs only (tabling under negation is SLG resolution, which
+computes the well-founded semantics — XSB's whole claim to fame — and
+is beyond this teaching module).
+
+CLI
+---
+    python3 tabling.py programs/reachability.dl -q 'path(n5, X)'
+    python3 tabling.py programs/left-recursive.dl -q 'ancestor(abe, X)'
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import defaultdict
+
+from tiny_datalog.datalog import (
+    check_query_atom, Const, DatalogError, format_fact, parse, parse_goal,
+    read_program, validate, _aggregate_of, _match, _sort_key)
+
+
+class TabledEngine:
+    """Iterative QSQR: tables keyed by call pattern, filled to fixpoint.
+
+    After query(), `tables` maps (pred, pattern) — pattern has a constant
+    per bound argument and None per free one — to the set of full answer
+    tuples for that subgoal, and `rounds` records the outer iterations."""
+
+    def __init__(self, clauses):
+        self.arity = validate(clauses)
+        for c in clauses:
+            if c.retract:
+                raise DatalogError("retraction is incremental.py's job: %s" % c)
+            if c.body and _aggregate_of(c.head):
+                raise DatalogError(
+                    "tabled aggregation needs completion detection (real "
+                    "SLG); this module is positive-rules-only: %s" % c)
+            for lit in c.body:
+                if lit.negated:
+                    raise DatalogError(
+                        "tabling under negation is SLG resolution (the "
+                        "well-founded semantics, XSB) — beyond this "
+                        "module: %s" % c)
+        self.by_pred = defaultdict(list)   # (pred, arity) -> clauses
+        for c in clauses:
+            self.by_pred[(c.head.pred, len(c.head.args))].append(c)
+        self.tables = {}
+        self.rounds = 0
+
+    # -- call patterns ------------------------------------------------------
+
+    @staticmethod
+    def _pattern(atom, subst):
+        """The call pattern of an atom under a substitution: the bound
+        arguments' values, None where still free."""
+        out = []
+        for a in atom.args:
+            if isinstance(a, Const):
+                out.append(a.value)
+            elif a.name in subst:
+                out.append(subst[a.name])
+            else:
+                out.append(None)
+        return tuple(out)
+
+    def _table(self, pred, pattern):
+        key = (pred, pattern)
+        if key not in self.tables:
+            self.tables[key] = set()   # discovered a new subgoal
+            self._grew = True          # ...which the fixpoint must revisit
+        return self.tables[key]
+
+    # -- one round of top-down solving --------------------------------------
+
+    def _prove(self, body, subst):
+        """Solve a rule body left to right; recursive calls read the
+        current tables (never the clauses directly — that is the whole
+        trick: no infinite descent, the fixpoint loop supplies growth)."""
+        if not body:
+            yield subst
+            return
+        lit, rest = body[0], body[1:]
+        table = self._table(lit.atom.pred, self._pattern(lit.atom, subst))
+        for ans in table:
+            s = _match(lit.atom.args, ans, subst)
+            if s is not None:
+                yield from self._prove(rest, s)
+
+    def _answers_for(self, key):
+        """Re-derive a subgoal's answers from its clauses, one step of
+        head unification plus a tabled body proof."""
+        pred, pattern = key
+        for clause in self.by_pred.get((pred, len(pattern)), ()):
+            # unify the head with the call pattern (bound args only)
+            seed = {}
+            ok = True
+            for a, v in zip(clause.head.args, pattern):
+                if v is None:
+                    continue
+                if isinstance(a, Const):
+                    if a.value != v:
+                        ok = False
+                        break
+                elif a.name in seed and seed[a.name] != v:
+                    ok = False
+                    break
+                else:
+                    seed[a.name] = v
+            if not ok:
+                continue
+            for s in self._prove(list(clause.body), seed):
+                yield tuple(a.value if isinstance(a, Const) else s[a.name]
+                            for a in clause.head.args)
+
+    # -- the fixpoint --------------------------------------------------------
+
+    def query(self, atom):
+        """All answers to `atom`, computed by tabled top-down evaluation.
+        Also populates self.tables / self.rounds for inspection."""
+        check_query_atom(atom, self.arity)
+        root = (atom.pred, self._pattern(atom, {}))
+        self.tables = {root: set()}
+        self.rounds = 0
+        changed = True
+        while changed:
+            changed = False
+            self._grew = False
+            self.rounds += 1
+            for key in list(self.tables):
+                table = self.tables[key]
+                for ans in list(self._answers_for(key)):
+                    if ans not in table:
+                        table.add(ans)
+                        changed = True
+            changed = changed or self._grew
+        return {t for t in self.tables[root]
+                if _match(atom.args, t, {}) is not None}
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Tabled top-down (QSQR) evaluation of positive "
+                    "Datalog — handles left recursion SLD cannot.")
+    ap.add_argument("file", help="Datalog program (.dl), positive rules only")
+    ap.add_argument("-q", "--query", action="append", default=[],
+                    metavar="ATOM", help="goal to solve (repeatable)")
+    ap.add_argument("-t", "--tables", action="store_true",
+                    help="also print every table (compare these with the "
+                         "magic predicates from datalog.py --magic!)")
+    args = ap.parse_args(argv)
+
+    try:
+        engine = TabledEngine(parse(read_program(args.file)))
+    except DatalogError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+    for q in args.query:
+        try:
+            atom = parse_goal(q)
+            answers = engine.query(atom)
+        except DatalogError as exc:
+            print("error: %s" % exc, file=sys.stderr)
+            return 1
+        print("?- %s   [tabled]" % atom)
+        for tup in sorted(answers, key=_sort_key):
+            print("   " + format_fact(atom.pred, tup))
+        print("   (%d answer%s; %d subgoal table%s, %d rounds)"
+              % (len(answers), "" if len(answers) == 1 else "s",
+                 len(engine.tables), "" if len(engine.tables) == 1 else "s",
+                 engine.rounds))
+        if args.tables:
+            for (pred, pattern), tbl in sorted(
+                    engine.tables.items(),
+                    key=lambda kv: (kv[0][0], str(kv[0][1]))):
+                shown = ", ".join("_" if v is None else str(v)
+                                  for v in pattern)
+                print("   table %s(%s): %d answer%s"
+                      % (pred, shown, len(tbl),
+                         "" if len(tbl) == 1 else "s"))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())