Skip to content

Commit bd19c99

Browse files
Update documentation
1 parent 1157cd0 commit bd19c99

4 files changed

Lines changed: 447 additions & 0 deletions

File tree

CITATIONS.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Research Citations
2+
3+
4+
5+
## Directed Feedback Arc Set
6+
**Title:** Computing a Feedback Arc Set Using PageRank
7+
**Authors:** Geladaris, Lionakis, and Tollis
8+
**Year:** 2023
9+
**Publication:** International Symposium on Graph Drawing and Network Visualization
10+
**Links:**
11+
https://arxiv.org/abs/2208.09234
12+
https://doi.org/10.1007/978-3-031-22203-0_14
13+
**Summary:** The new technique produces solutions that are better than the ones produced by the best previously known heuristics, often reducing the FAS size by more than 50%.
14+
15+
16+
## Directed Feedback Vertex Set
17+
**Title:** Wannabe Bounded Treewidth Graphs Admit a Polynomial Kernel for Directed Feedback Vertex Set
18+
**Authors:** Authors: Daniel Lokshtanov, Maadapuzhi-Sridharan Ramanujan, Saket Saurabh, Roohani Sharma, Meirav Zehavi
19+
**Year:** 2025
20+
**Publication:** ACM Transactions on Computation Theory, Volume 17, Issue 1
21+
**Links:** https://doi.org/10.1145/3711669
22+
23+
24+
## Tech Debt Prioritization
25+
**Title:** Prioritizing Design Debt Investment Opportunities
26+
**Authors:** Nico Zazworka, Carolyn Seaman, and Forrest Shull
27+
**Year:** 2011
28+
**Publication:** MTD '11: Proceedings of the 2nd Workshop on Managing Technical Debt
29+
**Links:** https://dl.acm.org/doi/10.1145/1985362.1985372

README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,25 @@ It scans your Git repository generates a single page application by runing:
1414
Code map viewers are powered by [3D Force Graph](https://vasturiano.github.io/3d-force-graph), [sigma.js](https://www.sigmajs.org/), and [GraphViz DOT](https://graphviz.org/docs/layouts/dot/)
1515
<br>If there are more than 4000 classes + relationships, a simplified 3D viewer will be used to avoid slowdowns. Features will be toggleable in the 3D UI in a future release.
1616

17+
## Decomposing and Removing Cycles
18+
Cutting-edge cycle analysis using [Directed Feedback Vertex Set](https://dl.acm.org/doi/10.1145/3711669) and [Directed Feedback Arc Set](https://arxiv.org/abs/2208.09234)
19+
algorithms are used to identify the most optimal classes and relationships in a codebase to remove cycles.
20+
These algorithms are powerful and will push your CPU to its limits for large codebases, though it does play nice and shouldn't slow your computer down.
21+
These graph algorithms can be used outside RefactorFirst.
22+
See [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/vertex/kernelized/DIAGRAM.md) for the flow of the vertex kernelized algorithm.
23+
See [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/arc/pageRank/DIAGRAM.md) for more details on the arc kernelized algorithm.
24+
25+
26+
### How to understand the Relationship Removal Priority table
27+
28+
The Relationship Removal Priority table shows the most optimal relationships to remove from your codebase to remove all cycles.
29+
The table is sorted by the number of cycles that a relationship exists in and then the change proneness of the clases in the relationship.
30+
- Classes that should be broken apart / removed from the codebase are bold.
31+
- If only one class is bold, the method(s) called by the non-bold class in the bold class should be moved to the non-bold class.
32+
- If both classes are bold, examine both classes and reassess the responsibilities of the classes and refactor to remove the relationship.
33+
- If neither class is bold, examine both classes determine how the relationship between the classes should be changed to remove the relationship.
34+
35+
1736
Take a look at the [Spring Petclinic REST project sample report](https://rawcdn.githack.com/refactorfirst/RefactorFirst/c46d26211a91ffbe08d4089e04a85ff31eb093c0/spring-petclinic-rest-report.html)!
1837

1938
The graphs generated in the report will look similar to this one:
Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# PageRank Feedback Arc Set (PageRankFAS) Algorithm
2+
3+
Based on the paper *"Computing a Feedback Arc Set Using PageRank"* by Geladaris, Lionakis, and Tollis ([arXiv:2208.09234](https://arxiv.org/abs/2208.09234)).
4+
5+
## High-Level Algorithm Flow
6+
7+
```mermaid
8+
flowchart TD
9+
A["**Input:** Directed Graph G(V, E)"] --> B["Copy graph into<br/>working graph G'"]
10+
B --> C{"Does G'<br/>have cycles?"}
11+
C -- No --> D["**Output:** Feedback Arc Set<br/>(set of removed edges)"]
12+
C -- Yes --> E["Find Strongly Connected<br/>Components (SCCs)<br/>using Kosaraju's algorithm"]
13+
E --> F["Filter to non-trivial SCCs<br/>(size > 1)"]
14+
F --> G["Process each SCC"]
15+
G --> H["Extract subgraph<br/>for this SCC"]
16+
H --> I["Build Line Digraph L(G)<br/>from SCC subgraph"]
17+
I --> J["Run PageRank<br/>on Line Digraph"]
18+
J --> K["Select edge with<br/>highest PageRank score"]
19+
K --> L["Remove edge from G'<br/>and add to FAS"]
20+
L --> C
21+
```
22+
23+
## Line Digraph Construction
24+
25+
Each edge in the original graph becomes a **vertex** in the line digraph. Edges in the line digraph represent adjacency (consecutive traversal) in the original graph.
26+
27+
```mermaid
28+
flowchart TD
29+
subgraph Original["**Original SCC Subgraph**"]
30+
direction LR
31+
oA((A)) -->|e1| oB((B))
32+
oB -->|e2| oC((C))
33+
oC -->|e3| oA
34+
oA -->|e4| oC
35+
end
36+
37+
Original --> Transform["Transform: each original edge<br/>becomes a line digraph vertex"]
38+
39+
subgraph Line["**Line Digraph L(G)**"]
40+
direction LR
41+
le1["e1 (A→B)"] -->|"B is source of e2"| le2["e2 (B→C)"]
42+
le2 -->|"C is source of e3"| le3["e3 (C→A)"]
43+
le2 -->|"C is source of... none extra"| le2x[ ]
44+
le3 -->|"A is source of e1"| le1
45+
le3 -->|"A is source of e4"| le4["e4 (A→C)"]
46+
le4 -->|"C is source of e3"| le3
47+
le1 -.-> le4x[ ]
48+
end
49+
50+
style le2x display:none
51+
style le4x display:none
52+
```
53+
54+
## Line Digraph Edge Creation (DFS-Based — Algorithm 3)
55+
56+
```mermaid
57+
flowchart TD
58+
S["Start DFS from<br/>arbitrary vertex v₀"] --> V["Visit vertex v,<br/>mark as visited"]
59+
V --> OE["For each outgoing<br/>edge e of v"]
60+
OE --> LV["Get LineVertex<br/>for edge e"]
61+
LV --> PREV{"Previous<br/>LineVertex<br/>exists?"}
62+
PREV -- Yes --> ADD_EDGE["Add edge:<br/>prevLineVertex → currentLineVertex<br/>in Line Digraph"]
63+
PREV -- No --> CHECK
64+
ADD_EDGE --> CHECK{"Target of e<br/>already visited?"}
65+
CHECK -- No --> REC["Recurse DFS on target<br/>with currentLineVertex as prev"]
66+
CHECK -- Yes --> BACK["Add edges from currentLineVertex<br/>to all LineVertices of<br/>target's outgoing edges<br/>(back-edge handling)"]
67+
REC --> OE
68+
BACK --> OE
69+
```
70+
71+
## PageRank Computation (Algorithm 4)
72+
73+
```mermaid
74+
flowchart TD
75+
INIT["Initialize all LineVertex scores<br/>score(v) = 1 / N"] --> ITER{"Iteration<br/>i < maxIterations?"}
76+
ITER -- No --> RESULT["Return PageRank scores<br/>for all LineVertices"]
77+
ITER -- Yes --> NEWMAP["Create new score map<br/>(all zeros)"]
78+
NEWMAP --> EACH["For each LineVertex v<br/>(in parallel)"]
79+
EACH --> SINK{"v has outgoing<br/>neighbors?"}
80+
SINK -- "No (sink)" --> SELF["newScore(v) += score(v)<br/>(keep score on itself)"]
81+
SINK -- Yes --> DIST["Distribute score(v) equally<br/>among outgoing neighbors:<br/>each gets score(v) / outDegree(v)"]
82+
DIST --> MERGE["newScore(target) += share<br/>using atomic merge"]
83+
SELF --> SWAP
84+
MERGE --> SWAP["Swap: currentScores = newScores"]
85+
SWAP --> ITER
86+
```
87+
88+
## Selecting the Feedback Edge
89+
90+
```mermaid
91+
flowchart LR
92+
PR["PageRank scores<br/>on Line Digraph"] --> MAX["Find LineVertex with<br/>**maximum** PageRank score"]
93+
MAX --> ORIG["Map back to<br/>original edge via<br/>LineVertex.getOriginalEdge()"]
94+
ORIG --> REMOVE["Remove edge from<br/>working graph &<br/>add to FAS"]
95+
```
96+
97+
## Class Relationships
98+
99+
```mermaid
100+
classDiagram
101+
class PageRankFAS~V, E~ {
102+
-Graph originalGraph
103+
-int pageRankIterations
104+
-Class edgeClass
105+
+computeFeedbackArcSet() Set~E~
106+
-processStronglyConnectedComponent(graph, scc) E
107+
-createLineDigraph(graph) LineDigraph
108+
-createLineDigraphEdges(graph, lineDigraph, map)
109+
-createLineDigraphEdgesDFS(graph, lineDigraph, map, vertex, prev, visited)
110+
-computePageRank(lineDigraph) Map
111+
-applyOneIteration(vertices, lineDigraph, current, new)
112+
-findStronglyConnectedComponents(graph) List
113+
-hasCycles(graph) boolean
114+
-createGraphCopy(original) Graph
115+
-createSubgraph(graph, vertices) Graph
116+
}
117+
118+
class LineDigraph~V, E~ {
119+
-Set vertices
120+
-Map adjacencyMap
121+
-Map incomingMap
122+
+addVertex(vertex) boolean
123+
+addEdge(source, target) boolean
124+
+vertexSet() Set
125+
+getOutgoingNeighbors(vertex) Set
126+
+getIncomingNeighbors(vertex) Set
127+
}
128+
129+
class LineVertex~V, E~ {
130+
-V source
131+
-V target
132+
-E originalEdge
133+
+getSource() V
134+
+getTarget() V
135+
+getOriginalEdge() E
136+
}
137+
138+
PageRankFAS --> LineDigraph : creates
139+
PageRankFAS --> LineVertex : creates
140+
LineDigraph o-- LineVertex : contains
141+
```

0 commit comments

Comments
 (0)