# LVS Reference: Netter object

The Netter object provides services related to network extraction from a layout plus comparison against a reference netlist. Similar to the DRC DRC::Netter (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.

The LVS Netter object inherits all methods of the DRC::Netter.

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 global#netter function:

    # 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

## "align" - Aligns the extracted netlist vs. the schematic

Usage:

- align

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.

This feature is in particular useful to remove structural cells like device PCells, reuse blocks etc.

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.

"netlist.flatten_circuit(...)" or "schematic.flatten_circuit(...)" are other (explicit) ways to flatten circuits.

Please note that flattening circuits has some side effects such as loss of details in the cross reference and net layout.

## "compare" - Compares the extracted netlist vs. the schematic

Usage:

- compare

Before using this method, a schematic netlist has to be loaded with schematic. The compare can be configured in more details using same_nets, same_circuits, same_device_classes and equivalent_pins.

The compare method will also modify the netlists in case of missing corresponding circuits: the unpaired circuit will be flattened then.

This method will return true, if the netlists are equivalent and false otherwise.

## "consider_net_names" - Indicates whether the netlist comparer shall use net names

Usage:

- consider_net_names(f)

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.

## "equivalent_pins" - Marks pins as equivalent

Usage:

- equivalent_pins(circuit, pin ...)

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):

    netter.equivalent_pins("NAND2", 0, 1)

The circuit argument is either a circuit name (a string) or a Circuit object from the schematic netlist.

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.

Before this method can be used, a schematic netlist needs to be loaded with schematic.

## "join_symmetric_nets" - Joins symmetric nets of selected circuits on the extracted netlist

Usage:

- join_symmetric_nets(circuit_filter)

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).

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.

For the symmetry detection, the specified constraints (e.g. tolerances, device filters etc.) apply.

## "lvs_data" - Gets the internal LayoutVsSchematic object

Usage:

- lvs_data

The LayoutVsSchematic object provides access to the internal details of the netter object.

## "max_branch_complexity" - Configures the maximum branch complexity for ambiguous net matching

Usage:

- max_branch_complexity(n)

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.

## "max_depth" - Configures the maximum search depth for net match deduction

Usage:

- max_depth(n)

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.

## "max_res" - Ignores resistors with a resistance above a certain value

Usage:

- max_res(threshold)

After using this method, the netlist compare will ignore resistor devices with a resistance value above the given threshold (in Farad).

## "min_caps" - Ignores capacitors with a capacitance below a certain value

Usage:

- min_caps(threshold)

After using this method, the netlist compare will ignore capacitance devices with a capacitance values below the given threshold (in Farad).

## "same_circuits" - Establishes an equivalence between the circuits

Usage:

- same_circuits(circuit_a, circuit_b)

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.

One of the circuits may be nil. In this case, the corresponding other circuit is mapped to "nothing", i.e. ignored.

Before this method can be used, a schematic netlist needs to be loaded with schematic.

## "same_device_classes" - Establishes an equivalence between the device classes

Usage:

- same_device_classes(class_a, class_b)

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.

Before this method can be used, a schematic netlist needs to be loaded with schematic.

One of the device classes may be "nil". In this case, the corresponding other device class is mapped to "nothing", i.e. ignored.

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.

    same_device_classes("POLYRES", "RES")
    same_device_classes("WELLRES", "RES")

will match both "POLYRES" and "WELLRES" on the layout side to "RES" on the schematic side.

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.

## "same_nets" - Establishes an equivalence between the nets

Usage:

- same_nets(circuit, net_a, net_b)
- same_nets(circuit_a, net_a, circuit_b, net_b)

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).

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.

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.

Before this method can be used, a schematic netlist needs to be loaded with schematic.

## "schematic" - Gets, sets or reads the reference netlist

Usage:

- schematic(filename)
- schematic(filename, reader)
- schematic(netlist)
- schematic

If no argument is given, the current schematic netlist is returned. nil is returned if no schematic netlist is set yet.

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 NetlistReader object and allows detailed customization of the reader process.

Alternatively, a Netlist object can be given which is obtained from any other source.

## "tolerance" - Specifies compare tolerances for certain device parameters

Usage:

- tolerance(device_class_name, parameter_name, absolute_tolerance [, relative_tolerance])
- tolerance(device_class_name, parameter_name [, :absolute => absolute_tolerance] [, :relative => relative_tolerance])

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.