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

API reference - Class Circuit

Notation used in Ruby API documentation

Module: db

Description: Circuits are the basic building blocks of the netlist

Class hierarchy: Circuit » NetlistObject

A circuit has pins by which it can connect to the outside. Pins are created using create_pin and are represented by the Pin class.

Furthermore, a circuit manages the components of the netlist. Components are devices (class Device) and subcircuits (class SubCircuit). Devices are basic devices such as resistors or transistors. Subcircuits are other circuits to which nets from this circuit connect. Devices are created using the create_device method. Subcircuits are created using the create_subcircuit method.

Devices are connected through 'terminals', subcircuits are connected through their pins. Terminals and pins are described by integer ID's in the context of most methods.

Finally, the circuit consists of the nets. Nets connect terminals of devices and pins of subcircuits or the circuit itself. Nets are created using create_net and are represented by objects of the Net class. See there for more about nets.

The Circuit object is only valid if the netlist object is alive. Circuits must be added to a netlist using Netlist#add to become part of the netlist.

The Circuit class has been introduced in version 0.26.

Public methods

void_assign(const Circuit other)Assigns another object to self
[const]Circuit 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]new Circuit ptr_dupCreates a copy of self
[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.
voidblankBlanks out the circuit
[const]DPolygonboundaryGets the boundary of the circuit
voidboundary=(const DPolygon boundary)Sets the boundary of the circuit
[const]unsigned intcell_indexGets the cell index of the circuit
voidcell_index=(unsigned int cell_index)Sets the cell index
voidclearClears the circuit
voidcombine_devicesCombines devices where possible
voidconnect_pin(unsigned long pin_id,
Net ptr net)
Connects the given pin with the given net.
voidconnect_pin(const Pin ptr pin,
Net ptr net)
Connects the given pin with the given net.
Device ptrcreate_device(DeviceClass ptr device_class,
string name = )
Creates a new bound Device object inside the circuit
Net ptrcreate_net(string name = )Creates a new Net object inside the circuit
Pin ptrcreate_pin(string name)Creates a new Pin object inside the circuit
SubCircuit ptrcreate_subcircuit(Circuit ptr circuit,
string name = )
Creates a new bound SubCircuit object inside the circuit
Device ptrdevice_by_id(unsigned long id)Gets the device object for a given ID.
[const]const Device ptrdevice_by_id(unsigned long id)Gets the device object for a given ID (const version).
Device ptrdevice_by_name(string name)Gets the device object for a given name.
[const]const Device ptrdevice_by_name(string name)Gets the device object for a given name (const version).
voiddisconnect_pin(unsigned long pin_id)Disconnects the given pin from any net.
voiddisconnect_pin(const Pin ptr pin)Disconnects the given pin from any net.
[const]booldont_purgeGets a value indicating whether the circuit can be purged on Netlist#purge.
voiddont_purge=(bool f)Sets a value indicating whether the circuit can be purged on Netlist#purge.
[iter]Circuiteach_childIterates over the child circuits of this circuit
[const,iter]Circuiteach_childIterates over the child circuits of this circuit (const version)
[iter]Deviceeach_deviceIterates over the devices of the circuit
[const,iter]Deviceeach_deviceIterates over the devices of the circuit (const version)
[iter]Neteach_netIterates over the nets of the circuit
[const,iter]Neteach_netIterates over the nets of the circuit (const version)
[iter]Circuiteach_parentIterates over the parent circuits of this circuit
[const,iter]Circuiteach_parentIterates over the parent circuits of this circuit (const version)
[iter]Pineach_pinIterates over the pins of the circuit
[const,iter]Pineach_pinIterates over the pins of the circuit (const version)
[iter]SubCircuiteach_refIterates over the subcircuit objects referencing this circuit
[const,iter]SubCircuiteach_refIterates over the subcircuit objects referencing this circuit (const version)
[iter]SubCircuiteach_subcircuitIterates over the subcircuits of the circuit
[const,iter]SubCircuiteach_subcircuitIterates over the subcircuits of the circuit (const version)
voidflatten_subcircuit(SubCircuit ptr subcircuit)Flattens a subcircuit
[const]boolhas_refs?Returns a value indicating whether the circuit has references
voidjoin_nets(Net ptr net,
Net ptr with)
Joins (connects) two nets into one
[const]stringnameGets the name of the circuit
voidname=(string name)Sets the name of the circuit
Net ptrnet_by_cluster_id(unsigned long cluster_id)Gets the net object corresponding to a specific cluster ID
Net ptrnet_by_name(string name)Gets the net object for a given name.
[const]const Net ptrnet_by_name(string name)Gets the net object for a given name (const version).
Net ptrnet_for_pin(unsigned long pin_id)Gets the net object attached to a specific pin.
[const]const Net ptrnet_for_pin(unsigned long pin_id)Gets the net object attached to a specific pin (const version).
Net ptrnet_for_pin(const Pin ptr pin)Gets the net object attached to a specific pin.
[const]const Net ptrnet_for_pin(const Pin ptr pin)Gets the net object attached to a specific pin (const version).
Netlist ptrnetlistGets the netlist object the circuit lives in
[const]const Netlist ptrnetlistGets the netlist object the circuit lives in (const version)
Net ptr[]nets_by_name(string name_pattern)Gets the net objects for a given name filter.
[const]const Net ptr[]nets_by_name(string name_pattern)Gets the net objects for a given name filter (const version).
Pin ptrpin_by_id(unsigned long id)Gets the Pin object corresponding to a specific ID
[const]const Pin ptrpin_by_id(unsigned long id)Gets the Pin object corresponding to a specific ID (const version)
Pin ptrpin_by_name(string name)Gets the Pin object corresponding to a specific name
[const]const Pin ptrpin_by_name(string name)Gets the Pin object corresponding to a specific name (const version)
[const]unsigned longpin_countGets the number of pins in the circuit
voidpurge_devicesPurges invalid devices.
voidpurge_netsPurges floating nets.
voidpurge_nets_keep_pinsPurges floating nets but keep pins.
voidremove_device(Device ptr device)Removes the given device from the circuit
voidremove_net(Net ptr net)Removes the given net from the circuit
voidremove_pin(unsigned long id)Removes the pin with the given ID from the circuit
voidremove_subcircuit(SubCircuit ptr subcircuit)Removes the given subcircuit from the circuit
voidrename_pin(unsigned long id,
string new_name)
Renames the pin with the given ID to 'new_name'
SubCircuit ptrsubcircuit_by_id(unsigned long id)Gets the subcircuit object for a given ID.
[const]const SubCircuit ptrsubcircuit_by_id(unsigned long id)Gets the subcircuit object for a given ID (const version).
SubCircuit ptrsubcircuit_by_name(string name)Gets the subcircuit object for a given name.
[const]const SubCircuit ptrsubcircuit_by_name(string name)Gets the subcircuit object for a given name (const version).

Detailed description

_assign

Signature: void _assign (const Circuit other)

Description: Assigns another object to self

_const_cast

Signature: [const] Circuit 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.

_dup

Signature: [const] new Circuit ptr _dup

Description: Creates a copy of self

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

blank

Signature: void blank

Description: Blanks out the circuit

This method will remove all the innards of the circuit and just leave the pins. The pins won't be connected to inside nets anymore, but the circuit can still be called by subcircuit references. This method will eventually create a 'circuit abstract' (or black box). It will set the dont_purge flag to mark this circuit as 'intentionally empty'.

boundary

Signature: [const] DPolygon boundary

Description: Gets the boundary of the circuit

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

boundary=

Signature: void boundary= (const DPolygon boundary)

Description: Sets the boundary of the circuit

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

cell_index

Signature: [const] unsigned int cell_index

Description: Gets the cell index of the circuit

See cell_index= for details.

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

cell_index=

Signature: void cell_index= (unsigned int cell_index)

Description: Sets the cell index

The cell index relates a circuit with a cell from a layout. It's intended to hold a cell index number if the netlist was extracted from a layout.

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

clear

Signature: void clear

Description: Clears the circuit

This method removes all objects and clears the other attributes.

combine_devices

Signature: void combine_devices

Description: Combines devices where possible

This method will combine devices that can be combined according to their device classes 'combine_devices' method. For example, serial or parallel resistors can be combined into a single resistor.

connect_pin

(1) Signature: void connect_pin (unsigned long pin_id, Net ptr net)

Description: Connects the given pin with the given net.

The net must be one inside the circuit. Any previous connected is resolved before this connection is made. A pin can only be connected to one net at a time.

(2) Signature: void connect_pin (const Pin ptr pin, Net ptr net)

Description: Connects the given pin with the given net.

The net and the pin must be objects from inside the circuit. Any previous connected is resolved before this connection is made. A pin can only be connected to one net at a time.

create_device

Signature: Device ptr create_device (DeviceClass ptr device_class, string name = )

Description: Creates a new bound Device object inside the circuit

This object describes a device of the circuit. The device is already attached to the device class. The name is optional and is used to identify the device in a netlist file.

For more details see the Device class.

create_net

Signature: Net ptr create_net (string name = )

Description: Creates a new Net object inside the circuit

This object will describe a net of the circuit. The nets are basically connections between the different components of the circuit (subcircuits, devices and pins).

A net needs to be filled with references to connect to specific objects. See the Net class for more details.

create_pin

Signature: Pin ptr create_pin (string name)

Description: Creates a new Pin object inside the circuit

This object will describe a pin of the circuit. A circuit connects to the outside through such a pin. The pin is added after all existing pins. For more details see the Pin class.

Starting with version 0.26.8, this method returns a reference to a Pin object rather than a copy.

create_subcircuit

Signature: SubCircuit ptr create_subcircuit (Circuit ptr circuit, string name = )

Description: Creates a new bound SubCircuit object inside the circuit

This object describes an instance of another circuit inside the circuit. The subcircuit is already attached to the other circuit. The name is optional and is used to identify the subcircuit in a netlist file.

For more details see the SubCircuit class.

device_by_id

(1) Signature: Device ptr device_by_id (unsigned long id)

Description: Gets the device object for a given ID.

If the ID is not a valid device ID, nil is returned.

(2) Signature: [const] const Device ptr device_by_id (unsigned long id)

Description: Gets the device object for a given ID (const version).

If the ID is not a valid device ID, nil is returned.

This constness variant has been introduced in version 0.26.8

device_by_name

(1) Signature: Device ptr device_by_name (string name)

Description: Gets the device object for a given name.

If the ID is not a valid device name, nil is returned.

(2) Signature: [const] const Device ptr device_by_name (string name)

Description: Gets the device object for a given name (const version).

If the ID is not a valid device name, nil is returned.

This constness variant has been introduced in version 0.26.8

disconnect_pin

(1) Signature: void disconnect_pin (unsigned long pin_id)

Description: Disconnects the given pin from any net.

(2) Signature: void disconnect_pin (const Pin ptr pin)

Description: Disconnects the given pin from any net.

dont_purge

Signature: [const] bool dont_purge

Description: Gets a value indicating whether the circuit can be purged on Netlist#purge.

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

dont_purge=

Signature: void dont_purge= (bool f)

Description: Sets a value indicating whether the circuit can be purged on Netlist#purge.

If this attribute is set to true, Netlist#purge will never delete this circuit. This flag therefore marks this circuit as 'precious'.

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

each_child

(1) Signature: [iter] Circuit each_child

Description: Iterates over the child circuits of this circuit

Child circuits are the ones that are referenced from this circuit via subcircuits.

(2) Signature: [const,iter] Circuit each_child

Description: Iterates over the child circuits of this circuit (const version)

Child circuits are the ones that are referenced from this circuit via subcircuits.

This constness variant has been introduced in version 0.26.8

each_device

(1) Signature: [iter] Device each_device

Description: Iterates over the devices of the circuit

(2) Signature: [const,iter] Device each_device

Description: Iterates over the devices of the circuit (const version)

This constness variant has been introduced in version 0.26.8

each_net

(1) Signature: [iter] Net each_net

Description: Iterates over the nets of the circuit

(2) Signature: [const,iter] Net each_net

Description: Iterates over the nets of the circuit (const version)

This constness variant has been introduced in version 0.26.8

each_parent

(1) Signature: [iter] Circuit each_parent

Description: Iterates over the parent circuits of this circuit

Child circuits are the ones that are referencing this circuit via subcircuits.

(2) Signature: [const,iter] Circuit each_parent

Description: Iterates over the parent circuits of this circuit (const version)

Child circuits are the ones that are referencing this circuit via subcircuits.

This constness variant has been introduced in version 0.26.8

each_pin

(1) Signature: [iter] Pin each_pin

Description: Iterates over the pins of the circuit

(2) Signature: [const,iter] Pin each_pin

Description: Iterates over the pins of the circuit (const version)

This constness variant has been introduced in version 0.26.8

each_ref

(1) Signature: [iter] SubCircuit each_ref

Description: Iterates over the subcircuit objects referencing this circuit

(2) Signature: [const,iter] SubCircuit each_ref

Description: Iterates over the subcircuit objects referencing this circuit (const version)

This constness variant has been introduced in version 0.26.8

each_subcircuit

(1) Signature: [iter] SubCircuit each_subcircuit

Description: Iterates over the subcircuits of the circuit

(2) Signature: [const,iter] SubCircuit each_subcircuit

Description: Iterates over the subcircuits of the circuit (const version)

This constness variant has been introduced in version 0.26.8

flatten_subcircuit

Signature: void flatten_subcircuit (SubCircuit ptr subcircuit)

Description: Flattens a subcircuit

This method will substitute the given subcircuit by its contents. The subcircuit is removed after this.

has_refs?

Signature: [const] bool has_refs?

Description: Returns a value indicating whether the circuit has references

A circuit has references if there is at least one subcircuit referring to it.

join_nets

Signature: void join_nets (Net ptr net, Net ptr with)

Description: Joins (connects) two nets into one

This method will connect the 'with' net with 'net' and remove 'with'.

This method has been introduced in version 0.26.4. Starting with version 0.28.13, net names will be formed from both input names, combining them with as a comma-separated list.

name

Signature: [const] string name

Description: Gets the name of the circuit

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

name=

Signature: void name= (string name)

Description: Sets the name of the circuit

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

net_by_cluster_id

Signature: Net ptr net_by_cluster_id (unsigned long cluster_id)

Description: Gets the net object corresponding to a specific cluster ID

If the ID is not a valid pin cluster ID, nil is returned.

net_by_name

(1) Signature: Net ptr net_by_name (string name)

Description: Gets the net object for a given name.

If the ID is not a valid net name, nil is returned.

(2) Signature: [const] const Net ptr net_by_name (string name)

Description: Gets the net object for a given name (const version).

If the ID is not a valid net name, nil is returned.

This constness variant has been introduced in version 0.26.8

net_for_pin

(1) Signature: Net ptr net_for_pin (unsigned long pin_id)

Description: Gets the net object attached to a specific pin.

This is the net object inside the circuit which attaches to the given outward-bound pin. This method returns nil if the pin is not connected or the pin ID is invalid.

(2) Signature: [const] const Net ptr net_for_pin (unsigned long pin_id)

Description: Gets the net object attached to a specific pin (const version).

This is the net object inside the circuit which attaches to the given outward-bound pin. This method returns nil if the pin is not connected or the pin ID is invalid.

This constness variant has been introduced in version 0.26.8

(3) Signature: Net ptr net_for_pin (const Pin ptr pin)

Description: Gets the net object attached to a specific pin.

This is the net object inside the circuit which attaches to the given outward-bound pin. This method returns nil if the pin is not connected or the pin object is nil.

(4) Signature: [const] const Net ptr net_for_pin (const Pin ptr pin)

Description: Gets the net object attached to a specific pin (const version).

This is the net object inside the circuit which attaches to the given outward-bound pin. This method returns nil if the pin is not connected or the pin object is nil.

This constness variant has been introduced in version 0.26.8

netlist

(1) Signature: Netlist ptr netlist

Description: Gets the netlist object the circuit lives in

(2) Signature: [const] const Netlist ptr netlist

Description: Gets the netlist object the circuit lives in (const version)

This constness variant has been introduced in version 0.26.8

nets_by_name

(1) Signature: Net ptr[] nets_by_name (string name_pattern)

Description: Gets the net objects for a given name filter.

The name filter is a glob pattern. This method will return all Net objects matching the glob pattern.

This method has been introduced in version 0.27.3.

(2) Signature: [const] const Net ptr[] nets_by_name (string name_pattern)

Description: Gets the net objects for a given name filter (const version).

The name filter is a glob pattern. This method will return all Net objects matching the glob pattern.

This constness variant has been introduced in version 0.27.3

pin_by_id

(1) Signature: Pin ptr pin_by_id (unsigned long id)

Description: Gets the Pin object corresponding to a specific ID

If the ID is not a valid pin ID, nil is returned.

(2) Signature: [const] const Pin ptr pin_by_id (unsigned long id)

Description: Gets the Pin object corresponding to a specific ID (const version)

If the ID is not a valid pin ID, nil is returned.

This constness variant has been introduced in version 0.26.8

pin_by_name

(1) Signature: Pin ptr pin_by_name (string name)

Description: Gets the Pin object corresponding to a specific name

If the ID is not a valid pin name, nil is returned.

(2) Signature: [const] const Pin ptr pin_by_name (string name)

Description: Gets the Pin object corresponding to a specific name (const version)

If the ID is not a valid pin name, nil is returned.

This constness variant has been introduced in version 0.26.8

pin_count

Signature: [const] unsigned long pin_count

Description: Gets the number of pins in the circuit

purge_devices

Signature: void purge_devices

Description: Purges invalid devices.

Purges devices which are considered invalid. Such devices are for example those whose terminals are all connected to a single net.

This method has been added in version 0.29.7.

purge_nets

Signature: void purge_nets

Description: Purges floating nets.

Floating nets are nets with no device or subcircuit attached to. Such floating nets are removed in this step. If these nets are connected outward to a circuit pin, this circuit pin is also removed.

purge_nets_keep_pins

Signature: void purge_nets_keep_pins

Description: Purges floating nets but keep pins.

This method will remove floating nets like purge_nets, but if these nets are attached to a pin, the pin will be left disconnected from any net.

This method has been introduced in version 0.26.2.

remove_device

Signature: void remove_device (Device ptr device)

Description: Removes the given device from the circuit

remove_net

Signature: void remove_net (Net ptr net)

Description: Removes the given net from the circuit

remove_pin

Signature: void remove_pin (unsigned long id)

Description: Removes the pin with the given ID from the circuit

This method has been introduced in version 0.26.2.

remove_subcircuit

Signature: void remove_subcircuit (SubCircuit ptr subcircuit)

Description: Removes the given subcircuit from the circuit

rename_pin

Signature: void rename_pin (unsigned long id, string new_name)

Description: Renames the pin with the given ID to 'new_name'

This method has been introduced in version 0.26.8.

subcircuit_by_id

(1) Signature: SubCircuit ptr subcircuit_by_id (unsigned long id)

Description: Gets the subcircuit object for a given ID.

If the ID is not a valid subcircuit ID, nil is returned.

(2) Signature: [const] const SubCircuit ptr subcircuit_by_id (unsigned long id)

Description: Gets the subcircuit object for a given ID (const version).

If the ID is not a valid subcircuit ID, nil is returned.

This constness variant has been introduced in version 0.26.8

subcircuit_by_name

(1) Signature: SubCircuit ptr subcircuit_by_name (string name)

Description: Gets the subcircuit object for a given name.

If the ID is not a valid subcircuit name, nil is returned.

(2) Signature: [const] const SubCircuit ptr subcircuit_by_name (string name)

Description: Gets the subcircuit object for a given name (const version).

If the ID is not a valid subcircuit name, nil is returned.

This constness variant has been introduced in version 0.26.8