API reference - Class NetlistComparer

Notation used in Ruby API documentation

Module: db

Description: Compares two netlists

This class performs a comparison of two netlists. It can be used with an event receiver (logger) to track the errors and net mismatches. Event receivers are derived from class GenericNetlistCompareLogger. The netlist comparer can be configured in different ways. Specific hints can be given for nets, device classes or circuits to improve efficiency and reliability of the graph equivalence deduction algorithm. For example, objects can be marked as equivalent using same_nets, same_circuits etc. The compare algorithm will then use these hints to derive further equivalences. This way, ambiguities can be resolved.

Another configuration option relates to swappable pins of subcircuits. If pins are marked this way, the compare algorithm may swap them to achieve net matching. Swappable pins belong to an 'equivalence group' and can be defined with equivalent_pins.

This class has been introduced in version 0.26.

Public constructors

new NetlistComparer ptrnewCreates a new comparer object.
new NetlistComparer ptrnew(GenericNetlistCompareLogger ptr logger)Creates a new comparer object.

Public methods

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]boolcompare(const Netlist ptr netlist_a,
const Netlist ptr netlist_b)
Compares two netlists.
[const]boolcompare(const Netlist ptr netlist_a,
const Netlist ptr netlist_b,
NetlistCompareLogger ptr logger)
Compares two netlists.
[const]booldont_consider_net_namesGets a value indicating whether net names shall not be considered
voiddont_consider_net_names=(bool f)Sets a value indicating whether net names shall not be considered
voidequivalent_pins(const Circuit ptr circuit_b,
unsigned long pin_id1,
unsigned long pin_id2)
Marks two pins of the given circuit as equivalent (i.e. they can be swapped).
voidequivalent_pins(const Circuit ptr circuit_b,
unsigned long[] pin_ids)
Marks several pins of the given circuit as equivalent (i.e. they can be swapped).
voidjoin_symmetric_nets(Circuit ptr circuit)Joins symmetric nodes in the given circuit.
[const]unsigned longmax_branch_complexityGets the maximum branch complexity
voidmax_branch_complexity=(unsigned long n)Sets the maximum branch complexity
[const]unsigned longmax_depthGets the maximum search depth
voidmax_depth=(unsigned long n)Sets the maximum search depth
voidmax_resistance=(double threshold)Excludes all resistor devices with a resistance values higher than the given threshold.
voidmin_capacitance=(double threshold)Excludes all capacitor devices with a capacitance values less than the given threshold.
voidsame_circuits(const Circuit ptr circuit_a,
const Circuit ptr circuit_b)
Marks two circuits as identical.
voidsame_device_classes(const DeviceClass ptr dev_cls_a,
const DeviceClass ptr dev_cls_b)
Marks two device classes as identical.
voidsame_nets(const Net ptr net_a,
const Net ptr net_b,
bool must_match = false)
Marks two nets as identical.
voidsame_nets(const Circuit ptr circuit_a,
const Circuit ptr circuit_b,
const Net ptr net_a,
const Net ptr net_b,
bool must_match = false)
Marks two nets as identical.
[const]Circuit ptr[]unmatched_circuits_a(Netlist ptr a,
Netlist ptr b)
Returns a list of circuits in A for which there is not corresponding circuit in B
[const]Circuit ptr[]unmatched_circuits_b(Netlist ptr a,
Netlist ptr b)
Returns a list of circuits in B for which there is not corresponding circuit in A

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

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

compare

(1) Signature: [const] bool compare (const Netlist ptr netlist_a, const Netlist ptr netlist_b)

Description: Compares two netlists.

This method will perform the actual netlist compare. It will return true if both netlists are identical. If the comparer has been configured with same_nets or similar methods, the objects given there must be located inside 'circuit_a' and 'circuit_b' respectively.

(2) Signature: [const] bool compare (const Netlist ptr netlist_a, const Netlist ptr netlist_b, NetlistCompareLogger ptr logger)

Description: Compares two netlists.

This method will perform the actual netlist compare using the given logger. It will return true if both netlists are identical. If the comparer has been configured with same_nets or similar methods, the objects given there must be located inside 'circuit_a' and 'circuit_b' respectively.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

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

Use of this method is deprecated. Use _destroy instead

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

Use of this method is deprecated. Use _destroyed? instead

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.

dont_consider_net_names

Signature: [const] bool dont_consider_net_names

Description: Gets a value indicating whether net names shall not be considered

See dont_consider_net_names= for details.

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

dont_consider_net_names=

Signature: void dont_consider_net_names= (bool f)

Description: Sets a value indicating whether net names shall not be considered

If this value is set to true, net names will not be considered when resolving ambiguities. Not considering net names usually is more expensive. The default is 'false' indicating that net names will be considered for ambiguity resolution.

This property has been introduced in version 0.26.7.

Python specific notes:
The object exposes a writable attribute 'dont_consider_net_names'. This is the setter.

equivalent_pins

(1) Signature: void equivalent_pins (const Circuit ptr circuit_b, unsigned long pin_id1, unsigned long pin_id2)

Description: Marks two pins of the given circuit as equivalent (i.e. they can be swapped).

Only circuits from the second input can be given swappable pins. This will imply the same swappable pins on the equivalent circuit of the first input. To mark multiple pins as swappable, use the version that takes a list of pins.

(2) Signature: void equivalent_pins (const Circuit ptr circuit_b, unsigned long[] pin_ids)

Description: Marks several pins of the given circuit as equivalent (i.e. they can be swapped).

Only circuits from the second input can be given swappable pins. This will imply the same swappable pins on the equivalent circuit of the first input. This version is a generic variant of the two-pin version of this method.

is_const_object?

Signature: [const] bool is_const_object?

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

Use of this method is deprecated. Use _is_const_object? instead

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

join_symmetric_nets

Signature: void join_symmetric_nets (Circuit ptr circuit)

Description: Joins symmetric nodes in the given circuit.

Nodes 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 to render a schematic-equivalent netlist in some cases (split gate option).

This algorithm will apply the comparer's settings to the symmetry condition (device filtering, device compare tolerances, device class equivalence etc.).

This method has been introduced in version 0.26.4.

max_branch_complexity

Signature: [const] unsigned long max_branch_complexity

Description: Gets the maximum branch complexity

See max_branch_complexity= for details.

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

max_branch_complexity=

Signature: void max_branch_complexity= (unsigned long n)

Description: Sets the maximum branch complexity

This value limits the maximum branch complexity of the backtracking algorithm. The complexity is the accumulated number of branch options with ambiguous net matches. Backtracking will stop when the maximum number of options has been exceeded.

By default, from version 0.27 on the complexity is unlimited and can be reduced in cases where runtimes need to be limited at the cost less elaborate matching evaluation.

As the computational complexity is the square of the branch count, this value should be adjusted carefully.

Python specific notes:
The object exposes a writable attribute 'max_branch_complexity'. This is the setter.

max_depth

Signature: [const] unsigned long max_depth

Description: Gets the maximum search depth

See max_depth= for details.

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

max_depth=

Signature: void max_depth= (unsigned long n)

Description: Sets the maximum search depth

This value limits the search depth of the backtracking algorithm to the given number of jumps.

By default, from version 0.27 on the depth is unlimited and can be reduced in cases where runtimes need to be limited at the cost less elaborate matching evaluation.

Python specific notes:
The object exposes a writable attribute 'max_depth'. This is the setter.

max_resistance=

Signature: void max_resistance= (double threshold)

Description: Excludes all resistor devices with a resistance values higher than the given threshold.

To reset this constraint, set this attribute to zero.

Python specific notes:
The object exposes a writable attribute 'max_resistance'. This is the setter.

min_capacitance=

Signature: void min_capacitance= (double threshold)

Description: Excludes all capacitor devices with a capacitance values less than the given threshold.

To reset this constraint, set this attribute to zero.

Python specific notes:
The object exposes a writable attribute 'min_capacitance'. This is the setter.

new

(1) Signature: [static] new NetlistComparer ptr new

Description: Creates a new comparer object.

See the class description for more details.

Python specific notes:
This method is the default initializer of the object

(2) Signature: [static] new NetlistComparer ptr new (GenericNetlistCompareLogger ptr logger)

Description: Creates a new comparer object.

The logger is a delegate or event receiver which the comparer will send compare events to. See the class description for more details.

Python specific notes:
This method is the default initializer of the object

same_circuits

Signature: void same_circuits (const Circuit ptr circuit_a, const Circuit ptr circuit_b)

Description: Marks two circuits as identical.

This method makes a circuit circuit_a in netlist a identical to the corresponding circuit circuit_b in netlist b (see compare). By default circuits with the same name are identical.

same_device_classes

Signature: void same_device_classes (const DeviceClass ptr dev_cls_a, const DeviceClass ptr dev_cls_b)

Description: Marks two device classes as identical.

This makes a device class dev_cls_a in netlist a identical to the corresponding device class dev_cls_b in netlist b (see compare). By default device classes with the same name are identical.

same_nets

(1) Signature: void same_nets (const Net ptr net_a, const Net ptr net_b, bool must_match = false)

Description: Marks two nets as identical.

This makes a net net_a in netlist a identical to the corresponding net net_b in netlist b (see compare). Otherwise, the algorithm will try to identify nets according to their topology. This method can be used to supply hints to the compare algorithm. It will use these hints to derive further identities.

If 'must_match' is true, the nets are required to match. If they don't, an error is reported.

The 'must_match' optional argument has been added in version 0.27.3.

(2) Signature: void same_nets (const Circuit ptr circuit_a, const Circuit ptr circuit_b, const Net ptr net_a, const Net ptr net_b, bool must_match = false)

Description: Marks two nets as identical.

This makes a net net_a in netlist a identical to the corresponding net net_b in netlist b (see compare). Otherwise, the algorithm will try to identify nets according to their topology. This method can be used to supply hints to the compare algorithm. It will use these hints to derive further identities.

If 'must_match' is true, the nets are required to match. If they don't, an error is reported.

This variant allows specifying nil for the nets indicating the nets are mismatched by definition. with 'must_match' this will render a net mismatch error.

This variant has been added in version 0.27.3.

unmatched_circuits_a

Signature: [const] Circuit ptr[] unmatched_circuits_a (Netlist ptr a, Netlist ptr b)

Description: Returns a list of circuits in A for which there is not corresponding circuit in B

This list can be used to flatten these circuits so they do not participate in the compare process.

unmatched_circuits_b

Signature: [const] Circuit ptr[] unmatched_circuits_b (Netlist ptr a, Netlist ptr b)

Description: Returns a list of circuits in B for which there is not corresponding circuit in A

This list can be used to flatten these circuits so they do not participate in the compare process.