KLayout 0.29.8 (2024-11-26 926dac96c) [master]

API reference - Class NetlistCrossReference

Notation used in Ruby API documentation

Module: db

Description: Represents the identity mapping between the objects of two netlists.

Class hierarchy: NetlistCrossReference » NetlistCompareLogger

Sub-classes: NetPairData, DevicePairData, PinPairData, SubCircuitPairData, CircuitPairData, NetTerminalRefPair, NetPinRefPair, NetSubcircuitPinRefPair, Status

The NetlistCrossReference object is a container for the results of a netlist comparison. It implemented the NetlistCompareLogger interface, hence can be used as output for a netlist compare operation (NetlistComparer#compare). It's purpose is to store the results of the compare. It is used in this sense inside the LayoutVsSchematic framework.

The basic idea of the cross reference object is pairing: the netlist comparer will try to identify matching items and store them as pairs inside the cross reference object. If no match is found, a single-sided pair is generated: one item is nil in this case. Beside the items, a status is kept which gives more details about success or failure of the match operation.

Item pairing happens on different levels, reflecting the hierarchy of the netlists. On the top level there are circuits. Inside circuits nets, devices, subcircuits and pins are paired. Nets further contribute their connected items through terminals (for devices), pins (outgoing) and subcircuit pins.

This class has been introduced in version 0.26.

Public methods

[const]NetlistCrossReference ptr_const_castReturns a non-const reference to self.
void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
[const]unsigned longcircuit_countGets the number of circuit pairs in the cross-reference object.
[iter]NetlistCrossReference::CircuitPairDataeach_circuit_pairDelivers the circuit pairs and their status.
[iter]NetlistCrossReference::DevicePairDataeach_device_pair(const NetlistCrossReference::CircuitPairData circuit_pair)Delivers the device pairs and their status for the given circuit pair.
[iter]NetlistCrossReference::NetPairDataeach_net_pair(const NetlistCrossReference::CircuitPairData circuit_pair)Delivers the net pairs and their status for the given circuit pair.
[iter]NetlistCrossReference::NetPinRefPaireach_net_pin_pair(const NetlistCrossReference::NetPairData net_pair)Delivers the pin pairs for the given net pair.
[iter]NetlistCrossReference::NetSubcircuitPinRefPaireach_net_subcircuit_pin_pair(const NetlistCrossReference::NetPairData net_pair)Delivers the subcircuit pin pairs for the given net pair.
[iter]NetlistCrossReference::NetTerminalRefPaireach_net_terminal_pair(const NetlistCrossReference::NetPairData net_pair)Delivers the device terminal pairs for the given net pair.
[iter]NetlistCrossReference::PinPairDataeach_pin_pair(const NetlistCrossReference::CircuitPairData circuit_pair)Delivers the pin pairs and their status for the given circuit pair.
[iter]NetlistCrossReference::SubCircuitPairDataeach_subcircuit_pair(const NetlistCrossReference::CircuitPairData circuit_pair)Delivers the subcircuit pairs and their status for the given circuit pair.
[const]const Netlist ptrnetlist_aGets the first netlist which participated in the compare.
[const]const Netlist ptrnetlist_bGets the second netlist which participated in the compare.
[const]const Circuit ptrother_circuit_for(const Circuit ptr circuit)Gets the matching other circuit for a given primary circuit.
[const]const Device ptrother_device_for(const Device ptr device)Gets the matching other device for a given primary device.
[const]const Net ptrother_net_for(const Net ptr net)Gets the matching other net for a given primary net.
[const]const Pin ptrother_pin_for(const Pin ptr pin)Gets the matching other pin for a given primary pin.
[const]const SubCircuit ptrother_subcircuit_for(const SubCircuit ptr subcircuit)Gets the matching other subcircuit for a given primary subcircuit.

Public static methods and constants

[static,const]NetlistCrossReference::StatusMatchEnum constant NetlistCrossReference::Match
[static,const]NetlistCrossReference::StatusMatchWithWarningEnum constant NetlistCrossReference::MatchWithWarning
[static,const]NetlistCrossReference::StatusMismatchEnum constant NetlistCrossReference::Mismatch
[static,const]NetlistCrossReference::StatusNoMatchEnum constant NetlistCrossReference::NoMatch
[static,const]NetlistCrossReference::StatusNoneEnum constant NetlistCrossReference::None
[static,const]NetlistCrossReference::StatusSkippedEnum constant NetlistCrossReference::Skipped

Detailed description

Match

Signature: [static,const] NetlistCrossReference::Status Match

Description: Enum constant NetlistCrossReference::Match

An exact match exists if this code is present.

Python specific notes:
The object exposes a readable attribute 'Match'. This is the getter.

MatchWithWarning

Signature: [static,const] NetlistCrossReference::Status MatchWithWarning

Description: Enum constant NetlistCrossReference::MatchWithWarning

If this code is present, a match was found but a warning is issued. For nets, this means that the choice is ambiguous and one, unspecific candidate has been chosen. For devices, this means a device match was established, but parameters or the device class are not matching exactly.

Python specific notes:
The object exposes a readable attribute 'MatchWithWarning'. This is the getter.

Mismatch

Signature: [static,const] NetlistCrossReference::Status Mismatch

Description: Enum constant NetlistCrossReference::Mismatch

This code means there is a match candidate, but exact identity could not be confirmed.

Python specific notes:
The object exposes a readable attribute 'Mismatch'. This is the getter.

NoMatch

Signature: [static,const] NetlistCrossReference::Status NoMatch

Description: Enum constant NetlistCrossReference::NoMatch

If this code is present, no match could be found. There is also 'Mismatch' which means there is a candidate, but exact identity could not be confirmed.

Python specific notes:
The object exposes a readable attribute 'NoMatch'. This is the getter.

None

Signature: [static,const] NetlistCrossReference::Status None

Description: Enum constant NetlistCrossReference::None

No specific status is implied if this code is present.

Python specific notes:
This member is available as 'None_' in Python.
The object exposes a readable attribute 'None_'. This is the getter.

Skipped

Signature: [static,const] NetlistCrossReference::Status Skipped

Description: Enum constant NetlistCrossReference::Skipped

On circuits this code means that a match has not been attempted because subcircuits of this circuits were not matched. As circuit matching happens bottom-up, all subcircuits must match at least with respect to their pins to allow any parent circuit to be matched.

Python specific notes:
The object exposes a readable attribute 'Skipped'. This is the getter.

_const_cast

Signature: [const] NetlistCrossReference ptr _const_cast

Description: Returns a non-const reference to self.

Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects.

This method has been introduced in version 0.29.6.

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

circuit_count

Signature: [const] unsigned long circuit_count

Description: Gets the number of circuit pairs in the cross-reference object.

each_circuit_pair

Signature: [iter] NetlistCrossReference::CircuitPairData each_circuit_pair

Description: Delivers the circuit pairs and their status.

See the class description for details.

each_device_pair

Signature: [iter] NetlistCrossReference::DevicePairData each_device_pair (const NetlistCrossReference::CircuitPairData circuit_pair)

Description: Delivers the device pairs and their status for the given circuit pair.

See the class description for details.

each_net_pair

Signature: [iter] NetlistCrossReference::NetPairData each_net_pair (const NetlistCrossReference::CircuitPairData circuit_pair)

Description: Delivers the net pairs and their status for the given circuit pair.

See the class description for details.

each_net_pin_pair

Signature: [iter] NetlistCrossReference::NetPinRefPair each_net_pin_pair (const NetlistCrossReference::NetPairData net_pair)

Description: Delivers the pin pairs for the given net pair.

For the net pair, lists the pin pairs identified on this net.

each_net_subcircuit_pin_pair

Signature: [iter] NetlistCrossReference::NetSubcircuitPinRefPair each_net_subcircuit_pin_pair (const NetlistCrossReference::NetPairData net_pair)

Description: Delivers the subcircuit pin pairs for the given net pair.

For the net pair, lists the subcircuit pin pairs identified on this net.

each_net_terminal_pair

Signature: [iter] NetlistCrossReference::NetTerminalRefPair each_net_terminal_pair (const NetlistCrossReference::NetPairData net_pair)

Description: Delivers the device terminal pairs for the given net pair.

For the net pair, lists the device terminal pairs identified on this net.

each_pin_pair

Signature: [iter] NetlistCrossReference::PinPairData each_pin_pair (const NetlistCrossReference::CircuitPairData circuit_pair)

Description: Delivers the pin pairs and their status for the given circuit pair.

See the class description for details.

each_subcircuit_pair

Signature: [iter] NetlistCrossReference::SubCircuitPairData each_subcircuit_pair (const NetlistCrossReference::CircuitPairData circuit_pair)

Description: Delivers the subcircuit pairs and their status for the given circuit pair.

See the class description for details.

netlist_a

Signature: [const] const Netlist ptr netlist_a

Description: Gets the first netlist which participated in the compare.

This member may be nil, if the respective netlist is no longer valid. In this case, the netlist cross-reference object cannot be used.

netlist_b

Signature: [const] const Netlist ptr netlist_b

Description: Gets the second netlist which participated in the compare.

This member may be nil, if the respective netlist is no longer valid.In this case, the netlist cross-reference object cannot be used.

other_circuit_for

Signature: [const] const Circuit ptr other_circuit_for (const Circuit ptr circuit)

Description: Gets the matching other circuit for a given primary circuit.

The return value will be nil if no match is found. Otherwise it is the 'b' circuit for circuits from the 'a' netlist and vice versa.

This method has been introduced in version 0.27.

other_device_for

Signature: [const] const Device ptr other_device_for (const Device ptr device)

Description: Gets the matching other device for a given primary device.

The return value will be nil if no match is found. Otherwise it is the 'b' device for devices from the 'a' netlist and vice versa.

This method has been introduced in version 0.27.

other_net_for

Signature: [const] const Net ptr other_net_for (const Net ptr net)

Description: Gets the matching other net for a given primary net.

The return value will be nil if no match is found. Otherwise it is the 'b' net for nets from the 'a' netlist and vice versa.

other_pin_for

Signature: [const] const Pin ptr other_pin_for (const Pin ptr pin)

Description: Gets the matching other pin for a given primary pin.

The return value will be nil if no match is found. Otherwise it is the 'b' pin for pins from the 'a' netlist and vice versa.

This method has been introduced in version 0.27.

other_subcircuit_for

Signature: [const] const SubCircuit ptr other_subcircuit_for (const SubCircuit ptr subcircuit)

Description: Gets the matching other subcircuit for a given primary subcircuit.

The return value will be nil if no match is found. Otherwise it is the 'b' subcircuit for subcircuits from the 'a' netlist and vice versa.

This method has been introduced in version 0.27.