<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">

<!-- generated by /home/matthias/klayout/master/scripts/extract_doc.rb  -->
<!-- DO NOT EDIT! -->

<doc>
<title>LVS Reference: Netter object</title>
<keyword name="Netter"/>
<p>
The Netter object provides services related to network extraction
from a layout plus comparison against a reference netlist.
Similar to the DRC <a href="/about/drc_ref_netter.xml">DRC::Netter</a> (which lacks the compare ability), the
relevant method of this object are available as global functions too
where they act on a default incarnation. Usually it's not required
to instantiate a Netter object explicitly. 
</p><p>
The LVS Netter object inherits all methods of the <a href="/about/drc_ref_netter.xml">DRC::Netter</a>.
</p><p>
An individual netter object can be created, if the netter results
need to be kept for multiple extractions. If you really need
a Netter object, use the global <a href="/about/lvs_ref_global.xml#netter">netter</a> function:
</p><p>
<pre>
# create a new Netter object:
nx = netter

# build connectivity
nx.connect(poly, contact)
...

# read the reference netlist
nx.schematic("reference.cir")

# configure the netlist compare
nx.same_circuits("A", "B")
...

# runs the compare
if ! nx.compare
puts("no equivalence!")
end
</pre>
</p>
<h2-index/>
<a name="align"/><h2>"align" - Aligns the extracted netlist vs. the schematic</h2>
<keyword name="align"/>
<p>Usage:</p>
<ul>
<li><tt>align</tt></li>
</ul>
<p>
The align method will modify the netlists in case of missing 
corresponding circuits. It will flatten these circuits, thus 
improving the equivalence between the netlists. Top level circuits
are not flattened.
</p><p>
This feature is in particular useful to remove structural cells
like device PCells, reuse blocks etc.
</p><p>
This method will also remove schematic circuits for which there is
no corresponding layout cell. In the extreme case of flat layout this
will result in a flat vs. flat compare.
</p><p>
"netlist.flatten_circuit(...)" or "schematic.flatten_circuit(...)"
are other (explicit) ways to flatten circuits.
</p><p>
Please note that flattening circuits has some side effects such 
as loss of details in the cross reference and net layout.
</p>
<a name="compare"/><h2>"compare" - Compares the extracted netlist vs. the schematic</h2>
<keyword name="compare"/>
<p>Usage:</p>
<ul>
<li><tt>compare</tt></li>
</ul>
<p>
Before using this method, a schematic netlist has to be loaded with <a href="#schematic">schematic</a>.
The compare can be configured in more details using <a href="#same_nets">same_nets</a>, <a href="#same_circuits">same_circuits</a>,
<a href="#same_device_classes">same_device_classes</a> and <a href="#equivalent_pins">equivalent_pins</a>.
</p><p>
The compare method will also modify the netlists in case of missing 
corresponding circuits: the unpaired circuit will be flattened then.
</p><p>
This method will return true, if the netlists are equivalent and false
otherwise.
</p>
<a name="consider_net_names"/><h2>"consider_net_names" - Indicates whether the netlist comparer shall use net names</h2>
<keyword name="consider_net_names"/>
<p>Usage:</p>
<ul>
<li><tt>consider_net_names(f)</tt></li>
</ul>
<p>
If this value is set to true (the default), the netlist comparer
will employ net names to resolve ambiguities. If set to false,
ambiguities will be resolved based on the topology alone. Topology
resolution is more expensive.
</p>
<a name="equivalent_pins"/><h2>"equivalent_pins" - Marks pins as equivalent</h2>
<keyword name="equivalent_pins"/>
<p>Usage:</p>
<ul>
<li><tt>equivalent_pins(circuit, pin ...)</tt></li>
</ul>
<p>
This method will mark the given pins as equivalent. This gives the compare algorithm
more degrees of freedom when establishing net correspondence. Typically this method
is used to declare inputs from gates are equivalent where are are logically, but not
physically (e.g. in a CMOS NAND gate):
</p><p>
<pre>
netter.equivalent_pins("NAND2", 0, 1)
</pre>
</p><p>
The circuit argument is either a circuit name (a string) or a Circuit object
from the schematic netlist. 
</p><p>
Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
</p><p>
The pin arguments are zero-based pin numbers, where 0 is the first number, 1 the second etc.
If the netlist provides named pins, names can be used instead of numbers. Again, use upper
case pin names for SPICE netlists.
</p><p>
Use this method andwhere in the script before the <a href="#compare">compare</a> call.
</p>
<a name="join_symmetric_nets"/><h2>"join_symmetric_nets" - Joins symmetric nets of selected circuits on the extracted netlist</h2>
<keyword name="join_symmetric_nets"/>
<p>Usage:</p>
<ul>
<li><tt>join_symmetric_nets(circuit_filter)</tt></li>
</ul>
<p>
Nets are symmetrical if swapping them would not modify the circuit.
Hence they will carry the same potential and can be connected (joined).
This will simplify the circuit and can be applied before device combination
(e.g. through "netlist.simplify") to render a schematic-equivalent netlist in some 
cases where symmetric nodes are split (i.e. "split gate" configuration).
</p><p>
This method operates on the extracted netlist (layout). The circuit filter
specifies the circuits to which to apply this operation. The filter is a
glob-style pattern. Using "*" for all circuits is possible, but it's 
discouraged currenty until the reliability of the symmetry detection 
algorithm is established. Currently it is recommended to apply it only to 
those circuits for which this feature is required.
</p><p>
For the symmetry detection, the specified constraints (e.g. tolerances,
device filters etc.) apply.
</p>
<a name="lvs_data"/><h2>"lvs_data" - Gets the internal <class_doc href="LayoutVsSchematic">LayoutVsSchematic</class_doc> object</h2>
<keyword name="lvs_data"/>
<p>Usage:</p>
<ul>
<li><tt>lvs_data</tt></li>
</ul>
<p>
The <class_doc href="LayoutVsSchematic">LayoutVsSchematic</class_doc> object provides access to the internal details of
the netter object.
</p>
<a name="max_branch_complexity"/><h2>"max_branch_complexity" - Configures the maximum branch complexity for ambiguous net matching</h2>
<keyword name="max_branch_complexity"/>
<p>Usage:</p>
<ul>
<li><tt>max_branch_complexity(n)</tt></li>
</ul>
<p>
The netlist compare algorithm is basically a backtracing algorithm.
With ambiguous nets, the algorithm picks possible net pairs and
tries whether they will make a good match. Following the deduction
path for this nets may lead to further branches if more ambiguous
nets are encountered. To avoid combinational explosion, the maximum
branch complexity is limited to the value configured with this 
function. The default value is 500 which means not more than
500 combinations are tried for a single seed pair. For networks
with inherent ambiguity such as decoders, the complexity
can be increased at the expense of potentially larger runtimes.
The runtime penality is roughly proportional to the branch
complexity.
</p><p>
By default, the branch complexity is unlimited, but it may
be reduced in order to limit the compare runtimes at the cost
of a less elaborate compare attempt. The preferred solution 
however is to use labels for net name hints which also reduces
the depth.
</p>
<a name="max_depth"/><h2>"max_depth" - Configures the maximum search depth for net match deduction</h2>
<keyword name="max_depth"/>
<p>Usage:</p>
<ul>
<li><tt>max_depth(n)</tt></li>
</ul>
<p>
The netlist compare algorithm works recursively: once a net
equivalence is established, additional matches are derived from
this equivalence. Such equivalences in turn are used to derive
new equivalences and so on. The maximum depth parameter configures
the number of recursions the algorithm performs before picking
the next net. With higher values for the depth, the algorithm
pursues this "deduction path" in greater depth while with 
smaller values, the algorithm prefers picking nets in a random fashion
as the seeds for this deduction path. The default value is 8. 
</p><p>
By default, the depth is unlimited, but it may
be reduced in order to limit the compare runtimes at the cost
of a less elaborate compare attempt. The preferred solution 
however is to use labels for net name hints which also reduces
the branch complexity.
</p>
<a name="max_res"/><h2>"max_res" - Ignores resistors with a resistance above a certain value</h2>
<keyword name="max_res"/>
<p>Usage:</p>
<ul>
<li><tt>max_res(threshold)</tt></li>
</ul>
<p>
After using this method, the netlist compare will ignore resistor devices
with a resistance value above the given threshold (in Farad).
</p>
<a name="min_caps"/><h2>"min_caps" - Ignores capacitors with a capacitance below a certain value</h2>
<keyword name="min_caps"/>
<p>Usage:</p>
<ul>
<li><tt>min_caps(threshold)</tt></li>
</ul>
<p>
After using this method, the netlist compare will ignore capacitance devices
with a capacitance values below the given threshold (in Farad).
</p>
<a name="same_circuits"/><h2>"same_circuits" - Establishes an equivalence between the circuits</h2>
<keyword name="same_circuits"/>
<p>Usage:</p>
<ul>
<li><tt>same_circuits(circuit_a, circuit_b)</tt></li>
</ul>
<p>
This method will force an equivalence between the two circuits.
By default, circuits are identified by name. If names are different, this
method allows establishing an explicit correspondence.
</p><p>
circuit_a is for the layout netlist, circuit_b for the schematic netlist.
Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
</p><p>
One of the circuits may be nil. In this case, the corresponding
other circuit is mapped to "nothing", i.e. ignored.
</p><p>
Use this method andwhere in the script before the <a href="#compare">compare</a> call.
</p>
<a name="same_device_classes"/><h2>"same_device_classes" - Establishes an equivalence between the device classes</h2>
<keyword name="same_device_classes"/>
<p>Usage:</p>
<ul>
<li><tt>same_device_classes(class_a, class_b)</tt></li>
</ul>
<p>
This method will force an equivalence between the two device classes.
Device classes are also known as "models".
By default, device classes are identified by name. If names are different, this
method allows establishing an explicit correspondence.
</p><p>
Before this method can be used, a schematic netlist needs to be loaded with
<a href="#schematic">schematic</a>.
</p><p>
class_a is for the layout netlist, class_b for the schematic netlist.
Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
</p><p>
One of the device classes may be "nil". In this case, the corresponding
other device class is mapped to "nothing", i.e. ignored.
</p><p>
A device class on one side can be mapped to multiple other device
classes on the other side by using this function multiple times, e.g.
</p><p>
<pre>
same_device_classes("POLYRES", "RES")
same_device_classes("WELLRES", "RES")
</pre>
</p><p>
will match both "POLYRES" and "WELLRES" on the layout side to "RES" on the 
schematic side.
</p><p>
Once a device class is mentioned with "same_device_classes", matching by
name is disabled for this class. So after using 'same_device_classes("A", "B")'
"A" is no longer equivalent to "A" on the other side. If you want "A" to 
stay equivalent to "A" too, you need to use 'same_device_classes("A", "A")' 
in addition.
</p><p>
Use this method andwhere in the script before the <a href="#compare">compare</a> call.
</p>
<a name="same_nets"/><h2>"same_nets" - Establishes an equivalence between the nets</h2>
<keyword name="same_nets"/>
<p>Usage:</p>
<ul>
<li><tt>same_nets(circuit, net_a, net_b)</tt></li>
<li><tt>same_nets(circuit_a, net_a, circuit_b, net_b)</tt></li>
</ul>
<p>
This method will force an equivalence between the net_a and net_b from circuit_a
and circuit_b (circuit in the three-argument form is for both circuit_a and circuit_b).
</p><p>
In the four-argument form, the circuits can be either given by name or as Circuit
objects. In the three-argument form, the circuit has to be given by name. 
Nets can be either given by name or as Net objects.
</p><p>
After using this function, the compare algorithm will consider these nets equivalent.
Use this method to provide hints for the comparer in cases which are difficult to
resolve otherwise.
</p><p>
circuit_a and net_a are for the layout netlist, circuit_b and net_b for the schematic netlist.
Names are case sensitive for layout-derived netlists and case-insensitive for SPICE schematic netlists.
</p><p>
Use this method andwhere in the script before the <a href="#compare">compare</a> call.
</p>
<a name="schematic"/><h2>"schematic" - Gets, sets or reads the reference netlist</h2>
<keyword name="schematic"/>
<p>Usage:</p>
<ul>
<li><tt>schematic(filename)</tt></li>
<li><tt>schematic(filename, reader)</tt></li>
<li><tt>schematic(netlist)</tt></li>
<li><tt>schematic</tt></li>
</ul>
<p>
If no argument is given, the current schematic netlist is returned. nil is 
returned if no schematic netlist is set yet.
</p><p>
If a filename is given (first two forms), the netlist is read from the given file.
If no reader is provided, Spice format will be assumed. The reader object is a
<class_doc href="NetlistReader">NetlistReader</class_doc> object and allows detailed customization of the reader process.
</p><p>
Alternatively, a <class_doc href="Netlist">Netlist</class_doc> object can be given which is obtained from any other
source.
</p>
<a name="tolerance"/><h2>"tolerance" - Specifies compare tolerances for certain device parameters</h2>
<keyword name="tolerance"/>
<p>Usage:</p>
<ul>
<li><tt>tolerance(device_class_name, parameter_name, absolute_tolerance [, relative_tolerance])</tt></li>
<li><tt>tolerance(device_class_name, parameter_name [, :absolute =&gt; absolute_tolerance] [, :relative =&gt; relative_tolerance])</tt></li>
</ul>
<p>
Specifies a compare tolerance for a specific parameter on a given device class.
The device class is the name of a device class in the extracted netlist.
Tolerances can be given in absolute units or relative or both. 
The relative tolerance is given as a factor, so 0.1 is a 10% tolerance.
Absolute and relative tolerances add, so specifying both allows for a larger
deviation.
</p>
</doc>
