Updated documentation

src/lay/lay/doc/manual/lvs.xml

@@ -19,13 +19,7 @@
     <topic href="/manual/lvs_io.xml"/>
     <topic href="/manual/lvs_connect.xml"/>
     <topic href="/manual/lvs_compare.xml"/>
-
-    <!--
-    <topic href="/manual/lvs_hierarchy.xml"/>
-    <topic href="/manual/lvs_reference.xml"/>
     <topic href="/manual/lvs_tweaks.xml"/>
-    <topic href="/manual/lvs_browser.xml"/>
-    -->
   </topics>
 
   <p>A reference for the functions and objects available for LVS scripts can be found here: <link href="/about/lvs_ref.xml"/>.</p>

src/lay/lay/doc/manual/lvs_compare.xml

@@ -65,6 +65,11 @@
 
   <pre>same_circuits("CIRCUIT_IN_LAYOUT", "CIRCUIT_IN_SCHEMATIC")</pre>
 
+  <p>
+  Declaring circuits as 'same' means they will still be compared. The function is just
+  a hint where to look for the compare target.
+  </p>
+
   <h2>Device class equivalence hint</h2>
 
   <p>
@@ -120,4 +125,60 @@ same_device_classes("NMOS_IN_LAYOUT", "NMOS_IN_SCHEMATIC")</pre>
 
   <pre>max_caps(1e-16)</pre>
 
+  <h2>How the compare algorithm works</h2>
+
+  <p>
+  The coarse flow of the netlist compare algorithm is this:
+  </p>
+
+  <pre>foreach circuit bottom up:
+  if matching circuit found in reference netlist:
+    if all subcircuits have been matched and pin matching has been established for them:
+      compare net graph locally from this circuit
+    else:
+      skip circuit with warning
+  else:
+    issue a circuit mismatch error</pre>
+
+  <p>
+  A consequence of this flow is that the compare will stop treating parent circuits when 
+  one circuit's pins can't be matched to pins from the corresponding reference circuit
+  or the corresponding circuit can't be found in the reference netlist. This behaviour 
+  fosters a bottom-up debugging approach: first fix the issues in subcircuits, then
+  proceed to the parent circuits.
+  </p>
+
+  <p>
+  The local net graph compare algorithm is a backtracking algorithm with 
+  hinting through topological net classification. Topological net classification 
+  is based on nearest-net neighborhood. The following image illustrates this:
+  </p>
+
+  <p>
+  <img src="/manual/net_graph.png"/>
+  </p>
+
+  <p>
+  Here the IN net's neighborhood is VDD via a traversal of gate to source/drain 
+  over M1, to OUT via a twofold traversal of gate to source/drain over M1 and M2 
+  and to VSS via another single traversal of gate to source/drain over M2.
+  This uniquely identifies IN in this simple circuit. In effect, OUT, VDD and VSS
+  can be identified uniquely because their transitions from the IN net are 
+  unambigously identifying them. The topological neighborhood is a simple metrics
+  which allows identifying matching nets from two netlists and deducing further relations.
+  </p>
+
+  <p>
+  In big netlists, the algorithm will first try to match nets unambigously according 
+  to their neighborhood metrics and register them as paired nets.
+  Such pairs often allow deducing further matching pairs. This deduction is 
+  continued until all non-ambiguous pairing options are exhausted.
+  For resolving ambiguities, backtracking is employed: 
+  the algorithm proposes a match and tentatively proceeds with this assumption. 
+  If this execution path leads to a mismatch or logical contradiction, 
+  the algorith will go back to the beginning and restart with a 
+  new proposal. Backtracking is usually required mainly to match networks
+  with a high symmetry such as clock trees.
+  </p>
+
 </doc>

src/lay/lay/doc/manual/lvs_tweaks.xml

@@ -3,13 +3,140 @@
 
 <doc>
 
-  <title>LVS Tweaks</title>
+  <title>LVS Netlist Tweaks</title>
   <keyword name="LVS"/>
-  <keyword name="LVS Tweaks"/>
+  <keyword name="LVS Netlist Tweaks"/>
 
   <h2-index/>
 
   <p>
+  Netlist tweaking is important to standardize netlists. Without tweaking,
+  the extracted netlist may contain elements that are redundant or
+  don't match anything found in the schematic.
   </p>
 
+  <p>
+  Netlist tweaks are applied on the extracted <class_doc href="Netlist"/> object. 
+  This can be obtained with the <a href="/about/drc_ref_global.xml#netlist">netlist</a> function.
+  This function will extract the netlist if not done already.
+  </p>
+
+  <p>
+  Netlist tweaks can also be applied to the schematic netlist. For example to flatten away 
+  a model subcircuit called "NMOS", use this expression:
+  </p>
+
+  <pre>schematic.flatten_circuit("NMOS")</pre>
+
+  <h2>Top level pin generation</h2>
+
+  <p>
+  Circuits extracted don't have pins on the top hierarchy level as the
+  extractor cannot figure out where to connect to this circuit.
+  The compare function does not try to match pins in this case.
+  But to gain a useful extracted netlists, pins are required.
+  Without pins, a circuit can't be embedded in a testbench for 
+  example. 
+  </p>
+
+  <p>
+  KLayout offers a function to create top-level pins using 
+  a simple heuristics: for every named (i.e. labelled) net in the top level 
+  circuit a pin will be created (<class_doc href="Netlist#make_top_level_pins"/>):
+  </p>
+
+  <pre>netlist.make_top_level_pins</pre>
+
+  <h2>Device combination</h2>
+
+  <p>
+  Combining devices is important for devices which are not 
+  represented as coherent entities in the layout. Examples are:
+  </p>
+
+  <ul>
+    <li><b>Fingered MOS transistors:</b> MOS transistors with a large width
+    are often split into multiple pieces to reduce the parasitic gate and
+    diffusion resistances and capacitances. In the layout this is equivalent
+    to multiple parallel transistors.
+    </li>
+    <li><b>Serial resistors:</b> Large resistors are often separated into 
+    stripes which are then connected in a meander structure. From the device
+    perspective such resistors consist of several resistors connected in 
+    series.
+    </li>
+    <li><b>Array capacitors:</b> Large capacitors are often split into 
+    smaller ones which are arranged in an array and connected in parallel.
+    This helps controlling the parasitic series resistances and inductances
+    and avoids manufacturing issues.
+    </li>
+  </ul>
+
+  <p>
+  In all these cases, the schematic usually summarizes these devices 
+  into a single one with lumped parameter values (total resistance, capacitance,
+  transistor width). This creates a discrepancy which "device combination"
+  avoids. "Device combination" is a step in which devices are identified which
+  can be combined into single devices (such as serial or parallel resistors and
+  capacitors). To run device combination, use <class_doc href="Netlist#combine_devices"/>:
+  </p>
+
+  <pre>netlist.combine_devices</pre>
+
+  <p>
+  The combination of serial devices might leave floating nets (the net connecting the
+  devices originally. These nets can be removed with <class_doc href="Netlist#purge_nets"/>.
+  See also <class_doc href="Netlist#simplify"/>, which is wrapper for several 
+  methods related to netlist normalization.
+  </p>
+
+  <p>
+  It's recommended to run "make_toplevel_pins" and "purge" before this step (see below).
+  </p>
+
+  <h2>Circuit flattening (elimination)</h2>
+
+  <p>
+  It's often required to flatten circuits that do not represent a specific level of organisation but
+  act as a wrapper to something else. In layouts, devices are often implemented as PCells and 
+  appear as specific cells for no other reason than being implemented in a subcell. The same 
+  might happen for schematic subcircuits which wrap a device. "Flattening" means that a circuit
+  is removed and it's contents are integrated into the calling circuits.
+  </p>
+
+  <p>
+  To flatten a circuit from the extracted netlist use
+  </p>
+
+  <pre>netlist.flatten_circuit("CIRCUIT_NAME")</pre>
+
+  <h2>Purging (elimination of redundancy)</h2>
+
+  <p>
+  Extracted netlists often contain elements without a functional 
+  aspect: via cells for example generate subcircuits with a single pin and
+  no device. Isolated metal islands (letters, logos, fill/planarisation 
+  patches) will create floating nets etc. Two methods are available to 
+  purge those elements.
+  </p>
+
+  <p>
+  <class_doc href="Netlist#purge"/> will remove all floating nets,
+  all circuits without devices or subcircuits. <class_doc href="Netlist#purge_nets"/>
+  will only purge floating nets.
+  Floating nets are nets which don't connect to any device or subcircuit.
+  </p>
+
+  <pre>netlist.purge
+netlist.purge_nets</pre>
+
+  <h2>Normalization wrapper (simplification)</h2>
+
+  <p>
+  <class_doc href="Netlist#simplify"/> is a wrapper for "make_top_level_pins",
+  "combine_devices" and "purge" in the recommended order:
+  </p>
+
+  <pre>netlist.simplify</pre>
+
 </doc>

src/lay/lay/layHelpResources.qrc

@@ -186,6 +186,7 @@
         <file alias="inv_with_diodes.png">doc/manual/inv_with_diodes.png</file>
         <file alias="inv_schematic.png">doc/manual/inv_schematic.png</file>
         <file alias="inv_schematic2.png">doc/manual/inv_schematic2.png</file>
+        <file alias="net_graph.png">doc/manual/net_graph.png</file>
         <file alias="bjt3_schematic.png">doc/manual/bjt3_schematic.png</file>
         <file alias="bjt4_schematic.png">doc/manual/bjt4_schematic.png</file>
         <file alias="mos3_schematic.png">doc/manual/mos3_schematic.png</file>