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

<!-- generated by /home/matthias/klayout/master/scripts/drc_lvs_doc/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="blank_circuit"/><h2>"blank_circuit" - Removes the content from the given circuits (blackboxing)</h2>
<keyword name="blank_circuit"/>
<p>Usage:</p>
<ul>
<li><tt>blank_circuit(circuit_filter)</tt></li>
</ul>
<p>
This method will erase all content from the circuits matching the filter.
The filter is a glob expression.
</p><p>
This has the following effects:
</p><p>
<ul>
<li>The circuits are no longer compared (netlist vs. schematic) </li>
<li>Named pins are required to match (use labels on the nets to name pins in the layout) </li>
<li>Unnamed pins are treated as equivalent and can be swapped </li>
<li>The selected circuits will not be purged on netlist simplification </li>
</ul>
</p><p>
Using this method can be useful to reduce the verification overhead for 
blocks which are already verifified by other ways or for which no schematic
is available - e.g. hard macros.
</p><p>
Example:
</p><p>
<pre>
# skips all MEMORY* circuits from compare
blank_circuit("MEMORY*")
</pre>
</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="disable_parameter"/><h2>"disable_parameter" - Indicates whether to disable a specific parameter for a given device</h2>
<keyword name="disable_parameter"/>
<p>Usage:</p>
<ul>
<li><tt>disable_parameter(device_class_name, parameter_name)</tt></li>
</ul>
<p>
Disabling a parameter is the inverse of <a href="#enable_parameter">enable_parameter</a>. Disabling a parameter will
reset the "primary" flag of the parameter. This has several effects - e.g. the parameter will not be 
used in device compare during netlist matching by default. 
</p><p>
This is not a strong concept but rather
a hint for the system. Disabling a parameter for netlist compare without side effects
is possible with the <a href="#ignore_parameter">ignore_parameter</a> function. In the same way, <a href="#tolerance">tolerance</a> will enable a parameter for
netlist compare regardless of the "primary" status of the parameter.
</p>
<a name="enable_parameter"/><h2>"enable_parameter" - Indicates whether to enable a specific parameter for a given device</h2>
<keyword name="enable_parameter"/>
<p>Usage:</p>
<ul>
<li><tt>enable_parameter(device_class_name, parameter_name)</tt></li>
</ul>
<p>
The parameter is made "primary" which enables further applications - e.g. it is netlisted
for some elements which normally would not print that parameter, and the parameter
is compared in the default device compare scheme during netlist matching.
</p><p>
Enabling a parameter is rather a hint for the system and the effects can be controlled
by other means, so this is not a strong concept. For example, once a <a href="#tolerance">tolerance</a> is 
specified for a parameter, the "primary" flag of the parameter is not considered anymore.
The inverse the this function is <a href="#disable_parameter">disable_parameter</a>.
</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="ignore_parameter"/><h2>"ignore_parameter" - Skip a specific parameter for a given device class name during device compare</h2>
<keyword name="ignore_parameter"/>
<p>Usage:</p>
<ul>
<li><tt>ignore_parameter(device_class_name, parameter_name)</tt></li>
</ul>
<p>
Use this function is ignore a parameter for a particular device class during the netlist compare.
Some parameters - for example "L" and "W" parameters of the resistor device - are "secondary" parameters
which are not ignored by default. Using "ignore_parameter" on such devices does not have an effect.
</p><p>
"ignore_parameter" and "tolerance" only have an effect with the default device comparer. Using a custom device comparer
will override the definitions by "ignore_parameter" or "tolerance".
</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="no_lvs_hints"/><h2>"no_lvs_hints" - Disables LVS hints</h2>
<keyword name="no_lvs_hints"/>
<p>Usage:</p>
<ul>
<li><tt>no_lvs_hints</tt></li>
</ul>
<p>
LVS hints may be expensive to compute. Use this function to disable
generation of LVS hints
</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_pattern, net_pattern)</tt></li>
<li><tt>same_nets(circuit_pattern, 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 circuits have to be given by name pattern. 
Nets can be either given by name or as Net objects.
In the two-argument form, the circuits and nets have to be given as name pattern.
</p><p>
"name pattern" are glob-style pattern - e.g. the following will identify the 
all nets starting with "A" from the extracted netlist with the same net from 
the schematic netlist for all circuits starting with "INV":
</p><p>
<pre>
same_nets("INV*", "A*")
</pre>
</p><p>
A plain "*" for the net pattern forces all (named) nets to be equivalent between layout and schematic. 
Unnamed nets from the extracted netlist are not considered - i.e. nets without a label.
</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><p>
Multiple calls of "same_nets" can be used. The calls are effective in the order
the are given. For example, the following sequence specifies equivalence of all
equally named nets, with the exception of "A" and "B" which are equivalent to each other
inside cell "ND2", despite their different name:
</p><p>
<pre>
same_nets("*", "*")
same_nets("ND2", "A", "B")
</pre>
</p>
<a name="same_nets!"/><h2>"same_nets!" - Establishes an equivalence between the nets with matching requirement</h2>
<keyword name="same_nets!"/>
<p>Usage:</p>
<ul>
<li><tt>same_nets!(circuit_pattern, net_pattern)</tt></li>
<li><tt>same_nets!(circuit_pattern, net_a, net_b)</tt></li>
<li><tt>same_nets!(circuit_a, net_a, circuit_b, net_b)</tt></li>
</ul>
<p>
This method is equivalent to <a href="#same_nets">same_nets</a>, but requires identity of the given nets.
If the specified nets do not match, an error is reported.
</p><p>
For example, this global specification requires all named nets from the
layout to have an equivalent net in the schematic and those nets need to be 
identical for all circuits:
</p><p>
<pre>
same_nets!("*", "*")
</pre>
</p><p>
The following specification requires "A" and "B" to be identical in
circuit "ND2". It is not an error if either "A" does not exist in the
layout or "B" does not exist in the schematic:
</p><p>
<pre>
same_nets!("ND2", "A", "B")
</pre>
</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="split_gates"/><h2>"split_gates" - Implements the "split gates" feature</h2>
<keyword name="split_gates"/>
<p>Usage:</p>
<ul>
<li><tt>split_gates(device_name)</tt></li>
<li><tt>split_gates(device_name, circuit_filter)</tt></li>
</ul>
<p>
Multi-fingered, multi-gate MOS transistors can be built without connecting
the source/drain internal nets between the fingers. This will prevent 
"combine_devices" from combining the single gate transistors of the
different fingers into single ones.
</p><p>
"split_gates" now marks the devices of the given class so that they will
receive a special treatment which joins the internl source/drain nodes.
</p><p>
By default, this method is applied to all circuits. You can specify
a circuit pattern to apply it to certain circuits only.
</p><p>
"device_name" must be a valid device name and denote a MOS3, MOS4, DMOS3
or DMOS4 device.
</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><p>
Some device parameters - like the resistor's "L" and "W" parameters - are not compared by default.
These are "secondary" device parameters. Using a tolerance on such parameters will make these parameters
being compared even if they are secondary ones.
</p><p>
A function is skip a parameter during the device compare is "ignore_parameter".
</p><p>
"tolerance" and "ignore_parameter" only have an effect with the default device comparer. Using a custom device comparer
will override the definitions by "ignore_parameter" or "tolerance".
</p>
</doc>
