<?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>DRC Reference: Netter object</title>
<keyword name="Netter"/>
<p>
The Netter object provides services related to network extraction
from a layout. The relevant methods of this object are available
as global functions too where they act on a default incarnation
of the netter. Usually it's not required to instantiate a Netter
object, but it serves as a container for this functionality.
</p><p>
<pre>
# create a new Netter object:
nx = netter
nx.connect(poly, contact)
...
</pre>
</p><p>
Network formation:
</p><p>
A basic service the Netter object provides is the formation of 
connected networks of conductive shapes (netting). To do so, the Netter
must be given a connection specification. This happens by calling
"connect" with two polygon layers. The Netter will then regard all
overlaps of shapes on these layers as connections between the
respective materials. Networks are the basis for netlist extraction,
network geometry deduction and the antenna check.
</p><p>
Connections can be cleared with "clear_connections". If not, 
connections add atop of the already defined ones. Here is an 
example for the antenna check:
</p><p>
<pre>
# build connction of poly+gate to metal1
connect(gate, poly)
connect(poly, contact)
connect(contact, metal1)

# runs an antenna check for metal1 with a ratio of 50
m1_antenna_errors = antenna_check(gate, metal1, 50.0)

# add connections to metal2
connect(metal1, via1)
connect(via1, metal2)

# runs an antenna check for metal2 with a ratio of 70.0
m2_antenna_errors = antenna_check(gate, metal2, 70.0)

# this will remove all connections made
clear_connections
...
</pre>
</p><p>
Further functionality of the Netter object:
</p><p>
More methods will be added in the future to support network-related features.
</p>
<h2-index/>
<a name="antenna_check"/><h2>"antenna_check" - Performs an antenna check</h2>
<keyword name="antenna_check"/>
<p>Usage:</p>
<ul>
<li><tt>antenna_check(gate, metal, ratio, [ diode_specs ... ] [, texts ])</tt></li>
</ul>
<p>
The antenna check is used to avoid plasma induced damage. Physically, 
the damage happes if during the manufacturing of a metal layer with
plasma etching charge accumulates on the metal islands. On reaching a
certain threshold, this charge may discarge over gate oxide attached of 
devices attached to such metal areas hence damaging it.
</p><p>
Antenna checks are performed by collecting all connected nets up to
a certain metal layer and then computing the area of all metal shapes
and all connected gates of a certain kind (e.g. thin and thick oxide gates).
The ratio of metal area divided by the gate area must not exceed a certain
threshold.
</p><p>
A simple antenna check is this:
</p><p>
<pre>
poly = ... # poly layer
diff = ... # diffusion layer
contact = ... # contact layer
metal1 = ... # metal layer

# compute gate area
gate = poly &amp; diff

# note that gate and poly have to be included - gate is
# a subset of poly, but forms the sensitive area
connect(gate, poly)
connect(poly, contact)
connect(contact, metal1)
errors = antenna_check(gate, metal1, 50.0)
</pre>
</p><p>
Usually antenna checks apply to multiple metal layers. In this case,
the connectivity needs to be extended after the first check to include
the next metal layers. This can be achieved with incremental connects:
</p><p>
<pre>
# provide connections up to metal1
connect(gate, poly)
connect(poly, contact)
connect(contact, metal1)
metal1_errors = antenna_check(gate, metal1, 50.0)

# now *add* connections up to metal2
connect(metal1, via1)
connect(via1, metal2)
metal2_errors = antenna_check(gate, metal2, 50.0)

... continue this scheme with further metal layers ...
</pre>
</p><p>
Plasma induced damage can be rectified by including diodes
which create a safe current path for discharging the metal
islands. Such diodes can be identified with a recognition layer
(usually the diffusion area of a certain kind). You can include
such diode recognition layers in the antenna check. If a connection
is detected to a diode, the respective network is skipped:
</p><p>
<pre>
...
diode = ... # diode recognition layer

connect(diode, contact)
errors = antenna_check(gate, metal1, 50.0, diode)
</pre>
</p><p>
You can also make diode connections decreases the
sensitivity of the antenna check depending on the size
of the diode. The following specification makes 
diode connections increase the ratio threshold by
10 per square micrometer of diode area:
</p><p>
<pre>
...
diode = ... # diode recognition layer

connect(diode, contact)
# each square micrometer of diode area connected to a network
# will add 10 to the ratio:
errors = antenna_check(gate, metal1, 50.0, [ diode, 10.0 ])
</pre>
</p><p>
Multiple diode specifications are allowed. Just add them 
to the antenna_check call.
</p><p>
You can include the perimeter into the area computation for
the gate or metal layer or both. The physical picture
is this: the side walls of the material contribute to the 
surface too. As the side wall area can be estimated by taking
the perimeter times some material thickness, the effective 
area is: 
</p><p>
<pre>
A(eff) = A + P * t
</pre>
</p><p>
Here A is the area of the polygons and P is their perimeter.
t is the "thickness" in micrometer units. To specify such
a condition, use the following notation:
</p><p>
<pre>
errors = antenna_check(area_and_perimeter(gate, 0.5), ...)
</pre>
</p><p>
"area_and_perimeter" takes the polygon layer and the 
thickness (0.5 micrometers in this case). 
This notation can be applied to both gate and
metal layers. A detailed notation for the usual,
area-only case is available as well for completeness:
</p><p>
<pre>
errors = antenna_check(area_only(gate), ...)

# this is equivalent to a zero thickness:
errors = antenna_check(area_and_perimeter(gate, 0.0), ...)
# or the standard case:
errors = antenna_check(gate, ...)
</pre>
</p><p>
Finally there is also "perimeter_only". When using this 
specification with a thickness value, the area is computed
from the perimeter alone:
</p><p>
<pre>
A(eff) = P * t
</pre>
</p><p>
<pre>
errors = antenna_check(perimeter_only(gate, 0.5), ...)
</pre>
</p><p>
The error shapes produced by the antenna check are copies
of the metal shapes on the metal layers of each network 
violating the antenna rule.
</p><p>
You can specify a text layer (use "labels" to create one). It will receive
error labels describing the measured values and computation parameters for debugging
the layout. This option has been introduced in version 0.27.11.
</p>
<a name="clear_connections"/><h2>"clear_connections" - Clears all connections stored so far</h2>
<keyword name="clear_connections"/>
<p>Usage:</p>
<ul>
<li><tt>clear_connections</tt></li>
</ul>
<p>
See <a href="#connect">connect</a> for more details.
</p>
<a name="connect"/><h2>"connect" - Specifies a connection between two layers</h2>
<keyword name="connect"/>
<p>Usage:</p>
<ul>
<li><tt>connect(a, b)</tt></li>
</ul>
<p>
a and b must be polygon or text layers. After calling this function, the
Netter regards all overlapping or touching shapes on these layers
to form an electrical connection between the materials formed by
these layers. This also implies intra-layer connections: shapes
on these layers touching or overlapping other shapes on these
layers will form bigger, electrically connected areas.
</p><p>
Texts will be used to assign net names to the nets. The preferred
method is to use <a href="/about/drc_ref_global.xml#labels">labels</a> to create a text layer from a design 
layer. When using <a href="/about/drc_ref_global.xml#input">input</a>, text labels are carried implicitly
with the polygons but at the cost of small dummy shapes (2x2 DBU
marker polygons) and limited functionality.
</p><p>
Multiple connect calls must be made to form larger connectivity
stacks across multiple layers. Such stacks may include forks and
joins.
</p><p>
Connections are accumulated. The connections defined so far
can be cleared with <a href="#clear_connections">clear_connections</a>.
</p>
<a name="connect_explicit"/><h2>"connect_explicit" - Specifies a list of net names for nets to connect ("must connect" nets)</h2>
<keyword name="connect_explicit"/>
<p>Usage:</p>
<ul>
<li><tt>connect_explicit(net_names)</tt></li>
<li><tt>connect_explicit(cell_pattern, net_names)</tt></li>
</ul>
<p>
Use this method to explicitly connect nets even if there is no physical connection.
The concept is similar to implicit connection (see <a href="#connect_implicit">connect_implicit</a>). The method gets
a list of nets which are connected virtually, even if there is no physical connection.
The first version applies this scheme to all cells, the second version to cells matching
the cell name pattern. The cell name pattern follows the usual glob style form (e.g. "A*"
applies the connection in all cells whose name starts with "A").
</p><p>
This method is useful to establish a logical connection which is made later up on the 
next level of hierarchy. For example, a standard cell my not contain substrate or well
taps as these may be made by tap or spare cells. Logically however, the cell only has
one power or ground pin for the devices and substrate or well. In order to match both
representations - for example for the purpose of LVS - the dual power or ground pins have
to be connected. Assuming that there is a global net "BULK" for the substrate and a
net "VSS" for the sources of the NMOS devices, the following statement will create this
connection for all cell names beginning with "INV":
</p><p>
<pre>
connect_global(bulk, "BULK")
...
connect_explicit("INV*", [ "BULK", "VSS" ])
</pre>
</p><p>
The resulting net and pin will carry a name made from the combination of the connected
nets. In this case it will be "BULK,VSS".
</p><p>
The virtual connection in general bears the risk of missing a physical connection. 
The "connect_explicit" feature therefore checks whether the connection is made physically 
on the next hierarchy level ("must connect" nets), except for top-level cells for which 
it is assumed that this connection is made later. 
A warning is raised instead for top level cells.
</p><p>
Explicit connections also imply implicit connections between different parts of 
one of the nets. In the example before, "VSS" pieces without a physical connection
will also be connected.
</p><p>
The explicit connections are applied on the next net extraction and cleared
on "clear_connections".
</p>
<a name="connect_global"/><h2>"connect_global" - Connects a layer with a global net</h2>
<keyword name="connect_global"/>
<p>Usage:</p>
<ul>
<li><tt>connect_global(l, name)</tt></li>
</ul>
<p>
Connects the shapes from the given layer l to a global net with the given name.
Global nets are common to all cells. Global nets automatically connect to parent
cells throughs implied pins. An example is the substrate (bulk) net which connects
to shapes belonging to tie-down diodes. "l" can be a polygon or text layer.
</p>
<a name="connect_implicit"/><h2>"connect_implicit" - Specifies a search pattern for implicit net connections ("must connect" nets)</h2>
<keyword name="connect_implicit"/>
<p>Usage:</p>
<ul>
<li><tt>connect_implicit(label_pattern)</tt></li>
<li><tt>connect_implicit(cell_pattern, label_pattern)</tt></li>
</ul>
<p>
This method specifies a net name search pattern, either for all cells or for
certain cells, given by a name search pattern. Search pattern follow the usual glob
form (e.g. "A*" for all cells or nets with names starting with "A").
</p><p>
Then, for nets matching the net name pattern and for which there is more than
one subnet, the subnets are connected. "Subnets" are physically disconnected parts
of a net which carry the same name.
</p><p>
This feature is useful for example for power nets which are complete in a cell,
but are supposed to be connected upwards in the hierarchy ("must connect" nets).
Physically there are multiple nets, logically - and specifically in the schematic for
the purpose of LVS - there is only one net. 
"connect_implicit" now creates a virtual, combined physical net that matches the logical net.
</p><p>
This is general bears the risk of missing a physical connection. The "connect_implicit"
feature therefore checks whether the connection is made physically on the next hierarchy
level, except for top-level cells for which it is assumed that this connection is made
later. A warning is raised instead for top level cells.
</p><p>
The implicit connections are applied on the next net extraction and cleared
on "clear_connections". Another feature is <a href="#connect_explicit">connect_explicit</a> which allows connecting
differently named subnets in a similar fashion.
</p>
<a name="device_scaling"/><h2>"device_scaling" - Specifies a dimension scale factor for the geometrical device properties</h2>
<keyword name="device_scaling"/>
<p>Usage:</p>
<ul>
<li><tt>device_scaling(factor)</tt></li>
</ul>
<p>
Specifying a factor of 2 will make all devices being extracted as if the 
geometries were two times larger. This feature is useful when the drawn layout
does not correspond to the physical dimensions.
</p>
<a name="extract_devices"/><h2>"extract_devices" - Extracts devices based on the given extractor class, name and device layer selection</h2>
<keyword name="extract_devices"/>
<p>Usage:</p>
<ul>
<li><tt>extract_devices(extractor, layer_hash)</tt></li>
<li><tt>extract_devices(extractor_class, name, layer_hash)</tt></li>
</ul>
<p>
Runs the device extraction for given device extractor class. In the first
form, the extractor object is given. In the second form, the extractor's
class object and the new extractor's name is given.
</p><p>
The device extractor is either an instance of one of the predefined extractor
classes (e.g. obtained from the utility methods such as <a href="/about/drc_ref_global.xml#mos4">mos4</a>) or a custom class. 
It provides the
algorithms for deriving the device parameters from the device geometry. It needs 
several device recognition layers which are passed in the layer hash.
</p><p>
Predefined device extractors are:
</p><p>
<ul>
<li><a href="/about/drc_ref_global.xml#mos3">mos3</a> - A three-terminal MOS transistor </li>
<li><a href="/about/drc_ref_global.xml#mos4">mos4</a> - A four-terminal MOS transistor </li>
<li><a href="/about/drc_ref_global.xml#dmos3">dmos3</a> - A three-terminal MOS asymmetric transistor </li>
<li><a href="/about/drc_ref_global.xml#dmos4">dmos4</a> - A four-terminal MOS asymmetric transistor </li>
<li><a href="/about/drc_ref_global.xml#bjt3">bjt3</a> - A three-terminal bipolar transistor </li>
<li><a href="/about/drc_ref_global.xml#bjt4">bjt4</a> - A four-terminal bipolar transistor </li>
<li><a href="/about/drc_ref_global.xml#diode">diode</a> - A planar diode </li>
<li><a href="/about/drc_ref_global.xml#resistor">resistor</a> - A resistor </li>
<li><a href="/about/drc_ref_global.xml#resistor_with_bulk">resistor_with_bulk</a> - A resistor with a separate bulk terminal </li>
<li><a href="/about/drc_ref_global.xml#capacitor">capacitor</a> - A capacitor </li>
<li><a href="/about/drc_ref_global.xml#capacitor_with_bulk">capacitor_with_bulk</a> - A capacitor with a separate bulk terminal </li>
</ul>
</p><p>
Each device class (e.g. n-MOS/p-MOS or high Vt/low Vt) needs its own instance
of device extractor. The device extractor beside the algorithm and specific 
extraction settings defines the name of the device to be built.
</p><p>
The layer hash is a map of device type specific functional names (key) and
polygon layers (value). Here is an example:
</p><p>
<pre>
deep

nwell   = input(1, 0)
active  = input(2, 0)
poly    = input(3, 0)
bulk    = make_layer   # renders an empty layer used for putting the terminals on

nactive = active - nwell  # active area of NMOS
nsd     = nactive - poly  # source/drain area
gate    = nactive &amp; poly  # gate area

extract_devices(mos4("NMOS4"), { :SD =&gt; nsd, :G =&gt; gate, :P =&gt; poly, :W =&gt; bulk })
</pre>
</p><p>
The return value of this method will be the device class of the devices
generated in the extraction step (see <class_doc href="DeviceClass">DeviceClass</class_doc>).
</p>
<a name="ignore_extraction_errors"/><h2>"ignore_extraction_errors" - Specifies whether to ignore extraction errors</h2>
<keyword name="ignore_extraction_errors"/>
<p>Usage:</p>
<ul>
<li><tt>ignore_extraction_errors(value)</tt></li>
</ul>
<p>
With this value set to false (the default), "extract_netlist" will raise
an exception upon extraction errors. Otherwise, extraction errors will be logged
but no error is raised.
</p>
<a name="l2n_data"/><h2>"l2n_data" - Gets the internal <class_doc href="LayoutToNetlist">LayoutToNetlist</class_doc> object</h2>
<keyword name="l2n_data"/>
<p>Usage:</p>
<ul>
<li><tt>l2n_data</tt></li>
</ul>
<p>
The <class_doc href="LayoutToNetlist">LayoutToNetlist</class_doc> object provides access to the internal details of
the netter object.
</p>
<a name="name"/><h2>"name" - Assigns a name to a layer</h2>
<keyword name="name"/>
<p>Usage:</p>
<ul>
<li><tt>name(layer, name)</tt></li>
<li><tt>name(layer, name, layer_number, datatype_number)</tt></li>
<li><tt>name(layer, name, layer_info)</tt></li>
</ul>
<p>
Layer names are listed in the LayoutToNetlist (L2N) or LVS database. They
are used to identify the layers, the net or device terminal geometries are
on. It is usual to have computed layers, so it is necessary to indicate the
purpose of the layer for later reuse of the geometries.
</p><p>
It is a good practice to assign names to computed and original layers, 
for example:
</p><p>
<pre>
poly = input(...)
poly_resistor = input(...)

poly_wiring = poly - poly_resistor
name(poly_wiring, "poly_wiring")
</pre>
</p><p>
Names must be assigned before the layers are used for the first time
in <a href="#connect">connect</a>, <a href="#soft_connect">soft_connect</a>, <a href="#connect_global">connect_global</a>, <a href="#soft_connect_global">soft_connect_global</a> and 
<a href="#extract_devices">extract_devices</a> statements. 
</p><p>
If layers are not named, they will be given a name made from the 
<a href="#name_prefix">name_prefix</a> and an incremental number when the layer is used for the
first time. 
</p><p>
<a href="#name">name</a> can only be used once on a layer and the layer names must be 
unique (not taken by another layer).
</p><p>
The layer/datatype or LayerInfo specification is optional and will
be used to configure the internal layout. This information is also
persisted inside database files. Specifying a layer/datatype information
is useful, if a layer is not an original layer, but is to be restored
to an actual layout layer later.
</p>
<a name="name_prefix"/><h2>"name_prefix" - Specifies the name prefix for auto-generated layer names</h2>
<keyword name="name_prefix"/>
<p>Usage:</p>
<ul>
<li><tt>name_prefix(prefix)</tt></li>
</ul>
<p>
See <link href="#name"/> for details. The default prefix is "l".
</p>
<a name="netlist"/><h2>"netlist" - Gets the extracted netlist or triggers extraction if not done yet</h2>
<keyword name="netlist"/>
<p>Usage:</p>
<ul>
<li><tt>netlist</tt></li>
</ul>
<p>
If no extraction has been performed yet, this method will start the 
layout analysis. Hence, all <a href="#connect">connect</a>, <a href="#connect_global">connect_global</a> and <a href="#connect_implicit">connect_implicit</a>
calls must have been made before this method is used. Further <a href="#connect">connect</a>
statements will clear the netlist and re-extract it again.
</p>
<a name="soft_connect"/><h2>"soft_connect" - Specifies a soft connection between two layers</h2>
<keyword name="soft_connect"/>
<p>Usage:</p>
<ul>
<li><tt>soft_connect(a, b)</tt></li>
</ul>
<p>
a and b must be polygon or text layers. After calling this function, the
Netter considers shapes from layer a and b connected in "soft mode".
Typically, b is a high-ohmic layer such as diffusion, implant for substate
material, also called the "lower" layer. 
</p><p>
A soft connection between shapes from layer a and b forms a directional 
connection like an ideal diode: current can flow down, but now up 
(not meant in the physical sense, this is a concept). 
</p><p>
Hence, two nets are disconnected, if they both connect to the same lower layer, 
but do not have a connection between them. 
</p><p>
The netlist extractor will use this scheme to identify nets that are 
connected only via such a high-ohmic region. Such a case is typically
bad for the functionality of a device and reported as an error.
Once, the check has been made and no error is found, soft-connected
nets are joined the same way than hard connections are made.
</p><p>
Beside this, soft connections follow the same rules than hard connections
(see <a href="#connect">connect</a>).
</p>
<a name="soft_connect_global"/><h2>"soft_connect_global" - Soft-connects a layer with a global net</h2>
<keyword name="soft_connect_global"/>
<p>Usage:</p>
<ul>
<li><tt>soft-connect_global(l, name)</tt></li>
</ul>
<p>
Connects the shapes from the given layer l to a global net with the given name
in "soft mode".
</p><p>
See <a href="#connect_global">connect_global</a> for details about the concepts of global nets.
See <a href="#soft_connect">soft_connect</a> for details about the concept of soft connections.
In global net soft connections, the global net (typically a substrate)
is always the "lower" layer.
</p>
<a name="top_level"/><h2>"top_level" - Specifies top level mode</h2>
<keyword name="top_level"/>
<p>Usage:</p>
<ul>
<li><tt>top_level(value)</tt></li>
</ul>
<p>
With this value set to false (the default), it is assumed that the 
circuit is not used as a top level chip circuit. In that case, for
example must-connect nets which are not connected are reported as
as warnings. If top level mode is set to true, such disconnected
nets are reported as errors as this indicates a missing physical
connection.
</p>
</doc>
