relationalai 0.13.0__py3-none-any.whl → 0.13.0.dev0__py3-none-any.whl

relationalai/experimental/paths/rpq/automaton.py

@@ -1,584 +0,0 @@
-from typing import List, Dict, Set, Tuple
-from relationalai.debugging import warn
-
-from .filter import EdgeLabel
-from .transition import (
-    EdgeTransition, NodeTransition, simulate
-)
-
-# =========================================================================================
-# Finite Automaton
-# =========================================================================================
-#
-# An NFA consists of:
-# - states -- a finite set of states (integers)
-# - init ⊆ states -- a set of initial states
-# - delta: states → states → {EdgeTransition} -- transition function
-# - final: states → {NodeTransition} -- final states function
-#
-# We introduce the NFA because a number of simplification manipulations are easier to
-# perform on an NFA than on a Glushkov outline. The NFA is obtained from the Glushkov
-# outline simply by adding a distinguished initial state 0 and using first transitions and
-# last transitions to extend the transition function and final states. The simplification
-# operations only remove unnecessary states and transitions; and their main purpose is to
-# remove simple cases of non-determinism due to the use of the repetition `[n:m]` in RPQs.
-# We do not perform more sophisticated operations such as determinization as those may lead
-# to introduction of new states and loss of correspondence between states and the positions
-# in the original RPQ.
-#
-# ------------------------------------------------------------------------------------------
-# Example
-# ------------------------------------------------------------------------------------------
-# Recall the RPQ `path(OddNode, star('-[A]->', EvenNode) | path('<-[B]-', Node)` and its
-# Glushkov automaton outline:
-#
-#  * epsilon:
-#    ⋅ ⊨⸨OddNode⸩⇒
-#  * positions (label):
-#      1 -⟨A⟩→
-#      2 ←⟨B⟩-
-#  * first:
-#      → 1:
-#        ⋅ ⊨⸨OddNode⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
-#      → 2:
-#        ⋅ ⊨⸨⸩=⟦←⟨B⟩-⟧=⸨⸩⇒
-#  * follows:
-#     - 1
-#       → 1:
-#         ⋅ ⊨⸨EvenNode⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
-#  * last:
-#     - 1:
-#       ⋅ ⊨⸨EvenNode⸩⇒
-#     - 2:
-#       ⋅ ⊨⸨Node⸩⇒
-#
-# The corresponding (reduced) finite automaton follows:
-#
-# * states: 0 1 2
-# * init: 0
-# * delta:
-#    - 0
-#       → 1
-#         ⋅ ⊨⸨OddNode⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
-#       → 2
-#         ⋅ ⊨⸨⸩=⟦←⟨B⟩-⟧=⸨⸩⇒
-#    - 1
-#       → 1
-#         ⋅ ⊨⸨EvenNode⸩=⟦-⟨A⟩→⟧=⸨⸩⇒
-# * final:
-#    - 0
-#       ⋅ ⊨⸨OddNode⸩⇒
-#    - 1
-#       ⋅ ⊨⸨EvenNode⸩⇒
-#    - 2
-#       ⋅ ⊨⸨Node⸩⇒
-# =========================================================================================
-
-class Automaton:
-    def __init__(self,
-                 states: Set[int],
-                 init:Set[int],
-                 delta: Dict[int, Dict[int, Set[EdgeTransition]]],
-                 final: Dict[int, Set[NodeTransition]]):
-        self.states = states
-        self.init = init
-        self.delta = delta
-        self.final = final
-
-    def __repr__(self) -> str:
-        res = "Automaton:\n"
-        res += "* states: " + ' '.join([str(s) for s in sorted(self.states)]) + "\n"
-        res += "* init: " + ' '.join([str(s) for s in sorted(self.init)]) + "\n"
-        res += "* delta:\n"
-        for q in sorted(self.delta):
-            res += f"   - {q}\n"
-            for p in sorted(self.delta[q]):
-                res += f"      → {p}\n"
-                for t in self.delta[q][p]:
-                    res += f"        ⋅ {t}\n"
-        res += "* final: \n"
-        for q in sorted(self.final):
-            res += f"   - {q}\n"
-            for t in self.final[q]:
-                res += f"      ⋅ {t}\n"
-        return res[:-1]
-
-    def __len__(self) -> int:
-        return len(self.states)
-
-    def to_dict(self) -> dict:
-        return {
-            "type": "Automaton",
-            "states": list(sorted(self.states)),
-            "init": list(sorted(self.init)),
-            "delta": {
-                q: {
-                    p: [t.to_dict() for t in self.delta[q][p]]
-                    for p in self.delta[q]
-                }
-                for q in self.delta
-            },
-            "final": {
-                q: [t.to_dict() for t in self.final[q]]
-                for q in self.final
-            }
-        }
-
-    @property
-    def alphabet(self) -> Set[EdgeLabel]:
-        res = set()
-        for q in self.delta:
-            for p in self.delta[q]:
-                for t in self.delta[q][p]:
-                    res.add(t.get_label())
-        return res
-
-    # Methods to query the automaton regardless of whether it is complete or not
-    def get_edge_transitions(self, q: int, p: int) -> Set[EdgeTransition]:
-        return self.delta.get(q, dict()).get(p, set())
-
-    def get_edge_labels(self, q: int, p: int) -> Set[EdgeLabel]:
-        return {t.get_label() for t in self.get_edge_transitions(q, p)}
-
-    def has_edge_transitions(self, q: int, p: int) -> bool:
-        return len(self.get_edge_transitions(q, p)) > 0
-
-    def get_outbound_states(self, q: int) -> Set[int]:
-        return {p for p in self.states if self.has_edge_transitions(q, p)}
-
-    def get_inbound_states(self, p: int) -> Set[int]:
-        return {q for q in self.states if self.has_edge_transitions(q, p)}
-
-    def get_initial_state(self) -> int:
-        assert len(self.init) == 1, "Automaton is non-deterministic: multiple initial states"
-        return next(iter(self.init))
-
-    def get_final_states(self) -> Set[int]:
-        return {q for q in self.states if self.is_final(q)}
-
-    def is_final(self, q: int) -> bool:
-        return len(self.get_final_transitions(q)) > 0
-
-    def is_exit(self, q: int) -> bool:
-        return self.is_final(q) and len(self.get_outbound_states(q)) == 0
-
-    def get_final_transitions(self, q: int) -> Set[NodeTransition]:
-        return self.final.get(q, set())
-
-    # Returns a list of strings explaining causes of non-determinism
-    def determinism_report(self) -> List[str]:
-        report = []
-
-        # this won't be happening if we work with Glushkov automata from RPQ
-        if len(self.init) > 1:
-            report.append(f"Multiple initial states: {', '.join(map(str, self.init))}")
-
-        def complain(q: int, lab: EdgeLabel, T: Set[Tuple[EdgeTransition, int]]) -> str:
-            if q == 0:
-                complaint = f"Ambiguous initial transitions for label {lab}:\n"
-            else:
-                complaint = f"Ambiguous transitions from {q} with label {lab}:\n"
-            for (t, p) in T:
-                complaint += f"  -> to position {p} (with transition {t})\n"
-            return complaint
-
-        for q in self.states:
-            q_labels: Dict[EdgeLabel, Set[Tuple[EdgeTransition, int]]] = dict()
-            for p in self.get_outbound_states(q):
-                for t in self.delta[q][p]:
-                    lab = t.get_label()
-                    if lab not in q_labels:
-                        q_labels[lab] = set()
-                    q_labels[lab].add((t, p))
-
-            for lab in q_labels:
-                if len(q_labels[lab]) > 1:
-                    report.append(complain(q, lab, q_labels[lab]))
-
-        return report
-
-    def is_deterministic(self) -> bool:
-        return len(self.determinism_report()) == 0
-
-    # Checks if the automaton has no reachable final states i.e. empty language.
-    def is_void(self) -> bool:
-        reachable: Set[int] = set()
-        frontier: Set[int] = self.init.copy()
-        while len(frontier) > 0:
-            q = frontier.pop()
-            if q in reachable:
-                continue
-            reachable.add(q)
-            for p in self.get_outbound_states(q):
-                if p in reachable | frontier:
-                    continue
-                frontier.add(p)
-
-        return len(reachable & self.get_final_states()) == 0
-
-    # Checks whether the automaton is grounded, i.e., it accepts only a finite number of
-    # paths in given a finite graph. An automaton can accept an infinite number of
-    # single-node paths if the initial state is accepting with an final ε-transition that
-    # does not check for node label.
-    def is_grounded(self) -> bool:
-        return all(t.is_grounded() for q in self.init for t in self.get_final_transitions(q))
-
-    # ----------------------------------------------------------------------------
-    # Reduction
-    # ----------------------------------------------------------------------------
-
-    # Simplifies the automaton by removing unnecessary states and transitions.
-    def reduce(self, prune_states_only=False):
-        while True:
-            pruned = False
-
-            # logger.debug("Pruning iteration for")
-            # logger.debug(self)
-
-            pruned |= self.prune_unreachable_states()
-            pruned |= self.prune_unproductive_states()
-
-            if not prune_states_only:
-                pruned |= self.prune_redundant_transitions()
-
-            if not pruned:
-                break
-
-        # logger.debug("Final automaton after reduction:")
-        # logger.debug(self)
-
-    # Prunes unreachable states: returns True if any states were pruned.
-    def prune_unreachable_states(self) -> bool:
-        reachable: Set[int] = set()
-        frontier: Set[int] = self.init.copy()
-        while len(frontier) > 0:
-            q = frontier.pop()
-            if q in reachable:
-                continue
-            reachable.add(q)
-            for p in self.get_outbound_states(q):
-                if p in reachable | frontier:
-                    continue
-                frontier.add(p)
-
-        unreachable = self.states - reachable
-
-        # logger.debug('Unreachable states:')
-        # logger.debug(list(sorted(unreachable)))
-
-        self.prune(redundant_states=unreachable)
-
-        return len(unreachable) > 0
-
-    # Prunes unproductive states: returns True if any states were pruned.
-    def prune_unproductive_states(self, debug: bool=True) -> bool:
-        productive: Set[int] = set()
-        frontier = {q for q in self.states if self.is_final(q)}
-        while len(frontier) > 0:
-            q = frontier.pop()
-            if q in productive:
-                continue
-            productive.add(q)
-            for p in self.get_inbound_states(q):
-                if p in productive | frontier:
-                    continue
-                frontier.add(p)
-
-        unproductive = self.states - productive
-
-        # logger.debug('Unproductive states:')
-        # logger.debug(list(sorted(unproductive)))
-
-        self.prune(redundant_states=unproductive)
-
-        return len(unproductive) > 0
-
-    # Uses simulation relation on states to identify and prune redundant transitions.
-    # Returns True if any transitions were pruned.
-    def prune_redundant_transitions(self, debug: bool=True) -> bool:
-        # The simulation relation:
-        #
-        # p _simulates_ q, in code `(p,q) in simulates`, iff
-        # 1) for every transition t from q to q' there is a transition t' from p to p' such
-        #    that t' simulates t and p' simulates q'.
-        # 2) for every final transition t from q there is a final transition t' from p such
-        #    that t' simulates t.
-        #
-        # Property: if p simulates q, then any path accepted from q is also accepted from p.
-        #           The converse does not need to hold.
-        #
-        # The simulation relation is reflexive and transitive but not necessarily symmetric.
-
-        # We begin with the Cartesian product of states and iteratively remove pairs
-        # whenever an argument against simulation is found.
-        simulates = {(p, q) for p in self.states for q in self.states}
-
-        # logger.debug("Initial simulation:")
-        # logger.debug(simulation_to_dict(simulates))
-
-        # First, we remove pairs where acceptance of empty paths is not simulated
-        remove_pairs = set()
-        for p in self.states:
-            for q in self.get_final_states():
-                if not simulate(self.get_final_transitions(p), self.get_final_transitions(q)):
-                    remove_pairs.add((p, q))
-
-        simulates -= remove_pairs
-
-        # logger.debug("Pairs removed due to final state simulation:")
-        # logger.debug(list(sorted(remove_pairs)))
-        # logger.debug("Simulation pairs after final state check:")
-        # logger.debug(simulation_to_dict(simulates))
-
-        # Next, we inspect the transitions between positions
-        while True:
-            remove_pairs = set()
-            for (p, q) in simulates:
-                for next_q in self.get_outbound_states(q):
-                    for t_q in self.get_edge_transitions(q, next_q):
-                        t_p_found = False
-                        for next_p in self.get_outbound_states(p):
-                            if (next_p, next_q) not in simulates:
-                                continue
-                            for t_p in self.get_edge_transitions(p, next_p):
-                                if t_p.simulates(t_q):
-                                    t_p_found = True
-                        if not t_p_found:
-                            remove_pairs.add((p, q))
-
-            # logger.debug("Pairs removed in transition check iteration:")
-            # logger.debug(list(sorted(remove_pairs)))
-            # logger.debug("Simulation pairs after transition check iteration:")
-            # logger.debug(simulation_to_dict(simulates))
-
-            if len(remove_pairs) == 0:
-                break
-
-            simulates -= remove_pairs
-
-
-        # At this point, the simulation relation is in `simulates`
-
-        # We identify redundant transitions using the simulation relation.
-
-        # A final node transition t1 from q is _redundant_ if there is a final node
-        # transition t2 != t1 from q such that t2 simulates t1. For final transitions, we do
-        # not need to worry about cycles because if t1 is redundant due to t2 and t2 is
-        # redundant due to t1, then t1 == t2.
-
-        redundant_final_transitions: Dict[int, Set[NodeTransition]] = dict()
-        for q in self.get_final_states():
-            for t in self.get_final_transitions(q):
-                for t2 in self.get_final_transitions(q):
-                    if t == t2:
-                        continue
-                    if t2.simulates(t):
-                        # logger.debug(f"Final transition {t} from {q} is redundant because simulated by {t2}")
-                        if q not in redundant_final_transitions:
-                            redundant_final_transitions[q] = set()
-                        redundant_final_transitions[q].add(t)
-
-        # logger.debug("Redundant final transitions:")
-        # logger.debug(final_transitions_to_dict(redundant_final_transitions))
-
-        # Detecting redundant edge transitions is more subtle because cycles are possible.
-
-        # An edge-transition t1 from p to q1 _subsumes_ (is more general than) a
-        # edge-transition t2 from p to q2 if t1 simulates t2, q1 simulates q2, and q1 != q2.
-        # In code `(t1, q1) in subsumes[p][(t2, q2)]`.
-
-        subsumes: Dict[int, Dict[Tuple[EdgeTransition, int], Set[Tuple[EdgeTransition, int]]]] = {
-            p: dict() for p in self.states
-        }
-
-        for q in self.states:
-            for q1 in self.get_outbound_states(q):
-                for t1 in self.get_edge_transitions(q, q1):
-                    for q2 in self.get_outbound_states(q):
-                        for t2 in self.get_edge_transitions(q, q2):
-                            if t1.simulates(t2) and (q1, q2) in simulates and q1 != q2:
-                                if (t2, q2) not in subsumes[q]:
-                                    subsumes[q][(t2, q2)] = set()
-                                subsumes[q][(t2, q2)].add((t1, q1))
-        # logger.debug("Subsumption:")
-        # logger.debug(subsumption_to_dict(subsumes))
-
-        # An edge-transition t2 from p to q2 is _redundant_ if
-        # 1) there is an edge-transition t1 from p such that t1 subsumes t2 but t2 does not
-        #    subsume t1.
-        # 2) there is an edge-transition t1 from p to q1 such that t1 subsumes t2 and t2
-        #    subsumes t1, but q1 > q2. (breaking subsumption cycles)
-        redundant_edge_transitions: Dict[Tuple[int,int], Set[EdgeTransition]]= dict()
-        for q in subsumes:
-            for (t2, q2) in subsumes[q]:
-                for (t1, q1) in subsumes[q][(t2, q2)]:
-                    if (t2, q2) not in subsumes[q].get((t1, q1), set()) or q1 > q2:
-                        if (q, q2) not in redundant_edge_transitions:
-                            redundant_edge_transitions[(q, q2)] = set()
-                        redundant_edge_transitions[(q, q2)].add(t2)
-
-        # logger.debug("Redundant edge transitions:")
-        # logger.debug(edge_transitions_to_dict(redundant_edge_transitions))
-
-        self.prune(redundant_edge_transitions=redundant_edge_transitions,
-                   redundant_final_transitions=redundant_final_transitions)
-
-        return len(redundant_edge_transitions) > 0 or len(redundant_final_transitions) > 0
-
-    # Trims the automaton by removing redundant states and transitions
-    def prune(self,
-              redundant_states: Set[int] = set(),
-              redundant_edge_transitions: Dict[Tuple[int,int], Set[EdgeTransition]] = dict(),
-              redundant_final_transitions: Dict[int, Set[NodeTransition]] = dict()):
-
-        states = self.states - redundant_states
-        init = self.init & states
-        delta = dict()
-        final = dict()
-
-        for q in states:
-            for p in states:
-                T = self.get_edge_transitions(q, p)
-                T = T - redundant_edge_transitions.get((q, p), set())
-                if len(T) > 0:
-                    if q not in delta:
-                        delta[q] = dict()
-                    delta[q][p] = T
-
-        for q in states:
-            T = self.get_final_transitions(q)
-            T = T - redundant_final_transitions.get(q, set())
-            if len(T) > 0:
-                final[q] = T
-
-        self.states = states
-        self.init = init
-        self.delta = delta
-        self.final = final
-
-
-#
-# Private functions for logging only
-#
-
-#
-# `logger` treats any dictionary as an event. To enable logging of arbitrary data
-# structures we convert them to dictionary but need to encapsulate them in a class that
-# implements `to_dict` method that ensures that the dictionary is not treated as an
-# event but emitted as a json fragment
-#
-class DictEncapsulation:
-    def __init__(self, d):
-        self.d = d
-
-    def to_dict(self):
-        return self.d
-
-    def __repr__(self):
-        return str(self.d)
-
-def simulation_to_dict(simulates: Set[Tuple[int, int]]):
-    d = dict()
-    for (p, q) in simulates:
-        if p not in d:
-            d[p] = list()
-        d[p].append(q)
-    for p in d:
-        d[p].sort()
-    return DictEncapsulation(d)
-
-def final_transitions_to_dict(final_transitions: Dict[int, Set[NodeTransition]]):
-    d = dict()
-    for q in final_transitions:
-        if len(final_transitions[q]) == 0:
-            continue
-        d[q] = [t.to_dict() for t in final_transitions[q]]
-    return DictEncapsulation(d)
-
-def subsumption_to_dict(subsumes: Dict[int, Dict[Tuple[EdgeTransition, int], Set[Tuple[EdgeTransition, int]]]]):
-    d = dict() # p -> [{'transition': t, 'to': q, 'subsumes': [{'transition': t0, 'to': q0}]}]
-
-    for p in subsumes:
-        if len(subsumes[p]) == 0:
-            continue
-        if p not in d:
-            d[p] = list()
-        for (t, q) in subsumes[p]:
-            for (t0, q0) in subsumes[p][(t, q)]:
-                d[p].append({
-                    'transition': t.to_dict(),
-                    'to': q,
-                    'subsumes': {
-                        'transition': t0.to_dict(),
-                        'to': q0
-                    }
-                })
-
-    return DictEncapsulation(d)
-
-
-def edge_transitions_to_dict(edge_transitions: Dict[Tuple[int,int], Set[EdgeTransition]]):
-    d = dict() # p -> q -> [t]
-
-    for (p, q) in edge_transitions:
-        if p not in d:
-            d[p] = dict()
-
-        if q not in d[p]:
-            d[p][q] = list()
-
-        for t in edge_transitions[(p, q)]:
-            d[p][q].append(t.to_dict())
-
-    return DictEncapsulation(d)
-
-def prepare_automaton(pattern, options) -> Automaton:
-    from .diagnostics import (
-        PathfinderSizeWarning,
-        PathfinderNonDeterminismWarning,
-        PathfinderVoidPatternError,
-        PathfinderUngroundedPatternError
-    )
-
-    force_transition_pruning = options.get('force_transition_pruning', False)
-
-    # logger.debug("Emitting PyRel for RPQ")
-    # logger.debug(pattern)
-
-    # Pattern compilation
-    g = pattern.glushkov()
-
-    # logger.debug(g)
-
-    a = g.automaton()
-
-    # logger.debug("Before reduction")
-    # logger.debug(a)
-    # logger.debug(f"Size: {len(a)}")
-    # logger.debug(f"Automaton is deterministic: {a.is_deterministic()}")
-
-    prune_states_only = len(pattern) >= 50
-    if force_transition_pruning:
-        prune_states_only = False
-    if len(pattern) >= 50:
-        warn(PathfinderSizeWarning(pattern, prune_states_only))
-
-    # Automaton reduction
-    # logger.debug(f"Prune states only: {prune_states_only}")
-    a.reduce(prune_states_only=prune_states_only)
-
-    # logger.debug("After reduction")
-    # logger.debug(a)
-    # logger.debug(f"Size: {len(a)}")
-    # logger.debug(f"Automaton is deterministic: {a.is_deterministic()}")
-
-    if not a.is_deterministic():
-        warn(PathfinderNonDeterminismWarning(pattern, a, prune_states_only))
-
-    if a.is_void():
-        raise PathfinderVoidPatternError(pattern)
-
-    if not options['suppress_groundedness_test'] and not a.is_grounded():
-        raise PathfinderUngroundedPatternError(pattern)
-
-    return a

relationalai/experimental/paths/rpq/diagnostics.py

@@ -1,56 +0,0 @@
-from relationalai.errors import RAIWarning, RAIException
-
-# -----------------------------------------------------------------------------------------
-# All User-facing diagnostic messages: Warnings and Errors
-# -----------------------------------------------------------------------------------------
-
-class PathfinderParameterWarning(RAIWarning):
-    def __init__(self, message: str):
-        super().__init__(message)
-
-class PathfinderSizeWarning(RAIWarning):
-    def __init__(self, pattern, prune_states_only: bool):
-        from .rpq import RPQ
-        assert isinstance(pattern, RPQ)
-
-        message = f"WARNING: RPQ pattern is prohibitively large {len(pattern)} >= 50"
-        if prune_states_only:
-            message += "\nSkipping transitions pruning"
-            message += "\nUse 'force_transition_pruning=True' to force transition pruning"
-        super().__init__(message)
-
-class PathfinderNonDeterminismWarning(RAIWarning):
-    def __init__(self, pattern, a, prune_states_only: bool):
-        from .rpq import RPQ
-        from .automaton import Automaton
-        assert isinstance(pattern, RPQ)
-        assert isinstance(a, Automaton)
-
-        message = "WARNING: RPQ pattern is non-deterministic\n"
-        if prune_states_only:
-            message += "Using 'force_transition_pruning=True' may solve this issue\n"
-        message += str(pattern)
-        message += "\n"
-        for reason in a.determinism_report():
-            message += " *" + reason + '\n'
-        message += "Pathfinder may return duplicate results"
-        super().__init__(message)
-
-class PathfinderUngroundedPatternError(RAIException):
-    def __init__(self, pattern):
-        from .rpq import RPQ
-        assert isinstance(pattern, RPQ)
-
-        message = "ERROR: Input RPQ pattern is ungrounded\n"
-        message += "Pattern potentially admits an infinite number of single-node paths\n"
-        message += str(pattern)
-        super().__init__(message)
-
-class PathfinderVoidPatternError(RAIException):
-    def __init__(self, pattern):
-        from .rpq import RPQ
-        assert isinstance(pattern, RPQ)
-
-        message = "ERROR: Input RPQ pattern is void (admits no paths)\n"
-        message += str(pattern)
-        super().__init__(message)