Add CSE pass description in doxygen documentation (#4504)

* Add CSE pass description

* Edits

* Review comments
Co-authored-by: Scott Cyphers <diyessi@users.noreply.github.com>
Co-authored-by: Scott Cyphers <scott.cyphers@intel.com>
Co-authored-by: Robert Kimball <robert.kimball@intel.com>

doc/doxygen/images/add_commutative_postcse.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: ngraph Pages: 1 -->
+<svg width="198pt" height="218pt"
+ viewBox="0.00 0.00 198.00 218.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 214)">
+<title>ngraph</title>
+<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-214 194,-214 194,4 -4,4"/>
+<!-- Add_3 -->
+<g id="node1" class="node">
+<title>Add_3</title>
+<polygon fill="none" stroke="#000000" points="131.5,-123 58.5,-123 58.5,-87 131.5,-87 131.5,-123"/>
+<text text-anchor="middle" x="95" y="-101.3" font-family="Times,serif" font-size="14.00" fill="#000000">Add_3 [0]</text>
+</g>
+<!-- Result_5 -->
+<g id="node2" class="node">
+<title>Result_5</title>
+<polygon fill="none" stroke="#dc143c" stroke-width="1.5" points="86,-36 2,-36 2,0 86,0 86,-36"/>
+<text text-anchor="middle" x="44" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">Result_5 [0]</text>
+</g>
+<!-- Add_3&#45;&gt;Result_5 -->
+<g id="edge1" class="edge">
+<title>Add_3&#45;&gt;Result_5</title>
+<path fill="none" stroke="#000000" d="M84.4328,-86.9735C77.3211,-74.8418 67.8168,-58.6287 59.8099,-44.9698"/>
+<polygon fill="#000000" stroke="#000000" points="62.6304,-42.8603 54.5537,-36.0034 56.5915,-46.4004 62.6304,-42.8603"/>
+<text text-anchor="middle" x="94" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- Result_4 -->
+<g id="node5" class="node">
+<title>Result_4</title>
+<polygon fill="none" stroke="#dc143c" stroke-width="1.5" points="188,-36 104,-36 104,0 188,0 188,-36"/>
+<text text-anchor="middle" x="146" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">Result_4 [0]</text>
+</g>
+<!-- Add_3&#45;&gt;Result_4 -->
+<g id="edge4" class="edge">
+<title>Add_3&#45;&gt;Result_4</title>
+<path fill="none" stroke="#000000" d="M107.5732,-86.9153C111.3675,-81.2554 115.4621,-74.9364 119,-69 123.5215,-61.4133 128.1307,-53.0039 132.231,-45.2381"/>
+<polygon fill="#000000" stroke="#000000" points="135.4312,-46.6702 136.9401,-36.1833 129.2209,-43.4404 135.4312,-46.6702"/>
+<text text-anchor="middle" x="147" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_0 -->
+<g id="node3" class="node">
+<title>CLONE_0</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="86,-210 0,-210 0,-174 86,-174 86,-210"/>
+<text text-anchor="middle" x="43" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_1</text>
+</g>
+<!-- CLONE_0&#45;&gt;Add_3 -->
+<g id="edge2" class="edge">
+<title>CLONE_0&#45;&gt;Add_3</title>
+<path fill="none" stroke="#000000" d="M53.7744,-173.9735C61.0256,-161.8418 70.7162,-145.6287 78.8801,-131.9698"/>
+<polygon fill="#000000" stroke="#000000" points="82.1132,-133.3827 84.2394,-123.0034 76.1046,-129.7913 82.1132,-133.3827"/>
+<text text-anchor="middle" x="94" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_1 -->
+<g id="node4" class="node">
+<title>CLONE_1</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="190,-210 104,-210 104,-174 190,-174 190,-210"/>
+<text text-anchor="middle" x="147" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_0</text>
+</g>
+<!-- CLONE_1&#45;&gt;Add_3 -->
+<g id="edge3" class="edge">
+<title>CLONE_1&#45;&gt;Add_3</title>
+<path fill="none" stroke="#000000" d="M137.5234,-173.8476C132.266,-164.0105 125.4937,-151.7102 119,-141 117.1526,-137.953 115.1657,-134.7991 113.1546,-131.6826"/>
+<polygon fill="#000000" stroke="#000000" points="115.9391,-129.547 107.5178,-123.118 110.0919,-133.3954 115.9391,-129.547"/>
+<text text-anchor="middle" x="148" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 1 </text>
+</g>
+</g>
+</svg>

doc/doxygen/images/add_commutative_precse.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: ngraph Pages: 1 -->
+<svg width="406pt" height="218pt"
+ viewBox="0.00 0.00 406.00 218.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 214)">
+<title>ngraph</title>
+<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-214 402,-214 402,4 -4,4"/>
+<!-- Add_3 -->
+<g id="node1" class="node">
+<title>Add_3</title>
+<polygon fill="none" stroke="#000000" points="131.5,-123 58.5,-123 58.5,-87 131.5,-87 131.5,-123"/>
+<text text-anchor="middle" x="95" y="-101.3" font-family="Times,serif" font-size="14.00" fill="#000000">Add_3 [0]</text>
+</g>
+<!-- Result_5 -->
+<g id="node2" class="node">
+<title>Result_5</title>
+<polygon fill="none" stroke="#dc143c" stroke-width="1.5" points="137,-36 53,-36 53,0 137,0 137,-36"/>
+<text text-anchor="middle" x="95" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">Result_5 [0]</text>
+</g>
+<!-- Add_3&#45;&gt;Result_5 -->
+<g id="edge1" class="edge">
+<title>Add_3&#45;&gt;Result_5</title>
+<path fill="none" stroke="#000000" d="M95,-86.9735C95,-75.1918 95,-59.5607 95,-46.1581"/>
+<polygon fill="#000000" stroke="#000000" points="98.5001,-46.0033 95,-36.0034 91.5001,-46.0034 98.5001,-46.0033"/>
+<text text-anchor="middle" x="116" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_0 -->
+<g id="node3" class="node">
+<title>CLONE_0</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="86,-210 0,-210 0,-174 86,-174 86,-210"/>
+<text text-anchor="middle" x="43" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_1</text>
+</g>
+<!-- CLONE_0&#45;&gt;Add_3 -->
+<g id="edge2" class="edge">
+<title>CLONE_0&#45;&gt;Add_3</title>
+<path fill="none" stroke="#000000" d="M53.7744,-173.9735C61.0256,-161.8418 70.7162,-145.6287 78.8801,-131.9698"/>
+<polygon fill="#000000" stroke="#000000" points="82.1132,-133.3827 84.2394,-123.0034 76.1046,-129.7913 82.1132,-133.3827"/>
+<text text-anchor="middle" x="94" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_1 -->
+<g id="node4" class="node">
+<title>CLONE_1</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="190,-210 104,-210 104,-174 190,-174 190,-210"/>
+<text text-anchor="middle" x="147" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_0</text>
+</g>
+<!-- CLONE_1&#45;&gt;Add_3 -->
+<g id="edge3" class="edge">
+<title>CLONE_1&#45;&gt;Add_3</title>
+<path fill="none" stroke="#000000" d="M137.5234,-173.8476C132.266,-164.0105 125.4937,-151.7102 119,-141 117.1526,-137.953 115.1657,-134.7991 113.1546,-131.6826"/>
+<polygon fill="#000000" stroke="#000000" points="115.9391,-129.547 107.5178,-123.118 110.0919,-133.3954 115.9391,-129.547"/>
+<text text-anchor="middle" x="149" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 1 </text>
+</g>
+<!-- Add_2 -->
+<g id="node5" class="node">
+<title>Add_2</title>
+<polygon fill="none" stroke="#000000" points="339.5,-123 266.5,-123 266.5,-87 339.5,-87 339.5,-123"/>
+<text text-anchor="middle" x="303" y="-101.3" font-family="Times,serif" font-size="14.00" fill="#000000">Add_2 [0]</text>
+</g>
+<!-- Result_4 -->
+<g id="node6" class="node">
+<title>Result_4</title>
+<polygon fill="none" stroke="#dc143c" stroke-width="1.5" points="345,-36 261,-36 261,0 345,0 345,-36"/>
+<text text-anchor="middle" x="303" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">Result_4 [0]</text>
+</g>
+<!-- Add_2&#45;&gt;Result_4 -->
+<g id="edge4" class="edge">
+<title>Add_2&#45;&gt;Result_4</title>
+<path fill="none" stroke="#000000" d="M303,-86.9735C303,-75.1918 303,-59.5607 303,-46.1581"/>
+<polygon fill="#000000" stroke="#000000" points="306.5001,-46.0033 303,-36.0034 299.5001,-46.0034 306.5001,-46.0033"/>
+<text text-anchor="middle" x="324" y="-57.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_2 -->
+<g id="node7" class="node">
+<title>CLONE_2</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="294,-210 208,-210 208,-174 294,-174 294,-210"/>
+<text text-anchor="middle" x="251" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_0</text>
+</g>
+<!-- CLONE_2&#45;&gt;Add_2 -->
+<g id="edge5" class="edge">
+<title>CLONE_2&#45;&gt;Add_2</title>
+<path fill="none" stroke="#000000" d="M261.7744,-173.9735C269.0256,-161.8418 278.7162,-145.6287 286.8801,-131.9698"/>
+<polygon fill="#000000" stroke="#000000" points="290.1132,-133.3827 292.2394,-123.0034 284.1046,-129.7913 290.1132,-133.3827"/>
+<text text-anchor="middle" x="301" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 0 </text>
+</g>
+<!-- CLONE_3 -->
+<g id="node8" class="node">
+<title>CLONE_3</title>
+<polygon fill="#ffffff" stroke="#0000ff" stroke-dasharray="5,2" points="398,-210 312,-210 312,-174 398,-174 398,-210"/>
+<text text-anchor="middle" x="355" y="-188.3" font-family="Times,serif" font-size="14.00" fill="#000000">Parameter_1</text>
+</g>
+<!-- CLONE_3&#45;&gt;Add_2 -->
+<g id="edge6" class="edge">
+<title>CLONE_3&#45;&gt;Add_2</title>
+<path fill="none" stroke="#000000" d="M345.0238,-173.931C339.5314,-164.1183 332.5236,-151.8148 326,-141 324.1827,-137.9874 322.2492,-134.8551 320.3049,-131.751"/>
+<polygon fill="#000000" stroke="#000000" points="323.1945,-129.7722 314.8844,-123.2 317.2823,-133.52 323.1945,-129.7722"/>
+<text text-anchor="middle" x="355" y="-144.8" font-family="Times,serif" font-size="14.00" fill="#000000"> 0 &#45;&gt; 1 </text>
+</g>
+</g>
+</svg>

src/ngraph/pass/cse.cpp

@@ -167,6 +167,9 @@ static bool cse_one_hot(shared_ptr<Node> a, shared_ptr<Node> b)
            (a->get_shape() == b->get_shape());
 }
 
+// To enable CSE for a new op, add a mapping between the op and a cse handler function to the map
+// below. If the op doesn't map to an existing handler, create a new handler to check if
+// all inputs and attributes for two nodes are exactly same.
 static unordered_map<type_index, function<bool(shared_ptr<Node>, shared_ptr<Node>)>>
     initialize_ops_to_cse_handlers()
 {

src/ngraph/pass/cse.hpp

@@ -26,6 +26,23 @@ namespace ngraph
     }
 }
 
+/// \brief The Common Subexpression Elimination pass removes duplicate computations in a given
+/// computation graph.
+///
+/// Two computations are considered to be duplicates of each other if both apply the same operation
+/// to the same set of inputs, with the same attributes.
+///
+/// In the example shown below, the original graph has duplicate Add computations.
+/// After applying this pass, the graph is optimized to have only one Add computation.
+/// <table>
+/// <tr><th>Before the pass:</th>
+///      <th> After the pass</th>
+/// </tr>
+/// <tr>
+///      <td> \image html add_commutative_precse.svg </td>
+///      <td> \image html add_commutative_postcse.svg </td>
+/// </tr>
+/// </table>
 class NGRAPH_API ngraph::pass::CommonSubexpressionElimination : public FunctionPass
 {
 public: