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. Starting with version 0.29.9, the recursive instance iterator will lock the layout it acts on while in iterating mode. While the iterator is active, the Layout object is maintained in 'under construction mode' (see Layout#under_construction). This is to prevent layout modifications to interfere with the iterator's operation. Specifically when coding in Ruby, pending iterators may block the Layout until the garbage collector cleans up these objects. To avoid this, call _destroy on the iterator when you no longer need it. The Layout is automatically unlocked when the iterator reaches the end.
| new RecursiveInstanceIterator ptr | new | (const Layout layout, const Cell cell) | Creates a recursive instance iterator. |
| new RecursiveInstanceIterator ptr | new | (const Layout layout, const Cell cell, const Box box, bool overlapping = false) | Creates a recursive instance iterator with a search region. |
| new RecursiveInstanceIterator ptr | new | (const Layout layout, const Cell cell, const Region region, bool overlapping) | Creates a recursive instance iterator with a search region. |
| [const] | bool | != | (const RecursiveInstanceIterator other) | Comparison of iterators - inequality |
| [const] | bool | == | (const RecursiveInstanceIterator other) | Comparison of iterators - equality |
| [const] | RecursiveInstanceIterator ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly 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 | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| [const] | bool | all_targets_enabled? | Gets a value indicating whether instances of all cells are reported | |
| void | assign | (const RecursiveInstanceIterator other) | Assigns another object to self | |
| [const] | bool | at_end? | End of iterator predicate | |
| [const] | const Cell ptr | cell | Gets the cell the current instance sits in | |
| [const] | unsigned int | cell_index | Gets the index of the cell the current instance sits in | |
| [const] | Region | complex_region | Gets the complex region that this iterator is using | |
| void | confine_region | (const Box box_region) | Confines the region that this iterator is iterating over | |
| void | confine_region | (const Region complex_region) | Confines the region that this iterator is iterating over | |
| [const] | InstElement | current_inst_element | Gets the current instance | |
| [const] | DCplxTrans | dtrans | Gets the accumulated transformation of the current instance parent cell to the top cell | |
| [const] | new RecursiveInstanceIterator ptr | dup | Creates a copy of self | |
| [iter] | RecursiveInstanceIterator | each | Native iteration | |
| void | enable_all_targets | Enables 'all targets' mode in which instances of all cells are reported | ||
| [const] | Cell ptr | inst_cell | Gets the target cell of the current instance | |
| [const] | DCplxTrans | inst_dtrans | Gets the micron-unit transformation of the current instance | |
| [const] | ICplxTrans | inst_trans | Gets the integer-unit transformation of the current instance | |
| [const] | const Layout ptr | layout | Gets the layout this iterator is connected to | |
| [const] | int | max_depth | Gets the maximum hierarchy depth | |
| void | max_depth= | (int depth) | Specifies the maximum hierarchy depth to look into | |
| [const] | int | min_depth | Gets the minimum hierarchy depth | |
| void | min_depth= | (int depth) | Specifies the minimum hierarchy depth to look into | |
| void | next | Increments the iterator | ||
| void | overlapping= | (bool region) | Sets a flag indicating whether overlapping instances are selected when a region is used | |
| [const] | bool | overlapping? | Gets a flag indicating whether overlapping instances are selected when a region is used | |
| [const] | InstElement[] | path | Gets the instantiation path of the instance addressed currently | |
| [const] | Box | region | Gets the basic region that this iterator is using | |
| void | region= | (const Box box_region) | Sets the rectangular region that this iterator is iterating over | |
| void | region= | (const Region complex_region) | Sets the complex region that this iterator is using | |
| void | reset | Resets the iterator to the initial state | ||
| void | reset_selection | Resets the selection to the default state | ||
| void | select_all_cells | Selects all cells. | ||
| void | select_cells | (unsigned int[] cells) | Unselects the given cells. | |
| void | select_cells | (string cells) | Unselects the given cells. | |
| [const] | unsigned int[] | targets | Gets the list of target cells | |
| void | targets= | (unsigned int[] cells) | Specifies the target cells. | |
| void | targets= | (string cells) | Specifies the target cells. | |
| [const] | const Cell ptr | top_cell | Gets the top cell this iterator is connected to | |
| [const] | ICplxTrans | trans | Gets the accumulated transformation of the current instance parent cell to the top cell | |
| void | unselect_all_cells | Unselects all cells. | ||
| void | unselect_cells | (unsigned int[] cells) | Unselects the given cells. | |
| void | unselect_cells | (string cells) | Unselects the given cells. |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead |
!= | 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: | |||||||
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: | |||||||
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: | |||||||
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: | |||||||
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: | |||||||
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: | |||||||
new | (1) Signature: [static] new RecursiveInstanceIterator ptr new (const Layout layout, const Cell cell) Description: Creates a recursive instance iterator.
This constructor creates a new recursive instance iterator which delivers the instances of the given cell plus its children. Python specific notes: | |||||||
(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.
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: | ||||||||
(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.
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: | ||||||||
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: | |||||||
overlapping? | Signature: [const] bool overlapping? Description: Gets a flag indicating whether overlapping instances are selected when a region is used Python specific notes: | |||||||
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: | |||||||
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: | |||||||
(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: | ||||||||
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: | |||||||
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: | |||||||
(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: | ||||||||
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. |