Added jupyter notebook integration and new visualization

automata/base/automaton.py

@@ -4,7 +4,6 @@
 import abc
 from typing import AbstractSet, Any, Dict, Generator, Mapping, NoReturn, Tuple
 
-from frozendict import frozendict
 from typing_extensions import Self
 
 import automata.base.config as global_config
@@ -124,29 +123,10 @@ def copy(self) -> Self:
         """Create a deep copy of the automaton."""
         return self.__class__(**self.input_parameters)
 
-    # Format the given value for string output via repr() or str(); this exists
-    # for the purpose of displaying
-
-    def _get_repr_friendly_value(self, value: Any) -> Any:
-        """
-        A helper function to convert the given value / structure into a fully
-        mutable one by recursively processing said structure and any of its
-        members, unfreezing them along the way
-        """
-        if isinstance(value, frozenset):
-            return {self._get_repr_friendly_value(element) for element in value}
-        elif isinstance(value, frozendict):
-            return {
-                dict_key: self._get_repr_friendly_value(dict_value)
-                for dict_key, dict_value in value.items()
-            }
-        else:
-            return value
-
     def __repr__(self) -> str:
         """Return a string representation of the automaton."""
         values = ", ".join(
-            f"{attr_name}={self._get_repr_friendly_value(attr_value)!r}"
+            f"{attr_name}={attr_value!r}"
             for attr_name, attr_value in self.input_parameters.items()
         )
         return f"{self.__class__.__qualname__}({values})"

automata/fa/dfa.py

@@ -17,18 +17,15 @@
     Iterable,
     Iterator,
     List,
-    Literal,
     Mapping,
     Optional,
     Set,
     Tuple,
     Type,
-    TypeVar,
     cast,
 )
 
 import networkx as nx
-from pydot import Dot, Edge, Node
 from typing_extensions import Self
 
 import automata.base.exceptions as exceptions
@@ -332,7 +329,7 @@ def minify(self, retain_names: bool = False) -> Self:
         Create a minimal DFA which accepts the same inputs as this DFA.
 
         First, non-reachable states are removed.
-        Then, similiar states are merged using Hopcroft's Algorithm.
+        Then, similar states are merged using Hopcroft's Algorithm.
             retain_names: If True, merged states retain names.
                           If False, new states will be named 0, ..., n-1.
         """
@@ -1553,38 +1550,48 @@ def get_name_original(states: FrozenSet[DFAStateT]) -> DFAStateT:
             final_states=dfa_final_states,
         )
 
-    def show_diagram(self, path=None):
+    def iter_states(self):
+        return iter(self.states)
+
+    def iter_transitions(self):
+        return (
+            (from_, to_, symbol)
+            for from_, lookup in self.transitions.items()
+            for symbol, to_ in lookup.items()
+        )
+
+    def is_accepting(self, state):
+        return state in self.final_states
+
+    def is_initial(self, state):
+        return state == self.initial_state
+
+    def _get_input_path(
+        self, input_str
+    ) -> tuple[list[tuple[DFAStateT, DFAStateT, DFASymbolT], bool]]:
         """
-        Creates the graph associated with this DFA
+        Calculate the path taken by input.
+
+        Args:
+            input_str (str): The input string to run on the DFA.
+
+        Returns:
+            tuple[list[tuple[DFAStateT, DFAStateT, DFASymbolT], bool]]: A list
+            of all transitions taken in each step and a boolean indicating
+            whether the DFA accepted the input.
+
         """
-        # Nodes are set of states
+        state_history = [
+            state
+            for state in self.read_input_stepwise(input_str, ignore_rejection=True)
+        ]
 
-        graph = Dot(graph_type="digraph", rankdir="LR")
-        nodes = {}
-        for state in self.states:
-            if state == self.initial_state:
-                # color start state with green
-                if state in self.final_states:
-                    initial_state_node = Node(
-                        state, style="filled", peripheries=2, fillcolor="#66cc33"
-                    )
-                else:
-                    initial_state_node = Node(
-                        state, style="filled", fillcolor="#66cc33"
-                    )
-                nodes[state] = initial_state_node
-                graph.add_node(initial_state_node)
-            else:
-                if state in self.final_states:
-                    state_node = Node(state, peripheries=2)
-                else:
-                    state_node = Node(state)
-                nodes[state] = state_node
-                graph.add_node(state_node)
-        # adding edges
-        for from_state, lookup in self.transitions.items():
-            for to_label, to_state in lookup.items():
-                graph.add_edge(Edge(nodes[from_state], nodes[to_state], label=to_label))
-        if path:
-            graph.write_png(path)
-        return graph
+        path = [
+            transition
+            for transition in zip(state_history, state_history[1:], input_str)
+        ]
+
+        last_state = state_history[-1] if state_history else self.initial_state
+        accepted = last_state in self.final_states
+
+        return path, accepted

automata/fa/fa.py

@@ -1,7 +1,15 @@
 #!/usr/bin/env python3
 """Classes and methods for working with all finite automata."""
-
 import abc
+import os
+import pathlib
+import typing
+import uuid
+from collections import defaultdict
+from typing import Any, Iterable
+
+import graphviz
+from coloraide import Color
 
 from automata.base.automaton import Automaton, AutomatonStateT
 
@@ -12,3 +20,217 @@ class FA(Automaton, metaclass=abc.ABCMeta):
     """An abstract base class for finite automata."""
 
     __slots__ = tuple()
+
+    @staticmethod
+    def get_state_name(state_data: FAStateT) -> str:
+        """
+        Get an string representation of a state. This is used for displaying and
+        uses `str` for any unsupported python data types.
+        """
+        if isinstance(state_data, str):
+            if state_data == "":
+                return "λ"
+
+            return state_data
+
+        if isinstance(state_data, (set, frozenset, list, tuple)):
+            inner = ", ".join(FA.get_state_name(sub_data) for sub_data in state_data)
+            if isinstance(state_data, (set, frozenset)):
+                if state_data:
+                    return "{" + inner + "}"
+                else:
+                    return "∅"
+
+            if isinstance(state_data, tuple):
+                return "(" + inner + ")"
+
+            if isinstance(state_data, list):
+                return "[" + inner + "]"
+
+        return str(state_data)
+
+    def get_edge_name(self, symbol) -> str:
+        return str(symbol)
+
+    @abc.abstractmethod
+    def iter_states(self) -> Iterable[FAStateT]:
+        """Iterate over all states in the automaton."""
+
+    @abc.abstractmethod
+    def iter_transitions(self) -> Iterable[tuple[FAStateT, FAStateT, Any]]:
+        """
+        Iterate over all transitions in the automaton. Each transition is a tuple
+        of the form (from_state, to_state, symbol)
+        """
+
+    @abc.abstractmethod
+    def is_accepting(self, state: FAStateT) -> bool:
+        """Check if a state is an accepting state."""
+
+    @abc.abstractmethod
+    def is_initial(self, state: FAStateT) -> bool:
+        """Check if a state is an initial state."""
+
+    def show_diagram(
+        self,
+        input_str: str | None = None,
+        save_path: str | os.PathLike | None = None,
+        *,
+        engine: typing.Optional[str] = None,
+        view=False,
+        cleanup: bool = True,
+        horizontal: bool = True,
+        reverse_orientation: bool = False,
+        fig_size: tuple = None,
+        font_size: float = 14.0,
+        arrow_size: float = 0.85,
+        state_separation: float = 0.5,
+    ):
+        """
+        Generates the graph associated with the given DFA.
+        Args:
+            input_str (str, optional): String list of input symbols. Defaults to None.
+            - save_path (str or os.PathLike, optional): Path to output file. If
+              None, the output will not be saved.
+            - path (str, optional): Folder path for output file. Defaults to
+              None.
+            - view (bool, optional): Storing and displaying the graph as a pdf.
+              Defaults to False.
+            - cleanup (bool, optional): Garbage collection. Defaults to True.
+              horizontal (bool, optional): Direction of node layout. Defaults
+              to True.
+            - reverse_orientation (bool, optional): Reverse direction of node
+              layout. Defaults to False.
+            - fig_size (tuple, optional): Figure size. Defaults to None.
+            - font_size (float, optional): Font size. Defaults to 14.0.
+            - arrow_size (float, optional): Arrow head size. Defaults to 0.85.
+            - state_separation (float, optional): Node distance. Defaults to 0
+              5.
+        Returns:
+            Digraph: The graph in dot format.
+        """
+
+        # Defining the graph.
+        graph = graphviz.Digraph(strict=False, engine=engine)
+
+        # TODO test fig_size
+        if fig_size is not None:
+            graph.attr(size=", ".join(map(str, fig_size)))
+
+        graph.attr(ranksep=str(state_separation))
+        font_size = str(font_size)
+        arrow_size = str(arrow_size)
+
+        if horizontal:
+            graph.attr(rankdir="LR")
+        if reverse_orientation:
+            if horizontal:
+                graph.attr(rankdir="RL")
+            else:
+                graph.attr(rankdir="BT")
+
+        for state in self.iter_states():
+            # every edge needs an origin node, so we add a null node for every
+            # initial state.
+            if self.is_initial(state):
+                # we use a random uuid to make sure that the null node has a
+                # unique id to avoid colliding with other states and null_nodes.
+                null_node = str(uuid.uuid4())
+                graph.node(
+                    null_node,
+                    label="",
+                    tooltip=".",
+                    shape="point",
+                    fontsize=font_size,
+                )
+                node = self.get_state_name(state)
+                graph.edge(
+                    null_node,
+                    node,
+                    tooltip="->" + node,
+                    arrowsize=arrow_size,
+                )
+
+        for state in self.iter_states():
+            shape = "doublecircle" if self.is_accepting(state) else "circle"
+            node = self.get_state_name(state)
+            graph.node(node, shape=shape, fontsize=font_size)
+
+        is_edge_drawn = defaultdict(lambda: False)
+        if input_str is not None:
+            path, is_accepted = self._get_input_path(input_str=input_str)
+
+            start_color = Color("#ff0")
+            end_color = Color("#0f0") if is_accepted else Color("#f00")
+            interpolation = Color.interpolate([start_color, end_color], space="srgb")
+
+            # find all transitions in the finite state machine with traversal.
+            for transition_index, (from_state, to_state, symbol) in enumerate(
+                path, start=1
+            ):
+                color = interpolation(transition_index / len(path))
+                label = self.get_edge_name(symbol)
+
+                is_edge_drawn[from_state, to_state, symbol] = True
+                graph.edge(
+                    self.get_state_name(from_state),
+                    self.get_state_name(to_state),
+                    label=f"<{label} <b>[<i>#{transition_index}</i>]</b>>",
+                    arrowsize=arrow_size,
+                    fontsize=font_size,
+                    color=color.to_string(hex=True),
+                    penwidth="2.5",
+                )
+
+        edge_labels = defaultdict(list)
+        for from_state, to_state, symbol in self.iter_transitions():
+            if is_edge_drawn[from_state, to_state, symbol]:
+                continue
+
+            from_node = self.get_state_name(from_state)
+            to_node = self.get_state_name(to_state)
+            label = self.get_edge_name(symbol)
+            edge_labels[from_node, to_node].append(label)
+
+        for (from_node, to_node), labels in edge_labels.items():
+            graph.edge(
+                from_node,
+                to_node,
+                label=",".join(sorted(labels)),
+                arrowsize=arrow_size,
+                fontsize=font_size,
+            )
+
+        # Write diagram to file. PNG, SVG, etc.
+        if save_path is not None:
+            save_path: pathlib.Path = pathlib.Path(save_path)
+
+            directory = save_path.parent
+            directory.mkdir(parents=True, exist_ok=True)
+            filename = save_path.stem
+            format = save_path.suffix.split(".")[1] if save_path.suffix else None
+
+            graph.render(
+                directory=directory,
+                filename=filename,
+                format=format,
+                cleanup=cleanup,
+                view=view,
+            )
+
+        return graph
+
+    def _get_input_path(self, input_str):
+        """Calculate the path taken by input."""
+
+        raise NotImplementedError(
+            f"_get_input_path is not implemented for {self.__class__}"
+        )
+
+    def _ipython_display_(self):
+        # IPython is imported here because this function is only called by
+        # IPython. So if IPython is not installed, this function will not be
+        # called, therefore no need to add ipython as dependency.
+        from IPython.display import display
+
+        display(self.show_diagram())