KLayout 0.29.8 (2024-10-28 63dd591e5) [master]

API reference - Class RecursiveInstanceIterator

Notation used in Ruby API documentation

Module: db

Description: An iterator delivering instances recursively

The iterator can be obtained from a cell and optionally a region. It simplifies retrieval of instances while considering subcells as well. Some options can be specified in addition, i.e. the hierarchy level to which to look into. The search can be confined to instances of certain cells (see targets=) or to certain regions. Subtrees can be selected for traversal or excluded from it (see select_cells).

This is some sample code:

# prints the effective instances of cell "A" as seen from the initial cell "cell"
iter = cell.begin_instances_rec
iter.targets = "A"
while !iter.at_end?
  puts "Instance of #{iter.inst_cell.name} in #{cell.name}: " + (iter.dtrans * iter.inst_dtrans).to_s
  iter.next
end

# or shorter:
cell.begin_instances_rec.each do |iter|
  puts "Instance of #{iter.inst_cell.name} in #{cell.name}: " + (iter.dtrans * iter.inst_dtrans).to_s
end

Here, a target cell is specified which confines the search to instances of this particular cell. 'iter.dtrans' gives us the accumulated transformation of all parents up to the top cell. 'iter.inst_dtrans' gives us the transformation from the current instance. 'iter.inst_cell' finally gives us the target cell of the current instance (which is always 'A' in our case).

Cell offers three methods to get these iterators: begin_instances_rec, begin_instances_rec_touching and begin_instances_rec_overlapping. Cell#begin_instances_rec will deliver a standard recursive instance iterator which starts from the given cell and iterates over all child cells. Cell#begin_instances_rec_touching creates a RecursiveInstanceIterator which delivers the instances whose bounding boxed touch the given search box. Cell#begin_instances_rec_overlapping gives an iterator which delivers all instances whose bounding box overlaps the search box.

A RecursiveInstanceIterator object can also be created directly, like this:

iter = RBA::RecursiveInstanceIterator::new(layout, cell [, options ])

"layout" is the layout object, "cell" the Cell object of the initial cell.

The recursive instance iterator can be confined to a maximum hierarchy depth. By using max_depth=, the iterator will restrict the search depth to the given depth in the cell tree. In the same way, the iterator can be configured to start from a certain hierarchy depth using min_depth=. The hierarchy depth always applies to the parent of the instances iterated.

In addition, the recursive instance iterator supports selection and exclusion of subtrees. For that purpose it keeps flags per cell telling it for which cells to turn instance delivery on and off. The select_cells method sets the "start delivery" flag while unselect_cells sets the "stop delivery" flag. In effect, using unselect_cells will exclude that cell plus the subtree from delivery. Parts of that subtree can be turned on again using select_cells. For the cells selected that way, the instances of these cells and their child cells are delivered, even if their parent was unselected.

To get instances from a specific cell, i.e. "MACRO" plus its child cells, unselect the top cell first and the select the desired cell again:

# deliver all instances inside "MACRO" and the sub-hierarchy:
iter = RBA::RecursiveInstanceIterator::new(layout, cell)
iter.unselect_cells(cell.cell_index)
iter.select_cells("MACRO")
...

The unselect_all_cells and select_all_cells methods turn on the "stop" and "start" flag for all cells respectively. If you use unselect_all_cells and use select_cells for a specific cell, the iterator will deliver only the instances of the selected cell, not its children. Those are still unselected by unselect_all_cells:

# deliver all instance inside "MACRO" but not of child cells:
iter = RBA::RecursiveInstanceIterator::new(layout, cell)
iter.unselect_all_cells
iter.select_cells("MACRO")
...

Cell selection is done using cell indexes or glob pattern. Glob pattern are equivalent to the usual file name wildcards used on various command line shells. For example "A*" matches all cells starting with an "A". The curly brace notation and character classes are supported as well. For example "C{125,512}" matches "C125" and "C512" and "[ABC]*" matches all cells starting with an "A", a "B" or "C". "[^ABC]*" matches all cells not starting with one of that letters.

To confine instance iteration to instances of certain cells, use the targets feature:

# deliver all instance of "INV1":
iter = RBA::RecursiveInstanceIterator::new(layout, cell)
iter.targets = "INV1"
...

Targets can be specified either as lists of cell indexes or through a glob pattern.

Instances are always delivered depth-first with child instances before their parents. A default recursive instance iterator will first deliver leaf cells, followed by the parent of these cells.

When a search region is used, instances whose bounding box touch or overlap (depending on 'overlapping' flag) will be reported. The instance bounding box taken as reference is computed using all layers of the layout.

The iterator will deliver the individual elements of instance arrays, confined to the search region if one is given. Consequently the return value (current_inst_element) is an InstElement object which is basically a combination of an Instance object and information about the current array element. inst_cell, inst_trans and inst_dtrans are methods provided for convenience to access the current array member's transformation and the target cell of the current instance.

The RecursiveInstanceIterator class has been introduced in version 0.27.

Public constructors

new RecursiveInstanceIterator ptrnew(const Layout layout,
const Cell cell)
Creates a recursive instance iterator.
new RecursiveInstanceIterator ptrnew(const Layout layout,
const Cell cell,
const Box box,
bool overlapping = false)
Creates a recursive instance iterator with a search region.
new RecursiveInstanceIterator ptrnew(const Layout layout,
const Cell cell,
const Region region,
bool overlapping)
Creates a recursive instance iterator with a search region.

Public methods

[const]bool!=(const RecursiveInstanceIterator other)Comparison of iterators - inequality
[const]bool==(const RecursiveInstanceIterator other)Comparison of iterators - equality
[const]RecursiveInstanceIterator 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]boolall_targets_enabled?Gets a value indicating whether instances of all cells are reported
voidassign(const RecursiveInstanceIterator other)Assigns another object to self
[const]boolat_end?End of iterator predicate
[const]const Cell ptrcellGets the cell the current instance sits in
[const]unsigned intcell_indexGets the index of the cell the current instance sits in
[const]Regioncomplex_regionGets the complex region that this iterator is using
voidconfine_region(const Box box_region)Confines the region that this iterator is iterating over
voidconfine_region(const Region complex_region)Confines the region that this iterator is iterating over
[const]InstElementcurrent_inst_elementGets the current instance
[const]DCplxTransdtransGets the accumulated transformation of the current instance parent cell to the top cell
[const]new RecursiveInstanceIterator ptrdupCreates a copy of self
[iter]RecursiveInstanceIteratoreachNative iteration
voidenable_all_targetsEnables 'all targets' mode in which instances of all cells are reported
[const]Cell ptrinst_cellGets the target cell of the current instance
[const]DCplxTransinst_dtransGets the micron-unit transformation of the current instance
[const]ICplxTransinst_transGets the integer-unit transformation of the current instance
[const]const Layout ptrlayoutGets the layout this iterator is connected to
[const]intmax_depthGets the maximum hierarchy depth
voidmax_depth=(int depth)Specifies the maximum hierarchy depth to look into
[const]intmin_depthGets the minimum hierarchy depth
voidmin_depth=(int depth)Specifies the minimum hierarchy depth to look into
voidnextIncrements the iterator
voidoverlapping=(bool region)Sets a flag indicating whether overlapping instances are selected when a region is used
[const]booloverlapping?Gets a flag indicating whether overlapping instances are selected when a region is used
[const]InstElement[]pathGets the instantiation path of the instance addressed currently
[const]BoxregionGets the basic region that this iterator is using
voidregion=(const Box box_region)Sets the rectangular region that this iterator is iterating over
voidregion=(const Region complex_region)Sets the complex region that this iterator is using
voidresetResets the iterator to the initial state
voidreset_selectionResets the selection to the default state
voidselect_all_cellsSelects all cells.
voidselect_cells(unsigned int[] cells)Unselects the given cells.
voidselect_cells(string cells)Unselects the given cells.
[const]unsigned int[]targetsGets the list of target cells
voidtargets=(unsigned int[] cells)Specifies the target cells.
voidtargets=(string cells)Specifies the target cells.
[const]const Cell ptrtop_cellGets the top cell this iterator is connected to
[const]ICplxTranstransGets the accumulated transformation of the current instance parent cell to the top cell
voidunselect_all_cellsUnselects all cells.
voidunselect_cells(unsigned int[] cells)Unselects the given cells.
voidunselect_cells(string cells)Unselects the given cells.

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

!=

Signature: [const] bool != (const RecursiveInstanceIterator other)

Description: Comparison of iterators - inequality

Two iterators are not equal if they do not point to the same instance.

==

Signature: [const] bool == (const RecursiveInstanceIterator other)

Description: Comparison of iterators - equality

Two iterators are equal if they point to the same instance.

_const_cast

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

all_targets_enabled?

Signature: [const] bool all_targets_enabled?

Description: Gets a value indicating whether instances of all cells are reported

See targets= for a description of the target cell concept.

assign

Signature: void assign (const RecursiveInstanceIterator other)

Description: Assigns another object to self

at_end?

Signature: [const] bool at_end?

Description: End of iterator predicate

Returns true, if the iterator is at the end of the sequence

cell

Signature: [const] const Cell ptr cell

Description: Gets the cell the current instance sits in

cell_index

Signature: [const] unsigned int cell_index

Description: Gets the index of the cell the current instance sits in

This is equivalent to 'cell.cell_index'.

complex_region

Signature: [const] Region complex_region

Description: Gets the complex region that this iterator is using

The complex region is the effective region (a Region object) that the iterator is selecting from the layout. This region can be a single box or a complex region.

confine_region

(1) Signature: void confine_region (const Box box_region)

Description: Confines the region that this iterator is iterating over

This method is similar to setting the region (see region=), but will confine any region (complex or simple) already set. Essentially it does a logical AND operation between the existing and given region. Hence this method can only reduce a region, not extend it.

(2) Signature: void confine_region (const Region complex_region)

Description: Confines the region that this iterator is iterating over

This method is similar to setting the region (see region=), but will confine any region (complex or simple) already set. Essentially it does a logical AND operation between the existing and given region. Hence this method can only reduce a region, not extend it.

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.

current_inst_element

Signature: [const] InstElement current_inst_element

Description: Gets the current instance

This is the instance/array element the iterator currently refers to. This is a InstElement object representing the current instance and the array element the iterator currently points at.

See inst_trans, inst_dtrans and inst_cell for convenience methods to access the details of the current element.

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.

dtrans

Signature: [const] DCplxTrans dtrans

Description: Gets the accumulated transformation of the current instance parent cell to the top cell

This transformation represents how the current instance is seen in the top cell. This version returns the micron-unit transformation.

dup

Signature: [const] new RecursiveInstanceIterator ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

each

Signature: [iter] RecursiveInstanceIterator each

Description: Native iteration

This method enables native iteration, e.g.

  iter = ... # RecursiveInstanceIterator
  iter.each do |i|
     ... i is the iterator itself
  end

This is slightly more convenient than the 'at_end' .. 'next' loop.

This feature has been introduced in version 0.28.

Python specific notes:
This method enables iteration of the object.

enable_all_targets

Signature: void enable_all_targets

Description: Enables 'all targets' mode in which instances of all cells are reported

See targets= for a description of the target cell concept.

inst_cell

Signature: [const] Cell ptr inst_cell

Description: Gets the target cell of the current instance

This is the cell the current instance refers to. It is one of the targets if a target list is given.

inst_dtrans

Signature: [const] DCplxTrans inst_dtrans

Description: Gets the micron-unit transformation of the current instance

This is the transformation of the current instance inside its parent. 'dtrans * inst_dtrans' gives the full micron-unit transformation how the current cell is seen in the top cell. See also inst_trans and inst_cell.

inst_trans

Signature: [const] ICplxTrans inst_trans

Description: Gets the integer-unit transformation of the current instance

This is the transformation of the current instance inside its parent. 'trans * inst_trans' gives the full transformation how the current cell is seen in the top cell. See also inst_dtrans and inst_cell.

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.

layout

Signature: [const] const Layout ptr layout

Description: Gets the layout this iterator is connected to

max_depth

Signature: [const] int max_depth

Description: Gets the maximum hierarchy depth

See max_depth= for a description of that attribute.

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

max_depth=

Signature: void max_depth= (int depth)

Description: Specifies the maximum hierarchy depth to look into

A depth of 0 instructs the iterator to deliver only instances from the initial cell. A higher depth instructs the iterator to look deeper. The depth must be specified before the instances are being retrieved.

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

min_depth

Signature: [const] int min_depth

Description: Gets the minimum hierarchy depth

See min_depth= for a description of that attribute.

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

min_depth=

Signature: void min_depth= (int depth)

Description: Specifies the minimum hierarchy depth to look into

A depth of 0 instructs the iterator to deliver instances from the top level. 1 instructs to deliver instances from the first child level. The minimum depth must be specified before the instances are being retrieved.

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

new

(1) Signature: [static] new RecursiveInstanceIterator ptr new (const Layout layout, const Cell cell)

Description: Creates a recursive instance iterator.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including its children)
layer:The layer (index) from which the shapes are taken

This constructor creates a new recursive instance iterator which delivers the instances of the given cell plus its children.

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

(2) Signature: [static] new RecursiveInstanceIterator ptr new (const Layout layout, const Cell cell, const Box box, bool overlapping = false)

Description: Creates a recursive instance iterator with a search region.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including its children)
box:The search region
overlapping:If set to true, instances overlapping the search region are reported, otherwise touching is sufficient

This constructor creates a new recursive instance iterator which delivers the instances of the given cell plus its children.

The search is confined to the region given by the "box" parameter. If "overlapping" is true, instances whose bounding box is overlapping the search region are reported. If "overlapping" is false, instances whose bounding box touches the search region are reported. The bounding box of instances is measured taking all layers of the target cell into account.

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

(3) Signature: [static] new RecursiveInstanceIterator ptr new (const Layout layout, const Cell cell, const Region region, bool overlapping)

Description: Creates a recursive instance iterator with a search region.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including its children)
region:The search region
overlapping:If set to true, instances overlapping the search region are reported, otherwise touching is sufficient

This constructor creates a new recursive instance iterator which delivers the instances of the given cell plus its children.

The search is confined to the region given by the "region" parameter. The region needs to be a rectilinear region. If "overlapping" is true, instances whose bounding box is overlapping the search region are reported. If "overlapping" is false, instances whose bounding box touches the search region are reported. The bounding box of instances is measured taking all layers of the target cell into account.

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

next

Signature: void next

Description: Increments the iterator

This moves the iterator to the next instance inside the search scope.

overlapping=

Signature: void overlapping= (bool region)

Description: Sets a flag indicating whether overlapping instances are selected when a region is used

If this flag is false, instances touching the search region are returned.

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

overlapping?

Signature: [const] bool overlapping?

Description: Gets a flag indicating whether overlapping instances are selected when a region is used

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

path

Signature: [const] InstElement[] path

Description: Gets the instantiation path of the instance addressed currently

This attribute is a sequence of InstElement objects describing the cell instance path from the initial cell to the current instance. The path is empty if the current instance is in the top cell.

region

Signature: [const] Box region

Description: Gets the basic region that this iterator is using

The basic region is the overall box the region iterator iterates over. There may be an additional complex region that confines the region iterator. See complex_region for this attribute.

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

region=

(1) Signature: void region= (const Box box_region)

Description: Sets the rectangular region that this iterator is iterating over

See region for a description of this attribute. Setting a simple region will reset the complex region to a rectangle and reset the iterator to the beginning of the sequence.

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

(2) Signature: void region= (const Region complex_region)

Description: Sets the complex region that this iterator is using

See complex_region for a description of this attribute. Setting the complex region will reset the basic region (see region) to the bounding box of the complex region and reset the iterator to the beginning of the sequence.

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

reset

Signature: void reset

Description: Resets the iterator to the initial state

reset_selection

Signature: void reset_selection

Description: Resets the selection to the default state

In the initial state, the top cell and its children are selected. Child cells can be switched on and off together with their sub-hierarchy using select_cells and unselect_cells.

This method will also reset the iterator.

select_all_cells

Signature: void select_all_cells

Description: Selects all cells.

This method will set the "selected" mark on all cells. The effect is that subsequent calls of unselect_cells will unselect only the specified cells, not their children, because they are still unselected.

This method will also reset the iterator.

select_cells

(1) Signature: void select_cells (unsigned int[] cells)

Description: Unselects the given cells.

This method will sets the "selected" mark on the given cells. That means that these cells or their child cells are visited, unless they are marked as "unselected" again with the unselect_cells method.

The cells are given as a list of cell indexes.

This method will also reset the iterator.

(2) Signature: void select_cells (string cells)

Description: Unselects the given cells.

This method will sets the "selected" mark on the given cells. That means that these cells or their child cells are visited, unless they are marked as "unselected" again with the unselect_cells method.

The cells are given as a glob pattern. A glob pattern follows the syntax of file names on the shell (i.e. "A*" are all cells starting with a letter "A").

This method will also reset the iterator.

targets

Signature: [const] unsigned int[] targets

Description: Gets the list of target cells

See targets= for a description of the target cell concept. This method returns a list of cell indexes of the selected target cells.

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

targets=

(1) Signature: void targets= (unsigned int[] cells)

Description: Specifies the target cells.

If target cells are specified, only instances of these cells are delivered. This version takes a list of cell indexes for the targets. By default, no target cell list is present and the instances of all cells are delivered by the iterator. See all_targets_enabled? and enable_all_targets for a description of this mode. Once a target list is specified, the iteration is confined to the cells from this list. The cells are given as a list of cell indexes.

This method will also reset the iterator.

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

(2) Signature: void targets= (string cells)

Description: Specifies the target cells.

If target cells are specified, only instances of these cells are delivered. This version takes a cell list as a glob pattern. A glob pattern follows the syntax of file names on the shell (i.e. "A*" are all cells starting with a letter "A"). Use the curly-bracket notation to list different cells, e.g "{A,B,C}" for cells A, B and C.

By default, no target cell list is present and the instances of all cells are delivered by the iterator. See all_targets_enabled? and enable_all_targets for a description of this mode. Once a target list is specified, the iteration is confined to the cells from this list. The cells are given as a list of cell indexes.

This method will also reset the iterator.

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

top_cell

Signature: [const] const Cell ptr top_cell

Description: Gets the top cell this iterator is connected to

trans

Signature: [const] ICplxTrans trans

Description: Gets the accumulated transformation of the current instance parent cell to the top cell

This transformation represents how the current instance is seen in the top cell.

unselect_all_cells

Signature: void unselect_all_cells

Description: Unselects all cells.

This method will set the "unselected" mark on all cells. The effect is that subsequent calls of select_cells will select only the specified cells, not their children, because they are still unselected.

This method will also reset the iterator.

unselect_cells

(1) Signature: void unselect_cells (unsigned int[] cells)

Description: Unselects the given cells.

This method will sets the "unselected" mark on the given cells. That means that these cells or their child cells will not be visited, unless they are marked as "selected" again with the select_cells method.

The cells are given as a list of cell indexes.

This method will also reset the iterator.

(2) Signature: void unselect_cells (string cells)

Description: Unselects the given cells.

This method will sets the "unselected" mark on the given cells. That means that these cells or their child cells will not be visited, unless they are marked as "selected" again with the select_cells method.

The cells are given as a glob pattern. A glob pattern follows the syntax of file names on the shell (i.e. "A*" are all cells starting with a letter "A").

This method will also reset the iterator.