clean: Remove unused code and update docs

Author: vishnu-m77

docs/explanation/infrastructure.md

@@ -204,8 +204,38 @@ The fixed point rewriter transforms a pass by iteratively applying the pass till
 ///
 ///
 
-## Dataflow 
-`dataflow` defines a reusable forward dataflow analysis framework.
-
 ## Lattice
-`lattice` defines ordering and merge semantics used by analysis states. Use `LatticeBase` to model the state domain, then use `ForwardDataflowAnalysis` to run transfer and merge over a graph. This keeps transfer logic in the analysis class and ordering logic in the lattice class.
+
+The `Lattice` class in [`lattice.py`](../../src/oqd_compiler_infrastructure/lattice.py) defines a generic lattice interface with all the methods it requires. The following methods are defined:
+- top(): Returns the top element of the lattice.
+- bottom(): Returns the bottom element of the lattice.
+- leq(): Returns True if `t1 <= t2` in the lattice.
+- join(): Returns the least upper bound of `t1` and `t2`.
+- meet(): Returns the greatest lower bound of `t1` and `t2`.
+
+These methods allow analysis to be done on a concrete instance of the lattice. 
+
+The `LatticeBase` class defines a simple concrete implementation of a `Lattice`. It stores a dictionary that maps each node of the lattice to its immediate parent(s). It defines `LatticeTop` as the top element, and `LatticeBottom` as the bottom element of the lattice. This class defines the following helper methods:
+- is_class_node(t): Returns True if `t` is a valid lattice node.
+- add_node(t, parent): Adds a node to the lattice, by tracking the parent(s) of the node.
+- atomic_ancestors(t): Returns the atomic ancestors of a given node.
+
+These helper methods are used in the concrete implementation of the lattice operation methods: `leq`, `join`, and `meet`.
+
+You can define your own lattice using the `LatticeBase` class. 
+
+## Dataflow
+
+The `GraphProtocol` class in [`dataflow.py`](../../src/oqd_compiler_infrastructure/dataflow.py) defines a generic Graph Protocol interface that provides the nodes in the graph, the predecessors of a given node, and the successors of a given node. This protocol can be applied on any graph object for analysis: control flow graphs, dependency graphs, IR graphs, etc.
+
+The `DataflowAnalysis` class requires a Lattice to implement the analysis on. This class provides a dataflow analysis framework that can be used to implement a specific dataflow analysis The following methods are defined:
+- transfer(node, state_in): Returns the state of a given node after transfer.
+- bottom(): Returns the default starting state for all nodes.
+- merge(states): Joins incoming states using the lattice's join operation.
+- states_equal(t1, t2): Returns True if two states are equal in the lattice.
+
+The `ForwardDataflowAnalysis` class implements the forward dataflow analysis using the worklist algorithm with the `analyze` method. The output of the analysis is an instance of the `DataflowResult` class which contains the `in_states`, `out_states`, and the `iterations`.
+
+The `MapForwardDataflowAnalysis` is a helper instance of `ForwardDataflowAnalysis` for states that use a `dict[str, LatticeType]` type for analysis. 
+
+

src/oqd_compiler_infrastructure/dataflow.py

@@ -17,7 +17,6 @@
 from collections import deque
 from dataclasses import dataclass
 from typing import Generic, Iterable, TypeVar, Protocol
-
 from oqd_compiler_infrastructure.lattice import Lattice, LatticeType
 
 NodeType = TypeVar("NodeType")
@@ -66,10 +65,6 @@ def bottom(self) -> LatticeType:
         """Returns the default starting state for all nodes."""
         return self.lattice.bottom()
 
-    def boundary_state(self, node: NodeType) -> LatticeType:
-        """Returns the extra state injected at a given node."""
-        return self.bottom()
-
     def merge(self, states: Iterable[LatticeType]) -> LatticeType:
         """Joins incoming states using the lattice's join operation."""
         states_list = list(states)
@@ -88,7 +83,6 @@ def states_equal(self, t1: LatticeType, t2: LatticeType) -> bool:
 class ForwardDataflowAnalysis(DataflowAnalysis[NodeType, LatticeType], Generic[NodeType, LatticeType]):
     """
     Forward dataflow analysis framework.
-    This class implements the fixed point loop.
     """
     def __init__(self, lattice: Lattice[LatticeType]):
         super().__init__(lattice)
@@ -117,7 +111,7 @@ def analyze(self, graph: GraphProtocol[NodeType]) -> DataflowResult[NodeType, La
             iterations += 1
 
             pred_states = [out_states[pred] for pred in graph.predecessors(node)]
-            merged_input = self.merge([self.boundary_state(node), *pred_states])
+            merged_input = self.merge(pred_states)
 
             if not self.states_equal(in_states[node], merged_input):
                 in_states[node] = merged_input
@@ -137,23 +131,20 @@ def analyze(self, graph: GraphProtocol[NodeType]) -> DataflowResult[NodeType, La
 
 class MapForwardDataflowAnalysis(ForwardDataflowAnalysis[NodeType, dict[str, LatticeType]], Generic[NodeType, LatticeType]):
     """
-    Helper instance of ForwardDataflowAnalysis for states that need a dict Type
+    Helper instance of ForwardDataflowAnalysis for states that need a dict Type.
     """
     def __init__(self, lattice: Lattice[LatticeType]):
         super().__init__(lattice)
 
     def bottom(self) -> dict[str, LatticeType]:
         return {}
 
-    def boundary_state(self, node: NodeType) -> dict[str, LatticeType]:
-        return {}
-    
     def merge(self, states: Iterable[dict[str, LatticeType]]) -> dict[str, LatticeType]:
         states_list = list(states)
         if not states_list:
             return {}
 
-        bottom = self.lattice.bottom()
+        bottom = self.bottom()
         all_keys = set().union(*(state.keys() for state in states_list))
 
         merged = {}
@@ -166,7 +157,7 @@ def merge(self, states: Iterable[dict[str, LatticeType]]) -> dict[str, LatticeTy
         return merged
 
     def states_equal(self, t1: dict[str, LatticeType], t2: dict[str, LatticeType]) -> bool:
-        bottom = self.lattice.bottom()
+        bottom = self.bottom()
         all_keys = set(t1.keys()).union(t2.keys())
 
         for key in all_keys:

tests/test_dataflow.py

@@ -78,10 +78,10 @@ def test_reachability(self):
         )
         result = Reachability().analyze(graph)
 
-        assert result.in_states["entry"] == {"ENTRY"}
-        assert result.out_states["entry"] == {"ENTRY", "entry"}
-        assert result.out_states["mid"] == {"ENTRY", "entry", "mid"}
-        assert result.out_states["exit"] == {"ENTRY", "entry", "mid", "exit"}
+        assert result.in_states["entry"] == set()
+        assert result.out_states["entry"] == {"entry"}
+        assert result.out_states["mid"] == {"entry", "mid"}
+        assert result.out_states["exit"] == {"entry", "mid", "exit"}
         assert result.iterations >= 3